@braidlabs/gateway 0.6.0 → 0.7.0

package/README.md

@@ -173,6 +173,12 @@ as a declarative shadow root, so the browser parses it into exactly the shape th
 would have built; the slot then adopts it instead of fetching. Shells with no matching slot get
 one created before `</body>`.
 
+The stream waits at a slot whose fragment has not answered yet, so a slow fragment holds back the
+markup after it, for up to its `timeoutMs`. Set `stream: 'out-of-order'` on its manifest to stream
+past the slot instead: the slot is marked `data-braid-deferred`, and the fragment's markup follows
+before `</body>` in a hidden `<braid-late>` that the client moves into it. A fragment that answered
+in time is inlined as usual. See the [gateway docs](../../docs/packages/gateway.md#streaming-past-a-slow-fragment).
+
 A shell can instead mark one `<fragment-slot outlet>`. It takes the page's routed (bound) fragment,
 the first in registration order that no earlier named slot claimed, and is named after it. A shell
 that composes many routes then needs one slot rather than one per fragment id. Unbound widgets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braidlabs/gateway",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Braid gateway — fetch-native origin-front middleware that routes fragment traffic by exact id under the reserved /__braid/frag/ namespace, loads fragment manifests, and passes everything else through to your existing app.",
   "keywords": [
     "micro-frontends",

package/src/baggage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * W3C `baggage` for fragment requests, safely.
+ *
+ * Baggage is arbitrary key/value context that rides alongside a trace — a tenant, an experiment,
+ * a feature flag — and that is the problem with a browser's: a header any page script or extension
+ * can set, flowing into every internal service behind every fragment. `new Request(url, request)`
+ * used to copy it verbatim. Now a fragment request carries baggage only as the deployment allows:
+ *
+ * - inbound members are dropped unless their key is allowlisted, their value is well formed (W3C
+ *   baggage octets, valid percent-encoding), and, when the allowlist gives a pattern, their decoded
+ *   value matches it in full; member properties are dropped;
+ * - members the gateway sets itself win over a client's with the same key;
+ * - anything over the W3C limits (8192 bytes, 180 members) is dropped whole, as is a header that
+ *   cannot be parsed;
+ * - and only fragments inside the deployment's trust boundary get any, by the same rule as
+ *   `forwardCredentials` — decided by the caller.
+ */
+export interface BaggageOptions {
+    /**
+     * Inbound members a fragment may receive: keys, or keys mapped to a pattern their decoded value
+     * must match in full. Absent: none.
+     */
+    forward?: readonly string[] | Readonly<Record<string, RegExp>>;
+    /**
+     * Members the gateway adds to the request for one fragment, overriding a client's with the same
+     * key. Values are percent-encoded for you.
+     */
+    set?: (request: Request, fragmentId: string) => Record<string, string>;
+}
+/**
+ * The `baggage` header a fragment request carries, or `null` for none. The caller decides whether
+ * the fragment is inside the trust boundary at all; call this only for one that is.
+ */
+export declare function fragmentBaggage(request: Request, options: BaggageOptions | undefined, fragmentId: string): string | null;

package/src/baggage.js

@@ -0,0 +1,93 @@
+/**
+ * W3C `baggage` for fragment requests, safely.
+ *
+ * Baggage is arbitrary key/value context that rides alongside a trace — a tenant, an experiment,
+ * a feature flag — and that is the problem with a browser's: a header any page script or extension
+ * can set, flowing into every internal service behind every fragment. `new Request(url, request)`
+ * used to copy it verbatim. Now a fragment request carries baggage only as the deployment allows:
+ *
+ * - inbound members are dropped unless their key is allowlisted, their value is well formed (W3C
+ *   baggage octets, valid percent-encoding), and, when the allowlist gives a pattern, their decoded
+ *   value matches it in full; member properties are dropped;
+ * - members the gateway sets itself win over a client's with the same key;
+ * - anything over the W3C limits (8192 bytes, 180 members) is dropped whole, as is a header that
+ *   cannot be parsed;
+ * - and only fragments inside the deployment's trust boundary get any, by the same rule as
+ *   `forwardCredentials` — decided by the caller.
+ */
+const MAX_BYTES = 8192;
+const MAX_MEMBERS = 180;
+/** RFC 7230 token, which is what a baggage key is. */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** A value as it may appear on the wire: W3C baggage-octets, anything else percent-encoded. */
+const VALUE = /^[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*$/;
+const encoder = new TextEncoder();
+/**
+ * Each pattern, anchored around its whole source — an unanchored `/eu|us/` must not pass `euw`, nor
+ * `/a|ab/` fail `ab` — and without the flags that make a RegExp stateful (`g`, `y`) or let `^`/`$`
+ * match inside a value (`m`).
+ */
+const anchored = new WeakMap();
+function matchesWhole(pattern, value) {
+    let whole = anchored.get(pattern);
+    if (!whole) {
+        whole = new RegExp(`^(?:${pattern.source})$`, pattern.flags.replace(/[gmy]/g, ''));
+        anchored.set(pattern, whole);
+    }
+    return whole.test(value);
+}
+function allowedValue(forward, key, rawValue) {
+    if (!forward || !VALUE.test(rawValue))
+        return false;
+    let value;
+    try {
+        value = decodeURIComponent(rawValue);
+    }
+    catch {
+        return false;
+    }
+    if (Array.isArray(forward))
+        return forward.includes(key);
+    const patterns = forward;
+    return Object.hasOwn(patterns, key) && matchesWhole(patterns[key], value);
+}
+/**
+ * The `baggage` header a fragment request carries, or `null` for none. The caller decides whether
+ * the fragment is inside the trust boundary at all; call this only for one that is.
+ */
+export function fragmentBaggage(request, options, fragmentId) {
+    const members = new Map();
+    const inbound = request.headers.get('baggage');
+    if (inbound && options?.forward && encoder.encode(inbound).length <= MAX_BYTES) {
+        for (const part of inbound.split(',')) {
+            const member = part.trim();
+            if (!member)
+                continue;
+            // properties (`;prop=…`) are dropped: nothing downstream asked for them
+            const [pair] = member.split(';');
+            const separator = pair.indexOf('=');
+            if (separator <= 0)
+                continue;
+            const key = pair.slice(0, separator).trim();
+            const value = pair.slice(separator + 1).trim();
+            if (!TOKEN.test(key) || !allowedValue(options.forward, key, value))
+                continue;
+            members.set(key, value);
+        }
+    }
+    for (const [key, value] of Object.entries(options?.set?.(request, fragmentId) ?? {})) {
+        if (!TOKEN.test(key))
+            continue;
+        try {
+            members.set(key, encodeURIComponent(value));
+        }
+        catch {
+            // a lone surrogate has no encoding; the member is dropped rather than failing the request
+        }
+    }
+    if (members.size === 0 || members.size > MAX_MEMBERS)
+        return null;
+    const header = [...members].map(([key, value]) => `${key}=${value}`).join(',');
+    return encoder.encode(header).length <= MAX_BYTES ? header : null;
+}
+//# sourceMappingURL=baggage.js.map

package/src/baggage.js.map

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

package/src/cookie-scope.d.ts

@@ -0,0 +1,41 @@
+import type { FragmentManifest } from './registry.js';
+/**
+ * The partition a fragment's cookies and storage live in, or `null` for the shared origin.
+ *
+ * Compat fragments only, as on the client: a custom-element or contract fragment runs in the host
+ * window, where nothing would show it its cookies under their own names again.
+ */
+export declare function storagePartitionOf(fragment: Pick<FragmentManifest, 'id' | 'capabilities' | 'adapter'>): string | null;
+/**
+ * `braid$<partition>$`, with the partition percent-encoded so it is a valid cookie-name token
+ * (RFC 6265) and can never contain the `$` that ends it.
+ */
+export declare function cookieScopePrefix(partition: string): string;
+/** Whether a cookie name is in any fragment's scope. Nothing legitimate starts with the mark. */
+export declare function isScopedCookieName(name: string): boolean;
+/**
+ * One `Set-Cookie` line, moved into the partition's scope.
+ *
+ * The name gains the scope; `Domain` is dropped, so the cookie is host-only; `Path` becomes `/`,
+ * so it still arrives on page requests and a pierced fragment can be rendered signed-in. Every
+ * other attribute is kept. A name that already looks scoped is scoped again, so an endpoint can
+ * never set a cookie in another fragment's scope.
+ */
+export declare function scopeSetCookie(line: string, partition: string): string;
+/**
+ * The `Cookie` header a partitioned fragment's endpoint receives: its own cookies under the names
+ * its endpoint gave them, plus — only when `includeHost` (the deployment's `forwardCredentials`
+ * rule) — the host's unscoped cookies. Never another fragment's. `null` when nothing is left.
+ */
+export declare function scopeRequestCookies(header: string | null, partition: string, includeHost: boolean): string | null;
+/**
+ * The caller's cookies for a *shared* fragment under `forwardCredentials`: everything but the
+ * partitioned fragments' scoped cookies, which belong to their own fragments alone.
+ */
+export declare function withoutScopedCookies(header: string | null): string | null;
+/**
+ * Rewrites every `Set-Cookie` on `headers` into the partition's scope, in place, and drops
+ * `Clear-Site-Data`, with which one fragment's logout would wipe every other fragment's cookies
+ * and storage along with its own.
+ */
+export declare function scopeResponseCookies(headers: Headers, partition: string): void;

package/src/cookie-scope.js

@@ -0,0 +1,148 @@
+/**
+ * Per-fragment cookies for partitioned fragments: the server half of `capabilities.storage`.
+ *
+ * Trusted fragments share the host origin, and so its cookie jar. When fragments' backends finish
+ * an authorization-code login by setting a session cookie, two of them setting `session` with
+ * `Path=/` overwrite each other — and a gateway that forwards the caller's cookies hands every
+ * fragment every other fragment's session. For a partitioned fragment the gateway renames the
+ * cookies its endpoint sets into the partition's scope, and sends it only its own.
+ *
+ *     Set-Cookie: session=…            →  Set-Cookie: braid$orders$session=…; Path=/
+ *     Cookie: braid$orders$session=a; braid$billing$session=b; theme=dark
+ *                                      →  Cookie: session=a            (to orders)
+ *
+ * The partition is the one `capabilities.storage` names, so fragments that share Web Storage
+ * share cookies too. Fragments that do not opt in are untouched.
+ *
+ * The encoding is duplicated in `@braidlabs/core` (`compat/cookie-partition.ts`), which gives a
+ * partitioned realm the same view through `document.cookie`; e2e/cookie-scope.e2e.ts holds the two
+ * to each other.
+ */
+const SCOPE_MARK = 'braid$';
+/** Cookie-name prefixes the browser enforces, which must stay at the front of the name. */
+const BROWSER_PREFIXES = ['__Host-', '__Secure-'];
+/**
+ * The partition a fragment's cookies and storage live in, or `null` for the shared origin.
+ *
+ * Compat fragments only, as on the client: a custom-element or contract fragment runs in the host
+ * window, where nothing would show it its cookies under their own names again.
+ */
+export function storagePartitionOf(fragment) {
+    if ((fragment.adapter ?? 'compat') !== 'compat')
+        return null;
+    const grant = fragment.capabilities?.storage;
+    if (grant === 'partitioned')
+        return fragment.id;
+    if (grant && typeof grant === 'object') {
+        const partition = grant.partition;
+        if (typeof partition === 'string' && partition !== '')
+            return partition;
+    }
+    return null;
+}
+/**
+ * `braid$<partition>$`, with the partition percent-encoded so it is a valid cookie-name token
+ * (RFC 6265) and can never contain the `$` that ends it.
+ */
+export function cookieScopePrefix(partition) {
+    const encoded = encodeURIComponent(partition).replace(/[()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${SCOPE_MARK}${encoded}$`;
+}
+/** Splits off a `__Host-`/`__Secure-` prefix, matched without regard to case as browsers do. */
+function splitBrowserPrefix(name) {
+    const prefix = BROWSER_PREFIXES.find((candidate) => name.toLowerCase().startsWith(candidate.toLowerCase()));
+    return prefix ? [name.slice(0, prefix.length), name.slice(prefix.length)] : ['', name];
+}
+/** Whether a cookie name is in any fragment's scope. Nothing legitimate starts with the mark. */
+export function isScopedCookieName(name) {
+    return splitBrowserPrefix(name.trim())[1].startsWith(SCOPE_MARK);
+}
+function parseCookieHeader(header) {
+    return header
+        .split(';')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((cookie) => {
+        const separator = cookie.indexOf('=');
+        return { name: separator === -1 ? cookie : cookie.slice(0, separator), cookie };
+    });
+}
+/**
+ * One `Set-Cookie` line, moved into the partition's scope.
+ *
+ * The name gains the scope; `Domain` is dropped, so the cookie is host-only; `Path` becomes `/`,
+ * so it still arrives on page requests and a pierced fragment can be rendered signed-in. Every
+ * other attribute is kept. A name that already looks scoped is scoped again, so an endpoint can
+ * never set a cookie in another fragment's scope.
+ */
+export function scopeSetCookie(line, partition) {
+    const [pair, ...attributes] = line.split(';');
+    const separator = pair.indexOf('=');
+    // a cookie without a name (`=value`, or no `=`) is unusual enough to drop rather than guess at
+    if (separator <= 0)
+        return '';
+    const [browserPrefix, name] = splitBrowserPrefix(pair.slice(0, separator).trim());
+    const value = pair.slice(separator + 1);
+    const kept = attributes
+        .map((attribute) => attribute.trim())
+        .filter((attribute) => attribute !== '' && !/^(domain|path)\s*(=|$)/i.test(attribute));
+    return [`${browserPrefix}${cookieScopePrefix(partition)}${name}=${value}`, 'Path=/', ...kept].join('; ');
+}
+/**
+ * The `Cookie` header a partitioned fragment's endpoint receives: its own cookies under the names
+ * its endpoint gave them, plus — only when `includeHost` (the deployment's `forwardCredentials`
+ * rule) — the host's unscoped cookies. Never another fragment's. `null` when nothing is left.
+ */
+export function scopeRequestCookies(header, partition, includeHost) {
+    if (!header)
+        return null;
+    const own = cookieScopePrefix(partition);
+    const mine = [];
+    const mineNames = new Set();
+    const host = [];
+    for (const { name: rawName, cookie } of parseCookieHeader(header)) {
+        const [browserPrefix, name] = splitBrowserPrefix(rawName);
+        if (name.startsWith(own)) {
+            const ownName = `${browserPrefix}${name.slice(own.length)}`;
+            mine.push(`${ownName}${cookie.slice(rawName.length)}`);
+            mineNames.add(ownName);
+        }
+        else if (!name.startsWith(SCOPE_MARK) && includeHost) {
+            host.push({ name: rawName, cookie });
+        }
+    }
+    // the fragment's own cookie wins over a host cookie of the same name: parsers take the first
+    // occurrence, and the host's usually came first
+    const out = [...mine, ...host.filter(({ name }) => !mineNames.has(name)).map(({ cookie }) => cookie)];
+    return out.length > 0 ? out.join('; ') : null;
+}
+/**
+ * The caller's cookies for a *shared* fragment under `forwardCredentials`: everything but the
+ * partitioned fragments' scoped cookies, which belong to their own fragments alone.
+ */
+export function withoutScopedCookies(header) {
+    if (!header)
+        return null;
+    const out = parseCookieHeader(header)
+        .filter(({ name }) => !isScopedCookieName(name))
+        .map(({ cookie }) => cookie);
+    return out.length > 0 ? out.join('; ') : null;
+}
+/**
+ * Rewrites every `Set-Cookie` on `headers` into the partition's scope, in place, and drops
+ * `Clear-Site-Data`, with which one fragment's logout would wipe every other fragment's cookies
+ * and storage along with its own.
+ */
+export function scopeResponseCookies(headers, partition) {
+    headers.delete('clear-site-data');
+    const lines = headers.getSetCookie();
+    if (lines.length === 0)
+        return;
+    headers.delete('set-cookie');
+    for (const line of lines) {
+        const scoped = scopeSetCookie(line, partition);
+        if (scoped)
+            headers.append('set-cookie', scoped);
+    }
+}
+//# sourceMappingURL=cookie-scope.js.map

package/src/cookie-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-scope.js","sourceRoot":"","sources":["../../../../libs/braid-gateway/src/cookie-scope.ts"],"names":[],"mappings":"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"}

package/src/gateway.d.ts

@@ -1,6 +1,7 @@
 import { Principal, RegistryRefresh, RegistrySource, FragmentManifest } from './registry.js';
 import { DiscoveryOptions } from './discovery.js';
 import { type BreakerOptions } from './breaker.js';
+import { type BaggageOptions } from './baggage.js';
 import { type TelemetryOptions } from './telemetry.js';
 export interface GatewayOptions {
     /** The fragment registry: inline manifests, a JSON URL, or an async loader. */
@@ -65,6 +66,13 @@ export interface GatewayOptions {
      * throws forwards nothing. The same decision applies to websocket upgrades.
      */
     forwardCredentials?: boolean | ((fragment: FragmentManifest) => boolean);
+    /**
+     * W3C `baggage` for fragment requests. By default a fragment receives none: the browser's header
+     * is dropped rather than copied into every backend. Allowlist the inbound keys to keep, with an
+     * optional pattern for their values, and add members of the gateway's own. Only fragments that
+     * `forwardCredentials` allows receive any. See `baggage.ts`.
+     */
+    baggage?: BaggageOptions;
     /**
      * More request headers that carry the caller's identity, stripped alongside `cookie`,
      * `authorization` and `proxy-authorization` whenever {@link GatewayOptions.forwardCredentials}
@@ -121,6 +129,27 @@ export interface GatewayOptions {
      * `sec-fetch-dest` into the edge's cache key. See `docs/braid-cdn.md`.
      */
     pierceCacheControl?: 'private' | 'preserve';
+    /**
+     * Whether a fragment's `capabilities.network` is turned into a policy on its realm.
+     *
+     * By default the grant is advisory on the trusted tier: it documents intent and feeds the
+     * registry's analysis. With this set, the realm stub of every compat or custom-element fragment
+     * that declares one carries `connect-src 'self' <its origins>`:
+     *
+     * - `'report'` — as `Content-Security-Policy-Report-Only`. Nothing is blocked; the client logs
+     *   each request that would have been, under the fragment's name. Start here.
+     * - `'enforce'` — as `Content-Security-Policy`. The browser blocks the realm's own `fetch`, XHR,
+     *   WebSocket and EventSource requests to any other origin (and JSON module imports, which CSP
+     *   counts as connections).
+     *
+     * It governs what the fragment's realm does, not what the host document does: markup the
+     * fragment puts in the page is under the host's policy, and so is anything the realm calls on the
+     * host's behalf — `navigator.sendBeacon` (a compat realm's `navigator` is the host's), and any
+     * `sharedGlobals` client. Code that deliberately reaches into the host realm gets around it too. It is a tripwire for accidents and naive supply-chain
+     * exfiltration, not a security boundary — the trusted tier has none. Fragments that declare no
+     * `network` are untouched.
+     */
+    realmPolicy?: 'report' | 'enforce';
     /**
      * Called for every document request that reaches the shell, with which fragments composed into
      * it. This is what makes traffic-informed impact analysis possible: "after this change, 43 of
@@ -261,6 +290,24 @@ export interface UpgradeTarget {
     credentialHeaders: readonly string[];
     /** The `x-braid-via` value for the upstream request, this gateway's hop included. */
     via: string;
+    /**
+     * When present, the `Cookie` header the upgrade carries *instead of* the caller's (after the
+     * credential strip), or `null` for none: a partitioned fragment's own scoped cookies, or the
+     * caller's minus every partitioned fragment's (see cookie-scope.ts). A binding must apply it, or
+     * it forwards cookies that belong to other fragments.
+     */
+    cookie?: string | null;
+    /**
+     * For a partitioned fragment, rewrites a `Set-Cookie` line from the upstream's handshake response
+     * into the fragment's scope; an empty result means drop it. A binding must apply it to every
+     * `Set-Cookie` it relays to the browser.
+     */
+    setCookie?: (line: string) => string;
+    /**
+     * The `baggage` header the upgrade carries instead of the caller's, or `null` for none (see
+     * `GatewayOptions.baggage`). A binding must apply it: the caller's own is never forwarded as is.
+     */
+    baggage?: string | null;
 }
 /** What the gateway tells a `documents` hook about the registry it is serving right now. */
 export interface DocumentsContext {
@@ -290,7 +337,9 @@ export interface BraidGateway {
      *
      * A binding other than `toNodeUpgradeHandler` **must** remove `credentialHeaders` from the
      * upstream request when `forwardCredentials` is false, and set `x-braid-via` to `via` — the
-     * socket otherwise carries the user's identity past the boundary every fetch respects.
+     * socket otherwise carries the user's identity past the boundary every fetch respects. It must
+     * also replace `cookie` with `cookie` when the target carries one, and pass every `Set-Cookie`
+     * of the handshake response through `setCookie` when the target carries that.
      *
      * @returns the endpoint URL to dial, whether the caller's credentials may go with it (the same
      *          {@link GatewayOptions.forwardCredentials} rule as a fetch) and which headers carry