@braidlabs/core 0.7.0 → 0.8.0

package/src/realm/sandbox-realm.js

@@ -16,7 +16,7 @@ import { BraidError } from '../errors.js';
  * | --- | --- | --- |
  * | 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 |
+ * | cookies/storage | the host's | none: an opaque origin has no cookies, Web Storage or IndexedDB |
  * | composition | gateway namespaces, piercing, compat facade | none of it applies |
  *
  * **Why this is not a `RealmHandle`.** That interface exposes `window`, `document`, `evaluate()`
@@ -45,7 +45,51 @@ export const DEFAULT_SANDBOX_TOKENS = ['allow-scripts', 'allow-forms'];
  * 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 TOP_NAVIGATION_HINT = 'use "allow-top-navigation-by-user-activation" if the fragment genuinely needs to navigate the page';
+const REFUSED_SANDBOX_TOKENS = new Map([
+    ['allow-top-navigation', TOP_NAVIGATION_HINT],
+    ['allow-top-navigation-to-custom-protocols', TOP_NAVIGATION_HINT],
+    /**
+     * The same navigation by another door: a popup that escapes the sandbox can set
+     * `window.opener.top.location` and swap the host page for a lookalike.
+     */
+    [
+        'allow-popups-to-escape-sandbox',
+        '"allow-popups" alone lets the fragment open windows; they stay sandboxed, which is the point',
+    ],
+    /**
+     * The token that turns the sandbox off. With it the frame keeps a real origin: a `javascript:`
+     * src, or a navigation to a URL on the host's origin, then runs with the host's own authority.
+     * The handshake works without it, so nothing on this tier needs it.
+     */
+    [
+        'allow-same-origin',
+        'leave it out: the untrusted tier connects from an opaque origin, which is what keeps it isolated',
+    ],
+]);
+/**
+ * Every token the HTML standard defines. Anything else is refused rather than passed through: the
+ * browser ignores a token it does not know, so a typo would silently grant less than intended — or,
+ * as browsers add tokens, silently grant something nobody reviewed.
+ */
+const KNOWN_SANDBOX_TOKENS = new Set([
+    'allow-downloads',
+    'allow-forms',
+    'allow-modals',
+    'allow-orientation-lock',
+    'allow-pointer-lock',
+    'allow-popups',
+    'allow-popups-to-escape-sandbox',
+    'allow-presentation',
+    'allow-same-origin',
+    'allow-scripts',
+    'allow-storage-access-by-user-activation',
+    'allow-top-navigation',
+    'allow-top-navigation-by-user-activation',
+    'allow-top-navigation-to-custom-protocols',
+]);
+/** Loopback hosts, where plain `http:` is how local development serves a second origin. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const LOAD_TIMEOUT_MS = 15_000;
 /**
  * Refuses a same-origin URL for the untrusted tier.
@@ -69,6 +113,20 @@ export function assertCrossOrigin(src, fragmentId) {
             fixHint: 'untrusted fragments are addressed by absolute url, e.g. src="https://vendor.example.com/widget"',
         });
     }
+    /**
+     * Only a network scheme can name another origin. `javascript:`, `data:` and `blob:` have an
+     * opaque origin, which never equals the host's, so the comparison below would wave them through
+     * — and a `javascript:` src in a frame granted `allow-same-origin` runs in the host's origin.
+     */
+    const secure = url.protocol === 'https:';
+    const loopback = url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
+    if (!secure && !loopback) {
+        throw new BraidError(`the untrusted tier loads fragments over https, and "${src}" is not an https url`, {
+            fragmentId,
+            stage: 'slot-config',
+            fixHint: 'serve the fragment from its own https origin; plain http is accepted only on localhost',
+        });
+    }
     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,
@@ -82,12 +140,23 @@ export function assertCrossOrigin(src, fragmentId) {
 /** 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)) {
+    // The browser splits the attribute on whitespace and matches tokens case-insensitively, so this
+    // must too — or "ALLOW-TOP-NAVIGATION" and "allow-popups allow-top-navigation" slip past.
+    const normalized = requested.flatMap((entry) => String(entry).toLowerCase().split(/\s+/).filter(Boolean));
+    for (const token of normalized) {
+        if (!KNOWN_SANDBOX_TOKENS.has(token)) {
+            throw new BraidError(`"${token}" is not a sandbox token`, {
+                fragmentId,
+                stage: 'slot-config',
+                fixHint: 'sandbox tokens are the allow-* keywords the HTML standard defines, e.g. "allow-popups"',
+            });
+        }
+        const refusal = REFUSED_SANDBOX_TOKENS.get(token);
+        if (refusal !== undefined) {
             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`,
+                fixHint: refusal,
             });
         }
         tokens.add(token);
@@ -97,11 +166,9 @@ export function resolveSandboxTokens(requested = [], fragmentId) {
 /**
  * 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.
+ * The guest announces itself and the host answers that window with the port. The host listens
+ * before the frame is attached, so there is no ordering to race: however fast the guest's script
+ * runs, its announcement finds a listener.
  */
 export async function createSandboxRealm(init) {
     const { fragmentId, src, container, signal } = init;
@@ -109,7 +176,9 @@ export async function createSandboxRealm(init) {
     const tokens = resolveSandboxTokens(init.sandboxTokens, fragmentId);
     const instance = `${fragmentId}:${Date.now().toString(36)}`;
     const frame = document.createElement('iframe');
-    frame.src = src;
+    // The absolute URL that was checked, not the string: `src` would resolve against
+    // `document.baseURI`, which a `<base>` element can point somewhere `location.href` does not.
+    frame.src = new URL(src, location.href).href;
     frame.setAttribute('sandbox', tokens.join(' '));
     frame.setAttribute('part', 'frame');
     frame.style.cssText = 'display:block;border:0;width:100%;height:100%';
@@ -125,53 +194,50 @@ export async function createSandboxRealm(init) {
     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;
+    /**
+     * The guest speaks first, and the host answers that window and no other.
+     *
+     * A sandboxed frame without `allow-same-origin` has an opaque origin. A message targeted at the
+     * fragment's origin is never delivered to it, and its own messages arrive with origin `"null"`.
+     * The origin cannot identify it, so the window does: `event.source` is set by the browser, and
+     * only this frame's window can be `frame.contentWindow`. The reply goes to that window with `'*'`,
+     * the only target an opaque origin accepts. It reaches whichever document the frame holds when it
+     * arrives, which is the one that asked unless the frame navigated in between. Only the frame
+     * itself can navigate it, so any document it lands on is the vendor's choice and as trusted as the
+     * vendor.
+     */
     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)
+        if (event.source === null || event.source !== frame.contentWindow)
+            return;
+        if (event.origin !== 'null')
             return;
         if (event.data?.braid !== SANDBOX_READY)
             return;
         if (connected)
             return;
         connected = true;
-        post();
+        const message = { braid: SANDBOX_CONNECT, v: 1, fragmentId, instance };
+        event.source.postMessage(message, '*', [channel.port2]);
         resolve();
     };
+    // Listening before the frame exists, so a guest that announces itself at once is not missed.
     window.addEventListener('message', onWindowMessage);
-    const onLoad = () => {
-        if (connected)
-            return;
-        connected = true;
-        post();
-        resolve();
-    };
-    frame.addEventListener('load', onLoad, { once: true });
+    container.append(frame);
     const timeout = setTimeout(() => {
-        reject(new BraidError(`the untrusted fragment at "${src}" did not load within ${init.loadTimeoutMs ?? LOAD_TIMEOUT_MS}ms`, {
+        reject(new BraidError(`the untrusted fragment at "${src}" did not connect 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',
+            stage: 'handshake',
+            fixHint: `the fragment must call connectToBraidHost({ hostOrigin: '${location.origin}' }). Its frame runs in an opaque ` +
+                'origin, so its module scripts need Access-Control-Allow-Origin. Also check that its origin does not refuse ' +
+                'framing via X-Frame-Options or CSP frame-ancestors',
         }));
     }, init.loadTimeoutMs ?? LOAD_TIMEOUT_MS);
     try {
@@ -180,7 +246,6 @@ export async function createSandboxRealm(init) {
     finally {
         clearTimeout(timeout);
         window.removeEventListener('message', onWindowMessage);
-        frame.removeEventListener('load', onLoad);
     }
     return {
         kind: 'sandbox',

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

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

package/src/trusted-types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Braid's own writes into the sinks Trusted Types guards, for a host page that enforces them
+ * (`require-trusted-types-for 'script'`).
+ *
+ * The runtime writes to a handful of sinks itself: it parses the markup the gateway prepared, it
+ * marks a script as already started by giving it a line of text, and the opt-in HTML policy
+ * parses a fragment's write into an inert document before cleaning it. Under enforcement each of
+ * those needs a trusted value, so they go through one policy, named `braid`, which a host lists in
+ * its `trusted-types` directive.
+ *
+ * The policy passes values through unchanged, which is why it is never exported: only these call
+ * sites can reach it, and each one either writes something Braid authored or parses into a
+ * document where nothing runs. Everything a fragment writes itself still meets the host's own
+ * enforcement — which is the point of turning it on.
+ *
+ * Created on first use, in whichever realm the write happens: a realm document inherits the host's
+ * policy, and a trusted value is checked against the realm that writes it.
+ */
+/** Markup Braid parses: the gateway's prepared document, or a write it is about to clean. */
+export declare function trustedHTML(markup: string, realm?: object): string;
+/** Script text Braid writes itself. */
+export declare function trustedScript(source: string, realm?: object): string;
+/**
+ * Creates the host's policy now, if the page has Trusted Types. Called by `initBraid`, before any
+ * fragment code runs: what the host's directive grants is the name `braid`, so it must be Braid's
+ * before anything else on the page can create it.
+ */
+export declare function claimBraidPolicy(): void;

package/src/trusted-types.js

@@ -0,0 +1,58 @@
+/**
+ * Braid's own writes into the sinks Trusted Types guards, for a host page that enforces them
+ * (`require-trusted-types-for 'script'`).
+ *
+ * The runtime writes to a handful of sinks itself: it parses the markup the gateway prepared, it
+ * marks a script as already started by giving it a line of text, and the opt-in HTML policy
+ * parses a fragment's write into an inert document before cleaning it. Under enforcement each of
+ * those needs a trusted value, so they go through one policy, named `braid`, which a host lists in
+ * its `trusted-types` directive.
+ *
+ * The policy passes values through unchanged, which is why it is never exported: only these call
+ * sites can reach it, and each one either writes something Braid authored or parses into a
+ * document where nothing runs. Everything a fragment writes itself still meets the host's own
+ * enforcement — which is the point of turning it on.
+ *
+ * Created on first use, in whichever realm the write happens: a realm document inherits the host's
+ * policy, and a trusted value is checked against the realm that writes it.
+ */
+const POLICY_NAME = 'braid';
+const policies = new WeakMap();
+function policyFor(realm) {
+    if (policies.has(realm))
+        return policies.get(realm) ?? null;
+    const factory = realm.trustedTypes;
+    let policy = null;
+    if (factory) {
+        try {
+            const same = (input) => input;
+            policy = factory.createPolicy(POLICY_NAME, { createHTML: same, createScript: same });
+        }
+        catch (error) {
+            // Not listed in the host's `trusted-types` directive, or the name already taken — by a second
+            // copy of the runtime, or by script that ran first. Writes go as plain strings and enforcement
+            // reports them; the warning says which.
+            console.warn(`[braid] could not create the "${POLICY_NAME}" Trusted Types policy: ${error?.message ?? error}`);
+            policy = null;
+        }
+    }
+    policies.set(realm, policy);
+    return policy;
+}
+/** Markup Braid parses: the gateway's prepared document, or a write it is about to clean. */
+export function trustedHTML(markup, realm = globalThis) {
+    return policyFor(realm)?.createHTML(markup) ?? markup;
+}
+/** Script text Braid writes itself. */
+export function trustedScript(source, realm = globalThis) {
+    return policyFor(realm)?.createScript(source) ?? source;
+}
+/**
+ * Creates the host's policy now, if the page has Trusted Types. Called by `initBraid`, before any
+ * fragment code runs: what the host's directive grants is the name `braid`, so it must be Braid's
+ * before anything else on the page can create it.
+ */
+export function claimBraidPolicy() {
+    policyFor(globalThis);
+}
+//# sourceMappingURL=trusted-types.js.map

package/src/trusted-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-types.js","sourceRoot":"","sources":["../../../../libs/core/src/trusted-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,MAAM,WAAW,GAAG,OAAO,CAAC;AAC5B,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAoC,CAAC;AAEjE,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IAC5D,MAAM,OAAO,GAAI,KAA4B,CAAC,YAAY,CAAC;IAC3D,IAAI,MAAM,GAA6B,IAAI,CAAC;IAC5C,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC;YACtC,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACvF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,8FAA8F;YAC9F,+FAA+F;YAC/F,wCAAwC;YACxC,OAAO,CAAC,IAAI,CAAC,iCAAiC,WAAW,2BAA4B,KAAe,EAAE,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC;YAC1H,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAgB,UAAU;IACpE,OAAQ,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,MAAM,CAAwB,IAAI,MAAM,CAAC;AAChF,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,QAAgB,UAAU;IACtE,OAAQ,SAAS,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,MAAM,CAAwB,IAAI,MAAM,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,SAAS,CAAC,UAAU,CAAC,CAAC;AACxB,CAAC"}

package/src/weave/capabilities.d.ts

@@ -48,7 +48,9 @@ export interface FragmentCapabilities {
      * Whose Web Storage the fragment sees. `'shared'` (the default) is the host origin's, as for any
      * same-origin frame. `'partitioned'` gives it a store of its own, keyed by fragment id;
      * `{ partition }` names a store several fragments share. See `compat/storage-partition.ts`.
-     * Compat fragments only; ignored elsewhere.
+     * `{ databases: true }` (with or without `partition`) also gives the partition its own
+     * IndexedDB and Cache Storage — a Storage Bucket where the browser has them, prefixed names
+     * elsewhere. See `compat/database-partition.ts`. Compat fragments only; ignored elsewhere.
      */
     storage?: StorageGrant;
     /**
@@ -75,7 +77,9 @@ export interface FragmentCapabilities {
  * 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;
+export declare function createContextGate(capabilities: FragmentCapabilities | undefined, fragmentId: string, options?: {
+    untrusted?: boolean;
+}): (key: string) => boolean;
 /**
  * Resolves capabilities from the three places a host can write them, most authoritative first:
  *
@@ -100,7 +104,8 @@ export declare function resolveCapabilities(sources: Array<FragmentCapabilities
 export declare function resolveSharedGlobals(capabilities: FragmentCapabilities | undefined): readonly string[];
 /** A fragment's Web Storage grant. */
 export type StorageGrant = 'shared' | 'partitioned' | {
-    partition: string;
+    partition?: string;
+    databases?: boolean;
 };
 /**
  * The storage partition a fragment writes into, or `null` for the shared, host-origin store.
@@ -109,5 +114,7 @@ export type StorageGrant = 'shared' | 'partitioned' | {
  * two partitioned forms is the shared default — a typo must not quietly move a fragment's data.
  */
 export declare function resolveStoragePartition(capabilities: FragmentCapabilities | undefined, fragmentId: string): string | null;
+/** The partition whose IndexedDB and Cache Storage a fragment gets, or `null` for the origin's. */
+export declare function resolveDatabasePartition(capabilities: FragmentCapabilities | undefined, fragmentId: string): string | null;
 /** 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

@@ -11,8 +11,14 @@ import { getBraidConfig, isDevMode } from '../config.js';
  * 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;
+export function createContextGate(capabilities, fragmentId, options = {}) {
+    /**
+     * No grant means everything for a trusted fragment, which already holds the user's session, so
+     * that adding capabilities to one fragment does not starve the rest. An untrusted fragment is the
+     * opposite case: forgetting its grant must not hand a third party the user, the tenant and every
+     * token the host publishes, so it gets nothing until a grant names what it may read.
+     */
+    const read = capabilities?.context?.read ?? (options.untrusted ? [] : undefined);
     if (!read)
         return () => true;
     const granted = new Set(read);
@@ -75,12 +81,22 @@ export function resolveStoragePartition(capabilities, fragmentId) {
     if (grant === 'partitioned')
         return fragmentId;
     if (grant && typeof grant === 'object') {
-        const partition = grant.partition;
+        const { partition, databases } = grant;
         if (typeof partition === 'string' && partition !== '')
             return partition;
+        // databases of its own imply a partition of its own, named for the fragment as 'partitioned' is
+        if (databases === true && partition === undefined)
+            return fragmentId;
     }
     return null;
 }
+/** The partition whose IndexedDB and Cache Storage a fragment gets, or `null` for the origin's. */
+export function resolveDatabasePartition(capabilities, fragmentId) {
+    const grant = capabilities?.storage;
+    if (!grant || typeof grant !== 'object' || grant.databases !== true)
+        return null;
+    return resolveStoragePartition(capabilities, fragmentId);
+}
 /** Reads a capabilities block off a realm stub's adapter options, or off `initBraid` config. */
 export function readCapabilities(source) {
     if (!source || typeof source !== 'object')

package/src/weave/capabilities.js.map

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

package/src/weave/context-bridge.d.ts

@@ -59,6 +59,8 @@ export interface AttachContextRouterOptions {
      * subscription that never fires.
      */
     capabilities?: FragmentCapabilities;
+    /** An untrusted fragment with no `context.read` grant reads nothing, not everything. */
+    untrusted?: boolean;
     signal: AbortSignal;
 }
 /**

package/src/weave/context-bridge.js

@@ -31,7 +31,7 @@ export const CTX_CHANGED = 'ctx/changed';
  */
 export function attachContextRouter(options) {
     const { bus, channel, fragmentId, contextVersions, signal } = options;
-    const mayRead = createContextGate(options.capabilities, fragmentId);
+    const mayRead = createContextGate(options.capabilities, fragmentId, { untrusted: options.untrusted === true });
     const readFor = (key) => {
         const as = contextVersions[key];
         try {

package/src/weave/context-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-bridge.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/context-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context-bridge.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/context-bridge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAyCzC;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACtE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,YAAY,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC,CAAC;IAE/G,MAAM,OAAO,GAAG,CAAC,GAAW,EAAgD,EAAE;QAC5E,MAAM,EAAE,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QAChG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf;;;;;;;eAOG;YACH,OAAO,CAAC,KAAK,CAAC,UAAU,UAAU,cAAc,GAAG,4CAA4C,EAAE,KAAK,CAAC,CAAC;YACxG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,IAAI,CAAC,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1C,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACpC,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO;QAE3B;;;;;;;;WAQG;QACH,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO;QAE1B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B;;;;WAIG;QACH,MAAM,OAAO,GAA0B,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACtF,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACzG,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAwB,EACxB,KAAc;IAEd,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyC,CAAC;IAEnE;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE;QAClC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAA0B,CAAC;QAChE,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO;QAEpC,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;;YACvC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE5B,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACvD,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,mFAAmF;gBACnF,+EAA+E;gBAC/E,OAAO,CAAC,KAAK,CAAC,aAAa,GAAG,+DAA+D,EAAE,KAAK,CAAC,CAAC;YACxG,CAAC;QACH,CAAC;IACH,CAAC,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAEhD,OAAO;QACL,IAAI,CAAC,IAAiB;YACpB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxF,CAAC;QAED,GAAG,CAAC,GAAW;YACb,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QAED,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,gBAAgB;YACvC,IAAI,gBAAgB,EAAE,MAAM,EAAE,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;YACxF,IAAI,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,YAAY,GAAG,IAAI,GAAG,EAAE,CAAC;gBACzB,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YACnC,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAE3B,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,KAAK,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7D,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACjF,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAEtE,8FAA8F;YAC9F,mCAAmC;YACnC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC,gBAAgB,EAAE,MAAM,IAAI,IAAI,CAAC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAChE,IAAI,CAAC;oBACH,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACpB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,KAAK,CAAC,aAAa,GAAG,sCAAsC,EAAE,KAAK,CAAC,CAAC;gBAC/E,CAAC;YACH,CAAC;YACD,OAAO,WAAW,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/weave/guest.d.ts

@@ -32,6 +32,8 @@ export interface GuestSession {
     onPropsChanged(listener: (props: Readonly<Record<string, unknown>>) => void): () => void;
     /** Fragment → host. Surfaced on the slot element as `braid:event`. */
     emit(type: string, detail?: unknown): void;
+    /** Reports the fragment's first content as settled; see `FragmentEnv.settled`. */
+    settled(): void;
     onClosing: ClosingCoordinator['onClosing'];
     setDirty: ClosingCoordinator['setDirty'];
     /** Aborts when the host closes the session. */

package/src/weave/guest.js

@@ -6,7 +6,7 @@ import { createContextMirror } from './context-bridge.js';
 import { createClosingCoordinator } from './closing.js';
 import { answerHandshake } from './handshake.js';
 import { startFragmentBeats } from './liveness.js';
-import { FRAGMENT_EVENT, PROPS_CHANGED } from './messages.js';
+import { FRAGMENT_EVENT, PROPS_CHANGED, SETTLED } from './messages.js';
 const CONNECT_TIMEOUT_MS = 15_000;
 /** Waits for a host to offer a port, then completes the Weave handshake over it. */
 export async function connectToBraidHost(options) {
@@ -70,6 +70,7 @@ export async function connectToBraidHost(options) {
             return () => void propsListeners.delete(listener);
         },
         emit: (type, detail) => channel.send(FRAGMENT_EVENT, { type, detail }),
+        settled: () => channel.send(SETTLED),
         onClosing: closing.onClosing,
         setDirty: closing.setDirty,
         signal: controller.signal,
@@ -84,6 +85,10 @@ function acceptConnection(hostOrigin, timeoutMs) {
         // the sender, which is what makes it worth checking and `event.data` worth distrusting.
         if (event.origin !== hostOrigin)
             return;
+        // And from the page that framed this one: another window on the host's origin, such as a
+        // trusted fragment's realm or a popup, must not be able to hand this fragment a channel.
+        if (event.source !== window.parent)
+            return;
         const data = event.data;
         if (data?.braid !== SANDBOX_CONNECT)
             return;
@@ -107,11 +112,11 @@ function acceptConnection(hostOrigin, timeoutMs) {
     }
     window.addEventListener('message', onMessage);
     /**
-     * Announced *after* the listener is attached, so the two orderings converge.
+     * Announced *after* the listener is attached, because the host answers at once.
      *
-     * The host posts on the frame's `load` event, which may fire before this module has even been
-     * evaluated. Announcing tells a host that already gave up waiting to post again; attaching first
-     * means a host that posted immediately is not missed either.
+     * The announcement is what connects: this frame runs in an opaque origin, which the host cannot
+     * address by name, so it replies to the window that announced itself. The target origin still
+     * pins the host — a page that framed this one from any other origin never receives it.
      */
     const ready = { braid: SANDBOX_READY, v: 1 };
     window.parent?.postMessage(ready, hostOrigin);

package/src/weave/guest.js.map

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

package/src/weave/messages.d.ts

@@ -25,3 +25,27 @@ export interface FragmentEventPayload {
     type: string;
     detail?: unknown;
 }
+/**
+ * Fragment → host. The fragment's first content has settled: its own loading is done, not just its
+ * mount. Surfaced on the slot as the `settled` attribute and a `braid:settled` event.
+ *
+ * Separate from liveness on purpose. `healthy` proves the realm's event loop is turning, which is
+ * true from the first beat — while the application inside may still be showing its own spinner. Only
+ * the fragment knows when it has something worth looking at, so this is the fragment's to say, once.
+ */
+export declare const SETTLED = "frag/settled";
+/**
+ * Where a compat fragment finds its reporter: on its realm's global, under a registered symbol.
+ *
+ * A compat fragment is an unmodified app that never receives an env, so the one thing it may want
+ * to say has to be reachable from a global. A registered symbol rather than a name: it collides with
+ * nothing the app defines, and every copy of `@braidlabs/core` — the host's, and any bundled into
+ * the fragment — resolves the same one.
+ */
+export declare const BRAID_FRAGMENT_REPORTER: unique symbol;
+export interface BraidFragmentReporter {
+    /** Reports the fragment's first content as settled. Later calls do nothing. */
+    settled(): void;
+}
+/** The reporter the realm this code runs in was given, or undefined outside a Braid realm. */
+export declare function braidFragmentReporter(): BraidFragmentReporter | undefined;

package/src/weave/messages.js

@@ -10,4 +10,26 @@
 export const PROPS_CHANGED = 'props/changed';
 /** Fragment → host. Surfaced on the slot element as `braid:event`. */
 export const FRAGMENT_EVENT = 'frag/event';
+/**
+ * Fragment → host. The fragment's first content has settled: its own loading is done, not just its
+ * mount. Surfaced on the slot as the `settled` attribute and a `braid:settled` event.
+ *
+ * Separate from liveness on purpose. `healthy` proves the realm's event loop is turning, which is
+ * true from the first beat — while the application inside may still be showing its own spinner. Only
+ * the fragment knows when it has something worth looking at, so this is the fragment's to say, once.
+ */
+export const SETTLED = 'frag/settled';
+/**
+ * Where a compat fragment finds its reporter: on its realm's global, under a registered symbol.
+ *
+ * A compat fragment is an unmodified app that never receives an env, so the one thing it may want
+ * to say has to be reachable from a global. A registered symbol rather than a name: it collides with
+ * nothing the app defines, and every copy of `@braidlabs/core` — the host's, and any bundled into
+ * the fragment — resolves the same one.
+ */
+export const BRAID_FRAGMENT_REPORTER = Symbol.for('braid.fragment');
+/** The reporter the realm this code runs in was given, or undefined outside a Braid realm. */
+export function braidFragmentReporter() {
+    return globalThis[BRAID_FRAGMENT_REPORTER];
+}
 //# sourceMappingURL=messages.js.map

package/src/weave/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC"}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAmB3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAOpE,8FAA8F;AAC9F,MAAM,UAAU,qBAAqB;IACnC,OAAQ,UAAgE,CAAC,uBAAuB,CAAC,CAAC;AACpG,CAAC"}