@tokenoftrust/storefront-runner 6.5.0 → 6.5.2

package/apps/storefront/src/lib/integrations/webhooks/deliveryStore.ts

@@ -40,6 +40,8 @@
  * read-after-write discipline `AppRegistryService` uses.
  */
 import type { Queryable } from "../../catalog/d1/catalog.js";
+import { TOPIC_REQUIRED_SCOPE } from "./events.js";
+import { COMMERCE_TOPICS, commercePayloadAdmissible, type CommerceTopic } from "./commercePayloads.js";
 
 /** Mirrors the `Delivery.topic` / CloudEvents channel enum in the D1/D2 contract. */
 export type WebhookTopic =
@@ -668,6 +670,134 @@ export class WebhookDeliveryStore {
   }
 }
 
+/** A commerce delivery enqueued after its commit becomes the tenant commerce alarm's only after this long. */
+export const COMMERCE_DELIVERY_GRACE_MS = 60_000;
+
+/** `asyncapi.yaml`'s `dataschemaversion` for V1. */
+export const COMMERCE_DATASCHEMA_VERSION = "1";
+
+/** Thrown before any statement is built when a commerce payload fails its topic's closed schema. */
+export class CommercePayloadRefused extends Error {
+  constructor(readonly topic: CommerceTopic) {
+    super("commerce-payload-refused");
+    this.name = "CommercePayloadRefused";
+  }
+}
+
+export interface CommerceEventStatement {
+  sql: string;
+  params: unknown[];
+}
+
+/** SQL condition an eligible install row `i` satisfies; binds the tenant id, then the topic's required scope. */
+const ELIGIBLE_INSTALL_CONDITION = `i.tenant_id = ? AND i.status = 'active' AND i.managed_kind IS NULL
+    AND COALESCE(i.webhook_endpoint, '') != ''
+    AND EXISTS (SELECT 1 FROM json_each(i.scopes) WHERE json_each.value = ?)`;
+
+/** Installs on `tenantId` that would receive `topic` now, oldest first. Statements re-check this at write. */
+export function commerceTargetsQuery(tenantId: string, topic: CommerceTopic): CommerceEventStatement {
+  return {
+    sql: `SELECT i.install_id AS install_id FROM app_installs AS i
+      WHERE ${ELIGIBLE_INSTALL_CONDITION}
+      ORDER BY i.created_at ASC, i.install_id ASC`,
+    params: [tenantId, TOPIC_REQUIRED_SCOPE[topic]],
+  };
+}
+
+/**
+ * The single commerce emitter: one `webhook_events` row written only when `gate` holds, and one
+ * pending `webhook_deliveries` row per target written only when that event row exists and the
+ * target install is still eligible. Ids are minted by the caller so the statements run inside the
+ * batch of the change they report; the delivery id is the CloudEvents `id`.
+ */
+export function commerceEventStatements(input: {
+  eventId: string;
+  tenantId: string;
+  topic: CommerceTopic;
+  payload: unknown;
+  gate: CommerceEventStatement;
+  targets: readonly { installId: string; deliveryId: string }[];
+  now: string;
+}): CommerceEventStatement[] {
+  if (!commercePayloadAdmissible(input.topic, input.payload)) throw new CommercePayloadRefused(input.topic);
+  const statements: CommerceEventStatement[] = [
+    {
+      sql: `INSERT INTO webhook_events (id, tenant_id, topic, dataschema_version, payload, created_at)
+        SELECT ?, ?, ?, ?, ?, ? WHERE (${input.gate.sql})`,
+      params: [
+        input.eventId,
+        input.tenantId,
+        input.topic,
+        COMMERCE_DATASCHEMA_VERSION,
+        JSON.stringify(input.payload),
+        input.now,
+        ...input.gate.params,
+      ],
+    },
+  ];
+  for (const target of input.targets) {
+    statements.push({
+      sql: `INSERT INTO webhook_deliveries
+          (delivery_id, event_id, install_id, tenant_id, topic, state, attempts, created_at, updated_at)
+        SELECT ?, ?, i.install_id, i.tenant_id, ?, 'pending', 0, ?, ?
+        FROM app_installs AS i
+        WHERE i.install_id = ? AND ${ELIGIBLE_INSTALL_CONDITION}
+          AND EXISTS (SELECT 1 FROM webhook_events WHERE id = ? AND tenant_id = ? AND topic = ?)`,
+      params: [
+        target.deliveryId,
+        input.eventId,
+        input.topic,
+        input.now,
+        input.now,
+        target.installId,
+        input.tenantId,
+        TOPIC_REQUIRED_SCOPE[input.topic],
+        input.eventId,
+        input.tenantId,
+        input.topic,
+      ],
+    });
+  }
+  return statements;
+}
+
+/**
+ * Commerce-topic deliveries for one tenant that the alarm owns: `pending` rows older than the
+ * enqueue grace, and `retrying` rows whose next attempt is due.
+ */
+export async function dueCommerceDeliveries(
+  db: Queryable,
+  tenantId: string,
+  now: string,
+  graceMs: number,
+): Promise<{ due: string[]; nextAt: string | null }> {
+  const cutoff = new Date(Date.parse(now) - graceMs).toISOString();
+  const topics = [...COMMERCE_TOPICS];
+  const marks = topics.map(() => "?").join(",");
+  const rows = await db.all<{ delivery_id: string }>(
+    `SELECT delivery_id FROM webhook_deliveries
+      WHERE tenant_id = ? AND topic IN (${marks})
+        AND ((state = 'pending' AND created_at <= ?) OR (state = 'retrying' AND next_attempt_at <= ?))
+      ORDER BY created_at ASC, delivery_id ASC LIMIT 100`,
+    tenantId,
+    ...topics,
+    cutoff,
+    now,
+  );
+  const next = await db.first<{ next_at: string | null }>(
+    `SELECT MIN(CASE WHEN state = 'pending' THEN strftime('%Y-%m-%dT%H:%M:%fZ', created_at, ?) ELSE next_attempt_at END) AS next_at
+       FROM webhook_deliveries
+      WHERE tenant_id = ? AND topic IN (${marks})
+        AND ((state = 'pending' AND created_at > ?) OR (state = 'retrying' AND next_attempt_at > ?))`,
+    `+${graceMs / 1000} seconds`,
+    tenantId,
+    ...topics,
+    cutoff,
+    now,
+  );
+  return { due: rows.map((row) => row.delivery_id), nextAt: next?.next_at ?? null };
+}
+
 export interface CommerceOutboxDue {
   order_id: string;
   outbox_id: string;

package/apps/storefront/src/lib/integrations/webhooks/dispatcher.ts

@@ -57,7 +57,7 @@ export interface WebhookDispatcher {
 export type AttemptOutcome =
   | { kind: "delivered" }
   | { kind: "retrying"; nextAttemptAt: string }
-  | { kind: "dead-lettered"; reason: "install_unavailable" | "max_attempts" | "endpoint_blocked" };
+  | { kind: "dead-lettered"; reason: "install_unavailable" | "max_attempts" | "endpoint_blocked" | "payload_refused" };
 
 /** One attempt of one delivery. Implemented by `deliveryEngine.ts`'s `attemptDelivery`, partially applied over its deps. */
 export type AttemptDeliveryFn = (deliveryId: string) => Promise<AttemptOutcome>;

package/apps/storefront/src/lib/integrations/webhooks/getDispatcher.ts

@@ -29,6 +29,13 @@ import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
 /** Binding name `getDispatcher()` checks to pick the Cloudflare Queues adapter. Not yet declared in `wrangler.toml`. */
 export const WEBHOOK_QUEUE_BINDING = "WEBHOOK_DELIVERY_QUEUE";
 
+/** The `attemptDelivery` composition every dispatcher and the commerce alarm run per delivery id. */
+export function deliveryAttemptFor(db: Queryable, activeKid: string = DEFAULT_APP_GATEWAY_KID): AttemptDeliveryFn {
+  const store = new WebhookDeliveryStore(db);
+  const registry = new AppRegistryService(db, new D1CredentialStore(db, activeKid));
+  return (deliveryId) => attemptDelivery(deliveryId, { store, registry });
+}
+
 /**
  * Build a `WebhookDispatcher` over the real `STOREFRONT_APPS_DB` binding, or
  * return a 503 `Response` when that binding isn't configured in this
@@ -39,10 +46,8 @@ export async function getDispatcher(): Promise<WebhookDispatcher | Response> {
   if (!d1) return json({ error: "webhook dispatcher not configured" }, 503);
   const db = fromD1(d1);
 
-  const store = new WebhookDeliveryStore(db);
   const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
-  const registry = new AppRegistryService(db, new D1CredentialStore(db, activeKid));
-  const attempt: AttemptDeliveryFn = (deliveryId) => attemptDelivery(deliveryId, { store, registry });
+  const attempt = deliveryAttemptFor(db, activeKid);
 
   const queueSender = (await readQueue(WEBHOOK_QUEUE_BINDING)) as CloudflareQueueSender | undefined;
   if (queueSender) return new CloudflareQueueDispatcher(queueSender);

package/apps/storefront/src/lib/integrations/webhooks/orderFulfilledClaim.ts

@@ -0,0 +1,75 @@
+/**
+ * `order.fulfilled` is claimed once per order across its two producers: the fulfillment handoff
+ * and the order-forward receiver. The claim is keyed (tenant, stage, source, source order id,
+ * topic); each producer writes its claim and its gated event rows in one batch, and only the
+ * producer whose claim carries its event id writes the event.
+ */
+import type { CommerceStage } from "@tot/public-runtime";
+import type { CommerceEventStatement } from "./deliveryStore.js";
+
+export interface OrderFulfilledClaimKey {
+  tenantId: string;
+  stage: CommerceStage;
+  source: string;
+  sourceOrderId: string;
+}
+
+/** The forward contract's `env` mapped to a commerce stage; any other value claims and emits nothing. */
+export function forwardStage(env: string): CommerceStage | null {
+  if (env === "production") return "publication";
+  if (env === "sandbox") return "preview";
+  return null;
+}
+
+/** The handoff's claim: written only when no claim exists and `gate` holds (the handoff's CAS committed). */
+export function handoffClaimStatement(
+  key: OrderFulfilledClaimKey,
+  eventId: string,
+  now: string,
+  gate: CommerceEventStatement,
+): CommerceEventStatement {
+  return {
+    sql: `INSERT INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      SELECT ?, ?, ?, ?, 'order.fulfilled', ?, 'handoff', ?
+      WHERE NOT EXISTS (
+          SELECT 1 FROM commerce_event_claims
+          WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+        ) AND (${gate.sql})`,
+    params: [
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      eventId,
+      now,
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      ...gate.params,
+    ],
+  };
+}
+
+/** The forward receiver's claim. */
+export function forwardClaimStatement(key: OrderFulfilledClaimKey, eventId: string, now: string): CommerceEventStatement {
+  return {
+    sql: `INSERT OR IGNORE INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      VALUES (?, ?, ?, ?, 'order.fulfilled', ?, 'forward', ?)`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId, now],
+  };
+}
+
+/** Event gate: the claim for `key` carries `eventId`. */
+export function claimedByEventGate(key: OrderFulfilledClaimKey, eventId: string): CommerceEventStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM commerce_event_claims
+        WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+          AND event_id = ?
+      )`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId],
+  };
+}

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

@@ -21,6 +21,11 @@
  *     corresponding topic — e.g. -> `cancelled`, which V1 has no topic for)
  *     -> no emit; the row still updates, silently.
  *
+ * `order.fulfilled` is claimed once per order (`orderFulfilledClaim.ts`) under the key the signed
+ * intake and the fulfillment handoff use: (tenant, stage from `env`, `foxycart`, external order id).
+ * The claim, the event and its deliveries commit in one batch; a forward whose order is already
+ * claimed writes nothing, and an `env` other than production or sandbox emits no `order.fulfilled`.
+ *
  * Customer identity: `rawCustomerId` is optional (tot-foxycart's own
  * order-forward payload doesn't always carry one — mirrors `FoxyOrder`'s
  * own optional `customerEmail`). This receiver never derives, stores, or
@@ -36,7 +41,8 @@ import { SourceAuthorityStore } from "./sourceAuthorityStore.js";
 import { SourceAuthorityError, parseSourceWire, exactKeys, digestJson, type BeginAck, type ResultAck, type AuthorityCode, isRecord, isSourceId } from "./sourceAuthorityContract.js";
 import { OrdersStore, ScrappyOrderLedger, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
 import { emitWebhookEvent } from "../../integrations/webhooks/emit.js";
-import type { WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { commerceEventStatements, commerceTargetsQuery, type WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { claimedByEventGate, forwardClaimStatement, forwardStage, type OrderFulfilledClaimKey } from "../../integrations/webhooks/orderFulfilledClaim.js";
 import type { Queryable } from "../../catalog/d1/catalog.js";
 import {
   createLocalJWKSet,
@@ -125,7 +131,11 @@ function topicsFor(previousStatus: OrderStatus | null, status: OrderStatus): Web
  * verified the request's HMAC signature — this function never re-checks
  * authenticity and must never be reached from an unverified request.
  */
-export async function receiveForwardedOrder(db: Queryable, input: OrderForwardInput): Promise<OrderForwardResult> {
+export async function receiveForwardedOrder(
+  db: Queryable,
+  input: OrderForwardInput,
+  options: { notify?: (tenantId: string, deliveryIds: string[]) => void | Promise<void> } = {},
+): Promise<OrderForwardResult> {
   const store = new OrdersStore(db);
   // input.rawCustomerId is intentionally not read here — see the module doc's
   // "Customer identity" note for why no hash is derived from it.
@@ -142,14 +152,65 @@ export async function receiveForwardedOrder(db: Queryable, input: OrderForwardIn
     createdAt: input.createdAt ?? new Date().toISOString(),
   });
 
-  const emitted = topicsFor(previousStatus, input.status);
-  for (const topic of emitted) {
+  const emitted: WebhookTopic[] = [];
+  for (const topic of topicsFor(previousStatus, input.status)) {
+    if (topic === "order.fulfilled") {
+      if (await emitClaimedOrderFulfilled(db, input, order, options.notify)) emitted.push(topic);
+      continue;
+    }
     await emitWebhookEvent(topic, input.tenantId, toOrderData(order), {});
+    emitted.push(topic);
   }
 
   return { order, previousStatus, emitted };
 }
 
+/** Claims `order.fulfilled` for this order and, only under that claim, writes its event and deliveries. */
+async function emitClaimedOrderFulfilled(
+  db: Queryable,
+  input: OrderForwardInput,
+  order: Order,
+  notify: ((tenantId: string, deliveryIds: string[]) => void | Promise<void>) | undefined,
+): Promise<boolean> {
+  const stage = forwardStage(input.env);
+  if (!stage) return false;
+  if (!db.batch) throw new Error("Atomic D1 batch support is required.");
+  const key: OrderFulfilledClaimKey = {
+    tenantId: input.tenantId,
+    stage,
+    source: "foxycart",
+    sourceOrderId: input.externalOrderId,
+  };
+  const eventId = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const targets = commerceTargetsQuery(input.tenantId, "order.fulfilled");
+  const installs = await db.all<{ install_id: string }>(targets.sql, ...targets.params);
+  const deliveries = installs.map((row) => ({ installId: row.install_id, deliveryId: crypto.randomUUID() }));
+  await db.batch([
+    forwardClaimStatement(key, eventId, now),
+    ...commerceEventStatements({
+      eventId,
+      tenantId: input.tenantId,
+      topic: "order.fulfilled",
+      payload: toOrderData(order),
+      gate: claimedByEventGate(key, eventId),
+      targets: deliveries,
+      now,
+    }),
+  ]);
+  const written = await db.first<{ ok: number }>(`SELECT 1 AS ok FROM webhook_events WHERE id = ?`, eventId);
+  if (!written) return false;
+  const committed = await db.all<{ delivery_id: string }>(`SELECT delivery_id FROM webhook_deliveries WHERE event_id = ?`, eventId);
+  if (notify && committed.length > 0) {
+    try {
+      await notify(input.tenantId, committed.map((row) => row.delivery_id));
+    } catch {
+      // The committed deliveries stay pending; the tenant commerce alarm redelivers them.
+    }
+  }
+  return true;
+}
+
 export interface CommerceCallerConfig {
   expectedStage: CommerceStage;
   jwks: JSONWebKeySet;

package/apps/storefront/src/lib/orders/vault/appRecipientRead.ts

@@ -0,0 +1,217 @@
+/**
+ * A Private App's read of one order's ship-to recipient (`getFulfillmentRecipient`). The caller has
+ * already verified the token and scope, refused query overrides, and resolved one stage that equals
+ * both the routed stage and the order's stage.
+ *
+ * Order of work:
+ *  1. The install must be active on the tenant (else the generic 401 `invalid_token`) and still hold
+ *     the recipient scope (else 403 `scope_denied`). Has any assignment of this order named the
+ *     install? If not, `not-assigned`, and no contact table is touched.
+ *  2. The order's current assignment must be this install's `active` assignment and the order
+ *     releasable at its current event version, else `assignment-held` / `assignment-ended`.
+ *  3. The app-access audit insert (`appAuditStatement`) re-checks install, scope, assignment, order
+ *     version, consent and quota in one statement and is the only write. Nothing is decrypted, and
+ *     the ship group's state is not read, unless it committed its row.
+ *  4. Zero rows are classified from current state: install, scope, assignment, consent, then quota.
+ *
+ * Every failure is a code. A storage read that throws, before or after admission, answers 503
+ * `unavailable`; the audit insert's own error 503 `audit-unavailable`; the data key 503
+ * `vault-key-unavailable`. Responses carry codes and opaque ids only; the recipient is returned only
+ * on success.
+ */
+import type { Queryable } from "@/lib/catalog/d1/catalog.js";
+import type { KmsClient } from "@/lib/customers/contactVault/kms.js";
+import {
+  APP_CONTACT_PURPOSE,
+  APP_CONTACT_READS_PER_HOUR,
+  appAuditStatement,
+  HOUR_MS,
+  type VaultStage,
+} from "@/lib/customers/contactVault/contactAudit.js";
+import { isOpaqueId, type FulfillmentService } from "@/lib/fulfillment/fulfillmentService";
+import { readOrderShipRecipient } from "./orderContactVault.js";
+import type { ContactAddress } from "./orderContact.js";
+
+export const RECIPIENT_SCOPE = "orders:read:recipient";
+
+export interface AppRecipient {
+  orderId: string;
+  name?: string;
+  company?: string;
+  line1: string;
+  line2?: string;
+  city: string;
+  region?: string;
+  postalCode?: string;
+  country: string;
+}
+
+export type AppRecipientCode =
+  | "invalid_token"
+  | "scope_denied"
+  | "not-assigned"
+  | "assignment-held"
+  | "assignment-ended"
+  | "consent-missing"
+  | "consent-revoked"
+  | "consent-expired"
+  | "quota"
+  | "contact-erased"
+  | "contact-expired"
+  | "contact-absent"
+  | "contact-unreadable"
+  | "audit-unavailable"
+  | "vault-key-unavailable"
+  | "unavailable";
+
+export type AppRecipientOutcome =
+  | { ok: true; recipient: AppRecipient }
+  | { ok: false; status: number; code: AppRecipientCode };
+
+export interface AppRecipientInput {
+  tenantId: string;
+  stage: VaultStage;
+  installId: string;
+  orderId: string;
+  now: Date;
+}
+
+export interface AppRecipientDeps {
+  /** The apps database: audit insert, vault and authority reads. */
+  db: Queryable;
+  /** Reads the order's fulfillment view (assignment, holds, version); never decrypts. */
+  service: Pick<FulfillmentService, "get">;
+  kms: KmsClient;
+  auditId?: () => string;
+}
+
+type Eligibility =
+  | { kind: "eligible"; assignmentId: string; eventVersion: number }
+  | { kind: "refused"; status: number; code: AppRecipientCode };
+
+const refused = (status: number, code: AppRecipientCode) => ({ kind: "refused", status, code }) as const;
+
+async function installRefusal(db: Queryable, input: AppRecipientInput): Promise<Eligibility | null> {
+  const install = await db.first<{ tenant_id: string; status: string; scopes: string }>(
+    "SELECT tenant_id, status, scopes FROM app_installs WHERE install_id = ?",
+    input.installId,
+  );
+  if (!install || install.tenant_id !== input.tenantId || install.status !== "active") return refused(401, "invalid_token");
+  let scopes: unknown;
+  try {
+    scopes = JSON.parse(install.scopes);
+  } catch {
+    scopes = [];
+  }
+  if (!Array.isArray(scopes) || !scopes.includes(RECIPIENT_SCOPE)) return refused(403, "scope_denied");
+  return null;
+}
+
+async function eligibility(deps: AppRecipientDeps, input: AppRecipientInput): Promise<Eligibility> {
+  const { tenantId, stage, installId, orderId } = input;
+  const installRefused = await installRefusal(deps.db, input);
+  if (installRefused) return installRefused;
+  const named = await deps.db.first(
+    `SELECT 1 AS named FROM fulfillment_assignments
+      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND install_id = ? LIMIT 1`,
+    tenantId, stage, orderId, installId,
+  );
+  if (!named) return refused(404, "not-assigned");
+  const view = await deps.service.get({ role: "caller", actorId: installId, tenantId, stage }, orderId);
+  const assignment = view.ok ? view.value.assignment : null;
+  if (!view.ok || !assignment || assignment.installId !== installId) return refused(409, "assignment-ended");
+  if (assignment.state !== "active") return refused(409, "assignment-held");
+  const releasable = view.value.fulfillment === "ready" && view.value.holds.length === 0 && view.value.lines.length > 0;
+  if (!releasable) return refused(409, "assignment-held");
+  return { kind: "eligible", assignmentId: assignment.assignmentId, eventVersion: view.value.eventVersion };
+}
+
+/** Why the audit insert admitted nothing, read from current state; null when nothing explains it. */
+async function classifyRefusal(
+  deps: AppRecipientDeps,
+  input: AppRecipientInput,
+  admitted: { eventVersion: number },
+): Promise<{ status: number; code: AppRecipientCode } | null> {
+  const { db } = deps;
+  const { tenantId, stage, installId, now } = input;
+  const current = await eligibility(deps, input);
+  if (current.kind === "refused") return { status: current.status, code: current.code };
+  if (current.eventVersion !== admitted.eventVersion) return null;
+  const at = now.toISOString();
+  const live = await db.first(
+    `SELECT 1 AS live FROM app_contact_consents
+      WHERE install_id = ? AND tenant_id = ? AND stage = ? AND purpose = ? AND revoked_at IS NULL AND expires_at > ?`,
+    installId, tenantId, stage, APP_CONTACT_PURPOSE, at,
+  );
+  if (!live) {
+    const latest = await db.first<{ revoked_at: string | null }>(
+      `SELECT revoked_at FROM app_contact_consents
+        WHERE install_id = ? AND tenant_id = ? AND stage = ? AND purpose = ?
+        ORDER BY granted_at DESC, rowid DESC LIMIT 1`,
+      installId, tenantId, stage, APP_CONTACT_PURPOSE,
+    );
+    if (!latest) return { status: 403, code: "consent-missing" };
+    return { status: 403, code: latest.revoked_at !== null ? "consent-revoked" : "consent-expired" };
+  }
+  const hourAgo = new Date(now.getTime() - HOUR_MS).toISOString();
+  const used = await db.first<{ n: number }>(
+    "SELECT COUNT(*) AS n FROM app_contact_access_audit WHERE install_id = ? AND tenant_id = ? AND at > ?",
+    installId, tenantId, hourAgo,
+  );
+  if (Number(used?.n ?? 0) >= APP_CONTACT_READS_PER_HOUR) return { status: 429, code: "quota" };
+  return null;
+}
+
+function exported(orderId: string, shipTo: ContactAddress): AppRecipient {
+  const recipient: AppRecipient = { orderId, line1: shipTo.line1, city: shipTo.city, country: shipTo.country };
+  for (const field of ["name", "company", "line2", "region", "postalCode"] as const) {
+    const value = shipTo[field];
+    if (typeof value === "string" && value.length > 0) recipient[field] = value;
+  }
+  return recipient;
+}
+
+const ATTEMPTS = 2;
+const UNAVAILABLE = { ok: false, status: 503, code: "unavailable" } as const;
+
+export async function readAppRecipient(deps: AppRecipientDeps, input: AppRecipientInput): Promise<AppRecipientOutcome> {
+  if (!isOpaqueId(input.orderId)) return { ok: false, status: 404, code: "not-assigned" };
+  for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
+    let eligible: Eligibility;
+    try {
+      eligible = await eligibility(deps, input);
+    } catch {
+      return UNAVAILABLE;
+    }
+    if (eligible.kind === "refused") return { ok: false, status: eligible.status, code: eligible.code };
+    const admission = appAuditStatement({
+      auditId: deps.auditId?.() ?? crypto.randomUUID(),
+      installId: input.installId,
+      tenantId: input.tenantId,
+      stage: input.stage,
+      orderId: input.orderId,
+      assignmentId: eligible.assignmentId,
+      eventVersion: eligible.eventVersion,
+      scope: RECIPIENT_SCOPE,
+      now: input.now,
+    });
+    let read: Awaited<ReturnType<typeof readOrderShipRecipient>>;
+    try {
+      read = await readOrderShipRecipient(deps.db, deps.kms, {
+        tenantId: input.tenantId, stage: input.stage, orderId: input.orderId, admission, now: input.now,
+      });
+    } catch {
+      return UNAVAILABLE;
+    }
+    if (read.ok) return { ok: true, recipient: exported(input.orderId, read.shipTo) };
+    if (read.reason !== "not-admitted") return { ok: false, status: read.status, code: read.reason };
+    let why: { status: number; code: AppRecipientCode } | null;
+    try {
+      why = await classifyRefusal(deps, input, eligible);
+    } catch {
+      return UNAVAILABLE;
+    }
+    if (why) return { ok: false, ...why };
+  }
+  return { ok: false, status: 409, code: "assignment-held" };
+}

package/apps/storefront/src/lib/orders/vault/contactRoutes.ts

@@ -1,6 +1,7 @@
 /**
  * The admission every order-contact admin route runs before it touches the vault: the owner gate,
- * then the owner-or-staff split (contactReaderAuthority), then — for staff — a reason, a ticket and a
+ * then the owner-or-staff split (contactReaderAuthority; an owner route requires kind owner and a
+ * staff route kind staff, so any other kind is refused), then — for staff — a reason, a ticket and a
  * LIVE owner-consented customer-contact-read grant. The tenant comes from the routed host, never
  * from the request. An order contact's stage is the one its order is recorded under
  * (`resolveOrderStage`, shared with the Orders tab, with the shared-store admission its route
@@ -73,10 +74,10 @@ export async function openContactRoute(
 
   let actor: ContactActor;
   if (expect === "owner") {
-    if (authority.kind === "staff") return refuse("support-read-required", 403);
+    if (authority.kind !== "owner") return refuse("support-read-required", 403);
     actor = { actorId: authority.actorId, role: "owner" };
   } else {
-    if (authority.kind === "owner") return refuse("use-owner-route", 403);
+    if (authority.kind !== "staff") return refuse("use-owner-route", 403);
     const reason = readSupportReason(body);
     if (!reason) return refuse("malformed", 400);
     if (!(await resolveContactReadGrant(authority.email, host))) return refuse("grant-required", 403);

package/apps/storefront/src/lib/orders/vault/orderContactVault.ts

@@ -9,6 +9,8 @@
  *  - seal: [new data-key rows] + conditional vault insert + marker + replay (both conditioned on the
  *    vault row this command sealed) + key cleanup. Every refused or racing outcome commits nothing.
  *  - read / list: the audit row commits (staff quota in the same statement) before any decrypt.
+ *  - app recipient read: the app-access audit row commits before contact state is read or anything
+ *    is decrypted, and only the ship group is opened.
  *  - erase: audit, group clearing and detach commit together.
  *  - purge: one clock reading; each page is one batch.
  *
@@ -46,6 +48,7 @@ import {
   auditRecordIds,
   auditStatement,
   batchAuditStatement,
+  type AuditStatement,
   type ContactActor,
   type VaultStage,
 } from "@/lib/customers/contactVault/contactAudit.js";
@@ -768,6 +771,60 @@ export async function readOrderContact(
   }
 }
 
+export type ShipRecipientOutcome =
+  | { ok: true; shipTo: ContactAddress }
+  | { ok: false; status: 0; reason: "not-admitted" }
+  | {
+      ok: false;
+      status: 404 | 409 | 410 | 503;
+      reason:
+        | "contact-erased" | "contact-expired" | "contact-absent" | "contact-unreadable"
+        | "audit-unavailable" | "vault-key-unavailable" | "unavailable";
+    };
+
+const SHIP_SELECT = `SELECT fact_id, order_kid, ship_ceiling, ship_city, ship_postal_code, ship_region, ship_country,
+    ${LAYOUT.ship.sealed.join(", ")}
+  FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`;
+
+/**
+ * An app's recipient read of one order: the ship group only. `admission` is the app-access audit
+ * insert; it runs first and nothing here reads contact state, loads a key or decrypts unless it
+ * returned its row. Zero rows answer `not-admitted` (the caller classifies from authority state);
+ * an error answers 503 audit-unavailable. After admission the ship group's state classifies the
+ * order (erased, expired, absent, unreadable) and only a present group is opened. Every failure
+ * after admission is a code: the data key 503 vault-key-unavailable, any other storage error 503
+ * unavailable. No thrown message leaves this function.
+ */
+export async function readOrderShipRecipient(
+  db: Queryable,
+  kms: KmsClient,
+  input: { tenantId: string; stage: VaultStage; orderId: string; admission: AuditStatement; now: Date; policy?: RetentionPolicy },
+): Promise<ShipRecipientOutcome> {
+  const { tenantId, stage, orderId, now } = input;
+  const admitted = await admitAudit(db, input.admission);
+  if (admitted === "quota") return { ok: false, status: 0, reason: "not-admitted" };
+  if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
+  const unreadable = { ok: false, status: 409, reason: "contact-unreadable" } as const;
+  try {
+    const availability = await readOrderContactAvailability(db, { tenantId, stage, orderIds: [orderId], now, policy: input.policy });
+    const state = availability.get(orderId)?.shipTo ?? "unreadable";
+    if (state === "erased") return { ok: false, status: 410, reason: "contact-erased" };
+    if (state === "expired") return { ok: false, status: 410, reason: "contact-expired" };
+    if (state === "absent") return { ok: false, status: 404, reason: "contact-absent" };
+    if (state !== "present") return unreadable;
+    const row = await db.first<VaultRow>(SHIP_SELECT, tenantId, stage, orderId);
+    const kid = row ? text(row, "order_kid") : null;
+    if (!row || !kid) return unreadable;
+    const key = await keyForKid(db, kms, keyContext(tenantId, stage, ORDER_KEY), kid);
+    if (!key) return unreadable;
+    const opened = await openGroups(key, row, tenantId, stage, ["ship"]);
+    return opened?.shipTo ? { ok: true, shipTo: opened.shipTo } : unreadable;
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    return { ok: false, status: 503, reason: "unavailable" };
+  }
+}
+
 export interface ListedContact {
   orderId: string;
   contact: ReadableContact;