@tokenoftrust/storefront-runner 6.5.1 → 6.5.2

package/apps/storefront/migrations-apps/0027_app_contact_authority.sql

@@ -0,0 +1,70 @@
+-- Owner consent for a Private App install to read order recipients for one purpose. Opaque ids and
+-- times only; granted_by is sha256 of the owner actor id. Revoke sets revoked_at once; rows are never
+-- deleted, and re-granting inserts a new row.
+CREATE TABLE `app_contact_consents` (
+  `consent_id` text PRIMARY KEY NOT NULL,
+  `install_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `purpose` text NOT NULL CHECK (`purpose` = 'fulfillment-shipping'),
+  `granted_by` text NOT NULL CHECK (length(`granted_by`) = 64 AND `granted_by` NOT GLOB '*[^0-9a-f]*'),
+  `granted_at` text NOT NULL,
+  `expires_at` text NOT NULL,
+  `revoked_at` text,
+  CHECK (`expires_at` > `granted_at`),
+  CHECK (julianday(`expires_at`) IS NOT NULL AND julianday(`granted_at`) IS NOT NULL
+    AND julianday(`expires_at`) - julianday(`granted_at`) <= 365)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `app_contact_consents_live`
+ON `app_contact_consents` (`install_id`, `tenant_id`, `stage`, `purpose`)
+WHERE `revoked_at` IS NULL;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_consents_no_delete`
+BEFORE DELETE ON `app_contact_consents`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_consents_revoke_only`
+BEFORE UPDATE ON `app_contact_consents`
+WHEN OLD.`revoked_at` IS NOT NULL
+  OR NEW.`revoked_at` IS NULL
+  OR NEW.`consent_id` IS NOT OLD.`consent_id`
+  OR NEW.`install_id` IS NOT OLD.`install_id`
+  OR NEW.`tenant_id` IS NOT OLD.`tenant_id`
+  OR NEW.`stage` IS NOT OLD.`stage`
+  OR NEW.`purpose` IS NOT OLD.`purpose`
+  OR NEW.`granted_by` IS NOT OLD.`granted_by`
+  OR NEW.`granted_at` IS NOT OLD.`granted_at`
+  OR NEW.`expires_at` IS NOT OLD.`expires_at`
+BEGIN
+  SELECT RAISE(ABORT, 'revoke-only');
+END;
+--> statement-breakpoint
+-- Every admitted app read of an order recipient, written before anything is decrypted. Opaque ids
+-- only; append-only.
+CREATE TABLE `app_contact_access_audit` (
+  `audit_id` text PRIMARY KEY NOT NULL,
+  `install_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `purpose` text NOT NULL CHECK (`purpose` = 'fulfillment-shipping'),
+  `at` text NOT NULL,
+  `outcome` text NOT NULL CHECK (`outcome` = 'admitted')
+);
+--> statement-breakpoint
+CREATE INDEX `idx_app_contact_access_audit_quota` ON `app_contact_access_audit` (`install_id`, `tenant_id`, `at`);
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_access_audit_no_update`
+BEFORE UPDATE ON `app_contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_access_audit_no_delete`
+BEFORE DELETE ON `app_contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;

package/apps/storefront/src/lib/customers/contactVault/contactAudit.ts

@@ -18,7 +18,8 @@ export function auditRecordIds(ids: readonly string[]): string | null {
   if (ids.length > AUDIT_RECORD_IDS_MAX) throw new Error("contact audit: too many record ids");
   return ids.length === 0 ? null : ids.join(",");
 }
-const HOUR_MS = 3_600_000;
+/** The quota window. A row counts while its `at` is strictly after `now - HOUR_MS`: one exactly an hour old no longer counts. */
+export const HOUR_MS = 3_600_000;
 
 export interface ContactActor {
   actorId: string;
@@ -88,6 +89,60 @@ export async function admitAudit(db: AuditDb, statement: AuditStatement): Promis
   }
 }
 
+/** Admitted app recipient reads per install and tenant per hour. */
+export const APP_CONTACT_READS_PER_HOUR = 300;
+export const APP_CONTACT_PURPOSE = "fulfillment-shipping";
+
+/**
+ * The app-access audit insert (`app_contact_access_audit`): the recipient read's admission and its
+ * only write. It inserts one row only when, at that instant, the install is active on the tenant
+ * holding `scope`, the assignment is the install's active assignment of the order, the order still
+ * stands at `eventVersion` (the version its releasability was computed at), a live consent covers
+ * (install, tenant, stage, purpose), and the install has fewer than
+ * {@link APP_CONTACT_READS_PER_HOUR} admitted rows on the tenant in the last hour.
+ */
+export function appAuditStatement(input: {
+  auditId: string;
+  installId: string;
+  tenantId: string;
+  stage: VaultStage;
+  orderId: string;
+  assignmentId: string;
+  eventVersion: number;
+  scope: string;
+  now: Date;
+}): AuditStatement {
+  const { auditId, installId, tenantId, stage, orderId, assignmentId, eventVersion, scope, now } = input;
+  const at = now.toISOString();
+  const hourAgo = new Date(now.getTime() - HOUR_MS).toISOString();
+  return {
+    sql: `INSERT INTO app_contact_access_audit (audit_id, install_id, tenant_id, stage, order_id, purpose, at, outcome)
+          SELECT ?, ?, ?, ?, ?, '${APP_CONTACT_PURPOSE}', ?, 'admitted'
+          WHERE EXISTS (SELECT 1 FROM app_installs AS ai
+                  WHERE ai.install_id = ? AND ai.tenant_id = ? AND ai.status = 'active'
+                    AND EXISTS (SELECT 1 FROM json_each(ai.scopes) WHERE json_each.value = ?))
+            AND EXISTS (SELECT 1 FROM fulfillment_assignments AS fa
+                  WHERE fa.assignment_id = ? AND fa.tenant_id = ? AND fa.stage = ? AND fa.order_id = ?
+                    AND fa.install_id = ? AND fa.state = 'active')
+            AND EXISTS (SELECT 1 FROM scrappy_commerce_orders AS o
+                  WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ? AND o.event_version = ?)
+            AND EXISTS (SELECT 1 FROM app_contact_consents AS c
+                  WHERE c.install_id = ? AND c.tenant_id = ? AND c.stage = ? AND c.purpose = '${APP_CONTACT_PURPOSE}'
+                    AND c.revoked_at IS NULL AND c.expires_at > ?)
+            AND (SELECT COUNT(*) FROM app_contact_access_audit AS q
+                  WHERE q.install_id = ? AND q.tenant_id = ? AND q.at > ?) < ?
+          RETURNING audit_id`,
+    params: [
+      auditId, installId, tenantId, stage, orderId, at,
+      installId, tenantId, scope,
+      assignmentId, tenantId, stage, orderId, installId,
+      tenantId, stage, orderId, eventVersion,
+      installId, tenantId, stage, at,
+      installId, tenantId, hourAgo, APP_CONTACT_READS_PER_HOUR,
+    ],
+  };
+}
+
 /** The same insert without RETURNING, for use inside a batch whose later statements check the row. */
 export function batchAuditStatement(statement: AuditStatement): AuditStatement {
   return { sql: statement.sql.replace(/\s*RETURNING audit_id$/, ""), params: statement.params };

package/apps/storefront/src/lib/integrations/apps/appContactAuthority.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether a verified Private App request may ask for order contact at all: the only source of the
+ * `app` contact-reader kind. It is separate from `contactReaderAuthority`, whose outcomes stay
+ * owner, staff or none, so no human contact route can ever see an app.
+ *
+ * Every predicate is required: an install record, active, on the host tenant, the token's subject
+ * naming it, and the scope in both the install grant and the token. Consent, assignment and quota
+ * are decided by the audit insert, not here.
+ */
+export type AppContactAuthority = { kind: "app"; installId: string; tenantId: string } | { kind: "none" };
+
+export interface AppContactAuthorityInput {
+  install: { installId: string; tenantId: string; status: string; scopes: readonly string[] } | null | undefined;
+  claims: { sub: string; scopes: readonly string[] } | null | undefined;
+  hostResource: string;
+  scope: string;
+}
+
+export function appContactAuthority(input: AppContactAuthorityInput): AppContactAuthority {
+  const { install, claims, scope } = input;
+  const host = input.hostResource.trim();
+  if (!install || !claims || !host || !scope) return { kind: "none" };
+  if (install.status !== "active" || install.tenantId !== host) return { kind: "none" };
+  if (!install.installId || claims.sub !== install.installId) return { kind: "none" };
+  if (!install.scopes.includes(scope) || !claims.scopes.includes(scope)) return { kind: "none" };
+  return { kind: "app", installId: install.installId, tenantId: host };
+}

package/apps/storefront/src/lib/integrations/apps/appContactConsents.ts

@@ -0,0 +1,112 @@
+/**
+ * Owner consent for a Private App install to read order recipients (`app_contact_consents`). One
+ * purpose, `fulfillment-shipping`. Rows hold opaque ids, times and `granted_by` (sha256 hex of the
+ * owner actor id); never contact data or an email. Grant inserts a row only when the install is
+ * active on the tenant; revoke sets `revoked_at` once; uninstall revokes every live row in its own
+ * batch. The table's triggers refuse DELETE and every other UPDATE.
+ */
+import type { Queryable } from "../../catalog/d1/catalog.js";
+
+export const CONSENT_PURPOSE = "fulfillment-shipping";
+export const CONSENT_MAX_MS = 365 * 24 * 3_600_000;
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const CONSENT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export type ConsentStage = "preview" | "publication";
+
+export interface ConsentView {
+  consentId: string;
+  installId: string;
+  stage: ConsentStage;
+  purpose: typeof CONSENT_PURPOSE;
+  grantedAt: string;
+  expiresAt: string;
+  revokedAt: string | null;
+}
+
+export function isConsentId(value: string): boolean {
+  return CONSENT_ID.test(value) && !value.includes("@");
+}
+
+/**
+ * The closed grant body `{installId, purpose, expiresAt}`: purpose exactly `fulfillment-shipping`,
+ * expiresAt an ISO instant after `now` and at most 365 days later. Null otherwise.
+ */
+export function readConsentGrant(body: unknown, now: Date): { installId: string; expiresAt: string } | null {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const record = body as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  if (keys.length !== 3 || keys.join(",") !== "expiresAt,installId,purpose") return null;
+  const { installId, purpose, expiresAt } = record;
+  if (purpose !== CONSENT_PURPOSE) return null;
+  if (typeof installId !== "string" || !isConsentId(installId)) return null;
+  if (typeof expiresAt !== "string" || !ISO_INSTANT.test(expiresAt)) return null;
+  const expires = Date.parse(expiresAt);
+  if (!Number.isFinite(expires) || new Date(expires).toISOString() !== expiresAt) return null;
+  if (expires <= now.getTime() || expires - now.getTime() > CONSENT_MAX_MS) return null;
+  return { installId, expiresAt };
+}
+
+/** sha256 hex of the owner actor id: the only owner reference a consent row keeps. */
+export async function grantedByHash(actorId: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(actorId));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return error instanceof Error && /UNIQUE constraint failed/i.test(error.message);
+}
+
+export type GrantOutcome =
+  | { ok: true; consent: ConsentView }
+  | { ok: false; code: "install-not-found" | "conflict" };
+
+export async function grantConsent(
+  db: Queryable,
+  input: { tenantId: string; stage: ConsentStage; installId: string; expiresAt: string; grantedBy: string; now: Date; consentId?: string },
+): Promise<GrantOutcome> {
+  const consentId = input.consentId ?? crypto.randomUUID();
+  const grantedAt = input.now.toISOString();
+  try {
+    const rows = await db.all<{ consent_id: string }>(
+      `INSERT INTO app_contact_consents (consent_id, install_id, tenant_id, stage, purpose, granted_by, granted_at, expires_at, revoked_at)
+       SELECT ?, ?, ?, ?, '${CONSENT_PURPOSE}', ?, ?, ?, NULL
+       WHERE EXISTS (SELECT 1 FROM app_installs WHERE install_id = ? AND tenant_id = ? AND status = 'active')
+       RETURNING consent_id`,
+      consentId, input.installId, input.tenantId, input.stage, input.grantedBy, grantedAt, input.expiresAt,
+      input.installId, input.tenantId,
+    );
+    if (rows.length !== 1) return { ok: false, code: "install-not-found" };
+  } catch (error) {
+    if (isUniqueViolation(error)) return { ok: false, code: "conflict" };
+    throw error;
+  }
+  return {
+    ok: true,
+    consent: {
+      consentId, installId: input.installId, stage: input.stage, purpose: CONSENT_PURPOSE,
+      grantedAt, expiresAt: input.expiresAt, revokedAt: null,
+    },
+  };
+}
+
+/** Sets `revoked_at` on one live consent of (tenant, stage); null when there is none to revoke. */
+export async function revokeConsent(
+  db: Queryable,
+  input: { tenantId: string; stage: ConsentStage; consentId: string; now: Date },
+): Promise<ConsentView | null> {
+  const rows = await db.all<{
+    consent_id: string; install_id: string; stage: ConsentStage; granted_at: string; expires_at: string; revoked_at: string;
+  }>(
+    `UPDATE app_contact_consents SET revoked_at = ?
+      WHERE consent_id = ? AND tenant_id = ? AND stage = ? AND revoked_at IS NULL
+      RETURNING consent_id, install_id, stage, granted_at, expires_at, revoked_at`,
+    input.now.toISOString(), input.consentId, input.tenantId, input.stage,
+  );
+  const row = rows[0];
+  if (!row) return null;
+  return {
+    consentId: row.consent_id, installId: row.install_id, stage: row.stage, purpose: CONSENT_PURPOSE,
+    grantedAt: row.granted_at, expiresAt: row.expires_at, revokedAt: row.revoked_at,
+  };
+}

package/apps/storefront/src/lib/integrations/apps/registryService.ts

@@ -709,6 +709,7 @@ export class AppRegistryService {
         params: [this.now(), installId],
       },
       ...this.detach(row.tenant_id, installId, actor),
+      this.revokeConsentsStatement(installId, row.tenant_id),
       this.auditStatement({ installId, tenantId: row.tenant_id, event: "uninstalled", actor }),
     ]);
     await this.credentials.clear(installId);
@@ -785,6 +786,14 @@ export class AppRegistryService {
     };
   }
 
+  /** Revokes every live contact-read consent of the install on its tenant (`app_contact_consents`). */
+  private revokeConsentsStatement(installId: string, tenantId: string): { sql: string; params: unknown[] } {
+    return {
+      sql: "UPDATE app_contact_consents SET revoked_at = ? WHERE install_id = ? AND tenant_id = ? AND revoked_at IS NULL",
+      params: [this.now(), installId, tenantId],
+    };
+  }
+
   private detach(tenantId: string, installId: string, actor: string): { sql: string; params: unknown[] }[] {
     return detachInstallStatements({ tenantId, installId, actor, now: this.now() }).map((statement) => ({
       sql: statement.sql,

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "6.5.1",
+  "version": "6.5.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",