@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

package/apps/storefront/src/middleware/routeBranch.ts

@@ -0,0 +1,192 @@
+/**
+ * Which of the three middleware branches serves this request.
+ *
+ * The TIER answer is F2's, carried by `resolvePublicationRoutePlanV1`, and is
+ * never re-derived here. This module only maps that one answer onto the three
+ * serving shapes the Worker actually has, and applies the literal path tables
+ * that correct the resolver's deliberate fail-closed over-restriction of
+ * platform-reserved paths.
+ *
+ * Those tables are NOT a second classification. Every reserved path already has
+ * one answer (Tier 3, authorization required) and these do not change it: they
+ * only say HOW three fixed sets of reserved paths are served, because "run the
+ * control plane" is the wrong shape for all three.
+ *
+ *   - {@link PLATFORM_STATIC_ASSET_PREFIXES} — built and public/ bytes. Identical
+ *     for every visitor, no tenant state at all. Serving them through origin
+ *     compute is exactly what ADR 0013 exists to prevent.
+ *   - {@link PLATFORM_PUBLIC_DISCOVERY_PATHS} — robots/sitemap/llms. Anonymous-
+ *     identical, but rendered from the tenant's own catalog + content, so they
+ *     are not raw bytes; they are ordinary Tier 0 public output that happens to
+ *     live on a reserved mount.
+ *   - {@link PLATFORM_PUBLIC_APP_ROUTE_PREFIXES} — the app's own catalog browse
+ *     pages. Reserved so a tenant mount cannot claim them, which is a different
+ *     question from who may read them: they are the storefront's most public
+ *     surface, and `isCacheablePath` already whitelists the same set.
+ *
+ * Contract: docs/architecture/decisions/0013-public-serving-contract.md
+ */
+import {
+  resolvePublicationRoutePlanV1,
+  type PublicationRoutePlanV1,
+  type PublicationRouteRedirectPlanV1,
+  type RouteTierIndexV1,
+  type ResolvedRouteTierV1,
+} from "@tot/public-runtime";
+
+/**
+ * The three serving shapes.
+ *
+ *   static-passthrough — platform bytes; `next()` and baseline headers, nothing else.
+ *   public-render      — anonymous tenant output; no D1 read at request time.
+ *   control-plane      — authorization-gated; admin, API, preview, the dev loop.
+ */
+export type MiddlewareBranchV1 = "static-passthrough" | "public-render" | "control-plane";
+
+/**
+ * Built output and `public/` roots. Reached by the Worker only where the
+ * platform's static handler did not already answer them (plain `astro dev`, the
+ * local runner); serving them from the render chain would put origin compute in
+ * front of bytes that never vary.
+ */
+export const PLATFORM_STATIC_ASSET_PREFIXES = [
+  "/_astro",
+  "/apps",
+  "/assets",
+  "/brand",
+  "/favicon.svg",
+  "/js",
+  "/platform",
+  "/shared",
+] as const;
+
+/**
+ * Per-tenant discovery documents. Every one is generated from `locals.tot` +
+ * `locals.content` (see src/pages/robots.txt.ts, sitemap.xml.ts, llms.txt.ts),
+ * so they need the public render chain — they are not static bytes and cannot be
+ * passed through.
+ */
+export const PLATFORM_PUBLIC_DISCOVERY_PATHS = [
+  "/llms.txt",
+  "/robots.txt",
+  "/sitemap.xml",
+] as const;
+
+/**
+ * The storefront app's own catalog browse routes (src/pages/products,
+ * collections, search.astro, saved.astro). They are reserved mounts because a
+ * tenant publication space may not claim them — not because reading one needs
+ * authorization. `isCacheablePath` names the same set as the core public
+ * cacheable surface, and routing them through the control plane would put origin
+ * compute plus its D1 reads in front of a tenant's highest-traffic public pages.
+ *
+ * Dynamic Astro pages, not bytes, so `public-render` — never passthrough.
+ */
+export const PLATFORM_PUBLIC_APP_ROUTE_PREFIXES = [
+  "/collections",
+  "/products",
+  "/saved",
+  "/search",
+] as const;
+
+/**
+ * Case-folded, matching `isPlatformReserved`'s own folding in the tier resolver:
+ * a path it recognizes as reserved (`/Robots.txt`, `/ASSETS/app.js`) must reach
+ * the table that says HOW to serve it, or it falls through to the control plane.
+ * Every entry below is lowercase ASCII.
+ */
+function matchesPathOrPrefix(path: string, entry: string): boolean {
+  const caseFolded = path.toLowerCase();
+  return caseFolded === entry || caseFolded.startsWith(`${entry}/`);
+}
+
+export function isPlatformStaticAssetPath(renderPath: string): boolean {
+  return PLATFORM_STATIC_ASSET_PREFIXES.some((entry) => matchesPathOrPrefix(renderPath, entry));
+}
+
+export function isPlatformPublicDiscoveryPath(renderPath: string): boolean {
+  return PLATFORM_PUBLIC_DISCOVERY_PATHS.some((entry) => matchesPathOrPrefix(renderPath, entry));
+}
+
+export function isPlatformPublicAppRoutePath(renderPath: string): boolean {
+  return PLATFORM_PUBLIC_APP_ROUTE_PREFIXES.some((entry) =>
+    matchesPathOrPrefix(renderPath, entry),
+  );
+}
+
+export interface MiddlewareBranchInputV1 {
+  index: RouteTierIndexV1;
+  /**
+   * The TENANT-RELATIVE path — `renderPath` from `resolveTenantRouting`, with any
+   * `/<domain>` selection prefix already stripped. Never `url.pathname`: on a
+   * path-routed deployment `/<tenant>/admin` arrives with the prefix attached, and
+   * feeding that to the resolver misses the reserved-mount check entirely, which
+   * resolves the control plane as public Tier 0.
+   */
+  renderPath: string;
+  /**
+   * True when this HOST is withheld behind sign-in (`DEMO_GATE_MODE=login` and the
+   * host is in `DEMO_GATE_HOSTS`). A host property, resolved before and
+   * independently of any route: under ADR 0013 the Worker keeps "preview, draft
+   * overlay, admin, the dev loop, and gated member areas", so a login-gated host
+   * is not serving a public path at all and every route on it is control plane.
+   */
+  hostLoginGated: boolean;
+}
+
+export interface ResolvedMiddlewareBranchV1 {
+  branch: MiddlewareBranchV1;
+  /** F2's answer for this request, surfaced on `locals.routeTier`. */
+  route: ResolvedRouteTierV1;
+  /** One normalized publication-space answer shared by dispatch and rendering. */
+  publication: PublicationRoutePlanV1;
+}
+
+/** Astro rewrite target for tenant-prefix stripping or canonical render aliases. */
+export function middlewareRewriteTargetV1(input: {
+  requestPath: string;
+  basePath: string;
+  renderPath: string;
+  search: string;
+}): string | undefined {
+  return input.basePath !== "" || input.renderPath !== input.requestPath
+    ? `${input.renderPath}${input.search}`
+    : undefined;
+}
+
+/** Absolute 308 location for host- and path-routed publication aliases. */
+export function publicationRedirectLocationV1(input: {
+  origin: string;
+  basePath: string;
+  plan: PublicationRouteRedirectPlanV1;
+  search: string;
+}): string {
+  return `${input.origin}${input.basePath}${input.plan.locationPath}${input.search}`;
+}
+
+/**
+ * Resolve the route once and pick its branch. Fail-closed throughout: F2 answers
+ * Tier 3 with authorization required for anything it cannot resolve, and that
+ * lands on the control plane.
+ */
+export function resolveMiddlewareBranchV1(
+  input: MiddlewareBranchInputV1,
+): ResolvedMiddlewareBranchV1 {
+  const publication = resolvePublicationRoutePlanV1(input.index, input.renderPath);
+  const route = publication.route;
+  if (input.hostLoginGated) return { branch: "control-plane", route, publication };
+  if (isPlatformStaticAssetPath(input.renderPath)) {
+    return { branch: "static-passthrough", route, publication };
+  }
+  if (
+    isPlatformPublicDiscoveryPath(input.renderPath) ||
+    isPlatformPublicAppRoutePath(input.renderPath)
+  ) {
+    return { branch: "public-render", route, publication };
+  }
+  return {
+    branch: route.requiresAuthorization ? "control-plane" : "public-render",
+    route,
+    publication,
+  };
+}

package/apps/storefront/src/middleware/staticBundle.ts

@@ -0,0 +1,109 @@
+/**
+ * Digest-addressed static-bundle serving (ADR 0012/0013) — CDN → R2, no render.
+ *
+ * This is the public path's real substrate, so BOTH branches that can be asked
+ * for public bytes reach it: the render chain (route documents) and the static
+ * passthrough (`/_astro`, `/assets` and the other platform roots, whose per-version
+ * hashed names exist only inside a tenant's bundle, never in the Worker's own
+ * build output). It reads R2 and KV and never D1.
+ */
+import { readR2 } from "@/lib/runtimeEnv";
+import { getCachedPage, putCachedPage, staticBundleCacheKey } from "@/lib/edgeCache";
+import { resolveChannelDigest, serveStaticBundle } from "@tot/public-runtime";
+import type { StaticBundleR2BucketLike, TenantConfig } from "@tot/public-runtime";
+
+export interface StaticBundleAttemptInput {
+  request: Request;
+  url: URL;
+  tenant: TenantConfig;
+  basePath: string;
+  cache: Cache | undefined;
+  kv: KVNamespace | undefined;
+  isPreviewHost: boolean;
+  /** `?__preview=` or the `tot_preview` cookie. */
+  hasPreviewToken: boolean;
+  hasCandidatePin: boolean;
+  hasDraftCookie: boolean;
+  /** Managed installs inject document markup, so a bundled DOCUMENT would be stale. */
+  hasManagedInstalls: boolean;
+}
+
+/**
+ * Serve this request from the tenant's live bundle, or return null to let the
+ * caller own it.
+ *
+ * For a static-publish tenant's PRODUCTION reads only (never preview/test — the
+ * "Worker serves interactive preview, R2 serves prod" split). A missing digest or
+ * object fails closed inside `serveStaticBundle`, which is why this must fully own
+ * the response once eligible rather than degrading into a render.
+ *
+ * Host-resolved reads only (`basePath === ""`): bundle bytes are served VERBATIM
+ * with root-absolute links, so a path-prefixed view (/<domain>/… on the shared
+ * .store host) would escape its prefix on every href — those views keep SSR, which
+ * rewrites hrefs through basePath.
+ */
+export async function tryServeStaticBundle(
+  input: StaticBundleAttemptInput,
+): Promise<Response | null> {
+  const { request, url, tenant, cache, kv } = input;
+  const eligible =
+    tenant.staticPublish != null &&
+    tenant.staticPublish.enabled !== false &&
+    input.basePath === "" &&
+    request.method.toUpperCase() === "GET" &&
+    !input.isPreviewHost &&
+    !input.hasPreviewToken &&
+    !input.hasCandidatePin &&
+    !input.hasDraftCookie &&
+    !input.hasManagedInstalls &&
+    !url.pathname.startsWith("/api/");
+  if (!eligible) return null;
+
+  const bundleBucket = await readR2("STATIC_BUNDLES");
+  // No STATIC_BUNDLES binding (plain `astro dev`, or unconfigured) — degrading to
+  // the caller rather than a hard failure keeps `astro dev`/tests usable without
+  // provisioning R2.
+  if (!bundleBucket) return null;
+
+  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+  // The R2 bundle key is the `treeDigest`, NOT the `live` channel versionId (the
+  // Gitea sha). Read the reconciled digest companion (`channelDigests.live`) —
+  // `gatedPromote`/`rollbackCandidateAtomic` write it in the same CAS flip as the
+  // versionId. No digest = this tenant has never staged a bundle — the caller
+  // serves it (a static-publish tenant must be able to bootstrap, and its app
+  // surfaces must never be downed by an unstaged static plane).
+  const digest = await resolveChannelDigest(kvGet, tenant.tenant_id, "live");
+  if (!digest) {
+    console.error(
+      `[static-bundle] no live digest for ${tenant.tenant_id} — SSR until a bundle is staged`,
+    );
+    return null;
+  }
+
+  const bundleCacheKey = cache
+    ? staticBundleCacheKey(tenant.tenant_id, digest, url.pathname, url.search)
+    : null;
+  if (bundleCacheKey && cache) {
+    const hit = await getCachedPage(cache, bundleCacheKey);
+    if (hit) return hit;
+  }
+  const bundleResponse = await serveStaticBundle(
+    {
+      bucket: bundleBucket as unknown as StaticBundleR2BucketLike,
+      digest,
+      onFailClosed: (detail) => {
+        console.error(
+          `[static-bundle] fail-closed for ${tenant.tenant_id} ${url.pathname}: ${detail}`,
+        );
+      },
+    },
+    url.pathname,
+  );
+  // `null` = the manifest proves this path is outside the bundle's static surface
+  // (an app surface like /admin) — the caller owns it.
+  if (!bundleResponse) return null;
+  if (bundleCacheKey && cache) {
+    await putCachedPage(cache, bundleCacheKey, bundleResponse);
+  }
+  return bundleResponse;
+}

package/apps/storefront/src/pages/[...slug].astro

@@ -49,6 +49,7 @@ if (rawHtml && rawHtmlPolicy(tenant).allowed) {
     basePath,
     chromeWrapper,
     plan: Astro.locals.integrationPlan,
+    consentSnapshot: Astro.locals.consentSnapshot,
   });
 }
 

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -125,6 +125,7 @@ export async function POST(context: APIContext): Promise<Response> {
   const { id } = await createSession(
     store,
     {
+      subject: derived.subject,
       email: derived.email,
       resource: derived.resource,
       roles: [],

package/apps/storefront/src/pages/api/auth/step-up-verify.ts

@@ -110,6 +110,7 @@ export async function POST(context: APIContext): Promise<Response> {
   const { id } = await createSession(
     store,
     {
+      subject: derived.subject,
       email: derived.email,
       resource: derived.resource,
       roles: [],

package/apps/storefront/src/pages/api/auth/verify.ts

@@ -137,6 +137,7 @@ export async function POST(context: APIContext): Promise<Response> {
   const { id } = await createSession(
     store,
     {
+      subject: derived.subject,
       email: derived.email,
       // The verified aud (storefront app identity) — the console session's scope.
       resource: derived.resource,

package/apps/storefront/src/pages/api/compliance/preflight.ts

@@ -22,11 +22,18 @@ import {
   type VerificationState,
   type CartComplianceDecision,
 } from "@tot/public-runtime";
+import type { ComplianceRuleset } from "@tot/public-runtime";
 import {
+  isLiveTotVerificationProvider,
   isRegulatedTenant,
   isSandboxVerificationProvider,
   resolveTenantRuleset,
 } from "@/lib/compliance/enforcement";
+import {
+  createTotVerificationClient,
+  type TotVerificationClient,
+  type TotVerificationStatus,
+} from "@/lib/verification/totVerificationClient";
 
 export const prerender = false;
 
@@ -46,6 +53,31 @@ interface PreflightBody {
     evidenceRef?: string;
   } | null;
   ageAffirmed?: boolean;
+  /**
+   * LIVE provider only: the `appTransactionId` correlating this checkout attempt
+   * to a verification already started with ToT. Present on the resume leg of the
+   * shopper redirect trip. It is a CORRELATION HANDLE, not a claim — the server
+   * re-reads the real status for it on every call.
+   */
+  verificationRef?: string;
+  /** LIVE provider only: the shopper details a new verification is started from. */
+  shopper?: {
+    email?: string;
+    givenName?: string;
+    familyName?: string;
+    dateOfBirth?: string;
+  } | null;
+}
+
+/**
+ * What the live provider leg resolved, echoed back so the (downstream) checkout
+ * verification flow can send the shopper on and resume with the same ref. Purely
+ * informational — the DECISION is `decision`, computed server-side.
+ */
+interface LiveVerificationMeta {
+  ref?: string;
+  status?: TotVerificationStatus | "conditions_met" | "interactive";
+  continuationUrl?: string;
 }
 
 function json(body: unknown, status = 200): Response {
@@ -107,6 +139,134 @@ function normalizeDestination(
   };
 }
 
+// --- Live ToT verification provider -----------------------------------------
+
+let clientOverride: TotVerificationClient | null | undefined;
+
+/** Test seam: inject a client (or `null` to simulate an unconfigured env). */
+export function __setTotVerificationClientForTests(
+  client: TotVerificationClient | null | undefined,
+): void {
+  clientOverride = client;
+}
+
+async function resolveClient(): Promise<TotVerificationClient | null> {
+  if (clientOverride !== undefined) return clientOverride;
+  return await createTotVerificationClient();
+}
+
+/** Map a live provider status onto the pure engine's verification state. */
+function stateForStatus(
+  status: TotVerificationStatus,
+  ref: string,
+): VerificationState {
+  switch (status) {
+    case "cleared":
+      // The provider cleared its age/identity workflow for this app. It does not
+      // report a numeric age, so `verifiedAge` stays undefined — the engine then
+      // treats "verified" as satisfying the tenant's minAge, which is exactly the
+      // provider's own contract (the app's workflow encodes the age threshold).
+      return { outcome: "verified", evidenceRef: ref };
+    case "rejected":
+      return { outcome: "failed", evidenceRef: ref };
+    case "pending":
+      return { outcome: "pending", evidenceRef: ref };
+    case "not_started":
+      return { outcome: "unknown" };
+  }
+}
+
+interface LiveVerificationResolution {
+  state: VerificationState;
+  meta: LiveVerificationMeta;
+}
+
+/**
+ * Resolve the shopper's verification from the LIVE provider, server-side.
+ *
+ * Returns `null` on ANY adapter failure (unconfigured env, transport error,
+ * non-2xx, malformed payload) — the caller turns that into the same fail-closed
+ * BLOCK as "no provider configured". Never throws.
+ */
+async function resolveLiveVerification(
+  body: PreflightBody,
+): Promise<LiveVerificationResolution | null> {
+  let client: TotVerificationClient | null;
+  try {
+    client = await resolveClient();
+  } catch {
+    return null;
+  }
+  if (!client) return null;
+
+  const ref =
+    typeof body.verificationRef === "string" && body.verificationRef.trim()
+      ? body.verificationRef.trim()
+      : null;
+
+  try {
+    if (ref) {
+      const read = await client.readVerification({ appTransactionId: ref });
+      if (!read.ok) return null;
+      if (read.status !== "not_started") {
+        return { state: stateForStatus(read.status, ref), meta: { ref, status: read.status } };
+      }
+      // "not_started" for a known ref falls through to a create with the same ref.
+    }
+
+    const email =
+      typeof body.shopper?.email === "string" ? body.shopper.email.trim() : "";
+    if (!email) {
+      // Nothing started and nothing to start from: the shopper still has to
+      // verify. NOT an adapter failure — "unknown" is the engine's "do the step".
+      return {
+        state: { outcome: "unknown" },
+        meta: ref ? { ref, status: "not_started" } : {},
+      };
+    }
+
+    const appTransactionId = ref ?? crypto.randomUUID();
+    const created = await client.createVerification({
+      appTransactionId,
+      person: {
+        primaryEmail: email,
+        ...(body.shopper?.givenName ? { givenName: body.shopper.givenName } : {}),
+        ...(body.shopper?.familyName ? { familyName: body.shopper.familyName } : {}),
+        ...(body.shopper?.dateOfBirth ? { dateOfBirth: body.shopper.dateOfBirth } : {}),
+      },
+    });
+    if (!created.ok) return null;
+    const meta: LiveVerificationMeta = {
+      ref: appTransactionId,
+      status: created.nextStep === "conditions_met" ? "conditions_met" : "interactive",
+    };
+    if (created.continuationUrl) meta.continuationUrl = created.continuationUrl;
+    return {
+      state:
+        created.nextStep === "conditions_met"
+          ? { outcome: "verified", evidenceRef: appTransactionId }
+          : { outcome: "pending", evidenceRef: appTransactionId },
+      meta,
+    };
+  } catch {
+    // Belt-and-braces: the client is typed never-throws, but an unexpected
+    // exception must still fail closed rather than escape this route.
+    return null;
+  }
+}
+
+/**
+ * Strip the provider from a ruleset so the pure engine emits its existing
+ * "no verification provider configured" outcome — BLOCK + `failedClosed: true`.
+ * This is how an adapter failure fails closed WITHOUT touching the engine.
+ */
+function withProviderCleared(ruleset: ComplianceRuleset): ComplianceRuleset {
+  return {
+    ...ruleset,
+    verification: { ...ruleset.verification, provider: undefined },
+  };
+}
+
 export async function POST(context: APIContext): Promise<Response> {
   const { tenant, tot } = context.locals;
   const regulated = isRegulatedTenant(tenant);
@@ -121,9 +281,26 @@ export async function POST(context: APIContext): Promise<Response> {
       : json({ decision: evaluateEmpty() });
   }
 
-  const ruleset = await resolveTenantRuleset(tenant);
+  let ruleset = await resolveTenantRuleset(tenant);
   let verification = normalizeVerification(body.verification);
   const destination = normalizeDestination(body.destination);
+  let liveVerification: LiveVerificationMeta | undefined;
+
+  // LIVE provider: the decision is made here, from a real server-side API call.
+  // The client-supplied `verification` field is DISCARDED (it is a shopper input,
+  // not evidence) and the affirmation shortcut below is unreachable — "tot" is
+  // never in SANDBOX_VERIFICATION_PROVIDERS. Any adapter failure clears the
+  // provider so the engine blocks fail-closed, exactly as when none is wired.
+  if (ruleset && isLiveTotVerificationProvider(ruleset.verification.provider)) {
+    const resolved = await resolveLiveVerification(body);
+    if (!resolved) {
+      ruleset = withProviderCleared(ruleset);
+      verification = { outcome: "unknown" };
+    } else {
+      verification = resolved.state;
+      liveVerification = resolved.meta;
+    }
+  }
 
   // Test/sandbox verification profile (the mode the 8501 demo/preview runs in):
   // when the resolved provider is an explicit sandbox value and no live provider
@@ -187,7 +364,7 @@ export async function POST(context: APIContext): Promise<Response> {
     ageAffirmed: body.ageAffirmed === true,
   });
 
-  return json({ decision });
+  return json(liveVerification ? { decision, verification: liveVerification } : { decision });
 }
 
 /** The trivial "nothing to enforce" decision for an unregulated empty request. */

package/apps/storefront/src/pages/index.astro

@@ -63,6 +63,7 @@ if (rawHtml && rawHtmlPolicy(tenant).allowed) {
     basePath,
     chromeWrapper,
     plan: Astro.locals.integrationPlan,
+    consentSnapshot: Astro.locals.consentSnapshot,
   });
 }
 

package/apps/storefront/vitest.config.ts

@@ -13,6 +13,11 @@ export default defineConfig({
   resolve: {
     alias: {
       "@": fileURLToPath(new URL("./src", import.meta.url)),
+      // `astro:middleware` is a virtual id Astro's own Vite plugin maps onto this
+      // real module. Mapping it the same way lets src/middleware/index.ts — the
+      // branch-to-handler dispatch — be invoked in a unit test instead of only
+      // read as text.
+      "astro:middleware": "astro/virtual-modules/middleware.js",
     },
   },
   test: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -18,6 +18,7 @@
     "generate:managed-analytics-schemas": "node --experimental-strip-types scripts/generate-managed-analytics-api-v1-schemas.mjs"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
     "typescript": "^5.6.3",
     "vitest": "^2.1.8"
   }