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

package/packages/public-runtime/src/compliance/ruleset.ts

@@ -0,0 +1,117 @@
+/**
+ * Compliance RULESET — the data-driven jurisdiction/federal rule model the
+ * enforcement engine evaluates against. This is deliberately DATA, not code
+ * branches: a tenant's regulated obligations (state flavor/no-ship bans, per-order
+ * limits, PACT Act, verification, excise) are expressed as a serializable record
+ * so the rules can be reviewed, versioned, and updated without touching the
+ * evaluator. The concrete per-tenant data literals live in the app
+ * (`apps/storefront/src/config/compliance/rulesets.ts`); this module owns the
+ * SHAPE + resolution helpers.
+ *
+ * IMPORTANT — legal posture: this framework CAPTURES and ENFORCES the configured
+ * rules and captures the data required for filings. It does not constitute legal
+ * advice; the rule DATA and any regulatory FILING (e.g. PACT Act monthly reports)
+ * are the merchant's / their counsel's responsibility. Every ruleset carries a
+ * `source`/`updatedAt` provenance stamp to make that boundary explicit.
+ *
+ * Pure + edge-safe (no node, no I/O).
+ */
+
+/** A single jurisdiction's data-driven rule. `region` is a 2-letter code (uppercased). */
+export interface StateComplianceRule {
+  region: string;
+  /** No regulated (ENDS/vapor) shipments to this region at all (state no-ship). */
+  banAll?: boolean;
+  /** Flavored-ENDS ban — tobacco/menthol still allowed, characterizing flavors not. */
+  banFlavored?: boolean;
+  /** Per-order regulated-unit cap for this region (overrides the ruleset default). */
+  perOrderUnitLimit?: number;
+  /** Adult signature on delivery required for this region (else the PACT baseline). */
+  adultSignatureRequired?: boolean;
+  /** Short citation/note surfaced in the block message. */
+  note?: string;
+}
+
+/**
+ * Age/identity verification requirement. `provider` is the LIVE-provider contract:
+ * it is populated only when a verification provider is actually configured
+ * (external/operational config). A required verification with NO provider FAILS
+ * CLOSED (the enforcement gate blocks) — a notice that cannot verify is not
+ * compliance.
+ */
+export interface VerificationRequirement {
+  /** Verification must pass before checkout can complete. */
+  required: boolean;
+  /** Minimum age enforced (e.g. 21 for nicotine). */
+  minAge: number;
+  /**
+   * Live provider id once wired (e.g. "tot"). Absent ⇒ no provider configured;
+   * `resolveVerificationDecision` then blocks (safe default). Set by
+   * `resolveTenantRuleset` from operational config, never hardcoded in the data.
+   */
+  provider?: string;
+}
+
+/**
+ * Excise-tax obligation + how it is satisfied. Enforcement is fail-closed: an
+ * obligation with `handling: "unavailable"` BLOCKS checkout rather than silently
+ * shipping untaxed.
+ */
+export interface ExciseRequirement {
+  required: boolean;
+  /**
+   * - "managed-cart" — materialized in the managed cart via the pre-cart webhook +
+   *   `tot_excise_tax` coupon (Track B).
+   * - "provider" — external excise calc/handoff (contract in `note`).
+   * - "unavailable" — no excise path wired; enforcement fails closed.
+   */
+  handling: "managed-cart" | "provider" | "unavailable";
+  /** External excise-provider handoff contract note. */
+  note?: string;
+}
+
+/** PACT Act (ENDS shipments) rule. */
+export interface PactActRule {
+  enabled: boolean;
+  /** Adult signature (21+) on delivery — PACT baseline for ENDS. */
+  adultSignatureRequired: boolean;
+  /** Carriers that must NOT carry ENDS (PACT: USPS won't). Documents the carrier contract. */
+  prohibitedCarriers: string[];
+  /** Per-order data must be captured for the PACT Act monthly state report. */
+  reportingRequired: boolean;
+}
+
+export interface ComplianceRuleset {
+  tenantId: string;
+  minAge: number;
+  verification: VerificationRequirement;
+  excise: ExciseRequirement;
+  pactAct: PactActRule;
+  /** Fallback per-order regulated-unit cap when no state rule sets one. */
+  defaultPerOrderUnitLimit?: number;
+  /** The substance of jurisdiction enforcement — data-driven, not a static list in code. */
+  states: StateComplianceRule[];
+  /** ISO date the rule DATA was last reviewed (provenance). */
+  updatedAt: string;
+  /** Provenance / disclaimer note (who owns the data + filing responsibility). */
+  source: string;
+}
+
+/** Find the rule for a region (case-insensitive), or `undefined`. */
+export function stateRuleFor(
+  ruleset: Pick<ComplianceRuleset, "states">,
+  region: string | undefined | null,
+): StateComplianceRule | undefined {
+  if (!region) return undefined;
+  const key = region.trim().toUpperCase();
+  return ruleset.states.find((s) => s.region.toUpperCase() === key);
+}
+
+/** The effective per-order unit limit for a region (state rule wins over the default). */
+export function effectivePerOrderLimit(
+  ruleset: Pick<ComplianceRuleset, "states" | "defaultPerOrderUnitLimit">,
+  region: string | undefined | null,
+): number | undefined {
+  const stateLimit = stateRuleFor(ruleset, region)?.perOrderUnitLimit;
+  return stateLimit ?? ruleset.defaultPerOrderUnitLimit;
+}

package/packages/public-runtime/src/compliance/verification.ts

@@ -0,0 +1,81 @@
+/**
+ * Age/identity VERIFICATION gate — the enforcement decision on the verification
+ * axis. The soft 21+ affirmation (the front-door `AgeGate` island) is UX only and
+ * is NEVER accepted here as verification; this gate resolves the REAL requirement.
+ *
+ * The live provider is external/operational config (see
+ * `VerificationRequirement.provider`). This module's contract:
+ *   - not required            → pass ("not_required")
+ *   - required, no provider   → BLOCK, fail-closed (safe default)
+ *   - required, unknown/pending state → "required" (do the step; not yet cleared)
+ *   - required, failed        → BLOCK
+ *   - required, verified but under minAge → BLOCK
+ *   - required, verified ≥ minAge → pass ("satisfied")
+ *
+ * Pure + edge-safe.
+ */
+import type { VerificationRequirement } from "./ruleset.js";
+
+export type VerificationOutcome = "verified" | "failed" | "pending" | "unknown";
+
+/** The provider-reported (or absent) verification result for this shopper/session. */
+export interface VerificationState {
+  outcome: VerificationOutcome;
+  /** Verified age when the provider returns one. */
+  verifiedAge?: number;
+  /** Opaque provider evidence reference (feeds the evidence timeline). */
+  evidenceRef?: string;
+}
+
+export interface VerificationDecision {
+  status: "satisfied" | "required" | "blocked" | "not_required";
+  reason?: string;
+  /**
+   * True when the block is a fail-closed SAFETY default (no provider configured),
+   * not a real verification failure — surfaced distinctly so operators can see
+   * "verification isn't wired" vs "the shopper failed verification".
+   */
+  failedClosed: boolean;
+}
+
+export function resolveVerificationDecision(
+  requirement: VerificationRequirement,
+  state: VerificationState | null | undefined,
+): VerificationDecision {
+  if (!requirement.required) {
+    return { status: "not_required", failedClosed: false };
+  }
+  // Required but no live provider configured → FAIL CLOSED. Never silently allow.
+  if (!requirement.provider) {
+    return {
+      status: "blocked",
+      failedClosed: true,
+      reason:
+        "Age/identity verification is required but no verification provider is configured. " +
+        "Checkout is blocked until a provider is wired (safe default = BLOCK).",
+    };
+  }
+  if (!state || state.outcome === "unknown" || state.outcome === "pending") {
+    return {
+      status: "required",
+      failedClosed: false,
+      reason: "Age/identity verification must be completed before checkout.",
+    };
+  }
+  if (state.outcome === "failed") {
+    return {
+      status: "blocked",
+      failedClosed: false,
+      reason: "Age/identity verification did not pass.",
+    };
+  }
+  // verified
+  if (state.verifiedAge != null && state.verifiedAge < requirement.minAge) {
+    return {
+      status: "blocked",
+      failedClosed: false,
+      reason: `Verified age ${state.verifiedAge} is below the required minimum of ${requirement.minAge}.`,
+    };
+  }
+  return { status: "satisfied", failedClosed: false };
+}

package/packages/public-runtime/src/csp.ts

@@ -46,7 +46,11 @@ export function buildCsp(opts: CspOptions): string {
     // JS, so this is the one tolerated relaxation. style-src-elem still inherits
     // the strict 'self'+nonce from style-src; script-src stays fully strict.
     "style-src-attr": ["'unsafe-inline'"],
-    "font-src": ["'self'", ...(opts.fontSrc ?? [])],
+    // 'self' covers same-origin @fontsource files; `data:` covers the small ones
+    // Vite inlines as base64 `data:font/…` URIs at build time (assets under
+    // assetsInlineLimit get baked into the bundled CSS). Fonts can't execute JS,
+    // so allowing `data:` here is the same tolerated relaxation as img-src.
+    "font-src": ["'self'", "data:", ...(opts.fontSrc ?? [])],
     "img-src": ["'self'", "data:", ...(opts.imgSrc ?? [])],
     "connect-src": ["'self'", ...(opts.connectSrc ?? [])],
     "frame-src": ["'self'", ...(opts.frameSrc ?? [])],
@@ -70,8 +74,12 @@ export const CSP_REPORT_GROUP = "csp-endpoint";
  */
 export const STOREFRONT_CSP_ALLOWLIST = {
   scriptSrc: ["https://static.cloudflareinsights.com"],
-  styleSrc: ["https://fonts.googleapis.com"],
-  fontSrc: ["https://fonts.gstatic.com"],
+  // Web fonts are self-hosted (@fontsource, bundled same-origin) — no
+  // fonts.googleapis.com stylesheet or fonts.gstatic.com woff2 to allowlist;
+  // 'self' + `data:` (both added by buildCsp) cover style-src + font-src,
+  // including the small fonts Vite inlines as `data:font/…` base64 at build time.
+  styleSrc: [],
+  fontSrc: [],
   // Product imagery is rehosted to R2 or served from remote CDNs.
   imgSrc: ["https:"],
   connectSrc: ["https://cloudflareinsights.com"],
@@ -107,3 +115,19 @@ export function checkoutCspAdditions(storeOrigin: string): {
     imgSrc: [cdn, storeOrigin],
   };
 }
+
+/**
+ * CSP `frame-src` additions for the private-app widgets actually rendered on
+ * THIS page (PrivateApps epic, D5). Exact per-install origins, NEVER a
+ * wildcard — the sandbox (`allow-scripts`, no `allow-same-origin`) already
+ * isolates a widget from the page, but a broad `frame-src` would still let
+ * an unrelated origin be framed under cover of "it's a widget"; deriving the
+ * allowlist from the SAME resolved placements that rendered means an origin
+ * only ever appears here because a live, eligible install's iframe is
+ * actually on the page.
+ */
+export function appWidgetCspAdditions(
+  placements: readonly { endpoint: string }[],
+): { frameSrc: string[] } {
+  return { frameSrc: [...new Set(placements.map((p) => new URL(p.endpoint).origin))] };
+}

package/packages/public-runtime/src/customization-reconcile.ts

@@ -36,6 +36,29 @@ export interface PreviewStateEvidenceCheck {
   required?: boolean;
 }
 
+/**
+ * One validation finding surfaced to the admin panel (mirrors
+ * @tot/private-controlplane's `ReconcileFinding` — kept structural here so this
+ * read-only type stays dependency-free). `disposition` is one of
+ * `"blocking-safety" | "advisory-skip" | "advisory"`; `skipped` = the offending
+ * artifact was NOT materialized (a skip, or an un-overridden safety block).
+ */
+export interface PreviewStateFinding {
+  code: string;
+  path: string;
+  message: string;
+  disposition: string;
+  skipped: boolean;
+}
+
+/** Auditable authorization that materialized a preview past a blocking-safety
+ * finding — the WHO/WHY the admin panel shows (mirrors `SafetyOverride`). */
+export interface PreviewStateOverride {
+  by: string;
+  reason: string;
+  at: string;
+}
+
 /** Fail-safe preview state — target/actual can diverge when target is broken. */
 export interface PreviewState {
   tenantId: string;
@@ -46,6 +69,18 @@ export interface PreviewState {
   /** Why target != actual, when the target failed to render. Null on success. */
   lastError: string | null;
   lastReconcileAt: string | null;
+  /**
+   * Validation findings from the last reconcile — the advisory findings on a
+   * materialized preview, or the blocking-safety findings that stopped one —
+   * surfaced on the shareable dashboard / admin panel for the live/preview site.
+   * Absent/empty ⇒ the tenant's files validated clean. Written by `reconcilePreview`.
+   */
+  findings?: PreviewStateFinding[];
+  /**
+   * The auditable safety-block override applied to this reconcile (who/why), when a
+   * blocking-safety finding was materialized past. Absent/null ⇒ no override.
+   */
+  overriddenBy?: PreviewStateOverride | null;
   /**
    * The compliance verdict for the last successful reconcile (ADR 0010's evidence,
    * mirrored here so the PUBLIC, unauthenticated /preview/dashboard page can show

package/packages/public-runtime/src/customization-runtime.ts

@@ -38,6 +38,14 @@ export function siteVersionKey(tenantId: string, versionId: string): string {
 export function siteVersionIndexKey(tenantId: string): string {
   return `cust:versions:${tenantId}`;
 }
+/**
+ * KV key for a tenant's LIVE-PROMOTION history (versions actually flipped onto
+ * the `live` channel, in promotion order). Distinct from the raw publish history
+ * at `siteVersionIndexKey` — see `PromotionEvent`.
+ */
+export function promotionHistoryKey(tenantId: string): string {
+  return `cust:promotions:${tenantId}`;
+}
 
 /**
  * Canonical artifact path for a tenant's theme override.

package/packages/public-runtime/src/customization-versioning.ts

@@ -93,3 +93,20 @@ export interface SiteVersionSummary {
   createdAt: string;
   artifactCount: number;
 }
+
+/**
+ * One entry in a tenant's LIVE-PROMOTION history: a version that was actually
+ * flipped onto the `live` channel (via `setChannelPointer(..., "live", ...)` —
+ * the go-live promote or the initial live seed), in promotion order.
+ *
+ * Deliberately distinct from `SiteVersionSummary` (the raw publish history):
+ * that also contains candidate versions reconciled/published but NEVER promoted,
+ * so "the version before the current live" must be resolved from THIS list, not
+ * the publish history. A plain rollback (repointing `live` at a prior version)
+ * is NOT a promotion and is not recorded here.
+ */
+export interface PromotionEvent {
+  versionId: string;
+  /** ISO timestamp of the promotion. */
+  at: string;
+}

package/packages/public-runtime/src/extension-contract.ts

@@ -6,10 +6,11 @@
  * used by docs, validators, CLI checks, and the storefront app itself.
  */
 
-export const BLOCK_PALETTE_CURRENT_CONTRACT = "block-palette@3" as const;
+export const BLOCK_PALETTE_CURRENT_CONTRACT = "block-palette@4" as const;
 export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = [
   "block-palette@1",
   "block-palette@2",
+  "block-palette@3",
   BLOCK_PALETTE_CURRENT_CONTRACT,
 ] as const;
 

package/packages/public-runtime/src/hash.ts

@@ -0,0 +1,25 @@
+/**
+ * `sha256Hex` — a dependency-free, runtime-portable (Web Crypto, no `node:*`)
+ * sha256-hex primitive shared by the write side
+ * (`@tot/private-controlplane`'s `customization-versioning.ts`, content-
+ * addressed publish) and the renderer (`apps/storefront/src/lib/apps/
+ * credentials.ts`, client-secret hashing for the App Gateway).
+ *
+ * Lives HERE rather than in `@tot/private-controlplane` because it carries no
+ * control-plane business logic — it's a bare crypto primitive — and the
+ * renderer's `lib/apps/` is machine-fenced (depcruise
+ * `renderer-no-controlplane-pkg`) from ever importing that private package.
+ * `@tot/private-controlplane` still calls this exact function (no behavior
+ * change); PrivateApps epic D2 Chunk B just needed a copy the renderer is
+ * allowed to import.
+ */
+
+/** sha256 of content as lowercase hex, via Web Crypto (Workers + Node 20+). */
+export async function sha256Hex(content: string | Uint8Array): Promise<string> {
+  const bytes =
+    typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const digest = await crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/packages/public-runtime/src/index.ts

@@ -16,6 +16,7 @@
 export * from "./product.js";
 export * from "./tenant.js";
 export * from "./checkout.js";
+export * from "./membership.js";
 export * from "./checkout-orders.js";
 export * from "./capabilities.js";
 export * from "./checkout-style.js";
@@ -29,8 +30,13 @@ export * from "./customization-runtime.js";
 export * from "./customization-versioning.js";
 export * from "./customization-scripts.js";
 export * from "./customization-reconcile.js";
+export * from "./candidate-index.js";
 export * from "./extension-contract.js";
 export * from "./raw-html-policy.js";
+export * from "./review-trust-proof.js";
+export * from "./compliance/index.js";
 export * from "./tenant-assets.js";
 export * from "./binary-path.js";
 export * from "./hot-standby-readiness.js";
+export * from "./hash.js";
+export * from "./widget-postmessage.js";