@braidlabs/core 0.1.1 → 0.2.0

package/src/realm/realm-manager.js

@@ -1,5 +1,5 @@
 import { BraidError } from '../errors.js';
-import { isDevMode } from '../config.js';
+import { getBraidConfig, isDevMode } from '../config.js';
 import { BRAID_ADAPTER_META, BRAID_ADAPTER_OPTIONS_META, BRAID_PROTOCOL_META, BRAID_PROTOCOL_VERSION, braidFragmentUrl, braidRealmUrl, } from '../protocol.js';
 export async function createRealm(kind, init) {
     switch (kind) {
@@ -8,10 +8,16 @@ export async function createRealm(kind, init) {
         case 'contract-blob':
             return createContractBlobRealm(init);
         case 'sandbox':
-            throw new BraidError('the sandbox realm kind (untrusted tier) is not available in this build', {
+            /**
+             * Not a failure any more — a redirection. The untrusted tier is built, but it is not a
+             * `RealmHandle`: `window`, `document` and `evaluate()` are same-origin capabilities that a
+             * cross-origin frame cannot offer, and faking them is the illusion that tier exists to
+             * refuse. See `createSandboxRealm`.
+             */
+            throw new BraidError('untrusted fragments are not created through createRealm()', {
                 fragmentId: init.fragmentId,
                 stage: 'realm-boot',
-                fixHint: 'this build ships the trusted tier only — trusted realms are namespace isolation, not a security boundary',
+                fixHint: 'mount it as <fragment-slot trust="untrusted" src="https://…">, or call createSandboxRealm() directly',
             });
         default:
             throw new BraidError(`unknown realm kind "${kind}"`, {
@@ -38,7 +44,7 @@ async function createContractBlobRealm(init) {
     const { fragmentId, importMap } = init;
     // The base href must be absolute: a blob: URL has an opaque path, so a root-relative href
     // has nothing meaningful to resolve against.
-    const baseHref = new URL(braidFragmentUrl(fragmentId, '/'), location.origin).href;
+    const baseHref = init.baseHref ?? new URL(braidFragmentUrl(fragmentId, '/', '', getBraidConfig().basePath), location.origin).href;
     const realmDocumentHtml = `<!doctype html><meta charset="utf-8"><title>Braid realm: ${escapeHtml(fragmentId)}</title>` +
         `<meta name="${BRAID_PROTOCOL_META}" content="${BRAID_PROTOCOL_VERSION}">` +
         `<base href="${escapeHtml(baseHref)}">` +
@@ -216,8 +222,11 @@ async function createCompatHttpRealm(init) {
      */
     const iframe = document.createElement('iframe');
     iframe.hidden = true;
-    // the realm stub has its own namespace, so the fragment's asset URLs carry no header variance
-    iframe.src = braidRealmUrl(fragmentId, routeSrcUrl.pathname, routeSrcUrl.search);
+    // The realm stub has its own namespace, so the fragment's asset URLs carry no header variance.
+    // One stub per fragment, whatever the route: its only route-dependent part is `<base>`, which is
+    // set below. A stub per route and query was a cold request on every new page or `?utm=` — and a
+    // URL no precache could name in advance.
+    iframe.src = braidRealmUrl(fragmentId, '/', '', getBraidConfig().basePath);
     iframe.name = `braid:${fragmentId}`;
     const { promise: loaded, resolve: resolveLoaded, reject: rejectLoaded } = Promise.withResolvers();
     let alreadyLoaded = false;
@@ -246,6 +255,7 @@ async function createCompatHttpRealm(init) {
         alreadyLoaded = true;
         try {
             verifyRealmStub(iframe, fragmentId);
+            pointStubAtRoute(iframe.contentDocument, braidFragmentUrl(fragmentId, routeSrcUrl.pathname, '', getBraidConfig().basePath));
             // Restore the fragment's route-url illusion: the iframe was loaded from the gateway
             // namespace, but the fragment's JS context must observe the route url as its location.
             // The stub's <base> element is unaffected by replaceState and keeps relative url
@@ -266,6 +276,20 @@ async function createCompatHttpRealm(init) {
     init.signal.addEventListener('abort', () => handle.dispose(), { once: true });
     return handle;
 }
+/**
+ * Points a realm stub's relative urls at the route's directory in the fragment namespace, exactly
+ * as a stub fetched at the route would have. Nothing in the stub has resolved a url yet, so this is
+ * indistinguishable from the gateway having written it. A stub without a `<base>` — a hand-rolled
+ * one, say — gets one, rather than resolving everything against the stub's own url.
+ */
+export function pointStubAtRoute(stubDocument, href) {
+    let base = stubDocument.querySelector('base');
+    if (!base) {
+        base = stubDocument.createElement('base');
+        stubDocument.head.append(base);
+    }
+    base.setAttribute('href', href);
+}
 /**
  * Verifies the loaded iframe document is the gateway's realm stub for this protocol version.
  * This replaces title-check heuristics with explicit version negotiation: mismatches and
@@ -289,7 +313,8 @@ function verifyRealmStub(iframe, fragmentId) {
             stage: 'realm-boot',
             fixHint: protocol
                 ? 'upgrade @braidlabs/core and @braidlabs/gateway to the same package version'
-                : `ensure the braid gateway is mounted in front of this app and has a manifest registered for fragment id "${fragmentId}"`,
+                : `ensure the braid gateway is mounted in front of this app and has a manifest registered for fragment id "${fragmentId}", ` +
+                    `and that initBraid({ basePath }) matches the gateway's basePath`,
         });
     }
 }

package/src/realm/realm-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"realm-manager.js","sourceRoot":"","sources":["../../../../../libs/core/src/realm/realm-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"realm-manager.js","sourceRoot":"","sources":["../../../../../libs/core/src/realm/realm-manager.ts"],"names":[],"mappings":"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"}

package/src/realm/sandbox-realm.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The untrusted tier: a real cross-origin iframe, with a good protocol on it.
+ *
+ * That sentence is the honest description and it is worth leading with, because Braid's own
+ * documentation has been quietly implying otherwise. The trusted tier's advantages — one document,
+ * one layout, one accessibility tree, SSR piercing, printing, DOM projection — are consequences of
+ * *sharing a document*, and none of them survive a boundary the browser enforces. This tier gives
+ * up every one of them. In exchange it gives the only thing the trusted tier cannot: separation
+ * that holds when the code on the other side has gone bad rather than merely gone wrong.
+ *
+ * So this is not a better realm. It is a different bet, and the architecture is explicit about
+ * which one you are making:
+ *
+ * | | trusted (`compat-http`, `contract-blob`) | untrusted (`sandbox`) |
+ * | --- | --- | --- |
+ * | isolation | namespace, not security | browser-enforced |
+ * | DOM | projected into the host document | stays in its own document |
+ * | cookies/storage | the host's | its own, partitioned |
+ * | composition | gateway namespaces, piercing, compat facade | none of it applies |
+ *
+ * **Why this is not a `RealmHandle`.** That interface exposes `window`, `document`, `evaluate()`
+ * and `evaluateModule()` — every one of which is a same-origin capability. Making a cross-origin
+ * realm implement it would mean either throwing from four members or faking them, and faking them
+ * is precisely the "manufacture the illusion that two documents are one" move this tier exists to
+ * refuse. A different thing gets a different type.
+ */
+/** The connect message the host posts into the frame, carrying the port. */
+export declare const SANDBOX_CONNECT = "braid:connect";
+/** The announcement a guest posts to its parent when it is ready to receive one. */
+export declare const SANDBOX_READY = "braid:ready";
+export interface SandboxConnectMessage {
+    braid: typeof SANDBOX_CONNECT;
+    v: 1;
+    fragmentId: string;
+    instance: string;
+}
+export interface SandboxReadyMessage {
+    braid: typeof SANDBOX_READY;
+    v: 1;
+}
+/**
+ * Sandbox tokens granted to every untrusted fragment.
+ *
+ * `allow-scripts` because a fragment that cannot run scripts is not an application. `allow-forms`
+ * because a form post is the least surprising thing a page does. Everything else is an opt-in the
+ * host records in the registry, so the grant lives with the person who decided to make it.
+ */
+export declare const DEFAULT_SANDBOX_TOKENS: readonly ["allow-scripts", "allow-forms"];
+export interface SandboxRealmInit {
+    fragmentId: string;
+    /** The fragment's URL. Must be cross-origin to the host — see `assertCrossOrigin`. */
+    src: string;
+    /** Where the frame is mounted. The untrusted tier renders visibly; it projects nothing. */
+    container: ShadowRoot | HTMLElement;
+    signal: AbortSignal;
+    /** Additional sandbox tokens from the fragment's manifest. */
+    sandboxTokens?: readonly string[];
+    /** Permissions-Policy features to delegate, e.g. `['clipboard-write']`. */
+    permissions?: readonly string[];
+    /** How long to wait for the frame to load before failing. */
+    loadTimeoutMs?: number;
+}
+export interface SandboxRealm {
+    readonly kind: 'sandbox';
+    readonly fragmentId: string;
+    /** The frame element, so a host can size it. Its contents are not reachable from here. */
+    readonly frame: HTMLIFrameElement;
+    /** The fragment's origin, for pinning every message that crosses. */
+    readonly origin: string;
+    /** The host end of the message channel. */
+    readonly port: MessagePort;
+    dispose(): void;
+}
+/**
+ * Refuses a same-origin URL for the untrusted tier.
+ *
+ * This is the single most important check in the file. `sandbox="allow-scripts allow-same-origin"`
+ * on a **same-origin** frame is a sandbox that isn't one — the frame can reach into the host
+ * document and remove its own sandbox attribute — and the mistake is easy to make because the
+ * markup looks locked down. Refusing at the source, rather than trusting the token list, means the
+ * dangerous combination cannot be assembled from a manifest edit.
+ */
+export declare function assertCrossOrigin(src: string, fragmentId: string): string;
+/** Resolves the sandbox token list, refusing the ones that would undo the sandbox. */
+export declare function resolveSandboxTokens(requested: readonly string[] | undefined, fragmentId: string): string[];
+/**
+ * Creates the frame, waits for it to load, and establishes the message channel.
+ *
+ * The connect handshake is deliberately tolerant of ordering. The frame's `load` event and the
+ * guest's own script registering its listener race, and which wins depends on cache state — so the
+ * host posts on load *and* answers a guest that announces itself, and the guest announces itself
+ * whether or not it has already been posted to. Either order converges; neither has to be the fast
+ * one.
+ */
+export declare function createSandboxRealm(init: SandboxRealmInit): Promise<SandboxRealm>;

package/src/realm/sandbox-realm.js

@@ -0,0 +1,194 @@
+import { BraidError } from '../errors.js';
+/**
+ * The untrusted tier: a real cross-origin iframe, with a good protocol on it.
+ *
+ * That sentence is the honest description and it is worth leading with, because Braid's own
+ * documentation has been quietly implying otherwise. The trusted tier's advantages — one document,
+ * one layout, one accessibility tree, SSR piercing, printing, DOM projection — are consequences of
+ * *sharing a document*, and none of them survive a boundary the browser enforces. This tier gives
+ * up every one of them. In exchange it gives the only thing the trusted tier cannot: separation
+ * that holds when the code on the other side has gone bad rather than merely gone wrong.
+ *
+ * So this is not a better realm. It is a different bet, and the architecture is explicit about
+ * which one you are making:
+ *
+ * | | trusted (`compat-http`, `contract-blob`) | untrusted (`sandbox`) |
+ * | --- | --- | --- |
+ * | isolation | namespace, not security | browser-enforced |
+ * | DOM | projected into the host document | stays in its own document |
+ * | cookies/storage | the host's | its own, partitioned |
+ * | composition | gateway namespaces, piercing, compat facade | none of it applies |
+ *
+ * **Why this is not a `RealmHandle`.** That interface exposes `window`, `document`, `evaluate()`
+ * and `evaluateModule()` — every one of which is a same-origin capability. Making a cross-origin
+ * realm implement it would mean either throwing from four members or faking them, and faking them
+ * is precisely the "manufacture the illusion that two documents are one" move this tier exists to
+ * refuse. A different thing gets a different type.
+ */
+/** The connect message the host posts into the frame, carrying the port. */
+export const SANDBOX_CONNECT = 'braid:connect';
+/** The announcement a guest posts to its parent when it is ready to receive one. */
+export const SANDBOX_READY = 'braid:ready';
+/**
+ * Sandbox tokens granted to every untrusted fragment.
+ *
+ * `allow-scripts` because a fragment that cannot run scripts is not an application. `allow-forms`
+ * because a form post is the least surprising thing a page does. Everything else is an opt-in the
+ * host records in the registry, so the grant lives with the person who decided to make it.
+ */
+export const DEFAULT_SANDBOX_TOKENS = ['allow-scripts', 'allow-forms'];
+/**
+ * Tokens that are never granted, whatever the manifest says.
+ *
+ * `allow-top-navigation` lets an embedded frame navigate the whole page — the classic way an
+ * embedded advert becomes a phishing redirect. The `-by-user-activation` variant is the one to
+ * grant if you need it, and it must be granted deliberately rather than inherited from a broad
+ * "let this fragment navigate" instinct.
+ */
+const REFUSED_SANDBOX_TOKENS = new Set(['allow-top-navigation']);
+const LOAD_TIMEOUT_MS = 15_000;
+/**
+ * Refuses a same-origin URL for the untrusted tier.
+ *
+ * This is the single most important check in the file. `sandbox="allow-scripts allow-same-origin"`
+ * on a **same-origin** frame is a sandbox that isn't one — the frame can reach into the host
+ * document and remove its own sandbox attribute — and the mistake is easy to make because the
+ * markup looks locked down. Refusing at the source, rather than trusting the token list, means the
+ * dangerous combination cannot be assembled from a manifest edit.
+ */
+export function assertCrossOrigin(src, fragmentId) {
+    let url;
+    try {
+        url = new URL(src, location.href);
+    }
+    catch (cause) {
+        throw new BraidError(`"${src}" is not a valid url for an untrusted fragment`, {
+            fragmentId,
+            stage: 'slot-config',
+            cause,
+            fixHint: 'untrusted fragments are addressed by absolute url, e.g. src="https://vendor.example.com/widget"',
+        });
+    }
+    if (url.origin === location.origin) {
+        throw new BraidError(`the untrusted tier requires a cross-origin url, and "${url.origin}" is this host's origin`, {
+            fragmentId,
+            stage: 'slot-config',
+            fixHint: 'serve the fragment from a different origin — a same-origin sandbox is not a security ' +
+                'boundary, because the framed document can reach the host and clear its own sandbox attribute',
+        });
+    }
+    return url.origin;
+}
+/** Resolves the sandbox token list, refusing the ones that would undo the sandbox. */
+export function resolveSandboxTokens(requested = [], fragmentId) {
+    const tokens = new Set(DEFAULT_SANDBOX_TOKENS);
+    for (const token of requested) {
+        if (REFUSED_SANDBOX_TOKENS.has(token)) {
+            throw new BraidError(`the sandbox token "${token}" is never granted to an untrusted fragment`, {
+                fragmentId,
+                stage: 'slot-config',
+                fixHint: `use "${token}-by-user-activation" if the fragment genuinely needs to navigate the page`,
+            });
+        }
+        tokens.add(token);
+    }
+    return [...tokens];
+}
+/**
+ * Creates the frame, waits for it to load, and establishes the message channel.
+ *
+ * The connect handshake is deliberately tolerant of ordering. The frame's `load` event and the
+ * guest's own script registering its listener race, and which wins depends on cache state — so the
+ * host posts on load *and* answers a guest that announces itself, and the guest announces itself
+ * whether or not it has already been posted to. Either order converges; neither has to be the fast
+ * one.
+ */
+export async function createSandboxRealm(init) {
+    const { fragmentId, src, container, signal } = init;
+    const origin = assertCrossOrigin(src, fragmentId);
+    const tokens = resolveSandboxTokens(init.sandboxTokens, fragmentId);
+    const instance = `${fragmentId}:${Date.now().toString(36)}`;
+    const frame = document.createElement('iframe');
+    frame.src = src;
+    frame.setAttribute('sandbox', tokens.join(' '));
+    frame.setAttribute('part', 'frame');
+    frame.style.cssText = 'display:block;border:0;width:100%;height:100%';
+    /**
+     * Permissions-Policy delegation is a *deny* list by default: an unlisted feature is unavailable
+     * inside the frame regardless of what the fragment's own origin allows. Setting `allow` to the
+     * empty string when nothing is granted is not redundant — it makes the denial explicit in the
+     * markup, where someone auditing the page will see it.
+     */
+    frame.setAttribute('allow', (init.permissions ?? []).join('; '));
+    // Progressive: where supported, the frame gets an ephemeral, per-page storage and cookie jar, so
+    // an untrusted fragment cannot correlate this user with the same fragment on another site.
+    if ('credentialless' in HTMLIFrameElement.prototype) {
+        frame.setAttribute('credentialless', '');
+    }
+    container.append(frame);
+    const channel = new MessageChannel();
+    const dispose = () => {
+        channel.port1.close();
+        frame.remove();
+    };
+    signal.addEventListener('abort', dispose, { once: true });
+    const post = () => {
+        const message = { braid: SANDBOX_CONNECT, v: 1, fragmentId, instance };
+        /**
+         * The target origin is the fragment's exact origin, never `'*'`.
+         *
+         * With `'*'` the port would be delivered to whatever document happens to occupy the frame — and
+         * an untrusted fragment that navigated itself elsewhere between load and this call would hand a
+         * live channel into the host to a document nobody vetted.
+         */
+        frame.contentWindow?.postMessage(message, origin, [channel.port2]);
+    };
+    const { promise, resolve, reject } = Promise.withResolvers();
+    let connected = false;
+    const onWindowMessage = (event) => {
+        // Origin-pinned inbound as well as outbound: a `braid:ready` from any other origin is some
+        // other page on the tab talking, and must not cause the host to hand out a port.
+        if (event.origin !== origin)
+            return;
+        if (event.data?.braid !== SANDBOX_READY)
+            return;
+        if (connected)
+            return;
+        connected = true;
+        post();
+        resolve();
+    };
+    window.addEventListener('message', onWindowMessage);
+    const onLoad = () => {
+        if (connected)
+            return;
+        connected = true;
+        post();
+        resolve();
+    };
+    frame.addEventListener('load', onLoad, { once: true });
+    const timeout = setTimeout(() => {
+        reject(new BraidError(`the untrusted fragment at "${src}" did not load within ${init.loadTimeoutMs ?? LOAD_TIMEOUT_MS}ms`, {
+            fragmentId,
+            stage: 'realm-boot',
+            fixHint: 'check the url, and that the fragment origin does not refuse framing via X-Frame-Options or CSP frame-ancestors',
+        }));
+    }, init.loadTimeoutMs ?? LOAD_TIMEOUT_MS);
+    try {
+        await promise;
+    }
+    finally {
+        clearTimeout(timeout);
+        window.removeEventListener('message', onWindowMessage);
+        frame.removeEventListener('load', onLoad);
+    }
+    return {
+        kind: 'sandbox',
+        fragmentId,
+        frame,
+        origin,
+        port: channel.port1,
+        dispose,
+    };
+}
+//# sourceMappingURL=sandbox-realm.js.map

package/src/realm/sandbox-realm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-realm.js","sourceRoot":"","sources":["../../../../../libs/core/src/realm/sandbox-realm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAC/C,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAc3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,eAAe,EAAE,aAAa,CAAU,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC;AA6BjE,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAkB;IAC/D,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,IAAI,GAAG,gDAAgD,EAAE;YAC5E,UAAU;YACV,KAAK,EAAE,aAAa;YACpB,KAAK;YACL,OAAO,EAAE,iGAAiG;SAC3G,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,wDAAwD,GAAG,CAAC,MAAM,yBAAyB,EAAE;YAChH,UAAU;YACV,KAAK,EAAE,aAAa;YACpB,OAAO,EACL,uFAAuF;gBACvF,8FAA8F;SACjG,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,oBAAoB,CAAC,YAA+B,EAAE,EAAE,UAAkB;IACxF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,sBAAsB,CAAC,CAAC;IAEvD,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,UAAU,CAAC,sBAAsB,KAAK,6CAA6C,EAAE;gBAC7F,UAAU;gBACV,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,QAAQ,KAAK,2EAA2E;aAClG,CAAC,CAAC;QACL,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAsB;IAC7D,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEpD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,oBAAoB,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IAE5D,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC/C,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;IAChB,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,+CAA+C,CAAC;IAEtE;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAEjE,iGAAiG;IACjG,2FAA2F;IAC3F,IAAI,gBAAgB,IAAI,iBAAiB,CAAC,SAAS,EAAE,CAAC;QACpD,KAAK,CAAC,YAAY,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;IAErC,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,MAAM,OAAO,GAA0B,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;QAC9F;;;;;;WAMG;QACH,KAAK,CAAC,aAAa,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IACnE,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,eAAe,GAAG,CAAC,KAAmB,EAAE,EAAE;QAC9C,2FAA2F;QAC3F,iFAAiF;QACjF,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO;QACpC,IAAK,KAAK,CAAC,IAAwC,EAAE,KAAK,KAAK,aAAa;YAAE,OAAO;QACrF,IAAI,SAAS;YAAE,OAAO;QACtB,SAAS,GAAG,IAAI,CAAC;QACjB,IAAI,EAAE,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,IAAI,SAAS;YAAE,OAAO;QACtB,SAAS,GAAG,IAAI,CAAC;QACjB,IAAI,EAAE,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;IACF,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;QAC9B,MAAM,CACJ,IAAI,UAAU,CAAC,8BAA8B,GAAG,yBAAyB,IAAI,CAAC,aAAa,IAAI,eAAe,IAAI,EAAE;YAClH,UAAU;YACV,KAAK,EAAE,YAAY;YACnB,OAAO,EAAE,gHAAgH;SAC1H,CAAC,CACH,CAAC;IACJ,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,eAAe,CAAC,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,OAAO,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACtB,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QACvD,KAAK,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,UAAU;QACV,KAAK;QACL,MAAM;QACN,IAAI,EAAE,OAAO,CAAC,KAAK;QACnB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/src/weave/capabilities.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What a fragment is allowed to do, declared by the host and enforced where enforcement is possible.
+ *
+ * The organising principle is that **every grant names who enforces it**, because they are not all
+ * enforced by the same thing and pretending otherwise is how a capability system becomes theatre:
+ *
+ * | Grant | Enforced by | Trusted tier | Untrusted tier |
+ * | --- | --- | --- | --- |
+ * | `context` | **Braid** — the bus is ours | yes | yes |
+ * | `sandbox` | the browser | n/a — no frame to sandbox | yes |
+ * | `permissions` | the browser (Permissions-Policy) | n/a | yes |
+ * | `network` | the browser (CSP), or nobody | **advisory only** | CSP on the fragment's own origin |
+ *
+ * `context` is the one that matters most on the trusted tier, and the one Braid can actually
+ * enforce there — because Phase 1 turned the context bus into a message, so "what may this fragment
+ * read" became a question asked in exactly one place instead of a check to remember at every read.
+ *
+ * `network` is listed as advisory on the trusted tier rather than omitted. A trusted fragment runs
+ * in a same-origin realm with the host's `fetch`; Braid does not patch host globals and will not
+ * start, so this grant documents intent and feeds the registry's analysis. Recording that honestly
+ * is better than either enforcing it badly or leaving people to assume it works.
+ */
+export interface ContextGrants {
+    /**
+     * Context keys this fragment may read. Absent means **every key** — the pre-grant behaviour, kept
+     * as the default so that adding capabilities to one fragment does not silently starve the rest.
+     */
+    read?: string[];
+    /** Reserved: context keys this fragment may publish. No fragment can publish today. */
+    write?: string[];
+}
+export interface FragmentCapabilities {
+    context?: ContextGrants;
+    /** Additive `sandbox` tokens for an untrusted frame. */
+    sandbox?: string[];
+    /** Permissions-Policy features delegated into an untrusted frame. */
+    permissions?: string[];
+    /** Origins the fragment is expected to talk to. Advisory on the trusted tier — see above. */
+    network?: string[];
+    /** Reserved for the storage-partitioning work. */
+    storage?: 'partitioned' | 'shared';
+}
+/**
+ * Decides whether a context key may cross to a fragment, and says so once when it may not.
+ *
+ * Returning `undefined` rather than throwing is deliberate: an ungranted key must look to the
+ * fragment exactly like a key nobody has published, because those two cases are genuinely the same
+ * from inside the fragment and a distinct error would leak the shape of the host's context to code
+ * that was specifically not given it.
+ *
+ * The dev-mode warning is the other half. Silence would be correct for production and miserable for
+ * whoever is wondering why `user` is undefined, so the *host's* console names the missing grant —
+ * host-side, because the host is where the grant is written.
+ */
+export declare function createContextGate(capabilities: FragmentCapabilities | undefined, fragmentId: string): (key: string) => boolean;
+/**
+ * Resolves capabilities from the three places a host can write them, most authoritative first:
+ *
+ * 1. **the realm stub** — stamped by the gateway from the registry manifest (trusted tier only);
+ * 2. **`initBraid({ capabilities })`** — the registry stand-in for gateway-free composition, which
+ *    is the only source the untrusted tier has;
+ * 3. **slot attributes** — `sandbox=`, `allow=` on the element itself.
+ *
+ * All three are host-controlled, so this is a precedence rule rather than a trust ranking: every
+ * source is equally unable to be influenced by the fragment. The order reflects how centrally
+ * managed each one is, so that a grant written once in the registry is not quietly widened by markup
+ * on one page.
+ */
+export declare function resolveCapabilities(sources: Array<FragmentCapabilities | undefined>): FragmentCapabilities | undefined;
+/** Reads a capabilities block off a realm stub's adapter options, or off `initBraid` config. */
+export declare function readCapabilities(source: unknown): FragmentCapabilities | undefined;

package/src/weave/capabilities.js

@@ -0,0 +1,61 @@
+import { isDevMode } from '../config.js';
+/**
+ * Decides whether a context key may cross to a fragment, and says so once when it may not.
+ *
+ * Returning `undefined` rather than throwing is deliberate: an ungranted key must look to the
+ * fragment exactly like a key nobody has published, because those two cases are genuinely the same
+ * from inside the fragment and a distinct error would leak the shape of the host's context to code
+ * that was specifically not given it.
+ *
+ * The dev-mode warning is the other half. Silence would be correct for production and miserable for
+ * whoever is wondering why `user` is undefined, so the *host's* console names the missing grant —
+ * host-side, because the host is where the grant is written.
+ */
+export function createContextGate(capabilities, fragmentId) {
+    const read = capabilities?.context?.read;
+    if (!read)
+        return () => true;
+    const granted = new Set(read);
+    const warned = new Set();
+    return (key) => {
+        if (granted.has(key))
+            return true;
+        if (isDevMode() && !warned.has(key)) {
+            warned.add(key);
+            console.warn(`[braid:${fragmentId}] context "${key}" was not delivered: it is not in this fragment's ` +
+                `context.read grant (${[...granted].join(', ') || 'none'}). Add it to the fragment's ` +
+                `capabilities if it should be.`);
+        }
+        return false;
+    };
+}
+/**
+ * Resolves capabilities from the three places a host can write them, most authoritative first:
+ *
+ * 1. **the realm stub** — stamped by the gateway from the registry manifest (trusted tier only);
+ * 2. **`initBraid({ capabilities })`** — the registry stand-in for gateway-free composition, which
+ *    is the only source the untrusted tier has;
+ * 3. **slot attributes** — `sandbox=`, `allow=` on the element itself.
+ *
+ * All three are host-controlled, so this is a precedence rule rather than a trust ranking: every
+ * source is equally unable to be influenced by the fragment. The order reflects how centrally
+ * managed each one is, so that a grant written once in the registry is not quietly widened by markup
+ * on one page.
+ */
+export function resolveCapabilities(sources) {
+    const present = sources.filter((source) => Boolean(source));
+    if (present.length === 0)
+        return undefined;
+    // Later sources are less authoritative, so earlier ones are spread last and win.
+    return present.reduceRight((merged, source) => ({ ...merged, ...source }), {});
+}
+/** Reads a capabilities block off a realm stub's adapter options, or off `initBraid` config. */
+export function readCapabilities(source) {
+    if (!source || typeof source !== 'object')
+        return undefined;
+    const capabilities = source.capabilities;
+    if (!capabilities || typeof capabilities !== 'object')
+        return undefined;
+    return capabilities;
+}
+//# sourceMappingURL=capabilities.js.map

package/src/weave/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA+CzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAA8C,EAC9C,UAAkB;IAElB,MAAM,IAAI,GAAG,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;IAE7B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAEjC,OAAO,CAAC,GAAW,EAAE,EAAE;QACrB,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,IAAI,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChB,OAAO,CAAC,IAAI,CACV,UAAU,UAAU,cAAc,GAAG,oDAAoD;gBACvF,uBAAuB,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,8BAA8B;gBACtF,+BAA+B,CAClC,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAgD;IAEhD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAkC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,iFAAiF;IACjF,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,EAA0B,CAAC,CAAC;AACzG,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC9C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,YAAY,GAAI,MAAqC,CAAC,YAAY,CAAC;IACzE,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxE,OAAO,YAAoC,CAAC;AAC9C,CAAC"}

package/src/weave/channel.d.ts

@@ -0,0 +1,63 @@
+import { Envelope } from './envelope.js';
+/**
+ * The transport a channel runs over. Two exist: `same-realm` for trusted realms (direct dispatch,
+ * no serialization) and `port` for the cross-origin tier (`MessagePort` + structured clone).
+ *
+ * The interface is this small on purpose. Everything interesting — correlation, deadlines, replies,
+ * error propagation, close — lives in the channel above it, so that adding a transport is not an
+ * occasion to re-implement any of it slightly differently.
+ */
+export interface ChannelBacking {
+    post(envelope: Envelope): void;
+    /** Registers the sole inbound handler. Returns a detach function. */
+    receive(handler: (envelope: Envelope) => void): () => void;
+    close(): void;
+}
+/** Context handed to a message handler alongside its payload. */
+export interface MessageMeta {
+    readonly fragmentId: string;
+    readonly instance: string;
+    readonly scope: string | undefined;
+    readonly type: string;
+}
+export type MessageHandler = (payload: unknown, meta: MessageMeta) => unknown;
+export interface RequestOptions {
+    timeoutMs?: number;
+    scope?: string;
+}
+export interface BoundaryChannel {
+    /** Fire and forget. No reply is expected and none will be delivered. */
+    send(type: string, payload?: unknown, options?: {
+        scope?: string;
+    }): void;
+    /** Sends and awaits a reply. Rejects on timeout, on a remote throw, or if the channel closes. */
+    request<T = unknown>(type: string, payload?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Handles one message type, optionally on one scope.
+     *
+     * One handler per **(type, scope)** pair — a second registration for the same pair replaces the
+     * first, which keeps a duplicate registration a visible bug rather than a silent double-reply.
+     *
+     * Scope is part of the address rather than a filter the handler applies itself, and that
+     * distinction is load-bearing: a fragment reading both its own bus and the page bus registers
+     * `ctx/changed` twice, and with scope as a mere filter the second registration would silently
+     * displace the first and one of the two buses would go quiet.
+     */
+    on(type: string, handler: MessageHandler, options?: {
+        scope?: string;
+    }): () => void;
+    readonly fragmentId: string;
+    readonly instance: string;
+    readonly closed: AbortSignal;
+    close(): void;
+}
+export interface CreateChannelOptions {
+    backing: ChannelBacking;
+    fragmentId: string;
+    instance: string;
+    /** Closing the channel when the fragment instance is disposed. */
+    signal?: AbortSignal;
+    /** Default deadline for `request`. */
+    defaultTimeoutMs?: number;
+}
+export declare function createBoundaryChannel(options: CreateChannelOptions): BoundaryChannel;