@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/provider-checkout-extension.ts

@@ -0,0 +1,425 @@
+/**
+ * Certified provider-checkout-extension contract.
+ *
+ * The managed checkout is PROVIDER-HOSTED (Foxy): the payment form, card fields,
+ * and the money-bearing hosted checkout page live on the provider's origin, never
+ * on the storefront. The storefront's only reach into checkout is a small set of
+ * BRANDING/PRESENTATION seams — a themed in-page cart drawer and CSS/asset tokens
+ * pushed to the hosted checkout template. This module declares the CLOSED set of
+ * those seams and the fail-closed validator a CERTIFIED extension is bound by.
+ *
+ * It is a SPECIALIZATION of the integration capability model
+ * (`../integration-capabilities.ts`), not a competing one:
+ *   - The surface is PINNED to `checkout-payment` — the strictly-most-protected
+ *     sub-surface (sandbox-only, elevated-parent prohibited). A caller cannot pick
+ *     another surface; there is no surface field on the request.
+ *   - Attachment is the closed {@link CHECKOUT_EXTENSION_SEAMS} registry. Every
+ *     seam is a presentation seam (style tokens, scoped CSS, an asset ref, a
+ *     curated template region, a non-payment custom field). NONE reads or writes
+ *     card data, the signed cart, checkout totals, or the payment DOM — those live
+ *     only in `FORBIDDEN_CAPABILITIES` and are structurally absent here.
+ *   - Any registry capability a checkout extension additionally requests must be in
+ *     the tight, read-mostly {@link CHECKOUT_ELIGIBLE_CAPABILITIES} allowlist; the
+ *     request is then delegated to `validateIntegrationCapabilities`, so the
+ *     tenant-tier matrix, forbidden set, binding, and origin grammar are the ONE
+ *     source of truth. Two gates (checkout-eligibility + the capability model) both
+ *     have to pass.
+ *   - Certification is server-resolved and defaults OFF: an uncertified request is
+ *     denied. "Certified" here is the checkout-extension vetting gate — distinct
+ *     from the capability model's `certifiedImmutable` (which governs regulated
+ *     elevated-parent code, a tier that is prohibited on this surface anyway).
+ *
+ * Compliance obligations (policy-04, `../compliance-obligations.ts`) are unchanged
+ * by anything here: they are server-derived from tenant config and no seam is an
+ * input to their resolution. The platform-owned `checkout-controls` / `cart-preflight`
+ * anchors are `PROTECTED_SURFACES` there; this contract exposes no seam that reaches
+ * them.
+ *
+ * Provenance discipline: each seam is tagged `repo-confirmed` (backed by the
+ * storefront's existing Foxy integration) or `foxy-doc-assumption` (plausible from
+ * Foxy's model but NOT evidenced in this repo — needs external Foxy-doc verification
+ * before it is treated as delivered). Assumptions are in the contract as declared,
+ * validator-gated placeholders, not as confirmed capabilities.
+ *
+ * Pure and edge-safe (no node, no I/O): validators, CLI, docs, and admin review all
+ * read this one source of truth.
+ */
+import {
+  FORBIDDEN_CAPABILITIES,
+  isGrantableCapability,
+  validateIntegrationCapabilities,
+  type CapabilityDenial,
+  type CodeForm,
+  type ConsentPurpose,
+  type Enforcement,
+  type GrantedCapability,
+  type IntegrationBinding,
+  type Surface,
+  type TenantTier,
+} from "../integration-capabilities.js";
+import type { ExecutionTier } from "./phases.js";
+
+/** Contract token — bump the minor for additive seams, the major for a break (ADR 0006 semver). */
+export const PROVIDER_CHECKOUT_EXTENSION_CONTRACT = "provider-checkout-extension@1" as const;
+export type ProviderCheckoutExtensionContract = typeof PROVIDER_CHECKOUT_EXTENSION_CONTRACT;
+
+/**
+ * The surface is PINNED. Every certified checkout extension resolves against the
+ * strictly-most-protected `checkout-payment` cell — sandbox-only, elevated-parent
+ * prohibited (see the D-R2 matrix). It is not caller-selectable.
+ */
+export const CHECKOUT_EXTENSION_SURFACE: Surface = "checkout-payment";
+
+// ── Seam vocabulary ──────────────────────────────────────────────────────────
+
+/** Where a seam attaches. Both are presentation-only surfaces the storefront controls. */
+export const CHECKOUT_SEAM_LOCATIONS = ["in-page-cart-drawer", "hosted-checkout-page"] as const;
+export type CheckoutSeamLocation = (typeof CHECKOUT_SEAM_LOCATIONS)[number];
+
+/**
+ * How a seam contributes. Every kind is presentation/data-collection that stays on
+ * the storefront's side of the PCI boundary — none is executable parent code on the
+ * payment DOM (that is the elevated-parent tier, prohibited on this surface).
+ */
+export const CHECKOUT_ATTACHMENT_KINDS = [
+  "style-tokens", // CSS custom properties (`--tot-*`) the drawer/template references.
+  "scoped-css", // Bespoke CSS, scoped to the storefront's own drawer root.
+  "raw-css", // ASCII-safe raw CSS appended to the hosted checkout content.
+  "asset-ref", // An absolute-https asset URL (e.g. a logo) referenced by the template.
+  "template-content", // Curated content injected into a NAMED hosted-checkout region.
+  "custom-field", // A non-payment field collected at checkout, posted only to our server.
+] as const;
+export type CheckoutAttachmentKind = (typeof CHECKOUT_ATTACHMENT_KINDS)[number];
+
+/**
+ * Whether a seam is grounded in this repo's existing Foxy integration
+ * (`repo-confirmed`) or is a plausible Foxy mechanism NOT yet evidenced here
+ * (`foxy-doc-assumption`) and gated behind external Foxy-doc verification.
+ */
+export const SEAM_EVIDENCE = ["repo-confirmed", "foxy-doc-assumption"] as const;
+export type SeamEvidence = (typeof SEAM_EVIDENCE)[number];
+
+export interface CheckoutSeamDef {
+  /** Stable, wire-serialized seam id. */
+  id: string;
+  /** Operator-facing label. */
+  label: string;
+  location: CheckoutSeamLocation;
+  attachment: CheckoutAttachmentKind;
+  evidence: SeamEvidence;
+  /**
+   * For `repo-confirmed`: the code path that proves the seam exists.
+   * For `foxy-doc-assumption`: the exact external verification still owed.
+   */
+  provenance: string;
+  /** Consent purpose the seam's runtime effect depends on, when any (broker-enforced). */
+  requiresConsent?: ConsentPurpose;
+}
+
+function seam(def: CheckoutSeamDef): CheckoutSeamDef {
+  return def;
+}
+
+/**
+ * The CLOSED set of checkout UI seams a certified extension may attach to. Anything
+ * not here is unknown and fails closed. Every entry is presentation-only and, by
+ * construction, card-data-free: there is deliberately NO seam for the payment form,
+ * the card fields, the signed cart, or checkout totals.
+ */
+export const CHECKOUT_EXTENSION_SEAMS: Readonly<Record<string, CheckoutSeamDef>> = Object.freeze(
+  Object.fromEntries(
+    [
+      // ── repo-confirmed: backed by the existing Foxy integration ──────────────
+      seam({
+        id: "cart-drawer.style-tokens",
+        label: "Theme the in-page cart drawer via CSS custom properties",
+        location: "in-page-cart-drawer",
+        attachment: "style-tokens",
+        evidence: "repo-confirmed",
+        provenance:
+          "checkout.ts — the Foxy loader renders the cart into the storefront's own light DOM (root `#fc`), so it inherits the theme's CSS custom properties; `<CartDrawerStyles>` emits the brand baseline.",
+      }),
+      seam({
+        id: "cart-drawer.scoped-css",
+        label: "Bespoke CSS overrides for the in-page cart drawer",
+        location: "in-page-cart-drawer",
+        attachment: "scoped-css",
+        evidence: "repo-confirmed",
+        provenance:
+          "checkout.ts `ManagedCheckoutConfig.cartDrawerCss` — per-tenant CSS appended after the brand baseline; rules scope under `#fc`.",
+      }),
+      seam({
+        id: "hosted-checkout.style-tokens",
+        label: "Theme the hosted checkout page via CSS custom-property tokens",
+        location: "hosted-checkout-page",
+        attachment: "style-tokens",
+        evidence: "repo-confirmed",
+        provenance:
+          "checkout-style.ts `checkoutStyleToCss` — emits `--tot-checkout-*` tokens served at the storefront URL Foxy pulls as its theme `content_url` (`/theme/foxy`).",
+      }),
+      seam({
+        id: "hosted-checkout.raw-css",
+        label: "ASCII-safe raw-CSS override appended to the hosted checkout content",
+        location: "hosted-checkout-page",
+        attachment: "raw-css",
+        evidence: "repo-confirmed",
+        provenance:
+          "checkout-style.ts `buildCheckoutStyleCss` / `checkout.css` artifact — appended only when `isAsciiSafe` (the checkout cache pass is not Unicode-safe).",
+      }),
+      seam({
+        id: "hosted-checkout.logo",
+        label: "Brand logo shown on the hosted checkout header",
+        location: "hosted-checkout-page",
+        attachment: "asset-ref",
+        evidence: "repo-confirmed",
+        provenance:
+          "checkout-style.ts `CheckoutStyle.logoUrl` → `--tot-checkout-logo` — accepted only as an absolute https URL.",
+      }),
+
+      // ── foxy-doc-assumption: NOT evidenced in this repo; gated on verification ─
+      seam({
+        id: "hosted-checkout.template-region",
+        label: "Curated content injected into a named hosted-checkout template region",
+        location: "hosted-checkout-page",
+        attachment: "template-content",
+        evidence: "foxy-doc-assumption",
+        provenance:
+          "ASSUMPTION — Foxy's checkout template is customizable, but the named content regions, whether arbitrary HTML is permitted under our ASCII/CSP discipline, and how tokens are substituted are NOT evidenced in this repo. Verify against Foxy's checkout-template docs before treating as delivered.",
+      }),
+      seam({
+        id: "hosted-checkout.custom-field",
+        label: "A non-payment custom field collected at checkout",
+        location: "hosted-checkout-page",
+        attachment: "custom-field",
+        evidence: "foxy-doc-assumption",
+        provenance:
+          "ASSUMPTION — Foxy supports custom checkout fields, but this repo has no such integration. Verify the field never sits in the card-data/PCI path and posts back only to our own order webhook (not a third party) before treating as delivered.",
+      }),
+    ].map((s) => [s.id, s]),
+  ),
+);
+
+const SEAM_IDS: ReadonlySet<string> = new Set(Object.keys(CHECKOUT_EXTENSION_SEAMS));
+
+/** True when an id is in the closed checkout-seam registry. */
+export function isCheckoutExtensionSeam(id: string): boolean {
+  return SEAM_IDS.has(id);
+}
+
+/** All checkout-seam ids, in declaration order. */
+export function checkoutExtensionSeamIds(): string[] {
+  return Object.keys(CHECKOUT_EXTENSION_SEAMS);
+}
+
+/** Seam ids whose delivery is still gated on external Foxy-doc verification. */
+export function assumptionSeamIds(): string[] {
+  return checkoutExtensionSeamIds().filter(
+    (id) => CHECKOUT_EXTENSION_SEAMS[id]!.evidence === "foxy-doc-assumption",
+  );
+}
+
+// ── Checkout-eligible capability allowlist ───────────────────────────────────
+
+/**
+ * The ONLY registry capabilities a certified checkout extension may additionally
+ * request on the `checkout-payment` surface. Deliberately tight and read-mostly:
+ * anonymous reads, consent-gated checkout analytics, and the app's own public
+ * config. A capability outside this allowlist is denied `capability-not-checkout-
+ * eligible` even if the general capability model would otherwise grant it — so a
+ * future registry addition can never become silently checkout-reachable.
+ *
+ * Excluded on purpose: `broker:cart.add-line` (mutation on the payment surface),
+ * `broker:navigate`, any `lifecycle:*` (checkout is provider-hosted — no phase
+ * attach on the hosted page), and every `assurance:*` / `consent:*` declaration.
+ */
+export const CHECKOUT_ELIGIBLE_CAPABILITIES: readonly string[] = Object.freeze([
+  "broker:cart.read",
+  "broker:consent.read",
+  "broker:page-context.read",
+  "broker:analytics.emit",
+  "event:cart.viewed",
+  "event:checkout.started",
+  "event:order.completed",
+  "config:public.read",
+  "config:public.write",
+]);
+
+const ELIGIBLE_CAPABILITY_IDS: ReadonlySet<string> = new Set(CHECKOUT_ELIGIBLE_CAPABILITIES);
+
+/** True when a capability id may be requested by a checkout extension. */
+export function isCheckoutEligibleCapability(id: string): boolean {
+  return ELIGIBLE_CAPABILITY_IDS.has(id);
+}
+
+// ── Request / result contract ────────────────────────────────────────────────
+
+export interface CheckoutExtensionRequest {
+  binding: IntegrationBinding;
+  /** Execution tier. checkout-payment caps at sandbox; server/elevated-parent are denied. */
+  tier: ExecutionTier;
+  codeForm: CodeForm;
+  /** Requested seam ids from {@link CHECKOUT_EXTENSION_SEAMS}. */
+  seams: readonly string[];
+  /** Optional registry capabilities; each must be in {@link CHECKOUT_ELIGIBLE_CAPABILITIES}. */
+  capabilities?: readonly string[];
+  /** Requested exact-HTTPS CSP origins (shape-validated by the capability model). */
+  origins?: readonly string[];
+}
+
+/** Server-resolved evaluation context. Certification defaults OFF (fail-closed). */
+export interface CheckoutExtensionContext {
+  tenantTier: TenantTier;
+  /**
+   * A green, current checkout-extension certification for THIS binding. Server-
+   * resolved from authoritative state; never taken from the request. Absent → denied.
+   */
+  certified?: boolean;
+}
+
+export type CheckoutExtensionDenialReason =
+  | "uncertified"
+  | "unknown-seam"
+  | "capability-not-checkout-eligible"
+  | "capability"; // a passthrough denial from the underlying capability model.
+
+export interface CheckoutExtensionDenial {
+  reason: CheckoutExtensionDenialReason;
+  /** The offending seam or capability id, when one applies. */
+  subject?: string;
+  /** The underlying capability-model denial, when `reason` is `capability`. */
+  capabilityDenial?: CapabilityDenial;
+}
+
+export interface GrantedCheckoutSeam {
+  id: string;
+  location: CheckoutSeamLocation;
+  attachment: CheckoutAttachmentKind;
+  evidence: SeamEvidence;
+  requiresConsent?: ConsentPurpose;
+}
+
+export type CheckoutExtensionResult =
+  | {
+      ok: true;
+      contract: ProviderCheckoutExtensionContract;
+      binding: IntegrationBinding;
+      surface: Surface;
+      tier: ExecutionTier;
+      /** Honest enforcement for the granted tier (sandbox/adapter → enforced). */
+      enforcement: Enforcement;
+      seams: GrantedCheckoutSeam[];
+      capabilities: GrantedCapability[];
+      origins: string[];
+    }
+  | { ok: false; code: "checkout_extension_denied"; denials: CheckoutExtensionDenial[] };
+
+/**
+ * Validate a certified provider-checkout-extension request. Fail-closed and
+ * all-or-nothing: an uncertified binding, an unknown seam, a non-eligible
+ * capability, or any denial from the underlying capability model (tier above
+ * sandbox, forbidden/card-data scope, unbound binding, out-of-matrix surface,
+ * malformed origin) denies the WHOLE request — never a partial grant.
+ */
+export function validateCheckoutExtension(
+  request: CheckoutExtensionRequest,
+  context: CheckoutExtensionContext,
+): CheckoutExtensionResult {
+  const denials: CheckoutExtensionDenial[] = [];
+
+  // 1. Certification is mandatory and server-resolved.
+  if (!context.certified) {
+    denials.push({ reason: "uncertified" });
+  }
+
+  // 2. Every seam must be in the closed registry.
+  const grantedSeams: GrantedCheckoutSeam[] = [];
+  for (const id of request.seams) {
+    const def = CHECKOUT_EXTENSION_SEAMS[id];
+    if (!def) {
+      denials.push({ reason: "unknown-seam", subject: id });
+      continue;
+    }
+    grantedSeams.push({
+      id: def.id,
+      location: def.location,
+      attachment: def.attachment,
+      evidence: def.evidence,
+      requiresConsent: def.requiresConsent,
+    });
+  }
+
+  // 3. Partition requested capabilities into checkout-eligible (delegated) and
+  //    ineligible (denied here). A forbidden/card-data capability is never in the
+  //    allowlist, so it is caught here AND, defensively, by the delegated model.
+  const eligible: string[] = [];
+  for (const id of request.capabilities ?? []) {
+    if (isCheckoutEligibleCapability(id)) {
+      eligible.push(id);
+    } else {
+      denials.push({ reason: "capability-not-checkout-eligible", subject: id });
+    }
+  }
+
+  // 4. Delegate binding / tier / surface / capability / origin validation to the
+  //    ONE capability model, with the surface pinned to checkout-payment.
+  const capResult = validateIntegrationCapabilities(
+    {
+      binding: request.binding,
+      tier: request.tier,
+      surface: CHECKOUT_EXTENSION_SURFACE,
+      codeForm: request.codeForm,
+      capabilities: eligible,
+      origins: request.origins,
+    },
+    { tenantTier: context.tenantTier },
+  );
+
+  if (!capResult.ok) {
+    for (const d of capResult.denials) {
+      denials.push({ reason: "capability", subject: d.subject, capabilityDenial: d });
+    }
+  }
+
+  if (denials.length > 0 || !capResult.ok) {
+    return { ok: false, code: "checkout_extension_denied", denials };
+  }
+
+  return {
+    ok: true,
+    contract: PROVIDER_CHECKOUT_EXTENSION_CONTRACT,
+    binding: request.binding,
+    surface: CHECKOUT_EXTENSION_SURFACE,
+    tier: capResult.tier,
+    enforcement: capResult.enforcement,
+    seams: grantedSeams,
+    capabilities: capResult.capabilities,
+    origins: capResult.origins,
+  };
+}
+
+// ── Structural boundary invariant ────────────────────────────────────────────
+
+/**
+ * Assert (at module-load and in tests) that the checkout-extension vocabulary can
+ * never reach card data. Structurally: no eligible capability is a forbidden scope,
+ * and every eligible capability is a real, grantable registry id. This is the
+ * belt-and-suspenders check behind the "an extension cannot request card data"
+ * invariant — the primary enforcement is the allowlist + the capability model.
+ */
+export function assertCheckoutExtensionCardDataFree(): void {
+  const forbidden = new Set<string>(FORBIDDEN_CAPABILITIES as readonly string[]);
+  for (const id of CHECKOUT_ELIGIBLE_CAPABILITIES) {
+    if (forbidden.has(id)) {
+      throw new Error(
+        `checkout-eligible capability "${id}" is a forbidden scope — the card-data boundary is broken`,
+      );
+    }
+    if (!isGrantableCapability(id)) {
+      throw new Error(
+        `checkout-eligible capability "${id}" is not a grantable registry capability`,
+      );
+    }
+  }
+}
+
+assertCheckoutExtensionCardDataFree();