Security - GBG Documentation

This guide covers the security model of the GBGBridge Web SDK, including transport safety, content policies, origin allowlist hardening, token-exchange responsibilities, and production-deployment best practices.

Security model overview

GBGBridge runs entirely in the browser. The bridge is a structured-message layer on top of the browser’s native postMessage channel — it does not bypass any browser security mechanism. Three guarantees underpin the security model:

Cross-origin isolation — The host page and the journey iframe are separate origins. Same-origin policy prevents either from reading the other’s DOM, cookies, or storage. The bridge is the only sanctioned channel between them.
Origin allowlist — The SDK enforces a strict allowlist on both inbound and outbound messages. Messages to or from origins not in the allowlist are silently dropped.
Envelope validation — Every inbound message is validated against the protocol envelope before reaching any handler. Malformed messages are dropped before they can be routed.

Trust boundaries

Host page code runs with full access to the host’s origin (cookies, storage, network).
Journey iframe content runs in a sandboxed cross-origin context. It cannot access the host page’s DOM, storage, or APIs — only the bridge.
The bridge is the controlled interface. Every message crosses an origin boundary and is validated by the SDK before reaching either side.
Your backend does the token exchange and returns a tokenized journey URL. Credentials never reach the browser.

Transport security

Bridge messages travel over the browser’s in-process postMessage channel — they never leave the device. Network security applies separately to the journey URL load and any backend calls.

Message channel

Direction	Mechanism
Host → Iframe	`iframe.contentWindow.postMessage(message, targetOrigin)`
Iframe → Host	`window.postMessage(message, "*")` from inside the iframe, received via the host page’s `window` `message` listener

Both directions stay inside the browser’s process. There is no IPC across processes (browser-internal), and no network call between iframe and host.

Network security (journey URL load)

The journey URL is loaded over the network. Apply standard web transport hygiene:

HTTPS in production. Browsers block mixed content — an https:// host page loading an http:// iframe will fail silently. Local development on http://localhost works in both directions because browsers treat localhost as a secure context.
HSTS on the journey origin if you control it. Forces HTTPS even on first contact.
CSP frame-src directive on the host page (covered below).

Origin allowlist

The allowedOrigins array passed to BridgeHost / BridgeHostProvider is the load-bearing security control. The SDK enforces it on three independent checks per inbound message:

event.source !== iframe.contentWindow → drop silently.
event.origin not in the normalized allowlist → drop silently.
Envelope validation fails → drop silently.

And on outbound:

targetOrigin resolved from iframe.src not in the allowlist → drop with console.warn.

This means a script on the host page that repoints iframe.src to a hostile origin cannot use the bridge to leak data or invoke host capabilities — the outbound check fails and the inbound source check fails.

Origin allowlist enforcement is defence in depth: this is the host-page half of the work shipped under GGO-13990 (US1 + US2). The iframe-side journey enforces the same allowlist against event.origin of inbound messages from the host. Both ends of the bridge validate origin independently — neither half can be skipped by a script on the other side.

Format rules

Exact origins only. No paths, no trailing slashes, no wildcards.
Match scheme. https://example.com and http://example.com are different origins.
Default ports omitted. https://example.com and https://example.com:443 are the same; the SDK normalizes both to the canonical form, but write the canonical form yourself to avoid drift.
Non-default ports required. https://example.com:8443 requires the explicit port.
Empty arrays throw. new BridgeHost({ allowedOrigins: [], ... }) raises at construction. There is no implicit “allow all” — this is by design.

// Good
allowedOrigins: ["https://journey.example.com", "https://staging.journey.example.com"]

// Bad — trailing slash, path component, wildcard
allowedOrigins: ["https://journey.example.com/", "https://journey.example.com/start", "https://*.example.com"]

Multiple environments

If your host serves both production and staging, list both explicit origins. If the journey URL might be on yet a third origin (e.g., a per-tenant subdomain), build the allowlist dynamically:

const allowedOrigins = [
  new URL(journeyUrl).origin,
  "https://fallback.journey.example.com",
];

Avoid building allowlists from user-controlled input — a malicious URL could expand the allowlist past your intended trust set.

Complete multi-environment example

For a host page that serves both production and staging, three controls work together. All three reference the same set of journey origins:

// 1. CSP frame-src on the host page response header
// Content-Security-Policy: frame-src https://journey.example.com https://staging.journey.example.com;

// 2. Origin allowlist on the SDK
const JOURNEY_ORIGINS = {
  production: "https://journey.example.com",
  staging: "https://staging.journey.example.com",
} as const;

function JourneyView({ env, journeyUrl }: { env: keyof typeof JOURNEY_ORIGINS; journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);

  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={[JOURNEY_ORIGINS[env]]}
      hostVersion="1.0.0"
      capabilities={{ "camera.document": { supported: true, version: "1.0" } }}
    >
      <DocumentCaptureHandler />
      {/* 3. Iframe allow attribute scoped to camera only */}
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

Three things to keep aligned:

CSP frame-src lists both environments — without it, the browser blocks the iframe load entirely.
allowedOrigins is per-instance, scoped to the single environment in use — narrower than CSP. Hard-coding a tighter allowlist than your CSP is intentional.
iframe allow is environment-agnostic — same permission set for production and staging.

If you switch environments at runtime, force a Provider remount (key={env}) so the allowedOrigins snapshot rebuilds with the new origin. Don’t just change the allowedOrigins prop — it’s snapshotted at attach time.

Content Security Policy (CSP)

If your host page sets a CSP header, the journey origin must appear in frame-src (or child-src as a fallback for older browsers):

Content-Security-Policy: frame-src https://journey.example.com;

For multiple environments, list each explicitly. Avoid frame-src * in production — it disables a meaningful defence-in-depth layer. If the journey itself loads sub-resources from third-party origins (analytics, fonts), those are constrained by the journey’s CSP, not yours. Coordinate with the journey team if you see CSP failures in the iframe.

Iframe permission delegation

Browser permissions (camera, microphone, geolocation, etc.) are not inherited by iframes by default. Use the iframe allow attribute to delegate the permissions your journey might need:

<iframe src="https://journey.example.com" allow="camera; microphone"></iframe>

Even when your host handles capture via the bridge, set the appropriate allow values — the journey may invoke getUserMedia for a fallback flow (e.g., if capability.query returns supported: false for camera.document). Use the least-permissive set of permissions your integration actually requires. Don’t include geolocation or microphone if the journey doesn’t use them.

No bootstrap script injection

Unlike iOS (WKUserScript) and Android (WebViewClient.onPageStarted + addJavascriptInterface), the Web SDK does not inject any script into the journey iframe. Cross-origin restrictions would prevent it anyway — the host page cannot execute JavaScript inside a cross-origin iframe. The journey iframe loads its own SDK (@gbgplc-internal/ggo-native-bridge and its React variant) as part of its bundle. The host and iframe agree on the wire protocol; neither party can modify the other’s runtime. This is a hard browser constraint, not a design choice — but it also means there’s no bootstrap configuration to manage, and no risk of accidentally exposing host secrets via injected globals.

Message validation

Two layers of validation apply to every inbound message: shape validation at the transport layer, and payload validation inside your own handlers. Both matter — one keeps malformed messages out of your handlers, the other keeps malicious payloads from acting on your handler’s assumptions.

Envelope validation

Every inbound message goes through HostIframeChannel.isValidEnvelope before reaching BridgeHost. The checks:

version is a string
correlationId is a string
type is "request", "response", or "event"
timestamp is a number
payload exists and is an object
payload.action is a non-empty string

Failures are dropped silently. Malformed envelopes never reach handlers, the delegate, or pendingRequests.

Action validation

Handlers route by exact string match on payload.action. Register handlers only for actions you expect. Unknown actions:

Go to pendingRequests (capped at 50; overflow dropped).
Fire delegate.onUnhandledRequest so you can decide whether to respond manually.

Data validation in handlers

The iframe is the less-trusted zone. Treat its payload.data the same way you would treat any external input — validate every field your handler reads.

host.registerHandler("camera.document.capture", {
  handle: async (request, responder) => {
    const data = (request.payload as { data: Record<string, unknown> }).data;
    const side = data.side;

    if (side !== "front" && side !== "back") {
      responder.error({
        code: "INVALID_REQUEST",
        message: "Missing or invalid 'side' parameter. Expected 'front' or 'back'.",
        recoverable: true,
      });
      return;
    }

    const image = await captureDocument(side);
    responder.success({ image });
  },
});

Token exchange and credential safety

The journey URL is typically a single-use, signed URL minted by your backend. Three rules:

Backend mints the URL, not the browser. Use @gbg/go-core server-side to authenticate with GBG and obtain the tokenized journey URL. The host page receives only the URL.
Credentials never reach the browser. @gbg/go-core’s OAuth flow uses a client secret. Exposing it in browser code lets anyone mint sessions against your tenant. Always run that flow server-side.
The journey URL is a short-lived token. It typically expires within minutes and is single-use. Don’t cache it in localStorage or pass it through unprotected channels.

For the full backend-to-frontend handoff pattern, see Journey URL.

Browser permission handling

GBGBridge itself does not request any browser permissions. Your capability handlers are responsible for requesting and checking permissions before performing the operation.

host.registerHandler("camera.document.capture", {
  handle: async (_request, responder) => {
    if (!navigator.permissions) {
      // Fallback: just attempt getUserMedia
      try {
        const stream = await navigator.mediaDevices.getUserMedia({ video: true });
        // ... perform capture ...
        responder.success({ image: "..." });
      } catch {
        responder.error({
          code: "PERMISSION_DENIED",
          message: "Camera access denied",
          recoverable: true,
        });
      }
      return;
    }

    const status = await navigator.permissions.query({ name: "camera" as PermissionName });
    if (status.state === "denied") {
      responder.error({
        code: "PERMISSION_DENIED",
        message: "Camera access denied. Enable it in browser settings.",
        recoverable: true,
      });
      return;
    }

    // Proceed with capture
    const image = await captureDocument();
    responder.success({ image });
  },
});

Report the current permission state in your capabilities declaration when possible — the journey uses permissionState to surface a permission prompt before triggering the request.

const capabilities = {
  "camera.document": {
    supported: true,
    version: "1.0",
    permissionState: cameraPermissionState, // "granted" | "prompt" | "denied"
  },
};

Production checklist

Before shipping your integration:

Next steps

Journey URL — Backend token exchange and journey URL construction.
Integration Checklist — Pre-flight checks before shipping.
Troubleshooting — Diagnosing security-related issues.
API Reference — Configuration and setup API.

​Security model overview

​Trust boundaries

​Transport security

​Message channel

​Network security (journey URL load)

​Origin allowlist

​Format rules

​Multiple environments

​Complete multi-environment example

​Content Security Policy (CSP)

​Iframe permission delegation

​No bootstrap script injection

​Message validation

​Envelope validation

​Action validation

​Data validation in handlers

​Token exchange and credential safety

​Browser permission handling

​Production checklist

​Next steps

Security model overview

Trust boundaries

Transport security

Message channel

Network security (journey URL load)

Origin allowlist

Format rules

Multiple environments

Complete multi-environment example

Content Security Policy (CSP)

Iframe permission delegation

No bootstrap script injection

Message validation

Envelope validation

Action validation

Data validation in handlers

Token exchange and credential safety

Browser permission handling

Production checklist

Next steps