@antasphere/chassis-server 1.1.0 → 1.3.0

package/src/mcp/webhooks.ts

@@ -0,0 +1,370 @@
+import { z } from 'zod';
+import {
+  webhookDeliveryStatusSchema,
+  webhookEventPatternSchema,
+  webhookFiltersSchema,
+  webhookUrlSchema
+} from '@antasphere/chassis-contract';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { deny, jsonText, wrapToolErrors, type ErrorHints, type ToolTextResult } from './errors.js';
+import {
+  callApi,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext,
+  type ScopeCheck
+} from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+
+/**
+ * The eleven WEBHOOK tools (PRDCT-3482), registered by the chassis right after
+ * the team reads and only when the tool declares a webhooks scope: a webhook
+ * is a chassis concept (a URL a workspace registers to be told, by a signed
+ * POST, when one of the tool's events happens), so the tools over it are the
+ * chassis'. Thin shims over the instance's own /api/v1/webhooks called
+ * IN-PROCESS with the caller's bearer forwarded verbatim: the API's
+ * fail-closed scope allowlist, its owner-or-admin rule and its 404 for an
+ * endpoint of another workspace apply unchanged.
+ *
+ * Every tool pre-checks the tool's webhooks scope, except the catalog, which
+ * is a read (every non-guest member's, under the read scope). Nothing here
+ * names a tool, a brand or a domain: the prefix arrives as
+ * `identity.toolPrefix`, the event types as the instance's catalog.
+ */
+
+/** What a webhook IS, opening the descriptions. */
+const WHAT_IS_A_WEBHOOK =
+  'A webhook is a URL an organization registers to be told, by a signed HTTP POST, when something ' +
+  'happens (for example `thing.created`).';
+
+/** Who manages them. */
+const WHO_MANAGES = 'Only an owner or an admin of the organization manages webhooks, reads included.';
+
+/** How the `events` list of an endpoint reads. */
+const EVENT_PATTERNS =
+  'Each entry of `events` is an exact event type (`thing.created`), a family (`thing.*`) or ' +
+  'everything (`*`).';
+
+/**
+ * The webhook code only the webhook routes answer, merged into the instance's
+ * hint table by `composeErrorHints` like the project hints. The codes the
+ * webhook routes SHARE with the rest of the instance (`forbidden`,
+ * `demo_session`, `plan_required`) are worded for webhooks on the webhook
+ * tools alone ({@link webhookToolHints}): in the instance's table they would
+ * misread every other route's refusal.
+ */
+export function webhookErrorHints(toolPrefix: string): ErrorHints {
+  return {
+    url_refused:
+      'This instance does not deliver to that address. Refused: a scheme other than http or https ' +
+      '(https only on the cloud), a URL carrying a user name or password, a port other than the ' +
+      'scheme’s default, and an address that is not on the public internet (localhost, a private or ' +
+      'link-local network), unless the operator of a self-hosted instance opened private networks. ' +
+      `Use a public address of the receiver, then call ${toolPrefix}create_webhook or ` +
+      `${toolPrefix}update_webhook again.`,
+    unknown_event:
+      'One of the `events` entries is not an event type or family this instance delivers. ' +
+      `Read ${toolPrefix}webhook_events for the exact types; a family is its first word plus \`.*\`.`,
+    unknown_subject:
+      'One of the `filters` keys is not a subject this instance declares. ' +
+      `The subject keys are in ${toolPrefix}webhook_events (for example \`project\`).`
+  };
+}
+
+/** The shared codes, worded for the webhook tools only (layered over the instance's table there). */
+function webhookToolHints(toolPrefix: string): ErrorHints {
+  return {
+    forbidden:
+      'Only an owner or an admin of the organization manages webhooks, reads included. Ask one of ' +
+      `them to make the change, or to read the endpoints (${toolPrefix}webhook_events stays open to ` +
+      'every member).',
+    demo_session:
+      'This connection was opened by a demonstration link, which may not set up webhooks. A person ' +
+      'signed in with their own account must do it.',
+    plan_required:
+      'The organization’s plan does not include this — the upgrade link in this message is where a ' +
+      'human raises it; nothing was created.'
+  };
+}
+
+const webhookIdInput = z
+  .uuid()
+  .describe('The webhook id, from the webhook list or the create answer (never its URL).');
+
+const deliveryIdInput = z.uuid().describe('The delivery id, from the delivery list of this webhook.');
+
+const urlInput = webhookUrlSchema.describe(
+  'Where the deliveries go: a public http or https URL without credentials (https only on the cloud).'
+);
+
+const eventsInput = z
+  .array(webhookEventPatternSchema)
+  .min(1)
+  .max(50)
+  .describe(`What the endpoint subscribes to. ${EVENT_PATTERNS}`);
+
+const descriptionInput = z.string().max(200).describe('A short note on what the endpoint is for.');
+
+const filtersInput = webhookFiltersSchema.describe(
+  'Narrows the subscription by subject: a subject key of the catalog (its `subjects[].key`) mapped to ' +
+    'the ids it accepts, AND across keys, OR within a key; an event that does not carry a filtered ' +
+    'subject does not match. An empty object filters nothing.'
+);
+
+const enabledInput = z.boolean().describe('false pauses the deliveries without deleting the endpoint.');
+
+/** Register the eleven webhook tools on a server, after the team reads. */
+export function registerWebhookTools(
+  server: McpServer,
+  ctx: McpToolContext,
+  identity: McpIdentity,
+  scopes: McpScopes,
+  checkScope: ScopeCheck<string>,
+  hints: ErrorHints
+): void {
+  const webhooksScope = scopes.webhooks;
+  if (!webhooksScope) return;
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+  const prefix = identity.toolPrefix;
+  const t = (name: string) => `${prefix}${name}`;
+  const toolHints: ErrorHints = { ...hints, ...webhookToolHints(prefix) };
+
+  const run = (
+    scope: string,
+    workspace: string | undefined,
+    body: (c: McpToolContext) => Promise<unknown>
+  ): Promise<ToolTextResult> => {
+    const denied = checkScope(ctx.principal, scope);
+    if (denied) return Promise.resolve(denied);
+    const c = forWorkspace(ctx, workspace);
+    return wrapToolErrors(async () => jsonText(await body(c)), toolHints);
+  };
+
+  const send = (method: string, value?: unknown): RequestInit =>
+    value === undefined
+      ? { method }
+      : { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(value) };
+
+  const base = '/api/v1/webhooks';
+
+  // ── The catalog: a read ──────────────────────────────────────────────────
+
+  server.registerTool(
+    t('webhook_events'),
+    {
+      description:
+        `The event catalog of this instance: every event type it delivers to webhooks. ${WHAT_IS_A_WEBHOOK} ` +
+        'Returns { subjects: [{ key, field, description }], events: [{ type, description, subjects, ' +
+        'schema }] } — `subjects` are what an event is about (the key a filter uses, and the field of ' +
+        'the envelope’s `subjects` its value is written under: one id or a list of ids), `schema` is ' +
+        'the JSON Schema of the event’s `data`. ' +
+        `${EVENT_PATTERNS} Read this before ${t('create_webhook')}. Every member may read it.`,
+      inputSchema: { workspace: workspaceInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace }) => run(scopes.read, workspace, (c) => callApi(c, `${base}/events`))
+  );
+
+  // ── Endpoints ────────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhooks'),
+    {
+      description:
+        `List the organization’s webhooks, newest first. ${WHAT_IS_A_WEBHOOK} ${WHO_MANAGES} Returns ` +
+        '{ webhooks: [{ id, url, description, events, filters, enabled, createdBy, createdAt, ' +
+        'updatedAt, disabledAt, disabledReason, consecutiveFailures, lastDeliveryAt, ' +
+        'lastDeliveryStatus, previousSecretExpiresAt }], nextCursor } — never a signing secret. ' +
+        '`disabledAt` is set when the instance switched the endpoint off after failing too long. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: { workspace: workspaceInput, limit: limitInput, cursor: cursorInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, pageQuery(base, { cursor, limit })))
+  );
+
+  server.registerTool(
+    t('create_webhook'),
+    {
+      description:
+        `Register a webhook — confirm with the user first (URL and events included). ${WHAT_IS_A_WEBHOOK} ` +
+        `${WHO_MANAGES} ${EVENT_PATTERNS} The types are checked against ${t('webhook_events')}, and ` +
+        'the keys of `filters` are the catalog’s subject keys. The answer is the endpoint plus its ' +
+        'signing `secret` (`whsec_…`), shown ONCE and never again: give it to the receiver, which ' +
+        'verifies every delivery’s Standard Webhooks signature with it, and never store it anywhere ' +
+        `else. A lost secret is replaced by ${t('rotate_webhook_secret')}.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        url: urlInput,
+        events: eventsInput,
+        description: descriptionInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, url, events, description, filters, enabled }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(
+          c,
+          base,
+          send('POST', {
+            url,
+            events,
+            ...(description !== undefined ? { description } : {}),
+            ...(filters !== undefined ? { filters } : {}),
+            ...(enabled !== undefined ? { enabled } : {})
+          })
+        )
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook'),
+    {
+      description:
+        `Read one webhook, without its secret. ${WHO_MANAGES} Returns the endpoint as ` +
+        `${t('list_webhooks')} shows it. A webhook of another organization answers not found.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`))
+  );
+
+  server.registerTool(
+    t('update_webhook'),
+    {
+      description:
+        'Change a webhook’s URL, description, events, filters or enabled switch — confirm with the ' +
+        `user first. ${WHO_MANAGES} Send only the fields you are changing; \`events\` and \`filters\` ` +
+        `REPLACE the whole list or object. ${EVENT_PATTERNS} Setting enabled back to true resumes an ` +
+        'endpoint the instance switched off. The secret is unchanged. Returns the endpoint as it now is.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        url: urlInput.optional(),
+        description: descriptionInput.optional(),
+        events: eventsInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, webhookId, url, description, events, filters, enabled }) => {
+      const patch = { url, description, events, filters, enabled };
+      if (Object.values(patch).every((v) => v === undefined)) {
+        return deny(
+          'Nothing to change: pass at least one of url, description, events, filters or enabled. ' +
+            `Read the webhook first (${t('get_webhook')}) if you need its current values.`
+        );
+      }
+      const body = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+      return run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('PATCH', body)));
+    }
+  );
+
+  server.registerTool(
+    t('delete_webhook'),
+    {
+      description:
+        'Delete a webhook and its whole delivery history — confirm with the user first; nothing more ' +
+        `is sent to it and this cannot be undone. ${WHO_MANAGES} To pause it instead, call ` +
+        `${t('update_webhook')} with enabled set to false. Returns a last snapshot of the deleted endpoint.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { destructiveHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('DELETE')))
+  );
+
+  server.registerTool(
+    t('rotate_webhook_secret'),
+    {
+      description:
+        'Replace a webhook’s signing secret — confirm with the user first. ' +
+        `${WHO_MANAGES} The answer is the endpoint plus its new \`secret\` (\`whsec_…\`), shown ONCE: ` +
+        'give it to the receiver and never store it anywhere else. The previous secret keeps signing ' +
+        'until `previousSecretExpiresAt`, so the receiver can switch without a gap.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/rotate-secret`, send('POST')))
+  );
+
+  server.registerTool(
+    t('test_webhook'),
+    {
+      description:
+        'Send a signed `webhook.ping` to a webhook now, once, and answer how it went. ' +
+        `${WHO_MANAGES} Returns { delivery: { id, eventId, eventType, status, attempt, ` +
+        'lastStatusCode, lastError, … } } — `status` is `delivered` when the receiver answered 2xx, ' +
+        '`failed` otherwise, with `lastStatusCode` and `lastError` saying why. A ping is never retried.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/test`, send('POST')))
+  );
+
+  // ── Deliveries ───────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhook_deliveries'),
+    {
+      description:
+        `List a webhook’s deliveries, newest first, optionally by status. ${WHO_MANAGES} A delivery ` +
+        'is one event sent to this endpoint, with its attempts. Returns { deliveries: [{ id, ' +
+        'endpointId, eventId, eventType, status, attempt, lastStatusCode, lastError, nextAttemptAt, ' +
+        'deliveredAt, createdAt, updatedAt, payload }], nextCursor } — `eventId` is the receiver’s ' +
+        'dedupe key, `lastStatusCode` and `lastError` describe the latest attempt only. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        status: webhookDeliveryStatusSchema
+          .optional()
+          .describe(
+            '`pending` (waiting for an attempt or a retry), `delivered`, `failed`, or `held` (out of ' +
+              'retries, kept for a redelivery).'
+          ),
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, status, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, pageQuery(`${base}/${webhookId}/deliveries`, { cursor, limit }, { status }))
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook_delivery'),
+    {
+      description:
+        `Read one delivery of a webhook, with the payload as sent and its latest attempt. ${WHO_MANAGES} ` +
+        `Returns the delivery as ${t('list_webhook_deliveries')} shows it.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}`))
+  );
+
+  server.registerTool(
+    t('redeliver_webhook'),
+    {
+      description:
+        'Send one delivery’s event to its webhook again, as a new delivery — confirm with the user ' +
+        `first. ${WHO_MANAGES} The new delivery carries the same \`eventId\` (the receiver’s dedupe key) ` +
+        'and the same payload, and is queued: read its outcome later with ' +
+        `${t('get_webhook_delivery')}. Returns the new delivery.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}/redeliver`, send('POST'))
+      )
+  );
+}

package/src/members/removal.ts

@@ -12,6 +12,7 @@ import {
   workspaceTeamMembers,
   type DbConn
 } from '@antasphere/chassis-db';
+import type { WebhookEmitter } from '../webhooks/service.js';
 
 /**
  * The membership an ADD hangs a right on, re-read inside the add's own
@@ -67,10 +68,29 @@ export interface RemovedMembership {
  * audit record.
  */
 export type MembershipRemovalHook = (
+  tx: DbConn,
+  removed: readonly RemovedMembership[],
+  ctx: MembershipRemovalContext
+) => Promise<Record<string, number>>;
+
+/** What the tool's hook receives beside the rows: the webhooks' emitter, to report what it ended inside the same transaction (PRDCT-3483). */
+export interface MembershipRemovalContext {
+  webhooks: WebhookEmitter;
+}
+
+/** The hook as the chassis calls it, the context bound at boot (`bindMembershipRemoval`). */
+export type BoundMembershipRemoval = (
   tx: DbConn,
   removed: readonly RemovedMembership[]
 ) => Promise<Record<string, number>>;
 
+export function bindMembershipRemoval(
+  hook: MembershipRemovalHook | undefined,
+  ctx: MembershipRemovalContext
+): BoundMembershipRemoval | undefined {
+  return hook ? (tx, removed) => hook(tx, removed, ctx) : undefined;
+}
+
 export interface RemovalCounts {
   projectGrants: number;
   teamSeats: number;
@@ -127,7 +147,7 @@ export interface RemovalCounts {
 export async function deleteMembershipGrants(
   tx: DbConn,
   removed: readonly RemovedMembership[],
-  toolHook?: MembershipRemovalHook
+  toolHook?: BoundMembershipRemoval
 ): Promise<RemovalCounts> {
   if (removed.length === 0) {
     return { projectGrants: 0, teamSeats: 0, invitations: 0, demoPasses: 0, tool: {} };

package/src/middleware/idempotency.ts

@@ -69,7 +69,9 @@ const TARGET_PATHS = new Set([
   '/api/v1/api-keys',
   '/api/v1/invitations',
   '/api/v1/workspaces',
-  '/api/v1/projects'
+  '/api/v1/projects',
+  // A retried registration answers the first one's secret, never a second endpoint (PRDCT-3482).
+  '/api/v1/webhooks'
 ]);
 // The two member routes that MINT a credential for another user. Both are
 // covered (FUZZ-7): a replayed mint hands out a second live secret, and the

package/src/middleware/index.ts

@@ -31,3 +31,14 @@ export { MAX_JSON_DEPTH, exceedsJsonDepth, jsonDepthLimit } from './json-depth.j
 export { noStoreAuthenticated } from './no-store.js';
 export { isPublicOauthPath, oauthPublicEndpoints } from './oauth-public.js';
 export { buildCsp, hstsValue, inlineScriptHashes, securityHeaders } from './security-headers.js';
+export {
+  IMMUTABLE_ASSET_PREFIX,
+  IMMUTABLE_CACHE_CONTROL,
+  REVALIDATE_CACHE_CONTROL,
+  type SpaFallback,
+  type StaticAssetsOptions,
+  acceptedEncodings,
+  loadSpaFallback,
+  staticAssets,
+  staticCacheControl
+} from './static-assets.js';

package/src/middleware/scopes.ts

@@ -30,6 +30,14 @@ export interface ScopeAllowlistOptions<S extends string> {
   write: S;
   /** The tool's dedicated opt-in scope for the full-workspace export. */
   dataExport: S;
+  /**
+   * The tool's dedicated opt-in scope for the webhooks family (PRDCT-3482):
+   * registering an endpoint is a standing read of the workspace to a URL of
+   * the caller's choice, so no read or write key opens it. Absent: no
+   * machine principal reaches `/webhooks` at all (the catalog read stays
+   * under the read scope).
+   */
+  webhooks?: S | undefined;
   /** The tool's own rules, asked in order AFTER the chassis rules. */
   rules: ReadonlyArray<ScopeRule<S>>;
 }
@@ -89,6 +97,7 @@ export function createScopeAllowlist<S extends string>({
   read,
   write,
   dataExport,
+  webhooks,
   rules
 }: ScopeAllowlistOptions<S>): (path: string, method: string) => S | null {
   return function requiredScopeFor(path: string, method: string): S | null {
@@ -130,6 +139,11 @@ export function createScopeAllowlist<S extends string>({
     // Teams: the same discipline (above).
     const team = teamAccess(path, method);
     if (team !== null) return team === 'read' ? read : write;
+    // Webhooks (PRDCT-3482): the catalog is a read any key may make; the
+    // family itself, reads included, needs the tool's dedicated scope, and
+    // closes entirely when the tool declares none.
+    if (path === '/api/v1/webhooks/events' && isRead) return read;
+    if (path === '/api/v1/webhooks' || path.startsWith('/api/v1/webhooks/')) return webhooks ?? null;
     for (const rule of rules) {
       const needed = rule(path, method, isRead);
       if (needed !== null) return needed;

package/src/middleware/static-assets.ts

@@ -0,0 +1,144 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * The dashboard build, served so the browser keeps it (PRDCT-3584).
+ *
+ * Before this middleware the SPA's files went out with no `Cache-Control`,
+ * no validator and no compression: every visit to a tool re-downloaded the
+ * whole dashboard (about 1.2 MB of JavaScript in a hundred files on the
+ * team stack, measured 2026-10-17), and the splash the person stared at
+ * was that download. Two rules fix it, both on the build's own shape:
+ *
+ *  - `/_app/immutable/*` is CONTENT-HASHED by SvelteKit: a changed file has a
+ *    new name, so the cached copy can never be stale. It is served with
+ *    `public, max-age=31536000, immutable`: a second visit transfers none of
+ *    it. Every other static path (the HTML, the icons, the manifest) is
+ *    `no-cache`: kept, but revalidated on every use, so a release reaches
+ *    the browser on its next load.
+ *  - A `.br`, `.zst` or `.gz` sibling written at build time (the dashboard's
+ *    adapter has `precompress: true`) is served in place of the file when
+ *    the request accepts that encoding, with `Content-Encoding` and `Vary:
+ *    Accept-Encoding`. The server compresses nothing at runtime, and the
+ *    API is untouched: this middleware runs on the static files alone,
+ *    after every credentialed route has answered.
+ *
+ * Nothing here is a security input. `immutable` never reaches a response
+ * that is not a hashed asset, so no user-bearing answer can be cached; the
+ * authenticated JSON keeps its `no-store` (middleware/no-store.ts).
+ */
+
+/** The content-hashed prefix of a SvelteKit build. */
+export const IMMUTABLE_ASSET_PREFIX = '/_app/immutable/';
+export const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+export const REVALIDATE_CACHE_CONTROL = 'no-cache';
+
+/** The `Cache-Control` a static path of the build is served with. */
+export function staticCacheControl(requestPath: string): string {
+  return requestPath.startsWith(IMMUTABLE_ASSET_PREFIX) ? IMMUTABLE_CACHE_CONTROL : REVALIDATE_CACHE_CONTROL;
+}
+
+export interface StaticAssetsOptions {
+  /** The directory holding the built dashboard (`index.html`, `_app/`). */
+  publicDir: string;
+}
+
+/**
+ * Serve `publicDir` with the cache policy above and the precompressed
+ * siblings. Falls through (`next()`) on a path that is not a file there, so
+ * the SPA fallback behind it answers the application routes.
+ */
+export function staticAssets(options: StaticAssetsOptions): MiddlewareHandler {
+  const serve = serveStatic({ root: options.publicDir, precompressed: true });
+  return async (c, next) => {
+    // The application's HTML itself (`/`, `/index.html`) is the SPA
+    // fallback's to answer, with its validator and its sibling; the static
+    // server would hand it out with neither (verifier round 2).
+    if (c.req.path === '/' || c.req.path === '/index.html') return next();
+    const res = await serve(c, next);
+    // serveStatic answers a Response for a file it found and the result of
+    // `next()` otherwise; only the file gets the policy.
+    if (res instanceof Response) {
+      res.headers.set('Cache-Control', staticCacheControl(c.req.path));
+      if (!res.headers.has('Vary')) res.headers.set('Vary', 'Accept-Encoding');
+    }
+    return res;
+  };
+}
+
+// ── The SPA fallback ────────────────────────────────────────────────────────
+
+/** The encodings a precompressed sibling may carry, in the order they are preferred. */
+const FALLBACK_ENCODINGS = [
+  { name: 'br', ext: '.br' },
+  { name: 'gzip', ext: '.gz' }
+] as const;
+type FallbackEncoding = (typeof FALLBACK_ENCODINGS)[number]['name'];
+
+/** The encodings a request accepts, read from `Accept-Encoding` with any `;q=` weight ignored. */
+export function acceptedEncodings(header: string | undefined): Set<string> {
+  return new Set(
+    (header ?? '')
+      .split(',')
+      .map((part) => part.split(';')[0]!.trim().toLowerCase())
+      .filter(Boolean)
+  );
+}
+
+export interface SpaFallback {
+  /** The strong ETag of the plain HTML (the variants derive theirs from it). */
+  readonly etag: string;
+  /** Answer the application's HTML for a route the build has no file for. */
+  respond(c: Context): Response;
+}
+
+/**
+ * The application's HTML under any route the build has no file for, served
+ * with the two things the bare `c.html()` lacked (the tier 1 verifier's two
+ * caveats, PRDCT-3584): a strong `ETag` so `no-cache` means "revalidate"
+ * (a `304` costs no bytes), and the `.br` / `.gz` sibling of `index.html`
+ * when the build wrote one and the request accepts it, so a deep link costs
+ * the same as the root on a front that compresses nothing (Cloud Run, a
+ * self-hosted instance with no proxy). The HTML is read once at boot, like
+ * `indexHtml` itself.
+ */
+export async function loadSpaFallback(publicDir: string, html: string): Promise<SpaFallback> {
+  const plain = Buffer.from(html, 'utf8');
+  const etag = `"${createHash('sha256').update(plain).digest('base64url').slice(0, 27)}"`;
+  const variants = new Map<FallbackEncoding, Buffer>();
+  for (const { name, ext } of FALLBACK_ENCODINGS) {
+    try {
+      variants.set(name, await readFile(join(publicDir, `index.html${ext}`)));
+    } catch {
+      // no sibling of that encoding: the plain HTML answers those requests
+    }
+  }
+  return {
+    etag,
+    respond(c) {
+      const accepted = acceptedEncodings(c.req.header('accept-encoding'));
+      const encoding = FALLBACK_ENCODINGS.find((e) => accepted.has(e.name) && variants.has(e.name))?.name;
+      // One validator per representation: a cached brotli body is never
+      // confirmed against a plain one.
+      const variantEtag = encoding ? etag.replace(/"$/, `-${encoding}"`) : etag;
+      // The type rides the 304 too: the node server would otherwise stamp a
+      // text/plain default on it (verifier round 2), and RFC 9110 allows the
+      // 304 to repeat what the 200 carries.
+      const headers: Record<string, string> = {
+        'Cache-Control': REVALIDATE_CACHE_CONTROL,
+        'Content-Type': 'text/html; charset=utf-8',
+        ETag: variantEtag,
+        Vary: 'Accept-Encoding'
+      };
+      if (c.req.header('if-none-match') === variantEtag) {
+        return c.body(null, 304, headers);
+      }
+      if (encoding) headers['Content-Encoding'] = encoding;
+      const body = encoding ? variants.get(encoding)! : plain;
+      return c.body(new Uint8Array(body), 200, headers);
+    }
+  };
+}