@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

package/apps/storefront/src/lib/auth/stepUpChallenge.ts

@@ -0,0 +1,107 @@
+/**
+ * RFC 9470 step-up challenge types + classification — storefront's OWN port.
+ *
+ * storefront's server calls tot CORE's internal routes directly with machine
+ * creds (`totAccessClient.ts`), never through the tot-mcp gateway. That means
+ * there is NO `WWW-Authenticate` header on this path (that header only exists
+ * on the gateway) — CORE signals a step-up challenge or a pending identity-bind
+ * as PLAIN JSON on the response BODY. This module classifies that (already
+ * envelope-unwrapped) body into a typed result.
+ *
+ * This mirrors launchpad's step-up parser/`runWithStepUp` helper in spirit, but
+ * is a deliberately independent, storefront-owned module: storefront is a
+ * separate repo with disjoint history and cannot import launchpad's kernel.
+ *
+ * Verified shapes (tot20 @ bb66934f / qa core):
+ *   STEP-UP challenge (HTTP 401):
+ *     { ok:false, reason:'step-up-required',
+ *       obligations:[{ type:'step-up', requiredTier, requiredAcr, maxAuthAgeSeconds, message }] }
+ *   SUCCESS-PENDING (HTTP 2xx, identity-bind):
+ *     { ok:true, signinEnabled:false, obligations:[...] }
+ */
+
+/** A single obligation tot20 attaches to a step-up/pending response. */
+export interface StepUpObligation {
+  type: "step-up" | "dpop-required" | "reauthenticate";
+  requiredAcr?: string;
+  requiredAmr?: string[];
+  requiredTier?: string;
+  maxAuthAgeSeconds?: string | number;
+  message?: string;
+}
+
+/** The step-up challenge, flattened from the first `type:'step-up'` obligation. */
+export interface StepUpChallenge {
+  obligations: StepUpObligation[];
+  requiredAcr?: string;
+  requiredTier?: string;
+  maxAuthAgeSeconds?: string | number;
+}
+
+export type StepUpClassification =
+  | { kind: "step-up-required"; challenge: StepUpChallenge }
+  | { kind: "success-pending"; obligations: StepUpObligation[] }
+  | { kind: "none" };
+
+const OBLIGATION_TYPES = new Set(["step-up", "dpop-required", "reauthenticate"]);
+
+/** Parse + validate an `obligations` field into typed obligations (fail-open to `[]`). */
+function toObligations(raw: unknown): StepUpObligation[] {
+  if (!Array.isArray(raw)) return [];
+  const out: StepUpObligation[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const o = item as Record<string, unknown>;
+    if (typeof o.type !== "string" || !OBLIGATION_TYPES.has(o.type)) continue;
+    const obligation: StepUpObligation = { type: o.type as StepUpObligation["type"] };
+    if (typeof o.requiredAcr === "string") obligation.requiredAcr = o.requiredAcr;
+    if (Array.isArray(o.requiredAmr)) {
+      obligation.requiredAmr = o.requiredAmr.filter((a): a is string => typeof a === "string");
+    }
+    if (typeof o.requiredTier === "string") obligation.requiredTier = o.requiredTier;
+    if (typeof o.maxAuthAgeSeconds === "string" || typeof o.maxAuthAgeSeconds === "number") {
+      obligation.maxAuthAgeSeconds = o.maxAuthAgeSeconds;
+    }
+    if (typeof o.message === "string") obligation.message = o.message;
+    out.push(obligation);
+  }
+  return out;
+}
+
+/**
+ * Classify an UNWRAPPED tot CORE response body (already stripped of the
+ * `{ content, metadata }` envelope) into a step-up state. Pure + independently
+ * testable — `normalizeFederatedVerify` calls this BEFORE its `b.ok === true`
+ * branch so every other body shape falls through unchanged.
+ */
+export function classifyStepUp(body: unknown): StepUpClassification {
+  if (!body || typeof body !== "object") return { kind: "none" };
+  const b = body as Record<string, unknown>;
+  const obligations = toObligations(b.obligations);
+
+  // SUCCESS-PENDING: identity bound (HTTP 2xx, `ok:true`), sign-in awaits
+  // step-up completion. Checked FIRST because `ok:true` bodies never fall into
+  // the step-up-required (HTTP 401, `ok:false`) branch below, even though both
+  // shapes carry the same `type:'step-up'` obligation riding along.
+  if (b.ok === true) {
+    return b.signinEnabled === false ? { kind: "success-pending", obligations } : { kind: "none" };
+  }
+
+  // STEP-UP challenge (`ok:false`): signalled either by the explicit `reason`,
+  // or by an obligation of type `step-up` riding along on the response.
+  const stepUpObligation = obligations.find((o) => o.type === "step-up");
+  if (b.reason === "step-up-required" || stepUpObligation) {
+    const first = stepUpObligation ?? obligations[0];
+    return {
+      kind: "step-up-required",
+      challenge: {
+        obligations,
+        requiredAcr: first?.requiredAcr,
+        requiredTier: first?.requiredTier,
+        maxAuthAgeSeconds: first?.maxAuthAgeSeconds,
+      },
+    };
+  }
+
+  return { kind: "none" };
+}

package/apps/storefront/src/lib/auth/totAccessClient.ts

@@ -28,6 +28,7 @@
  */
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
+import { classifyStepUp, type StepUpChallenge, type StepUpObligation } from "./stepUpChallenge.js";
 
 /** `send` is deliberately opaque — it never reveals whether the email was eligible. */
 export interface AccessCodeSendResult {
@@ -92,6 +93,31 @@ export interface TotAccessClient {
    * authenticated caller server-side, never passed in the body.
    */
   exchangeSignInToken(token: string): Promise<FederatedVerifyResult>;
+  /**
+   * MINT a fresh single-use sign-in token for `email`, bound to (email, aud = THIS
+   * caller's appDomain), by calling tot20's access-code `/mint` as the storefront's
+   * OWN machine credential. Unlike `developerInvites` this is NOT operator-grant-gated
+   * per tenant — tot20 re-resolves the email's memberships fresh at exchange. Used to
+   * RE-ISSUE a dev's identity proof at CLI-sign-in approve time (subjectReissue), where
+   * the id_token's `aud` (= the storefront appDomain = the MCP client_id) is exactly
+   * what the MCP binds the subject_token to. Fails closed.
+   */
+  mintSignInToken(email: string, ttlSeconds?: number): Promise<SignInTokenMintResult>;
+  /**
+   * STEP-UP COMPLETION (SMS), leg 1: ask tot CORE to send a one-time SMS code to
+   * `identifier` (the identifier bound during a `step-up-required` challenge or a
+   * `success-pending` identity-bind). Neutral-on-failure — mirrors
+   * {@link sendFederatedCode}: a transport error still resolves `{ ok: true }` so
+   * the caller never learns whether the identifier was valid/eligible.
+   */
+  sendSmsChallenge(identifier: string): Promise<{ ok: true }>;
+  /**
+   * STEP-UP COMPLETION (SMS), leg 2: verify the code. On success the response
+   * carries the FRESHER `id_token` (acr `tot:aal:sms`, fresh `auth_time`) that
+   * satisfies the step-up obligation — the caller re-derives the session from it
+   * exactly like a normal federated verify. Fail-closed typed on any other shape.
+   */
+  verifySmsChallenge(identifier: string, code: string): Promise<SmsVerifyResult>;
 }
 
 /**
@@ -99,9 +125,27 @@ export interface TotAccessClient {
  * claims — email + all `tenants[]` — are the sole authority) and the `audience`
  * tot set (= the calling app). `id_token` is present-usually, not guaranteed
  * (signer degradation, contract §6); the consumer fails closed when it's absent.
+ *
+ * The `step-up-required`/`success-pending` variants carry tot20's RFC 9470
+ * obligations (see `@/lib/auth/stepUpChallenge`) instead of a plain failure
+ * reason, so the caller can drive the SMS completion loop rather than just
+ * showing a generic "invalid code" error.
  */
 export type FederatedVerifyResult =
   | { ok: true; email: string; audience: string; id_token?: string }
+  | { ok: false; reason: "step-up-required"; stepUp: StepUpChallenge }
+  | { ok: false; reason: "success-pending"; obligations: StepUpObligation[] }
+  | { ok: false; reason: VerifyFailureReason };
+
+/** Result of {@link TotAccessClient.mintSignInToken}. The raw `token` is a single-use
+ * secret — server-to-server only, NEVER logged. */
+export type SignInTokenMintResult =
+  | { ok: true; token: string; expiresAt?: string; ttlSeconds?: number }
+  | { ok: false; reason: VerifyFailureReason };
+
+/** Result of {@link TotAccessClient.verifySmsChallenge}. */
+export type SmsVerifyResult =
+  | { ok: true; idToken: string; email?: string }
   | { ok: false; reason: VerifyFailureReason };
 
 // --- HTTP transport seam (injected by tests) --------------------------------
@@ -286,6 +330,82 @@ export class HttpTotAccessClient implements TotAccessClient {
     // authoritative email (no client-supplied fallback needed).
     return normalizeFederatedVerify(body, "");
   }
+
+  async mintSignInToken(email: string, ttlSeconds?: number): Promise<SignInTokenMintResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/mint`,
+        {},
+        {
+          email: email.toLowerCase(),
+          ...(ttlSeconds != null ? { ttlSeconds } : {}),
+          ...this.credentialFields(),
+        },
+      );
+    } catch (e) {
+      try {
+        console.warn("[diag:mint] transport error", e instanceof Error ? e.message : String(e));
+      } catch {
+        /* never break */
+      }
+      return { ok: false, reason: "error" };
+    }
+    let body: unknown = "(unread)";
+    try {
+      body = await res.json();
+    } catch {
+      body = "(non-JSON)";
+    }
+    const result = normalizeMint(body);
+    // DIAGNOSTIC (secret-safe): on a non-ok mint, log tot20's status + body so a
+    // 404 (path) / 401·403 (cred not accepted here) / 5xx is diagnosable. The `token`
+    // (only present on success) is never in this branch, so nothing sensitive leaks.
+    if (!result.ok) {
+      try {
+        console.warn("[diag:mint]", JSON.stringify({ status: res.status, body }));
+      } catch {
+        /* never break */
+      }
+    }
+    return result;
+  }
+
+  async sendSmsChallenge(identifier: string): Promise<{ ok: true }> {
+    // Neutral by contract, mirroring sendFederatedCode: a transport error still
+    // resolves { ok: true } so the caller never learns eligibility. Best-effort
+    // server-side diagnostic only.
+    try {
+      await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/identity-send`,
+        {},
+        { identifier, channel: "sms", ...this.credentialFields() },
+      );
+    } catch {
+      /* swallow — neutral response */
+    }
+    return { ok: true };
+  }
+
+  async verifySmsChallenge(identifier: string, code: string): Promise<SmsVerifyResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/identity-verify`,
+        {},
+        { identifier, channel: "sms", code, ...this.credentialFields() },
+      );
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    return normalizeSmsVerify(body);
+  }
 }
 
 /** Parse tot20's FEDERATED verify response into a typed result (fail closed). */
@@ -296,6 +416,18 @@ export function normalizeFederatedVerify(
   // Unwrap the `{ content, metadata }` envelope when present (see normalizeVerify).
   const raw = (body ?? {}) as Record<string, unknown>;
   const b = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+
+  // Classify BEFORE the `b.ok === true` branch: a step-up challenge is `ok:false`
+  // but success-pending is `ok:true` — both must be caught here, ahead of the
+  // ordinary success/failure handling below.
+  const stepUp = classifyStepUp(b);
+  if (stepUp.kind === "step-up-required") {
+    return { ok: false, reason: "step-up-required", stepUp: stepUp.challenge };
+  }
+  if (stepUp.kind === "success-pending") {
+    return { ok: false, reason: "success-pending", obligations: stepUp.obligations };
+  }
+
   if (b.ok === true) {
     const idToken =
       typeof b.id_token === "string"
@@ -319,6 +451,51 @@ export function normalizeFederatedVerify(
   };
 }
 
+/** Parse tot20's access-code `/mint` response into a typed result (fail closed). */
+export function normalizeMint(body: unknown): SignInTokenMintResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const b = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  if (b.ok === true && typeof b.token === "string" && b.token) {
+    const result: SignInTokenMintResult = { ok: true, token: b.token };
+    if (typeof b.expiresAt === "string") result.expiresAt = b.expiresAt;
+    if (typeof b.ttlSeconds === "number") result.ttlSeconds = b.ttlSeconds;
+    return result;
+  }
+  const reason = b.reason;
+  const known: VerifyFailureReason[] = ["invalid", "expired", "too_many_attempts", "error"];
+  return {
+    ok: false,
+    reason: known.includes(reason as VerifyFailureReason) ? (reason as VerifyFailureReason) : "error",
+  };
+}
+
+/** Parse tot20's SMS step-up-completion verify response (fail closed). */
+export function normalizeSmsVerify(body: unknown): SmsVerifyResult {
+  // Same envelope-unwrap convention as normalizeVerify/normalizeFederatedVerify.
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const b = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  if (b.ok === true) {
+    const idToken =
+      typeof b.id_token === "string"
+        ? b.id_token
+        : typeof b.assertion === "string"
+          ? b.assertion
+          : undefined;
+    // The fresher credential is the SOLE authority for completing step-up — fail
+    // closed if it's absent rather than trusting an unsigned "ok".
+    if (!idToken) return { ok: false, reason: "error" };
+    const result: SmsVerifyResult = { ok: true, idToken };
+    if (typeof b.email === "string") result.email = b.email.toLowerCase();
+    return result;
+  }
+  const reason = b.reason;
+  const known: VerifyFailureReason[] = ["invalid", "expired", "too_many_attempts", "error"];
+  return {
+    ok: false,
+    reason: known.includes(reason as VerifyFailureReason) ? (reason as VerifyFailureReason) : "invalid",
+  };
+}
+
 /** Parse + validate tot20's verify response into our typed result (fail closed). */
 export function normalizeVerify(
   body: unknown,
@@ -379,6 +556,8 @@ export class MockTotAccessClient implements TotAccessClient {
   /** key = `${resource}${emailLower}` → roster entry. */
   private roster = new Map<string, MockRosterEntry>();
   sent: Array<{ email: string; resource: string }> = [];
+  /** Identifiers the mock was asked to SMS-challenge (step-up completion). */
+  smsSent: string[] = [];
 
   constructor(
     private readonly code = "123456",
@@ -472,6 +651,35 @@ export class MockTotAccessClient implements TotAccessClient {
     }
     return { ok: false, reason: "invalid" };
   }
+
+  async mintSignInToken(email: string): Promise<SignInTokenMintResult> {
+    // Mirror the mock exchange's accepted shape ("mock|<tenant>|<email>") so a
+    // mint→exchange round-trip resolves back to this email in tests / local dev.
+    const token = Buffer.from(`mock|storefront|${email.toLowerCase()}`, "utf8").toString("base64url");
+    return { ok: true, token };
+  }
+
+  async sendSmsChallenge(identifier: string): Promise<{ ok: true }> {
+    this.smsSent.push(identifier);
+    return { ok: true }; // neutral regardless of eligibility
+  }
+
+  async verifySmsChallenge(identifier: string, code: string): Promise<SmsVerifyResult> {
+    if (code !== this.code) return { ok: false, reason: "invalid" };
+    // The mock has no private key material; it returns a deterministic
+    // placeholder token unless a real signer is wired in an integration test.
+    const idToken = this.signIdToken
+      ? await this.signIdToken({
+          email: identifier.toLowerCase(),
+          resource: "",
+          roles: [],
+          capability: "member",
+        })
+      : `mock-sms-id-token|${identifier.toLowerCase()}`;
+    const result: SmsVerifyResult = { ok: true, idToken };
+    if (identifier.includes("@")) result.email = identifier.toLowerCase();
+    return result;
+  }
 }
 
 /** Collapse a role array to one effective capability (mirrors tot20's precedence). */

package/apps/storefront/src/lib/blog/provider.ts

@@ -0,0 +1,39 @@
+import type { BlogPost, BlogPostSummary } from "./types.js";
+
+const indexGlobs = import.meta.glob<BlogPostSummary[]>(
+  "../../../../../tenants/*/content/blog/index.json",
+  { import: "default" },
+);
+const postGlobs = import.meta.glob<BlogPost>(
+  "../../../../../tenants/*/content/blog/posts/*.json",
+  { import: "default" },
+);
+const redirectGlobs = import.meta.glob<Record<string, string>>(
+  "../../../../../tenants/*/content/blog/redirects.json",
+  { import: "default" },
+);
+
+function tenantKey(keys: string[], tenantId: string, suffix: string): string | undefined {
+  const segment = `/tenants/${tenantId}/content/blog/`;
+  return keys.find((key) => key.includes(segment) && key.endsWith(suffix));
+}
+
+export async function listBlogPosts(tenantId: string): Promise<BlogPostSummary[]> {
+  const key = tenantKey(Object.keys(indexGlobs), tenantId, "/index.json")
+    ?? Object.keys(indexGlobs).find((candidate) => candidate.includes(`/tenants/${tenantId}/content/blog/index.json`));
+  return key ? indexGlobs[key]!() : [];
+}
+
+export async function getBlogPost(tenantId: string, slug: string): Promise<BlogPost | null> {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) return null;
+  const key = tenantKey(Object.keys(postGlobs), tenantId, `/posts/${slug}.json`);
+  return key ? postGlobs[key]!() : null;
+}
+
+export async function resolveBlogRedirect(tenantId: string, slug: string): Promise<string | null> {
+  const key = tenantKey(Object.keys(redirectGlobs), tenantId, "/redirects.json")
+    ?? Object.keys(redirectGlobs).find((candidate) => candidate.includes(`/tenants/${tenantId}/content/blog/redirects.json`));
+  if (!key) return null;
+  const redirects = await redirectGlobs[key]!();
+  return redirects[slug] ?? null;
+}

package/apps/storefront/src/lib/blog/types.ts

@@ -0,0 +1,26 @@
+export interface BlogImage {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+export interface BlogPostSummary {
+  source: { platform: "wordpress"; id: string };
+  slug: string;
+  title: string;
+  seoTitle: string;
+  description: string;
+  excerpt: string;
+  publishedAt: string;
+  modifiedAt: string;
+  author: string;
+  categories: string[];
+  tags: string[];
+  featuredImage?: BlogImage;
+}
+
+export interface BlogPost extends BlogPostSummary {
+  oldSlugs: string[];
+  contentHtml: string;
+}

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

@@ -47,5 +47,43 @@ export async function readCartSecret(
   commerce: ResolvedManagedCheckout,
 ): Promise<string | undefined> {
   if (commerce.mode !== "signed") return undefined;
-  return readEnv("FOXY_CART_SECRET");
+  const secret = await readEnv("FOXY_CART_SECRET");
+  return secret && secret.length ? secret : undefined;
+}
+
+/**
+ * The outcome of resolving whether — and how — a tenant may build add-to-cart
+ * forms this request.
+ *   - `enabled: true, secret: undefined`  → `unsigned-demo` (no secret needed).
+ *   - `enabled: true, secret: "…"`        → `signed` with its validation secret.
+ *   - `enabled: false`                    → FAIL CLOSED: signed mode is configured
+ *     but the secret is missing, so NO cart may be built. The caller must render
+ *     no buy form (never a tamperable / broken one).
+ */
+export interface CartSigningResolution {
+  enabled: boolean;
+  secret?: string;
+}
+
+/**
+ * Resolve cart signing for a request, failing CLOSED for production signed
+ * checkout. Signed mode is the real-merchant configuration, so its
+ * cart-validation secret is REQUIRED: without it we refuse to emit any buy form
+ * (a signed form we can't sign would be tamperable; an unsigned one against a
+ * validation-ON store would be broken). Missing-secret in signed mode is a
+ * deployment misconfiguration, so we log it loudly (`console.error`) in every
+ * environment — it should never happen on a live store and must be caught fast.
+ * `unsigned-demo` needs no secret and is always enabled.
+ */
+export async function resolveCartSigning(
+  commerce: ResolvedManagedCheckout,
+): Promise<CartSigningResolution> {
+  if (commerce.mode !== "signed") return { enabled: true };
+  const secret = await readCartSecret(commerce);
+  if (secret) return { enabled: true, secret };
+  console.error(
+    "[storefront] signed checkout is configured but FOXY_CART_SECRET is missing — " +
+      "buy forms disabled (fail-closed). Set the cart-validation secret for this environment.",
+  );
+  return { enabled: false };
 }

package/apps/storefront/src/lib/chrome/model.ts

@@ -220,6 +220,17 @@ export interface TenantChrome {
    * cutover of a SHIPPED tenant stays a deliberate, gated step.
    */
   sharedChrome?: boolean;
+  /**
+   * OPT-IN: also link the shared commerce-MARKETING stylesheet
+   * (/shared/commerce-marketing.css, unit F5) into this tenant's wrapper — the
+   * raw-page BODY layer (page-hero / prose / callouts / value & tier cards /
+   * contact form / FAQ / CTA band) its content fragments repeat. Linked AFTER the
+   * chrome sheet so its page-level variants win. Absent/false ⇒ not linked, so a
+   * SHIPPED tenant that still carries its own page-local <style> never
+   * double-loads or silently flips until its integration unit strips that CSS and
+   * adopts (same gated-cutover discipline as `sharedChrome`).
+   */
+  sharedMarketingCss?: boolean;
   /** <html lang> (defaults to "en"). */
   lang?: string;
   head?: ChromeHead;

package/apps/storefront/src/lib/compliance/enforcement.ts

@@ -0,0 +1,95 @@
+/**
+ * Compliance enforcement ADAPTER — the request-scoped bridge between a resolved
+ * tenant and the pure `@tot/public-runtime` enforcement engine. It:
+ *   - decides whether a tenant is REGULATED (age/nicotine),
+ *   - resolves its data-driven ruleset (fail-closed: regulated + no ruleset ⇒ null),
+ *   - wires the LIVE verification provider from operational env
+ *     (`TOT_VERIFICATION_PROVIDER`) — absent ⇒ the verification gate fails closed,
+ *   - and produces the enforcement→evidence signals the promote gate consumes.
+ *
+ * The verification provider being external config is deliberate: this repo owns
+ * the GATE and its safe default (BLOCK), not the provider integration. Setting
+ * `TOT_VERIFICATION_PROVIDER=tot` (once the live ToT verification flow is wired)
+ * is what flips a regulated tenant from "blocked/not-promotable" to enforceable.
+ */
+import type {
+  TenantConfig,
+  ComplianceRuleset,
+  EnforcementEvidenceSignals,
+} from "@tot/public-runtime";
+import { enforcementSignals } from "@tot/public-runtime";
+import { readEnv } from "@/lib/env";
+import { COMPLIANCE_RULESETS } from "@/config/compliance/rulesets";
+
+/** True when the tenant sells age/nicotine-restricted goods (drives fail-closed). */
+export function isRegulatedTenant(
+  tenant: Pick<TenantConfig, "compliance">,
+): boolean {
+  const c = tenant.compliance;
+  return !!c && ((c.minAge != null && c.minAge > 0) || !!c.nicotineWarning);
+}
+
+/**
+ * Provider values that denote a NON-LIVE, test/sandbox verification profile. This
+ * is the mode the 8501 demo/preview runs in: there is no live identity provider,
+ * so the storefront's front-door 21+ affirmation is allowed to SIMULATE a passed
+ * age/identity verification — and ONLY then — so the regulated checkout can be
+ * exercised end-to-end for the demo without a real provider or any secret.
+ *
+ * This does NOT weaken the F12 invariant that a soft affirmation is never real
+ * verification: the simulation is gated on an EXPLICIT sandbox provider value set
+ * per-environment (test-tier only). Production leaves `TOT_VERIFICATION_PROVIDER`
+ * UNSET (→ fail-closed) or points it at the live provider (whose own outcome is
+ * then required); in neither case does affirmation substitute for verification.
+ */
+export const SANDBOX_VERIFICATION_PROVIDERS: ReadonlySet<string> = new Set([
+  "sandbox",
+  "test",
+  "demo",
+]);
+
+/** True when the resolved verification provider is an explicit sandbox/test profile. */
+export function isSandboxVerificationProvider(
+  provider: string | undefined | null,
+): boolean {
+  return !!provider && SANDBOX_VERIFICATION_PROVIDERS.has(provider.toLowerCase());
+}
+
+/**
+ * The PACT reporting CAPTURE sink status. The record BUILDER
+ * (`buildPactReportRecord`) ships in this unit and the capture point is wired at
+ * order intake; the durable per-state export/FILING is a documented follow-up. We
+ * report the capture path as wired so the promote gate doesn't hard-block on the
+ * filing (merchant/counsel-owned) while still requiring the per-order data model.
+ */
+const PACT_REPORTING_CAPTURE_WIRED = true;
+
+/**
+ * Resolve a tenant's compliance ruleset, or `null` when it can't be resolved for a
+ * regulated tenant (the caller must then fail closed). Wires the live verification
+ * provider from env. An unregulated tenant returns `null` too — callers key on
+ * {@link isRegulatedTenant} to distinguish "no ruleset needed" from "fail closed".
+ */
+export async function resolveTenantRuleset(
+  tenant: Pick<TenantConfig, "tenant_id" | "compliance">,
+): Promise<ComplianceRuleset | null> {
+  const base = COMPLIANCE_RULESETS[tenant.tenant_id];
+  if (!base) return null;
+  const provider = (await readEnv("TOT_VERIFICATION_PROVIDER")) || undefined;
+  return {
+    ...base,
+    verification: { ...base.verification, provider },
+  };
+}
+
+/** Build the enforcement→evidence signals for a tenant (for the promote gate). */
+export async function resolveEnforcementEvidenceSignals(
+  tenant: Pick<TenantConfig, "tenant_id" | "compliance">,
+): Promise<EnforcementEvidenceSignals> {
+  const regulated = isRegulatedTenant(tenant);
+  const ruleset = await resolveTenantRuleset(tenant);
+  return enforcementSignals(ruleset, {
+    regulated,
+    reportingCaptureWired: PACT_REPORTING_CAPTURE_WIRED,
+  });
+}

package/apps/storefront/src/lib/content/callout.ts

@@ -0,0 +1,78 @@
+/**
+ * Callout contract (spec §F4). A tone-styled aside — the structured, data-driven
+ * form of the repeated `.disclaimer` / `.warn-band` page patterns that the f05
+ * shared sheet (public/shared/commerce-marketing.css) defines for the raw-HTML
+ * path. A tenant supplies a {@link CalloutModel}; <Callout> paints it from f06
+ * tokens with the a11y semantics baked in (see {@link calloutPresentation}), so
+ * no tenant hand-authors the callout markup + its role/aria.
+ *
+ * Tones map to the same token vocabulary the f05 sheet uses:
+ *   info    → `--color-info`    (the sheet's `.disclaimer`, e.g. an FYI)
+ *   warning → `--color-warning` (the sheet's `.warn-band`, a caution)
+ *   legal   → `--color-warning` (compliance/legal caution; distinct label)
+ *   success → `--color-success` (a positive confirmation)
+ * Node-free + presentation-free so the contract tests and the .astro widget
+ * share ONE definition.
+ */
+import type { RichText } from "./richtext.js";
+
+export type CalloutTone = "info" | "warning" | "legal" | "success";
+
+export interface CalloutModel {
+  tone: CalloutTone;
+  /** Optional bold lead line above the body. */
+  title?: string;
+  /** The callout copy (inline links/emphasis allowed; never HTML). */
+  body: RichText;
+}
+
+/**
+ * The a11y + styling recipe for a tone. Kept here (not in the component) so the
+ * semantics are one testable mapping: `role` and `label` drive the assistive
+ * announcement, `tokenVar` is the accent/tint token, `iconPath` is the SVG path.
+ * `role` stays "note" for all tones — these are STATIC page asides, not live
+ * regions, so "alert" would be wrong (it would interrupt a screen reader).
+ */
+export interface CalloutPresentation {
+  role: "note";
+  /** aria-label for the callout region (announces its nature). */
+  label: string;
+  /** The contract token this tone tints from (accent + border + icon). */
+  tokenVar: `--color-${string}`;
+  /** SVG path `d` for the tone's leading icon (info "i" / caution "!" / check). */
+  iconPath: string;
+}
+
+// Simple, self-contained 24-grid icon paths (stroke, currentColor via token).
+const ICON_INFO =
+  "M12 16v-5M12 8h.01M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z";
+const ICON_CAUTION =
+  "M12 9v4m0 4h.01M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0Z";
+const ICON_CHECK = "M20 6 9 17l-5-5";
+
+const PRESENTATION: Record<CalloutTone, CalloutPresentation> = {
+  info: { role: "note", label: "Note", tokenVar: "--color-info", iconPath: ICON_INFO },
+  warning: {
+    role: "note",
+    label: "Important",
+    tokenVar: "--color-warning",
+    iconPath: ICON_CAUTION,
+  },
+  legal: {
+    role: "note",
+    label: "Legal notice",
+    tokenVar: "--color-warning",
+    iconPath: ICON_CAUTION,
+  },
+  success: {
+    role: "note",
+    label: "Confirmed",
+    tokenVar: "--color-success",
+    iconPath: ICON_CHECK,
+  },
+};
+
+/** The a11y + tone recipe for a callout tone. */
+export function calloutPresentation(tone: CalloutTone): CalloutPresentation {
+  return PRESENTATION[tone] ?? PRESENTATION.info;
+}