@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

package/apps/storefront/src/lib/runtimeEnv.ts

@@ -0,0 +1,124 @@
+/**
+ * Runtime env access that works in BOTH contexts:
+ *   - `astro dev` (Node): reads import.meta.env / process.env.
+ *   - Cloudflare Workers (prod): reads the `cloudflare:workers` env module.
+ *
+ * Astro v6+/@astrojs/cloudflare v14 REMOVED `Astro.locals.runtime.env`; the
+ * supported path is `import { env } from "cloudflare:workers"`. That module only
+ * exists in the worker runtime, so we import it lazily + guarded and fall back
+ * to build-time env in dev. See DECISIONS.md.
+ *
+ * This module holds every binding EXCEPT D1. `./env.js` is this surface plus
+ * `readD1`, and the public-render branch may reach this module but not that one —
+ * `public-render-no-request-time-d1` in .dependency-cruiser.cjs enforces it. A
+ * fence can only forbid a MODULE, so the one accessor that hands out a live
+ * control-plane database has to live in a module of its own for the fence to
+ * have anything to name.
+ */
+
+let workerEnv: Record<string, unknown> | null | undefined;
+
+/** The raw Workers env bag, or null outside the Workers runtime. */
+export async function getWorkerEnv(): Promise<Record<string, unknown> | null> {
+  if (workerEnv !== undefined) return workerEnv;
+  try {
+    // @ts-expect-error — virtual module, only resolvable in the Workers runtime.
+    const mod = await import("cloudflare:workers");
+    workerEnv = (mod.env ?? null) as Record<string, unknown> | null;
+  } catch {
+    workerEnv = null;
+  }
+  return workerEnv;
+}
+
+function fromBuild(key: string): string | undefined {
+  const meta = import.meta.env as Record<string, string | undefined>;
+  if (meta[key] != null) return meta[key];
+  if (typeof process !== "undefined" && process.env && process.env[key] != null) {
+    return process.env[key];
+  }
+  return undefined;
+}
+
+export async function readEnv(key: string): Promise<string | undefined> {
+  const w = await getWorkerEnv();
+  const wv = w?.[key];
+  if (typeof wv === "string" && wv.length) return wv;
+  return fromBuild(key);
+}
+
+/** The slice of the Workers ExecutionContext runAfterResponse needs — the
+ *  @astrojs/cloudflare adapter exposes it to routes as `locals.cfContext`. */
+export interface CfExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * Run `work` PAST the response — the request's `ExecutionContext.waitUntil`
+ * when the caller passes it, else a detached floating promise (dev/Node). For
+ * webhook RECEIVERS that must ACK fast: the upstream forwarder (tot-mcp
+ * gitea-webhook proxy) aborts its forward at 15s and Gitea bounds its delivery
+ * wait too, while a real reconcile takes tens of seconds — running it inside
+ * the request meant every healthy reconcile was killed mid-flight and recorded
+ * as `forward_failed` (a layer of Trello 13075, behind the auth fix).
+ *
+ * CALLERS MUST PASS `locals.cfContext` (the @astrojs/cloudflare adapter's
+ * per-request ExecutionContext, `createLocals: { cfContext: ctx }`): in the
+ * Workers runtime a merely-floating promise is CANCELLED the moment the
+ * response returns — an earlier revision here imported `waitUntil` from
+ * `cloudflare:workers` (not exported by this adapter/runtime version), silently
+ * degraded to the floating promise, and the async reconcile died unobserved
+ * right after its 202. The floating-promise branch is a DEV-ONLY fallback.
+ * Errors are the caller's to handle inside `work` (this never throws).
+ */
+export function runAfterResponse(
+  work: Promise<unknown>,
+  cfContext?: CfExecutionContextLike | null,
+): void {
+  const swallowed = work.catch(() => {});
+  if (cfContext && typeof cfContext.waitUntil === "function") {
+    cfContext.waitUntil(swallowed);
+    return;
+  }
+  // dev/Node only — in the Workers runtime this promise would be cancelled at
+  // response end, which is exactly the bug the parameter above exists to avoid.
+  void swallowed;
+}
+
+/** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
+export async function readKv(binding: string): Promise<KVNamespace | undefined> {
+  const w = await getWorkerEnv();
+  const b = w?.[binding];
+  return (b as KVNamespace | undefined) ?? undefined;
+}
+
+/** R2 bucket binding (e.g. TENANT_ASSETS, PRODUCT_IMAGES), if present. */
+export async function readR2(binding: string): Promise<R2Bucket | undefined> {
+  const w = await getWorkerEnv();
+  return (w?.[binding] as R2Bucket | undefined) ?? undefined;
+}
+
+/**
+ * Cloudflare Analytics Engine dataset binding (e.g. ACTIVITY_ANALYTICS), if
+ * present. Untyped (`unknown`) deliberately — the caller casts to its own
+ * minimal `writeDataPoint` shape (see `activity/store.ts`'s
+ * `AnalyticsEngineLike`) rather than this module taking a types dep. Absent in
+ * dev/Node and until the binding is provisioned; callers treat undefined as
+ * "analytics sink unavailable, skip it" (never an error).
+ */
+export async function readAnalytics(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}
+
+/**
+ * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
+ * Untyped (`unknown`) deliberately — callers cast to their own minimal
+ * queue-shape interface (see `webhooks/cloudflareQueueDispatcher.ts`'s
+ * `CloudflareQueueSender`) rather than this module taking a types dep on a
+ * specific binding's shape.
+ */
+export async function readQueue(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}

package/apps/storefront/src/lib/verification/totVerificationClient.ts

@@ -0,0 +1,485 @@
+/**
+ * TotVerificationClient — the storefront's seam to Token of Trust's LIVE
+ * age/identity verification API, i.e. the code behind
+ * `TOT_VERIFICATION_PROVIDER="tot"`.
+ *
+ *   POST /api/person  { totApiKey, totSecretKey, appDomain, appTransactionId, person }
+ *        → { content: { code, continuation: { params: { url } }, reservationToken } }
+ *          `code` = "WorkflowService:conditionsMet"        → nothing further needed
+ *                 = "WorkflowService:nextStepIsInteractive" → send the shopper to
+ *                   `continuation.params.url` (the redirect trip owned by the
+ *                   checkout-verification-flow unit; this client only surfaces it)
+ *
+ *   GET  /api/person?totApiKey=…&totSecretKey=…&appDomain=…&appTransactionId=…
+ *        → { content: { appTransactionId, user, transaction: { report: {
+ *            connection: { status }, gates: { isCleared, isSubmitted,
+ *            isRejected, isUpdateRequested } } } } }
+ *          The report is NESTED under `transaction.report` — see `reportOf`.
+ *
+ * Credentials are the VERIFICATION app's pair (`TOT_VERIFICATION_API_KEY` /
+ * `TOT_VERIFICATION_SECRET_KEY`, appDomain `TOT_VERIFICATION_APP_DOMAIN`) — never
+ * `TOT_API_KEY`/`TOT_SECRET_KEY`, which are the storefront's OWN operator identity
+ * under a different appDomain. Authenticating a shopper's verification under the
+ * operator identity would silently bind it to the wrong tenant.
+ *
+ * FAIL CLOSED, ALWAYS. Every method returns a typed result and never throws: a
+ * transport error, a non-2xx, an unparseable body, an unexpected shape, or a
+ * missing credential all resolve to `{ ok: false, reason }`. The caller
+ * (`/api/compliance/preflight`) turns any `ok:false` into the same BLOCK +
+ * `failedClosed:true` decision as "no provider configured".
+ *
+ * `totSecretKey` never appears in a log line, an error message, or a response —
+ * only status codes and coarse shape descriptions are logged on failure.
+ *
+ * Structure mirrors `@/lib/auth/totAccessClient`: interface + Http impl + Mock +
+ * env factory, with the wire-credential shape isolated to `credentialFields()`.
+ */
+import { readEnv } from "@/lib/env";
+import {
+  FetchHttpTransport,
+  type HttpGetTransport,
+  type HttpResponseLike,
+  type HttpTransport,
+} from "@/lib/http/fetchTransport";
+
+// --- Gate normalization -----------------------------------------------------
+
+/**
+ * Gate values that denote a POSITIVE (set) gate. `GET /api/person` reports each
+ * gate either as a bare value or as a `{ value, dependsOn }` object — observed
+ * live for this app as `isCleared: { value: "fullMatch", dependsOn: [...] }`.
+ */
+const POSITIVE_GATE_VALUES: ReadonlySet<string> = new Set([
+  "fullmatch",
+  "partialmatch",
+  "true",
+]);
+
+/**
+ * Normalize one gate from `GET /api/person` to a boolean.
+ *
+ * The gate is set when it is `true`, the string `"fullMatch"`/`"partialMatch"`,
+ * or an OBJECT whose `.value` is one of those. **Never compare a gate with a bare
+ * `===` string.** The wire shape for this tenant/app is the object form, so
+ * `gates.isCleared === "fullMatch"` is always false and reports "pending"
+ * forever, with no error anywhere — the single most common integration bug
+ * against this API. Anything else (missing, `false`, an unrecognized string, an
+ * object with no usable `.value`) is NOT set.
+ */
+export function isGateSet(gate: unknown): boolean {
+  if (gate === true) return true;
+  if (typeof gate === "string") return POSITIVE_GATE_VALUES.has(gate.toLowerCase());
+  if (gate && typeof gate === "object") {
+    const value = (gate as { value?: unknown }).value;
+    if (value === true) return true;
+    if (typeof value === "string") return POSITIVE_GATE_VALUES.has(value.toLowerCase());
+  }
+  return false;
+}
+
+// --- Result types -----------------------------------------------------------
+
+/**
+ * Why a call did not produce a usable answer. Every one of these is fail-closed
+ * at the call site — they are distinguished only for operator diagnostics.
+ */
+export type TotVerificationFailureReason =
+  | "not_configured"
+  | "transport_error"
+  | "http_error"
+  | "malformed_response";
+
+/** What the create call decided about the shopper's next step. */
+export type TotVerificationNextStep =
+  | "conditions_met"
+  | "interactive"
+  /** A `code` we don't recognize — treated as "not cleared" by the caller. */
+  | "indeterminate";
+
+export type CreateVerificationResult =
+  | {
+      ok: true;
+      nextStep: TotVerificationNextStep;
+      /** The raw `content.code` (diagnostics + downstream flow branching). */
+      code: string;
+      /**
+       * Where to send the shopper when `nextStep === "interactive"`. Consumed by
+       * the downstream checkout-verification-flow unit; this client only surfaces
+       * it and never redirects.
+       */
+      continuationUrl?: string;
+      reservationToken?: string;
+      /** Echo of the correlation id, to be replayed to {@link readVerification}. */
+      appTransactionId: string;
+    }
+  | { ok: false; reason: TotVerificationFailureReason };
+
+/** Where the shopper stands, as the READ call reports it. */
+export type TotVerificationStatus =
+  /** `isCleared` is set — verification passed. */
+  | "cleared"
+  /** `isRejected` is set — verification did not pass. */
+  | "rejected"
+  /** Submitted or connected but neither cleared nor rejected yet. */
+  | "pending"
+  /** `connection.status === "noUser"` — nothing started for this correlation id. */
+  | "not_started";
+
+export type ReadVerificationResult =
+  | {
+      ok: true;
+      status: TotVerificationStatus;
+      submitted: boolean;
+      updateRequested: boolean;
+    }
+  | { ok: false; reason: TotVerificationFailureReason };
+
+/** The person payload the create call submits. Only `primaryEmail` is required. */
+export interface VerificationPersonInput {
+  primaryEmail: string;
+  givenName?: string;
+  familyName?: string;
+  /** ISO date (YYYY-MM-DD) when the shopper supplied one. */
+  dateOfBirth?: string;
+  location?: Record<string, unknown>;
+}
+
+export interface CreateVerificationInput {
+  /** Per-checkout-attempt correlation id — replayed to the read call. */
+  appTransactionId: string;
+  person: VerificationPersonInput;
+  appUserid?: string;
+  reservation?: boolean;
+}
+
+export interface ReadVerificationInput {
+  appTransactionId?: string;
+  appUserid?: string;
+  scope?: string;
+}
+
+export interface TotVerificationClient {
+  /**
+   * Start (or re-assert) a verification for this checkout attempt. Returns the
+   * continuation URL when the shopper must complete an interactive step.
+   */
+  createVerification(input: CreateVerificationInput): Promise<CreateVerificationResult>;
+  /** Read where an existing verification stands. Safe to call repeatedly. */
+  readVerification(input: ReadVerificationInput): Promise<ReadVerificationResult>;
+}
+
+// --- HTTP implementation ----------------------------------------------------
+
+/** The transport this client needs: JSON POST plus a query-string GET. */
+export type VerificationTransport = HttpTransport & HttpGetTransport;
+
+const defaultTransport = (): VerificationTransport =>
+  new FetchHttpTransport({
+    defaultHeaders: { "content-type": "application/json", accept: "application/json" },
+    // A hung verification subrequest must not hold the checkout gate open; an
+    // abort surfaces as `transport_error`, which fails closed.
+    timeoutMs: 10_000,
+  });
+
+export interface HttpTotVerificationClientConfig {
+  /** Verification API base, e.g. `https://qa.tokenoftrust.com/api` (no trailing slash). */
+  baseUrl: string;
+  apiKey: string;
+  secretKey: string;
+  /** The VERIFICATION app's domain, e.g. `verify.e2e.test`. */
+  appDomain: string;
+  transport?: VerificationTransport;
+}
+
+/**
+ * Truthy only when every field the live API requires is present. The factory
+ * returns `null` otherwise so the caller fails closed instead of issuing a call
+ * that would 401 (or, worse, authenticate as the wrong app).
+ */
+export function isVerificationClientConfigured(
+  config: Partial<HttpTotVerificationClientConfig>,
+): config is HttpTotVerificationClientConfig {
+  return !!(config.baseUrl && config.apiKey && config.secretKey && config.appDomain);
+}
+
+export class HttpTotVerificationClient implements TotVerificationClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey: string;
+  private readonly appDomain: string;
+  private readonly transport: VerificationTransport;
+
+  constructor(config: HttpTotVerificationClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.appDomain = config.appDomain;
+    this.transport = config.transport ?? defaultTransport();
+  }
+
+  /**
+   * The one integration-sensitive spot: how this client authenticates. tot reads
+   * `totApiKey`/`totSecretKey`/`appDomain` from the request BODY on POST and from
+   * the QUERY STRING on GET (no bearer header). Swap here if that ever changes —
+   * nowhere else knows the wire shape.
+   */
+  private credentialFields(): Record<string, string> {
+    return {
+      totApiKey: this.apiKey,
+      totSecretKey: this.secretKey,
+      appDomain: this.appDomain,
+    };
+  }
+
+  async createVerification(
+    input: CreateVerificationInput,
+  ): Promise<CreateVerificationResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/person`,
+        {},
+        {
+          ...this.credentialFields(),
+          appTransactionId: input.appTransactionId,
+          ...(input.appUserid ? { appUserid: input.appUserid } : {}),
+          ...(input.reservation != null ? { reservation: input.reservation } : {}),
+          person: input.person,
+        },
+      );
+    } catch (e) {
+      logFailure("create", { transport: errorLabel(e) });
+      return { ok: false, reason: "transport_error" };
+    }
+    if (!isOk(res.status)) {
+      logFailure("create", { status: res.status });
+      return { ok: false, reason: "http_error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      logFailure("create", { status: res.status, body: "unparseable" });
+      return { ok: false, reason: "malformed_response" };
+    }
+    return normalizeCreate(body, input.appTransactionId);
+  }
+
+  async readVerification(input: ReadVerificationInput): Promise<ReadVerificationResult> {
+    if (!input.appTransactionId && !input.appUserid) {
+      // Nothing to correlate on — the API requires at least one.
+      logFailure("read", { body: "no-correlation-id" });
+      return { ok: false, reason: "not_configured" };
+    }
+    const query = new URLSearchParams({
+      ...this.credentialFields(),
+      ...(input.appTransactionId ? { appTransactionId: input.appTransactionId } : {}),
+      ...(input.appUserid ? { appUserid: input.appUserid } : {}),
+      ...(input.scope ? { scope: input.scope } : {}),
+    });
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.get(`${this.baseUrl}/person?${query.toString()}`, {});
+    } catch (e) {
+      logFailure("read", { transport: errorLabel(e) });
+      return { ok: false, reason: "transport_error" };
+    }
+    if (!isOk(res.status)) {
+      logFailure("read", { status: res.status });
+      return { ok: false, reason: "http_error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      logFailure("read", { status: res.status, body: "unparseable" });
+      return { ok: false, reason: "malformed_response" };
+    }
+    return normalizeRead(body);
+  }
+}
+
+const isOk = (status: number) => status >= 200 && status < 300;
+
+const errorLabel = (e: unknown) => (e instanceof Error ? e.name : "unknown");
+
+/**
+ * Log ONLY non-secret diagnostics. The request body carries `totSecretKey`, so it
+ * is never logged — status codes and coarse shape labels only.
+ */
+function logFailure(op: "create" | "read", detail: Record<string, unknown>): void {
+  try {
+    console.warn("[verification:tot]", JSON.stringify({ op, ...detail }));
+  } catch {
+    /* never break the gate on a logging failure */
+  }
+}
+
+/** Unwrap tot's `{ content, metadata }` envelope (falls back to the raw body). */
+function unwrap(body: unknown): Record<string, unknown> {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  return (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<
+    string,
+    unknown
+  >;
+}
+
+/**
+ * Locate the gate/connection REPORT inside a `GET /api/person` body.
+ *
+ * The live wire nests it: `content.transaction.report.{connection,gates}` — the
+ * envelope's `content` carries only `appUserid`/`appTransactionId`/`user`/
+ * `transaction`. Reading `content.gates` therefore finds nothing and every read
+ * resolves to `malformed_response`, which fails closed for EVERY shopper,
+ * including a cleared one — silently, since fail-closed is also the correct
+ * answer when the service is genuinely unreachable. Descend first; a body that
+ * carries the report un-nested is used as-is.
+ */
+function reportOf(body: unknown): Record<string, unknown> {
+  const content = unwrap(body);
+  const transaction = content.transaction as { report?: unknown } | undefined;
+  const report = transaction?.report;
+  if (report && typeof report === "object") return report as Record<string, unknown>;
+  return content;
+}
+
+/** Parse `POST /api/person` into a typed result (fail closed on any surprise). */
+export function normalizeCreate(
+  body: unknown,
+  appTransactionId: string,
+): CreateVerificationResult {
+  const b = unwrap(body);
+  const code = typeof b.code === "string" ? b.code : "";
+  if (!code) {
+    logFailure("create", { body: "no-code" });
+    return { ok: false, reason: "malformed_response" };
+  }
+  const nextStep: TotVerificationNextStep = code.endsWith(":conditionsMet")
+    ? "conditions_met"
+    : code.endsWith(":nextStepIsInteractive")
+      ? "interactive"
+      : "indeterminate";
+
+  const continuation = b.continuation as { params?: { url?: unknown } } | undefined;
+  const url = continuation?.params?.url;
+  const result: CreateVerificationResult = {
+    ok: true,
+    nextStep,
+    code,
+    appTransactionId,
+  };
+  if (typeof url === "string" && url) result.continuationUrl = url;
+  if (typeof b.reservationToken === "string" && b.reservationToken) {
+    result.reservationToken = b.reservationToken;
+  }
+  return result;
+}
+
+/** Parse `GET /api/person` into a typed status (fail closed on any surprise). */
+export function normalizeRead(body: unknown): ReadVerificationResult {
+  const b = reportOf(body);
+  const connection = b.connection as { status?: unknown } | undefined;
+  const gatesRaw = b.gates;
+  const gates = (gatesRaw && typeof gatesRaw === "object" ? gatesRaw : null) as Record<
+    string,
+    unknown
+  > | null;
+  const connectionStatus =
+    connection && typeof connection === "object" && typeof connection.status === "string"
+      ? connection.status
+      : undefined;
+
+  if (!gates && connectionStatus !== "noUser") {
+    // Neither a recognizable gate map nor an explicit "no user" — we cannot tell
+    // where the shopper stands, so we refuse to guess.
+    logFailure("read", { body: "no-gates" });
+    return { ok: false, reason: "malformed_response" };
+  }
+  if (connectionStatus === "noUser") {
+    return { ok: true, status: "not_started", submitted: false, updateRequested: false };
+  }
+
+  const submitted = isGateSet(gates?.isSubmitted);
+  const updateRequested = isGateSet(gates?.isUpdateRequested);
+  // DENY WINS: a rejection is honored even if a cleared gate is somehow also set.
+  const status: TotVerificationStatus = isGateSet(gates?.isRejected)
+    ? "rejected"
+    : isGateSet(gates?.isCleared)
+      ? "cleared"
+      : "pending";
+  return { ok: true, status, submitted, updateRequested };
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+
+/**
+ * In-memory client for unit tests and local dev. It NEVER stands in for the live
+ * provider at runtime: the factory only ever builds {@link HttpTotVerificationClient},
+ * so an unconfigured environment fails closed rather than silently mocking a pass.
+ */
+export class MockTotVerificationClient implements TotVerificationClient {
+  created: CreateVerificationInput[] = [];
+  read: ReadVerificationInput[] = [];
+
+  constructor(
+    private readonly createResult: CreateVerificationResult = {
+      ok: true,
+      nextStep: "interactive",
+      code: "WorkflowService:nextStepIsInteractive",
+      continuationUrl: "https://qa.tokenoftrust.com/verify/mock",
+      appTransactionId: "mock-txn",
+    },
+    private readonly readResult: ReadVerificationResult = {
+      ok: true,
+      status: "pending",
+      submitted: false,
+      updateRequested: false,
+    },
+  ) {}
+
+  async createVerification(input: CreateVerificationInput): Promise<CreateVerificationResult> {
+    this.created.push(input);
+    return this.createResult;
+  }
+
+  async readVerification(input: ReadVerificationInput): Promise<ReadVerificationResult> {
+    this.read.push(input);
+    return this.readResult;
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+
+/**
+ * Build the env-configured live client, or `null` when the environment is not
+ * fully configured (missing base URL, appDomain, or either half of the
+ * verification credential pair). `null` is the fail-closed signal — the caller
+ * MUST block rather than proceed.
+ *
+ * Reads `TOT_VERIFICATION_API_KEY`/`TOT_VERIFICATION_SECRET_KEY` and NEVER falls
+ * back to `TOT_API_KEY`/`TOT_SECRET_KEY` (a different app identity).
+ */
+export async function createTotVerificationClient(
+  overrides: Partial<HttpTotVerificationClientConfig> = {},
+): Promise<HttpTotVerificationClient | null> {
+  const config: Partial<HttpTotVerificationClientConfig> = {
+    baseUrl: overrides.baseUrl ?? (await readEnv("TOT_VERIFICATION_API_BASE_URL")),
+    apiKey: overrides.apiKey ?? (await readEnv("TOT_VERIFICATION_API_KEY")),
+    secretKey: overrides.secretKey ?? (await readEnv("TOT_VERIFICATION_SECRET_KEY")),
+    appDomain: overrides.appDomain ?? (await readEnv("TOT_VERIFICATION_APP_DOMAIN")),
+  };
+  if (overrides.transport) config.transport = overrides.transport;
+  if (!isVerificationClientConfigured(config)) {
+    logFailure("create", {
+      body: "not-configured",
+      missing: [
+        !config.baseUrl && "TOT_VERIFICATION_API_BASE_URL",
+        !config.apiKey && "TOT_VERIFICATION_API_KEY",
+        !config.secretKey && "TOT_VERIFICATION_SECRET_KEY",
+        !config.appDomain && "TOT_VERIFICATION_APP_DOMAIN",
+      ].filter(Boolean),
+    });
+    return null;
+  }
+  return new HttpTotVerificationClient(config);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * The candidate-render CONTENT PIN (`__tot_candidate_pin`), resolved once for
+ * whichever branch serves the request.
+ *
+ * The token is signed, tenant-bound and expiry-bound, minted only by the
+ * control-plane candidate/revision renderers. Both branches that can reach the
+ * static bundle ask this — the render chain and the static passthrough — so
+ * `hasCandidatePin` means the same thing at both: a pin this tenant actually
+ * verified, never the mere presence of a query param a client can type.
+ */
+import { readEnv } from "@/lib/runtimeEnv";
+import { CANDIDATE_CONTENT_PIN_PARAM, verifyContentPinToken } from "@tot/public-runtime";
+
+export interface CandidateContentPin {
+  versionId: string;
+  basePath: string;
+}
+
+/**
+ * The pin this request carries, or null. Fail-closed: an absent secret, an
+ * unverifiable token, or one claiming another tenant all resolve to null and the
+ * caller falls through to normal channel-resolved content.
+ */
+export async function resolveCandidateContentPin(
+  url: URL,
+  tenantId: string,
+): Promise<CandidateContentPin | null> {
+  const param = url.searchParams.get(CANDIDATE_CONTENT_PIN_PARAM);
+  if (!param) return null;
+  const secret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+  if (!secret) return null;
+  const verified = await verifyContentPinToken(secret, param, Math.floor(Date.now() / 1000));
+  if (!verified.ok || verified.claims.tenantId !== tenantId) return null;
+  return { versionId: verified.claims.versionId, basePath: verified.claims.basePath };
+}