@tokenoftrust/storefront-runner 2.4.50 → 2.4.51

package/apps/storefront/src/lib/commerce/finalCartAuthorization.ts

@@ -0,0 +1,234 @@
+/**
+ * Final-cart authorization decision. Payment is admitted only when the caller
+ * token, the bound cart, fresh evidence, the verification seam, and mirror stock
+ * all agree. Catalog availability and a browser confirmation are not authority.
+ */
+import {
+  admitCallerToken,
+  assertMinor,
+  decideCommerceCommand,
+  finalCartDigest,
+  finalCartStillBound,
+  sumMinor,
+  type CallerToken,
+  type CommerceEvidence,
+  type CommerceStage,
+  type EvidenceState,
+  type FinalCartBinding,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+import { readMirrorAuthority, VERIFICATION_PROVIDER_OWNER, type ReserveHold } from "@/lib/inventory/allocations.js";
+
+export interface SeamView {
+  status: "clear" | "absent" | "blocked";
+  failedClosed?: boolean;
+  codes?: readonly string[];
+}
+
+export interface FinalCartRequest {
+  now: string;
+  routedTenantId: string;
+  quoted: FinalCartBinding;
+  presented: FinalCartBinding;
+  evidence: CommerceEvidence | null;
+  seam: SeamView | null;
+  catalogAvailable: boolean;
+  browserConfirmed: boolean;
+  token: CallerToken | null;
+  trustedIssuers: readonly string[];
+  expectedAudience: string;
+  activeKids: readonly string[];
+  authorities: readonly unknown[];
+  payment?: PaymentState;
+  stock?: StockState;
+  fulfillment?: FulfillmentState;
+  label?: LabelState;
+}
+
+export type FinalCartDecision =
+  | {
+      ok: true;
+      digest: string;
+      expiresAt: string;
+      amountMinor: number;
+      holds: ReserveHold[];
+      issuer: string;
+      jti: string;
+      tenantId: string;
+      stage: CommerceStage;
+    }
+  | { ok: false; finding: string; owner?: string };
+
+const EVIDENCE_FIELDS = ["verification", "tax", "risk", "stock"] as const;
+
+function sortedLines(cart: FinalCartBinding) {
+  return [...cart.lines].sort(
+    (left, right) => left.sku.localeCompare(right.sku) || left.unitMinor - right.unitMinor || left.quantity - right.quantity,
+  );
+}
+
+function cartFinding(quoted: FinalCartBinding, presented: FinalCartBinding, routedTenantId: string): string | null {
+  if (quoted.tenantId !== routedTenantId || presented.tenantId !== routedTenantId || quoted.tenantId !== presented.tenantId) {
+    return "tenant-changed";
+  }
+  if (quoted.stage !== presented.stage) return "stage-changed";
+  if (quoted.currency !== presented.currency) return "currency-changed";
+  if (quoted.destinationDigest !== presented.destinationDigest) return "destination-changed";
+  const left = sortedLines(quoted);
+  const right = sortedLines(presented);
+  if (left.length !== right.length || left.some((line, index) => line.sku !== right[index]?.sku)) return "product-changed";
+  if (left.some((line, index) => line.unitMinor !== right[index]?.unitMinor)) return "price-changed";
+  if (left.some((line, index) => line.quantity !== right[index]?.quantity)) return "quantity-changed";
+  if (quoted.verificationExpiresAt !== presented.verificationExpiresAt || quoted.taxExpiresAt !== presented.taxExpiresAt) {
+    return "evidence-window-changed";
+  }
+  return null;
+}
+
+function evidenceFinding(evidence: CommerceEvidence | null): string | null {
+  if (!evidence) return "missing-evidence";
+  for (const field of EVIDENCE_FIELDS) {
+    const state: EvidenceState | string = evidence[field];
+    if (state === "fresh") continue;
+    if (state === "UNKNOWN") return `evidence-${field}-unknown`;
+    if (state === "stale" || state === "unreadable" || state === "absent") return `evidence-${field}-${state}`;
+    return `evidence-${field}-unreadable`;
+  }
+  return null;
+}
+
+function seamFinding(seam: SeamView | null): { finding: string; owner?: string } | null {
+  if (!seam || seam.status === "absent") return { finding: "verification-seam-absent" };
+  if (seam.status === "clear") return null;
+  const codes = (seam.codes ?? []).filter((code) => /^[a-z0-9_-]+$/.test(code));
+  if (seam.failedClosed && codes.some((code) => code === "verification_unconfigured" || code === "ruleset_unavailable")) {
+    return { finding: "verification-provider-unconfigured", owner: VERIFICATION_PROVIDER_OWNER };
+  }
+  return { finding: codes[0] ? `verification-refused:${codes[0]}` : "verification-refused" };
+}
+
+function isCatalogShape(value: unknown): boolean {
+  return value == null || (typeof value === "object" && value !== null && "available" in value && !("provider" in value));
+}
+
+function commandFinding(reason: string): string {
+  switch (reason) {
+    case "stock":
+      return "stock-unknown";
+    case "fulfillment":
+      return "fulfillment-refused";
+    case "reconcile":
+      return "payment-reconcile";
+    case "payment":
+      return "payment-refused";
+    default:
+      return "evidence-refused";
+  }
+}
+
+function earlierExpiry(left: string, right: string): string {
+  return left <= right ? left : right;
+}
+
+/** Deny with one specific finding, or clear a mirror hold for each sku. */
+export async function evaluateFinalCart(input: FinalCartRequest): Promise<FinalCartDecision> {
+  if (input.browserConfirmed && (!input.token || input.token.scheme !== "asymmetric-jwks" || !input.token.signatureValid)) {
+    return { ok: false, finding: "browser-not-authority" };
+  }
+  if (!input.token) return { ok: false, finding: "signature" };
+  const admitted = admitCallerToken({
+    token: input.token,
+    trustedIssuers: input.trustedIssuers,
+    expectedAudience: input.expectedAudience,
+    activeKids: input.activeKids,
+    now: input.now,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  });
+  if (!admitted.ok) return { ok: false, finding: admitted.reason };
+
+  const changed = cartFinding(input.quoted, input.presented, input.routedTenantId);
+  if (changed) return { ok: false, finding: changed };
+
+  if (input.presented.lines.length < 1) return { ok: false, finding: "malformed-request" };
+
+  const evidence = evidenceFinding(input.evidence);
+  if (evidence) return { ok: false, finding: evidence };
+
+  const expiresAt = earlierExpiry(input.presented.verificationExpiresAt, input.presented.taxExpiresAt);
+  if (
+    input.presented.verificationExpiresAt <= input.now ||
+    input.presented.taxExpiresAt <= input.now ||
+    expiresAt <= input.now
+  ) {
+    return { ok: false, finding: "evidence-expired" };
+  }
+
+  let digest: string;
+  let amountMinor: number;
+  try {
+    for (const line of input.presented.lines) {
+      assertMinor(line.quantity, "quantity");
+      assertMinor(line.unitMinor, "unitMinor");
+    }
+    amountMinor = sumMinor(input.presented.lines.map((line) => line.unitMinor * line.quantity));
+    digest = await finalCartDigest(input.presented);
+    const quotedDigest = await finalCartDigest(input.quoted);
+    if (!finalCartStillBound(quotedDigest, digest, input.now, expiresAt)) return { ok: false, finding: "cart-unbound" };
+  } catch {
+    return { ok: false, finding: "malformed-request" };
+  }
+
+  const seam = seamFinding(input.seam);
+  if (seam) return { ok: false, finding: seam.finding, ...(seam.owner ? { owner: seam.owner } : {}) };
+
+  const command = decideCommerceCommand({
+    command: "authorize-final-cart",
+    payment: input.payment ?? "pending",
+    stock: input.stock ?? "unallocated",
+    fulfillment: input.fulfillment ?? "held",
+    label: input.label ?? "none",
+    evidence: input.evidence!,
+    providerOutcome: null,
+  });
+  if (!command.admit) return { ok: false, finding: commandFinding(command.reason) };
+
+  const quantities = new Map<string, number>();
+  for (const line of input.presented.lines) {
+    quantities.set(line.sku, (quantities.get(line.sku) ?? 0) + line.quantity);
+  }
+  const holds: ReserveHold[] = [];
+  for (const sku of [...quantities.keys()].sort()) {
+    const quantity = quantities.get(sku)!;
+    const named =
+      input.authorities.find((value) => {
+        if (!value || typeof value !== "object") return false;
+        return (value as { sku?: unknown }).sku === sku;
+      }) ?? (quantities.size === 1 ? (input.authorities[0] ?? null) : null);
+    if (named && typeof named === "object" && "provider" in named && (named as { provider: unknown }).provider !== "mirror") {
+      return { ok: false, finding: "authority-unavailable" };
+    }
+    const mirror = readMirrorAuthority(named);
+    if (!mirror || mirror.sku !== sku) {
+      return { ok: false, finding: input.catalogAvailable && isCatalogShape(named) ? "catalog-not-authority" : "authority-unavailable" };
+    }
+    if (mirror.onHand < quantity) return { ok: false, finding: "stock-unavailable" };
+    holds.push({ sku, locationId: mirror.locationId, quantity, onHand: mirror.onHand });
+  }
+
+  if (input.token.scheme !== "asymmetric-jwks") return { ok: false, finding: "shared-secret" };
+  return {
+    ok: true,
+    digest,
+    expiresAt,
+    amountMinor,
+    holds,
+    issuer: input.token.issuer,
+    jti: input.token.jti,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  };
+}

package/apps/storefront/src/lib/inventory/allocations.ts

@@ -0,0 +1,749 @@
+/**
+ * Mirror-stock allocations for a final cart. Catalog availability is not a hold.
+ * One allocation per tenant, stage, order, sku, and location. Payment confirmation
+ * moves `reserved` to `confirmed` once; that quantity stays the decrement.
+ * Expiry and timeout release only `reserved`. Cancel before handoff releases once.
+ * A refund does not restock. There is no on-hand ledger in this schema; `onHand`
+ * is the mirror balance the caller resolved, never a catalog quantity.
+ */
+import {
+  decideCommerceCommand,
+  type CommerceEvidence,
+  type CommerceStage,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+
+export const RESERVATION_AUTHORITY_HEADER = "x-tot-reservation-authority";
+export const RESERVATION_AUTHORITY_NONE = "none";
+/** Catalog `available` / `quantity` never authorizes a hold. */
+export const CATALOG_IS_RESERVATION_AUTHORITY = false;
+export const VERIFICATION_PROVIDER_OWNER = "tot-9577-tot-verification-provider";
+
+const SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+const LOCATION_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,80}$/;
+const ISSUER_RE = /^[A-Za-z0-9._:/?#&=%+-]{1,200}$/;
+const JTI_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,128}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+
+export interface SqlStatement {
+  sql: string;
+  params: readonly unknown[];
+}
+
+export interface StatementRunner {
+  all(sql: string, params: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
+  batch(statements: readonly SqlStatement[]): Promise<readonly (readonly Record<string, unknown>[])[]>;
+}
+
+interface SqliteStatement {
+  all(...params: unknown[]): unknown[];
+}
+
+export interface SqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): SqliteStatement;
+}
+
+interface D1Bound {
+  all(): Promise<unknown>;
+}
+
+export interface D1CommerceDatabase {
+  prepare(sql: string): { bind(...vals: unknown[]): D1Bound };
+  batch?(statements: unknown[]): Promise<unknown[]>;
+}
+
+export interface MirrorStockAuthority {
+  provider: "mirror";
+  readable: true;
+  locationId: string;
+  sku: string;
+  onHand: number;
+  asOf: string;
+}
+
+export interface ReserveHold {
+  sku: string;
+  locationId: string;
+  quantity: number;
+  onHand: number;
+}
+
+export interface ReserveInput {
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  cartDigest: string;
+  expiresAt: string;
+  now: string;
+  currency: string;
+  amountMinor: number;
+  issuer: string;
+  jti: string;
+  holds: readonly ReserveHold[];
+}
+
+export type ReserveResult =
+  | { ok: true; authorizationId: string; repeated: boolean; expiresAt: string }
+  | { ok: false; finding: "caller-replay" | "stock-unavailable" | "malformed-request" };
+
+export interface PolicyResult {
+  released: number;
+  restock: false;
+  finding: string;
+  /** Units moved from reserved to confirmed. Present only for payment confirmation. */
+  decremented?: number;
+}
+
+type PolicyKind = "refund" | "cancel" | "payment-failure" | "confirm" | "expiry" | "timeout" | "restart";
+
+export interface PolicyInput {
+  kind: PolicyKind;
+  tenantId: string;
+  stage: CommerceStage;
+  orderId?: string;
+  now?: string;
+  evidence?: CommerceEvidence;
+  providerOutcome?: "intent" | "accepted" | "unknown" | "voided" | "refunded" | null;
+}
+
+const FRESH_EVIDENCE: CommerceEvidence = {
+  verification: "fresh",
+  tax: "fresh",
+  risk: "fresh",
+  stock: "fresh",
+};
+
+let testOnHand: ((sku: string, locationId: string) => number | null) | null = null;
+
+/**
+ * Non-production mirror balance. Production has no on-hand ledger in this schema,
+ * so the read stays empty and authorization fails closed.
+ */
+export function __setMirrorOnHandForTests(reader: ((sku: string, locationId: string) => number | null) | null): void {
+  testOnHand = reader;
+}
+
+export function mirrorOnHand(sku: string, locationId: string): number | null {
+  if (process.env.NODE_ENV === "production") return null;
+  if (!testOnHand) return null;
+  const onHand = testOnHand(sku, locationId);
+  if (typeof onHand !== "number" || !Number.isSafeInteger(onHand) || onHand < 0) return null;
+  return onHand;
+}
+
+export function reservationAuthorityHeader(): typeof RESERVATION_AUTHORITY_NONE {
+  if (CATALOG_IS_RESERVATION_AUTHORITY) {
+    throw new Error("catalog availability is not reservation authority");
+  }
+  return RESERVATION_AUTHORITY_NONE;
+}
+
+export function readMirrorAuthority(value: unknown): MirrorStockAuthority | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  if (record.provider !== "mirror" || record.readable !== true) return null;
+  if (typeof record.locationId !== "string" || !LOCATION_RE.test(record.locationId)) return null;
+  if (typeof record.sku !== "string" || !SKU_RE.test(record.sku)) return null;
+  if (typeof record.onHand !== "number" || !Number.isSafeInteger(record.onHand) || record.onHand < 0) return null;
+  if (typeof record.asOf !== "string" || record.asOf.trim() === "" || record.asOf.length > 40) return null;
+  return {
+    provider: "mirror",
+    readable: true,
+    locationId: record.locationId,
+    sku: record.sku,
+    onHand: record.onHand,
+    asOf: record.asOf,
+  };
+}
+
+const chains = new WeakMap<object, Promise<unknown>>();
+
+function enqueue<T>(key: object, job: () => Promise<T> | T): Promise<T> {
+  const previous = chains.get(key) ?? Promise.resolve();
+  const run = previous.then(job, job);
+  chains.set(
+    key,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return run;
+}
+
+function asRows(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) return value as Record<string, unknown>[];
+  if (value && typeof value === "object" && Array.isArray((value as { results?: unknown }).results)) {
+    return (value as { results: Record<string, unknown>[] }).results;
+  }
+  return [];
+}
+
+export function sqliteCommerceRunner(db: SqliteDatabase): StatementRunner {
+  return {
+    all(sql, params) {
+      return enqueue(db, () => db.prepare(sql).all(...params) as Record<string, unknown>[]);
+    },
+    batch(statements) {
+      return enqueue(db, () => {
+        db.exec("BEGIN IMMEDIATE");
+        try {
+          const results = statements.map(
+            (statement) => db.prepare(statement.sql).all(...statement.params) as Record<string, unknown>[],
+          );
+          db.exec("COMMIT");
+          return results;
+        } catch (error) {
+          try {
+            db.exec("ROLLBACK");
+          } catch {
+            /* the failed statement already aborted the transaction */
+          }
+          throw error;
+        }
+      });
+    },
+  };
+}
+
+export function d1CommerceRunner(db: D1CommerceDatabase): StatementRunner {
+  return {
+    async all(sql, params) {
+      return asRows(await db.prepare(sql).bind(...params).all());
+    },
+    async batch(statements) {
+      if (!db.batch) {
+        const results: Record<string, unknown>[][] = [];
+        for (const statement of statements) {
+          results.push(asRows(await db.prepare(statement.sql).bind(...statement.params).all()));
+        }
+        return results;
+      }
+      const bound: unknown[] = statements.map((statement) => db.prepare(statement.sql).bind(...statement.params));
+      const results = await db.batch(bound);
+      return results.map((result) => asRows(result));
+    },
+  };
+}
+
+function sumQuantity(rows: readonly Record<string, unknown>[]): number {
+  let total = 0;
+  for (const row of rows) {
+    const quantity = row.quantity;
+    if (typeof quantity === "number" && Number.isSafeInteger(quantity) && quantity > 0) total += quantity;
+  }
+  return total;
+}
+
+function text(row: Record<string, unknown>, key: string): string {
+  const value = row[key];
+  return typeof value === "string" ? value : "";
+}
+
+function reserveShape(input: ReserveInput): ReserveResult | null {
+  if (!ID_RE.test(input.tenantId) || !ID_RE.test(input.orderId)) return { ok: false, finding: "malformed-request" };
+  if (input.stage !== "preview" && input.stage !== "publication") return { ok: false, finding: "malformed-request" };
+  if (!DIGEST_RE.test(input.cartDigest) || !/^[A-Z]{3}$/.test(input.currency)) return { ok: false, finding: "malformed-request" };
+  if (!ISSUER_RE.test(input.issuer) || !JTI_RE.test(input.jti)) return { ok: false, finding: "malformed-request" };
+  if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return { ok: false, finding: "malformed-request" };
+  if (input.holds.length < 1) return { ok: false, finding: "malformed-request" };
+  for (const hold of input.holds) {
+    if (!SKU_RE.test(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
+    if (!Number.isSafeInteger(hold.quantity) || hold.quantity < 1) return { ok: false, finding: "malformed-request" };
+    if (!Number.isSafeInteger(hold.onHand) || hold.onHand < 0) return { ok: false, finding: "malformed-request" };
+  }
+  return null;
+}
+
+function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string): SqlStatement {
+  return {
+    sql: `INSERT INTO scrappy_allocations (tenant_id, stage, order_id, sku, location_id, quantity, state)
+      SELECT ?, ?, ?, ?, ?, ?, 'reserved'
+      WHERE (
+        SELECT COALESCE(SUM(quantity), 0) FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ? AND state IN ('reserved', 'confirmed')
+      ) + ? <= ?
+      AND NOT EXISTS (
+        SELECT 1 FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sku = ? AND location_id = ?
+          AND state IN ('reserved', 'confirmed')
+      )
+      AND NOT EXISTS (
+        SELECT 1 FROM scrappy_final_cart_authorizations
+        WHERE tenant_id = ? AND stage = ? AND cart_digest = ? AND state IN ('active', 'consumed')
+      )
+      AND EXISTS (
+        SELECT 1 FROM scrappy_caller_replay
+        WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ? AND seen_at = ?
+      )
+      AND EXISTS (
+        SELECT 1 FROM scrappy_commerce_orders
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+      )
+      ON CONFLICT DO NOTHING
+      RETURNING order_id`,
+    params: [
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      hold.sku,
+      hold.locationId,
+      hold.quantity,
+      input.tenantId,
+      input.stage,
+      hold.sku,
+      hold.locationId,
+      hold.quantity,
+      hold.onHand,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      hold.sku,
+      hold.locationId,
+      input.tenantId,
+      input.stage,
+      input.cartDigest,
+      input.tenantId,
+      input.stage,
+      input.issuer,
+      input.jti,
+      seenAt,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+    ],
+  };
+}
+
+/** Admit one hold per sku. A second active digest returns the existing authorization. */
+export async function reserveAllocation(runner: StatementRunner, input: ReserveInput): Promise<ReserveResult> {
+  const malformed = reserveShape(input);
+  if (malformed) return malformed;
+  const seen = await runner.all(
+    `SELECT jti FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+    [input.tenantId, input.stage, input.issuer, input.jti],
+  );
+  if (seen.length > 0) return { ok: false, finding: "caller-replay" };
+
+  const seenAt = `${input.now}|${crypto.randomUUID()}`;
+  const holds = [...input.holds].sort((left, right) => left.sku.localeCompare(right.sku) || left.locationId.localeCompare(right.locationId));
+  const statements: SqlStatement[] = [
+    {
+      sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT DO NOTHING
+        RETURNING jti`,
+      params: [input.tenantId, input.stage, input.issuer, input.jti, seenAt],
+    },
+    {
+      sql: `INSERT INTO scrappy_commerce_orders (
+          tenant_id, stage, order_id, source, source_order_id, currency, placed_at,
+          payment_state, compliance_state, stock_state, fulfillment_state, label_state,
+          amount_minor, event_version
+        ) VALUES (?, ?, ?, 'scrappy', ?, ?, ?, 'pending', 'UNKNOWN', 'unallocated', 'held', 'none', ?, 1)
+        ON CONFLICT DO NOTHING
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, input.orderId, input.orderId, input.currency, input.now, input.amountMinor],
+    },
+    ...holds.map((hold) => allocationInsert(input, hold, seenAt)),
+    {
+      sql: `INSERT INTO scrappy_final_cart_authorizations (
+          tenant_id, stage, authorization_id, cart_digest, expires_at, state
+        )
+        SELECT ?, ?, ?, ?, ?, 'active'
+        WHERE (
+          SELECT COUNT(*) FROM scrappy_allocations
+          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'reserved'
+        ) = ?
+        AND NOT EXISTS (
+          SELECT 1 FROM scrappy_final_cart_authorizations
+          WHERE tenant_id = ? AND stage = ? AND cart_digest = ? AND state IN ('active', 'consumed')
+        )
+        AND EXISTS (
+          SELECT 1 FROM scrappy_caller_replay
+          WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ? AND seen_at = ?
+        )
+        ON CONFLICT DO NOTHING
+        RETURNING authorization_id`,
+      params: [
+        input.tenantId,
+        input.stage,
+        input.orderId,
+        input.cartDigest,
+        input.expiresAt,
+        input.tenantId,
+        input.stage,
+        input.orderId,
+        holds.length,
+        input.tenantId,
+        input.stage,
+        input.cartDigest,
+        input.tenantId,
+        input.stage,
+        input.issuer,
+        input.jti,
+        seenAt,
+      ],
+    },
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'released'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'reserved'
+          AND NOT EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage, input.orderId, input.tenantId, input.stage, input.orderId],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = 'reserved'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+          AND EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          )
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, input.orderId, input.tenantId, input.stage, input.orderId],
+    },
+    {
+      sql: `SELECT authorization_id, expires_at FROM scrappy_final_cart_authorizations
+        WHERE tenant_id = ? AND stage = ? AND cart_digest = ? AND state IN ('active', 'consumed')
+        ORDER BY CASE state WHEN 'active' THEN 0 ELSE 1 END
+        LIMIT 1`,
+      params: [input.tenantId, input.stage, input.cartDigest],
+    },
+  ];
+
+  const results = await runner.batch(statements);
+  const replayRows = results[0] ?? [];
+  const authRows = results[2 + holds.length] ?? [];
+  const selected = results[results.length - 1] ?? [];
+  if (authRows.length > 0) {
+    return { ok: true, authorizationId: input.orderId, repeated: false, expiresAt: input.expiresAt };
+  }
+  if (replayRows.length === 0) return { ok: false, finding: "caller-replay" };
+  const existing = selected[0];
+  if (existing) {
+    return {
+      ok: true,
+      authorizationId: text(existing, "authorization_id"),
+      repeated: true,
+      expiresAt: text(existing, "expires_at"),
+    };
+  }
+  return { ok: false, finding: "stock-unavailable" };
+}
+
+export async function releaseHoldOnce(
+  runner: StatementRunner,
+  input: {
+    tenantId: string;
+    stage: CommerceStage;
+    orderId: string;
+    allocationState: "released" | "expired";
+    authState: "denied" | "expired";
+    orderStock: StockState;
+  },
+): Promise<number> {
+  const scope = [input.tenantId, input.stage, input.orderId];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_final_cart_authorizations
+        SET state = ?
+        WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state IN ('active', 'consumed')
+        RETURNING authorization_id`,
+      params: [input.authState, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = ?
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state IN ('reserved', 'confirmed')
+        RETURNING quantity`,
+      params: [input.allocationState, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = ?
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND stock_state IN ('reserved', 'confirmed')
+        RETURNING order_id`,
+      params: [input.orderStock, ...scope],
+    },
+  ]);
+  return sumQuantity(results[1] ?? []);
+}
+
+export async function settleExpired(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage; now: string; orderId?: string; force: boolean },
+): Promise<number> {
+  const orderId = input.orderId ?? "";
+  const force = input.force ? 1 : 0;
+  const due = [input.tenantId, input.stage, orderId, orderId, input.now, force];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_final_cart_authorizations
+        SET state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND state = 'active'
+          AND (? = '' OR authorization_id = ?)
+          AND (expires_at <= ? OR ? = 1)
+        RETURNING authorization_id`,
+      params: due,
+    },
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND state = 'reserved'
+          AND order_id IN (
+            SELECT authorization_id FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND state = 'expired'
+              AND (? = '' OR authorization_id = ?)
+              AND (expires_at <= ? OR ? = 1)
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage, ...due],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND stock_state IN ('reserved', 'confirmed')
+          AND order_id IN (
+            SELECT authorization_id FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND state = 'expired'
+              AND (? = '' OR authorization_id = ?)
+              AND (expires_at <= ? OR ? = 1)
+          )
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, ...due],
+    },
+  ]);
+  return sumQuantity(results[1] ?? []);
+}
+
+export async function releaseOrphanAllocations(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage },
+): Promise<number> {
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'released'
+        WHERE tenant_id = ? AND stage = ?
+          AND state IN ('reserved', 'confirmed')
+          AND NOT EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations AS auth
+            WHERE auth.tenant_id = scrappy_allocations.tenant_id
+              AND auth.stage = scrappy_allocations.stage
+              AND auth.authorization_id = scrappy_allocations.order_id
+              AND auth.state IN ('active', 'consumed')
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage],
+    },
+  ]);
+  return sumQuantity(results[0] ?? []);
+}
+
+interface OrderRow {
+  payment: PaymentState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+}
+
+async function loadOrder(
+  runner: StatementRunner,
+  tenantId: string,
+  stage: CommerceStage,
+  orderId: string,
+): Promise<OrderRow | null> {
+  const rows = await runner.all(
+    `SELECT payment_state, stock_state, fulfillment_state, label_state
+     FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    [tenantId, stage, orderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  const allocs = await runner.all(
+    `SELECT state FROM scrappy_allocations WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    [tenantId, stage, orderId],
+  );
+  const states = allocs.map((alloc) => text(alloc, "state"));
+  const stock = states.includes("reserved")
+    ? "reserved"
+    : states.includes("confirmed")
+      ? "confirmed"
+      : (text(row, "stock_state") as StockState);
+  return {
+    payment: text(row, "payment_state") as PaymentState,
+    stock,
+    fulfillment: text(row, "fulfillment_state") as FulfillmentState,
+    label: text(row, "label_state") as LabelState,
+  };
+}
+
+function commandFinding(reason: string): string {
+  switch (reason) {
+    case "stock":
+      return "stock-unknown";
+    case "fulfillment":
+      return "fulfillment-refused";
+    case "reconcile":
+      return "payment-reconcile";
+    case "payment":
+      return "payment-refused";
+    case "evidence":
+      return "evidence-refused";
+    default:
+      return "fulfillment-refused";
+  }
+}
+
+/** Move reserved units to confirmed once. A second call decrements nothing. */
+export async function confirmHoldOnce(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage; orderId: string },
+): Promise<{ decremented: number; states: string[] }> {
+  const scope = [input.tenantId, input.stage, input.orderId];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'confirmed'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'reserved'
+          AND EXISTS (
+            SELECT 1 FROM scrappy_commerce_orders
+            WHERE tenant_id = ? AND stage = ? AND order_id = ?
+              AND fulfillment_state IN ('held', 'ready')
+              AND payment_state IN ('pending', 'authorized', 'captured')
+          )
+          AND EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          )
+        RETURNING quantity`,
+      params: [...scope, ...scope, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_final_cart_authorizations
+        SET state = 'consumed'
+        WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          AND EXISTS (
+            SELECT 1 FROM scrappy_allocations
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'confirmed'
+          )
+        RETURNING authorization_id`,
+      params: [...scope, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET payment_state = CASE
+              WHEN payment_state IN ('pending', 'authorized') THEN 'captured'
+              ELSE payment_state
+            END,
+            stock_state = 'confirmed'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+          AND fulfillment_state IN ('held', 'ready')
+          AND payment_state IN ('pending', 'authorized', 'captured')
+          AND EXISTS (
+            SELECT 1 FROM scrappy_allocations
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'confirmed'
+          )
+        RETURNING order_id`,
+      params: [...scope, ...scope],
+    },
+    {
+      sql: `SELECT state FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      params: scope,
+    },
+  ]);
+  return {
+    decremented: sumQuantity(results[0] ?? []),
+    states: (results[3] ?? []).map((row) => text(row, "state")),
+  };
+}
+
+/** Apply the recorded release policy. `restock` stays false on every result. */
+export async function applyAllocationPolicy(runner: StatementRunner, input: PolicyInput): Promise<PolicyResult> {
+  const scope = { tenantId: input.tenantId, stage: input.stage };
+  if (input.kind === "confirm") {
+    if (!input.orderId) return { released: 0, restock: false, decremented: 0, finding: "order-absent" };
+    const order = await loadOrder(runner, input.tenantId, input.stage, input.orderId);
+    if (!order) return { released: 0, restock: false, decremented: 0, finding: "order-absent" };
+    if (order.fulfillment === "handed_off") return { released: 0, restock: false, decremented: 0, finding: "shipped-out-of-scope" };
+    if (order.fulfillment === "cancelled" || order.fulfillment === "UNKNOWN") {
+      return { released: 0, restock: false, decremented: 0, finding: "fulfillment-refused" };
+    }
+    const confirmed = await confirmHoldOnce(runner, { tenantId: input.tenantId, stage: input.stage, orderId: input.orderId });
+    if (confirmed.decremented > 0) return { released: 0, restock: false, decremented: confirmed.decremented, finding: "confirmed" };
+    if (confirmed.states.includes("confirmed")) return { released: 0, restock: false, decremented: 0, finding: "already-confirmed" };
+    return { released: 0, restock: false, decremented: 0, finding: "already-released" };
+  }
+  if (input.kind === "restart") {
+    const released = await releaseOrphanAllocations(runner, scope);
+    return { released, restock: false, finding: "restart-reconciled" };
+  }
+  if (input.kind === "expiry" || input.kind === "timeout") {
+    const released = await settleExpired(runner, {
+      ...scope,
+      now: input.now ?? "",
+      orderId: input.orderId,
+      force: input.kind === "timeout",
+    });
+    return { released, restock: false, finding: released > 0 ? "expired" : "already-released" };
+  }
+  if (!input.orderId) return { released: 0, restock: false, finding: "order-absent" };
+  const order = await loadOrder(runner, input.tenantId, input.stage, input.orderId);
+  if (!order) return { released: 0, restock: false, finding: "order-absent" };
+
+  if (input.kind === "payment-failure") {
+    if (order.fulfillment === "handed_off") return { released: 0, restock: false, finding: "shipped-out-of-scope" };
+    if (order.stock === "confirmed" || order.payment === "captured") {
+      return { released: 0, restock: false, finding: "already-confirmed" };
+    }
+    const released = await releaseHoldOnce(runner, {
+      tenantId: input.tenantId,
+      stage: input.stage,
+      orderId: input.orderId,
+      allocationState: "released",
+      authState: "denied",
+      orderStock: "released",
+    });
+    return { released, restock: false, finding: released > 0 ? "released" : "already-released" };
+  }
+
+  const decision = decideCommerceCommand({
+    command: input.kind,
+    payment: order.payment,
+    stock: order.stock,
+    fulfillment: order.fulfillment,
+    label: order.label,
+    evidence: input.evidence ?? FRESH_EVIDENCE,
+    providerOutcome: input.providerOutcome ?? null,
+  });
+  if (input.kind === "refund") {
+    return {
+      released: 0,
+      restock: false,
+      finding: decision.admit ? "refund-no-restock" : commandFinding(decision.reason),
+    };
+  }
+  if (!decision.admit || !decision.releaseReservation) {
+    return { released: 0, restock: false, finding: decision.admit ? "cancel-no-release" : commandFinding(decision.reason) };
+  }
+  const released = await releaseHoldOnce(runner, {
+    tenantId: input.tenantId,
+    stage: input.stage,
+    orderId: input.orderId,
+    allocationState: "released",
+    authState: "denied",
+    orderStock: "released",
+  });
+  return { released, restock: false, finding: released > 0 ? "released" : "already-released" };
+}

package/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -0,0 +1,366 @@
+/**
+ * POST /api/commerce/final-cart-authorization — time-limited final-cart admission.
+ * Caller-owned asymmetric tokens only. Catalog availability, a browser confirmation,
+ * and missing verification evidence do not authorize payment.
+ */
+import type { APIContext } from "astro";
+import { createLocalJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify, type JSONWebKeySet, type JWTPayload } from "jose";
+import type { TenantConfig } from "@tot/public-runtime";
+import {
+  type CallerToken,
+  type CommerceEvidence,
+  type CommerceStage,
+  type EvidenceState,
+  type FinalCartBinding,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+import { fromD1, listAllActiveProducts } from "@/lib/d1/catalog.js";
+import { readD1, readEnv } from "@/lib/env";
+import { evaluateFinalCart, type SeamView } from "@/lib/commerce/finalCartAuthorization.js";
+import { d1CommerceRunner, mirrorOnHand, reserveAllocation } from "@/lib/inventory/allocations.js";
+import { POST as compliancePreflight } from "../compliance/preflight.js";
+
+export const prerender = false;
+
+const EVIDENCE_STATES = new Set(["fresh", "UNKNOWN", "stale", "unreadable", "absent"]);
+const STAGES = new Set(["preview", "publication"]);
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+  });
+}
+
+function deny(finding: string, status: number, owner?: string): Response {
+  return json(owner ? { ok: false, finding, owner } : { ok: false, finding }, status);
+}
+
+function statusFor(finding: string): number {
+  if (finding === "store-unconfigured" || finding === "caller-unconfigured") return 503;
+  if (
+    finding === "browser-not-authority" ||
+    finding === "tenant-unbound" ||
+    finding === "shared-secret" ||
+    finding === "signature" ||
+    finding === "kid" ||
+    finding === "issuer" ||
+    finding === "audience" ||
+    finding === "expired" ||
+    finding === "lifetime" ||
+    finding === "jti" ||
+    finding === "tenant" ||
+    finding === "stage"
+  ) {
+    return 401;
+  }
+  return 409;
+}
+
+function claimString(payload: JWTPayload, key: string): string {
+  const value = payload[key];
+  return typeof value === "string" ? value : "";
+}
+
+function parseList(value: string | undefined): string[] | null {
+  if (!value || value.trim() === "") return null;
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string" || item.trim() === "")) return null;
+      return parsed as string[];
+    } catch {
+      return null;
+    }
+  }
+  const parts = trimmed.split(",").map((part) => part.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : null;
+}
+
+function publicJwks(value: string | undefined): JSONWebKeySet | null {
+  if (!value) return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== "object" || !Array.isArray((parsed as { keys?: unknown }).keys)) return null;
+    const keys = (parsed as { keys: unknown[] }).keys;
+    if (keys.length < 1) return null;
+    for (const key of keys) {
+      if (!key || typeof key !== "object") return null;
+      const record = key as Record<string, unknown>;
+      if (typeof record.d === "string" || record.kty === "oct" || typeof record.k === "string") return null;
+    }
+    return parsed as JSONWebKeySet;
+  } catch {
+    return null;
+  }
+}
+
+function readCart(value: unknown): FinalCartBinding | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  if (typeof record.tenantId !== "string" || typeof record.currency !== "string" || typeof record.destinationDigest !== "string") {
+    return null;
+  }
+  if (typeof record.stage !== "string" || !STAGES.has(record.stage)) return null;
+  if (typeof record.verificationExpiresAt !== "string" || typeof record.taxExpiresAt !== "string") return null;
+  if (!Array.isArray(record.lines) || record.lines.length > 50) return null;
+  const lines = [];
+  for (const line of record.lines) {
+    if (!line || typeof line !== "object") return null;
+    const row = line as Record<string, unknown>;
+    if (typeof row.sku !== "string" || typeof row.quantity !== "number" || typeof row.unitMinor !== "number") return null;
+    lines.push({ sku: row.sku, quantity: row.quantity, unitMinor: row.unitMinor });
+  }
+  return {
+    tenantId: record.tenantId,
+    stage: record.stage as CommerceStage,
+    currency: record.currency,
+    lines,
+    destinationDigest: record.destinationDigest,
+    verificationExpiresAt: record.verificationExpiresAt,
+    taxExpiresAt: record.taxExpiresAt,
+  };
+}
+
+function readEvidence(value: unknown): CommerceEvidence | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const evidence = {} as CommerceEvidence;
+  for (const field of ["verification", "tax", "risk", "stock"] as const) {
+    const state = record[field];
+    if (typeof state !== "string" || !EVIDENCE_STATES.has(state)) return null;
+    evidence[field] = state as EvidenceState;
+  }
+  return evidence;
+}
+
+function readState<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value) ? (value as T) : undefined;
+}
+
+function destinationOf(value: unknown): { region: string; country: string } | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const region = typeof record.region === "string" ? record.region.trim() : "";
+  const country = typeof record.country === "string" ? record.country.trim() : "";
+  if (!/^[A-Za-z]{2}$/.test(region)) return null;
+  if (country !== "" && !/^[A-Za-z]{2}$/.test(country)) return null;
+  return { region: region.toUpperCase(), country: country === "" ? "US" : country.toUpperCase() };
+}
+
+async function catalogOffers(sku: string): Promise<boolean> {
+  const database = await readD1("CATALOG_DB");
+  if (!database) return false;
+  try {
+    const products = await listAllActiveProducts(fromD1(database));
+    for (const product of products) {
+      for (const variant of product.variants) {
+        if (variant.sku === sku && variant.inventory.available === true) return true;
+      }
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+async function verificationSeam(
+  context: APIContext,
+  cart: FinalCartBinding,
+  destination: { region: string; country: string } | null,
+): Promise<SeamView> {
+  const tot = (context.locals as { tot?: { getProductByHandle: (handle: string) => Promise<unknown> } }).tot ?? {
+    getProductByHandle: async () => null,
+  };
+  const response = await compliancePreflight({
+    request: new Request("https://synthetic-tenant.invalid/api/compliance/preflight", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        lines: cart.lines.map((line) => ({ handle: line.sku, sku: line.sku, quantity: line.quantity })),
+        ...(destination ? { destination: { region: destination.region, country: destination.country } } : {}),
+      }),
+    }),
+    locals: { tenant: context.locals.tenant, tot },
+  } as APIContext);
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    return { status: "absent" };
+  }
+  const decision = body && typeof body === "object" ? (body as { decision?: { status?: unknown; failedClosed?: unknown; blocks?: unknown } }).decision : undefined;
+  if (!decision || decision.status === "clear") return { status: decision ? "clear" : "absent" };
+  const blocks = Array.isArray(decision.blocks) ? decision.blocks : [];
+  const codes = blocks
+    .map((block) => (block && typeof block === "object" ? (block as { code?: unknown }).code : undefined))
+    .filter((code): code is string => typeof code === "string");
+  return { status: "blocked", failedClosed: decision.failedClosed === true, codes };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const tenant = context.locals.tenant as TenantConfig | undefined;
+  const appDomain = tenant?.appDomain ?? "";
+  if (!tenant || appDomain === "") return deny("tenant-unbound", 401);
+
+  let body: Record<string, unknown>;
+  try {
+    const parsed = await context.request.json();
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return deny("malformed-request", 409);
+    body = parsed as Record<string, unknown>;
+  } catch {
+    return deny("malformed-request", 409);
+  }
+
+  if (body.scheme === "shared-secret") {
+    const decision = await evaluateFinalCart({
+      now: new Date().toISOString(),
+      routedTenantId: appDomain,
+      quoted: readCart(body.quoted) ?? emptyCart(appDomain),
+      presented: readCart(body.presented) ?? emptyCart(appDomain),
+      evidence: readEvidence(body.evidence),
+      seam: { status: "clear" },
+      catalogAvailable: false,
+      browserConfirmed: body.browserConfirmed === true,
+      token: { scheme: "shared-secret" },
+      trustedIssuers: [],
+      expectedAudience: "",
+      activeKids: [],
+      authorities: [],
+    });
+    return deny(decision.ok ? "shared-secret" : decision.finding, statusFor(decision.ok ? "shared-secret" : decision.finding), decision.ok ? undefined : decision.owner);
+  }
+
+  const quoted = readCart(body.quoted);
+  const presented = readCart(body.presented);
+  if (!quoted || !presented) return deny("malformed-request", 409);
+
+  const jwks = publicJwks(await readEnv("SCRAPPY_CALLER_JWKS"));
+  const issuers = parseList(await readEnv("SCRAPPY_CALLER_ISSUERS"));
+  const audience = await readEnv("SCRAPPY_CALLER_AUDIENCE");
+  const activeKids = parseList(await readEnv("SCRAPPY_CALLER_ACTIVE_KIDS"));
+  if (!jwks || !issuers || !audience || !activeKids) return deny("caller-unconfigured", 503);
+
+  const header = context.request.headers.get("authorization") ?? "";
+  const bearer = header.startsWith("Bearer ") ? header.slice("Bearer ".length).trim() : "";
+  let token: CallerToken | null = null;
+  if (bearer !== "") {
+    try {
+      const decoded = decodeJwt(bearer);
+      const protectedHeader = decodeProtectedHeader(bearer);
+      let signatureValid = false;
+      try {
+        await jwtVerify(bearer, createLocalJWKSet(jwks), { algorithms: ["EdDSA"] });
+        signatureValid = true;
+      } catch (error) {
+        const code = error && typeof error === "object" && "code" in error ? String((error as { code: unknown }).code) : "";
+        signatureValid = code === "ERR_JWT_EXPIRED" || code === "ERR_JWT_CLAIM_VALIDATION_FAILED";
+      }
+      const exp = typeof decoded.exp === "number" ? new Date(decoded.exp * 1000).toISOString() : "";
+      const audienceClaim = typeof decoded.aud === "string" ? decoded.aud : Array.isArray(decoded.aud) ? decoded.aud[0] ?? "" : "";
+      const stageClaim = claimString(decoded, "stage");
+      const stage: CommerceStage =
+        stageClaim === "preview" || stageClaim === "publication"
+          ? stageClaim
+          : presented.stage === "preview"
+            ? "publication"
+            : "preview";
+      token = {
+        scheme: "asymmetric-jwks",
+        signatureValid,
+        kid: typeof protectedHeader.kid === "string" ? protectedHeader.kid : "",
+        issuer: typeof decoded.iss === "string" ? decoded.iss : "",
+        audience: audienceClaim,
+        expiresAt: exp,
+        jti: claimString(decoded, "jti"),
+        tenantId: claimString(decoded, "tenantId"),
+        stage,
+      };
+    } catch {
+      token = null;
+    }
+  }
+
+  const provider = tenant.inventory?.provider ?? "mirror";
+  const authorities: unknown[] = [];
+  const now = new Date().toISOString();
+  if (provider !== "mirror") {
+    authorities.push({ provider, sku: presented.lines[0]?.sku });
+  } else {
+    const skus = [...new Set(presented.lines.map((line) => line.sku))];
+    for (const sku of skus) {
+      const onHand = mirrorOnHand(sku, "unspecified");
+      authorities.push(
+        onHand == null
+          ? null
+          : { provider: "mirror", readable: true, locationId: "unspecified", sku, onHand, asOf: now },
+      );
+    }
+  }
+  let catalogAvailable = false;
+  for (const line of presented.lines) {
+    if (await catalogOffers(line.sku)) catalogAvailable = true;
+  }
+
+  const decision = await evaluateFinalCart({
+    now,
+    routedTenantId: appDomain,
+    quoted,
+    presented,
+    evidence: readEvidence(body.evidence),
+    seam: await verificationSeam(context, presented, destinationOf(body.destination)),
+    catalogAvailable,
+    browserConfirmed: body.browserConfirmed === true,
+    token,
+    trustedIssuers: issuers,
+    expectedAudience: audience,
+    activeKids,
+    authorities,
+    payment: readState<PaymentState>(body.payment, ["UNKNOWN", "pending", "authorized", "captured", "capture_unknown", "voided", "refund_requested", "refunded", "refund_unknown"]),
+    stock: readState<StockState>(body.stock, ["UNKNOWN", "unallocated", "reserved", "confirmed", "released", "expired"]),
+    fulfillment: readState<FulfillmentState>(body.fulfillment, ["UNKNOWN", "held", "ready", "handed_off", "cancelled"]),
+    label: readState<LabelState>(body.label, ["UNKNOWN", "none", "intent", "purchased", "printed", "void_requested", "voided"]),
+  });
+  if (!decision.ok) return deny(decision.finding, statusFor(decision.finding), decision.owner);
+
+  const database = await readD1("STOREFRONT_APPS_DB");
+  if (!database || typeof database.prepare !== "function") return deny("store-unconfigured", 503);
+  const reserved = await reserveAllocation(d1CommerceRunner(database), {
+    tenantId: decision.tenantId,
+    stage: decision.stage,
+    orderId: `a${crypto.randomUUID()}`,
+    cartDigest: decision.digest,
+    expiresAt: decision.expiresAt,
+    now,
+    currency: presented.currency,
+    amountMinor: decision.amountMinor,
+    issuer: decision.issuer,
+    jti: decision.jti,
+    holds: decision.holds,
+  });
+  if (!reserved.ok) return deny(reserved.finding, statusFor(reserved.finding));
+  return json({
+    ok: true,
+    authorizationId: reserved.authorizationId,
+    cartDigest: decision.digest,
+    expiresAt: reserved.expiresAt,
+    repeated: reserved.repeated,
+    stage: decision.stage,
+  });
+}
+
+function emptyCart(tenantId: string): FinalCartBinding {
+  return {
+    tenantId,
+    stage: "preview",
+    currency: "USD",
+    lines: [{ sku: "sku-1", quantity: 1, unitMinor: 0 }],
+    destinationDigest: "dest-synthetic",
+    verificationExpiresAt: "1970-01-01T00:00:00.000Z",
+    taxExpiresAt: "1970-01-01T00:00:00.000Z",
+  };
+}

package/package.json

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