@substrat-run/vertical-host 0.141.0 → 0.143.0

package/dist/invocation-log.js

@@ -1,10 +1,378 @@
 /**
- * The per-request log line and the platform's entry wrapper (#1978).
+ * One structured log line per invocation, carrying the two dimensions Cloudflare
+ * structurally cannot record: which TENANT and which SCOPE a request belonged to
+ * (`docs/architecture/observability.md` §4.2/§4.3).
  *
- * Moving here from the kernel: this is host-side HTTP code that every deployed vertical
- * mounts, and nothing in it needs a kernel guarantee. For one release the definition still
- * lives in `@substrat-run/kernel` and this module re-exports that same binding, so an
- * import from either package is the one function. Import it from here.
+ * ## Why this exists at all
+ *
+ * Observability is keyed on the deployed unit — a worker script — and one vertical's
+ * script serves every tenant that installed it. That makes script-grain data safe for
+ * staff and for the vertical's builder, and unsafe for an installer: their own numbers
+ * are inseparable from everyone else's (§3). The router already stamps `tenantId` on the
+ * datapoints and log lines IT emits, which is why tenant-keyed *metrics* need no code in
+ * this package. Logs are the other half, and the router cannot supply it: a trace does
+ * not cross the dispatch hop. Verified against production — a router line's `traceId`
+ * reaches `substrat-control-plane` (a service binding) but never the dispatched vertical,
+ * and every vertical event is a trace of exactly one event. There is nothing to join on,
+ * so the line has to be emitted on this side.
+ *
+ * ## What it makes possible that nothing else does
+ *
+ * A vertical's successful request emits NO log event whatsoever — the host logs only on a
+ * platform fault, and the scope host logs nothing at all. So before this middleware, a
+ * vertical's entire log presence was its crashes. The stamped line is therefore not only
+ * the correlation key; it is the thing that makes a tenant-facing log view have any rows.
+ *
+ * ## The correlation contract
+ *
+ * Every log line emitted during one invocation shares `$metadata.requestId`, so a reader
+ * resolves a tenant's lines in two phases: filter on `tenantId` to find the invocations,
+ * then fetch every line sharing their request ids. That is what attributes a vertical's
+ * OWN `console.log` output — which carries no tenant of its own — to the tenant whose
+ * request produced it.
+ *
+ * The inverse of that contract is a rule, not an optimisation: a line with no `tenantId`
+ * is never shown to a tenant (§4.3). An un-routed local invocation has no asserted
+ * headers and therefore emits no line — there is no tenant it could be attributed to, and
+ * inventing one is the only way this could ever leak.
+ *
+ * ## The tenant is a VERIFIED assertion, never a header
+ *
+ * Which is why the line is written from `readRoutedNode`'s answer and not from
+ * `headers.get('x-substrat-tenant')`. The two look interchangeable — behind the router
+ * they are — and they are not, for exactly the reason #966 made `readRoutedNode` itself
+ * fail closed: K-26's boundary is that a vertical's script has no public route, and that
+ * is a DEPLOYMENT fact, with `workers.dev` on by default. Reading the header directly
+ * meant anyone who could reach the script could name any tenant they liked and have the
+ * line filed under it — a request the vertical then refuses with a 400, since `nodeFor`
+ * does verify, while this middleware's `finally` had already written the forged line.
+ *
+ * That is not a cosmetic wrong row. The read path uses the stamped line as PROOF that an
+ * invocation was a given tenant's, and admits that invocation's other log lines — which
+ * carry no tenant of their own — into that tenant's view on the strength of it. A forged
+ * stamp is therefore a way to put chosen text on somebody else's dashboard. So the same
+ * verification the vertical does for its own routing happens here, with the same secret
+ * and the same dev opt-out, and a failed one writes nothing at all.
+ */
+// The subpath, not the root: this module is bundled into every vertical's upload (the
+// platform entry, #1893), and the root carries every schema in the vocabulary.
+// The same holds for the kernel, whose two zero-import subpaths this reaches it through.
+import { encodeInvocationRecord, FIELD_COVERAGE_HEADER, INVOCATION_RECORD_HEADER, invocationLevelOf, } from '@substrat-run/contracts/invocation-record';
+import { invocationLine } from '@substrat-run/kernel/invocation-line';
+import { ulid } from '@substrat-run/kernel/ulid';
+import { readRoutedNode, ROUTED_ID, RouterAssertionError } from './routed-node.js';
+/**
+ * The per-request store key the middleware parks its {@link InvocationRecord} under (#1746).
+ * A published name, like `substratInvocationId`: `mountOperations` reads it in another
+ * package, and a vertical's own routes may fill it in too.
+ */
+export const INVOCATION_RECORD_KEY = 'substratInvocationRecord';
+/**
+ * The platform's version binding, read straight off the env.
+ *
+ * The one exception to "bindings only through the options": `SUBSTRAT_VERSION_ID` is not
+ * the vertical's binding to name, the platform attaches it to every pushed script, and a
+ * vertical that had to pass it through would be one more line to forget with no way for
+ * it to be wrong. Read defensively — the env is typed `unknown` here.
+ */
+function versionIdOf(env) {
+    const v = env?.SUBSTRAT_VERSION_ID;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/**
+ * The path, with the query string DISCARDED.
+ *
+ * Not a tidiness choice. A vertical that speaks OIDC carries `code`, `state` and
+ * `id_token_hint` in its query strings, an invite or magic-link flow carries a
+ * single-use token, and the platform's own internal calls carry `tenantId`/`scopeId`.
+ * An access log that swallowed those would put live credentials into a store that is
+ * read by a wider audience than the request ever had, and keep them there for the
+ * backend's whole retention window. Logging the path alone loses nothing a reader
+ * needs: which route ran is the question, and the identifiers are already dimensions.
+ */
+function pathOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        // A URL the runtime accepted but `URL` will not parse is not worth failing over.
+        return '/';
+    }
+}
+/**
+ * The registry of stamps, keyed by the incoming `Request`, on `globalThis` under a GLOBAL
+ * symbol. Global rather than module state, because two copies of this code meet in one
+ * request: the platform's entry (`withInvocationLog`, prebuilt into the upload) and the
+ * copy the vertical bundled (this package, or a kernel from before #1978) — different
+ * module instances, one `Symbol.for`. Weak, so a
+ * finished request's stamp goes with its `Request`.
+ */
+const STAMPS = Symbol.for('substrat.invocation-stamp');
+function stamps() {
+    const g = globalThis;
+    return (g[STAMPS] ??= new WeakMap());
+}
+/**
+ * The stamp a request already carries, if a layer outside this one started it (#1893).
+ * `vertical-host` reads the record through this when the Hono context has none, which is
+ * the case when the platform's entry stamped the request and the vertical mounts nothing.
+ */
+export function invocationStampOf(request) {
+    return stamps().get(request);
+}
+/**
+ * #1923: whether the per-response field walk is armed for this request — the one question the
+ * walk's two callers in `vertical-host` (the operation routes and the MCP door) ask.
+ *
+ * `false` for a request no stamp covers, and for a stamp begun by a layer that predates the
+ * switch: every version skew between the platform's entry and a vertical's bundled copy
+ * reads as off, never as on.
+ */
+export function fieldCoverageArmed(request) {
+    return typeof stamps().get(request)?.fieldCoverageId === 'string';
+}
+function beginStamp(request, env, options) {
+    const stamp = { invocationId: ulid(), record: {} };
+    const fieldCoverageId = armedFieldCoverageId(request.headers, env, options);
+    if (fieldCoverageId)
+        stamp.fieldCoverageId = fieldCoverageId;
+    stamps().set(request, stamp);
+    return stamp;
+}
+/**
+ * #1923: the dispatch id the ROUTER armed the field walk with for this request, or `undefined`.
+ *
+ * The header alone is a claim. It is honoured only when its value is a ULID and the request's
+ * router assertion verifies, with the same secret and the same dev opt-out as the tenant on
+ * the line, because it is trusted for the same reason: the router strips every inbound
+ * `x-substrat-*` header, and a caller that reaches the script some other way holds no secret.
+ * An unrouted request, or one whose assertion fails, is never armed.
+ *
+ * The header is read first, so a request the router did not sample — almost all of them —
+ * pays one header read and no verification.
+ */
+function armedFieldCoverageId(headers, env, options) {
+    let id;
+    try {
+        id = headers.get(FIELD_COVERAGE_HEADER);
+    }
+    catch {
+        return undefined;
+    }
+    if (id === null || !ROUTED_ID.test(id))
+        return undefined;
+    return routedNodeOrNull(headers, env, options) !== null ? id : undefined;
+}
+/**
+ * Write the line for a finished request — the one place it is written, whichever layer
+ * started the stamp.
+ *
+ * No VERIFIED tenant ⇒ no line, and the three ways that happens are all silence here: no
+ * assertion at all (an un-routed call), an assertion this worker cannot verify or that is
+ * not the router's (`RouterAssertionError`), and — defensively — anything else the read
+ * throws. Writing a line for any of them would be filing one caller's request under a
+ * tenant of their choosing.
+ */
+function writeInvocationLine(stamp, done, options) {
+    // Called from a `finally`: a throw here would replace the vertical's answer, or its own
+    // error, with a logging failure. The platform wraps every uploaded script in this (#1893),
+    // so nothing in it may escape — a line that cannot be written is one missing line.
+    try {
+        writeLineOrThrow(stamp, done, options);
+    }
+    catch (e) {
+        try {
+            console.log(JSON.stringify({ substrat: 'invocation-log-fault', detail: String(e) }));
+        }
+        catch {
+            /* the console itself is gone; there is nowhere left to say so */
+        }
+    }
+}
+function writeLineOrThrow(stamp, done, options) {
+    const node = routedNodeOrNull(done.request.headers, done.env, options);
+    if (!node)
+        return;
+    const { record, invocationId } = stamp;
+    const line = invocationLine({
+        tenantId: node.tenantId,
+        scopeId: node.scopeId,
+        vertical: node.verticalSlug,
+        surface: node.surface,
+        method: done.request.method,
+        path: pathOf(done.request.url),
+        status: done.status,
+        threw: done.threw,
+        durationMs: Date.now() - done.started,
+        invocationId,
+        level: invocationLevelOf(done.status, done.threw, record.problemCode),
+        operation: record.operation,
+        problemCode: record.problemCode,
+        principalKind: record.principalKind,
+        ...(record.emitted ? { emitted: record.emitted } : {}),
+        versionId: versionIdOf(done.env),
+        ...(record.outputFields ? { outputFields: record.outputFields } : {}),
+        ...(stamp.fieldCoverageId ? { fieldCoverageId: stamp.fieldCoverageId } : {}),
+    });
+    console.log(JSON.stringify(line));
+}
+/**
+ * Mount as the FIRST middleware on a vertical's app, with the same two answers the
+ * vertical gives `readRoutedNode` in its own `nodeFor`:
+ *
+ * ```ts
+ * const app = new Hono<{ Bindings: Env }>();
+ * app.use(
+ *   '*',
+ *   invocationLog<Env>({
+ *     routerSecret: (env) => env.ROUTER_SECRET,
+ *     allowUnsigned: (env) => env.ALLOW_DEV_NODE === 'true',
+ *   }),
+ * );
+ * ```
+ *
+ * First, because Hono composes handlers in registration order and stops at the one that
+ * returns a response — middleware registered after a route does not wrap that route.
+ *
+ * **Since #1893 the platform stamps every deployed request itself**, by wrapping the
+ * uploaded entry with `withInvocationLog`. A vertical that still mounts this middleware
+ * then finds the request already stamped and steps aside — it hands the platform's stamp
+ * to the handler chain through the context, as it always did, and writes no second line.
+ * Mounted where no platform entry runs (a dev server behind a dev router), it stamps as
+ * before.
+ *
+ * Nothing here can fail a request: the line is written in a `finally`, and a throw from
+ * the handler is re-thrown untouched for `onError` to map as it always did.
+ */
+export function invocationLog(options = {}) {
+    return async (c, next) => {
+        // Stamped already by the platform's entry: pass the stamp down, write nothing.
+        const existing = invocationStampOf(c.req.raw);
+        if (existing) {
+            c.set?.('substratInvocationId', existing.invocationId);
+            c.set?.(INVOCATION_RECORD_KEY, existing.record);
+            await next();
+            return;
+        }
+        // Host code, so a real clock is correct here — `ctx.now()` is the module-code rule,
+        // and this middleware runs outside any operation's transaction.
+        const started = Date.now();
+        // Minted per request, before anything can emit. A ULID so it sorts by time like
+        // every other id on the spine.
+        const stamp = beginStamp(c.req.raw, c.env, options);
+        c.set?.('substratInvocationId', stamp.invocationId);
+        c.set?.(INVOCATION_RECORD_KEY, stamp.record);
+        let threw = false;
+        try {
+            await next();
+        }
+        catch (e) {
+            threw = true;
+            // Always re-thrown: the envelope `mountPlatformSurface` installs is what answers
+            // the caller, and swallowing here would turn a fault into a silent 200.
+            throw e;
+        }
+        finally {
+            writeInvocationLine(stamp, { request: { method: c.req.method, url: c.req.raw.url, headers: c.req.raw.headers }, env: c.env, status: threw ? null : (c.res?.status ?? null), threw, started }, options);
+        }
+    };
+}
+/** The handlers a module worker may export besides `fetch`, passed through untouched. */
+const OTHER_HANDLERS = ['scheduled', 'queue', 'email', 'tail', 'trace', 'alarm', 'test'];
+/**
+ * The platform's half of the stamp (#1893): wrap a module worker's `fetch` so every request
+ * it serves is stamped, whatever framework the worker is written in and whether or not it
+ * mounts the middleware.
+ *
+ * The control plane builds this into the entry it uploads in front of every vertical's
+ * bundle (`platform-entry.generated.ts`), which is what makes the stamp the platform's
+ * rather than a line each vertical has to remember. A request the vertical's own
+ * middleware already stamped — possible only if something wrapped this one — is passed
+ * straight through. The other handlers (`scheduled`, `queue`, …) are passed through
+ * untouched, bound to the worker, since a stamp is about a routed request.
+ *
+ * Nothing here can fail a request: the line is written in a `finally`, and a throw is
+ * re-thrown untouched.
+ */
+export function withInvocationLog(worker, options = {}) {
+    // The platform wraps whatever a bundle's default export is (#1893): a class entrypoint or
+    // no default at all has no `fetch` to stamp, and is handed back untouched.
+    const inner = worker?.fetch;
+    if (typeof inner !== 'function')
+        return worker;
+    const wrapped = {
+        async fetch(request, env, ctx) {
+            if (invocationStampOf(request))
+                return inner.call(worker, request, env, ctx);
+            const started = Date.now();
+            const stamp = beginStamp(request, env, options);
+            let status = null;
+            let threw = false;
+            try {
+                const response = await inner.call(worker, request, env, ctx);
+                status = response.status;
+                handRecordToRouter(response, stamp.record, request, env, options);
+                return response;
+            }
+            catch (e) {
+                threw = true;
+                throw e;
+            }
+            finally {
+                writeInvocationLine(stamp, { request, env, status, threw, started }, options);
+            }
+        },
+    };
+    for (const name of OTHER_HANDLERS) {
+        const h = worker[name];
+        if (typeof h === 'function')
+            wrapped[name] = h.bind(worker);
+    }
+    return wrapped;
+}
+/**
+ * #1904: hand the record back to the router on the response, which meters the request with
+ * it and strips the header before the response leaves (`INVOCATION_RECORD_HEADER`).
+ *
+ * Only on a request the router vouched for: a direct caller gets no header, and the router
+ * is the only reader. Never a throw — a response whose headers are immutable (one passed
+ * straight through from a `fetch`) reached no operation and has nothing to hand back, and
+ * metering must not fail a request either way.
+ */
+function handRecordToRouter(response, record, request, env, options) {
+    try {
+        const value = encodeInvocationRecord(record);
+        if (value === null || !routedNodeOrNull(request.headers, env, options))
+            return;
+        response.headers?.set?.(INVOCATION_RECORD_HEADER, value);
+    }
+    catch {
+        /* immutable headers: see above */
+    }
+}
+/**
+ * The verified node, or `null` — never a throw.
+ *
+ * `readRoutedNode` is deliberately loud: present-but-wrong headers are a
+ * misconfiguration or an attack and a caller that routes on them must hear about it.
+ * This caller does not route on them; it writes a log line in a `finally`, where a throw
+ * would replace the vertical's real answer with a logging failure. So the loudness is
+ * swallowed HERE and only here, and the request is unaffected either way.
  */
-export { invocationLog, INVOCATION_RECORD_KEY, invocationStampOf, withInvocationLog, fieldCoverageArmed, } from '@substrat-run/kernel';
+function routedNodeOrNull(headers, env, options) {
+    try {
+        return readRoutedNode(headers, {
+            expectedSecret: options.routerSecret?.(env),
+            allowUnsigned: options.allowUnsigned?.(env) ?? false,
+        });
+    }
+    catch (e) {
+        // `RouterAssertionError` is the expected shape — a bad, missing or unverifiable
+        // secret, or a malformed id. Anything else would be a bug in the read, and a bug in
+        // the LOGGER must not become a failed request either.
+        if (!(e instanceof RouterAssertionError))
+            console.log(JSON.stringify({ substrat: 'invocation-log-fault', detail: String(e) }));
+        return null;
+    }
+}
 //# sourceMappingURL=invocation-log.js.map

package/dist/invocation-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"invocation-log.js","sourceRoot":"","sources":["../src/invocation-log.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"invocation-log.js","sourceRoot":"","sources":["../src/invocation-log.ts"],"names":[],"mappings":"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"}

package/dist/kick-flags.d.ts

@@ -0,0 +1,9 @@
+import type { ScopeStubOptions } from '@substrat-run/kernel';
+/**
+ * Both kick flags as the stub options that raise them (#1705 PR 2): spread into `getScope`'s
+ * options with the handler's header setter. One call per worker rather than one line per flag,
+ * so a flag added later reaches every vertical that uses this, and not only the ones that
+ * remembered the line. A vertical that skips it still works, and waits for the sweep.
+ */
+export declare function kickFlags(setHeader: (name: string, value: string) => void): Pick<ScopeStubOptions, 'onPlatformRequests' | 'onExportedEvents'>;
+//# sourceMappingURL=kick-flags.d.ts.map

package/dist/kick-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kick-flags.d.ts","sourceRoot":"","sources":["../src/kick-flags.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/C,IAAI,CAAC,gBAAgB,EAAE,oBAAoB,GAAG,kBAAkB,CAAC,CAKnE"}

package/dist/kick-flags.js

@@ -0,0 +1,20 @@
+/**
+ * The two response flags that ask the router for a kick (#1705 PR 2, #1998).
+ *
+ * Here rather than in the kernel since #1998: only a vertical's worker raises them, from the
+ * scope stub's observers, and the header names are contracts' wire vocabulary.
+ */
+import { EXPORTED_EVENTS_HEADER, PLATFORM_REQUEST_HEADER } from '@substrat-run/contracts/wire-headers';
+/**
+ * Both kick flags as the stub options that raise them (#1705 PR 2): spread into `getScope`'s
+ * options with the handler's header setter. One call per worker rather than one line per flag,
+ * so a flag added later reaches every vertical that uses this, and not only the ones that
+ * remembered the line. A vertical that skips it still works, and waits for the sweep.
+ */
+export function kickFlags(setHeader) {
+    return {
+        onPlatformRequests: () => setHeader(PLATFORM_REQUEST_HEADER, '1'),
+        onExportedEvents: () => setHeader(EXPORTED_EVENTS_HEADER, '1'),
+    };
+}
+//# sourceMappingURL=kick-flags.js.map

package/dist/kick-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kick-flags.js","sourceRoot":"","sources":["../src/kick-flags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAGvG;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,SAAgD;IAEhD,OAAO;QACL,kBAAkB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,uBAAuB,EAAE,GAAG,CAAC;QACjE,gBAAgB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,sBAAsB,EAAE,GAAG,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/live.d.ts

@@ -45,9 +45,9 @@
 import type { Context, Env, Hono } from 'hono';
 import { isUpgradeRequest, type LiveReadSurface } from '@substrat-run/kernel';
 /**
- * Is this request asking to be upgraded to a WebSocket? Moving here from the kernel (#1978),
- * which keeps the `LiveReadSurface` contract. For one release the definition still lives in
- * `@substrat-run/kernel` and this is that same binding. Import it from here.
+ * Is this request asking to be upgraded to a WebSocket? Defined in the kernel beside the
+ * `LiveReadSurface` contract, because the hosted adapter's door asks it too (#1978); this is
+ * that same binding, beside the route that asks it first.
  */
 export { isUpgradeRequest };
 /** Where `mountLiveReads` mounts the route unless told otherwise. */

package/dist/live.js

@@ -1,9 +1,9 @@
 import { LIVE_MODE_HEADER } from '@substrat-run/contracts';
 import { isUpgradeRequest } from '@substrat-run/kernel';
 /**
- * Is this request asking to be upgraded to a WebSocket? Moving here from the kernel (#1978),
- * which keeps the `LiveReadSurface` contract. For one release the definition still lives in
- * `@substrat-run/kernel` and this is that same binding. Import it from here.
+ * Is this request asking to be upgraded to a WebSocket? Defined in the kernel beside the
+ * `LiveReadSurface` contract, because the hosted adapter's door asks it too (#1978); this is
+ * that same binding, beside the route that asks it first.
  */
 export { isUpgradeRequest };
 /** Where `mountLiveReads` mounts the route unless told otherwise. */

package/dist/routed-node.d.ts

@@ -1,11 +1,87 @@
+import type { ScopeId, TenantId } from '@substrat-run/contracts';
 /**
- * Reading the node the router asserted (K-26, #1978).
+ * A tenant or scope id: a ULID, exactly what `@substrat-run/contracts`' `tenantId` and
+ * `scopeId` schemas accept (`z.string().regex(ULID).brand()`).
  *
- * Moving here from the kernel: every vertical reads it, and nothing in it needs a kernel
- * guarantee. For one release the definition still lives in `@substrat-run/kernel` and this
- * module re-exports that same binding, so an import from either package is the one
- * function. Import it from here.
+ * Checked with the pattern itself rather than through those schemas since #1893, because
+ * this file is bundled into the platform's entry in front of EVERY deployed vertical
+ * (`withInvocationLog`), and a runtime import of the contracts package pulls all of it —
+ * and zod — into that bundle: 750 KB added to every upload to run one regex. The brands
+ * are types, so they still come from contracts; `routed-node.test.ts` holds this pattern to
+ * those schemas so the two cannot drift.
  */
-export { readRoutedNode, RouterAssertionError } from '@substrat-run/kernel';
-export type { RoutedNode, HeaderReader, ReadRoutedNodeOptions } from '@substrat-run/kernel';
+export declare const ROUTED_ID: RegExp;
+/**
+ * Reading the node the router asserted (K-26).
+ *
+ * The router resolves `hostname → (tenant, scope, surface)` and forwards over a
+ * service binding with that resolution in headers. This is the vertical's side of
+ * that contract, shared because every vertical needs it and none of them should be
+ * re-deriving how to trust it. Here rather than in the kernel since #1978: nothing in it
+ * needs a kernel guarantee.
+ *
+ * Web-standard only and structurally typed: the base tsconfig is `ES2023` with no
+ * DOM lib, deliberately, so no package assumes a browser. Taking the one method we
+ * need rather than the whole `Headers` type keeps that true and costs nothing — a
+ * real `Headers` satisfies it, and so does a plain object in a test.
+ */
+/** The one method this needs from a `Headers`. A real `Headers` satisfies it. */
+export interface HeaderReader {
+    get(name: string): string | null;
+}
+export interface RoutedNode {
+    tenantId: TenantId;
+    scopeId: ScopeId;
+    /** Which app answers: `app`, `storefront`, `back-office`, … Vertical vocabulary. */
+    surface: string;
+    verticalSlug: string | null;
+}
+/** Thrown when headers are present but not trustworthy. Never means "no router". */
+export declare class RouterAssertionError extends Error {
+}
+export interface ReadRoutedNodeOptions {
+    /**
+     * The router's shared secret, as this worker holds it (`ROUTER_SECRET`). When set,
+     * an assertion is trusted only if `x-substrat-router` matches it — always, even
+     * with `allowUnsigned`.
+     */
+    expectedSecret?: string;
+    /**
+     * Accept an assertion nobody signed, when no secret is configured (#966).
+     *
+     * Off by default, and that default is the boundary: a worker deployed without
+     * its secret used to trust any `x-substrat-*` headers it was handed, which is a
+     * forged tenant from anyone who could reach the script directly. Now it refuses
+     * them — loudly, as a `RouterAssertionError` — until the secret is provisioned.
+     *
+     * The one legitimate exception is an un-routed local instance behind a dev
+     * router that has no secret either, which is what `ALLOW_DEV_NODE` already
+     * names; a host sets this from that flag and from nothing else.
+     */
+    allowUnsigned?: boolean;
+}
+/**
+ * The `(tenant, scope)` this request is for, or `null` when no router fronted it.
+ *
+ * Three outcomes, kept distinct on purpose:
+ *
+ *   - **null** — no assertion at all. The caller decides: a single-tenant standalone
+ *     deploy substitutes its own node, anything else refuses.
+ *   - **throws** — headers are present but wrong: a bad or missing secret, a secret
+ *     this worker cannot verify because it holds none, or ids that are not ULIDs.
+ *     Present-but-wrong is a misconfiguration or an attack, and collapsing it into
+ *     `null` would let either one fall through to whatever the caller does for
+ *     "unrouted".
+ *   - **a node** — trustworthy, and the tenant whose data this request may touch.
+ *
+ * `expectedSecret` is what makes the headers trustworthy in code. K-26's real
+ * boundary is that vertical workers have no public route, so the router is the only
+ * possible source — but that is a deployment fact, and `workers.dev` is on by
+ * default. When the secret is configured, a request that did not come from the
+ * router cannot assert a tenant no matter how the routes are configured. When it is
+ * NOT configured the assertion fails closed (#966): an unsigned assertion is refused
+ * unless the host opted in with `allowUnsigned`, so forgetting to provision the
+ * secret is a visible outage rather than an open door.
+ */
+export declare function readRoutedNode(headers: HeaderReader, options?: ReadRoutedNodeOptions): RoutedNode | null;
 //# sourceMappingURL=routed-node.d.ts.map

package/dist/routed-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routed-node.d.ts","sourceRoot":"","sources":["../src/routed-node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"routed-node.d.ts","sourceRoot":"","sources":["../src/routed-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAIjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAA6B,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AAEH,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,oFAAoF;AACpF,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,qBAA0B,GAClC,UAAU,GAAG,IAAI,CA6BnB"}

package/dist/routed-node.js

@@ -1,10 +1,68 @@
+// The subpath, not the root: this file is bundled into the platform's entry (#1893).
+import { secretMatches } from '@substrat-run/contracts/wire-auth';
 /**
- * Reading the node the router asserted (K-26, #1978).
+ * A tenant or scope id: a ULID, exactly what `@substrat-run/contracts`' `tenantId` and
+ * `scopeId` schemas accept (`z.string().regex(ULID).brand()`).
  *
- * Moving here from the kernel: every vertical reads it, and nothing in it needs a kernel
- * guarantee. For one release the definition still lives in `@substrat-run/kernel` and this
- * module re-exports that same binding, so an import from either package is the one
- * function. Import it from here.
+ * Checked with the pattern itself rather than through those schemas since #1893, because
+ * this file is bundled into the platform's entry in front of EVERY deployed vertical
+ * (`withInvocationLog`), and a runtime import of the contracts package pulls all of it —
+ * and zod — into that bundle: 750 KB added to every upload to run one regex. The brands
+ * are types, so they still come from contracts; `routed-node.test.ts` holds this pattern to
+ * those schemas so the two cannot drift.
  */
-export { readRoutedNode, RouterAssertionError } from '@substrat-run/kernel';
+export const ROUTED_ID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/** Thrown when headers are present but not trustworthy. Never means "no router". */
+export class RouterAssertionError extends Error {
+}
+/**
+ * The `(tenant, scope)` this request is for, or `null` when no router fronted it.
+ *
+ * Three outcomes, kept distinct on purpose:
+ *
+ *   - **null** — no assertion at all. The caller decides: a single-tenant standalone
+ *     deploy substitutes its own node, anything else refuses.
+ *   - **throws** — headers are present but wrong: a bad or missing secret, a secret
+ *     this worker cannot verify because it holds none, or ids that are not ULIDs.
+ *     Present-but-wrong is a misconfiguration or an attack, and collapsing it into
+ *     `null` would let either one fall through to whatever the caller does for
+ *     "unrouted".
+ *   - **a node** — trustworthy, and the tenant whose data this request may touch.
+ *
+ * `expectedSecret` is what makes the headers trustworthy in code. K-26's real
+ * boundary is that vertical workers have no public route, so the router is the only
+ * possible source — but that is a deployment fact, and `workers.dev` is on by
+ * default. When the secret is configured, a request that did not come from the
+ * router cannot assert a tenant no matter how the routes are configured. When it is
+ * NOT configured the assertion fails closed (#966): an unsigned assertion is refused
+ * unless the host opted in with `allowUnsigned`, so forgetting to provision the
+ * secret is a visible outage rather than an open door.
+ */
+export function readRoutedNode(headers, options = {}) {
+    const rawTenant = headers.get('x-substrat-tenant');
+    const rawScope = headers.get('x-substrat-scope');
+    if (!rawTenant && !rawScope)
+        return null;
+    const { expectedSecret, allowUnsigned = false } = options;
+    if (expectedSecret) {
+        if (!secretMatches(headers.get('x-substrat-router'), expectedSecret)) {
+            throw new RouterAssertionError('router assertion is not signed by a known router');
+        }
+    }
+    else if (!allowUnsigned) {
+        throw new RouterAssertionError('router assertion cannot be verified: this worker has no ROUTER_SECRET configured');
+    }
+    if (!rawTenant || !rawScope) {
+        throw new RouterAssertionError('router assertion is incomplete');
+    }
+    if (!ROUTED_ID.test(rawTenant) || !ROUTED_ID.test(rawScope)) {
+        throw new RouterAssertionError('router assertion carries a malformed id');
+    }
+    return {
+        tenantId: rawTenant,
+        scopeId: rawScope,
+        surface: headers.get('x-substrat-surface') ?? 'app',
+        verticalSlug: headers.get('x-substrat-vertical'),
+    };
+}
 //# sourceMappingURL=routed-node.js.map