@braidlabs/gateway 0.7.1 → 0.8.0

package/README.md

@@ -303,6 +303,34 @@ It only works end to end once the fragment can see the user: `forwardCredentials
 header via `additionalHeaders`. The gateway warns when a fragment opts in and neither is set — at startup for an inline registry, on the
 first redirect for a URL or loader registry.
 
+## Per-user preferences (opt-in)
+
+`preferences` serves each signed-in user's own JSON entries at `/__braid/preferences/*`. It is what
+`serverStore()` from `@braidlabs/console/workspace` talks to, so preferences, app settings and
+saved layouts follow the user to any browser.
+
+```ts
+import { filePreferenceBackend } from '@braidlabs/gateway/node';
+
+createGateway({
+  registry,
+  principal: async (request) => {
+    const session = await sessions.read(request);
+    return session && { subject: session.userId, roles: session.roles };
+  },
+  preferences: { backend: filePreferenceBackend({ directory: '/var/lib/braid/preferences' }) },
+});
+```
+
+- Entries are keyed by the principal's `subject`, which must come from your session and be
+  globally unique (`${iss}|${sub}` across identity providers). No subject, 401.
+- Same-origin only: a cross-site `Sec-Fetch-Site`, or a foreign `Origin` when that is absent, gets
+  403, reads included.
+- Bounded: 64 KiB a value, 1000 entries and 1 MiB a user, enforced by the backend in the same
+  write (413 past any of them). Every answer is `private, no-store`.
+- Backends: `memoryPreferenceBackend()` for tests, `filePreferenceBackend()` for one Node process,
+  or your own `PreferenceBackend` over a database behind several instances. Full details: [gateway docs](../../docs/packages/gateway.md#per-user-preferences-opt-in).
+
 ## Discovery endpoint (optional)
 
 For shells that build their UI from the registry rather than hard-coding slot names — a launcher,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braidlabs/gateway",
-  "version": "0.7.1",
+  "version": "0.8.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/cookie-scope.js

@@ -34,9 +34,12 @@ export function storagePartitionOf(fragment) {
     if (grant === 'partitioned')
         return fragment.id;
     if (grant && typeof grant === 'object') {
-        const partition = grant.partition;
+        const { partition, databases } = grant;
         if (typeof partition === 'string' && partition !== '')
             return partition;
+        // as on the client: databases of its own imply a partition named for the fragment
+        if (databases === true && partition === undefined)
+            return fragment.id;
     }
     return null;
 }

package/src/cookie-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-scope.js","sourceRoot":"","sources":["../../../../libs/braid-gateway/src/cookie-scope.ts"],"names":[],"mappings":"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"}
+{"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,5 +1,6 @@
 import { Principal, RegistryRefresh, RegistrySource, FragmentManifest } from './registry.js';
 import { DiscoveryOptions } from './discovery.js';
+import { type PreferencesOptions } from './preferences.js';
 import { type BreakerOptions } from './breaker.js';
 import { type BaggageOptions } from './baggage.js';
 import { type TelemetryOptions } from './telemetry.js';
@@ -29,7 +30,13 @@ export interface GatewayOptions {
      * 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'. */
+    /**
+     * Defaults to 'production'.
+     *
+     * 'development' is for a gateway on your own machine: it **skips every `access` rule**, lists
+     * every fragment with its endpoint in discovery, sends verbose error bodies, and rewrites
+     * `Origin` to the endpoint's own. Never set it on a gateway other people can reach.
+     */
     mode?: 'production' | 'development';
     /**
      * Additional headers set on every request forwarded to a fragment endpoint.
@@ -92,6 +99,13 @@ export interface GatewayOptions {
      * See {@link DiscoveryOptions}.
      */
     discovery?: DiscoveryOptions;
+    /**
+     * Serves each signed-in user's preferences at `/__braid/preferences/*`, for the workspace's
+     * `serverStore` (`@braidlabs/console/workspace`): preferences, app settings and saved layouts. Entries are keyed by
+     * the `subject` your `principal` resolver returns; a request without one is refused with 401.
+     * Off unless configured. See {@link PreferencesOptions}.
+     */
+    preferences?: PreferencesOptions;
     /**
      * Resolves who is asking, for manifests that declare `access` rules.
      *
@@ -227,6 +241,17 @@ export interface GatewayOptions {
      * on an origin it does not own.
      */
     serviceWorker?: boolean | ServiceWorkerOptions;
+    /**
+     * Tell the browser which links it may fetch or render ahead of a click (Speculation Rules,
+     * Chromium), from the fragments whose manifest sets `speculate`.
+     *
+     * Every HTML document the gateway serves or passes through then carries
+     * `Speculation-Rules: "/__braid/speculation-rules.json"`. The header is the same for everyone,
+     * so a cached page stays shareable. The rules it points to are built per request from the
+     * registry: a fragment the caller may not fetch is left out, and when any fragment has access
+     * rules the response is private to the caller. Off by default.
+     */
+    speculationRules?: boolean;
     /**
      * The path this gateway is mounted under, for a host that shares its domain and does not own the
      * root (`/manage`). The reserved namespaces move under it — `/manage/__braid/frag/…` — and the
@@ -328,6 +353,13 @@ export interface BraidGateway {
      *             document requests are passed through and fragments boot client-side instead.
      */
     handle(request: Request, next?: () => Promise<Response>): Promise<Response | null>;
+    /**
+     * Headers a binding adds to a page it passes to the app when `handle` returned null — the
+     * pointer to the speculation rules, when `speculationRules` is on — or null for none. Set on the
+     * way out rather than by reading the app's response, so a passed-through page streams exactly as
+     * it would without the gateway. Browsers ignore them on anything but HTML.
+     */
+    pageHeaders(request: Request): Record<string, string> | null;
     /**
      * Resolves a websocket upgrade addressed to a fragment.
      *

package/src/gateway.js

@@ -1,6 +1,8 @@
-import { BRAID_ADAPTER_META, BRAID_ADAPTER_OPTIONS_META, BRAID_FRAGMENT_ID_HEADER, BRAID_MAX_HOPS, BRAID_PROTOCOL_META, BRAID_PROTOCOL_VERSION, BRAID_REDIRECT_LOCATION_HEADER, BRAID_RETURN_URL_HEADER, braidFragmentUrl, parseBraidPathname, BRAID_SERVICE_WORKER_PATH, BRAID_VITALS_BEACON_PATH, BRAID_VITALS_SCRIPT_PATH, BRAID_VIA_HEADER, } from './protocol.js';
+import { BRAID_ADAPTER_META, BRAID_ADAPTER_OPTIONS_META, BRAID_FRAGMENT_ID_HEADER, BRAID_MAX_HOPS, BRAID_PROTOCOL_META, BRAID_PROTOCOL_VERSION, BRAID_REDIRECT_LOCATION_HEADER, BRAID_RETURN_URL_HEADER, braidFragmentUrl, parseBraidPathname, BRAID_SERVICE_WORKER_PATH, BRAID_SPECULATION_RULES_PATH, BRAID_VITALS_BEACON_PATH, BRAID_VITALS_SCRIPT_PATH, BRAID_VIA_HEADER, } from './protocol.js';
 import { canFetch, canList, hasAccessRules, isOriginSource, Registry, } from './registry.js';
 import { createDiscoveryHandler } from './discovery.js';
+import { createPreferencesHandler } from './preferences.js';
+import { speculationRulesFor } from './speculation.js';
 import { createBreaker } from './breaker.js';
 import { createSingleFlight, singleFlightKey } from './single-flight.js';
 import { scopeRequestCookies, scopeResponseCookies, scopeSetCookie, storagePartitionOf, withoutScopedCookies } from './cookie-scope.js';
@@ -33,7 +35,9 @@ export function createGateway(options) {
             throw new Error(`braid-gateway: registryRefreshMs must be a positive number of milliseconds, got ${options.registryRefreshMs}`);
         }
     }
-    const mode = options.mode ?? 'development';
+    // Production unless asked: development skips access rules, so it must never be what a
+    // deployment gets for forgetting an option.
+    const mode = options.mode ?? 'production';
     const pierceCacheControl = options.pierceCacheControl ?? 'private';
     const realmPolicy = options.realmPolicy;
     if (realmPolicy !== undefined && realmPolicy !== 'report' && realmPolicy !== 'enforce') {
@@ -147,7 +151,9 @@ export function createGateway(options) {
         const unsupported = [
             serviceWorker && 'serviceWorker',
             options.discovery && 'discovery',
+            options.preferences && 'preferences',
             vitalsEnabled && 'telemetry.webVitals',
+            options.speculationRules && 'speculationRules',
         ].filter(Boolean);
         if (unsupported.length) {
             throw new Error(`braid-gateway: basePath "${basePath}" is not supported together with ${unsupported.join(', ')} yet — ` +
@@ -259,8 +265,10 @@ export function createGateway(options) {
      */
     const resolvePrincipal = async (request) => options.principal ? ((await options.principal(request)) ?? undefined) : undefined;
     const discovery = createDiscoveryHandler(registry, options.discovery, mode, resolvePrincipal);
+    const preferences = createPreferencesHandler(options.preferences, resolvePrincipal);
     return {
         refreshRegistry,
+        pageHeaders,
         close() {
             closed = true;
             clearTimeout(refreshTimer);
@@ -275,6 +283,9 @@ export function createGateway(options) {
             if (discovery?.owns(requestUrl.pathname)) {
                 return discovery.handle(request, requestUrl);
             }
+            if (preferences?.owns(requestUrl.pathname)) {
+                return preferences.handle(request, requestUrl);
+            }
             if (serviceWorker && requestUrl.pathname === BRAID_SERVICE_WORKER_PATH) {
                 return serviceWorkerResponse(serviceWorker);
             }
@@ -291,36 +302,14 @@ export function createGateway(options) {
             if (vitalsEnabled && requestUrl.pathname === BRAID_VITALS_BEACON_PATH) {
                 return handleVitalsBeacon(request);
             }
+            if (options.speculationRules && requestUrl.pathname === BRAID_SPECULATION_RULES_PATH) {
+                return speculationRulesResponse(request);
+            }
             const route = braidRoute(requestUrl.pathname);
             if (!route) {
-                // HEAD gets the same answer without the body, so a monitor or link checker in front of a
-                // gateway with no app behind it sees the page a browser would.
-                if (options.documents && request.method === 'HEAD') {
-                    const asGet = new Request(request.url, { method: 'GET', headers: request.headers });
-                    const document = await options.documents(asGet, { manifests: await registry.current() });
-                    if (document) {
-                        const headers = new Headers(document.headers);
-                        headers.append('vary', 'sec-fetch-dest');
-                        applyPierceCacheControl(headers);
-                        await document.body?.cancel();
-                        return new Response(null, { status: document.status, headers });
-                    }
-                }
-                const document = options.documents && isDocumentRequest(request)
-                    ? await options.documents(request, { manifests: await registry.current() })
-                    : null;
-                if (document) {
-                    // The defined document is the shell: pierced like an app's response when fragments match,
-                    // and served as it is when none do.
-                    const composed = await handleShellRequest(request, requestUrl, async () => document);
-                    if (composed)
-                        return composed;
-                    const served = new Response(document.body, document);
-                    served.headers.append('vary', 'sec-fetch-dest');
-                    applyPierceCacheControl(served.headers);
-                    return served;
-                }
-                return next ? handleShellRequest(request, requestUrl, next) : null;
+                // A page the gateway leaves to the app comes back null, untouched: the binding adds the
+                // page headers on its way through, without the gateway reading the app's response.
+                return withPageHeaders(request, await pageResponse(request, requestUrl, next));
             }
             /**
              * Braid requests are routed to the addressed fragment exactly: an unknown fragment id is a
@@ -698,6 +687,9 @@ export function createGateway(options) {
         // browser's `zstd` would come back decoded by some runtimes and not others (see `forwardable`)
         if (fragmentFetch === globalThis.fetch)
             fragmentRequest.headers.set('accept-encoding', [...FETCH_DECODED_CODINGS].join(', '));
+        // A browser (the gateway in a service worker) forbids the header and drops it without a word:
+        // the browser then picks the codings itself and decodes every one it picked.
+        const codingsPinned = fragmentRequest.headers.has('accept-encoding');
         fragmentRequest.headers.set('x-braid-fragment-mode', 'embedded');
         /**
          * In development, present the request as coming from the endpoint's own origin.
@@ -769,7 +761,7 @@ export function createGateway(options) {
             };
             const sentResponse = key ? await singleFlight.run(key, send) : await send();
             // a function endpoint hands over its own bytes; only the platform fetch decodes them
-            const response = forwardable(sentResponse, fragmentFetch === globalThis.fetch);
+            const response = forwardable(sentResponse, fragmentFetch === globalThis.fetch, codingsPinned);
             // A 5xx is a reachable endpoint, but it is not a working one — a fragment returning 500 on
             // every request would otherwise hold the circuit closed forever and keep paying for it.
             if (response.status >= 500)
@@ -805,6 +797,83 @@ export function createGateway(options) {
             return { ok: false, error, timedOut: timeoutSignal.aborted };
         }
     }
+    /** A request outside the Braid namespace: a page, composed or passed to the shell. */
+    async function pageResponse(request, requestUrl, next) {
+        // HEAD gets the same answer without the body, so a monitor or link checker in front of a
+        // gateway with no app behind it sees the page a browser would.
+        if (options.documents && request.method === 'HEAD') {
+            const asGet = new Request(request.url, { method: 'GET', headers: request.headers });
+            const document = await options.documents(asGet, { manifests: await registry.current() });
+            if (document) {
+                const headers = new Headers(document.headers);
+                headers.append('vary', 'sec-fetch-dest');
+                applyPierceCacheControl(headers);
+                await document.body?.cancel();
+                return new Response(null, { status: document.status, headers });
+            }
+        }
+        const document = options.documents && isDocumentRequest(request)
+            ? await options.documents(request, { manifests: await registry.current() })
+            : null;
+        if (document) {
+            // The defined document is the shell: pierced like an app's response when fragments match,
+            // and served as it is when none do.
+            const composed = await handleShellRequest(request, requestUrl, async () => document);
+            if (composed)
+                return composed;
+            const served = new Response(document.body, document);
+            served.headers.append('vary', 'sec-fetch-dest');
+            applyPierceCacheControl(served.headers);
+            return served;
+        }
+        return next ? handleShellRequest(request, requestUrl, next) : null;
+    }
+    /**
+     * The headers a page carries because of this gateway, for a browser navigation: today, the
+     * pointer to the speculation rules.
+     *
+     * Every page, not only composed ones: the page that *links* to a fragment's route is the one the
+     * browser speculates from, and it is usually not that route. The value is the same for every
+     * caller, so it never makes a page private, and a browser ignores it on anything but HTML.
+     */
+    function pageHeaders(request) {
+        if (!options.speculationRules || !isNavigation(request))
+            return null;
+        return { 'speculation-rules': `"${BRAID_SPECULATION_RULES_PATH}"` };
+    }
+    /** A page the gateway produced, with {@link pageHeaders} on it. */
+    function withPageHeaders(request, page) {
+        const headers = page && !isOpaque(page) ? pageHeaders(request) : null;
+        return headers ? withHeaders(page, headers) : page;
+    }
+    /**
+     * The rules themselves: the pierce patterns of every fragment that asks for speculation, less
+     * those the caller may not list or fetch — as discovery and the namespace keep them out of sight.
+     *
+     * Private whenever the gateway can tell callers apart (a `principal` resolver) or any fragment
+     * has access rules: decided from configuration, so a shared cache never holds a list that a
+     * registry refresh has since made personal. Never stored in development, where nothing is filtered.
+     */
+    async function speculationRulesResponse(request) {
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return new Response(null, { status: 405, headers: { allow: 'GET, HEAD' } });
+        }
+        const manifests = await registry.listFragments();
+        const personal = !isDevelopment && (options.principal !== undefined || manifests.some(hasAccessRules));
+        const principal = personal ? await resolvePrincipal(request) : undefined;
+        const visible = manifests.filter((manifest) => isDevelopment || !hasAccessRules(manifest) || (canList(manifest, principal) && canFetch(manifest, principal)));
+        return new Response(request.method === 'HEAD' ? null : JSON.stringify(speculationRulesFor(visible)), {
+            headers: {
+                'content-type': 'application/speculationrules+json',
+                ...(isDevelopment
+                    ? { 'cache-control': 'no-store' }
+                    : personal
+                        ? { 'cache-control': 'private, no-store', vary: 'cookie, authorization' }
+                        : // short: the registry it comes from refreshes on its own schedule
+                            { 'cache-control': 'public, max-age=60' }),
+            },
+        });
+    }
     /**
      * Handles a request bound for the shell application.
      *
@@ -848,6 +917,8 @@ export function createGateway(options) {
             }
         }
         const shell = await next();
+        if (isOpaque(shell))
+            return shell;
         const isNullBody = shell.status === 204 ||
             shell.status === 205 ||
             shell.status === 304 ||
@@ -893,6 +964,10 @@ export function createGateway(options) {
             cancelFragmentBodies();
             throw error;
         }
+        if (isOpaque(shellResponse)) {
+            cancelFragmentBodies();
+            return shellResponse;
+        }
         const isShellNullBody = shellResponse.status === 204 ||
             shellResponse.status === 205 ||
             shellResponse.status === 304 ||
@@ -1093,7 +1168,7 @@ export function createGateway(options) {
 export function toWebMiddleware(gateway) {
     return async (request, next) => {
         const shellOnce = once(next);
-        return (await gateway.handle(request, shellOnce)) ?? shellOnce();
+        return (await gateway.handle(request, shellOnce)) ?? passThrough(gateway, request, await shellOnce());
     };
 }
 /**
@@ -1113,9 +1188,14 @@ export function toWebMiddleware(gateway) {
 export function toFetchHandler(gateway, appHandler) {
     return async (request) => {
         const shellOnce = once(() => Promise.resolve(appHandler(request)));
-        return (await gateway.handle(request, shellOnce)) ?? shellOnce();
+        return (await gateway.handle(request, shellOnce)) ?? passThrough(gateway, request, await shellOnce());
     };
 }
+/** The app's own response to a request the gateway passed to it, with the gateway's page headers. */
+function passThrough(gateway, request, response) {
+    const headers = isOpaque(response) ? null : gateway.pageHeaders(request);
+    return headers ? withHeaders(response, headers) : response;
+}
 /** Memoizes an async thunk so the wrapped work happens at most once. */
 function once(fn) {
     let pending;
@@ -1244,6 +1324,35 @@ function escapeHtml(value) {
 function appendHop(request) {
     return [request.headers.get(BRAID_VIA_HEADER), 'braid'].filter(Boolean).join(', ');
 }
+/**
+ * A response with nothing to compose or annotate: a browser's opaque redirect (status 0), which is
+ * what a navigation's own `fetch` returns when the shell redirects, or a network error. Neither can
+ * be copied into a new `Response`, and both are for the browser to act on as they are.
+ */
+function isOpaque(response) {
+    return response.status === 0;
+}
+/** A top-level browser navigation: the request a page's own headers are for. */
+function isNavigation(request) {
+    return request.method === 'GET' && request.headers.get('sec-fetch-dest') === 'document';
+}
+/**
+ * The response with these headers set. A response's headers are often immutable (one `fetch`
+ * returned), so it is copied then — the body streams through the copy untouched.
+ */
+function withHeaders(response, headers) {
+    try {
+        for (const [name, value] of Object.entries(headers))
+            response.headers.set(name, value);
+        return response;
+    }
+    catch {
+        const copy = new Response(response.body, response);
+        for (const [name, value] of Object.entries(headers))
+            copy.headers.set(name, value);
+        return copy;
+    }
+}
 /** How many Braid gateways a request has already crossed, from its `x-braid-via` entries. */
 function hopCount(request) {
     const via = request.headers.get(BRAID_VIA_HEADER);
@@ -1274,8 +1383,11 @@ const HOP_BY_HOP_HEADERS = ['connection', 'keep-alive', 'proxy-connection', 'tra
  * Only what the platform `fetch` returned: a function endpoint hands over its own bytes and is
  * trusted to describe them — one that wraps `fetch` must drop these headers itself. On Workers,
  * which would re-encode a passed-through body, this costs the compression of that one hop.
+ *
+ * Where the codings could not be pinned (`codingsPinned` false: a browser, which forbids setting
+ * `accept-encoding`), the browser asked for them and decodes all it asked for, so none is refused.
  */
-function forwardable(response, decodedByFetch) {
+function forwardable(response, decodedByFetch, codingsPinned = true) {
     const encoding = response.headers.get('content-encoding');
     const connection = response.headers.get('connection');
     const reframe = decodedByFetch && encoding !== null;
@@ -1283,7 +1395,7 @@ function forwardable(response, decodedByFetch) {
     // runtime's fetch decoded it varies — Node's decodes zstd — so neither the length nor the coding
     // can be said to describe the body. Refused, the same on every runtime, rather than guessed at.
     const codings = encoding?.split(',').map((coding) => coding.trim().toLowerCase()).filter(Boolean) ?? [];
-    if (reframe && codings.some((coding) => coding !== 'identity' && !FETCH_DECODED_CODINGS.has(coding))) {
+    if (reframe && codingsPinned && codings.some((coding) => coding !== 'identity' && !FETCH_DECODED_CODINGS.has(coding))) {
         void response.body?.cancel();
         return new Response(`braid-gateway: the endpoint answered in content-encoding "${encoding}", which was not requested`, {
             status: 502,