@tokenoftrust/storefront-runner 6.5.0 → 6.5.2

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

@@ -41,9 +41,10 @@
  * `app_version_snapshots` table over the SAME `Queryable` seam this service
  * uses). The authority for "which version is active" is the version store's
  * `MAX(seq)` current snapshot; `app_installs.app_version` is a DERIVED MIRROR
- * that this service re-points from the store's post-write current version in
- * the same operation ({@link AppRegistryService.syncActiveVersionMirror}). The
- * two can never diverge because the mirror is only ever written from the
+ * that this service writes from the store's current version in the same
+ * operation: `update` writes it from the activation it commits in the same
+ * batch, and `rollback` re-syncs it ({@link AppRegistryService.syncActiveVersionMirror}).
+ * The two can never diverge because the mirror is only ever written from the
  * store's current snapshot — you change the active version by retaining/rolling
  * one, never by writing the mirror directly. `rollback` restores a prior
  * version's whole facet set atomically (store-side) and re-syncs the mirror, so
@@ -56,6 +57,7 @@ import {
   AppVersionError,
   type AppVersionFacets,
   type AppVersionSnapshot,
+  type PlannedVersionWrite,
 } from "./appVersionStore.js";
 import {
   DEFAULT_EXECUTION_TIER,
@@ -71,6 +73,7 @@ import {
   type PlanIntegrationConsent,
 } from "@tot/public-runtime";
 import type { Queryable } from "../../catalog/d1/catalog.js";
+import { PROCESSOR_SCOPE, detachInstallStatements } from "../../fulfillment/assignmentStore.js";
 
 export type AppInstallStatus = "active" | "suspended" | "uninstalled";
 
@@ -558,20 +561,19 @@ export class AppRegistryService {
     const widgetPlacementsJson =
       widgetPlacements !== undefined ? JSON.stringify(widgetPlacements) : row.widget_placements;
 
-    // Retain this update as a new activation BEFORE the metadata write — after
-    // every fail-closed validation above, so a bad patch retains nothing. This
-    // captures the whole facet set at this version and, being the last write
-    // gate that can refuse (a secret-bearing facet set), keeps `update` all-or-
-    // nothing. `app_version` is NOT written here: it is the mirror, re-pointed
-    // below from the store's post-retain current version.
+    // Plan this update's new activation after every fail-closed validation above, so a
+    // bad patch retains nothing; planning is the last gate that can refuse (a
+    // secret-bearing facet set). The activation, the metadata write and the
+    // `app_version` mirror (the planned activation's version) commit in one batch.
     const facets = resolveVersionFacets({
       appVersion,
       scopes: effectiveScopes,
       manifest: patch.manifest !== undefined ? patch.manifest : (JSON.parse(row.manifest) as unknown),
       override: patch.versionFacets,
     });
+    let retained: PlannedVersionWrite;
     try {
-      await this.versionStore.retainVersion({
+      retained = await this.versionStore.planRetainVersion({
         installId,
         tenantId: row.tenant_id,
         facets,
@@ -581,27 +583,27 @@ export class AppRegistryService {
       throw this.asRegistryError(cause);
     }
 
-    await this.db.run(
-      `UPDATE app_installs
-          SET scopes = ?, manifest = ?, webhook_endpoint = ?,
-              widget_placements = ?, updated_at = ?
-        WHERE install_id = ?`,
-      scopesJson,
-      manifestJson,
-      webhookEndpoint,
-      widgetPlacementsJson,
-      now,
-      installId,
-    );
-    await this.syncActiveVersionMirror(installId);
-
-    await this.appendAudit({
-      installId,
-      tenantId: row.tenant_id,
-      event: "updated",
-      actor,
-      detail: { fields: Object.keys(patch) },
-    });
+    // An install that can no longer be notified of fulfillment work loses its assignments and
+    // processor config in the same batch as the change that descoped it.
+    const processorCapable = effectiveScopes.includes(PROCESSOR_SCOPE) && !!webhookEndpoint;
+    await this.lifecycleBatch([
+      { sql: retained.statement.sql, params: [...(retained.statement.params ?? [])] },
+      {
+        sql: `UPDATE app_installs
+            SET scopes = ?, manifest = ?, webhook_endpoint = ?,
+                widget_placements = ?, app_version = ?, updated_at = ?
+          WHERE install_id = ?`,
+        params: [scopesJson, manifestJson, webhookEndpoint, widgetPlacementsJson, retained.snapshot.appVersion, now, installId],
+      },
+      ...(processorCapable ? [] : this.detach(row.tenant_id, installId, actor)),
+      this.auditStatement({
+        installId,
+        tenantId: row.tenant_id,
+        event: "updated",
+        actor,
+        detail: { fields: Object.keys(patch) },
+      }),
+    ]);
 
     return this.getOrThrow(installId);
   }
@@ -646,8 +648,11 @@ export class AppRegistryService {
         "invalid_state",
       );
     }
-    await this.setStatus(installId, "suspended");
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "suspended", actor });
+    await this.lifecycleBatch([
+      this.statusStatement(installId, "suspended"),
+      ...this.detach(row.tenant_id, installId, actor),
+      this.auditStatement({ installId, tenantId: row.tenant_id, event: "suspended", actor }),
+    ]);
     return this.getOrThrow(installId);
   }
 
@@ -660,8 +665,11 @@ export class AppRegistryService {
         "invalid_state",
       );
     }
-    await this.setStatus(installId, "active");
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "resumed", actor });
+    // Resume restores access only; released assignments stay released until a new operator release.
+    await this.lifecycleBatch([
+      this.statusStatement(installId, "active"),
+      this.auditStatement({ installId, tenantId: row.tenant_id, event: "resumed", actor }),
+    ]);
     return this.getOrThrow(installId);
   }
 
@@ -695,13 +703,16 @@ export class AppRegistryService {
     if (row.status === "uninstalled") {
       throw new RegistryError(`Install is already uninstalled.`, "invalid_state");
     }
-    await this.db.run(
-      `UPDATE app_installs SET status = 'uninstalled', widget_placements = '[]', updated_at = ? WHERE install_id = ?`,
-      this.now(),
-      installId,
-    );
+    await this.lifecycleBatch([
+      {
+        sql: `UPDATE app_installs SET status = 'uninstalled', widget_placements = '[]', updated_at = ? WHERE install_id = ?`,
+        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);
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "uninstalled", actor });
     return this.getOrThrow(installId);
   }
 
@@ -738,10 +749,9 @@ export class AppRegistryService {
   /**
    * Re-point `app_installs.app_version` (the derived mirror) to the version
    * store's current (`MAX(seq)`) snapshot — the single reconciliation step that
-   * keeps the mirror and the source-of-truth authority from diverging. Called
-   * after every store write that can change the active version (`update`,
-   * `rollback`); `install` sets the mirror from the same resolved facet set at
-   * INSERT time, so it is already consistent there.
+   * keeps the mirror and the source-of-truth authority from diverging after a
+   * `rollback`. `install` and `update` write the mirror from the activation they
+   * commit in the same write, so they are already consistent.
    */
   private async syncActiveVersionMirror(installId: string): Promise<void> {
     const current = await this.versionStore.currentVersion(installId);
@@ -769,13 +779,32 @@ export class AppRegistryService {
     return cause;
   }
 
-  private async setStatus(installId: string, status: AppInstallStatus): Promise<void> {
-    await this.db.run(
-      `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
-      status,
-      this.now(),
-      installId,
-    );
+  private statusStatement(installId: string, status: AppInstallStatus): { sql: string; params: unknown[] } {
+    return {
+      sql: `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
+      params: [status, this.now(), installId],
+    };
+  }
+
+  /** 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,
+      params: [...statement.params],
+    }));
+  }
+
+  /** Lifecycle writes commit together or not at all; a handle without batch is refused before any write. */
+  private async lifecycleBatch(statements: { sql: string; params: unknown[] }[]): Promise<void> {
+    if (!this.db.batch) throw new Error("Atomic D1 batch support is required.");
+    await this.db.batch(statements);
   }
 
   private async findRowByAppTenantEnv(
@@ -809,25 +838,32 @@ export class AppRegistryService {
     return toDomain(await this.mustFindRow(installId));
   }
 
-  private async appendAudit(params: {
+  private auditStatement(params: {
     installId: string;
     tenantId: string;
     event: AppAuditEvent;
     actor: string;
     detail?: Record<string, unknown>;
     traceId?: string;
-  }): Promise<void> {
-    await this.db.run(
-      `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at)
+  }): { sql: string; params: unknown[] } {
+    return {
+      sql: `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at)
        VALUES (?,?,?,?,?,?,?,?)`,
-      crypto.randomUUID(),
-      params.installId,
-      params.tenantId,
-      params.event,
-      params.actor,
-      params.traceId ?? null,
-      JSON.stringify(params.detail ?? {}),
-      this.now(),
-    );
+      params: [
+        crypto.randomUUID(),
+        params.installId,
+        params.tenantId,
+        params.event,
+        params.actor,
+        params.traceId ?? null,
+        JSON.stringify(params.detail ?? {}),
+        this.now(),
+      ],
+    };
+  }
+
+  private async appendAudit(params: Parameters<AppRegistryService["auditStatement"]>[0]): Promise<void> {
+    const statement = this.auditStatement(params);
+    await this.db.run(statement.sql, ...statement.params);
   }
 }

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

@@ -0,0 +1,101 @@
+/**
+ * Payload admission for the commerce topics the single commerce emitter writes:
+ * `fulfillment.assignment.created`, `fulfillment.assignment.updated` and `order.fulfilled`.
+ *
+ * Each topic has a closed key set (`asyncapi.yaml` `FulfillmentAssignmentData` and `OrderData`)
+ * and every payload also passes the private-identity check. Both run when the event row is
+ * written and again before the delivery engine signs and POSTs it.
+ */
+import type { WebhookTopic } from "./deliveryStore.js";
+
+export type CommerceTopic = "fulfillment.assignment.created" | "fulfillment.assignment.updated" | "order.fulfilled";
+
+export const COMMERCE_TOPICS: readonly CommerceTopic[] = [
+  "fulfillment.assignment.created",
+  "fulfillment.assignment.updated",
+  "order.fulfilled",
+];
+
+/** Keys that identify a person or an address. None may appear at any depth of a commerce payload. */
+export const COMMERCE_PRIVATE_KEYS = new Set([
+  "customer",
+  "customerEmail",
+  "customerName",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "city",
+  "company",
+  "postalCode",
+  "shippingAddress",
+  "billingAddress",
+  "shipTo",
+  "billTo",
+  "address",
+  "firstName",
+  "lastName",
+  "name",
+]);
+
+const ASSIGNMENT_KEYS = ["assignmentId", "orderId", "stage", "state", "eventVersion", "occurredAt"] as const;
+const ASSIGNMENT_STATES = new Set(["active", "held", "cancelled"]);
+const ORDER_DATA_KEYS = new Set(["id", "status", "currency", "customerHash", "subtotal", "total", "lineItems"]);
+const LINE_ITEM_KEYS = new Set(["sku", "handle", "quantity", "lineTotal"]);
+
+export function isCommerceTopic(topic: WebhookTopic): topic is CommerceTopic {
+  return (COMMERCE_TOPICS as readonly string[]).includes(topic);
+}
+
+export function commercePayloadHasPrivateIdentity(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
+  return Object.entries(value as Record<string, unknown>).some(
+    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 256;
+}
+
+function assignmentAdmissible(topic: CommerceTopic, payload: Record<string, unknown>): boolean {
+  const keys = Object.keys(payload);
+  if (keys.length !== ASSIGNMENT_KEYS.length || !ASSIGNMENT_KEYS.every((key) => keys.includes(key))) return false;
+  if (!nonEmptyString(payload.assignmentId) || !nonEmptyString(payload.orderId)) return false;
+  if (payload.stage !== "preview" && payload.stage !== "publication") return false;
+  if (typeof payload.state !== "string" || !ASSIGNMENT_STATES.has(payload.state)) return false;
+  if (topic === "fulfillment.assignment.created" && payload.state !== "active") return false;
+  if (!Number.isSafeInteger(payload.eventVersion) || Number(payload.eventVersion) < 0) return false;
+  return typeof payload.occurredAt === "string" && Number.isFinite(Date.parse(payload.occurredAt));
+}
+
+function orderFulfilledAdmissible(payload: Record<string, unknown>): boolean {
+  if (Object.keys(payload).some((key) => !ORDER_DATA_KEYS.has(key))) return false;
+  if (!nonEmptyString(payload.id) || payload.status !== "fulfilled" || !nonEmptyString(payload.currency)) return false;
+  if (payload.customerHash !== undefined && typeof payload.customerHash !== "string") return false;
+  for (const key of ["subtotal", "total"] as const) {
+    if (payload[key] !== undefined && (typeof payload[key] !== "number" || !Number.isFinite(payload[key]))) return false;
+  }
+  if (payload.lineItems === undefined) return true;
+  if (!Array.isArray(payload.lineItems)) return false;
+  return payload.lineItems.every(
+    (item) =>
+      isRecord(item) &&
+      Object.keys(item).every((key) => LINE_ITEM_KEYS.has(key)) &&
+      nonEmptyString(item.sku) &&
+      Number.isSafeInteger(item.quantity) &&
+      (item.handle === undefined || typeof item.handle === "string") &&
+      (item.lineTotal === undefined || (typeof item.lineTotal === "number" && Number.isFinite(item.lineTotal))),
+  );
+}
+
+/** True when `payload` is exactly the closed shape `topic` allows and carries no private identity. */
+export function commercePayloadAdmissible(topic: CommerceTopic, payload: unknown): boolean {
+  if (!isRecord(payload) || commercePayloadHasPrivateIdentity(payload)) return false;
+  return topic === "order.fulfilled" ? orderFulfilledAdmissible(payload) : assignmentAdmissible(topic, payload);
+}

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

@@ -24,7 +24,8 @@
  */
 import { WebhookDeliveryStore, ScrappyCommerceOutbox, type CommerceOutboxDue, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
-import { buildCloudEventEnvelope } from "./events.js";
+import { buildCloudEventEnvelope, TOPIC_REQUIRED_SCOPE } from "./events.js";
+import { commercePayloadAdmissible, commercePayloadHasPrivateIdentity, isCommerceTopic } from "./commercePayloads.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
 import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
@@ -91,11 +92,17 @@ export class DeliveryEngineError extends Error {
  * still creates a delivery row for it), so refusing it here on status alone
  * would silently swallow every uninstall notification. It still refuses a
  * missing install or one with no endpoint, and every OTHER topic still
- * refuses a non-active (suspended/uninstalled) install exactly as before.
+ * refuses a non-active (suspended/uninstalled) install. Every topic also
+ * requires, at delivery time, that the install belongs to the delivery's
+ * tenant and still holds `TOPIC_REQUIRED_SCOPE[topic]`, so a descoped install
+ * receives nothing already queued.
  */
-function isDeadInstall(install: AppInstall | null, topic: WebhookTopic): boolean {
+function isDeadInstall(install: AppInstall | null, delivery: WebhookDelivery): boolean {
   if (!install || !install.webhookEndpoint) return true;
-  if (topic === "app.uninstalled") return false;
+  if (install.tenantId !== delivery.tenantId) return true;
+  const requiredScope = TOPIC_REQUIRED_SCOPE[delivery.topic];
+  if (requiredScope != null && !install.scopes.includes(requiredScope)) return true;
+  if (delivery.topic === "app.uninstalled") return false;
   return install.status !== "active";
 }
 
@@ -138,7 +145,7 @@ export async function attemptDelivery(deliveryId: string, deps: AttemptDeliveryD
     throw new DeliveryEngineError(`Cannot resolve install "${delivery.installId}" for delivery "${deliveryId}".`, cause);
   }
 
-  if (isDeadInstall(install, delivery.topic)) {
+  if (isDeadInstall(install, delivery)) {
     // Don't deliver to a dead/suspended install, or one with no endpoint
     // configured — no POST attempt, no recordAttempt row; go straight to the
     // one terminal-failure state the store has. This is how suspension kills
@@ -193,6 +200,11 @@ async function deliverSigned(
     return { kind: "dead-lettered", reason: "endpoint_blocked" };
   }
 
+  if (isCommerceTopic(delivery.topic) && !commercePayloadAdmissible(delivery.topic, event.payload)) {
+    await ctx.store.transitionState({ deliveryId, toState: "dead-lettered" });
+    return { kind: "dead-lettered", reason: "payload_refused" };
+  }
+
   const envelope = buildCloudEventEnvelope({
     deliveryId,
     tenantId: delivery.tenantId,
@@ -283,35 +295,6 @@ async function postWithTimeout(
 // Transport rejects private fields even when an outbox row was written outside
 // the Orders service. scrappyDurability.test.ts checks every Orders private key
 // recursively at actual retry time so the two boundary policies cannot diverge.
-const COMMERCE_PRIVATE_KEYS = new Set([
-  "customer",
-  "customerEmail",
-  "customerName",
-  "email",
-  "phone",
-  "line1",
-  "line2",
-  "city",
-  "company",
-  "postalCode",
-  "shippingAddress",
-  "billingAddress",
-  "shipTo",
-  "billTo",
-  "address",
-  "firstName",
-  "lastName",
-  "name",
-]);
-
-function commercePayloadHasPrivateIdentity(value: unknown): boolean {
-  if (value === null || typeof value !== "object") return false;
-  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
-  return Object.entries(value as Record<string, unknown>).some(
-    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
-  );
-}
-
 function publicCommercePayload(payload: string): Record<string, unknown> | null {
   let parsed: unknown;
   try {