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

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

@@ -0,0 +1,168 @@
+/**
+ * Retry/backoff dispatcher — PrivateApps epic, D4 (Chunk C: Dispatcher +
+ * Delivery Engine). Owns WHEN a delivery gets attempted: the `WebhookDispatcher`
+ * transport seam that Chunk D (emit hooks) and Chunk E (routes — e.g. manual
+ * replay) enqueue work through, the pure backoff policy every dispatcher
+ * implementation shares, and `InMemoryDispatcher`, the V1 implementation that
+ * per `d4-design-resolutions` IS the production path.
+ *
+ * `cloudflareQueueDispatcher.ts` builds a Cloudflare Queues adapter behind the
+ * SAME seam, but it is not wired into the Worker entry yet — per the design
+ * resolution, V1 does not provision a real Queue. Investigation into whether
+ * that's even possible with the current adapter: `@astrojs/cloudflare` v14
+ * generates the Worker entry as `{ fetch: handle }` only (see
+ * `node_modules/@astrojs/cloudflare/dist/entrypoints/server.js`) — there is no
+ * hook to also export a `queue()` consumer alongside the generated `fetch()`.
+ * `dist/index.js` DOES thread `queues.producers` through to the underlying
+ * `@cloudflare/vite-plugin` config (for `env.WEBHOOK_DELIVERY_QUEUE.send()` to
+ * work as a producer binding), but nothing analogous exists for consumers.
+ * TODO(infra decision — wire the Queue consumer entry): once a real Queue is
+ * provisioned, either (a) upgrade `@astrojs/cloudflare` in case a later
+ * version adds consumer support, or (b) hand-write a small wrapper worker
+ * module that re-exports the generated `fetch` and ALSO exports a `queue()`
+ * that calls `cloudflareQueueDispatcher.ts`'s `queue()` — replacing
+ * `wrangler.toml`'s implicit "main is generated" note with an explicit `main`
+ * pointing at that wrapper. Neither is done here; this file and
+ * `cloudflareQueueDispatcher.ts` only build the seam + adapter, gated behind
+ * `getDispatcher.ts`'s binding-presence check (no `[[queues]]` binding is
+ * declared in `wrangler.toml`, so that branch is dead code until infra adds one).
+ *
+ * Deliberately decoupled from `deliveryEngine.ts`: the dispatcher's job is
+ * scheduling ("run this deliveryId now / at this time"), not HTTP delivery.
+ * `InMemoryDispatcher` takes the engine's `attemptDelivery` as an injected
+ * `AttemptDeliveryFn` rather than importing `deliveryEngine.ts` directly, so
+ * tests can drive it with a fake attempt function with no store/registry/
+ * signing/fetch involved at all.
+ */
+
+/** One unit of dispatcher work: attempt (or retry) delivering one delivery. */
+export interface DispatchJob {
+  deliveryId: string;
+  /** ISO timestamp; the dispatcher must not run the job before this. Omitted = run ASAP. */
+  notBefore?: string;
+}
+
+/** The transport seam `deliveryEngine.ts`'s callers (Chunk D/E) enqueue work through. */
+export interface WebhookDispatcher {
+  enqueue(job: DispatchJob): Promise<void>;
+}
+
+/**
+ * `attemptDelivery`'s outcome, as classified by `deliveryEngine.ts` — this is
+ * the type the dispatcher branches on to decide whether to reschedule.
+ * `"retrying"`/`"dead-lettered"` mirror `DeliveryState` names on purpose (see
+ * `deliveryStore.ts`); `"delivered"`/`"dead-lettered"` are terminal — only
+ * `"retrying"` ever reschedules.
+ */
+export type AttemptOutcome =
+  | { kind: "delivered" }
+  | { kind: "retrying"; nextAttemptAt: string }
+  | { kind: "dead-lettered"; reason: "install_unavailable" | "max_attempts" | "endpoint_blocked" };
+
+/** One attempt of one delivery. Implemented by `deliveryEngine.ts`'s `attemptDelivery`, partially applied over its deps. */
+export type AttemptDeliveryFn = (deliveryId: string) => Promise<AttemptOutcome>;
+
+/** Deliveries stop retrying and are dead-lettered after this many attempts. */
+export const MAX_DELIVERY_ATTEMPTS = 6;
+
+const BASE_DELAY_SECONDS = 30;
+const MAX_DELAY_SECONDS = 60 * 60; // 1h cap
+
+/**
+ * Exponential backoff with full jitter, capped at 1h:
+ * `min(BASE * 2^(attempt-1), cap)`, then a uniform pick in `(0, cap]`.
+ * `attempt` is 1-indexed — the attempt number that just failed (so attempt 1
+ * ⇒ up to 30s, attempt 2 ⇒ up to 60s, … capping out well before attempt 6 /
+ * {@link MAX_DELIVERY_ATTEMPTS}).
+ */
+export function computeBackoffDelaySeconds(attempt: number): number {
+  const exp = BASE_DELAY_SECONDS * 2 ** Math.max(0, attempt - 1);
+  const cap = Math.min(exp, MAX_DELAY_SECONDS);
+  return Math.floor(Math.random() * cap) + 1; // never 0 — always some delay before retrying
+}
+
+interface PendingJob {
+  deliveryId: string;
+  notBefore: number;
+}
+
+export interface InMemoryDispatcherOptions {
+  /** Injected clock (epoch ms). Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+   * Default `true` (production behavior): an immediate job runs on a
+   * microtask and a delayed retry schedules a real `setTimeout`. Set `false`
+   * in tests — jobs queue internally instead of touching real timers; drain
+   * them deterministically with {@link InMemoryDispatcher.runDueNow}.
+   */
+  useRealTimers?: boolean;
+}
+
+/**
+ * V1's WORKING production dispatcher (per `d4-design-resolutions`) — an
+ * in-process queue with no external infra. `enqueue()` never awaits the
+ * actual HTTP attempt; it schedules it and returns.
+ */
+export class InMemoryDispatcher implements WebhookDispatcher {
+  private readonly now: () => number;
+  private readonly useRealTimers: boolean;
+  private readonly pending: PendingJob[] = [];
+  private readonly timers = new Set<ReturnType<typeof setTimeout>>();
+
+  constructor(
+    private readonly attempt: AttemptDeliveryFn,
+    options: InMemoryDispatcherOptions = {},
+  ) {
+    this.now = options.now ?? (() => Date.now());
+    this.useRealTimers = options.useRealTimers ?? true;
+  }
+
+  async enqueue(job: DispatchJob): Promise<void> {
+    const notBefore = job.notBefore ? Date.parse(job.notBefore) : this.now();
+    this.scheduleOrRun(job.deliveryId, notBefore);
+  }
+
+  /**
+   * Test-only deterministic drain: repeatedly runs every job whose
+   * `notBefore` is `<= now()` — including retries a just-run attempt itself
+   * schedules, if those are also due — until nothing is due. Only meaningful
+   * when constructed with `useRealTimers: false`; with real timers, jobs never
+   * sit in `pending` (they're already scheduled via microtask/setTimeout).
+   */
+  async runDueNow(): Promise<void> {
+    for (;;) {
+      const now = this.now();
+      const dueIndex = this.pending.findIndex((j) => j.notBefore <= now);
+      if (dueIndex === -1) return;
+      const [job] = this.pending.splice(dueIndex, 1);
+      await this.run(job!.deliveryId);
+    }
+  }
+
+  private scheduleOrRun(deliveryId: string, notBefore: number): void {
+    if (!this.useRealTimers) {
+      this.pending.push({ deliveryId, notBefore });
+      return;
+    }
+    const delayMs = notBefore - this.now();
+    if (delayMs <= 0) {
+      queueMicrotask(() => {
+        void this.run(deliveryId);
+      });
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      void this.run(deliveryId);
+    }, delayMs);
+    if (typeof timer.unref === "function") timer.unref(); // don't hold the process open for a pending retry
+    this.timers.add(timer);
+  }
+
+  private async run(deliveryId: string): Promise<void> {
+    const outcome = await this.attempt(deliveryId);
+    if (outcome.kind === "retrying") {
+      this.scheduleOrRun(deliveryId, Date.parse(outcome.nextAttemptAt));
+    }
+  }
+}

package/apps/storefront/src/lib/webhooks/emit.ts

@@ -0,0 +1,167 @@
+/**
+ * Webhook event emitter — PrivateApps epic, D4 (Chunk D: Emit hooks). The one
+ * place a caller (today: the two D2 admin routes; a future catalog/order/etc.
+ * trigger later) turns "something happened" into a persisted event + one
+ * delivery per eligible install + an enqueued dispatcher job per delivery.
+ * Targeting is resolved HERE so callers never hand-roll it: an install is
+ * eligible for a topic when it's `active` (`app.uninstalled` is the one
+ * exception — see {@link isEligibleTarget}, and `deliveryEngine.ts`'s
+ * matching `isDeadInstall` exemption), has a `webhookEndpoint`, and its
+ * `scopes` include `TOPIC_REQUIRED_SCOPE[topic]` when that topic requires one
+ * (`events.ts`) — an app only receives events it's scoped for.
+ *
+ * Two targeting modes, chosen by whether `opts.installId` is given:
+ *   - Given: scoped to exactly that one install (still subject to
+ *     {@link isEligibleTarget}). This is REQUIRED for the two lifecycle
+ *     topics (`app.installed`/`app.uninstalled` — {@link LIFECYCLE_TOPICS}):
+ *     each is inherently about ONE subject install, never a tenant-wide
+ *     broadcast — otherwise every other app on the tenant would learn about
+ *     (and, for `app.uninstalled`, keep getting redelivered) a DIFFERENT
+ *     app's lifecycle transitions, a cross-app isolation leak. Omitting it
+ *     for a lifecycle topic is refused (logged, `null`), not silently
+ *     broadened.
+ *   - Omitted: tenant-wide fan-out to every eligible, topic-subscribed
+ *     install — correct for data topics (`order.created`, etc.), where
+ *     multiple installed apps legitimately subscribe to the same data.
+ *
+ * Mirrors `adminService.ts`'s `getRegistryService()` composition-root shape —
+ * reuses it outright for the registry, and builds its own
+ * `WebhookDeliveryStore` over the same `STOREFRONT_APPS_DB` binding (the D1
+ * binding is one binding shared by every composition root; there is no
+ * separate "events DB").
+ *
+ * Best-effort, not authoritative: an unconfigured runtime, or an unconfigured
+ * dispatcher (`getDispatcher()` returning its 503), is logged and swallowed
+ * here rather than thrown — a webhook-plumbing outage must never fail the
+ * business mutation (install/uninstall) that triggered the emit. Callers
+ * should still wrap their own call in try/catch as a second layer (belt +
+ * suspenders), since an unexpected store/registry error is NOT swallowed —
+ * see the two admin routes this wires into.
+ *
+ * Payload minimization is enforced at the call site, not here: `data` is
+ * passed through to the CloudEvents envelope verbatim, so never pass secrets
+ * or raw PII. Per the contract, `app.installed`/`app.uninstalled` carry no
+ * customer data at all (envelope identity only — `{}`); any future topic
+ * needing customer identity must use the per-(tenant, app-install) opaque
+ * hash, never a raw identifier.
+ */
+import { WebhookDeliveryStore, type WebhookTopic } from "./deliveryStore.js";
+import { TOPIC_REQUIRED_SCOPE } from "./events.js";
+import { getDispatcher } from "./getDispatcher.js";
+import { getRegistryService } from "../apps/adminService.js";
+import type { AppInstall } from "../apps/registryService.js";
+import { fromD1 } from "../d1/catalog.js";
+import { readD1 } from "../env.js";
+
+/** Contract-scoped payload schema version — `asyncapi.yaml`'s `dataschemaversion` is `const: "1"` for V1. */
+const DATASCHEMA_VERSION = "1";
+
+export interface EmitWebhookEventOptions {
+  /**
+   * Restrict delivery to exactly this one install — the event's subject.
+   * REQUIRED for `app.installed`/`app.uninstalled` (see
+   * {@link LIFECYCLE_TOPICS}); omit for a tenant-wide data-topic fan-out.
+   */
+  installId?: string;
+  /** Override for a future contract version bump. Defaults to {@link DATASCHEMA_VERSION}. */
+  dataschemaVersion?: string;
+}
+
+/** `null` when no install on the tenant was eligible — not an error; no event/delivery rows are written in that case. */
+export type EmitWebhookEventResult = { eventId: string; deliveryCount: number } | null;
+
+/**
+ * Topics that are inherently about ONE subject install, never a tenant-wide
+ * broadcast — `emitWebhookEvent` refuses to run one of these without
+ * `opts.installId` (see the header + the guard below).
+ */
+const LIFECYCLE_TOPICS: ReadonlySet<WebhookTopic> = new Set(["app.installed", "app.uninstalled"]);
+
+/**
+ * An install is eligible for `topic` when it has a webhook endpoint and
+ * carries the topic's required scope, if any, and — with one exception — is
+ * `active`. `app.uninstalled` waives the active check: it's the defined
+ * farewell event, fired AFTER `registry.uninstall()` has already flipped the
+ * install to `uninstalled`, so requiring `active` here would mean it never
+ * fires at all. It does NOT waive the endpoint requirement.
+ */
+function isEligibleTarget(install: AppInstall, topic: WebhookTopic): boolean {
+  if (!install.webhookEndpoint) return false;
+  if (install.status !== "active" && topic !== "app.uninstalled") return false;
+  const requiredScope = TOPIC_REQUIRED_SCOPE[topic];
+  return requiredScope == null || install.scopes.includes(requiredScope);
+}
+
+/** Swallow-and-log a soft failure — logging itself must never throw. Same `[diag:...]` shape as `grants/developerInvites.ts`. */
+function logDiag(fields: Record<string, unknown>): void {
+  try {
+    console.warn("[diag:webhooks:emit]", JSON.stringify(fields));
+  } catch {
+    /* diagnostics must never break the caller */
+  }
+}
+
+/**
+ * Emit one webhook event for `tenantId`: resolve eligible installs, persist
+ * the event + one `pending` delivery per eligible install, then enqueue each
+ * delivery on the dispatcher. Returns `null` (not an error) when nothing on
+ * the tenant was eligible, when the runtime isn't configured for webhooks at
+ * all, or when a lifecycle topic was called without the required
+ * `opts.installId` (a caller bug — logged, never silently broadened to a
+ * tenant-wide broadcast).
+ */
+export async function emitWebhookEvent(
+  topic: WebhookTopic,
+  tenantId: string,
+  data: unknown,
+  opts: EmitWebhookEventOptions = {},
+): Promise<EmitWebhookEventResult> {
+  if (LIFECYCLE_TOPICS.has(topic) && !opts.installId) {
+    logDiag({ topic, tenantId, reason: "lifecycle_topic_requires_installId" });
+    return null;
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) {
+    logDiag({ topic, tenantId, reason: "storefront_apps_db_unconfigured" });
+    return null;
+  }
+  const store = new WebhookDeliveryStore(fromD1(d1));
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) {
+    // Shouldn't happen given the STOREFRONT_APPS_DB check above (same
+    // binding), but stay fail-closed rather than assume.
+    logDiag({ topic, tenantId, reason: "registry_unconfigured" });
+    return null;
+  }
+
+  // `listByTenant` is the tenant-ownership check for a given `installId`, for
+  // free: an install belonging to a different tenant simply never appears in
+  // `candidates`, so a cross-tenant `installId` yields zero eligible targets
+  // rather than leaking across tenants.
+  const candidates = await registry.listByTenant(tenantId);
+  const scoped = opts.installId ? candidates.filter((install) => install.installId === opts.installId) : candidates;
+  const eligible = scoped.filter((install) => isEligibleTarget(install, topic));
+  if (eligible.length === 0) return null;
+
+  const { event, deliveries } = await store.createEvent(
+    { tenantId, topic, dataschemaVersion: opts.dataschemaVersion ?? DATASCHEMA_VERSION, payload: data },
+    eligible.map((install) => ({ installId: install.installId })),
+  );
+
+  const dispatcher = await getDispatcher();
+  if (dispatcher instanceof Response) {
+    // The event + delivery rows are already persisted `pending` — nothing is
+    // lost, just not yet scheduled. A future scan/replay path (Chunk E) can
+    // still pick them up once the dispatcher IS configured.
+    logDiag({ topic, tenantId, eventId: event.id, deliveryCount: deliveries.length, reason: "dispatcher_unconfigured" });
+    return { eventId: event.id, deliveryCount: deliveries.length };
+  }
+
+  for (const delivery of deliveries) {
+    await dispatcher.enqueue({ deliveryId: delivery.deliveryId });
+  }
+
+  return { eventId: event.id, deliveryCount: deliveries.length };
+}

package/apps/storefront/src/lib/webhooks/endpointGuard.ts

@@ -0,0 +1,135 @@
+/**
+ * Webhook endpoint guard — PrivateApps epic, D4 SSRF hardening. The manifest
+ * schema (`docs/private-apps/contract/tot-app.schema.json`) promises
+ * `webhookEndpoint` is https-only; nothing enforced that promise at runtime
+ * until this guard existed. It is applied at two points:
+ *   - Write time (`../apps/registryService.ts`'s `install`/`update`) — refuse
+ *     to persist a bad endpoint at all (fail closed, no row written).
+ *   - Delivery time (`deliveryEngine.ts`, defense-in-depth) — re-checked right
+ *     before the signed POST, in case a row somehow predates this guard or a
+ *     future write path forgets to call it.
+ *
+ * `new URL()` does most of the hard work for us: it lowercases hostnames and
+ * canonicalizes IPv4 literals written in decimal/octal/hex/shorthand forms
+ * (`0x7f000001`, `017700000001`, `127.1`, …) all the way down to dotted-quad,
+ * and normalizes IPv6 literals to their shortest lowercase-hex form —
+ * including collapsing an embedded IPv4-mapped address (`::ffff:127.0.0.1`)
+ * into its hex-group equivalent. That means the range checks below only ever
+ * see canonical output, not every obfuscated spelling of the same address.
+ *
+ * RESIDUAL RISK — NOT defended here: DNS rebinding. A public hostname
+ * (`hooks.example.com`) can resolve to a private IP (`127.0.0.1`,
+ * `169.254.169.254`, …) at fetch time, after this check already passed
+ * against the literal hostname. Cloudflare Workers' `fetch()` doesn't expose
+ * or let a caller pin the resolved IP, so there is no hook here to catch
+ * that case — this guard is scheme + literal-host based only. A full fix
+ * would need a resolve-and-pin step or an egress proxy that resolves DNS
+ * itself and refuses to connect to a private target; neither exists yet.
+ * Tracked as a follow-up, not a V1 blocker.
+ */
+
+export type WebhookEndpointValidation = { ok: true } | { ok: false; reason: string };
+
+/** One IPv4 octet quartet, each 0-255. */
+type IPv4Octets = readonly [number, number, number, number];
+
+function parseIPv4(host: string): IPv4Octets | null {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])] as const;
+  return octets.every((o) => o <= 255) ? octets : null;
+}
+
+/** 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (incl. the 169.254.169.254 cloud metadata host), 0.0.0.0/8. */
+function isPrivateIPv4(octets: IPv4Octets): boolean {
+  const [a, b] = octets;
+  if (a === 127) return true;
+  if (a === 10) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 0) return true;
+  return false;
+}
+
+/** Expand a canonical (possibly `::`-compressed) IPv6 address into its 8 uint16 groups. */
+function parseIPv6Groups(addr: string): number[] | null {
+  const parts = addr.split("::");
+  if (parts.length > 2) return null;
+
+  const head = parts[0] ? parts[0].split(":") : [];
+  const tail = parts.length === 2 && parts[1] ? parts[1].split(":") : [];
+  const explicit = parts.length === 2 ? head.length + tail.length : head.length;
+  if (parts.length === 1 && explicit !== 8) return null;
+
+  const filled = parts.length === 2 ? 8 - explicit : 0;
+  if (filled < 0) return null;
+  const groups = [...head, ...Array(filled).fill("0"), ...tail];
+  if (groups.length !== 8) return null;
+
+  const values = groups.map((g) => Number.parseInt(g || "0", 16));
+  return values.every((v) => Number.isInteger(v) && v >= 0 && v <= 0xffff) ? values : null;
+}
+
+/** `::1` loopback, `::` unspecified, `fc00::/7` unique-local, `fe80::/10` link-local, and any IPv4-mapped form of an {@link isPrivateIPv4} address. */
+function isPrivateIPv6(groups: number[]): boolean {
+  if (groups.every((g) => g === 0)) return true; // ::
+  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return true; // ::1
+  if ((groups[0]! & 0xfe00) === 0xfc00) return true; // fc00::/7
+  if ((groups[0]! & 0xffc0) === 0xfe80) return true; // fe80::/10
+
+  // IPv4-mapped: ::ffff:0:0/96 — the last two groups are the mapped address.
+  if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff) {
+    const mapped: IPv4Octets = [
+      (groups[6]! >> 8) & 0xff,
+      groups[6]! & 0xff,
+      (groups[7]! >> 8) & 0xff,
+      groups[7]! & 0xff,
+    ];
+    if (isPrivateIPv4(mapped)) return true;
+  }
+  return false;
+}
+
+const PRIVATE_HOST_REASON = "endpoint cannot target a private, loopback, or link-local address";
+
+/**
+ * Validate an app-supplied `webhookEndpoint`. https-only, no IP-literal
+ * target in a private/loopback/link-local/reserved range (v4 or v6,
+ * including IPv4-mapped IPv6), and no `localhost`/`*.localhost` hostname.
+ * See the module header for what this deliberately does NOT cover.
+ */
+export function validateWebhookEndpoint(raw: string): WebhookEndpointValidation {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: "endpoint is not a valid URL" };
+  }
+
+  if (url.protocol !== "https:") {
+    return { ok: false, reason: "endpoint must use https" };
+  }
+
+  const hostname = url.hostname; // already lowercased by URL parsing
+  if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+    return { ok: false, reason: "endpoint cannot target localhost" };
+  }
+
+  const ipv4 = parseIPv4(hostname);
+  if (ipv4 && isPrivateIPv4(ipv4)) {
+    return { ok: false, reason: PRIVATE_HOST_REASON };
+  }
+
+  if (hostname.startsWith("[") && hostname.endsWith("]")) {
+    const groups = parseIPv6Groups(hostname.slice(1, -1));
+    // A hostname the URL parser accepted as `[...]` is a syntactically valid
+    // IPv6 literal; a parse failure here means our own expansion has a gap,
+    // not that the address is benign — fail closed rather than let it through.
+    if (!groups || isPrivateIPv6(groups)) {
+      return { ok: false, reason: PRIVATE_HOST_REASON };
+    }
+  }
+
+  return { ok: true };
+}

package/apps/storefront/src/lib/webhooks/events.ts

@@ -0,0 +1,98 @@
+/**
+ * CloudEvents envelope builder — PrivateApps epic, D4 (Chunk C). Builds the
+ * EXACT wire shape `docs/private-apps/contract/asyncapi.yaml`'s
+ * `CloudEventEnvelope` schema requires (field-for-field, including the
+ * CloudEvents extensions), plus `TOPIC_REQUIRED_SCOPE` — the topic→required-
+ * scope map from `docs/private-apps/api-event-reference.md` §"Scope →
+ * endpoint / topic matrix", which `events.test.ts` checks against that table
+ * directly (no machine-readable topic-scope JSON exists, unlike
+ * `scopes.json`) — same drift-proofing discipline `scopes.test.ts` uses for
+ * `V1_SCOPES` vs. `contract/scopes.json`.
+ */
+import type { WebhookTopic } from "./deliveryStore.js";
+
+export const CLOUDEVENTS_SPECVERSION = "1.0";
+export const CLOUDEVENTS_DATACONTENTTYPE = "application/json";
+
+/**
+ * Required scope per topic (asyncapi.yaml channel descriptions +
+ * api-event-reference.md's topic matrix). `null` = no event scope gates it —
+ * `app.installed`/`app.uninstalled` deliver to any install with a webhook
+ * endpoint, per "(any valid token)" in the matrix.
+ */
+export const TOPIC_REQUIRED_SCOPE: Record<WebhookTopic, string | null> = {
+  "app.installed": null,
+  "app.uninstalled": null,
+  "catalog.product.updated": "catalog:read",
+  "inventory.changed": "inventory:read",
+  "order.created": "orders:webhook",
+  "order.fulfilled": "orders:webhook",
+  "customer.marketing_consent.updated": "customers:read:minimal",
+  "attribution.finalized": "attribution:write",
+};
+
+/** `type`'s reverse-DNS prefix (asyncapi.yaml `CloudEventEnvelope.type`). */
+export function eventType(topic: WebhookTopic): string {
+  return `com.tokenoftrust.storefront.${topic}`;
+}
+
+/** `source` — the emitting gateway + tenant (asyncapi.yaml: e.g. `/tenants/acme/storefront`). */
+export function envelopeSource(tenantId: string): string {
+  return `/tenants/${tenantId}/storefront`;
+}
+
+export interface BuildEnvelopeInput {
+  /** The wire `id` — this delivery's id, stable across its own retries (never the eventId). */
+  deliveryId: string;
+  tenantId: string;
+  topic: WebhookTopic;
+  dataschemaVersion: string;
+  /** The event-specific payload — opaque here, shaped by `topic` (OrderData, etc. in the contract). */
+  data: unknown;
+  appInstallId: string;
+  /** Delivery attempt count so far, 0 on the first attempt (CloudEvents `retrycount` extension). */
+  retryCount: number;
+  /** Correlation extensions — omitted from the envelope entirely when not supplied. */
+  totRequestId?: string;
+  traceparent?: string;
+  /** Injected clock; defaults to `Date`. Override in tests for a deterministic `time`. */
+  now?: () => Date;
+}
+
+/** Mirrors `asyncapi.yaml`'s `CloudEventEnvelope` schema exactly — required + optional extension fields. */
+export interface CloudEventEnvelope {
+  specversion: "1.0";
+  id: string;
+  source: string;
+  type: string;
+  time: string;
+  datacontenttype: "application/json";
+  dataschemaversion: string;
+  tenantid: string;
+  appinstallid: string;
+  retrycount: number;
+  totrequestid?: string;
+  traceparent?: string;
+  data: unknown;
+}
+
+/** Build one delivery's CloudEvents envelope. Never adds anything beyond `data` — payload minimization is the emitter's (Chunk D's) job. */
+export function buildCloudEventEnvelope(input: BuildEnvelopeInput): CloudEventEnvelope {
+  const now = input.now ?? (() => new Date());
+  const envelope: CloudEventEnvelope = {
+    specversion: CLOUDEVENTS_SPECVERSION,
+    id: input.deliveryId,
+    source: envelopeSource(input.tenantId),
+    type: eventType(input.topic),
+    time: now().toISOString(),
+    datacontenttype: CLOUDEVENTS_DATACONTENTTYPE,
+    dataschemaversion: input.dataschemaVersion,
+    tenantid: input.tenantId,
+    appinstallid: input.appInstallId,
+    retrycount: input.retryCount,
+    data: input.data,
+  };
+  if (input.totRequestId) envelope.totrequestid = input.totRequestId;
+  if (input.traceparent) envelope.traceparent = input.traceparent;
+  return envelope;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Composition root for the webhook dispatcher — PrivateApps epic, D4 (Chunk
+ * C). Mirrors `../apps/adminService.ts`'s `getRegistryService()`: builds the
+ * real `WebhookDeliveryStore` + `AppRegistryService` over the
+ * `STOREFRONT_APPS_DB` binding, wires them into `attemptDelivery` as the `AttemptDeliveryFn` every
+ * dispatcher implementation runs per job, and returns the SAME 503-when-
+ * unconfigured `Response` shape `getRegistryService()` does when that binding
+ * is missing.
+ *
+ * Selects the dispatcher implementation by binding presence:
+ * `env.WEBHOOK_DELIVERY_QUEUE` present → `CloudflareQueueDispatcher`, else
+ * `InMemoryDispatcher` — V1's actual production path (no `[[queues]]` binding
+ * is declared in `wrangler.toml` yet, so the Cloudflare branch is unreachable
+ * until infra provisions one; see `dispatcher.ts`'s header for the full
+ * design-resolution + entry-wiring context).
+ */
+import { WebhookDeliveryStore } from "./deliveryStore.js";
+import { attemptDelivery } from "./deliveryEngine.js";
+import { InMemoryDispatcher, type AttemptDeliveryFn, type WebhookDispatcher } from "./dispatcher.js";
+import { CloudflareQueueDispatcher, type CloudflareQueueSender } from "./cloudflareQueueDispatcher.js";
+import { AppRegistryService } from "../apps/registryService.js";
+import { D1CredentialStore } from "../apps/credentials.js";
+import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "../apps/gatewayKeys.js";
+import { json } from "../apps/adminService.js";
+import { fromD1 } from "../d1/catalog.js";
+import { readD1, readEnv, readQueue } from "../env.js";
+
+/** Binding name `getDispatcher()` checks to pick the Cloudflare Queues adapter. Not yet declared in `wrangler.toml`. */
+export const WEBHOOK_QUEUE_BINDING = "WEBHOOK_DELIVERY_QUEUE";
+
+/**
+ * Build a `WebhookDispatcher` over the real `STOREFRONT_APPS_DB` binding, or
+ * return a 503 `Response` when that binding isn't configured in this
+ * runtime — same fail-closed shape as `getRegistryService()`.
+ */
+export async function getDispatcher(): Promise<WebhookDispatcher | Response> {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  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 queueSender = (await readQueue(WEBHOOK_QUEUE_BINDING)) as CloudflareQueueSender | undefined;
+  if (queueSender) return new CloudflareQueueDispatcher(queueSender);
+  return new InMemoryDispatcher(attempt);
+}

package/apps/storefront/src/lib/webhooks/signing.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP Message Signatures (RFC 9421) + Content-Digest (RFC 9530) signer for
+ * outbound webhook delivery (PrivateApps epic, D4 Chunk B).
+ *
+ * The implementation MOVED to `@tokenoftrust/private-apps-devkit`
+ * (PrivateApps epic D6 Chunk B) so the `tot app` CLI harness (D6 Chunk D) can
+ * verify webhook signatures without importing Astro-internal code — without
+ * forking security-critical crypto into a second, drifting copy. This file
+ * is now a thin re-export; the devkit package is the ONE source of truth.
+ * See `packages/private-apps-devkit/src/signing.ts` for the full scope
+ * notes (hand-rolled/narrowly-scoped, not a general httpsig implementation)
+ * and `packages/private-apps-devkit/tests/signing.test.ts` for the RFC-vector
+ * proofs. `signing.test.ts` alongside this file still imports from here —
+ * unchanged — so it now exercises those same functions through this
+ * re-export.
+ */
+export {
+  SIGNATURE_LABEL,
+  WEBHOOK_SIGNATURE_COVERED_COMPONENTS,
+  computeContentDigestSha256,
+  buildSignatureParamsValue,
+  buildSignatureBase,
+  signWebhookRequest,
+  verifyWebhookSignature,
+  type SignWebhookRequestInput,
+  type SignWebhookRequestResult,
+  type WebhookVerifyResult,
+  type VerifyWebhookSignatureInput,
+} from "@tokenoftrust/private-apps-devkit";