@braidlabs/gateway 0.1.1

package/src/registry.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Registry & manifests: the registry is data, not code. Fragments register via manifest
+ * documents; deploying a fragment never redeploys the gateway.
+ */
+/** How a fragment failure surfaces in a composed page. */
+export type FragmentFallback = 'omit' | 'placeholder' | 'error-html';
+/**
+ * `braid.manifest.json` — one per fragment.
+ */
+import type { FragmentAppdMetadata, FragmentFdc3Metadata } from './appd.js';
+export interface FragmentManifest {
+    /** Unique fragment id; addresses the fragment in the reserved namespace (`/__braid/frag/:id/*`). */
+    id: string;
+    /**
+     * The endpoint of the fragment application: a base URL, or a `fetch`-compatible function.
+     * Namespace requests are forwarded here with the namespace prefix stripped, so the endpoint
+     * sees the same paths it would serve standalone.
+     */
+    endpoint: string | typeof fetch;
+    /**
+     * The adapter the fragment runs under in the client. Defaults to `"compat"` — the contained
+     * web-fragments-style emulation layer — so legacy apps compose with zero app-code changes.
+     */
+    adapter?: string;
+    /** Contract version for contract-mode fragments (unused by the compat adapter). */
+    contractVersion?: string;
+    /** Module entry for contract-mode fragments (unused by the compat adapter). */
+    entry?: string;
+    /**
+     * For the `custom-element` adapter: the tag name the fragment's entry module defines.
+     *
+     * The fragment ships an ordinary custom element and knows nothing about Braid; this is how
+     * the gateway tells the client what to mount.
+     */
+    element?: string;
+    /**
+     * Route-pattern sugar: the page URLs whose server-rendered HTML this fragment is pierced
+     * into. Patterns are URLPattern pathname syntax (`/checkout/*`, `/orders/:id`).
+     *
+     * This is *only* the "which page URLs pierce which fragment" mapping — it is never the
+     * mechanism for asset or data routing, which is always exact and id-addressed.
+     */
+    pierce?: string[];
+    /**
+     * Whether this fragment renders the page's route.
+     *
+     * Defaults to `true`: a bound fragment is a screen, so it is fetched at the page's own path and
+     * participates in host navigation. `false` marks a widget — header chrome, a sidebar, a global
+     * search box — whose content lives at one fixed path regardless of which page it appears on.
+     */
+    bound?: boolean;
+    /**
+     * Where an unbound fragment's content lives, as a path on its own endpoint (`/panel`).
+     *
+     * Required in practice for `bound: false`, because the alternative is asking a notifications
+     * endpoint for `/billing/invoices` — a request that means nothing to it and that will, at best,
+     * 404 on every page the widget appears on.
+     */
+    src?: string;
+    /** Typed event surface for hosts. Reserved; not enforced by this build. */
+    events?: Record<string, {
+        detail: string;
+    }>;
+    /** Per-fragment budget for endpoint fetches, in milliseconds. */
+    timeoutMs?: number;
+    /**
+     * Opt this fragment out of concurrent-fetch coalescing. Defaults to `true` (coalesced).
+     *
+     * The gateway only shares a fetch between requests whose `cookie`, `authorization`, `user-agent`,
+     * and negotiation headers match, which covers how endpoints normally vary. Set this to `false`
+     * when yours varies on something the gateway cannot see — a tenant header, a feature-flag
+     * header, anything bespoke — because two such requests would otherwise look identical to it and
+     * share one render.
+     */
+    coalesce?: boolean;
+    /**
+     * What the gateway renders into the slot when this fragment can't be server-rendered.
+     *
+     * - `placeholder` (default) — the slot is left empty and marked `data-braid-fallback`, so the
+     *   page can style a skeleton. The client runtime then fetches the fragment itself, which
+     *   means a transient SSR failure self-heals instead of becoming a visible error.
+     * - `omit` — same, without the marker attribute.
+     * - `error-html` — the gateway renders an error into the slot. Choose this only when a
+     *   missing section is worse than a visible failure.
+     */
+    fallback?: FragmentFallback;
+    /** Compat-specific options. */
+    compat?: {
+        fidelity?: 'documented';
+        warnOnUnaudited?: boolean;
+    };
+    /** Human-readable name for discovery listings. Defaults to the id. */
+    title?: string;
+    /** One-line description for discovery listings. */
+    description?: string;
+    /** Free-form labels for filtering and grouping in discovery listings. */
+    tags?: string[];
+    /**
+     * FDC3 metadata: the intents this app handles and raises, and the channels it uses.
+     *
+     * Projected into the App Directory listing (see `appd.ts`). The runtime members —
+     * `apiVersion`, `contexts` — are reserved for the FDC3 work and unused by the gateway.
+     */
+    fdc3?: FragmentFdc3Metadata;
+    /**
+     * Descriptive fields the App Directory carries that the registry does not otherwise need —
+     * publisher, contact addresses, icons. Purely for listings.
+     */
+    appd?: FragmentAppdMetadata;
+    /**
+     * Who may list this fragment, and who may load it. Declared at registration, so a
+     * fragment's own team decides its exposure rather than every host re-deciding it.
+     *
+     * **Both are public by default.** Omit `access` entirely and anyone can discover and load the
+     * fragment; add only the rule you need. The two are independent: a fragment can be openly
+     * listed but restricted to load (visible in a launcher, gated on click), or loadable by anyone
+     * holding a deep link but kept out of listings.
+     */
+    access?: FragmentAccess;
+}
+export interface FragmentAccess {
+    /** Who may see this fragment in the discovery registry. Public when omitted. */
+    list?: AccessRule;
+    /** Who may load this fragment through the namespace, or have it pierced in. Public when omitted. */
+    fetch?: AccessRule;
+}
+export interface AccessRule {
+    /** The caller must hold **at least one** of these roles. */
+    roles?: string[];
+    /** The caller must hold **all** of these scopes. */
+    scopes?: string[];
+}
+/** Who is asking, as resolved from a request by the gateway's host application. */
+export interface Principal {
+    roles?: readonly string[];
+    scopes?: readonly string[];
+}
+/**
+ * Whether a principal satisfies an access rule.
+ *
+ * Note the deliberate asymmetry, which matches how these are normally used: **roles are any-of**
+ * (holding one of `["finance", "admin"]` is enough), while **scopes are all-of** (an operation
+ * requiring `["billing:read", "billing:list"]` needs both).
+ */
+export declare function satisfies(rule: AccessRule | undefined, principal: Principal | undefined): boolean;
+/** Whether this fragment appears in discovery listings for the given caller. */
+export declare function canList(manifest: ResolvedFragmentManifest, principal: Principal | undefined): boolean;
+/** Whether this caller may load the fragment — through the namespace or by piercing. */
+export declare function canFetch(manifest: ResolvedFragmentManifest, principal: Principal | undefined): boolean;
+/** Whether a manifest restricts anything at all, so the gateway can skip resolving a principal. */
+export declare function hasAccessRules(manifest: ResolvedFragmentManifest): boolean;
+/** A manifest with all defaults applied. */
+export interface ResolvedFragmentManifest extends FragmentManifest {
+    adapter: string;
+    timeoutMs: number;
+    fallback: FragmentFallback;
+    bound: boolean;
+}
+/**
+ * The adapter used when a manifest doesn't declare one. This build ships only the compat
+ * adapter, and makes it the default.
+ */
+export declare const DEFAULT_ADAPTER = "compat";
+export declare const DEFAULT_TIMEOUT_MS = 1500;
+/**
+ * A registry source: inline manifests, a URL to a JSON document (an array of manifests), or an
+ * async loader for anything else (file, KV, database).
+ */
+export type RegistrySource = FragmentManifest[] | string | (() => Promise<FragmentManifest[]>);
+export declare function normalizeManifest(manifest: FragmentManifest): ResolvedFragmentManifest;
+export declare class Registry {
+    #private;
+    constructor(source: RegistrySource);
+    getFragment(fragmentId: string): Promise<ResolvedFragmentManifest | undefined>;
+    /**
+     * Returns every fragment whose `pierce` patterns cover this page path, in registration order.
+     *
+     * A page may compose several independently deployed fragments; each is pierced into the slot
+     * that names it.
+     */
+    matchPierceRoutes(pathname: string): Promise<ResolvedFragmentManifest[]>;
+    /** Every registered fragment, ordered by id so pagination is deterministic. */
+    listFragments(): Promise<ResolvedFragmentManifest[]>;
+}

package/src/registry.js

@@ -0,0 +1,187 @@
+/**
+ * Registry & manifests: the registry is data, not code. Fragments register via manifest
+ * documents; deploying a fragment never redeploys the gateway.
+ */
+/**
+ * Whether a principal satisfies an access rule.
+ *
+ * Note the deliberate asymmetry, which matches how these are normally used: **roles are any-of**
+ * (holding one of `["finance", "admin"]` is enough), while **scopes are all-of** (an operation
+ * requiring `["billing:read", "billing:list"]` needs both).
+ */
+export function satisfies(rule, principal) {
+    if (!rule)
+        return true;
+    const roles = new Set(principal?.roles ?? []);
+    const scopes = new Set(principal?.scopes ?? []);
+    if (rule.roles?.length && !rule.roles.some((role) => roles.has(role)))
+        return false;
+    if (rule.scopes?.length && !rule.scopes.every((scope) => scopes.has(scope)))
+        return false;
+    return true;
+}
+/** Whether this fragment appears in discovery listings for the given caller. */
+export function canList(manifest, principal) {
+    return satisfies(manifest.access?.list, principal);
+}
+/** Whether this caller may load the fragment — through the namespace or by piercing. */
+export function canFetch(manifest, principal) {
+    return satisfies(manifest.access?.fetch, principal);
+}
+/** Whether a manifest restricts anything at all, so the gateway can skip resolving a principal. */
+export function hasAccessRules(manifest) {
+    return Boolean(manifest.access?.list || manifest.access?.fetch);
+}
+/**
+ * The adapter used when a manifest doesn't declare one. This build ships only the compat
+ * adapter, and makes it the default.
+ */
+export const DEFAULT_ADAPTER = 'compat';
+export const DEFAULT_TIMEOUT_MS = 1500;
+export function normalizeManifest(manifest) {
+    if (!manifest.id || manifest.id.includes('/')) {
+        throw new Error(`braid-gateway: manifest id "${manifest.id}" is invalid — ids must be non-empty and must not contain "/"`);
+    }
+    if (!manifest.endpoint) {
+        throw new Error(`braid-gateway: manifest "${manifest.id}" is missing its endpoint`);
+    }
+    // Warned rather than thrown: the fragment still composes, at the page path, which is wrong in a
+    // way that shows up as an empty widget rather than as an error anyone can trace back to here.
+    if (manifest.bound === false && !manifest.src) {
+        console.warn(`braid-gateway: fragment "${manifest.id}" declares bound: false without a src, so it will be ` +
+            `fetched at each page's own path — declare the path its content lives at, e.g. src: "/panel"`);
+    }
+    return {
+        ...manifest,
+        adapter: manifest.adapter ?? DEFAULT_ADAPTER,
+        timeoutMs: manifest.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        fallback: manifest.fallback ?? 'placeholder',
+        bound: manifest.bound ?? true,
+    };
+}
+export class Registry {
+    #source;
+    #manifests;
+    #pierceRoutes;
+    constructor(source) {
+        this.#source = source;
+        if (Array.isArray(source)) {
+            // inline manifests fail fast at construction
+            this.#manifests = indexManifests(source);
+            this.#pierceRoutes = compilePierceRoutes(this.#manifests);
+        }
+    }
+    async getFragment(fragmentId) {
+        const manifests = await this.#load();
+        return manifests.get(fragmentId);
+    }
+    /**
+     * Returns every fragment whose `pierce` patterns cover this page path, in registration order.
+     *
+     * A page may compose several independently deployed fragments; each is pierced into the slot
+     * that names it.
+     */
+    async matchPierceRoutes(pathname) {
+        await this.#load();
+        // Deduplicated by fragment. Routes are compiled one per *pattern*, so a fragment declaring
+        // both `/billing` and `/billing/*` matches `/billing` twice — the second through the
+        // trailing-slash tolerance. Returning it twice would fetch that fragment twice per page load
+        // and pierce two copies of it into one slot; callers want the set of fragments that match,
+        // not the set of patterns that did.
+        const matched = new Map();
+        for (const route of this.#pierceRoutes) {
+            if (route.matches(pathname) && !matched.has(route.manifest.id)) {
+                matched.set(route.manifest.id, route.manifest);
+            }
+        }
+        return [...matched.values()];
+    }
+    /** Every registered fragment, ordered by id so pagination is deterministic. */
+    async listFragments() {
+        const manifests = await this.#load();
+        return [...manifests.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    async #load() {
+        if (this.#manifests)
+            return this.#manifests;
+        const source = this.#source;
+        let manifests;
+        if (typeof source === 'function') {
+            manifests = await source();
+        }
+        else if (typeof source === 'string') {
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new Error(`braid-gateway: loading the registry from "${source}" failed with HTTP ${response.status}`);
+            }
+            manifests = (await response.json());
+        }
+        else {
+            manifests = source;
+        }
+        this.#manifests = indexManifests(manifests);
+        this.#pierceRoutes = compilePierceRoutes(this.#manifests);
+        return this.#manifests;
+    }
+}
+/**
+ * Compiles every manifest's `pierce` patterns with the standard URLPattern API (global since
+ * Node 23.8, and native on Workers/Deno). An invalid pattern is a registration error, not a
+ * silently-never-matching route.
+ */
+function compilePierceRoutes(manifests) {
+    const routes = [];
+    const piercing = [...manifests.values()].some((manifest) => (manifest.pierce ?? []).length > 0);
+    if (piercing)
+        assertURLPatternAvailable();
+    for (const manifest of manifests.values()) {
+        for (const pathnamePattern of manifest.pierce ?? []) {
+            let pattern;
+            try {
+                pattern = new URLPattern({ pathname: pathnamePattern });
+            }
+            catch (cause) {
+                throw new Error(`braid-gateway: fragment "${manifest.id}" declares an invalid pierce pattern "${pathnamePattern}" — ` +
+                    `patterns use URLPattern pathname syntax (https://developer.mozilla.org/docs/Web/API/URL_Pattern_API)`, { cause });
+            }
+            routes.push({
+                manifest,
+                matches(pathname) {
+                    if (pattern.test({ pathname }))
+                        return true;
+                    // URLPattern is strict about trailing slashes (`/checkout/*` does not match
+                    // `/checkout`); page routes are conventionally slash-insensitive, so try both forms
+                    const toggled = pathname.endsWith('/') ? pathname.slice(0, -1) : `${pathname}/`;
+                    return toggled !== '' && pattern.test({ pathname: toggled });
+                },
+            });
+        }
+    }
+    return routes;
+}
+/**
+ * `URLPattern` is a global only from Node 23.8; on older runtimes the constructor throws a
+ * ReferenceError. Left to the per-pattern try/catch below that reads as "your pattern is invalid"
+ * for every pattern in the registry, which sends you debugging the manifest instead of the runtime.
+ */
+function assertURLPatternAvailable() {
+    if (typeof URLPattern !== 'undefined')
+        return;
+    const node = typeof process !== 'undefined' && process.versions?.node ? ` (running Node ${process.versions.node})` : '';
+    throw new Error(`braid-gateway: this runtime has no global URLPattern${node}, which pierce patterns require — ` +
+        `use Node 24 or newer (URLPattern is global from Node 23.8), or a runtime that implements the ` +
+        `URL Pattern API (Workers, Deno, modern browsers)`);
+}
+function indexManifests(manifests) {
+    const indexed = new Map();
+    for (const manifest of manifests) {
+        const resolved = normalizeManifest(manifest);
+        if (indexed.has(resolved.id)) {
+            console.warn(`braid-gateway: duplicate manifest for fragment id "${resolved.id}" — ignoring the duplicate`);
+            continue;
+        }
+        indexed.set(resolved.id, resolved);
+    }
+    return indexed;
+}
+//# sourceMappingURL=registry.js.map

package/src/registry.js.map

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

package/src/rewriter/html-rewrite-stream.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The owned streaming HTML rewriter (zero forked dependencies).
+ *
+ * Braid's streaming needs are narrow and known: rename three elements, neutralize scripts and
+ * script-preload links, inject content at slot elements, and interleave two HTML streams. That
+ * is a small enough surface to own outright rather than inherit a forked HTMLRewriter wasm
+ * build — and owning it is what makes the composition protocol testable as a spec.
+ *
+ * Properties this implementation guarantees:
+ *
+ * - **Streaming**: output is produced as input arrives. Only the current (partial) tag is
+ *   buffered, so memory stays bounded regardless of document size.
+ * - **Chunk-boundary safe**: a tag, comment, doctype, or raw-text end sequence split across
+ *   network chunks is reassembled before it is interpreted.
+ * - **Fidelity by default**: a tag no handler modifies is emitted byte-for-byte as it arrived.
+ *   Only mutated tags are re-serialized.
+ * - **Stream injection**: injected content may itself be a `ReadableStream`, which is what makes
+ *   piercing a true interleave (shell up to the slot, then the fragment's stream, then the rest
+ *   of the shell) rather than a buffer-everything-then-concatenate.
+ *
+ * Scope note: this is a rewriter, not a parser. It does not build a tree, resolve implied tags,
+ * or handle malformed-markup recovery — it observes a linear token stream. That is sufficient
+ * for every transform in the composition protocol, and the conformance vectors in
+ * `html-rewrite-stream.spec.ts` are the oracle for it.
+ */
+/** Content that can be injected: literal HTML, or a stream of it (interleaved as it arrives). */
+export type Injection = string | ReadableStream<Uint8Array>;
+export interface StartTag {
+    /** The tag name, lowercased. Assigning renames the element. */
+    tagName: string;
+    readonly selfClosing: boolean;
+    /** Lowercased names of the element's attributes, in source order. */
+    readonly attributeNames: string[];
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    /** Emits content immediately before this start tag. */
+    before(content: Injection): void;
+    /** Emits content immediately after this start tag (i.e. as the element's first content). */
+    prepend(content: Injection): void;
+}
+export interface EndTag {
+    readonly tagName: string;
+    /** Emits content immediately before this end tag. */
+    before(content: Injection): void;
+}
+export interface ElementHandler {
+    element?(tag: StartTag): void;
+    endTag?(tag: EndTag): void;
+}
+export interface RewriteOptions {
+    /**
+     * Handlers keyed by lowercased tag name. The key `*` matches every element and runs before
+     * the tag-specific handler — used for transforms that apply regardless of element, such as
+     * stripping inline event handlers.
+     */
+    handlers: Record<string, ElementHandler>;
+    /** Drops `<!doctype …>` tokens (nested doctypes make some parsers choke). */
+    stripDoctype?: boolean;
+    /**
+     * Emitted once the input ends. Used as the safety net for injections anchored to an end tag
+     * that never arrives — `</body>` is optional in HTML and frequently omitted.
+     */
+    onEnd?(): Injection | undefined;
+}
+export declare function rewriteHtmlStream(input: ReadableStream<Uint8Array>, options: RewriteOptions): ReadableStream<Uint8Array>;
+/** Adapts an async generator of chunks into a ReadableStream. */
+export declare function toReadableStream(generator: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array>;
+/** Builds a stream from literal strings and other streams, concatenated in order. */
+export declare function concatStreams(parts: Injection[]): ReadableStream<Uint8Array>;