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

package/apps/storefront/src/lib/apps/apiRoute.ts

@@ -0,0 +1,35 @@
+/**
+ * Response helpers shared by every `/api/apps/v1/*` route (PrivateApps epic,
+ * D3) — a no-store JSON responder (mirrors `../grants/route.ts` /
+ * `./adminService.ts`'s pattern) plus the `tot-request-id` / `traceparent`
+ * response headers `docs/private-apps/contract/openapi.yaml` documents on
+ * every operation.
+ */
+import type { APIContext } from "astro";
+
+/** No-store JSON response — scoped-app API bodies must never be edge/browser-cached. */
+export function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/** The W3C Trace Context shape the contract's `Traceparent` parameter/header pins. */
+const TRACEPARENT_RE = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+
+/**
+ * Stamp a fresh `tot-request-id` on every response, and echo `traceparent`
+ * back ONLY when the request sent a well-formed one — never fabricate a
+ * trace context the caller didn't start. Callers apply this to BOTH success
+ * and error responses (including `authorizeAppRequest`'s), so every response
+ * off a `/api/apps/v1/*` route carries a request id.
+ */
+export function withRequestId(res: Response, context: Pick<APIContext, "request">): Response {
+  res.headers.set("tot-request-id", crypto.randomUUID());
+  const traceparent = context.request.headers.get("traceparent");
+  if (traceparent && TRACEPARENT_RE.test(traceparent)) {
+    res.headers.set("traceparent", traceparent);
+  }
+  return res;
+}

package/apps/storefront/src/lib/apps/catalogMapper.ts

@@ -0,0 +1,39 @@
+/**
+ * Maps the internal `CatalogProduct` read model to the D3 contract's
+ * `Product` shape (`docs/private-apps/contract/openapi.yaml`, schema
+ * `Product` — `additionalProperties: false`). Drops every internal field
+ * the contract doesn't declare (variants, images, metafields, source, …) so
+ * an app only ever sees the minimized public catalog surface.
+ */
+import type { CatalogProduct } from "@tot/public-runtime";
+
+export interface ContractProduct {
+  id: string;
+  handle: string;
+  title: string;
+  status: "active" | "draft" | "archived";
+  vendor?: string;
+  productType?: string;
+  tags?: string[];
+  priceRange: { min: number; max: number; currency: string };
+  updatedAt?: string;
+}
+
+/** Project one `CatalogProduct` into the contract's `Product` — nothing else survives. */
+export function toContractProduct(p: CatalogProduct): ContractProduct {
+  return {
+    id: p.id,
+    handle: p.handle,
+    title: p.title,
+    status: p.status,
+    vendor: p.vendor,
+    productType: p.product_type,
+    tags: p.tags,
+    priceRange: {
+      min: p.price_range.min,
+      max: p.price_range.max,
+      currency: p.price_range.currency,
+    },
+    updatedAt: p.updated_at,
+  };
+}

package/apps/storefront/src/lib/apps/credentials.ts

@@ -0,0 +1,153 @@
+/**
+ * D1-backed `CredentialPort` implementation (PrivateApps epic, D2 Chunk B) —
+ * issues/rotates/clears the OAuth2 client-credentials for an app install, and
+ * verifies a presented `(clientId, secret)` pair for the token endpoint
+ * (`tokenIssuer.ts`).
+ *
+ * Pure over the `Queryable` seam, the same shape `AppRegistryService` and the
+ * catalog read model use (`../d1/catalog.ts`). The secret is NEVER stored in
+ * plaintext — only its sha256 hash, via `@tot/public-runtime`'s `sha256Hex`
+ * (reused, not reinvented — the SAME primitive the customization publish
+ * spine's content-addressing uses). Imported from `@tot/public-runtime`
+ * rather than `@tot/private-controlplane` because this module lives in the
+ * renderer (`src/lib/apps/`), which depcruise's `renderer-no-controlplane-pkg`
+ * fence forbids from ever importing the private control-plane package —
+ * `sha256Hex` carries no control-plane logic, so it lives in the
+ * renderer-safe package instead (see `hash.ts` there). The plaintext secret
+ * is returned exactly once, from `issue`/`rotate`, and never again;
+ * `verifySecret` only ever compares hashes.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+import type { CredentialPort, IssuedCredential } from "./registryService.js";
+import type { Queryable } from "../d1/catalog.js";
+
+/** `IssuedCredential` plus the one-time plaintext secret — never stored, never re-returned. */
+export type IssuedCredentialSecret = IssuedCredential & { secret: string };
+
+/** Thrown when a credential-lifecycle call targets an install with no credential row. */
+export class CredentialError extends Error {
+  constructor(
+    message: string,
+    readonly code: "not_found",
+  ) {
+    super(message);
+    this.name = "CredentialError";
+  }
+}
+
+/** Raw `app_credentials` row shape (snake_case columns). */
+interface CredentialRow {
+  install_id: string;
+  client_id: string;
+  secret_hash: string;
+  secret_created_at: string;
+  rotated_at: string | null;
+  jwks_kid: string;
+}
+
+/** High-entropy secret bytes (256 bits) before base64url encoding. */
+const SECRET_BYTES = 32;
+
+/**
+ * Fixed value hashed on the unknown-clientId path so a DB miss costs about
+ * the same as a wrong-secret hit — no "does this clientId exist" timing
+ * oracle from the miss path skipping the hash entirely.
+ */
+const DUMMY_SECRET_FOR_TIMING = "dummy-secret-for-timing-parity";
+
+function randomSecret(): string {
+  const bytes = new Uint8Array(SECRET_BYTES);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64url");
+}
+
+/**
+ * Constant-time compare of two equal-shape hex digests — hashes are fixed
+ * length, so this avoids a timing oracle on the secret comparison without
+ * needing a dedicated crypto-compare primitive.
+ */
+function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+export class D1CredentialStore implements CredentialPort {
+  constructor(
+    private readonly db: Queryable,
+    /** The `kid` new credentials are stamped with — the currently-active signing key. */
+    private readonly activeJwksKid: string,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  /** Issue a fresh client-credential set for a newly installed app. */
+  async issue(installId: string): Promise<IssuedCredentialSecret> {
+    const clientId = crypto.randomUUID();
+    const secret = randomSecret();
+    const secretHash = await sha256Hex(secret);
+    await this.db.run(
+      `INSERT INTO app_credentials (install_id, client_id, secret_hash, secret_created_at, rotated_at, jwks_kid)
+       VALUES (?,?,?,?,NULL,?)`,
+      installId,
+      clientId,
+      secretHash,
+      this.now(),
+      this.activeJwksKid,
+    );
+    return { installId, clientId, jwksKid: this.activeJwksKid, secret };
+  }
+
+  /**
+   * Rotate the secret for an existing install: same `clientId`, a fresh
+   * secret + hash, `rotated_at` bumped. No grace window — the old secret
+   * stops verifying immediately.
+   */
+  async rotate(installId: string): Promise<IssuedCredentialSecret> {
+    const row = await this.mustFindRow(installId);
+    const secret = randomSecret();
+    const secretHash = await sha256Hex(secret);
+    await this.db.run(
+      `UPDATE app_credentials SET secret_hash = ?, rotated_at = ? WHERE install_id = ?`,
+      secretHash,
+      this.now(),
+      installId,
+    );
+    return { installId, clientId: row.client_id, jwksKid: row.jwks_kid, secret };
+  }
+
+  /** Revoke/clear credential material for an install (uninstall). Idempotent. */
+  async clear(installId: string): Promise<void> {
+    await this.db.run(`DELETE FROM app_credentials WHERE install_id = ?`, installId);
+  }
+
+  /**
+   * Verify a presented `(clientId, secret)`. Returns the owning `installId` on
+   * a match, `null` otherwise — an unknown `clientId` and a wrong `secret`
+   * are indistinguishable to the caller (fail closed, no enumeration oracle).
+   */
+  async verifySecret(clientId: string, presentedSecret: string): Promise<string | null> {
+    const row = await this.db.first<CredentialRow>(
+      `SELECT * FROM app_credentials WHERE client_id = ?`,
+      clientId,
+    );
+    if (!row) {
+      // Unknown clientId: still hash a fixed dummy value so this path takes
+      // about as long as the wrong-secret path below (see DUMMY_SECRET_FOR_TIMING).
+      await sha256Hex(DUMMY_SECRET_FOR_TIMING);
+      return null;
+    }
+    const presentedHash = await sha256Hex(presentedSecret);
+    if (!timingSafeEqualHex(presentedHash, row.secret_hash)) return null;
+    return row.install_id;
+  }
+
+  private async mustFindRow(installId: string): Promise<CredentialRow> {
+    const row = await this.db.first<CredentialRow>(
+      `SELECT * FROM app_credentials WHERE install_id = ?`,
+      installId,
+    );
+    if (!row) throw new CredentialError(`No credential row for install "${installId}".`, "not_found");
+    return row;
+  }
+}

package/apps/storefront/src/lib/apps/gatewayKeys.ts

@@ -0,0 +1,156 @@
+/**
+ * RS256 signing-key loader for the Storefront App Gateway (PrivateApps epic,
+ * D2 Chunk B) — the key that mints and verifies the OAuth2 client-credentials
+ * JWTs a private app presents to the D3 scoped APIs.
+ *
+ * Mirrors `../auth/brokerAssertion.ts`'s `loadSigningKey` caching + `readEnv`
+ * usage EXACTLY, but over a SEPARATE key (`JWT_APP_GATEWAY_PRIVATE_KEY_B64`):
+ * an app must never be able to mint, or verify offline as, a tot20 broker
+ * assertion, and vice versa.
+ *
+ * The private key never leaves this module. `loadGatewayJwks` derives the
+ * PUBLIC JWKS from it — an RSA private key already embeds the public modulus
+ * + exponent, so no separate public-key env var is needed — and explicitly
+ * STRIPS every private field (`d`, `p`, `q`, `dp`, `dq`, `qi`, `oth`) before
+ * returning; that redaction is the one thing this module must never get
+ * wrong. V1 always publishes exactly one active key, but the return shape
+ * (`{ keys: JWK[] }`) is forward-compatible with more (multiple `kid`s) per
+ * `d2-design-resolutions`, so a future rotation-with-overlap doesn't need a
+ * shape change.
+ */
+import { importPKCS8, exportJWK, type CryptoKey, type JWK, type JSONWebKeySet } from "jose";
+import { readEnv } from "@/lib/env";
+
+/** The only algorithm the gateway signs with (verifiers reject anything else). */
+export const APP_GATEWAY_ALG = "RS256";
+
+/** Default key id (overridable via `JWT_APP_GATEWAY_KID`). Names the published key. */
+export const DEFAULT_APP_GATEWAY_KID = "app-gateway-1";
+
+/** Default issuer (overridable via `JWT_APP_GATEWAY_ISSUER`). */
+export const DEFAULT_APP_GATEWAY_ISSUER = "storefront-app-gateway";
+
+/** Access-token lifetime — deliberately short, same TTL as `BROKER_TTL_SECONDS`. */
+export const APP_TOKEN_TTL_SECONDS = 300;
+
+/**
+ * Widget launch-token lifetime (PrivateApps epic, D5 Chunk B) — shorter than
+ * {@link APP_TOKEN_TTL_SECONDS}: this token only needs to survive the SSR
+ * render → iframe-load round trip, never a standing API session.
+ */
+export const WIDGET_LAUNCH_TOKEN_TTL_SECONDS = 120;
+
+/** Env keys the loader reads (server-only). */
+export const APP_GATEWAY_PRIVATE_KEY_ENV = "JWT_APP_GATEWAY_PRIVATE_KEY_B64";
+export const APP_GATEWAY_KID_ENV = "JWT_APP_GATEWAY_KID";
+export const APP_GATEWAY_ISSUER_ENV = "JWT_APP_GATEWAY_ISSUER";
+
+/**
+ * Thrown when the gateway can't load its signing key — the private key env is
+ * absent/malformed. Routes map this to a 503 ("integration not configured")
+ * and FAIL CLOSED: with no key, no token can be minted or verified.
+ */
+export class GatewayKeyError extends Error {}
+
+/** Optional test/DI overrides (avoids touching process env in unit tests). */
+export interface GatewayKeyOverrides {
+  /** base64 of the PKCS8 PEM private key (defaults to the env value). */
+  privateKeyB64?: string;
+  kid?: string;
+  issuer?: string;
+}
+
+export interface GatewaySigningConfig {
+  key: CryptoKey;
+  kid: string;
+  issuer: string;
+}
+
+// Import the signing key once per distinct PEM (importPKCS8 is not free), same
+// cache shape as brokerAssertion.ts's `keyCache`. Keyed on the base64 string so
+// a key rotation (new env value) transparently re-imports and re-derives.
+const signingKeyCache = new Map<string, CryptoKey>();
+const publicJwkCache = new Map<string, JWK>();
+
+async function importPrivateKey(privateKeyB64: string): Promise<CryptoKey> {
+  const cached = signingKeyCache.get(privateKeyB64);
+  if (cached) return cached;
+  let pem: string;
+  try {
+    pem = Buffer.from(privateKeyB64, "base64").toString("utf8");
+  } catch (cause) {
+    throw new GatewayKeyError(
+      `app gateway: ${APP_GATEWAY_PRIVATE_KEY_ENV} is not valid base64 ` +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  if (!/-----BEGIN (RSA )?PRIVATE KEY-----/.test(pem)) {
+    throw new GatewayKeyError(
+      `app gateway: decoded ${APP_GATEWAY_PRIVATE_KEY_ENV} is not a PEM private key`,
+    );
+  }
+  let key: CryptoKey;
+  try {
+    // extractable: true — required so `loadGatewayJwks` below can derive the
+    // public JWK from this same key. The private key itself is still never
+    // exported anywhere outside this module.
+    key = (await importPKCS8(pem, APP_GATEWAY_ALG, { extractable: true })) as CryptoKey;
+  } catch (cause) {
+    throw new GatewayKeyError(
+      `app gateway: failed to import the RS256 private key ` +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  signingKeyCache.set(privateKeyB64, key);
+  return key;
+}
+
+/**
+ * Resolve the active signing config (key + kid + issuer) from env, or
+ * `overrides` in tests. FAILS CLOSED: throws {@link GatewayKeyError} when the
+ * private key env is absent/malformed.
+ */
+export async function loadGatewaySigningConfig(
+  overrides: GatewayKeyOverrides = {},
+): Promise<GatewaySigningConfig> {
+  const privateKeyB64 = overrides.privateKeyB64 ?? (await readEnv(APP_GATEWAY_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new GatewayKeyError(
+      `app gateway: ${APP_GATEWAY_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const kid = overrides.kid ?? (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
+  const issuer =
+    overrides.issuer ?? (await readEnv(APP_GATEWAY_ISSUER_ENV)) ?? DEFAULT_APP_GATEWAY_ISSUER;
+  const key = await importPrivateKey(privateKeyB64);
+  return { key, kid, issuer };
+}
+
+/**
+ * Derive the PUBLIC JWKS for the active key — sanitized (every private RSA
+ * field stripped) and cached by the source private-key base64 (so a rotated
+ * key transparently re-derives, same invalidation as the signing-key cache).
+ * V1 always returns exactly one key; the envelope supports more without a
+ * shape change later.
+ */
+export async function loadGatewayJwks(
+  overrides: GatewayKeyOverrides = {},
+): Promise<JSONWebKeySet> {
+  const privateKeyB64 = overrides.privateKeyB64 ?? (await readEnv(APP_GATEWAY_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new GatewayKeyError(
+      `app gateway: ${APP_GATEWAY_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const { key, kid } = await loadGatewaySigningConfig(overrides);
+  let jwk = publicJwkCache.get(privateKeyB64);
+  if (!jwk) {
+    const full = (await exportJWK(key)) as Record<string, unknown>;
+    // Strip every private RSA field (RFC 7518 §6.3.2) — only the public parts
+    // (kty, n, e) are ever published. This line is the one place that matters.
+    const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, oth: _oth, ...publicOnly } = full;
+    jwk = { ...publicOnly, kid, alg: APP_GATEWAY_ALG, use: "sig" };
+    publicJwkCache.set(privateKeyB64, jwk);
+  }
+  return { keys: [jwk] };
+}

package/apps/storefront/src/lib/apps/healthAggregate.ts

@@ -0,0 +1,66 @@
+/**
+ * Admin Health view aggregation — PrivateApps epic, D8 (Chunk A + D). Folds
+ * one `AppInstall` (`registryService.ts`) and its `InstallHealth` rollup
+ * (`../webhooks/deliveryStore.ts`'s `getInstallHealth`, now including
+ * `p95DeliveryMs`) into the single `AppInstallHealthView` shape the admin
+ * console renders. Deliberately transport-free — no D1/fetch here, so it's
+ * unit-testable with fakes; the caller (the admin health route) owns
+ * fetching the install + health and calling this.
+ *
+ * Data-minimization for the console: `webhookEndpoint` is never surfaced as
+ * a raw URL here, only as `hasWebhookEndpoint` presence — the console shows
+ * "configured or not", not the app's receiver address.
+ *
+ * `runtimeMode` is hardcoded to `"external"` for V1: there is no per-install
+ * runtime-mode column yet (every install today IS an externally-hosted app;
+ * an in-platform runtime mode is a D9+ concern).
+ */
+import { validateWebhookEndpoint } from "../webhooks/endpointGuard.js";
+import type { InstallHealth } from "../webhooks/deliveryStore.js";
+import type { AppInstall, AppInstallStatus, WidgetPlacementInput } from "./registryService.js";
+
+/**
+ * - `no_endpoint` — no `webhookEndpoint` configured at all.
+ * - `blocked` — a configured endpoint now fails the same SSRF guard
+ *   `registryService.ts` enforces at write time (it may have passed then and
+ *   drifted since), OR the health rollup's most recent failure was
+ *   classified `endpoint_blocked`.
+ * - `ok` — otherwise.
+ */
+export type EgressStatus = "ok" | "blocked" | "no_endpoint";
+
+export interface AppInstallHealthView {
+  id: string;
+  appId: string;
+  status: AppInstallStatus;
+  env: string;
+  runtimeMode: "external";
+  scopes: string[];
+  widgetPlacements: WidgetPlacementInput[];
+  hasWebhookEndpoint: boolean;
+  health: InstallHealth;
+  egressStatus: EgressStatus;
+}
+
+function computeEgressStatus(install: AppInstall, health: InstallHealth): EgressStatus {
+  if (!install.webhookEndpoint) return "no_endpoint";
+  const validation = validateWebhookEndpoint(install.webhookEndpoint);
+  if (!validation.ok || health.lastErrorClass === "endpoint_blocked") return "blocked";
+  return "ok";
+}
+
+/** Build the console's `AppInstallHealthView` for one install. Pure — both inputs are already-fetched domain objects. */
+export function buildInstallHealthView(install: AppInstall, health: InstallHealth): AppInstallHealthView {
+  return {
+    id: install.installId,
+    appId: install.appId,
+    status: install.status,
+    env: install.env,
+    runtimeMode: "external",
+    scopes: install.scopes,
+    widgetPlacements: install.widgetPlacements,
+    hasWebhookEndpoint: install.webhookEndpoint != null,
+    health,
+    egressStatus: computeEgressStatus(install, health),
+  };
+}

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

@@ -0,0 +1,206 @@
+/**
+ * App-owned attribution/commission write model — PrivateApps epic, D6
+ * (Chunk C). Owns the `app_attributions` rows `schema.ts` declares: the
+ * ledger `POST /attribution` (`docs/private-apps/contract/openapi.yaml`'s
+ * `writeAttribution`) writes into. Writes only into the app's own
+ * attribution namespace — this service never mutates `orders`, it only
+ * READS the referenced order for the tenant-ownership check the contract
+ * requires ("the referenced `orderId` MUST belong to the calling
+ * tenant/install... rejected with 403, mirroring the cross-tenant read
+ * rule").
+ *
+ * Pure over the `Queryable` seam (see `../../d1/catalog.ts`), same shape
+ * `AppRegistryService`/`OrdersStore` use, so this runs unchanged against
+ * real D1 in the Worker and an in-memory `node:sqlite` in tests.
+ *
+ * `attributionId` is the app's own stable id for the event and is the
+ * table's primary key alongside `installId` — a SECOND write with the same
+ * attributionId is its own idempotency dimension, independent of the
+ * `Idempotency-Key` ledger (`idempotency.ts`) the route layers on top: an
+ * app that resubmits the same event under a fresh Idempotency-Key should
+ * still see it treated as idempotent, so identical content is a stable
+ * no-op replay (returns the row already on record) while differing content
+ * is a conflict — once recorded, an attributionId's content is immutable.
+ */
+import { OrdersStore } from "./ordersStore.js";
+import type { Queryable } from "../../d1/catalog.js";
+
+export interface CommissionInput {
+  amount?: number;
+  currency?: string;
+}
+
+/** A `customerHash` value must be a sha256 hex digest — see `customerHash.ts`. */
+const CUSTOMER_HASH_PATTERN = /^[0-9a-f]{64}$/;
+
+export interface RecordAttributionInput {
+  installId: string;
+  /** The caller's OWN tenant, from JWT claims — never trusted from request input. */
+  tenantId: string;
+  attributionId: string;
+  orderId: string;
+  campaign?: string;
+  referralCode?: string;
+  commission?: CommissionInput;
+  /**
+   * The app's own per-(tenant,install) `customerHash`, as ECHOED BACK from a
+   * prior `GET /orders`/`GET /orders/{id}` read — not a raw identifier. This
+   * service never hashes it: hashing an already-opaque value again would
+   * break the app's ability to correlate this attribution against the order
+   * it read the hash from. Validated as a 64-hex sha256 digest (a raw email
+   * or name fails that check, preserving minimization) and stored AS-IS.
+   */
+  customerHash?: string;
+}
+
+/** The contract's `AttributionRecord` shape — deliberately excludes `customerHash` (never echoed back). */
+export interface AttributionRecord {
+  attributionId: string;
+  orderId: string;
+  campaign?: string;
+  referralCode?: string;
+  commission?: { amount?: number; currency?: string };
+  recordedAt: string;
+}
+
+export type AttributionErrorCode =
+  | "attribution_forbidden"
+  | "attribution_conflict"
+  | "attribution_invalid_customer_hash";
+
+/** Thrown by every rule violation below — callers (the route) branch on `.code`. */
+export class AttributionError extends Error {
+  constructor(
+    message: string,
+    readonly code: AttributionErrorCode,
+  ) {
+    super(message);
+    this.name = "AttributionError";
+  }
+}
+
+/** Raw `app_attributions` row shape (snake_case columns). */
+interface AppAttributionRow {
+  install_id: string;
+  attribution_id: string;
+  tenant_id: string;
+  order_id: string;
+  campaign: string | null;
+  referral_code: string | null;
+  commission_amount: number | null;
+  commission_currency: string | null;
+  customer_hash: string | null;
+  recorded_at: string;
+}
+
+function toRecord(row: AppAttributionRow): AttributionRecord {
+  const hasCommission = row.commission_amount != null || row.commission_currency != null;
+  return {
+    attributionId: row.attribution_id,
+    orderId: row.order_id,
+    ...(row.campaign != null ? { campaign: row.campaign } : {}),
+    ...(row.referral_code != null ? { referralCode: row.referral_code } : {}),
+    ...(hasCommission
+      ? {
+          commission: {
+            ...(row.commission_amount != null ? { amount: row.commission_amount } : {}),
+            ...(row.commission_currency != null ? { currency: row.commission_currency } : {}),
+          },
+        }
+      : {}),
+    recordedAt: row.recorded_at,
+  };
+}
+
+/** True when a fresh write would be byte-for-byte the same content as the stored row (a stable replay, not a conflict). */
+function sameContent(row: AppAttributionRow, input: RecordAttributionInput, hashedCustomer: string | null): boolean {
+  return (
+    row.order_id === input.orderId &&
+    (row.campaign ?? undefined) === input.campaign &&
+    (row.referral_code ?? undefined) === input.referralCode &&
+    (row.commission_amount ?? undefined) === input.commission?.amount &&
+    (row.commission_currency ?? undefined) === input.commission?.currency &&
+    row.customer_hash === hashedCustomer
+  );
+}
+
+export class AppAttributionService {
+  constructor(
+    private readonly db: Queryable,
+    private readonly orders: OrdersStore = new OrdersStore(db),
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  /**
+   * Record one attribution event. Enforces the D1-contract ownership rule
+   * BEFORE any write: `orderId` must resolve to an order owned by the
+   * caller's OWN tenant, or this throws `attribution_forbidden` — a foreign
+   * order and a nonexistent order get the SAME treatment (no oracle), so a
+   * caller can't fish for which orderIds exist on other tenants.
+   *
+   * A repeat `attributionId` for this install is checked AFTER the
+   * ownership gate: identical content is returned as-is (idempotent
+   * no-op); any difference is `attribution_conflict`.
+   */
+  async record(input: RecordAttributionInput): Promise<AttributionRecord> {
+    const order = await this.orders.getByExternalId(input.orderId);
+    if (!order || order.tenantId !== input.tenantId) {
+      throw new AttributionError(`orderId does not belong to this tenant/install.`, "attribution_forbidden");
+    }
+
+    if (input.customerHash !== undefined && !CUSTOMER_HASH_PATTERN.test(input.customerHash)) {
+      throw new AttributionError(
+        `customerHash, when given, must be the 64-character hex customerHash echoed back from a prior order read — not a raw customer identifier.`,
+        "attribution_invalid_customer_hash",
+      );
+    }
+    const hashedCustomer = input.customerHash ?? null;
+
+    const existing = await this.db.first<AppAttributionRow>(
+      `SELECT * FROM app_attributions WHERE install_id = ? AND attribution_id = ?`,
+      input.installId,
+      input.attributionId,
+    );
+    if (existing) {
+      if (!sameContent(existing, input, hashedCustomer)) {
+        throw new AttributionError(
+          `attributionId "${input.attributionId}" was already recorded with different content.`,
+          "attribution_conflict",
+        );
+      }
+      return toRecord(existing);
+    }
+
+    const recordedAt = this.now();
+    const row: AppAttributionRow = {
+      install_id: input.installId,
+      attribution_id: input.attributionId,
+      tenant_id: input.tenantId,
+      order_id: input.orderId,
+      campaign: input.campaign ?? null,
+      referral_code: input.referralCode ?? null,
+      commission_amount: input.commission?.amount ?? null,
+      commission_currency: input.commission?.currency ?? null,
+      customer_hash: hashedCustomer,
+      recorded_at: recordedAt,
+    };
+    await this.db.run(
+      `INSERT INTO app_attributions
+         (install_id, attribution_id, tenant_id, order_id, campaign, referral_code,
+          commission_amount, commission_currency, customer_hash, recorded_at)
+       VALUES (?,?,?,?,?,?,?,?,?,?)`,
+      row.install_id,
+      row.attribution_id,
+      row.tenant_id,
+      row.order_id,
+      row.campaign,
+      row.referral_code,
+      row.commission_amount,
+      row.commission_currency,
+      row.customer_hash,
+      row.recorded_at,
+    );
+
+    return toRecord(row);
+  }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Opaque customer hash — PrivateApps epic, D6 (Chunk A). The `customerHash`
+ * every order/attribution surface exposes instead of a raw customer id (see
+ * `docs/private-apps/api-event-reference.md`'s PII-minimization matrix and
+ * `contract/openapi.yaml`'s `Order.customerHash`).
+ *
+ * Stable per **(tenant, app-install)**: the same customer always resolves to
+ * the same hash within one install, so an app stays internally consistent
+ * across its own `order.created`/`order.fulfilled`/`attribution.finalized`
+ * events. Deliberately NOT comparable across installs on the same tenant
+ * (each install's hash is salted by its own `installId`) — two apps must
+ * never be able to correlate the same customer against each other.
+ *
+ * Reuses `@tot/public-runtime`'s `sha256Hex` (Web Crypto, no `node:*`) rather
+ * than a new hash primitive — same primitive `apps/credentials.ts` uses for
+ * client-secret hashing.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+
+/**
+ * Hash a raw (tenant-scoped) customer identifier into the opaque, per-install
+ * `customerHash` the contract exposes. One-way — never reversible to the raw
+ * `rawCustomerId`, and never logged/stored anywhere in its raw form by this
+ * module's callers.
+ */
+export function customerHash(tenantId: string, installId: string, rawCustomerId: string): Promise<string> {
+  return sha256Hex(`${tenantId}:${installId}:${rawCustomerId}`);
+}