@braidlabs/gateway 0.3.0 → 0.5.0

package/README.md

@@ -45,8 +45,9 @@ to load, and the element to mount:
 createGateway({ registry, discovery: { appd: true } });
 ```
 
-Serves the same registry in FDC3 App Directory shape at `/__braid/registry/appd/v2/apps` (and
-`/appd/v2/apps/{appId}`). It is a **projection, not a second directory** — same manifests, same
+Serves the same registry as an FDC3 2.2 App Directory: `/__braid/registry/appd/v2/apps` lists
+`{ applications, message }`, and `/appd/v2/apps/{appId}` returns the bare `Application` record.
+It is a **projection, not a second directory** — same manifests, same
 `access.list` rules — so a caller can never see through AppD a resolver that discovery would have
 hidden. `findIntent` becomes a registry query, and a user only sees resolvers they may use.
 
@@ -69,11 +70,17 @@ Two mapping decisions worth knowing:
   A fragment is *mounted into a page*, not opened as a window, so a Braid-aware agent reads
   `hostManifests.braid` and mounts a `<fragment-slot>`; one that does not falls back to the URL.
 
-An app the caller may not list 404s exactly as an unregistered one does — distinguishing them would
-let an unauthorized caller enumerate the registry one id at a time.
+An app the caller may not list 404s (with AppD's `{ code, message }` error body) exactly as an
+unregistered one does — distinguishing them would let an unauthorized caller enumerate the registry
+one id at a time.
 
-Verify the record shape against the FDC3 AppD v2 spec before depending on it; the schema carries
-more optional members than this projects.
+Records are validated in the test suite against FDC3 2.2's own App Directory schema. Relative icon
+`src` values are resolved against the origin, since AppD requires absolute URLs, and a link that is
+not http(s) is dropped rather than passed on. Optional members
+Braid has no data for (`lang`, `screenshots`, `localizedVersions`, `interop.appChannels`) are not
+produced. To serve the same directory from the governed registry instead of a gateway, see
+`createRegistryApi({ appd })` in `@braidlabs/registry`; to give fragments `window.fdc3`, see
+`@braidlabs/fdc3`.
 
 A relative `entry` is re-rooted into the fragment's namespace, so the module and its imports are
 fetched through the gateway rather than from the host's root. Such a fragment serves no document,
@@ -166,6 +173,13 @@ 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>`.
 
+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
+never fill an outlet. A named slot after the outlet is too late for a fragment the outlet already
+took, so the gateway unnames it (`data-braid-in-outlet`) and warns, rather than let the client boot
+a second copy. The outlet is filled on full page loads only.
+
 Fragment HTML is transformed on the way through: the doctype is stripped, `<html>/<head>/<body>`
 become `braid-html/braid-head/braid-body` (start *and* end tags), scripts are neutralized to
 `type="inert"`, and script preload links become `rel="inert-*"`. Fragment scripts are therefore
@@ -547,6 +561,11 @@ user against the shell. A fragment that needs to know who is asking should be gi
 scoped to it: a per-request assertion via `additionalHeaders`, or a token exchanged for the
 fragment's own audience. `forwardCredentials: true` restores the old behaviour, and is only
 appropriate when every endpoint in the registry sits inside the same trust boundary as the shell.
+When only some do, pass a function instead, `forwardCredentials: (fragment) => …`, and the gateway
+decides per fragment. A function that throws forwards nothing, and websocket upgrades follow the
+same decision. `proxy-authorization` is stripped with them, and `credentialHeaders` adds any
+identity header an auth proxy in front of the shell injects (`x-auth-request-access-token`,
+`cf-access-jwt-assertion`, …).
 
 Not yet implemented from the architecture's security section: allow-listed manifest origins and
 signed manifests. Until those land, treat the registry as trusted configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braidlabs/gateway",
-  "version": "0.3.0",
+  "version": "0.5.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/appd.d.ts

@@ -11,9 +11,9 @@ import type { ResolvedFragmentManifest } from './registry.js';
  * The payoff for FDC3 is direct: `findIntent` becomes a registry query, and because discovery
  * filters by the caller's principal, a user only ever sees resolvers they are permitted to use.
  *
- * **Verify the record shape against the FDC3 AppD v2 spec before relying on it.** The mapping below
- * is faithful to the standard as understood here, but the schema has more optional members than
- * this uses and is the kind of thing that is easy to be subtly wrong about.
+ * Records are checked against FDC3 2.2's own AppD schema in `appd.spec.ts` (vendored under
+ * `tools/fdc3/`). Optional members Braid has no data for — `lang`, `screenshots`,
+ * `localizedVersions`, `interop.appChannels` — are not produced.
  */
 /** The `fdc3` block a manifest may carry. A superset of what AppD needs; the rest is for the runtime. */
 export interface FragmentFdc3Metadata {
@@ -51,14 +51,14 @@ export interface FragmentAppdMetadata {
         type?: string;
     }[];
 }
+/** An FDC3 AppD v2 `Application` record — the members Braid fills. */
 export interface AppdApplication {
     appId: string;
-    name: string;
+    title: string;
     type: 'web';
     details: {
         url: string;
     };
-    title?: string;
     description?: string;
     tooltip?: string;
     version?: string;
@@ -75,7 +75,6 @@ export interface AppdApplication {
     interop?: {
         intents?: {
             listensFor?: Record<string, {
-                name: string;
                 displayName?: string;
                 contexts: string[];
                 resultType?: string;
@@ -110,10 +109,29 @@ export interface AppdListResponse {
     applications: AppdApplication[];
     message: string;
 }
-export interface AppdAppResponse {
-    application: AppdApplication;
+/** AppD's error body, `ErrorDTO`. */
+export interface AppdError {
+    code: number;
     message: string;
 }
+/**
+ * The App Directory's two reads over a set of manifests the caller may already see: the listing,
+ * or one application by `appId`. `GET /v2/apps/{appId}` answers with the bare `Application`, not
+ * a wrapper. Headers are the caller's — what may be cached differs between the gateway, whose
+ * listing depends on who asked, and the registry.
+ */
+export declare function appdResponse(options: {
+    manifests: readonly ResolvedFragmentManifest[];
+    origin: string;
+    /** Present for `/v2/apps/{appId}`, absent for the listing. */
+    appId?: string;
+}): {
+    status: 200;
+    body: AppdListResponse | AppdApplication;
+} | {
+    status: 404;
+    body: AppdError;
+};
 /**
  * Projects one manifest into an AppD record.
  *

package/src/appd.js

@@ -1,4 +1,31 @@
 import { BRAID_FRAGMENT_PREFIX } from './protocol.js';
+/**
+ * The App Directory's two reads over a set of manifests the caller may already see: the listing,
+ * or one application by `appId`. `GET /v2/apps/{appId}` answers with the bare `Application`, not
+ * a wrapper. Headers are the caller's — what may be cached differs between the gateway, whose
+ * listing depends on who asked, and the registry.
+ */
+export function appdResponse(options) {
+    const { manifests, origin, appId } = options;
+    if (appId === undefined) {
+        // one manifest the projection cannot read is left out, not allowed to fail everyone's listing
+        const applications = manifests.flatMap((manifest) => {
+            try {
+                return [toAppdApplication(manifest, origin)];
+            }
+            catch {
+                return [];
+            }
+        });
+        return { status: 200, body: { applications, message: 'OK' } };
+    }
+    const match = manifests.find((manifest) => manifest.id === appId);
+    // the same 404 for "not visible to you" as for "not registered" — distinguishing them would let
+    // an unauthorized caller enumerate the registry one id at a time
+    if (!match)
+        return { status: 404, body: { code: 404, message: `No application with appId "${appId}"` } };
+    return { status: 200, body: toAppdApplication(match, origin) };
+}
 /**
  * Projects one manifest into an AppD record.
  *
@@ -15,12 +42,12 @@ import { BRAID_FRAGMENT_PREFIX } from './protocol.js';
 export function toAppdApplication(manifest, origin) {
     const mount = `${BRAID_FRAGMENT_PREFIX}${encodeURIComponent(manifest.id)}/`;
     const page = firstPiercePage(manifest.pierce);
+    // `name` is deprecated in AppD v2 in favour of `appId` and `title`, so it is not set.
     const application = {
         appId: manifest.id,
-        name: manifest.id,
+        title: manifest.title ?? manifest.id,
         type: 'web',
         details: { url: new URL(page ?? mount, origin).href },
-        title: manifest.title ?? manifest.id,
         hostManifests: {
             braid: { fragmentId: manifest.id, mount, adapter: manifest.adapter, standalonePage: page !== null },
         },
@@ -36,14 +63,20 @@ export function toAppdApplication(manifest, origin) {
         application.contactEmail = appd.contactEmail;
     if (appd?.supportEmail)
         application.supportEmail = appd.supportEmail;
-    if (appd?.moreInfo)
-        application.moreInfo = appd.moreInfo;
+    const moreInfo = appd?.moreInfo ? webUrl(appd.moreInfo, origin) : null;
+    if (moreInfo)
+        application.moreInfo = moreInfo;
     if (appd?.version)
         application.version = appd.version;
     if (appd?.tooltip)
         application.tooltip = appd.tooltip;
-    if (appd?.icons?.length)
-        application.icons = appd.icons.map((icon) => ({ ...icon }));
+    // AppD requires an absolute icon url; a manifest may name one relative to the shell
+    const icons = (appd?.icons ?? []).flatMap((icon) => {
+        const src = webUrl(icon.src, origin);
+        return src ? [{ ...icon, src }] : [];
+    });
+    if (icons.length)
+        application.icons = icons;
     const interop = toInterop(manifest.fdc3);
     if (interop)
         application.interop = interop;
@@ -53,10 +86,8 @@ function toInterop(fdc3) {
     if (!fdc3)
         return undefined;
     const listensFor = Object.entries(fdc3.listensFor ?? {}).reduce((accumulator, [intent, declaration]) => {
-        // `name` is required on an AppD intent record and duplicates the key. Filling it from the key
-        // rather than requiring it in the manifest keeps one source of truth for the intent's name.
+        // the key is the intent's name; AppD v2's intent record has no `name` member of its own
         accumulator[intent] = {
-            name: intent,
             contexts: declaration.contexts ?? [],
             ...(declaration.displayName ? { displayName: declaration.displayName } : {}),
             ...(declaration.resultType ? { resultType: declaration.resultType } : {}),
@@ -73,6 +104,22 @@ function toInterop(fdc3) {
     };
     return Object.keys(interop).length > 0 ? interop : undefined;
 }
+/**
+ * A manifest-supplied link, absolute on `origin`, or null when it is not an http(s) URL. Dropping
+ * a bad one keeps one manifest's typo from failing the whole listing, and keeps `javascript:` out
+ * of every launcher that renders the directory.
+ */
+function webUrl(value, origin) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value, origin);
+        return url.protocol === 'https:' || url.protocol === 'http:' ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The first pierce pattern reduced to a concrete page path.
  *

package/src/appd.js.map

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

package/src/breaker.d.ts

@@ -40,6 +40,8 @@ export interface Breaker {
     succeeded(fragmentId: string): void;
     failed(fragmentId: string): void;
     stateOf(fragmentId: string): BreakerState;
+    /** Drops a fragment's circuit — after a registry refresh removed it or changed its endpoint. */
+    forget(fragmentId: string): void;
 }
 /**
  * Creates a breaker.

package/src/breaker.js

@@ -64,6 +64,9 @@ export function createBreaker(options = {}, onTransition, now = Date.now) {
             circuit.probing = true;
             return true;
         },
+        forget(fragmentId) {
+            circuits.delete(fragmentId);
+        },
         succeeded(fragmentId) {
             const circuit = circuitFor(fragmentId);
             circuit.failures = 0;

package/src/breaker.js.map

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

package/src/discovery.js

@@ -1,5 +1,5 @@
 import { BRAID_FRAGMENT_PREFIX, BRAID_PROTOCOL_VERSION } from './protocol.js';
-import { toAppdApplication } from './appd.js';
+import { appdResponse } from './appd.js';
 import { canFetch, canList } from './registry.js';
 export const DEFAULT_DISCOVERY_PATH = '/__braid/registry';
 export const DEFAULT_DISCOVERY_PAGE_SIZE = 100;
@@ -41,22 +41,15 @@ export function createDiscoveryHandler(registry, options, mode, resolvePrincipal
             // so a caller can never see a resolver through AppD that discovery would have hidden.
             if (appdEnabled && url.pathname.startsWith(appdPath)) {
                 const requested = url.pathname.slice(appdPath.length).replace(/^\//, '');
-                if (!requested) {
-                    const body = {
-                        applications: visible.map((manifest) => toAppdApplication(manifest, url.origin)),
-                        message: 'OK',
-                    };
-                    return json(body, 200, { 'Cache-Control': 'no-store', Vary: 'cookie, authorization' });
-                }
-                const appId = decodeURIComponent(requested);
-                const match = visible.find((manifest) => manifest.id === appId);
-                if (!match) {
-                    // 404 for "not visible to you" as well as "not registered" — distinguishing them would
-                    // let an unauthorized caller enumerate the registry one id at a time.
-                    return json({ message: `No application with appId "${appId}"` }, 404, { 'Cache-Control': 'no-store' });
-                }
-                const body = { application: toAppdApplication(match, url.origin), message: 'OK' };
-                return json(body, 200, { 'Cache-Control': 'no-store', Vary: 'cookie, authorization' });
+                const { status, body } = appdResponse({
+                    manifests: visible,
+                    origin: url.origin,
+                    ...(requested ? { appId: safeDecode(requested) } : {}),
+                });
+                return json(body, status, {
+                    'Cache-Control': 'no-store',
+                    ...(status === 200 ? { Vary: 'cookie, authorization' } : {}),
+                });
             }
             const pageSize = clampPageSize(url.searchParams.get('pageSize'), defaultPageSize, maxPageSize);
             const totalPages = Math.max(1, Math.ceil(visible.length / pageSize));
@@ -118,6 +111,15 @@ function clampPage(requested, totalPages) {
         return 1;
     return Math.min(parsed, totalPages);
 }
+/** A malformed escape names no application, rather than throwing. */
+function safeDecode(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
 function json(body, status, headers = {}) {
     return new Response(JSON.stringify(body), {
         status,

package/src/discovery.js.map

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

package/src/gateway.d.ts

@@ -1,10 +1,33 @@
-import { Principal, RegistrySource } from './registry.js';
+import { Principal, RegistryRefresh, RegistrySource, FragmentManifest } from './registry.js';
 import { DiscoveryOptions } from './discovery.js';
 import { type BreakerOptions } from './breaker.js';
 import { type TelemetryOptions } from './telemetry.js';
 export interface GatewayOptions {
     /** The fragment registry: inline manifests, a JSON URL, or an async loader. */
     registry: RegistrySource;
+    /**
+     * Reload the registry source every this many milliseconds, and serve what it returns from then
+     * on — a re-pin goes live without a restart.
+     *
+     * Off by default, which keeps the snapshot model's "a re-pin is a deploy". With a source that
+     * follows a moving pointer (`snapshotRegistry` without `pinned`, a URL), this is hot re-pin; with
+     * a pinned source it is a cheap no-op. Each reload is all-or-nothing, and one that fails leaves
+     * the current registry serving and is reported as a `registry` telemetry event.
+     *
+     * Instances poll independently, so a fleet converges within one interval rather than at one
+     * instant. Not allowed with inline manifests, which cannot change.
+     */
+    registryRefreshMs?: number;
+    /**
+     * Supplies the page itself for a document request, in place of the shell app behind the gateway:
+     * return HTML, or null to let `next` (the app) answer as usual.
+     *
+     * Fragments are pierced into what this returns exactly as into an app's response, and a page it
+     * answers is served even when no fragment pierces it. This is how a shell defined as data — see
+     * `shellDocuments` in `@braidlabs/registry` — is served with no app and no rebuild. Consulted only
+     * for document requests (GET, `Sec-Fetch-Dest: document` or an HTML `Accept`).
+     */
+    documents?: (request: Request, context: DocumentsContext) => Response | null | Promise<Response | null>;
     /** 'development' enables verbose error bodies; defaults to 'development'. */
     mode?: 'production' | 'development';
     /**
@@ -28,8 +51,31 @@ export interface GatewayOptions {
      * assertion minted per request via {@link GatewayOptions.additionalHeaders}, or a token
      * exchanged for the fragment's own audience. Turn this on only when every endpoint in the
      * registry is inside the same trust boundary as the shell.
+     *
+     * Or decide per fragment, when only some of them are — the usual case once a gateway composes
+     * other teams' gateways:
+     *
+     * ```ts
+     * forwardCredentials: (fragment) => typeof fragment.endpoint === 'string' &&
+     *   fragment.endpoint.startsWith('https://orders.internal/'),
+     * ```
+     *
+     * The function is the host's, never the manifest's: a fragment that could declare its own
+     * entitlement to the user's cookies would not be behind a boundary at all. A function that
+     * throws forwards nothing. The same decision applies to websocket upgrades.
      */
-    forwardCredentials?: boolean;
+    forwardCredentials?: boolean | ((fragment: FragmentManifest) => boolean);
+    /**
+     * More request headers that carry the caller's identity, stripped alongside `cookie`,
+     * `authorization` and `proxy-authorization` whenever {@link GatewayOptions.forwardCredentials}
+     * does not allow a fragment.
+     *
+     * An auth proxy in front of the shell often adds its own: `x-auth-request-access-token`
+     * (oauth2-proxy), `cf-access-jwt-assertion` (Cloudflare Access), `x-amzn-oidc-data` (an ALB).
+     * The gateway cannot know them, and each one is the user's identity handed to every fragment
+     * endpoint unless it is listed here.
+     */
+    credentialHeaders?: readonly string[];
     /**
      * Publishes a paginated listing of the fragments this gateway serves, for shells that build
      * their UI from the registry instead of hard-coding slot names.
@@ -206,6 +252,25 @@ export interface RoutingEvent {
     fragmentIds: string[];
     at: number;
 }
+/** Where a fragment websocket upgrade goes, and what may travel with it. See `resolveUpgrade`. */
+export interface UpgradeTarget {
+    fragmentId: string;
+    target: URL;
+    forwardCredentials: boolean;
+    /** Headers that carry the caller's identity: stripped unless `forwardCredentials`. */
+    credentialHeaders: readonly string[];
+    /** The `x-braid-via` value for the upstream request, this gateway's hop included. */
+    via: string;
+}
+/** What the gateway tells a `documents` hook about the registry it is serving right now. */
+export interface DocumentsContext {
+    /**
+     * The manifests the gateway is serving — exactly the array its registry source last returned and
+     * it accepted. A hook that renders from the same snapshot (`shellDocuments`) keys on this, so a
+     * page's shell can never come from a snapshot the gateway refused to load.
+     */
+    manifests: readonly FragmentManifest[];
+}
 export interface BraidGateway {
     /**
      * Handles a request if it belongs to Braid: a fragment-namespace request, or a document
@@ -223,13 +288,24 @@ export interface BraidGateway {
      * addressed through the fragment namespace, so the gateway has to say where they go — the
      * socket plumbing itself belongs to the platform binding.
      *
-     * @returns the endpoint URL to dial, or null when the request is not a fragment upgrade, the
-     *          fragment is unknown, or the caller may not load it.
+     * 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.
+     *
+     * @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
+     *          them, and the hop header to send — or null when the request is not a fragment
+     *          upgrade, the fragment is unknown, the caller may not load it, or it has already
+     *          crossed too many gateways.
+     */
+    resolveUpgrade(request: Request): Promise<UpgradeTarget | null>;
+    /**
+     * Reloads the registry source now and swaps in what it returns. Resolves once the new registry
+     * is serving; rejects, leaving the current one serving, when the source fails.
      */
-    resolveUpgrade(request: Request): Promise<{
-        fragmentId: string;
-        target: URL;
-    } | null>;
+    refreshRegistry(): Promise<RegistryRefresh>;
+    /** Stops the `registryRefreshMs` timer. Nothing else holds resources between requests. */
+    close(): void;
 }
 export declare function createGateway(options: GatewayOptions): BraidGateway;
 /**