@tokenoftrust/storefront-runner 2.4.91 → 2.5.0

package/package.json

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

package/packages/public-runtime/src/checkout-orders.ts

@@ -223,7 +223,7 @@ export const LABEL_STATES = [
 ] as const;
 export type LabelState = (typeof LABEL_STATES)[number];
 
-export const EVIDENCE_STATES = ["fresh", "UNKNOWN", "stale", "unreadable", "absent"] as const;
+export const EVIDENCE_STATES = ["fresh", "not-required", "UNKNOWN", "stale", "unreadable", "absent"] as const;
 export type EvidenceState = (typeof EVIDENCE_STATES)[number];
 
 export const PROVIDER_OUTCOMES = ["intent", "accepted", "unknown", "voided", "refunded"] as const;
@@ -331,6 +331,48 @@ export interface FinalCartBinding {
   taxExpiresAt: string;
 }
 
+/** Provider-authenticated cart facts; authority evidence is resolved by the receiving server. */
+export interface CommerceProviderCartSnapshot {
+  provider: "foxycart";
+  providerCartId: string;
+  providerCartDigest: string;
+  /** Current PRIVATE provider-cart reference, verified by the provider integration. */
+  expectedAuthorizationId?: string;
+  tenantId: string;
+  stage: CommerceStage;
+  currency: string;
+  lines: readonly FinalCartLine[];
+  totals: MinorTotals;
+  destinationDigest: string;
+  destination: { country: string; region: string };
+}
+
+/** Safe source references explaining each server-owned authority decision. */
+export interface CommerceAuthoritySource {
+  requirement: "required" | "not-required";
+  state: "satisfied" | "not-required";
+  source: string;
+  policyRevision: string;
+  expiresAt: string;
+}
+export type CommerceEvidenceProvenance = Record<keyof CommerceEvidence, CommerceAuthoritySource>;
+
+export interface SyntheticCommerceAuthorityPolicy {
+  purpose: "synthetic-nonbillable";
+  revision: string;
+  expiresAt: string;
+  requirements: Record<"verification" | "tax" | "risk", "required" | "not-required">;
+}
+
+export interface CommerceAdmissionSnapshot extends CommerceProviderCartSnapshot {
+  authorizationId: string;
+  cartDigest: string;
+  evidence: CommerceEvidence;
+  provenance: CommerceEvidenceProvenance;
+  expiresAt: string;
+  now: string;
+}
+
 export interface AsymmetricCallerToken {
   scheme: "asymmetric-jwks";
   signatureValid: boolean;
@@ -358,12 +400,8 @@ export type CallerTokenRefusal =
   | "stage";
 
 export function evidencePermitsRelease(evidence: CommerceEvidence): boolean {
-  return (
-    evidence.verification === "fresh" &&
-    evidence.tax === "fresh" &&
-    evidence.risk === "fresh" &&
-    evidence.stock === "fresh"
-  );
+  return evidence.stock === "fresh" && (["verification", "tax", "risk"] as const)
+    .every(field => evidence[field] === "fresh" || evidence[field] === "not-required");
 }
 
 export function paymentIsCaptured(payment: PaymentState): boolean {

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

@@ -25,13 +25,32 @@ import type {
   SubscriptionPurchaseOption,
 } from "./product.js";
 import { DEFAULT_ONE_TIME_PURCHASE_OPTION } from "./product.js";
+import type { TenantConfig } from "./tenant.js";
+
+/** Stable commerce scope shared by signed carts, provider callers and operator authorization. */
+export function commerceTenantId(tenant: Pick<TenantConfig, "appDomain">): string {
+  return tenant.appDomain;
+}
+
+/** Public API destination on the declared nonproduction wildcard Worker route. */
+export const SAMPLE_CART_HANDOFF_URL =
+  "https://synthetic-vendor-b.tokenoftrust.store/api/commerce/checkout-handoff";
+
+/** Identifier-only local sample form. Product facts are resolved by the hosted catalog. */
+export function sampleVariantCartPayload(handle: string, variantId: string): VariantCartPayload {
+  return {
+    hidden: [
+      { name: "sample_product", value: handle },
+      { name: "sample_variant", value: variantId },
+    ],
+    quantityName: "quantity",
+  };
+}
 
 /**
  * Per-tenant managed-checkout wiring. Public config only — the signing SECRET is never
- * stored here (it's an env-injected Worker binding, resolved per request). In
- * `unsigned-demo` mode there is no secret at all: links go to a demo store that
- * has cart validation turned OFF, so a developer can run the full cart locally
- * (and on our shared preview worker) with zero secrets.
+ * stored here (it's an env-injected Worker binding, resolved per request).
+ * `unsigned-demo` sends plain fields and reads no secret.
  */
 export interface ManagedCheckoutConfig {
   /** Checkout store subdomain, e.g. "tot-demo". */
@@ -42,8 +61,8 @@ export interface ManagedCheckoutConfig {
    */
   storeDomain?: string;
   /**
-   * "signed" (preview/live: cart validation ON, HMAC every field) or
-   * "unsigned-demo" (local/preview demo: validation OFF, no secret needed).
+   * "signed" (cart validation ON, HMAC every field; requires FOXY_CART_SECRET) or
+   * "unsigned-demo" (plain fields, reads no secret).
    */
   mode: "signed" | "unsigned-demo";
   /**
@@ -59,9 +78,15 @@ export interface ManagedCheckoutConfig {
   cartDrawerCss?: string;
 }
 
+/** Runtime tenant records must name a supported mode before they can build or admit a cart. */
+export function isManagedCheckoutMode(value: unknown): value is ManagedCheckoutConfig["mode"] {
+  return value === "signed" || value === "unsigned-demo";
+}
+
 /**
- * The ONE shared ToT-owned demo checkout store (test mode, cart validation
- * OFF, no secret). The local dev loop (`synthesizeDevTenant`) wires every
+ * The ONE shared ToT-owned demo checkout store (`tot-preview`). Carts are
+ * signed: HMAC cart validation is required, and FOXY_CART_SECRET must be set
+ * before they are served. The local dev loop (`synthesizeDevTenant`) wires every
  * local commerce checkout to this exact config; the hosted QA/test tier's
  * demo-checkout fallback (`resolveTenantCommerce`) reuses this same constant
  * rather than a second copy of the literal, so "the same as `tot dev`" stays
@@ -69,7 +94,7 @@ export interface ManagedCheckoutConfig {
  */
 export const SHARED_DEMO_CHECKOUT: ManagedCheckoutConfig = {
   storeSubDomain: "tot-preview",
-  mode: "unsigned-demo",
+  mode: "signed",
 };
 
 /** Resolved, request-scoped commerce facts stashed on `Astro.locals`. */
@@ -244,6 +269,7 @@ export function quantityAllowed(value: string): boolean {
 export function resolveManagedCheckout(
   config: ManagedCheckoutConfig,
 ): ResolvedManagedCheckout {
+  if (!isManagedCheckoutMode(config.mode)) throw new CartSigningUnavailableError();
   const storeDomain =
     config.storeDomain ??
     `${config.storeSubDomain}${DEFAULT_CHECKOUT_HOST_SUFFIX}`;
@@ -463,6 +489,7 @@ export async function buildVariantCartPayload(
   variant: CatalogVariant,
   opts: BuildVariantCartPayloadOptions,
 ): Promise<VariantCartPayload> {
+  if (!isManagedCheckoutMode(opts.mode)) throw new CartSigningUnavailableError();
   // Hide-at-launch guard: refuse to SIGN a subscription option while
   // Autopilot is disabled. `visiblePurchaseOptions` removes subscription options
   // for such tenants, so one reaching the signer means the visibility filter was
@@ -586,6 +613,7 @@ export async function enforceCartSubmission(input: {
   secret?: string;
   trustedTenantId: string;
 }): Promise<CartEnforcement> {
+  if (!isManagedCheckoutMode(input.mode)) return denial("signing-unavailable");
   if (input.mode === "signed" && !input.secret) return denial("signing-unavailable");
   if (!input.trustedTenantId) return denial("tenant");
 

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

@@ -12,6 +12,7 @@ import type { IntegrationDeclarationInput } from "./integration/resolve.js";
 import type { EuUkVisitorPolicy } from "./integration/plan.js";
 import type { PublicationSpaceManifestV1 } from "./publication-space.js";
 import type { HtmlCachePolicy } from "./html-cache-policy.js";
+import type { SyntheticCommerceAuthorityPolicy } from "./checkout-orders.js";
 
 /**
  * The shared semantic COLOR contract — the widget library's public API.
@@ -609,6 +610,8 @@ export interface TenantConfig {
    */
   commerce?: {
     checkout?: ManagedCheckoutConfig;
+    /** Server-owned applicability for nonbillable synthetic fixtures; never waives regulated rules. */
+    authorityPolicy?: SyntheticCommerceAuthorityPolicy;
     /**
      * Autopilot (subscription) program visibility. Absent → subscription
      * purchase options render wherever a product authors them (framework/dev