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

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

@@ -0,0 +1,311 @@
+/**
+ * KV data layer for the `ReviewEnvironment` projection — the canonical read model
+ * that answers, for one change/PR, *"what is the hosted preview, is it current, is
+ * it reviewable, and can it be merged?"* (see `docs/review-environment-contract.md`,
+ * the u0 keystone this unit — s1 — implements).
+ *
+ * This module is the STORE + TYPES only: it persists and enumerates records; it
+ * does NOT assemble/derive `status` (that join over `ChangeState` + `PreviewState`
+ * is a separate concern) and it never authors any of the projected fields — every
+ * field is a projection of an upstream fact.
+ *
+ * Backends are injected via a `get`/`put` KV interface (Cloudflare KV in prod, an
+ * in-memory map in dev + tests), mirroring `tenant-assets.ts`'s `AssetsKv` pattern,
+ * so this module stays storage-agnostic and unit-testable.
+ *
+ * NOTE (contract discrepancy, resolved): the u0 doc types `evidence` as the
+ * `EvidenceReport` from `@tot/private-controlplane`. This package is the public,
+ * edge-shipped runtime and MUST NOT import `@tot/private-controlplane` (machine-
+ * enforced — see index.ts). So `evidence` uses the structural mirror this package
+ * already carries for exactly this reason: the same shape `PreviewState.evidence`
+ * uses in `customization-reconcile.ts` (`PreviewStateEvidenceCheck[]` + `promotable`
+ * + `generatedAt`). It is surfaced from the reconcile route's evidence, never
+ * re-derived here.
+ */
+import type {
+  PreviewStateEvidenceCheck,
+  PreviewStateFinding,
+  PreviewStateOverride,
+} from "./customization-reconcile.js";
+
+/**
+ * The hosted review-environment status — a fourth, deliberately narrow vocabulary
+ * scoped to the review environment (distinct from controlplane `ChangeState`,
+ * storefront `ChangeStatus`, and evidence `EvidenceStatus`). Derived by joining the
+ * change lifecycle with the reconcile state; see the u0 contract's "Deriving status".
+ */
+export type ReviewEnvironmentStatus =
+  | "queued"
+  | "reconciling"
+  | "ready"
+  | "blocked"
+  | "merged"
+  | "closed";
+
+/**
+ * The compliance + SEO verdict carried on a `ReviewEnvironment`. Structural mirror
+ * of `@tot/private-controlplane`'s `EvidenceReport` (this package cannot import it —
+ * see the module note), identical to `PreviewState.evidence`'s shape.
+ */
+export interface ReviewEnvironmentEvidence {
+  checks: PreviewStateEvidenceCheck[];
+  /** Derived upstream: every `REQUIRED_FOR_PROMOTE` check is `pass`. */
+  promotable: boolean;
+  generatedAt: string;
+}
+
+/**
+ * One canonical read model for a change's hosted review environment. Assembled
+ * (never authored) from the change record, the forge PR, and the preview reconcile
+ * state + its evidence verdict. Persisted at `cust:change:<tenantId>:<changeId>`.
+ */
+export interface ReviewEnvironment {
+  /** Tenant/owner scope (matches `PreviewState.tenantId` + the `cust:*` key scope). */
+  tenantId: string;
+  /** Opaque change-record id — the projection is keyed on it. */
+  changeId: string;
+  /** Forge PR number, or `null` in a change-first flow before a PR exists. */
+  prNumber: number | null;
+  /** Source branch the PR ships from, or `null` until a branch/PR exists. */
+  branch: string | null;
+  /** PR head commit — the reconcile TARGET; may not yet be what renders (`versionId`). */
+  headSha: string | null;
+  /** Target-branch tip the PR merges into (merge base), or `null` before a PR. */
+  baseSha: string | null;
+  /**
+   * The immutable site `versionId` the `preview` channel currently points at (last
+   * successfully materialized commit). Equals `headSha` when `ready`; LAGS it when
+   * `blocked` (last-good preview keeps rendering). `null` before the first reconcile.
+   */
+  versionId: string | null;
+  /** Projected review-environment status (the join). Always present. */
+  status: ReviewEnvironmentStatus;
+  /** Absolute deep-link to the hosted preview, or `null` until a preview exists. */
+  previewUrl: string | null;
+  /** Compliance + SEO verdict for the rendered preview, or `null` before evidence. */
+  evidence: ReviewEnvironmentEvidence | null;
+  /**
+   * Validation findings from the candidate's last reconcile — advisory findings on a
+   * materialized candidate, or the blocking-safety findings that stopped one —
+   * surfaced in the PR review console. Absent/empty ⇒ validated clean.
+   */
+  findings?: PreviewStateFinding[];
+  /** Auditable safety-block override applied to this candidate (who/why), if any. */
+  overriddenBy?: PreviewStateOverride | null;
+  /**
+   * Environment-side merge eligibility only: `evidence?.promotable === true` AND no
+   * merge conflict AND `status === "ready"`. Deliberately excludes the acting
+   * operator's per-viewer capability (resolved server-side by `acceptGate`).
+   */
+  mergeable: boolean;
+  /** Human-legible reason the environment is not healthy, or `null` when healthy. */
+  lastError: string | null;
+  /** ISO 8601 timestamp of the last time this projection was recomputed. */
+  updatedAt: string;
+}
+
+/** KV key for one tenant-change `ReviewEnvironment` projection. */
+export function reviewEnvironmentKey(tenantId: string, changeId: string): string {
+  return `cust:change:${tenantId}:${changeId}`;
+}
+/** KV key for a tenant's change index (list of changeIds). */
+export function reviewEnvironmentIndexKey(tenantId: string): string {
+  return `cust:changes:${tenantId}`;
+}
+
+/**
+ * Injectable KV backend for the candidate store (Cloudflare KV in prod, an
+ * in-memory map in dev + tests). Mirrors `tenant-assets.ts`'s `AssetsKv`.
+ */
+export interface CandidateKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+/**
+ * A {@link CandidateKv} that can also DELETE a key — the eviction surface the
+ * retire/GC path (unit U7) needs. Kept separate from `CandidateKv` so the many
+ * write-only `{ get, put }` adapters (the webhook reconcile, build-on-demand,
+ * accept) are unaffected: only the retire endpoint constructs a delete-capable
+ * adapter. A real Cloudflare KV namespace satisfies this structurally.
+ */
+export interface CandidateKvDeletable extends CandidateKv {
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Read one tenant-change `ReviewEnvironment`, or `null` when absent/malformed.
+ * Never throws — a malformed record reads as `null` (fall back to a recompute).
+ */
+export async function readReviewEnvironment(
+  kv: Pick<CandidateKv, "get">,
+  tenantId: string,
+  changeId: string,
+): Promise<ReviewEnvironment | null> {
+  const raw = await kv.get(reviewEnvironmentKey(tenantId, changeId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as ReviewEnvironment;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a tenant's change index (the list of `changeId`s), or `[]` when unset or
+ * malformed. Never throws — the index is a read-optimization, never a write gate.
+ */
+export async function readChangeIndex(
+  kv: Pick<CandidateKv, "get">,
+  tenantId: string,
+): Promise<string[]> {
+  const raw = await kv.get(reviewEnvironmentIndexKey(tenantId));
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed)
+      ? parsed.filter((id): id is string => typeof id === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * In-process serialization for the per-tenant change-index read-modify-write.
+ *
+ * The tenant index (`cust:changes:<tenantId>`) is updated by a read-modify-write:
+ * read the current id list, append if absent, write it back. The injected KV is a
+ * bare Cloudflare KV namespace in prod (`{ get, put }` — see the `candidateKv`
+ * adapter in `apps/storefront/src/pages/api/changes/accept.ts`) with NO
+ * compare-and-swap / conditional-write primitive, so two concurrent writes for
+ * different candidates of one tenant can interleave — both read the index before
+ * either writes it back — and the second `put` silently drops the first's append.
+ *
+ * Chaining every index write for a given key through one promise removes that
+ * interleaving *within a Worker isolate*, where concurrent requests share this
+ * module instance — which is the realistic concurrent-reconcile shape (two open
+ * PRs for one tenant reconciling on two near-simultaneous invocations on the same
+ * isolate). Cross-isolate writes to the same key remain last-write-wins; CF KV
+ * exposes no primitive to prevent that, so this closes the in-isolate race the
+ * repro test exercises rather than pretending to a distributed lock the backend
+ * cannot provide.
+ */
+const indexWriteChains = new Map<string, Promise<unknown>>();
+
+function serializeIndexWrite<T>(
+  key: string,
+  task: () => Promise<T>,
+): Promise<T> {
+  const prev = indexWriteChains.get(key) ?? Promise.resolve();
+  // Run `task` after the prior write settles (success OR failure), so one
+  // rejected write never wedges the chain for the key.
+  const run = prev.then(task, task);
+  const settled = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  indexWriteChains.set(key, settled);
+  void settled.then(() => {
+    if (indexWriteChains.get(key) === settled) indexWriteChains.delete(key);
+  });
+  return run;
+}
+
+/**
+ * Test-only: clear the per-index write-serialization chains. `indexWriteChains` is a
+ * MODULE singleton (deliberately — the in-isolate serialization is process-wide), so
+ * under a shared-module test runner it leaks ACROSS test files: a settled chain left
+ * by one file is inherited by the next, making otherwise-isolated tests order-
+ * dependent. Call in `beforeEach` to give each test a clean slate. No-op in prod.
+ */
+export function resetReviewEnvIndexWriteChainsForTest(): void {
+  indexWriteChains.clear();
+}
+
+/**
+ * Upsert one `ReviewEnvironment` record and add its `changeId` to the tenant index
+ * (idempotent — a re-write of an existing change leaves the index unchanged). The
+ * per-record write goes to its own key (`cust:change:<tenantId>:<changeId>`) with
+ * no cross-candidate contention, so it stays outside the lock. The index update is
+ * a read-modify-write over the SHARED per-tenant key, so it is serialized per index
+ * key (see `serializeIndexWrite`) to keep concurrent writes for different
+ * candidates from clobbering each other's append.
+ */
+export async function writeReviewEnvironment(
+  kv: CandidateKv,
+  record: ReviewEnvironment,
+): Promise<void> {
+  await kv.put(
+    reviewEnvironmentKey(record.tenantId, record.changeId),
+    JSON.stringify(record),
+  );
+  await serializeIndexWrite(reviewEnvironmentIndexKey(record.tenantId), async () => {
+    const index = await readChangeIndex(kv, record.tenantId);
+    if (!index.includes(record.changeId)) {
+      await kv.put(
+        reviewEnvironmentIndexKey(record.tenantId),
+        JSON.stringify([...index, record.changeId]),
+      );
+    }
+  });
+}
+
+/**
+ * Evict one `ReviewEnvironment` record AND remove its `changeId` from the tenant
+ * index — the KV half of retire/GC (unit U7). The per-record key is deleted
+ * outright; the tenant index is updated by the SAME serialized read-modify-write
+ * `writeReviewEnvironment` uses (see {@link serializeIndexWrite}), so a retire that
+ * races a concurrent write for a DIFFERENT candidate never resurrects a dropped
+ * entry or leaves a dangling index id (the corruption risk this helper exists to
+ * prevent — the mirror-image of `writeReviewEnvironment`'s append).
+ *
+ * IDEMPOTENT by contract: deleting an already-absent candidate is a clean no-op.
+ * Returns whether anything was actually removed (`true` iff the record existed OR
+ * the index carried the id), so the caller can report `evicted` honestly while a
+ * repeat retire still succeeds.
+ */
+export async function deleteReviewEnvironment(
+  kv: CandidateKvDeletable,
+  tenantId: string,
+  changeId: string,
+): Promise<boolean> {
+  // Did the record exist before we removed it? (drives the honest `evicted` flag).
+  const recordExisted =
+    (await kv.get(reviewEnvironmentKey(tenantId, changeId))) !== null;
+  await kv.delete(reviewEnvironmentKey(tenantId, changeId));
+
+  // Update the SHARED per-tenant index under the same per-key serialization as the
+  // append, so a concurrent write for another candidate can't clobber the removal
+  // (and vice-versa). Only rewrite when the id is actually present — an idempotent
+  // repeat leaves the index byte-identical.
+  let indexHadId = false;
+  await serializeIndexWrite(reviewEnvironmentIndexKey(tenantId), async () => {
+    const index = await readChangeIndex(kv, tenantId);
+    if (index.includes(changeId)) {
+      indexHadId = true;
+      await kv.put(
+        reviewEnvironmentIndexKey(tenantId),
+        JSON.stringify(index.filter((id) => id !== changeId)),
+      );
+    }
+  });
+
+  return recordExisted || indexHadId;
+}
+
+/**
+ * Enumerate a tenant's `ReviewEnvironment` records via the index (one `get` per
+ * indexed change, no scan). Skips any index entry whose record is missing/malformed,
+ * so a dangling index id never breaks the list.
+ */
+export async function listReviewEnvironments(
+  kv: Pick<CandidateKv, "get">,
+  tenantId: string,
+): Promise<ReviewEnvironment[]> {
+  const index = await readChangeIndex(kv, tenantId);
+  const records = await Promise.all(
+    index.map((changeId) => readReviewEnvironment(kv, tenantId, changeId)),
+  );
+  return records.filter((r): r is ReviewEnvironment => r !== null);
+}

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

@@ -24,6 +24,7 @@ import type {
   ProductPurchaseOption,
   SubscriptionPurchaseOption,
 } from "./product.js";
+import { DEFAULT_ONE_TIME_PURCHASE_OPTION } from "./product.js";
 
 /**
  * Per-tenant managed-checkout wiring. Public config only — the signing SECRET is never
@@ -95,6 +96,26 @@ export interface BuildVariantCartPayloadOptions {
   mode: ManagedCheckoutConfig["mode"];
   secret?: string;
   purchaseOption?: ProductPurchaseOption;
+  /**
+   * The member-adjusted EFFECTIVE price to sign (F11b), computed server-side via
+   * membership.ts `priceForPurchaseOption` for the shopper's resolved eligibility.
+   * When set it REPLACES the list/subscription price as the single signed source
+   * of truth, so a given price is only ever valid for the member context it was
+   * signed under (see {@link ../membership.ts buildMemberSignedCartPayload}).
+   * Absent → the list/subscription price (anonymous shopper). Never a client-
+   * supplied value: only the server, holding the cart secret, ever signs it.
+   */
+  signedPrice?: number;
+  /**
+   * Whether Autopilot (subscription purchase options) is enabled for the tenant.
+   * `visiblePurchaseOptions` already drops subscription options when Autopilot is
+   * off, so a subscription option reaching the signer means that filter was
+   * bypassed; when `false` we REFUSE to sign it (hide-at-launch). The server thus
+   * never mints a signed subscription payload, so a hidden Autopilot plan can't be
+   * resurrected via a crafted form post. Defaults to `true` (the framework default
+   * — subscriptions visible) so existing callers are unaffected.
+   */
+  autopilotEnabled?: boolean;
 }
 
 const DEFAULT_CHECKOUT_HOST_SUFFIX = ".foxycart.com";
@@ -126,11 +147,18 @@ export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
   purchaseOption?: ProductPurchaseOption,
+  opts?: { signedPrice?: number },
 ): { code: string; fields: CartField[] } {
   const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
     product.images[0]?.url;
-  const price = purchaseOptionPrice(variant.price, purchaseOption);
+  // The signed price is either the caller's member-adjusted EFFECTIVE price
+  // (F11b — the single signed source of truth, computed server-side from the
+  // shopper's resolved eligibility) or, absent that, the list/subscription price.
+  const price =
+    opts?.signedPrice !== undefined
+      ? assertEffectivePrice(opts.signedPrice, variant.price)
+      : purchaseOptionPrice(variant.price, purchaseOption);
   const fields: CartField[] = [
     { name: "name", value: variant.title || product.title },
     { name: "price", value: price.toFixed(2) },
@@ -143,12 +171,45 @@ export function cartFieldsForVariant(
   for (const [optName, optVal] of Object.entries(variant.option_values)) {
     if (optName && optVal) fields.push({ name: optName, value: optVal });
   }
+  // Bind the SELECTED purchase option into the signed payload so a shopper can't
+  // switch one-time↔subscription (or between plans) after the form is signed —
+  // e.g. keep a subscription's discounted `price` while dropping the recurring
+  // commitment. The synthesized default one-time option carries no real choice,
+  // so we omit it to avoid a redundant "Purchase option: One-time purchase" line
+  // on every non-subscription cart. Any authored option (a real one-time plan or
+  // a subscription) is emitted and signed → modifying it fails validation.
+  if (purchaseOption && !isDefaultOneTimeOption(purchaseOption)) {
+    fields.push({ name: "Purchase option", value: purchaseOption.label });
+  }
   if (purchaseOption?.kind === "subscription") {
     fields.push(...subscriptionCartFields(purchaseOption));
   }
   return { code, fields };
 }
 
+/**
+ * Validate a caller-supplied EFFECTIVE price before it becomes the signed source
+ * of truth (F11b). The member-adjusted price (membership.ts
+ * `priceForPurchaseOption`) is computed server-side and threaded in so the SIGNED
+ * price reflects the shopper's resolved eligibility. It must be a finite,
+ * non-negative amount no greater than the list price — an effective price is
+ * always a discount off list, never an increase, so anything above list signals a
+ * pricing bug and is refused rather than signed.
+ */
+function assertEffectivePrice(signedPrice: number, listPrice: number): number {
+  if (!Number.isFinite(signedPrice) || signedPrice < 0) {
+    throw new Error(
+      `signed price must be a finite non-negative number (got ${signedPrice})`,
+    );
+  }
+  if (signedPrice > listPrice) {
+    throw new Error(
+      `signed price ${signedPrice} exceeds the list price ${listPrice} — an effective price must be a discount off list`,
+    );
+  }
+  return Number(signedPrice.toFixed(2));
+}
+
 export function purchaseOptionPrice(
   basePrice: number,
   purchaseOption?: ProductPurchaseOption,
@@ -184,6 +245,19 @@ export function isSubscriptionFrequency(value: string): boolean {
   return Number.isFinite(amount) && amount > 0;
 }
 
+/**
+ * True for the synthesized default one-time option (see
+ * `DEFAULT_ONE_TIME_PURCHASE_OPTION`) — the "no real choice" case where binding a
+ * "Purchase option" field would only add cart-line noise. An authored one-time
+ * option (distinct id) is a genuine choice and is NOT treated as the default.
+ */
+function isDefaultOneTimeOption(option: ProductPurchaseOption): boolean {
+  return (
+    option.kind === "one_time" &&
+    option.id === DEFAULT_ONE_TIME_PURCHASE_OPTION.id
+  );
+}
+
 function subscriptionCartFields(
   option: SubscriptionPurchaseOption,
 ): CartField[] {
@@ -193,8 +267,10 @@ function subscriptionCartFields(
     );
   }
 
+  // NB: the shopper-facing "Purchase option" line is emitted (and signed) by the
+  // general purchase-option branch in cartFieldsForVariant, not here — this adds
+  // only the checkout engine's reserved subscription params.
   const fields: CartField[] = [
-    { name: "Purchase option", value: option.label },
     { name: "sub_frequency", value: option.frequency },
   ];
   if (option.startDate) {
@@ -249,10 +325,26 @@ export async function buildVariantCartPayload(
   variant: CatalogVariant,
   opts: BuildVariantCartPayloadOptions,
 ): Promise<VariantCartPayload> {
+  // Hide-at-launch guard (F11b): 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
+  // bypassed (e.g. a crafted request) — signing it would mint a valid subscription
+  // payload that a crafted form post could then replay into the cart. Fail closed.
+  if (
+    opts.autopilotEnabled === false &&
+    opts.purchaseOption?.kind === "subscription"
+  ) {
+    throw new Error(
+      "buildVariantCartPayload: refusing to sign a subscription purchase option " +
+        "while Autopilot is disabled (hide-at-launch) — visiblePurchaseOptions must " +
+        "be applied before signing",
+    );
+  }
   const { code, fields } = cartFieldsForVariant(
     product,
     variant,
     opts.purchaseOption,
+    { signedPrice: opts.signedPrice },
   );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {