@uidu/app-bridge

The browser half of a uidu custom app. uidu frames the app (a Space tab, or a workspace app of its own) and hands it a short-lived session over postMessage; this package does the handshake and keeps the token fresh.

import { connect, DEFAULT_HOST_ORIGINS } from '@uidu/app-bridge';
import { createClient, fromBridge, ensureModel } from '@uidu/client';

const bridge = await connect({
  // default: ['https://*.uidu.org']; add dev hosts and custom domains
  hostOrigins: [...DEFAULT_HOST_ORIGINS, 'https://me.uidu.local:8443'],
});

bridge.context; // { locale, theme, accent, user, space, workspaceApp }
const client = createClient(fromBridge(bridge)); // token asked per request

bridge.on('context', (ctx) => {}); // a new session changed theme/accent/locale…
bridge.on('error', (err) => {}); // the host refused or ignored a refresh
bridge.destroy();

In React, use <UiduAppProvider> / useUiduApp() from @uidu/react.

Behaviour

• Accepts messages only from window.parent, from the origin that framed the app (location.ancestorOrigins, else document.referrer), and only if that origin is in hostOrigins. Posts to that origin only, never *.
• Refuses a session whose graphqlUrl is not on the host origin.
• getToken() returns the cached token until under refreshMargin (60s) of expiry, then sends uidu:refresh; concurrent callers share one refresh. The token is opaque — never decode it.
• connect() rejects with an AppBridgeError so the app can fall back: NOT_EMBEDDED, UNKNOWN_HOST, UNTRUSTED_HOST, TIMEOUT (5s), HOST_ERROR (the host's uidu:error message), INVALID_MESSAGE.

The wire format lives in src/protocol.ts (PROTOCOL_VERSION = 1); changing it is a two-repo change with uidu's CustomAppFrame.tsx. A server half (@uidu/app-bridge/server: token verification) waits for ES256 + JWKS on the uidu side.