@braidlabs/gateway 0.1.1 → 0.2.0

package/README.md

@@ -141,7 +141,10 @@ runs at most once per request.
   request inside the fragment's namespace. Version mismatches fail in the client as named errors
   — no title-check heuristics.
 - **Fragment documents** (`/__braid/doc/:id/*`): the fragment's HTML prepared for the host page's
-  DOM — exactly what piercing injects, for the client-boot path.
+  DOM — exactly what piercing injects, for the client-boot path. Fetched at the page's route,
+  unless the manifest declares `documentPath` (`/index.html`) for an SPA on a static origin that
+  404s every route. A fragment's redirect here is reported as an error, or — for a fragment that
+  opts in — followed as a page navigation; see [Login redirects](#login-redirects-opt-in).
 - **Fragment assets/data** (`/__braid/frag/:id/*`): forwarded to the endpoint with the prefix
   stripped, so endpoints see the same paths they serve standalone. Redirects pass through
   unfollowed; each fragment gets a manifest-declared timeout budget.
@@ -166,7 +169,10 @@ one created before `</body>`.
 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
-never live in the host realm, not even between parsing and activation.
+never live in the host realm, not even between parsing and activation. The gateway does add
+`<link rel="prefetch">` hints for the fragment's own scripts (inside its shadow root, never inside
+its document) so their downloads start before the client boots it; a prefetch fetches into the
+HTTP cache and never executes anything.
 
 If a fragment can't be server-rendered, the page still renders and the slot is left for the
 client runtime to fill — a transient SSR failure self-heals rather than becoming a visible
@@ -188,6 +194,20 @@ browser, and most CDNs ignore `Vary` on anything but `Accept-Encoding`.
 **No braid URL varies on a request header.** Point a CDN at them and they cache correctly with
 no configuration at all.
 
+### Mounting under a path
+
+A host that shares its domain and does not own the root — `/manage/` behind a load balancer —
+moves the namespaces under its mount. Set the same `basePath` on both sides:
+
+```ts
+createGateway({ registry, basePath: '/manage' }); // serves /manage/__braid/{frag,realm,doc}/…
+initBraid({ basePath: '/manage' });               // host page: requests them there
+```
+
+The gateway then leaves root `/__braid/*` alone. Page URLs are unaffected: `pierce` patterns still
+match the full pathname (`/manage/goals/*`). `serviceWorker`, `discovery`, and
+`telemetry.webVitals` do not support a `basePath` yet, and combining them with one throws.
+
 ### The one thing that does vary
 
 | Header | URL | Response changes to | Why |
@@ -211,6 +231,58 @@ advisory, and many CDNs honor it only for `Accept-Encoding`. Since only *page* U
 and page URLs are usually personalized and uncacheable anyway, the practical advice is simply:
 don't edge-cache pierced pages. See [CDN setup](../../docs/braid-cdn.md).
 
+## Login redirects (opt-in)
+
+A fragment that needs a login answers its document request with a redirect. A browser fetch cannot
+act on that: followed, it dies as a CORS error; told not to follow, it hides where the redirect was
+going. So by default the client reports a named `fragment-fetch` error, and the redirect goes nowhere.
+
+A fragment can opt in to having the page follow it instead:
+
+```ts
+createGateway({
+  registry: [{ id: 'goals', endpoint: 'https://goals.internal/', redirect: 'navigate' }],
+  redirectOrigins: ['https://login.example.com', 'https://*.example.com'],
+  additionalHeaders: (request) => ({ 'x-user': signedIdentityFor(request) }), // see below
+});
+```
+
+For that fragment's `/__braid/doc/` requests the gateway answers a redirect with a `409` carrying the
+target in `x-braid-redirect-location` (never a 3xx, which the browser would hide again), and the
+client navigates the whole page there — what the shell would have done had the redirect hit the
+top-level request. Nothing else changes: other fragments, and the `/__braid/frag/` namespace, keep
+passing redirects through.
+
+**Where it may go.** The target is chosen by the fragment's endpoint and becomes a top-level
+navigation, so it is checked, and anything else is refused with a `502`:
+
+| Target | Result |
+| --- | --- |
+| A path on the host's own origin (including `/__braid/…`, for a login that is itself a fragment) | followed as a host path |
+| A path inside the fragment's own endpoint (`/apps/goals/login` for `https://goals.internal/apps/goals/`) | mapped to the same path on the host (`/login`) |
+| An origin in `redirectOrigins` — exact (`https://login.example.com`) or a subdomain wildcard (`https://*.example.com`, which does not match `example.com` itself) | followed as given |
+| `javascript:`, `data:`, any other scheme, any other origin | refused |
+
+**Return URLs.** A fragment builds `?next=` from the URL it saw, which is its own and means nothing to
+the user. A query parameter whose whole value is that URL (its path, on the fragment's origin or
+the host's; the query is ignored) is pointed at the page the user was on, taken from the
+`x-braid-return-url` header the client sends (the `Referer` header is the fallback, and only a page on
+the gateway's origin is ever used). The header is read by the gateway and not forwarded to the
+fragment, because a page URL can carry a token in its hash. Other parameters keep their exact bytes. Not
+rewritten: a return URL buried inside another parameter's value (an OAuth `state`, say), and a
+parameter equal to the fragment's bare root `/`, which is usually an OAuth `redirect_uri`.
+
+**Concurrent requests are not coalesced** for a fragment that opts in: a redirect's cookies carry the
+login's state and nonce, and sharing one with another caller would share those too.
+
+**The loop.** The gateway strips the caller's cookies by default, so a fragment that redirects
+because it cannot see who the user is will redirect again after login sends them back — forever. The
+client follows a given fragment's redirect at most once per 30 seconds (remembered in
+`sessionStorage`; if that is unavailable it does not follow at all) and reports an error instead.
+It only works end to end once the fragment can see the user: `forwardCredentials`, or a per-caller
+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.
+
 ## Discovery endpoint (optional)
 
 For shells that build their UI from the registry rather than hard-coding slot names — a launcher,
@@ -406,11 +478,16 @@ wants; nothing outlives the request that started it. No TTL, no invalidation, no
 no dependence on which instance a request lands on — which is what makes it safe by default on ECS
 or any horizontally scaled deployment.
 
-Two requests share a fetch only when their `cookie`, `authorization`, `user-agent`, and negotiation
-headers match exactly, and a fragment declaring `access` rules is never shared at all. So this helps
-anonymous and shared-identity traffic and does nothing for personalized fragments — two signed-in
-users never share a flight. That is correct rather than a limitation: sharing a render across
-identities is a data leak wearing a performance feature's clothes.
+The key is computed from the request that is actually **sent**, so it contains exactly what the
+endpoint can see: `user-agent`, the negotiation headers, any header the gateway itself added via
+`additionalHeaders`, and — when `forwardCredentials` is on — `cookie` and `authorization`. A
+fragment declaring `access` rules is never shared at all.
+
+Because credentials are not forwarded by default, two signed-in users produce a byte-identical
+fragment request and *do* share a flight, which is correct: the endpoint cannot tell them apart.
+Turn on `forwardCredentials`, or add a per-caller header, and they stop sharing again. Sharing a
+render across identities the endpoint *can* distinguish is a data leak wearing a performance
+feature's clothes, so anything that varies by caller has to be in the key.
 
 For an endpoint that varies on something the gateway cannot see — a tenant or feature-flag header —
 opt out on the manifest with `coalesce: false`.
@@ -438,20 +515,38 @@ gets unstamped markup, which is correct for all three.
 
 The trusted tier is **namespace isolation, not a security boundary**: fragments are same-origin
 with the host and share its cookies, storage, and DOM reachability. What the gateway does
-guarantee is that nothing a fragment sends can execute JavaScript in the *host realm* or
-navigate the host page — scripts are neutralized, inline `on*` handlers are stripped, and
-`<meta http-equiv="refresh">` is defanged. Fragment code runs in the fragment's realm or not at
-all.
-
-Deliberately not neutralized, because they require a user to act rather than executing on parse:
-`javascript:` URLs and form `action`s. A trusted fragment can navigate a page the user clicks
-through.
+guarantee is that no code a fragment's markup carries inline can execute outside the fragment's
+realm or navigate the host page — with one opt-in exception, [login redirects](#login-redirects-opt-in),
+whose targets are restricted to the host's origin, the fragment's own endpoint, and
+`redirectOrigins` — scripts are neutralized, inline `on*` handlers are stripped,
+`<meta http-equiv="refresh">` is defanged, and frames whose document the markup carries inline
+lose it: `iframe[srcdoc]`, and any `iframe`/`embed`/`object` URL other than `http(s):`, a path, or
+`about:blank` (so `javascript:`, `data:`, `blob:`). `srcdoc` and `javascript:` run on parse with
+the host's origin, no click needed; `data:` and `blob:` are refused alongside them as the same
+markup-as-document shape. Each removal is named on the tag in `data-braid-blocked`. The rule is
+deliberately blunt — it also removes a sandboxed `srcdoc` and a `data:` PDF or SVG in an
+`object` — so serve such content from a URL instead. A frame that loads a document from the
+fragment's own namespace (`<iframe src="widget.html">`) is left alone: it runs the fragment's
+code with the host's origin, which its realm already does. The full list, the trade-offs and the
+workarounds: [What the gateway does to fragment markup](../../docs/braid-fragment-markup.md).
+
+Deliberately not neutralized, because they require a user to click rather than executing on
+parse: `javascript:` URLs on links (`a`, `area`) and form `action`s. A trusted fragment can
+navigate a page the user clicks through.
 
 Defaults worth knowing: `x-forwarded-proto`/`x-forwarded-host` are **overwritten** from the real
 request (opt into passthrough with `trustForwardedHeaders` only behind a proxy you control); an
 endpoint's path is a boundary, so `endpoint: 'https://internal/apps/billing/'` cannot be used to
-reach the rest of that origin; and every request header — including `Cookie` — is forwarded to
-fragment endpoints, so treat a manifest entry as granting that endpoint the user's session.
+reach the rest of that origin; and the caller's `Cookie` and `Authorization` are **not** forwarded
+to fragment endpoints.
+
+That last one is the trust boundary between a shell and the fragments it composes. Those headers
+authenticate the caller to *the shell's* origin, and a fragment endpoint is frequently a different
+team and often a different company — forwarding them would let every fragment backend act as that
+user against the shell. A fragment that needs to know who is asking should be given something
+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.
 
 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.1.1",
+  "version": "0.2.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",
@@ -41,4 +41,4 @@
     "url": "https://github.com/braidjs/braid/issues"
   },
   "module": "./src/index.js"
-}
+}

package/src/gateway.d.ts

@@ -2,26 +2,34 @@ import { Principal, RegistrySource } from './registry.js';
 import { DiscoveryOptions } from './discovery.js';
 import { type BreakerOptions } from './breaker.js';
 import { type TelemetryOptions } from './telemetry.js';
-/**
- * Gateway core: fetch-native, platform-neutral origin-front middleware.
- *
- * Two responsibilities:
- *
- * 1. **Namespace routing**: requests under `/__braid/frag/:id/*` address a fragment by id,
- *    exactly — realm stubs, assets, and data. No pattern matching, no request sniffing.
- * 2. **Piercing**: for document requests whose page URL a fragment declares in its
- *    `pierce` patterns, the fragment's server-rendered HTML is interleaved into the shell's
- *    response stream, so fragments paint with the shell's first response.
- *
- * Everything else passes through to the shell untouched.
- */
 export interface GatewayOptions {
     /** The fragment registry: inline manifests, a JSON URL, or an async loader. */
     registry: RegistrySource;
     /** 'development' enables verbose error bodies; defaults to 'development'. */
     mode?: 'production' | 'development';
-    /** Additional headers set on every request forwarded to a fragment endpoint. */
-    additionalHeaders?: Record<string, string>;
+    /**
+     * Additional headers set on every request forwarded to a fragment endpoint.
+     *
+     * A function is called once per fragment request with the *incoming* request, for headers that
+     * describe the current caller — a signed identity assertion, a trace id, a tenant id. A plain
+     * object is read once at construction, so anything per-request has to be the function form.
+     */
+    additionalHeaders?: Record<string, string> | ((request: Request) => Record<string, string>);
+    /**
+     * Forward the caller's `Cookie` and `Authorization` headers to fragment endpoints.
+     *
+     * **Off by default, deliberately.** A fragment endpoint is a URL from the registry — frequently
+     * a different team, often a different company, sometimes a different network. `Cookie` and
+     * `Authorization` authenticate the caller to *the shell's* origin, so forwarding them hands
+     * every fragment backend the ability to act as that user against it. That is the whole trust
+     * boundary between a host and the fragments it composes.
+     *
+     * A fragment that needs to identify the caller should be given something scoped to it: an
+     * 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.
+     */
+    forwardCredentials?: boolean;
     /**
      * 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.
@@ -144,6 +152,29 @@ export interface GatewayOptions {
      * on an origin it does not own.
      */
     serviceWorker?: boolean | ServiceWorkerOptions;
+    /**
+     * 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
+     * gateway stops answering them at the root. Pass the same value to `initBraid({ basePath })` in
+     * the host page.
+     *
+     * Only the namespaces move. Page URLs are untouched: `pierce` patterns still match the full
+     * pathname, and bound fragments are still fetched at it.
+     *
+     * Not yet supported together with `serviceWorker`, `discovery`, or `telemetry.webVitals`, which
+     * would otherwise keep serving at the root; combining them throws.
+     */
+    basePath?: string;
+    /**
+     * Origins a fragment with `redirect: 'navigate'` may send the page to, beyond the host's own
+     * origin and the fragment's own endpoint path — typically an identity provider.
+     *
+     * Exact origins (`https://login.example.com`) or a subdomain wildcard (`https://*.example.com`,
+     * which matches `a.example.com` and `a.b.example.com` but not `example.com` itself). A redirect to
+     * anywhere else is refused with a 502 rather than followed: it ends up as a top-level navigation,
+     * and the fragment's endpoint should not be able to choose where the whole page goes.
+     */
+    redirectOrigins?: string[];
 }
 export interface ServiceWorkerOptions {
     /** The scope to claim, sent as `Service-Worker-Allowed`. Defaults to `/`. */