@callcorpacd/platform-bridge 1.0.0

package/AUTHORING.md

@@ -0,0 +1,102 @@
+# Partner App Author DX
+
+Create → develop (mock or live portal) → build → publish → embed.
+
+## Quick start (partners — no Platform repo)
+
+See [`../create-callcorp-sandbox/PARTNER.md`](../create-callcorp-sandbox/PARTNER.md). Maintainer publish steps: [`../create-callcorp-sandbox/PUBLISH.md`](../create-callcorp-sandbox/PUBLISH.md).
+
+## Quick start (from this monorepo)
+
+```bash
+cd WebApps/VuePortal_new
+node create-callcorp-sandbox/index.js my-app -y
+cd my-app
+npm install
+```
+
+Default template is **Vue 3 + Vite**. Other stacks:
+
+```bash
+node create-callcorp-sandbox/index.js --list-templates
+node create-callcorp-sandbox/index.js my-app -y --template html-js
+node create-callcorp-sandbox/index.js my-app -y --template vue-quasar
+```
+
+See [`../create-callcorp-sandbox/templates/README.md`](../create-callcorp-sandbox/templates/README.md) for the catalog.
+
+You may run the scaffolder from any drive (e.g. `Q:\`); it creates `./my-app` under your cwd and links `@callcorpacd/platform-bridge` with an absolute `file:C:/...` path when the monorepo is on another drive.
+
+**SUBST / mapped drives:** If `Q:` is `SUBST`’d to a folder on `C:`, Vite can resolve modules to the real `C:\...` path while the server root is `Q:\...`. The template `vite.config.js` allows both via `server.fs.allow`. If you still see “Failed to load url /src/main.js”, run `npm run dev` from the **real** path (`C:\CallCorp\RootLocalFlowProjects\my-app`) instead of `Q:\my-app`.
+### Offline mock bridge
+
+```bash
+npm run dev:mock
+```
+
+### Live portal embed (real APIs)
+
+```bash
+npm run dev
+```
+
+Then paste the **dev** snippet into a portal UserControl (`SourceKind: Url` → `https://localhost:5174/`). The first `npm run dev` may prompt once to install a local trusted CA (mkcert); after that the portal iframe loads without a certificate click-through.
+
+```bash
+npx callcorp-sandbox embed-snippet --mode dev
+npx callcorp-sandbox embed-snippet --mode prod
+```
+
+### Publish to Platform Files
+
+If `~/.callcorp/sandbox.json` is missing, the CLI reuses a parent BuildCC workspace API key (`.buildcc/secrets.json`) when present — skip `login` in that case.
+
+```bash
+# npx callcorp-sandbox login   # only if no sandbox.json / BuildCC key
+npm run build
+npx callcorp-sandbox publish
+```
+
+Use the **prod** embed snippet (`SourceKind: PlatformFile`) after publish.
+
+Mass Storage:
+
+```bash
+npx callcorp-sandbox publish --target mass-storage --owner-id <customerId>
+```
+
+Scaffolded apps include a stack-specific `AGENTS.md` (bridge rules, publish, auth skip order). Agents creating a new app should read [`../create-callcorp-sandbox/AGENTS.md`](../create-callcorp-sandbox/AGENTS.md) and pick a template from [`../create-callcorp-sandbox/templates/README.md`](../create-callcorp-sandbox/templates/README.md).
+
+Partners without Platform repo access: [`../create-callcorp-sandbox/PARTNER.md`](../create-callcorp-sandbox/PARTNER.md).
+
+## Packages
+
+| Package | Path | Role |
+|---------|------|------|
+| `@callcorpacd/platform-bridge` | [`PlatformBridge/`](./) | Guest/host postMessage bridge |
+| `create-callcorp-sandbox` | [`../create-callcorp-sandbox/`](../create-callcorp-sandbox/) | `npm create` scaffolder |
+| `@callcorpacd/sandbox-cli` | [`../callcorp-sandbox-cli/`](../callcorp-sandbox-cli/) | `login` / `publish` / `embed-snippet` / `whoami` |
+| Templates | [`../create-callcorp-sandbox/templates/`](../create-callcorp-sandbox/templates/) | Guest scaffolds: `vue-vite`, `html-js`, `vue-quasar` |
+
+In the monorepo, the scaffolder wires `file:` dependencies to sibling folders when present. Outside the repo (after npm publish), scaffolded apps depend on `@callcorpacd/platform-bridge` and `@callcorpacd/sandbox-cli` from the public npm registry.
+
+## Live localhost requirements
+
+- Vite serves **HTTPS** via `vite-plugin-mkcert` so the HTTPS portal can iframe it with a locally trusted cert (one-time OS trust prompt on first `npm run dev`).
+- `Content-Security-Policy: frame-ancestors *` so the portal may embed the dev server.
+- `SandboxedApp` allowlists the iframe origin for `postMessage` automatically from `Url`.
+- If the iframe still cannot reach localhost HTTPS (locked-down trust store, etc.), `SandboxedApp` shows **Open app in new tab** / **Retry** guidance.
+
+Do not leave `Url: https://localhost:…` in production UserControls.
+
+## Passing host params into the guest
+
+Add a `Params` map on the embed `ControlData`. Values are interpolated strings evaluated by the portal (`{{ParamByName("Id")}}`, `{# Root.UserName #}`, literals). After handshake the guest reads them from `platform.context.params`; subscribe for live updates:
+
+```js
+const platform = await createPlatformBridge();
+console.log(platform.context.params);
+platform.context.subscribe((params) => console.log('updated', params));
+```
+
+See [`README.md`](./README.md#passing-params-from-a-usercontrol-document) for full embed JSON examples.

package/README.md

@@ -0,0 +1,171 @@
+# @callcorpacd/platform-bridge
+
+Guest/host **postMessage** bridge so partner content in a sandboxed iframe can call portal APIs **without** receiving access tokens.
+
+Used by the Vue3 `SandboxedApp` control. Designed to grow into a published npm package (partners + internal apps).
+
+**Authoring a guest app (create / localhost / publish):** see [`AUTHORING.md`](AUTHORING.md).
+
+## Install (local / monorepo)
+
+Vue3 already depends on this package via `file:../PlatformBridge` and Vite aliases:
+
+- `@callcorpacd/platform-bridge`
+- `@callcorpacd/platform-bridge/client`
+- `@callcorpacd/platform-bridge/host`
+- `@callcorpacd/platform-bridge/protocol`
+
+## Guest (inside the iframe)
+
+```js
+import { createPlatformBridge } from '@callcorpacd/platform-bridge/client';
+
+const platform = await createPlatformBridge();
+
+// Document Params (interpolated on the host) arrive on handshake:
+const { RecordId, Mode } = platform.context.params;
+platform.context.subscribe((params) => {
+  // Live updates when host Params re-evaluate
+});
+
+const data = await platform.api.get('Apps/User/FullName');
+await platform.api.post('Some/Path', { hello: 'world' });
+```
+
+**v1 surface:**
+
+- `platform.api.get | cachedGet | post | put | patch | delete`
+- `platform.context.params` — `Record<string, string>` from host `ControlData.Params`
+- `platform.context.subscribe(listener)` — notified on `bridge.context.update`
+
+**Reserved (not implemented on the host yet):** `platform.navigate`, `platform.ui`, `platform.events`.
+
+### Security
+
+- Do **not** call the band API with `fetch` and a token from guest code; use the bridge.
+- The host allowlists paths via `ControlData.AllowedApiPrefixes` on `SandboxedApp`.
+- Absolute `http(s)` URLs are rejected by default.
+- Do not put secrets or tokens in `Params`.
+
+## Host (portal)
+
+```js
+import { createHostBridgeHandler } from '@callcorpacd/platform-bridge/host';
+import api from '@/Services/api';
+
+const handler = createHostBridgeHandler({
+  getAllowedOrigin: () => contentOrigin,
+  getAllowedApiPrefixes: () => ['Apps/User/', 'Document/'],
+  getContextParams: () => ({ RecordId: '123', Mode: 'edit' }),
+  api,
+});
+window.addEventListener('message', handler.handleMessage);
+// Later, when params change:
+handler.pushContextUpdate();
+```
+
+`SandboxedApp.jsx` wires this for you from `ControlData.Params`.
+
+## Passing params from a UserControl document
+
+`ControlData.Params` is a flat map of **string** values. Each value may use portal interpolations (`{{...}}` or `{#...#}`). The host evaluates them and delivers the result as `platform.context.params`.
+
+```json
+{
+  "ControlType": "SandboxedApp",
+  "ControlData": {
+    "Name": "PartnerApp",
+    "SourceKind": "PlatformFile",
+    "ContentPath": "PartnerContent/hello/index.html",
+    "AllowedApiPrefixes": ["Apps/User/"],
+    "Params": {
+      "RecordId": "{{ParamByName(\"Id\")}}",
+      "Mode": "edit",
+      "Title": "Hello {# Root.UserName #}"
+    }
+  }
+}
+```
+
+Keys are static identifiers. Values are coerced to strings (`null`/`undefined` → `''`). Nested objects/arrays are out of scope—use `platform.api.*` for rich data.
+
+## Protocol v1
+
+| Type | Direction | Purpose |
+|------|-----------|---------|
+| `bridge.ready` | guest → host | Handshake |
+| `bridge.ready.ack` | host → guest | Handshake complete; payload includes `{ protocolVersion, params }` |
+| `bridge.context.update` | host → guest | `{ params }` when host Params change |
+| `bridge.api.request` | guest → host | `{ method, url, data? }` |
+| `bridge.api.response` | host → guest | `{ result }` |
+| `bridge.api.error` | host → guest | `{ message, code, status? }` |
+
+Channel id: `callcorp.platform-bridge`. Version field must match `PROTOCOL_VERSION` (currently `1`). Adding `params` on ReadyAck is additive; older guests ignore unknown payload fields.
+
+## Deploying partner content
+
+Preferred path for new apps: scaffold with `create-callcorp-sandbox`, `npm run build`, then `callcorp-sandbox publish` (see [`AUTHORING.md`](AUTHORING.md)). Vite `dist/` uses `base: './'`; `SandboxedApp` PlatformFile mode rewrites relative JS/CSS asset URLs to authenticated blob URLs.
+
+Content path convention: `PartnerContent/{AppId}/[version/]index.html`
+
+### Platform FileAPI (recommended for testing)
+
+Upload via CLI publish or the file browser. Minimal hand-built sample: [`samples/hello/`](samples/hello/).
+
+```json
+{
+  "ControlType": "SandboxedApp",
+  "ControlData": {
+    "Name": "PartnerApp",
+    "SourceKind": "PlatformFile",
+    "ContentPath": "PartnerContent/hello/index.html",
+    "AllowedApiPrefixes": ["Apps/User/"],
+    "Params": {
+      "Greeting": "Hello from the host"
+    }
+  }
+}
+```
+
+### Live localhost (dev)
+
+```json
+{
+  "ControlType": "SandboxedApp",
+  "ControlData": {
+    "Name": "PartnerAppDev",
+    "SourceKind": "Url",
+    "Url": "https://localhost:5174/",
+    "AllowedApiPrefixes": ["Apps/User/"],
+    "Params": {
+      "Mode": "dev"
+    }
+  }
+}
+```
+
+### Mass Storage / S3
+
+```json
+{
+  "ControlType": "SandboxedApp",
+  "ControlData": {
+    "Name": "PartnerApp",
+    "SourceKind": "MassStorage",
+    "OwnerId": "{# Root.CustomerID #}",
+    "ContentPath": "PartnerContent/my-app/index.html",
+    "AllowedApiPrefixes": ["Apps/User/", "Document/"],
+    "Params": {
+      "RecordId": "{{ParamByName(\"Id\")}}"
+    }
+  }
+}
+```
+
+## Roadmap
+
+- Expand host capabilities (`navigate`, `ui`, `events`) with a protocol version bump.
+- Optional VuePortal `/partner-content/...` route for streaming FileBin without blob rewriting.
+- Designer schema: add `ControlData.Params` (`object`, `additionalProperties: { type: string }`) on `DynamicControl_SandboxedApp` (runtime already accepts it via `additionalProperties: true`).
+
+Published for partners as public npm packages (`@callcorpacd/platform-bridge`, `@callcorpacd/sandbox-cli`, `create-callcorp-sandbox`). See [`../create-callcorp-sandbox/PARTNER.md`](../create-callcorp-sandbox/PARTNER.md).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@callcorpacd/platform-bridge",
+  "version": "1.0.0",
+  "description": "Guest/host postMessage bridge for sandboxed partner content in the CallCorp portal.",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./host": "./src/host.js",
+    "./protocol": "./src/protocol.js"
+  },
+  "files": [
+    "src",
+    "samples",
+    "README.md",
+    "AUTHORING.md"
+  ],
+  "keywords": [
+    "callcorp",
+    "platform-bridge",
+    "iframe",
+    "sandbox"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/samples/hello/client.js

@@ -0,0 +1,206 @@
+import { ApiMethod, MessageType, PROTOCOL_VERSION, createMessage, isBridgeMessage } from './protocol.js';
+
+function generateRequestId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID)
+        return crypto.randomUUID();
+    return `pb-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {Record<string, string>}
+ */
+function normalizeParams(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        const value = raw[key];
+        out[key] = value === undefined || value === null ? '' : String(value);
+    }
+    return out;
+}
+
+/**
+ * Create a guest-side platform bridge that talks to the portal host via postMessage.
+ * Auth tokens never enter the guest; the host attaches them when proxying API calls.
+ *
+ * @param {object} [options]
+ * @param {Window} [options.parentWindow] Parent window (default: window.parent)
+ * @param {string} [options.targetOrigin='*'] Origin used when posting to the parent; prefer a concrete origin when known
+ * @param {number} [options.handshakeTimeoutMs=15000]
+ * @returns {Promise<{
+ *   api: {
+ *     get: (url: string) => Promise<unknown>,
+ *     cachedGet: (url: string) => Promise<unknown>,
+ *     post: (url: string, data?: unknown) => Promise<unknown>,
+ *     put: (url: string, data?: unknown) => Promise<unknown>,
+ *     patch: (url: string, data?: unknown) => Promise<unknown>,
+ *     delete: (url: string) => Promise<unknown>,
+ *   },
+ *   context: {
+ *     readonly params: Record<string, string>,
+ *     subscribe: (listener: (params: Record<string, string>) => void) => () => void,
+ *   },
+ *   navigate: (...args: unknown[]) => Promise<never>,
+ *   ui: Record<string, never>,
+ *   events: Record<string, never>,
+ *   dispose: () => void,
+ *   protocolVersion: number,
+ * }>}
+ */
+export function createPlatformBridge(options = {}) {
+    const parentWindow = options.parentWindow || (typeof window !== 'undefined' ? window.parent : null);
+    const targetOrigin = options.targetOrigin || '*';
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 15000;
+
+    if (!parentWindow || parentWindow === (typeof window !== 'undefined' ? window : null)) {
+        return Promise.reject(new Error('@callcorpacd/platform-bridge: createPlatformBridge must run inside an iframe hosted by the portal.'));
+    }
+
+    const pending = new Map();
+    const contextListeners = new Set();
+    let disposed = false;
+    let ready = false;
+    /** @type {Record<string, string>} */
+    let currentParams = {};
+
+    function applyParams(raw) {
+        currentParams = Object.freeze(normalizeParams(raw));
+        for (const listener of contextListeners) {
+            try {
+                listener(currentParams);
+            }
+            catch {
+                // Guest listener errors must not break the bridge.
+            }
+        }
+    }
+
+    function post(type, requestId, payload) {
+        parentWindow.postMessage(createMessage({ type, requestId, payload }), targetOrigin);
+    }
+
+    function onMessage(event) {
+        if (disposed || !isBridgeMessage(event.data))
+            return;
+        if (event.data.version > PROTOCOL_VERSION)
+            return;
+
+        const { type, requestId, payload } = event.data;
+
+        if (type === MessageType.ReadyAck) {
+            ready = true;
+            applyParams(payload?.params);
+            const handshake = pending.get('__handshake__');
+            if (handshake) {
+                pending.delete('__handshake__');
+                handshake.resolve();
+            }
+            return;
+        }
+
+        if (type === MessageType.ContextUpdate) {
+            applyParams(payload?.params);
+            return;
+        }
+
+        if (!requestId || !pending.has(requestId))
+            return;
+
+        const entry = pending.get(requestId);
+        pending.delete(requestId);
+
+        if (type === MessageType.ApiResponse)
+            entry.resolve(payload?.result);
+        else if (type === MessageType.ApiError)
+            entry.reject(Object.assign(new Error(payload?.message || 'Bridge API error'), { bridgeError: payload }));
+    }
+
+    if (typeof window !== 'undefined')
+        window.addEventListener('message', onMessage);
+
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        if (typeof window !== 'undefined')
+            window.removeEventListener('message', onMessage);
+        contextListeners.clear();
+        for (const [, entry] of pending) {
+            entry.reject(new Error('@callcorpacd/platform-bridge: disposed'));
+        }
+        pending.clear();
+    }
+
+    function apiRequest(method, url, data) {
+        if (disposed)
+            return Promise.reject(new Error('@callcorpacd/platform-bridge: disposed'));
+        if (!ready)
+            return Promise.reject(new Error('@callcorpacd/platform-bridge: bridge is not ready'));
+
+        const requestId = generateRequestId();
+        return new Promise((resolve, reject) => {
+            pending.set(requestId, { resolve, reject });
+            post(MessageType.ApiRequest, requestId, { method, url, data });
+        });
+    }
+
+    const notImplemented = (name) => async () => {
+        throw new Error(`@callcorpacd/platform-bridge: ${name} is reserved for a future protocol version`);
+    };
+
+    const platform = {
+        protocolVersion: PROTOCOL_VERSION,
+        api: {
+            get: (url) => apiRequest(ApiMethod.GET, url),
+            cachedGet: (url) => apiRequest(ApiMethod.CACHED_GET, url),
+            post: (url, data) => apiRequest(ApiMethod.POST, url, data),
+            put: (url, data) => apiRequest(ApiMethod.PUT, url, data),
+            patch: (url, data) => apiRequest(ApiMethod.PATCH, url, data),
+            delete: (url) => apiRequest(ApiMethod.DELETE, url),
+        },
+        context: {
+            get params() {
+                return currentParams;
+            },
+            /**
+             * @param {(params: Record<string, string>) => void} listener
+             * @returns {() => void} unsubscribe
+             */
+            subscribe(listener) {
+                if (typeof listener !== 'function')
+                    throw new TypeError('@callcorpacd/platform-bridge: context.subscribe requires a function');
+                contextListeners.add(listener);
+                return () => contextListeners.delete(listener);
+            },
+        },
+        navigate: notImplemented('platform.navigate'),
+        ui: Object.freeze({}),
+        events: Object.freeze({}),
+        dispose,
+    };
+
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pending.delete('__handshake__');
+            dispose();
+            reject(new Error('@callcorpacd/platform-bridge: handshake timed out waiting for host ReadyAck'));
+        }, handshakeTimeoutMs);
+
+        pending.set('__handshake__', {
+            resolve: () => {
+                clearTimeout(timer);
+                resolve(platform);
+            },
+            reject: (err) => {
+                clearTimeout(timer);
+                reject(err);
+            },
+        });
+
+        post(MessageType.Ready, undefined, { protocolVersion: PROTOCOL_VERSION });
+    });
+}
+
+export default createPlatformBridge;

package/samples/hello/index.html

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Platform Bridge Hello</title>
+  <style>
+    :root {
+      font-family: Segoe UI, system-ui, sans-serif;
+      color: #1a1a1a;
+      background: #f7f7f5;
+    }
+    body { margin: 1.5rem; }
+    h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
+    p { margin: 0 0 1rem; color: #444; }
+    button {
+      padding: 0.5rem 0.85rem;
+      border: 1px solid #888;
+      border-radius: 4px;
+      background: #fff;
+      cursor: pointer;
+    }
+    pre {
+      white-space: pre-wrap;
+      background: #fff;
+      border: 1px solid #ddd;
+      padding: 0.75rem;
+      min-height: 4rem;
+    }
+    .label { font-weight: 600; margin-top: 1rem; }
+  </style>
+</head>
+<body>
+  <h1>Sandboxed partner sample</h1>
+  <p>
+    Upload this folder (<code>index.html</code>, <code>client.js</code>, <code>protocol.js</code>)
+    to Platform Files, then embed with <code>SandboxedApp</code> (<code>SourceKind: PlatformFile</code>).
+    Optional host <code>ControlData.Params</code> appear below after handshake.
+  </p>
+  <button id="run" type="button">Call Apps/User/FullName</button>
+  <div class="label">Host Params (<code>platform.context.params</code>)</div>
+  <pre id="params">Waiting for bridge…</pre>
+  <div class="label">API result</div>
+  <pre id="out">—</pre>
+
+  <script type="module">
+    // Deploy client.js + protocol.js beside this file (same Platform Files folder).
+    import { createPlatformBridge } from './client.js';
+
+    const out = document.getElementById('out');
+    const paramsEl = document.getElementById('params');
+    const run = document.getElementById('run');
+
+    function showParams(params) {
+      paramsEl.textContent = JSON.stringify(params, null, 2);
+    }
+
+    try {
+      const platform = await createPlatformBridge();
+      out.textContent = 'Bridge ready (protocol v' + platform.protocolVersion + ').';
+      showParams(platform.context.params);
+      platform.context.subscribe(showParams);
+
+      run.addEventListener('click', async () => {
+        out.textContent = 'Calling…';
+        try {
+          // Host ControlData.AllowedApiPrefixes must include "Apps/User/" (or "Apps/User/FullName").
+          const result = await platform.api.get('Apps/User/FullName');
+          out.textContent = JSON.stringify(result, null, 2);
+        } catch (err) {
+          out.textContent = 'Error: ' + (err.message || String(err));
+        }
+      });
+    } catch (err) {
+      out.textContent = 'Handshake failed: ' + (err.message || String(err));
+      paramsEl.textContent = '—';
+      run.disabled = true;
+    }
+  </script>
+</body>
+</html>

package/samples/hello/protocol.js

@@ -0,0 +1,60 @@
+/**
+ * Versioned postMessage protocol for @callcorpacd/platform-bridge.
+ * Bump PROTOCOL_VERSION when message shapes or capabilities change.
+ */
+
+export const PROTOCOL_VERSION = 1;
+export const CHANNEL = 'callcorp.platform-bridge';
+
+export const MessageType = Object.freeze({
+    Ready: 'bridge.ready',
+    ReadyAck: 'bridge.ready.ack',
+    ApiRequest: 'bridge.api.request',
+    ApiResponse: 'bridge.api.response',
+    ApiError: 'bridge.api.error',
+    /** Host → guest: refreshed ControlData.Params string map */
+    ContextUpdate: 'bridge.context.update',
+});
+
+export const ApiMethod = Object.freeze({
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    PATCH: 'PATCH',
+    DELETE: 'DELETE',
+    CACHED_GET: 'CACHED_GET',
+});
+
+/**
+ * @param {unknown} data
+ * @returns {boolean}
+ */
+export function isBridgeMessage(data) {
+    return !!(
+        data &&
+        typeof data === 'object' &&
+        data.channel === CHANNEL &&
+        typeof data.version === 'number' &&
+        typeof data.type === 'string'
+    );
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.type
+ * @param {string} [options.requestId]
+ * @param {unknown} [options.payload]
+ * @returns {{ channel: string, version: number, type: string, requestId?: string, payload?: unknown }}
+ */
+export function createMessage({ type, requestId, payload }) {
+    const message = {
+        channel: CHANNEL,
+        version: PROTOCOL_VERSION,
+        type,
+    };
+    if (requestId !== undefined)
+        message.requestId = requestId;
+    if (payload !== undefined)
+        message.payload = payload;
+    return message;
+}

package/src/client.js

@@ -0,0 +1,206 @@
+import { ApiMethod, MessageType, PROTOCOL_VERSION, createMessage, isBridgeMessage } from './protocol.js';
+
+function generateRequestId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID)
+        return crypto.randomUUID();
+    return `pb-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {Record<string, string>}
+ */
+function normalizeParams(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        const value = raw[key];
+        out[key] = value === undefined || value === null ? '' : String(value);
+    }
+    return out;
+}
+
+/**
+ * Create a guest-side platform bridge that talks to the portal host via postMessage.
+ * Auth tokens never enter the guest; the host attaches them when proxying API calls.
+ *
+ * @param {object} [options]
+ * @param {Window} [options.parentWindow] Parent window (default: window.parent)
+ * @param {string} [options.targetOrigin='*'] Origin used when posting to the parent; prefer a concrete origin when known
+ * @param {number} [options.handshakeTimeoutMs=15000]
+ * @returns {Promise<{
+ *   api: {
+ *     get: (url: string) => Promise<unknown>,
+ *     cachedGet: (url: string) => Promise<unknown>,
+ *     post: (url: string, data?: unknown) => Promise<unknown>,
+ *     put: (url: string, data?: unknown) => Promise<unknown>,
+ *     patch: (url: string, data?: unknown) => Promise<unknown>,
+ *     delete: (url: string) => Promise<unknown>,
+ *   },
+ *   context: {
+ *     readonly params: Record<string, string>,
+ *     subscribe: (listener: (params: Record<string, string>) => void) => () => void,
+ *   },
+ *   navigate: (...args: unknown[]) => Promise<never>,
+ *   ui: Record<string, never>,
+ *   events: Record<string, never>,
+ *   dispose: () => void,
+ *   protocolVersion: number,
+ * }>}
+ */
+export function createPlatformBridge(options = {}) {
+    const parentWindow = options.parentWindow || (typeof window !== 'undefined' ? window.parent : null);
+    const targetOrigin = options.targetOrigin || '*';
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 15000;
+
+    if (!parentWindow || parentWindow === (typeof window !== 'undefined' ? window : null)) {
+        return Promise.reject(new Error('@callcorpacd/platform-bridge: createPlatformBridge must run inside an iframe hosted by the portal.'));
+    }
+
+    const pending = new Map();
+    const contextListeners = new Set();
+    let disposed = false;
+    let ready = false;
+    /** @type {Record<string, string>} */
+    let currentParams = {};
+
+    function applyParams(raw) {
+        currentParams = Object.freeze(normalizeParams(raw));
+        for (const listener of contextListeners) {
+            try {
+                listener(currentParams);
+            }
+            catch {
+                // Guest listener errors must not break the bridge.
+            }
+        }
+    }
+
+    function post(type, requestId, payload) {
+        parentWindow.postMessage(createMessage({ type, requestId, payload }), targetOrigin);
+    }
+
+    function onMessage(event) {
+        if (disposed || !isBridgeMessage(event.data))
+            return;
+        if (event.data.version > PROTOCOL_VERSION)
+            return;
+
+        const { type, requestId, payload } = event.data;
+
+        if (type === MessageType.ReadyAck) {
+            ready = true;
+            applyParams(payload?.params);
+            const handshake = pending.get('__handshake__');
+            if (handshake) {
+                pending.delete('__handshake__');
+                handshake.resolve();
+            }
+            return;
+        }
+
+        if (type === MessageType.ContextUpdate) {
+            applyParams(payload?.params);
+            return;
+        }
+
+        if (!requestId || !pending.has(requestId))
+            return;
+
+        const entry = pending.get(requestId);
+        pending.delete(requestId);
+
+        if (type === MessageType.ApiResponse)
+            entry.resolve(payload?.result);
+        else if (type === MessageType.ApiError)
+            entry.reject(Object.assign(new Error(payload?.message || 'Bridge API error'), { bridgeError: payload }));
+    }
+
+    if (typeof window !== 'undefined')
+        window.addEventListener('message', onMessage);
+
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        if (typeof window !== 'undefined')
+            window.removeEventListener('message', onMessage);
+        contextListeners.clear();
+        for (const [, entry] of pending) {
+            entry.reject(new Error('@callcorpacd/platform-bridge: disposed'));
+        }
+        pending.clear();
+    }
+
+    function apiRequest(method, url, data) {
+        if (disposed)
+            return Promise.reject(new Error('@callcorpacd/platform-bridge: disposed'));
+        if (!ready)
+            return Promise.reject(new Error('@callcorpacd/platform-bridge: bridge is not ready'));
+
+        const requestId = generateRequestId();
+        return new Promise((resolve, reject) => {
+            pending.set(requestId, { resolve, reject });
+            post(MessageType.ApiRequest, requestId, { method, url, data });
+        });
+    }
+
+    const notImplemented = (name) => async () => {
+        throw new Error(`@callcorpacd/platform-bridge: ${name} is reserved for a future protocol version`);
+    };
+
+    const platform = {
+        protocolVersion: PROTOCOL_VERSION,
+        api: {
+            get: (url) => apiRequest(ApiMethod.GET, url),
+            cachedGet: (url) => apiRequest(ApiMethod.CACHED_GET, url),
+            post: (url, data) => apiRequest(ApiMethod.POST, url, data),
+            put: (url, data) => apiRequest(ApiMethod.PUT, url, data),
+            patch: (url, data) => apiRequest(ApiMethod.PATCH, url, data),
+            delete: (url) => apiRequest(ApiMethod.DELETE, url),
+        },
+        context: {
+            get params() {
+                return currentParams;
+            },
+            /**
+             * @param {(params: Record<string, string>) => void} listener
+             * @returns {() => void} unsubscribe
+             */
+            subscribe(listener) {
+                if (typeof listener !== 'function')
+                    throw new TypeError('@callcorpacd/platform-bridge: context.subscribe requires a function');
+                contextListeners.add(listener);
+                return () => contextListeners.delete(listener);
+            },
+        },
+        navigate: notImplemented('platform.navigate'),
+        ui: Object.freeze({}),
+        events: Object.freeze({}),
+        dispose,
+    };
+
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pending.delete('__handshake__');
+            dispose();
+            reject(new Error('@callcorpacd/platform-bridge: handshake timed out waiting for host ReadyAck'));
+        }, handshakeTimeoutMs);
+
+        pending.set('__handshake__', {
+            resolve: () => {
+                clearTimeout(timer);
+                resolve(platform);
+            },
+            reject: (err) => {
+                clearTimeout(timer);
+                reject(err);
+            },
+        });
+
+        post(MessageType.Ready, undefined, { protocolVersion: PROTOCOL_VERSION });
+    });
+}
+
+export default createPlatformBridge;

package/src/host.js

@@ -0,0 +1,241 @@
+import { ApiMethod, MessageType, PROTOCOL_VERSION, createMessage, isBridgeMessage } from './protocol.js';
+
+const SUPPORTED_METHODS = new Set(Object.values(ApiMethod));
+
+/**
+ * Normalize and validate a relative API path against an allowlist of prefixes.
+ * Absolute http(s) URLs are rejected unless allowAbsoluteUrls is true.
+ *
+ * @param {string} url
+ * @param {string[]} allowedApiPrefixes
+ * @param {{ allowAbsoluteUrls?: boolean }} [options]
+ * @returns {{ ok: true, url: string } | { ok: false, reason: string }}
+ */
+export function validateApiUrl(url, allowedApiPrefixes, options = {}) {
+    if (!url || typeof url !== 'string')
+        return { ok: false, reason: 'URL is required' };
+
+    const trimmed = url.trim();
+    const isAbsolute = /^https?:\/\//i.test(trimmed) || trimmed.startsWith('//');
+
+    if (isAbsolute && !options.allowAbsoluteUrls)
+        return { ok: false, reason: 'Absolute URLs are not allowed' };
+
+    if (isAbsolute)
+        return { ok: true, url: trimmed };
+
+    const path = trimmed.startsWith('/') ? trimmed.slice(1) : trimmed;
+    const prefixes = Array.isArray(allowedApiPrefixes) ? allowedApiPrefixes : [];
+
+    if (prefixes.length === 0)
+        return { ok: false, reason: 'No AllowedApiPrefixes configured' };
+
+    const allowed = prefixes.some((prefix) => {
+        if (prefix === undefined || prefix === null)
+            return false;
+        const normalized = String(prefix).replace(/^\//, '');
+        if (!normalized)
+            return true;
+        if (path === normalized)
+            return true;
+        if (normalized.endsWith('/'))
+            return path.startsWith(normalized);
+        return path.startsWith(`${normalized}/`);
+    });
+
+    if (!allowed)
+        return { ok: false, reason: `URL is not in AllowedApiPrefixes: ${path}` };
+
+    return { ok: true, url: path };
+}
+
+/**
+ * Resolve whether a message event origin is permitted for this sandboxed app.
+ *
+ * @param {string} eventOrigin
+ * @param {string | string[] | (() => string | string[] | null | undefined)} allowedOrigin
+ * @returns {boolean}
+ */
+export function isAllowedOrigin(eventOrigin, allowedOrigin) {
+    if (!eventOrigin)
+        return false;
+
+    const resolved = typeof allowedOrigin === 'function' ? allowedOrigin() : allowedOrigin;
+    if (!resolved)
+        return false;
+
+    const list = Array.isArray(resolved) ? resolved : [resolved];
+    return list.some((origin) => origin && (origin === '*' || origin === eventOrigin));
+}
+
+/**
+ * @returns {Record<string, string>}
+ */
+function normalizeParams(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        const value = raw[key];
+        out[key] = value === undefined || value === null ? '' : String(value);
+    }
+    return out;
+}
+
+/**
+ * Create a host-side message handler that proxies allowlisted API calls through the portal api service.
+ *
+ * @param {object} options
+ * @param {() => string | string[] | null | undefined} options.getAllowedOrigin
+ * @param {() => string[]} options.getAllowedApiPrefixes
+ * @param {object} options.api Portal api.jsx service (get/post/put/patch/delete_/cachedGet)
+ * @param {() => Record<string, string> | null | undefined} [options.getContextParams]
+ * @param {(source: MessageEventSource, origin: string) => void} [options.onReady]
+ * @param {(error: unknown, context: object) => void} [options.onError]
+ * @param {boolean} [options.allowAbsoluteUrls=false]
+ * @returns {{
+ *   handleMessage: (event: MessageEvent) => void,
+ *   pushContextUpdate: (params?: Record<string, string>) => void,
+ *   dispose: () => void,
+ * }}
+ */
+export function createHostBridgeHandler(options) {
+    const {
+        getAllowedOrigin,
+        getAllowedApiPrefixes,
+        api,
+        getContextParams,
+        onReady,
+        onError,
+        allowAbsoluteUrls = false,
+    } = options;
+
+    let disposed = false;
+    /** @type {MessageEventSource | null} */
+    let guestSource = null;
+    /** @type {string | null} */
+    let guestOrigin = null;
+
+    function reply(source, origin, type, requestId, payload) {
+        if (!source || typeof source.postMessage !== 'function')
+            return;
+        const target = origin && origin !== 'null' ? origin : '*';
+        source.postMessage(createMessage({ type, requestId, payload }), target);
+    }
+
+    function resolveParams(override) {
+        if (override !== undefined)
+            return normalizeParams(override);
+        if (typeof getContextParams === 'function')
+            return normalizeParams(getContextParams());
+        return {};
+    }
+
+    async function executeApi(method, url, data) {
+        switch (method) {
+            case ApiMethod.GET:
+                return api.get(url);
+            case ApiMethod.CACHED_GET:
+                return api.cachedGet(url);
+            case ApiMethod.POST:
+                return api.post(url, data);
+            case ApiMethod.PUT:
+                return api.put(url, data);
+            case ApiMethod.PATCH:
+                return api.patch(url, data);
+            case ApiMethod.DELETE:
+                return api.delete_(url);
+            default:
+                throw new Error(`Unsupported bridge API method: ${method}`);
+        }
+    }
+
+    async function handleMessage(event) {
+        if (disposed || !isBridgeMessage(event.data))
+            return;
+        if (event.data.version !== PROTOCOL_VERSION)
+            return;
+        if (!isAllowedOrigin(event.origin, getAllowedOrigin))
+            return;
+
+        const { type, requestId, payload } = event.data;
+
+        if (type === MessageType.Ready) {
+            guestSource = event.source;
+            guestOrigin = event.origin;
+            reply(event.source, event.origin, MessageType.ReadyAck, undefined, {
+                protocolVersion: PROTOCOL_VERSION,
+                params: resolveParams(),
+            });
+            if (onReady)
+                onReady(event.source, event.origin);
+            return;
+        }
+
+        if (type !== MessageType.ApiRequest)
+            return;
+
+        try {
+            const method = payload?.method;
+            const url = payload?.url;
+            const data = payload?.data;
+
+            if (!SUPPORTED_METHODS.has(method)) {
+                reply(event.source, event.origin, MessageType.ApiError, requestId, {
+                    message: `Unsupported method: ${method}`,
+                    code: 'unsupported_method',
+                });
+                return;
+            }
+
+            const validation = validateApiUrl(url, getAllowedApiPrefixes(), { allowAbsoluteUrls });
+            if (!validation.ok) {
+                reply(event.source, event.origin, MessageType.ApiError, requestId, {
+                    message: validation.reason,
+                    code: 'url_not_allowed',
+                });
+                return;
+            }
+
+            const result = await executeApi(method, validation.url, data);
+            reply(event.source, event.origin, MessageType.ApiResponse, requestId, { result });
+        }
+        catch (error) {
+            if (onError)
+                onError(error, { requestId, payload });
+
+            const status = error?.StatusCode ?? error?.statusCode ?? error?.status;
+            reply(event.source, event.origin, MessageType.ApiError, requestId, {
+                message: error?.message || error?.Message || String(error),
+                code: status === 401 ? 'unauthorized' : 'api_error',
+                status,
+                // Never forward tokens or raw headers; include a shallow server payload when present.
+                detail: error?.Result ?? error?.data ?? undefined,
+            });
+        }
+    }
+
+    /**
+     * Push an updated params map to the connected guest (after handshake).
+     * @param {Record<string, string>} [params] Defaults to getContextParams()
+     */
+    function pushContextUpdate(params) {
+        if (disposed || !guestSource)
+            return;
+        reply(guestSource, guestOrigin, MessageType.ContextUpdate, undefined, {
+            params: resolveParams(params),
+        });
+    }
+
+    return {
+        handleMessage,
+        pushContextUpdate,
+        dispose() {
+            disposed = true;
+            guestSource = null;
+            guestOrigin = null;
+        },
+    };
+}
+
+export default createHostBridgeHandler;

package/src/index.js

@@ -0,0 +1,15 @@
+export {
+    PROTOCOL_VERSION,
+    CHANNEL,
+    MessageType,
+    ApiMethod,
+    isBridgeMessage,
+    createMessage,
+} from './protocol.js';
+
+export { createPlatformBridge } from './client.js';
+export {
+    createHostBridgeHandler,
+    validateApiUrl,
+    isAllowedOrigin,
+} from './host.js';

package/src/protocol.js

@@ -0,0 +1,60 @@
+/**
+ * Versioned postMessage protocol for @callcorpacd/platform-bridge.
+ * Bump PROTOCOL_VERSION when message shapes or capabilities change.
+ */
+
+export const PROTOCOL_VERSION = 1;
+export const CHANNEL = 'callcorp.platform-bridge';
+
+export const MessageType = Object.freeze({
+    Ready: 'bridge.ready',
+    ReadyAck: 'bridge.ready.ack',
+    ApiRequest: 'bridge.api.request',
+    ApiResponse: 'bridge.api.response',
+    ApiError: 'bridge.api.error',
+    /** Host → guest: refreshed ControlData.Params string map */
+    ContextUpdate: 'bridge.context.update',
+});
+
+export const ApiMethod = Object.freeze({
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    PATCH: 'PATCH',
+    DELETE: 'DELETE',
+    CACHED_GET: 'CACHED_GET',
+});
+
+/**
+ * @param {unknown} data
+ * @returns {boolean}
+ */
+export function isBridgeMessage(data) {
+    return !!(
+        data &&
+        typeof data === 'object' &&
+        data.channel === CHANNEL &&
+        typeof data.version === 'number' &&
+        typeof data.type === 'string'
+    );
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.type
+ * @param {string} [options.requestId]
+ * @param {unknown} [options.payload]
+ * @returns {{ channel: string, version: number, type: string, requestId?: string, payload?: unknown }}
+ */
+export function createMessage({ type, requestId, payload }) {
+    const message = {
+        channel: CHANNEL,
+        version: PROTOCOL_VERSION,
+        type,
+    };
+    if (requestId !== undefined)
+        message.requestId = requestId;
+    if (payload !== undefined)
+        message.payload = payload;
+    return message;
+}