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

package/packages/public-runtime/src/integration/correlation-token.ts

@@ -0,0 +1,444 @@
+/**
+ * The signed, opaque checkout-correlation token (ADR 0022 `receipt-consent-propagation`,
+ * ADR 0023 Q3 `resolve-gate-legal-q3-correlation-token` = analytics-consent-required;
+ * ext-commerce-03). It is the ONE cross-site attribution handle that survives the
+ * managed-checkout handoff: minted by the storefront at `checkout.handoff`, carried
+ * through the provider (Foxy) as a never-signed passthrough cart field, echoed back on
+ * the verified order webhook, and verified server-side by the order join
+ * (ext-commerce-04) to thread a browser handoff to its authoritative conversion.
+ *
+ * It is a CORRELATION HANDLE, never a capability:
+ *   - It binds exactly `{ v, tenant, env, eventId, iat, exp, jti }` and NOTHING else —
+ *     no scope, role, price, permission, or action. Verifying it authorizes nothing;
+ *     it only asserts "this handoff, in this tenant/environment, is still within its
+ *     bounded lifetime." Downstream code decides what to do with a verified thread.
+ *   - It carries NO PII and NO secret: `tenant`/`env` are public execution-context
+ *     facts (already in the host/URL), `eventId`/`jti` are opaque random-ish handles,
+ *     and the timestamps are integers. No email, name, address, identity result, cart
+ *     secret, or signing secret ever enters it.
+ *   - Its integrity is an HMAC-SHA256 over the SERVER-ONLY correlation secret. That
+ *     secret is an env-injected Worker binding resolved per request (like the cart
+ *     secret, and DISTINCT from it — key separation), passed in explicitly here and
+ *     never read from a global, never serialized, never shipped to the browser.
+ *
+ * Consent gate (ADR 0023 Q3): the token is carried through the handoff ONLY when the
+ * shopper is analytics-eligible ({@link isPurposeEligible} for `analytics`). When not
+ * eligible the token is DROPPED — the handoff proceeds without the correlation field
+ * and the eventual order is explicitly UNATTRIBUTED. The correlation is never smuggled
+ * past a withheld analytics consent (see {@link correlationForHandoff}).
+ *
+ * Wire format, provider limits, and canonical encoding:
+ * `docs/architecture/commerce-correlation-token.md`.
+ */
+import type { IntegrationEnvironment } from "./environment.js";
+import { INTEGRATION_ENVIRONMENTS } from "./environment.js";
+import type { EventCorrelation } from "./events.js";
+import type { ConsentSnapshot } from "./consent-broker.js";
+import { isPurposeEligible } from "./consent-broker.js";
+import type { ConsentPurpose } from "../integration-capabilities.js";
+
+/** The token version tag; an unknown version fails closed on verify. */
+export const CORRELATION_TOKEN_VERSION = 1 as const;
+
+/** The consent purpose the cross-site correlation carry requires (ADR 0023 Q3). */
+export const CORRELATION_CONSENT_PURPOSE: ConsentPurpose = "analytics";
+
+/**
+ * Default bounded lifetime: the window a shopper has to complete the hosted checkout
+ * so the order webhook still joins to the handoff. One hour comfortably spans a normal
+ * checkout while keeping the replay surface small; callers may override per surface.
+ */
+export const DEFAULT_CORRELATION_TTL_SECONDS = 60 * 60;
+
+/**
+ * The never-signed passthrough cart field the token rides in through the provider.
+ * The `h:` prefix marks a Foxy hidden/custom field that is passed to the transaction
+ * verbatim and is NOT part of the cart HMAC (`checkout.ts` never signs `h:`/`x:`/
+ * `__`/`utm_` params), so carrying the token needs no cart secret and cannot perturb
+ * price signing. It surfaces on the verified order webhook for the order join to read.
+ */
+export const CORRELATION_CART_FIELD_NAME = "h:tot_correlation";
+
+/**
+ * The provider-safe upper bound on the encoded token length. The token is well under
+ * this (~160 chars) for the fixed claim set; the bound is a conservative guard against
+ * a provider truncating an over-long custom field value. Minting asserts it.
+ */
+export const MAX_CORRELATION_TOKEN_LENGTH = 512;
+
+/** The exact wire charset: two base64url segments joined by a single `.` — URL/form safe, no padding. */
+export const CORRELATION_TOKEN_PATTERN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+/**
+ * The complete, closed set of bound claims — the ONLY thing the token asserts. Adding a
+ * field here is a deliberate contract change; a verifier rejects any decoded payload
+ * with an unknown key so the claim set can never silently grow.
+ */
+export interface CorrelationTokenClaims {
+  /** Contract version; a token whose `v` this build does not know fails closed. */
+  v: typeof CORRELATION_TOKEN_VERSION;
+  /** The tenant the handoff ran in — a public execution-context fact, never caller-set. */
+  tenant: string;
+  /** The stage the handoff ran in; a candidate/staged token can never satisfy a `live` verify. */
+  env: IntegrationEnvironment;
+  /** The opaque logical correlation/handoff event id the order join threads to. */
+  eventId: string;
+  /** Issued-at, Unix seconds. */
+  iat: number;
+  /** Expiry, Unix seconds. After this the token is dead — join yields an unattributed order. */
+  exp: number;
+  /** A unique per-mint nonce; the single-use key a replay guard consumes. */
+  jti: string;
+}
+
+const CLAIM_KEYS: readonly (keyof CorrelationTokenClaims)[] = [
+  "v",
+  "tenant",
+  "env",
+  "eventId",
+  "iat",
+  "exp",
+  "jti",
+];
+
+export interface MintCorrelationTokenInput {
+  /** The tenant, from trusted server execution context — never a caller-supplied value. */
+  tenant: string;
+  /** The stage, from trusted server execution context. */
+  environment: IntegrationEnvironment;
+  /** The logical correlation/handoff event id this token threads. */
+  eventId: string;
+  /** Bounded lifetime; defaults to {@link DEFAULT_CORRELATION_TTL_SECONDS}. */
+  ttlSeconds?: number;
+  /** Injectable wall clock in ms (defaults to `Date.now()`) for deterministic tests. */
+  now?: number;
+}
+
+export interface MintedCorrelationToken {
+  /** The opaque wire token: `<base64url(payload)>.<base64url(hmac)>`. */
+  token: string;
+  /** The bound claims, so the caller can build the event envelope's correlation. */
+  claims: CorrelationTokenClaims;
+}
+
+/** The tenant/environment a verify is performed against, from trusted server context. */
+export interface CorrelationVerifyContext {
+  tenant: string;
+  environment: IntegrationEnvironment;
+  /** Injectable wall clock in ms (defaults to `Date.now()`) for deterministic tests. */
+  now?: number;
+}
+
+/** Why a token was not accepted. Every path is a returned reason, never a thrown error. */
+export type CorrelationRejectReason =
+  /** No token was echoed back (provider dropped it, or the shopper was unattributed). */
+  | "missing"
+  /** The token is not two base64url segments, or its payload is not the closed claim shape. */
+  | "malformed"
+  /** The HMAC does not verify — the token (or its payload) was tampered with. */
+  | "bad_signature"
+  /** A valid token minted for a different tenant or environment (cross-tenant/stage). */
+  | "context_mismatch"
+  /** The token is past its `exp`. */
+  | "expired"
+  /** A structurally valid, in-context, unexpired token whose `jti` was already consumed. */
+  | "replay";
+
+export type CorrelationVerifyResult =
+  | { ok: true; claims: CorrelationTokenClaims }
+  | { ok: false; reason: CorrelationRejectReason };
+
+// --- encoding -------------------------------------------------------------------
+
+function b64urlEncodeBytes(bytes: ArrayBuffer | Uint8Array): string {
+  return Buffer.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)).toString("base64url");
+}
+
+function b64urlEncodeUtf8(text: string): string {
+  return Buffer.from(text, "utf8").toString("base64url");
+}
+
+/** Decode a base64url segment to UTF-8, or `null` if it is not clean base64url. */
+function b64urlDecodeUtf8(segment: string): string | null {
+  try {
+    const buf = Buffer.from(segment, "base64url");
+    // Reject non-canonical input: re-encoding must reproduce the exact segment.
+    if (buf.toString("base64url") !== segment) return null;
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function importHmacKey(secret: string, usage: "sign" | "verify"): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+/** A compact 96-bit random single-use nonce as lowercase hex. */
+function randomJti(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// --- mint -----------------------------------------------------------------------
+
+/**
+ * Mint a signed correlation token. The `secret` is the server-only correlation-signing
+ * key, injected by the caller from its Worker binding; it is used to sign and then
+ * discarded — it never enters the token, the claims, or any serialized surface.
+ */
+export async function mintCorrelationToken(
+  input: MintCorrelationTokenInput,
+  secret: string,
+): Promise<MintedCorrelationToken> {
+  const nowMs = input.now ?? Date.now();
+  const iat = Math.floor(nowMs / 1000);
+  const ttl = input.ttlSeconds ?? DEFAULT_CORRELATION_TTL_SECONDS;
+  const claims: CorrelationTokenClaims = {
+    v: CORRELATION_TOKEN_VERSION,
+    tenant: input.tenant,
+    env: input.environment,
+    eventId: input.eventId,
+    iat,
+    exp: iat + ttl,
+    jti: randomJti(),
+  };
+
+  const payloadB64 = b64urlEncodeUtf8(canonicalClaims(claims));
+  const key = await importHmacKey(secret, "sign");
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payloadB64) as unknown as BufferSource,
+  );
+  const token = `${payloadB64}.${b64urlEncodeBytes(sig)}`;
+
+  if (token.length > MAX_CORRELATION_TOKEN_LENGTH) {
+    throw new Error(
+      `correlation token length ${token.length} exceeds provider-safe limit ${MAX_CORRELATION_TOKEN_LENGTH}`,
+    );
+  }
+  return { token, claims };
+}
+
+/**
+ * Canonical, fixed-order serialization of the claims — the exact bytes both mint and
+ * the payload decode agree on. Fixed key order (not input order) so an equal claim set
+ * always yields byte-identical output; `JSON.stringify` escapes any delimiter inside a
+ * value, so no field can be smuggled across the claim boundary.
+ */
+function canonicalClaims(claims: CorrelationTokenClaims): string {
+  return JSON.stringify({
+    v: claims.v,
+    tenant: claims.tenant,
+    env: claims.env,
+    eventId: claims.eventId,
+    iat: claims.iat,
+    exp: claims.exp,
+    jti: claims.jti,
+  });
+}
+
+// --- verify ---------------------------------------------------------------------
+
+/**
+ * Verify a token's signature, tenant/environment binding, and expiry against trusted
+ * context. This is the PURE verify — it does not consume single-use state; layer
+ * {@link verifyCorrelationTokenOnce} over it for replay defense. A `null`/`undefined`/
+ * empty token (a missing provider echo) is the explicit `missing` reason, never a throw.
+ */
+export async function verifyCorrelationToken(
+  token: string | null | undefined,
+  ctx: CorrelationVerifyContext,
+  secret: string,
+): Promise<CorrelationVerifyResult> {
+  if (typeof token !== "string" || token.length === 0) {
+    return { ok: false, reason: "missing" };
+  }
+  if (token.length > MAX_CORRELATION_TOKEN_LENGTH || !CORRELATION_TOKEN_PATTERN.test(token)) {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const [payloadB64, sigB64] = token.split(".") as [string, string];
+
+  const key = await importHmacKey(secret, "verify");
+  let sigBytes: Buffer;
+  try {
+    sigBytes = Buffer.from(sigB64, "base64url");
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    sigBytes as unknown as BufferSource,
+    new TextEncoder().encode(payloadB64) as unknown as BufferSource,
+  );
+  if (!valid) return { ok: false, reason: "bad_signature" };
+
+  const claims = decodeClaims(payloadB64);
+  if (!claims) return { ok: false, reason: "malformed" };
+
+  if (claims.tenant !== ctx.tenant || claims.env !== ctx.environment) {
+    return { ok: false, reason: "context_mismatch" };
+  }
+
+  const nowSec = Math.floor((ctx.now ?? Date.now()) / 1000);
+  if (nowSec >= claims.exp) return { ok: false, reason: "expired" };
+
+  return { ok: true, claims };
+}
+
+/** A pluggable single-use store. The durable KV/DO store is injected by the consumer. */
+export interface CorrelationReplayGuard {
+  /** True if this `jti` was already consumed. */
+  seen(jti: string): boolean | Promise<boolean>;
+  /** Record `jti` as consumed until `expiresAtSec` (so the store can prune it later). */
+  remember(jti: string, expiresAtSec: number): void | Promise<void>;
+}
+
+/**
+ * Verify AND consume a token exactly once. On a fully valid token whose `jti` the guard
+ * has not seen, it records the `jti` and returns the claims; a second presentation of
+ * the same token is rejected `replay`. Signature/context/expiry rejections never consume
+ * the guard. This is the order-join-facing entry point.
+ */
+export async function verifyCorrelationTokenOnce(
+  token: string | null | undefined,
+  ctx: CorrelationVerifyContext,
+  secret: string,
+  guard: CorrelationReplayGuard,
+): Promise<CorrelationVerifyResult> {
+  const base = await verifyCorrelationToken(token, ctx, secret);
+  if (!base.ok) return base;
+  if (await guard.seen(base.claims.jti)) return { ok: false, reason: "replay" };
+  await guard.remember(base.claims.jti, base.claims.exp);
+  return base;
+}
+
+/** Decode a base64url payload to the closed claim shape, or `null` if it is not exactly that. */
+function decodeClaims(payloadB64: string): CorrelationTokenClaims | null {
+  const json = b64urlDecodeUtf8(payloadB64);
+  if (json === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const obj = parsed as Record<string, unknown>;
+
+  for (const key of Object.keys(obj)) {
+    if (!(CLAIM_KEYS as readonly string[]).includes(key)) return null;
+  }
+  if (obj.v !== CORRELATION_TOKEN_VERSION) return null;
+  if (typeof obj.tenant !== "string" || obj.tenant.length === 0) return null;
+  if (typeof obj.env !== "string" || !(INTEGRATION_ENVIRONMENTS as readonly string[]).includes(obj.env)) {
+    return null;
+  }
+  if (typeof obj.eventId !== "string" || obj.eventId.length === 0) return null;
+  if (!Number.isSafeInteger(obj.iat) || !Number.isSafeInteger(obj.exp)) return null;
+  if (typeof obj.jti !== "string" || obj.jti.length === 0) return null;
+
+  return {
+    v: CORRELATION_TOKEN_VERSION,
+    tenant: obj.tenant,
+    env: obj.env as IntegrationEnvironment,
+    eventId: obj.eventId,
+    iat: obj.iat as number,
+    exp: obj.exp as number,
+    jti: obj.jti,
+  };
+}
+
+// --- handoff carry (ADR 0023 Q3 gate) -------------------------------------------
+
+/**
+ * The correlation outcome for one checkout handoff. `attributed: true` carries the
+ * token to put on the provider cart field and the matching {@link EventCorrelation}
+ * for the event envelope; `attributed: false` means the shopper is not analytics-
+ * eligible, so NO token is carried and the resulting order is explicitly unattributed.
+ */
+export type HandoffCorrelation =
+  | {
+      attributed: true;
+      token: string;
+      /** The cross-site carrier field: put `{ name, value }` on the provider cart. */
+      cartField: { name: string; value: string };
+      /** The event-envelope correlation thread (`id` === bound `eventId`). */
+      correlation: EventCorrelation;
+      claims: CorrelationTokenClaims;
+    }
+  | { attributed: false; reason: "analytics-consent-required" };
+
+/**
+ * Resolve the correlation carry for a checkout handoff under ADR 0023 Q3. Mints and
+ * returns the token ONLY when the consent snapshot is analytics-eligible; otherwise it
+ * returns `attributed: false` and the handoff must proceed WITHOUT the correlation
+ * field — the order is unattributed, never covertly correlated.
+ */
+export async function correlationForHandoff(
+  input: MintCorrelationTokenInput,
+  snapshot: ConsentSnapshot,
+  secret: string,
+): Promise<HandoffCorrelation> {
+  if (!isPurposeEligible(snapshot, CORRELATION_CONSENT_PURPOSE)) {
+    return { attributed: false, reason: "analytics-consent-required" };
+  }
+  const { token, claims } = await mintCorrelationToken(input, secret);
+  return {
+    attributed: true,
+    token,
+    cartField: { name: CORRELATION_CART_FIELD_NAME, value: token },
+    correlation: { id: claims.eventId, expiresAt: new Date(claims.exp * 1000).toISOString() },
+    claims,
+  };
+}
+
+/**
+ * Read the correlation token a provider echoed back on the verified order webhook. The
+ * provider carries the {@link CORRELATION_CART_FIELD_NAME} field verbatim; an absent or
+ * non-string value yields `undefined`, which {@link verifyCorrelationToken} treats as
+ * the explicit `missing` (unattributed) outcome.
+ */
+export function readEchoedCorrelation(
+  fields: Record<string, unknown> | null | undefined,
+): string | undefined {
+  if (!fields) return undefined;
+  const raw = fields[CORRELATION_CART_FIELD_NAME];
+  return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+
+/**
+ * A simple in-memory single-use store for local dev and tests. Production supplies a
+ * durable KV/Durable-Object-backed {@link CorrelationReplayGuard}; this one prunes
+ * expired `jti`s lazily on each `seen` so it does not grow unbounded in a long process.
+ */
+export class InMemoryCorrelationReplayGuard implements CorrelationReplayGuard {
+  private readonly consumed = new Map<string, number>();
+
+  constructor(private readonly nowSec: () => number = () => Math.floor(Date.now() / 1000)) {}
+
+  seen(jti: string): boolean {
+    this.prune();
+    return this.consumed.has(jti);
+  }
+
+  remember(jti: string, expiresAtSec: number): void {
+    this.consumed.set(jti, expiresAtSec);
+  }
+
+  private prune(): void {
+    const now = this.nowSec();
+    for (const [jti, exp] of this.consumed) {
+      if (now >= exp) this.consumed.delete(jti);
+    }
+  }
+}