> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Transport security, iframe origin validation, and PII handling for the TypeScript Bridge SDK

This page covers the security model for the TypeScript Bridge SDK across each embedding environment. The threat model differs sharply between native WebViews and iframes — native platforms enforce origin scoping at the OS level, whereas iframes require explicit origin validation in the bridge config.

## Transport security by environment

| Environment           | Security model                                                                                             | Origin validation        |
| --------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------ |
| **iOS (WKWebView)**   | Messages scoped to loaded web content. OS enforces that only the WebView's content can send messages.      | Built-in by the platform |
| **Android (WebView)** | Messages scoped via `@JavascriptInterface`. Only JavaScript inside the WebView can call interface methods. | Built-in by the platform |
| **iframe**            | Uses `postMessage` which supports cross-origin communication. **Origin validation is required.**           | Must be configured       |
| **Standalone**        | No communication occurs. Messages are silently dropped.                                                    | N/A                      |

## iframe origin validation

When running in an iframe, the bridge validates message origins in both directions.

### Incoming messages (host to web)

Configure `iframeAllowedOrigins` to restrict which parent origins can send messages:

```typescript theme={null}
const bridge = NativeBridge.getInstance({
  iframeAllowedOrigins: ['https://app.example.com'],
});
```

If `iframeAllowedOrigins` is empty (default), messages from **any** origin are accepted.

<Warning>
  In production, always specify allowed origins for iframe embeddings.
</Warning>

### Outgoing messages (web to host)

Configure `iframeTargetOrigin` to restrict where messages are sent:

```typescript theme={null}
const bridge = NativeBridge.getInstance({
  iframeTargetOrigin: 'https://app.example.com',
});
```

Defaults to `window.location.origin`. This prevents messages from being intercepted by a malicious parent frame on a different origin.

### Recommended iframe configuration

Combine the two settings: list every parent origin you accept messages from in `iframeAllowedOrigins`, and pin `iframeTargetOrigin` to the single origin you send messages to. In practice this means including staging in `iframeAllowedOrigins` (so you can dev/test against it) while still scoping the target origin to production:

```typescript theme={null}
const bridge = NativeBridge.getInstance({
  iframeAllowedOrigins: ['https://app.example.com', 'https://staging.example.com'],
  iframeTargetOrigin: 'https://app.example.com',
});
```

`iframeAllowedOrigins` controls who can talk *to* the bridge; `iframeTargetOrigin` controls who the bridge talks back *to*. Both must be set in production iframe deployments.

## PII and sensitive data

### What the bridge transmits

The bridge is a transport layer — it sends whatever data you put in the `data` field of requests and events.

| Data type               | Typical flow             | Recommendation                                     |
| ----------------------- | ------------------------ | -------------------------------------------------- |
| Captured images, base64 | Host to web in response  | Transmitted in-memory; not persisted by the bridge |
| Journey IDs             | Web to host in events    | Non-sensitive identifiers                          |
| Timestamps              | Both directions          | Non-sensitive                                      |
| Theme/locale data       | Host to web in events    | Non-sensitive                                      |
| Error messages          | Host to web in responses | Should not contain PII                             |

### Best practices

1. **Don't include PII in event payloads** — Journey events should contain IDs and metadata, not personally identifiable information.

2. **Images are transient** — Base64 image data passes through the bridge but is not stored. The message log (capped at 500 entries) may temporarily contain image data.

3. **Don't log message payloads in production** — `onMessageLog()` and `getMessageLog()` are debugging tools. Avoid logging full payloads to external services.

## Message integrity

The bridge does not sign or encrypt messages. The security model relies on:

* **Native platforms (iOS/Android):** The OS ensures only the WebView's content can communicate with the host.
* **iframe:** Origin validation ensures messages only flow between trusted origins.

## Content Security Policy

If your application uses CSP, ensure it allows the embedding via the `frame-ancestors` directive:

```http theme={null}
Content-Security-Policy: frame-ancestors 'self' https://your-host-domain.com;
```

## Token and credential handling

The bridge itself does not handle authentication tokens, API keys, or credentials. **Do not** send tokens or secrets through the bridge's event or request system. If the host needs to provide an API token to the web app, do so via the initial page URL or configuration injection — not through bridge messages.

## Version compatibility

The bridge includes a protocol version (`'1.0'`) in every message. If the web SDK and host app have different protocol versions, messages with mismatched versions are still processed (with a console warning), providing forward compatibility.