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

package/apps/storefront/src/lib/apps/orders/orderConversionD1.ts

@@ -0,0 +1,150 @@
+/**
+ * The D1-backed durable seams the verified-order conversion join
+ * (`@tot/public-runtime`'s `computeOrderConversion`) needs in the Worker, plus the
+ * thin wrapper the order-forward receiver route calls to run the join.
+ *
+ * Two durable stores on `STOREFRONT_APPS_DB` (the same D1 the order rows live in, so
+ * attribution and the order it attributes share one database):
+ *   - `correlation_replay` — the single-use `jti` ledger behind the injected
+ *     {@link CorrelationReplayGuard}: a correlation token is honored exactly once, and
+ *     a replay of a consumed `jti` is refused. Rows are pruned once past their `exp`
+ *     (a past-`exp` token is already rejected `expired` before the guard is reached).
+ *   - `order_attribution` — the per-`(tenant, orderId)` attribution ledger: the order's
+ *     attribution is fixed on its first conversion and reused for later lifecycle events.
+ *
+ * Both run over the `Queryable` seam, so they serve real D1 in the Worker and an
+ * in-memory `node:sqlite` in tests unchanged.
+ */
+import type { Queryable } from "../../d1/catalog.js";
+import { readEnv } from "@/lib/env";
+import {
+  computeOrderConversion,
+  resolveConversionEnvironment,
+  readEchoedCorrelation,
+  type CorrelationReplayGuard,
+  type OrderConversionAttributionStore,
+  type OrderConversionResult,
+  type StoredAttribution,
+} from "@tot/public-runtime";
+import type { OrderForwardInput, OrderForwardResult } from "./orderForwardReceiver.js";
+
+/** The server-only correlation-signing key binding, distinct from the cart secret. */
+const CORRELATION_SECRET_ENV = "COMMERCE_CORRELATION_SECRET";
+
+/**
+ * Durable single-use `jti` guard over `correlation_replay`. `seen` is an existence
+ * check; `remember` prunes any past-`exp` rows (bounded growth) then records the `jti`
+ * idempotently.
+ */
+export class D1CorrelationReplayGuard implements CorrelationReplayGuard {
+  constructor(
+    private readonly db: Queryable,
+    private readonly nowSec: () => number = () => Math.floor(Date.now() / 1000),
+  ) {}
+
+  async seen(jti: string): Promise<boolean> {
+    const row = await this.db.first<{ one: number }>(
+      `SELECT 1 AS one FROM correlation_replay WHERE jti = ?`,
+      jti,
+    );
+    return row != null;
+  }
+
+  async remember(jti: string, expiresAtSec: number): Promise<void> {
+    const now = this.nowSec();
+    await this.db.run(`DELETE FROM correlation_replay WHERE expires_at <= ?`, now);
+    await this.db.run(
+      `INSERT OR IGNORE INTO correlation_replay (jti, expires_at, consumed_at) VALUES (?, ?, ?)`,
+      jti,
+      expiresAtSec,
+      new Date(now * 1000).toISOString(),
+    );
+  }
+}
+
+interface OrderAttributionRow {
+  attributed: number;
+  correlation_id: string | null;
+  correlation_expires_at: string | null;
+  reason: string | null;
+}
+
+/** Durable per-`(tenant, orderId)` attribution ledger over `order_attribution`. */
+export class D1OrderConversionAttributionStore implements OrderConversionAttributionStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  async get(tenant: string, orderId: string): Promise<StoredAttribution | null> {
+    const row = await this.db.first<OrderAttributionRow>(
+      `SELECT attributed, correlation_id, correlation_expires_at, reason
+         FROM order_attribution WHERE tenant_id = ? AND external_order_id = ?`,
+      tenant,
+      orderId,
+    );
+    return row ? toStored(row) : null;
+  }
+
+  async putIfAbsent(
+    tenant: string,
+    orderId: string,
+    record: StoredAttribution,
+  ): Promise<StoredAttribution> {
+    await this.db.run(
+      `INSERT OR IGNORE INTO order_attribution
+         (tenant_id, external_order_id, attributed, correlation_id, correlation_expires_at, reason, recorded_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      tenant,
+      orderId,
+      record.attributed ? 1 : 0,
+      record.correlationId,
+      record.correlationExpiresAt,
+      record.reason,
+      this.now(),
+    );
+    // Return the EFFECTIVE row: a concurrent first-writer's record wins over this one.
+    const stored = await this.get(tenant, orderId);
+    return stored ?? record;
+  }
+}
+
+function toStored(row: OrderAttributionRow): StoredAttribution {
+  return {
+    attributed: row.attributed === 1,
+    correlationId: row.correlation_id,
+    correlationExpiresAt: row.correlation_expires_at,
+    reason: (row.reason as StoredAttribution["reason"]) ?? null,
+  };
+}
+
+/**
+ * Run the verified-order → server conversion join for one forwarded order: read the
+ * echoed correlation the provider carried back, resolve the durable guard + attribution
+ * ledger over `db`, and produce the canonical server conversion event(s) plus the
+ * explicit attribution outcome. The correlation is verified against the ORDER's own
+ * tenant/environment, so a cross-tenant/stage token can never attribute.
+ */
+export async function joinForwardedOrderConversion(
+  db: Queryable,
+  input: OrderForwardInput,
+  receiverResult: OrderForwardResult,
+): Promise<OrderConversionResult> {
+  const correlationSecret = await readEnv(CORRELATION_SECRET_ENV);
+  return computeOrderConversion({
+    order: {
+      tenant: input.tenantId,
+      externalOrderId: input.externalOrderId,
+      status: receiverResult.order.status,
+      currency: input.currency,
+      total: input.total,
+      lineItems: input.lineItems,
+    },
+    environment: resolveConversionEnvironment(input.env),
+    emittedTopics: receiverResult.emitted,
+    echoedCorrelation: readEchoedCorrelation(input.providerFields),
+    correlationSecret,
+    guard: new D1CorrelationReplayGuard(db),
+    attributionStore: new D1OrderConversionAttributionStore(db),
+  });
+}

package/apps/storefront/src/lib/apps/orders/orderForwardReceiver.ts

@@ -51,6 +51,14 @@ export interface OrderForwardInput {
   rawCustomerId?: string;
   /** ISO timestamp the order was actually created at tot-foxycart. Defaults to receipt time when omitted (e.g. a backfill missing it) — only matters for a brand-new row; ignored on an update. */
   createdAt?: string;
+  /** The provider's echoed custom cart fields (e.g. `h:tot_correlation`) the order-conversion join reads the correlation token from. Absent → the conversion is explicitly unattributed. */
+  providerFields?: Record<string, unknown>;
+  /** Opaque provider event identity. Missing legacy forwards are never measured. */
+  providerEventId?: string;
+  /** Exact provider event instant; measurement rejects non-canonical/missing values. */
+  occurredAt?: string;
+  /** Provider-authoritative non-negative minor-unit total; no float conversion is used. */
+  amountMinor?: number;
 }
 
 export interface OrderForwardResult {

package/apps/storefront/src/lib/apps/orders/ordersStore.ts

@@ -12,7 +12,7 @@
  */
 import type { Queryable } from "../../d1/catalog.js";
 
-export type OrderStatus = "created" | "fulfilled" | "cancelled";
+export type OrderStatus = "created" | "fulfilled" | "refunded" | "cancelled";
 
 /** One order line item (JSON-as-text in the row; see `Order.lineItems` in the contract). */
 export interface OrderLineItem {

package/apps/storefront/src/lib/apps/orders/verifiedProviderMeasurement.ts

@@ -0,0 +1,117 @@
+/** Durable WS4 adapter for the already HMAC-verified Foxy order-forward path.
+ * It has no browser, GTM, dataLayer, receipt-DOM, destination, or admin capability.
+ * The caller catches every error, so a measurement-store outage cannot block commerce. */
+import {
+  intentFromVerifiedProviderTruth,
+} from "../../../../../../packages/public-runtime/src/regulated-commerce/provider-order/bridge.js";
+import {
+  parseVerifiedOrderTruth,
+  resolveVerifiedOrderTruth,
+  verifiedOrderTruthFingerprint,
+  type VerifiedOrderSnapshot,
+  type VerifiedOrderTruth,
+  type VerifiedOrderTruthResolution,
+} from "../../../../../../packages/public-runtime/src/regulated-commerce/purchase-truth/contract.js";
+import type { RegulatedCommerceIntent } from "../../../../../../packages/public-runtime/src/regulated-commerce/events/contract.js";
+import type { Queryable } from "../../d1/catalog.js";
+import type { OrderForwardInput } from "./orderForwardReceiver.js";
+
+const FOXY_PROVIDER = "foxycart";
+const LIVE_ENVS = new Set(["live", "production"]);
+type ProviderEventRow = { fingerprint: string; receipt_id: string };
+type ProviderOrderRow = { provider: string; provider_order_id: string; tenant_id: string; state: "purchased" | "refunded" | "cancelled" };
+
+export type VerifiedProviderMeasurementOutcome =
+  | "recorded" | "duplicate" | "replay-conflict" | "stale-transition" | "ignored-non-live" | "ignored-malformed";
+export interface VerifiedProviderMeasurementResult { readonly outcome: VerifiedProviderMeasurementOutcome; readonly intent: RegulatedCommerceIntent | null; }
+
+function snapshot(row: ProviderOrderRow | null): VerifiedOrderSnapshot | null {
+  return row ? { provider: row.provider, providerOrderId: row.provider_order_id, tenant: row.tenant_id, state: row.state } : null;
+}
+function isIsoInstant(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
+}
+
+/** Missing event identity/minor units fails closed. Legacy forwards still ACK as
+ * commerce, but cannot become regulated measurement. */
+export function verifiedTruthFromForwardedOrder(input: OrderForwardInput): VerifiedOrderTruth | null {
+  if (!LIVE_ENVS.has(input.env)) return null;
+  if (typeof input.providerEventId !== "string" || !isIsoInstant(input.occurredAt) || typeof input.amountMinor !== "number" || !Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return null;
+  const parsed = parseVerifiedOrderTruth({
+    schemaVersion: "1", authority: "verified-provider", provider: FOXY_PROVIDER,
+    providerEventId: input.providerEventId, providerOrderId: input.externalOrderId,
+    tenant: input.tenantId, status: input.status, occurredAt: input.occurredAt,
+    currency: input.currency, amountMinor: input.amountMinor,
+  });
+  return parsed.ok ? parsed.value : null;
+}
+
+/** Server-only D1 ledger/outbox. Event insertion uses a receipt id plus RETURNING,
+ * giving concurrent identical deliveries one winner. The order state change is a
+ * guarded SQL CAS, so a race cannot overwrite a refund/cancel with a purchase. */
+export class D1VerifiedProviderMeasurementStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly receiptId: () => string = () => crypto.randomUUID(),
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  async record(input: OrderForwardInput): Promise<VerifiedProviderMeasurementResult> {
+    if (!LIVE_ENVS.has(input.env)) return { outcome: "ignored-non-live", intent: null };
+    const record = verifiedTruthFromForwardedOrder(input);
+    if (!record) return { outcome: "ignored-malformed", intent: null };
+    const fingerprint = verifiedOrderTruthFingerprint(record);
+    const receiptId = this.receiptId();
+    const inserted = await this.db.all<{ receipt_id: string }>(
+      `INSERT INTO regulated_commerce_provider_events
+         (provider, provider_event_id, fingerprint, receipt_id, received_at)
+       VALUES (?, ?, ?, ?, ?) ON CONFLICT(provider, provider_event_id) DO NOTHING RETURNING receipt_id`,
+      record.provider, record.providerEventId, fingerprint, receiptId, this.now(),
+    );
+    if (inserted.length === 0) {
+      const existing = await this.event(record.provider, record.providerEventId);
+      return { outcome: existing?.fingerprint === fingerprint ? "duplicate" : "replay-conflict", intent: null };
+    }
+    for (let attempts = 0; attempts < 3; attempts++) {
+      const resolution = resolveVerifiedOrderTruth({ record, existingEvent: null, existingOrder: snapshot(await this.order(record)) });
+      if (resolution.outcome !== "accepted") return { outcome: resolution.outcome === "stale-transition" ? "stale-transition" : "replay-conflict", intent: null };
+      if (!(await this.claimTransition(record, resolution))) continue;
+      const built = intentFromVerifiedProviderTruth(record, resolution);
+      if (!built.intent) return { outcome: "recorded", intent: null };
+      await this.db.run(
+        `INSERT OR IGNORE INTO regulated_commerce_intent_outbox
+           (intent_id, tenant_id, provider, provider_event_id, payload, created_at) VALUES (?, ?, ?, ?, ?, ?)`,
+        built.intent.id, record.tenant, record.provider, record.providerEventId, JSON.stringify(built.intent), this.now(),
+      );
+      return { outcome: "recorded", intent: built.intent };
+    }
+    return { outcome: "stale-transition", intent: null };
+  }
+
+  /** Local/admin-safe test surface: only the minimized semantic outbox. */
+  async intents(): Promise<RegulatedCommerceIntent[]> {
+    const rows = await this.db.all<{ payload: string }>(`SELECT payload FROM regulated_commerce_intent_outbox ORDER BY created_at, intent_id`);
+    return rows.map((row) => JSON.parse(row.payload) as RegulatedCommerceIntent);
+  }
+
+  private event(provider: string, providerEventId: string): Promise<ProviderEventRow | null> {
+    return this.db.first<ProviderEventRow>(`SELECT fingerprint, receipt_id FROM regulated_commerce_provider_events WHERE provider = ? AND provider_event_id = ?`, provider, providerEventId);
+  }
+  private order(record: VerifiedOrderTruth): Promise<ProviderOrderRow | null> {
+    return this.db.first<ProviderOrderRow>(`SELECT provider, provider_order_id, tenant_id, state FROM regulated_commerce_provider_orders WHERE provider = ? AND provider_order_id = ? AND tenant_id = ?`, record.provider, record.providerOrderId, record.tenant);
+  }
+  private async claimTransition(record: VerifiedOrderTruth, resolution: Extract<VerifiedOrderTruthResolution, { outcome: "accepted" }>): Promise<boolean> {
+    const rows = await this.db.all<{ provider_event_id: string }>(
+      `INSERT INTO regulated_commerce_provider_orders
+         (provider, provider_order_id, tenant_id, state, provider_event_id, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(provider, provider_order_id, tenant_id) DO UPDATE SET
+         state = excluded.state, provider_event_id = excluded.provider_event_id, updated_at = excluded.updated_at
+       WHERE regulated_commerce_provider_orders.state = 'purchased'
+         AND excluded.state IN ('purchased', 'refunded', 'cancelled')
+       RETURNING provider_event_id`,
+      record.provider, record.providerOrderId, record.tenant, resolution.nextOrder.state, record.providerEventId, this.now(),
+    );
+    return rows.some((row) => row.provider_event_id === record.providerEventId);
+  }
+}