@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/pages/api/activity.ts

@@ -0,0 +1,137 @@
+/**
+ * POST /api/activity — the ingest endpoint of the operational activity telemetry
+ * spine (card D4). Accepts one `ActivityEvent` (or a batch array) as JSON from
+ * the emitter cohorts — the CLI (D3) and the UI (D6), both posting the wire shape
+ * of `packages/public-runtime/src/activity/event.ts` — authenticates the caller,
+ * re-redacts server-side, and fans each accepted event out to the sink(s) its
+ * catalog entry declares. See DECISIONS.md §8 for the store decision.
+ *
+ * AUTH — HMAC-SHA256 service-auth (`src/lib/activity/ingestAuth.ts`). The caller
+ * presents the authenticated tenant in `x-tot-activity-tenant` and a hex
+ * signature over `<tenant>\n<rawBody>` in `x-tot-activity-signature`, keyed by
+ * the `ACTIVITY_INGEST_SECRET` Worker secret. Binding the tenant into the signed
+ * material is what makes the tenant scope trustworthy: the route writes every
+ * row under THIS verified tenant and discards any body-supplied `scope.tenantId`
+ * (multi-tenant isolation). An unset secret is a 503 (seam not configured — the
+ * same convention as the MCP webhook receivers), not an auth failure.
+ *
+ * DEFENSE IN DEPTH — every event is rebuilt through `createActivityEvent()`
+ * (`ingestEvents`), re-applying the default-deny allowlist + canary scan even
+ * though emitters already redacted. A value-canary trip is self-telemetried as
+ * `system.ingest.rejected` so a leak attempt is visible (D6/D7 alert on it).
+ *
+ * OFF THE CRITICAL PATH — auth + parse + validate + redact are cheap synchronous
+ * CPU; the sink WRITES (D1 + Analytics Engine) run past the response via
+ * `runAfterResponse` (Workers `waitUntil`). The response is a 202 with per-event
+ * accepted/rejected counts the instant validation is done — a slow D1 write never
+ * holds the emitter's request open. JSON bodies are exempt from Astro's CSRF
+ * origin check, so the server-to-server callers work.
+ */
+import type { APIContext } from "astro";
+import { readD1, readEnv, readAnalytics, runAfterResponse, type CfExecutionContextLike } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { verifyIngestAuth } from "@/lib/activity/ingestAuth";
+import { ingestEvents, type IngestRejection } from "@/lib/activity/ingest";
+import { fanOutActivity, type AnalyticsEngineLike, type ActivitySinks } from "@/lib/activity/store";
+import { isActivityDisabled } from "@/lib/activity/killSwitch";
+import { createActivityEvent } from "@tot/public-runtime";
+
+export const prerender = false;
+
+/** Cap the batch so a single POST can't fan out unbounded work past the response. */
+const MAX_BATCH = 200;
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    // Write-path ack — never cacheable. Mirrors the house convention.
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  // Kill switch (D8): telemetry off ⇒ accept-and-drop. Fail-open toward the EMITTER —
+  // a 202 (never a 4xx/5xx) so a CLI/UI poster never errors, retries, or is delayed by
+  // the switch; nothing is validated, stored, or fanned out.
+  if (isActivityDisabled()) {
+    return json({ ok: true, disabled: true, accepted: 0, rejected: [] }, 202);
+  }
+
+  const secret = await readEnv("ACTIVITY_INGEST_SECRET");
+  if (!secret) {
+    // Seam not configured (emitters don't post without the shared ingest secret).
+    return new Response("activity ingest not configured", { status: 503 });
+  }
+
+  // Read the RAW body once: it is both the auth material and the JSON payload.
+  const rawBody = await context.request.text();
+
+  const auth = await verifyIngestAuth(context.request.headers, rawBody, secret);
+  if (!auth.ok) return new Response(auth.reason, { status: auth.status });
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return json({ ok: false, reason: "invalid JSON body" }, 400);
+  }
+  const events = Array.isArray(parsed) ? parsed : [parsed];
+  if (events.length === 0) return json({ ok: true, accepted: 0, rejected: [] }, 202);
+  if (events.length > MAX_BATCH) {
+    return json({ ok: false, reason: `batch too large (max ${MAX_BATCH})` }, 413);
+  }
+
+  // Validate + re-redact under the AUTHENTICATED tenant (cheap, synchronous).
+  const { accepted, rejected } = ingestEvents(events, auth.tenantId);
+
+  // Resolve the sink bindings (absent in dev/until provisioned ⇒ that sink is
+  // skipped, never an error).
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  const analytics = (await readAnalytics("ACTIVITY_ANALYTICS")) as AnalyticsEngineLike | undefined;
+  const sinks: ActivitySinks = {
+    ...(d1 ? { db: fromD1(d1) } : {}),
+    ...(analytics ? { analytics } : {}),
+    ingestedAt: new Date().toISOString(),
+  };
+
+  // Self-telemetry: a value-canary trip during server-side redaction means an
+  // emitter leaked (or tried to leak) a secret/PII into the payload. Emit a
+  // `system.ingest.rejected` event (itself routed to logs+analytics) so D6/D7 can
+  // alert — the fact of the trip, the action, never the offending value. Rejected
+  // events get the same self-telemetry so a spoof/unknown-action attempt is
+  // visible. Built here (synchronously) but fanned out off-path below.
+  const selfTelemetry = [
+    ...accepted
+      .filter((a) => a.canaryTripped)
+      .map((a) =>
+        createActivityEvent({
+          action: "system.ingest.rejected",
+          actor: { kind: "system", id: "activity-ingest" },
+          source: "server",
+          outcome: { status: "refused", errorClass: "canary_tripped" },
+          scope: { tenantId: auth.tenantId },
+          payload: { args: { reason: "canary_tripped", attemptedAction: a.event.action } },
+        }).event,
+      ),
+    ...rejected.map((r: IngestRejection) =>
+      createActivityEvent({
+        action: "system.ingest.rejected",
+        actor: { kind: "system", id: "activity-ingest" },
+        source: "server",
+        outcome: { status: "refused", errorClass: r.reason },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { reason: r.reason, ...(r.attemptedAction ? { attemptedAction: r.attemptedAction } : {}) } },
+      }).event,
+    ),
+  ];
+
+  // Fan every accepted event + the self-telemetry out to its sinks, PAST the
+  // response. Best-effort per sink (never throws). The adapter's per-request
+  // ExecutionContext lives at `locals.runtime.ctx`; runAfterResponse floats the
+  // promise in dev/Node when it is absent.
+  const cfContext = (context.locals as { runtime?: { ctx?: CfExecutionContextLike } })?.runtime?.ctx ?? null;
+  const work = Promise.all([...accepted.map((a) => a.event), ...selfTelemetry].map((e) => fanOutActivity(e, sinks)));
+  runAfterResponse(work, cfContext);
+
+  return json({ ok: true, accepted: accepted.length, rejected }, 202);
+}

package/apps/storefront/src/pages/api/admin/activity-alerts.ts

@@ -0,0 +1,73 @@
+/**
+ * `GET /api/admin/activity-alerts` — the polled/on-demand surface for card D7's
+ * operational-activity alert conditions.
+ *
+ * On-demand by design (see `lib/activity/alerts.ts` header): D7 deliberately does
+ * NOT add a cron/scheduled runner (no established precedent for one in this repo).
+ * This route runs `checkActivityAlerts()` fresh on every call, so it doubles as:
+ *   (a) the data source for the `/admin/ops-timeline` alerts banner (that page
+ *       calls the same function directly, in-process — this route is for OTHER
+ *       callers), and
+ *   (b) a lightweight endpoint an external uptime/monitor tool can poll on an
+ *       interval, turning "on-demand" into "effectively continuous" without this
+ *       repo standing up its own scheduler.
+ *
+ * ACCESS CONTROL mirrors `/admin/ops-timeline` exactly (same owner/admin-of-tenant
+ * or ToT-staff gate via `resolveAdminEntry`/`resolveAdminTenantMode`) rather than a
+ * new service-secret seam — this repo's other machine-to-machine surfaces
+ * (candidate-reconcile, the activity ingest route) authenticate a SPECIFIC known
+ * caller (MCP, an emitter) via a shared secret; there is no such caller for
+ * "a monitor polls for alerts" yet, and inventing one is the "new notification
+ * infra" the card scopes OUT. An admin/staff session (the same one that already
+ * views ops-timeline) is the correct, already-available caller today.
+ *
+ * TENANT ISOLATION — scoped to `Astro.locals.tenant.tenant_id` exactly like
+ * ops-timeline; never a URL/query value.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { resolveAdminEntry } from "@/lib/auth/adminEntry";
+import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
+import { readD1 } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { checkActivityAlerts } from "@/lib/activity/alerts";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tenant } = context.locals;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
+  const viewerSession = await readViewerSession(context);
+  if (!viewerSession) return json({ ok: false, reason: "sign_in_required" }, 401);
+
+  const adminEntry = resolveAdminEntry({
+    record: viewerSession,
+    hostResource: tenant.appDomain,
+    nowSeconds,
+  });
+  const { isStaff } = resolveAdminTenantMode({
+    session: viewerSession,
+    adminAppTenant: tenant.appDomain,
+    requestedTarget: null,
+    nowSeconds,
+  });
+  const authorized = adminEntry.isOwnerViewer || isStaff;
+  if (!authorized) return json({ ok: false, reason: "not_authorized" }, 403);
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ ok: true, dbAvailable: false, alerts: [] });
+
+  const alerts = await checkActivityAlerts(fromD1(d1), tenant.tenant_id);
+  return json({ ok: true, dbAvailable: true, alerts });
+}

package/apps/storefront/src/pages/api/apps/admin/credentials/rotate.ts

@@ -24,6 +24,8 @@ import {
   json,
 } from "@/lib/apps/adminService.js";
 import { RegistryError } from "@/lib/apps/registryService.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -50,11 +52,35 @@ export async function POST(context: APIContext): Promise<Response> {
   const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
   if (owned instanceof Response) return owned;
 
+  // D10: acting cohort (merchant/admin), emitted source "server". SECURITY: the
+  // rotated secret (`issued.secret`) is NEVER placed in the payload — the allowlist
+  // names only the non-sensitive app handle (appId/env, from the owned install) +
+  // rotation time.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const issued = await registry.rotateCredentials(installId, auth.actor);
+    recordActivity({
+      action: "app.credential.rotated",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: owned.appId, env: owned.env, rotatedAt: new Date().toISOString() } },
+    });
     return json({ credential: { clientId: issued.clientId, secret: issued.secret } });
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.credential.rotated",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: owned.appId, env: owned.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/install.ts

@@ -13,6 +13,8 @@ import { resolveAdminSession } from "@/lib/apps/adminSession.js";
 import { getRegistryService, registryErrorResponse, json } from "@/lib/apps/adminService.js";
 import { RegistryError, type InstallInput } from "@/lib/apps/registryService.js";
 import { emitWebhookEvent } from "@/lib/webhooks/emit.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -75,6 +77,11 @@ export async function POST(context: APIContext): Promise<Response> {
   const registry = await getRegistryService();
   if (registry instanceof Response) return registry;
 
+  // D10: resolve the acting cohort ONCE (merchant/admin — a store owner managing
+  // their own app, or ToT staff operating-as). Emitted as source "server" (the
+  // app.* catalog source), best-effort, never alters control flow.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const result = await registry.install(input, { tenantId: auth.tenantId, actor: auth.actor });
     try {
@@ -92,9 +99,27 @@ export async function POST(context: APIContext): Promise<Response> {
         }),
       );
     }
+    recordActivity({
+      action: "app.install",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: input.appId, appVersion: input.appVersion, env: input.env } },
+    });
     return json(result, 201);
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.install",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: err.code === "scope_denied" ? "refused" : "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: input.appId, appVersion: input.appVersion, env: input.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/resume.ts

@@ -20,6 +20,8 @@ import {
   json,
 } from "@/lib/apps/adminService.js";
 import { RegistryError } from "@/lib/apps/registryService.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -46,11 +48,32 @@ export async function POST(context: APIContext): Promise<Response> {
   const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
   if (owned instanceof Response) return owned;
 
+  // D10: acting cohort (merchant/admin), emitted source "server" per the app.* catalog.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const install = await registry.resume(installId, auth.actor);
+    recordActivity({
+      action: "app.resume",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: owned.appId, env: owned.env } },
+    });
     return json({ install });
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.resume",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: err.code === "invalid_state" ? "refused" : "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: owned.appId, env: owned.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/suspend.ts

@@ -21,6 +21,8 @@ import {
   json,
 } from "@/lib/apps/adminService.js";
 import { RegistryError } from "@/lib/apps/registryService.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -47,11 +49,32 @@ export async function POST(context: APIContext): Promise<Response> {
   const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
   if (owned instanceof Response) return owned;
 
+  // D10: acting cohort (merchant/admin), emitted source "server" per the app.* catalog.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const install = await registry.suspend(installId, auth.actor);
+    recordActivity({
+      action: "app.suspend",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: owned.appId, env: owned.env } },
+    });
     return json({ install });
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.suspend",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: err.code === "invalid_state" ? "refused" : "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: owned.appId, env: owned.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/uninstall.ts

@@ -22,6 +22,8 @@ import {
 } from "@/lib/apps/adminService.js";
 import { RegistryError } from "@/lib/apps/registryService.js";
 import { emitWebhookEvent } from "@/lib/webhooks/emit.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -48,6 +50,10 @@ export async function POST(context: APIContext): Promise<Response> {
   const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
   if (owned instanceof Response) return owned;
 
+  // D10: acting cohort (merchant/admin), emitted source "server" per the app.*
+  // catalog. Best-effort, never alters control flow.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const install = await registry.uninstall(installId, auth.actor);
     try {
@@ -66,9 +72,27 @@ export async function POST(context: APIContext): Promise<Response> {
         }),
       );
     }
+    recordActivity({
+      action: "app.uninstall",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: owned.appId, env: owned.env } },
+    });
     return json({ install });
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.uninstall",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: owned.appId, env: owned.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/update.ts

@@ -21,6 +21,8 @@ import {
   json,
 } from "@/lib/apps/adminService.js";
 import { RegistryError, type AppInstallPatch } from "@/lib/apps/registryService.js";
+import { resolveUiActor } from "@/lib/activity/uiActor";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -93,11 +95,32 @@ export async function POST(context: APIContext): Promise<Response> {
   const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
   if (owned instanceof Response) return owned;
 
+  // D10: acting cohort (merchant/admin), emitted source "server" per the app.* catalog.
+  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
+
   try {
     const install = await registry.update(installId, patch, auth.actor);
+    recordActivity({
+      action: "app.update",
+      actor: activityActor,
+      source: "server",
+      outcome: { status: "succeeded" },
+      scope: { tenantId: auth.tenantId },
+      payload: { args: { appId: owned.appId, env: owned.env } },
+    });
     return json({ install });
   } catch (err) {
-    if (err instanceof RegistryError) return registryErrorResponse(err);
+    if (err instanceof RegistryError) {
+      recordActivity({
+        action: "app.update",
+        actor: activityActor,
+        source: "server",
+        outcome: { status: err.code === "invalid_state" ? "refused" : "failed", errorClass: err.code },
+        scope: { tenantId: auth.tenantId },
+        payload: { args: { appId: owned.appId, env: owned.env } },
+      });
+      return registryErrorResponse(err);
+    }
     throw err;
   }
 }

package/apps/storefront/src/pages/api/apps/admin/webhooks/deliveries/[deliveryId]/replay.ts

@@ -27,6 +27,7 @@ import { WebhookDeliveryStore } from "@/lib/webhooks/deliveryStore.js";
 import { getDispatcher } from "@/lib/webhooks/getDispatcher.js";
 import { fromD1 } from "@/lib/d1/catalog.js";
 import { readD1 } from "@/lib/env";
+import { resolveUiActor, recordUiActivity } from "@/lib/activity/uiActor";
 
 export const prerender = false;
 
@@ -55,5 +56,15 @@ export async function POST(context: APIContext): Promise<Response> {
   const requeued = await store.requeueForReplay(deliveryId);
   await dispatcher.enqueue({ deliveryId });
 
+  // D11: ops/support console replay. Resolve the acting cohort (admin/merchant per
+  // resolveOperatorSession) from the session; `surface: "admin"` disambiguates from the
+  // app-facing v1 call site that shares this key. deliveryId is the opaque wire id.
+  const activityActor = await resolveUiActor(context, {});
+  recordUiActivity(activityActor, {
+    action: "webhook.delivery.replayed",
+    outcome: { status: "succeeded" },
+    scope: { tenantId: auth.tenantId },
+    payload: { args: { deliveryId, surface: "admin" } },
+  });
   return json({ delivery: requeued }, 202);
 }

package/apps/storefront/src/pages/api/apps/internal/order-forward.ts

@@ -24,6 +24,7 @@ import {
   type OrderForwardInput,
 } from "@/lib/apps/orders/orderForwardReceiver.js";
 import type { OrderLineItem, OrderStatus } from "@/lib/apps/orders/ordersStore.js";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -168,5 +169,15 @@ export async function POST(context: APIContext): Promise<Response> {
   if (!d1) return json({ error: "orders store not configured" }, 503);
 
   const result = await receiveForwardedOrder(fromD1(d1), input);
+  // D11: HIGH-VOLUME machine action (the tot-foxycart forwarder, HMAC-authed) → analytics
+  // only, never timelined. Coarse dimensions only; customer/order ids never stored.
+  recordActivity({
+    action: "app.order.forwarded",
+    actor: { kind: "agent", id: "order-forwarder" },
+    source: "server",
+    outcome: { status: "succeeded" },
+    scope: { tenantId: input.tenantId },
+    payload: { args: { status: result.order.status, env: input.env, currency: input.currency } },
+  });
   return json({ ok: true, status: result.order.status, emitted: result.emitted }, 200);
 }

package/apps/storefront/src/pages/api/apps/v1/attribution.ts

@@ -18,6 +18,7 @@ import { checkIdempotency, computeBodyHash, recordIdempotency } from "@/lib/apps
 import { AppAttributionService, AttributionError } from "@/lib/apps/orders/attributionService.js";
 import { fromD1 } from "@/lib/d1/catalog.js";
 import { readD1 } from "@/lib/env";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -130,6 +131,14 @@ export async function POST(context: APIContext): Promise<Response> {
     });
   } catch (err) {
     if (err instanceof AttributionError) {
+      recordActivity({
+        action: "app.attribution.recorded",
+        actor: { kind: "agent", id: auth.install.installId },
+        source: "server",
+        outcome: { status: "failed", errorClass: err.code },
+        scope: { tenantId: auth.install.tenantId },
+        ...(parsed.campaign ? { payload: { args: { campaign: parsed.campaign } } } : {}),
+      });
       const status =
         err.code === "attribution_forbidden" ? 403 : err.code === "attribution_conflict" ? 409 : 400;
       return withRequestId(json({ error: err.message, code: err.code }, status), context);
@@ -138,5 +147,16 @@ export async function POST(context: APIContext): Promise<Response> {
   }
 
   await recordIdempotency(db, auth.install.installId, idempotencyKey, bodyHash, record);
+  // D11: HIGH-VOLUME machine action (an installed private app / external bot, app-JWT
+  // authed) → analytics only, never timelined. installId is an opaque, per-install handle
+  // (non-PII) — a good stable actor id. referralCode/customerHash are never stored.
+  recordActivity({
+    action: "app.attribution.recorded",
+    actor: { kind: "agent", id: auth.install.installId },
+    source: "server",
+    outcome: { status: "succeeded" },
+    scope: { tenantId: auth.install.tenantId },
+    ...(parsed.campaign ? { payload: { args: { campaign: parsed.campaign } } } : {}),
+  });
   return withRequestId(json(record, 201), context);
 }

package/apps/storefront/src/pages/api/apps/v1/webhooks/deliveries/[deliveryId]/replay.ts

@@ -27,6 +27,7 @@ import { toContractDelivery } from "@/lib/webhooks/deliveryMapper.js";
 import { getDispatcher } from "@/lib/webhooks/getDispatcher.js";
 import { fromD1 } from "@/lib/d1/catalog.js";
 import { readD1 } from "@/lib/env";
+import { recordActivity } from "@/lib/activity/recordActivity";
 
 export const prerender = false;
 
@@ -58,5 +59,16 @@ export async function POST(context: APIContext): Promise<Response> {
   const requeued = await store.requeueForReplay(deliveryId);
   await dispatcher.enqueue({ deliveryId });
 
+  // D11: the app-facing (install-owned, app-JWT authed) replay — the `agent` cohort. Same
+  // catalog key as the admin console call site; `surface: "v1"` disambiguates. installId
+  // is an opaque per-install handle; deliveryId is the opaque CloudEvents wire id.
+  recordActivity({
+    action: "webhook.delivery.replayed",
+    actor: { kind: "agent", id: auth.install.installId },
+    source: "server",
+    outcome: { status: "succeeded" },
+    scope: { tenantId: auth.install.tenantId },
+    payload: { args: { deliveryId, surface: "v1" } },
+  });
   return withRequestId(json(toContractDelivery(requeued), 202), context);
 }