@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/apps/storefront/src/lib/tracking/tenantReadAccess.ts

@@ -0,0 +1,138 @@
+/**
+ * Merchant-facing READ authorization over the per-tenant interaction D1
+ * databases `dt-storage-per-tenant-d1` built (`tenantD1Registry.ts`,
+ * `interactionStore.ts`). This is `dt-tenant-isolation`: the release-order
+ * doc's hard invariant is "no merchant-visible surface ships until this
+ * lands", and this module is that surface's data-access layer.
+ *
+ * THE ISOLATION GUARANTEE THIS MODULE RELIES ON (built by
+ * `dt-storage-per-tenant-d1`, not re-implemented here): `resolveTenantStore`
+ * is the ONLY way to get a `Queryable`, and it is bound to exactly one
+ * tenant's database UUID. There is no handle anywhere that spans two
+ * tenants' rows, so every function below is safe to call with an UNSCOPED
+ * `SELECT` — the database itself is the isolation boundary, not the `WHERE`
+ * clause. A `tenant_id = ?` predicate is still included below (matching the
+ * `TenantInteractionStore.tenantId` the caller resolved — NEVER a
+ * client-suppliable value) as defence-in-depth and to keep the row's
+ * redundant `tenant_id` column meaningful, not because it is what makes the
+ * isolation hold.
+ *
+ * `assertStoreOwnership` is the extra check this unit adds on top: before
+ * trusting a resolved store for a read, confirm `interaction_store_meta`
+ * (stamped by `dt-storage-per-tenant-d1` at provision time) actually says
+ * this database belongs to the tenant we resolved it for. A resolution bug
+ * that somehow handed back the wrong store is caught here rather than
+ * silently serving the wrong tenant's rows to a merchant.
+ */
+import type { TenantInteractionStore } from "./tenantD1Registry.js";
+
+/** One row of the merchant-visible recent-events feed. */
+export interface RecentInteractionEvent {
+  type: string;
+  el: string;
+  action: string | null;
+  placement: string | null;
+  scope: string | null;
+  ts: string;
+  ingestedAt: string;
+}
+
+/** One rolled-up (action, el) count — the merchant-visible summary shape. */
+export interface InteractionActionCount {
+  el: string;
+  action: string;
+  count: number;
+}
+
+export interface InteractionInsights {
+  totalEvents: number;
+  byAction: InteractionActionCount[];
+  recent: RecentInteractionEvent[];
+}
+
+/** Cap on the recent-events feed — a dashboard preview, not an export. */
+const DEFAULT_RECENT_LIMIT = 50;
+const MAX_RECENT_LIMIT = 200;
+
+/**
+ * Confirm a resolved store's `interaction_store_meta` row actually names the
+ * tenant we resolved it for. Returns `false` (never throws) on any mismatch,
+ * a missing meta row, or a query failure — all fail-closed: the caller must
+ * treat that as "cannot verify this store, do not read from it."
+ */
+export async function assertStoreOwnership(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+): Promise<boolean> {
+  try {
+    const meta = await store.db.first<{ tenant_id: string }>(
+      `SELECT tenant_id FROM interaction_store_meta WHERE id = 1`,
+    );
+    return !!meta && meta.tenant_id === store.tenantId;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recent raw events for ONE tenant's own store, newest first. Scoped to the
+ * resolved store's database (the isolation boundary) AND to its
+ * `tenantId` (defence-in-depth) — there is no parameter here through which a
+ * caller can ask for a different tenant's rows; the only tenant this can
+ * ever return is the one `store` was resolved for.
+ */
+export async function readRecentInteractionEvents(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+  opts?: { limit?: number },
+): Promise<RecentInteractionEvent[]> {
+  const limit = Math.max(1, Math.min(opts?.limit ?? DEFAULT_RECENT_LIMIT, MAX_RECENT_LIMIT));
+  return store.db.all<RecentInteractionEvent>(
+    `SELECT type, el, action, placement, scope, ts, ingested_at AS ingestedAt
+       FROM interaction_events
+      WHERE tenant_id = ?
+      ORDER BY ingested_at DESC
+      LIMIT ?`,
+    store.tenantId,
+    limit,
+  );
+}
+
+/**
+ * Simple aggregate over ONE tenant's own store: total row count + a rollup by
+ * (el, action). Mirrors the AE dimension tuple's spirit but computed directly
+ * off the tenant's own raw rows, scoped the same way as
+ * {@link readRecentInteractionEvents}.
+ */
+export async function readInteractionSummary(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+): Promise<{ totalEvents: number; byAction: InteractionActionCount[] }> {
+  const totalRow = await store.db.first<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM interaction_events WHERE tenant_id = ?`,
+    store.tenantId,
+  );
+  const byAction = await store.db.all<InteractionActionCount>(
+    `SELECT el, COALESCE(action, '') AS action, COUNT(*) AS count
+       FROM interaction_events
+      WHERE tenant_id = ?
+      GROUP BY el, action
+      ORDER BY count DESC`,
+    store.tenantId,
+  );
+  return { totalEvents: totalRow?.n ?? 0, byAction };
+}
+
+/**
+ * The full merchant-visible read: ownership-asserted, then summary + recent
+ * feed off the SAME scoped store. Returns `undefined` when the store fails
+ * the ownership assertion — fail-closed, never a partial/best-guess result.
+ */
+export async function readTenantInteractionInsights(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+  opts?: { limit?: number },
+): Promise<InteractionInsights | undefined> {
+  if (!(await assertStoreOwnership(store))) return undefined;
+  const [summary, recent] = await Promise.all([
+    readInteractionSummary(store),
+    readRecentInteractionEvents(store, opts),
+  ]);
+  return { totalEvents: summary.totalEvents, byAction: summary.byAction, recent };
+}

package/apps/storefront/src/lib/tracking-writeback/rewriteTrackingIds.ts

@@ -0,0 +1,175 @@
+/**
+ * `data-tot-el` writeback (dt-id-writeback) — the git-time rewriter that turns
+ * `tracking-id-derivation.ts`'s PROPOSALS into an actual attribute in a tenant's
+ * source HTML, so a human reviews and accepts a real diff (never a silent
+ * runtime mutation). Mirrors the pattern `the-build/toc.ts` already uses for
+ * heading anchors: parse5 fragment/document tree, mutate in place, re-`serialize()`
+ * ONLY when something actually changed (byte-preserving otherwise).
+ *
+ * Scope: tenant-authored BODY documents only (`content/home.html`,
+ * `content/<tenant>/pages-html/<slug>.html`) — never governed chrome, which
+ * `trackingAttributes()` / `trackingAttributesHtml()` already stamp via a
+ * separate, non-derived path (`dt-stamp-chrome-nav`). This module does not know
+ * about chrome and must never be pointed at `chrome.html` / `chrome.json`.
+ *
+ * Contract: docs/architecture/interaction-tracking-attribute-contract.md
+ * ("Deriving `data-tot-el`").
+ */
+import { parse, parseFragment, serialize } from "parse5";
+import {
+  createTrackingIdDeriver,
+  isTrackableNode,
+  TRACKING_ATTR_EL,
+  type DerivationOptions,
+  type DerivationConfidence,
+  type StructuralNode,
+} from "@tot/public-runtime";
+
+/** Minimal structural view of a parse5 node (duck-typed, as toc.ts does). */
+interface P5Attr {
+  name: string;
+  value: string;
+}
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  attrs?: P5Attr[];
+  childNodes?: P5Node[];
+}
+
+/** One proposed (or already-declared) `data-tot-el` this pass encountered. */
+export interface TrackingWritebackProposal {
+  /** The proposed (or, for a `"declared"` row, the pre-existing) value. */
+  el: string;
+  confidence: DerivationConfidence;
+  /** Most-significant-first, per `DerivedTrackingId.signals` — the diff annotation. */
+  signals: readonly string[];
+  /** True iff a human should name this element before accepting the diff. */
+  needsReview: boolean;
+  /** True iff `data-tot-el` was ALREADY present (nothing written; verbatim). */
+  alreadyDeclared: boolean;
+  /** The element's tag, for the review listing. */
+  tag: string;
+  /** A short open-tag snippet (no children) so a reviewer can locate the element. */
+  snippet: string;
+}
+
+export interface TrackingWritebackResult {
+  /** The (possibly) rewritten source. Byte-identical to the input when `changed` is false. */
+  html: string;
+  /** True iff at least one element gained a new `data-tot-el`. */
+  changed: boolean;
+  /** Every candidate element seen, in document order — declared rows included. */
+  proposals: TrackingWritebackProposal[];
+}
+
+function attrsToRecord(attrs?: P5Attr[]): Record<string, string> | undefined {
+  if (!attrs || attrs.length === 0) return undefined;
+  const rec: Record<string, string> = {};
+  for (const a of attrs) rec[a.name] = a.value;
+  return rec;
+}
+
+function toStructuralNode(node: P5Node): StructuralNode {
+  return { tag: (node.tagName ?? "").toLowerCase(), attrs: attrsToRecord(node.attrs) };
+}
+
+function openTagSnippet(node: StructuralNode): string {
+  const attrs = node.attrs ?? {};
+  const parts = Object.entries(attrs)
+    .filter((entry): entry is [string, string] => typeof entry[1] === "string")
+    .map(([k, v]) => `${k}="${v}"`);
+  return `<${node.tag}${parts.length ? " " + parts.join(" ") : ""}>`;
+}
+
+function isElement(node: P5Node): node is P5Node & { tagName: string } {
+  return typeof node.tagName === "string" && node.tagName.length > 0;
+}
+
+/** Every `data-tot-el` value anywhere in the tree, in document order — the
+ * pre-existing identities a fresh proposal must never collide with, per the
+ * derivation engine's own handoff ("reserve() every id already in the source,
+ * BEFORE deriving"). Deliberately unfiltered by {@link isTrackableNode}: a
+ * hand-authored id on an element this pass wouldn't otherwise touch still
+ * occupies the namespace. */
+function* declaredIds(root: P5Node): Generator<string> {
+  for (const child of root.childNodes ?? []) {
+    if (isElement(child)) {
+      const value = child.attrs?.find((a) => a.name === TRACKING_ATTR_EL)?.value?.trim();
+      if (value) yield value;
+    }
+    yield* declaredIds(child);
+  }
+}
+
+/**
+ * Walk the tree in document order, yielding every trackable element with its
+ * ancestor stack (OUTERMOST first — the derivation engine's own contract).
+ */
+function* candidates(
+  root: P5Node,
+  ancestors: readonly P5Node[] = [],
+): Generator<{ node: P5Node; ancestors: readonly P5Node[] }> {
+  for (const child of root.childNodes ?? []) {
+    if (isElement(child)) {
+      if (isTrackableNode(toStructuralNode(child))) {
+        yield { node: child, ancestors };
+      }
+      yield* candidates(child, [...ancestors, child]);
+    } else {
+      yield* candidates(child, ancestors);
+    }
+  }
+}
+
+/** Whether `html` looks like a full document (vs. a body-only fragment). */
+function isFullDocument(html: string): boolean {
+  return /^\s*(<!doctype\s|<html[\s>])/i.test(html);
+}
+
+/**
+ * Propose (and write) `data-tot-el` for every undeclared trackable element in
+ * `html`. Pure: no I/O, no network. `confidence: "declared"` elements are
+ * returned in `proposals` for a complete review listing but are NEVER mutated —
+ * a declared identity is permanent (per the derivation engine's own contract).
+ *
+ * `html` may be a full tenant document (`content/home.html`, doctype + `<html>`)
+ * or a body-only fragment (`content/<tenant>/pages-html/<slug>.html`) — detected
+ * automatically so one function serves both writeback call sites.
+ */
+export function deriveTrackingWriteback(
+  html: string,
+  options?: DerivationOptions,
+): TrackingWritebackResult {
+  const fullDocument = isFullDocument(html);
+  const root = (fullDocument ? parse(html) : parseFragment(html)) as unknown as P5Node;
+
+  const deriver = createTrackingIdDeriver(options);
+  for (const id of declaredIds(root)) deriver.reserve(id);
+
+  const proposals: TrackingWritebackProposal[] = [];
+  let changed = false;
+
+  for (const { node, ancestors } of candidates(root)) {
+    const structural = toStructuralNode(node);
+    const alreadyDeclared = Boolean(structural.attrs?.[TRACKING_ATTR_EL]?.trim());
+    const derived = deriver.derive({
+      node: structural,
+      ancestors: ancestors.map(toStructuralNode),
+    });
+    proposals.push({
+      el: derived.el,
+      confidence: derived.confidence,
+      signals: derived.signals,
+      needsReview: derived.needsReview,
+      alreadyDeclared,
+      tag: structural.tag,
+      snippet: openTagSnippet(structural),
+    });
+    if (alreadyDeclared) continue; // declared verbatim — never overwritten
+    node.attrs = [...(node.attrs ?? []), { name: TRACKING_ATTR_EL, value: derived.el }];
+    changed = true;
+  }
+
+  return { html: changed ? serialize(root as never) : html, changed, proposals };
+}

package/apps/storefront/src/lib/tracking-writeback/writebackCandidate.ts

@@ -0,0 +1,110 @@
+/**
+ * dt-id-writeback — turns {@link deriveTrackingWriteback} proposals for one or
+ * more tenant body documents into the SAME reviewable-candidate shape the admin
+ * Blog tab already rides (`pages/api/admin/blog.ts`): a content-only
+ * {@link FileChange} patch opened via `ChangeClient.openCandidate`, so a human
+ * reviews a real PR diff and accepts it — never a silent runtime mutation.
+ *
+ * This module is pure (no MCP call, no ChangeClient dependency) so the patch +
+ * PR body construction is unit-testable without a live forge; the route that
+ * calls `openCandidate` is a thin wrapper (see the sibling API route).
+ */
+import { deriveTrackingWriteback, type TrackingWritebackProposal } from "./rewriteTrackingIds.js";
+import type { DerivationOptions } from "@tot/public-runtime";
+
+/** One tenant body document to scan — repo-relative path + its current content. */
+export interface WritebackSourceFile {
+  /** e.g. "content/home.html" or "content/acme/pages-html/pricing.html". */
+  path: string;
+  content: string;
+}
+
+/** One file this writeback pass actually changed, plus its full proposal list. */
+export interface WritebackFileResult {
+  path: string;
+  content: string;
+  proposals: readonly TrackingWritebackProposal[];
+}
+
+export interface WritebackCandidatePlan {
+  /** Files that gained at least one new `data-tot-el` — the `FileChange` patch. */
+  patch: { path: string; content: string }[];
+  /** Every changed file's full proposal list, for the PR body + a caller's own reporting. */
+  files: WritebackFileResult[];
+  /** True iff `patch` is non-empty — nothing to open when false. */
+  hasChanges: boolean;
+  /** Count of `needsReview: true` rows across every changed file — the review flag. */
+  needsReviewCount: number;
+}
+
+/**
+ * Run the derivation writeback over every source file and assemble the patch a
+ * candidate PR would carry. Files with no undeclared trackable elements (already
+ * fully migrated, or nothing trackable) are omitted from `patch` entirely — this
+ * never proposes a no-op change.
+ */
+export function planTrackingWriteback(
+  sources: readonly WritebackSourceFile[],
+  options?: DerivationOptions,
+): WritebackCandidatePlan {
+  const files: WritebackFileResult[] = [];
+  const patch: { path: string; content: string }[] = [];
+  let needsReviewCount = 0;
+
+  for (const source of sources) {
+    const result = deriveTrackingWriteback(source.content, options);
+    if (!result.changed) continue;
+    files.push({ path: source.path, content: result.html, proposals: result.proposals });
+    patch.push({ path: source.path, content: result.html });
+    needsReviewCount += result.proposals.filter((p) => p.needsReview && !p.alreadyDeclared).length;
+  }
+
+  return { patch, files, hasChanges: patch.length > 0, needsReviewCount };
+}
+
+/**
+ * Render the candidate PR's body: a per-file listing of every NEWLY-assigned
+ * `data-tot-el`, with `needsReview: true` rows called out in their own section
+ * (per the derivation engine's own design intent — a positional id is the one a
+ * human should rename before accepting). `signals` is the diff annotation.
+ */
+export function formatWritebackReviewBody(plan: WritebackCandidatePlan): string {
+  const lines: string[] = [
+    "Derived `data-tot-el` identity for tenant-authored body elements that had none.",
+    "`confidence: \"declared\"` elements are untouched (never overwritten).",
+    "",
+  ];
+
+  const needsReview = plan.files.flatMap((f) =>
+    f.proposals
+      .filter((p) => p.needsReview && !p.alreadyDeclared)
+      .map((p) => ({ file: f.path, proposal: p })),
+  );
+
+  if (needsReview.length > 0) {
+    lines.push(
+      `## ⚠ Needs review — ${needsReview.length} element${needsReview.length === 1 ? "" : "s"} named by position`,
+      "",
+      "These derived ids leaned on sibling order (no author-chosen name, class, or link found). " +
+        "Rename them to something meaningful before accepting.",
+      "",
+    );
+    for (const { file, proposal } of needsReview) {
+      lines.push(`- \`${file}\`: \`${proposal.el}\` — ${proposal.snippet} _(${proposal.signals.join(", ")})_`);
+    }
+    lines.push("");
+  }
+
+  for (const file of plan.files) {
+    const assigned = file.proposals.filter((p) => !p.alreadyDeclared);
+    if (assigned.length === 0) continue;
+    lines.push(`## \`${file.path}\` — ${assigned.length} id${assigned.length === 1 ? "" : "s"} assigned`, "");
+    for (const p of assigned) {
+      const flag = p.needsReview ? "⚠ " : "";
+      lines.push(`- ${flag}\`${p.el}\` (${p.confidence}) — ${p.snippet} _(${p.signals.join(", ")})_`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}

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

@@ -24,8 +24,6 @@
  */
 import { WebhookDeliveryStore, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
-import { loadWebhookSigningConfig, type WebhookSigningConfig } from "./webhookSigningKey.js";
-import { signWebhookRequest, type SignWebhookRequestResult } from "./signing.js";
 import { buildCloudEventEnvelope } from "./events.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
@@ -33,6 +31,28 @@ import { validateWebhookEndpoint } from "./endpointGuard.js";
 /** Bounded per-attempt timeout — a hung receiver must not hold a dispatcher slot open indefinitely. */
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+// Both signing.js and webhookSigningKey.js ultimately re-export from
+// @tokenoftrust/private-apps-devkit, a workspace-only package never vendored
+// into the public storefront-runner — a static import of either (type-only
+// included: `tsc` resolves a module for `import type` too) would be a
+// dangling import in that build. The VALUES are loaded via dynamic import at
+// their call sites below (see attemptDelivery/deliverSigned); these two
+// shapes are duplicated here, type-only, so this module's own types don't
+// need those files to exist in the runner. Keep in sync with
+// webhookSigningKey.ts's WebhookSigningConfig and
+// private-apps-devkit/src/signing.ts's SignWebhookRequestResult.
+interface WebhookSigningConfig {
+  key: CryptoKey;
+  kid: string;
+}
+interface SignWebhookRequestResult {
+  headers: {
+    "content-digest": string;
+    "signature-input": string;
+    signature: string;
+  };
+}
+
 /** The minimal registry seam the engine needs: resolving the target install by id. Satisfied by `AppRegistryService`. */
 export interface InstallResolver {
   get(installId: string): Promise<AppInstall | null>;
@@ -83,7 +103,17 @@ export async function attemptDelivery(deliveryId: string, deps: AttemptDeliveryD
   const now = deps.now ?? (() => new Date());
   const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const fetchImpl = deps.fetchImpl ?? fetch;
-  const loadSigningConfig = deps.loadSigningConfig ?? loadWebhookSigningConfig;
+  const loadSigningConfig =
+    deps.loadSigningConfig ??
+    (async () => {
+      // Absent from the public storefront-runner (dropped; see WebhookSigningConfig above).
+      // ts-ignore, not ts-expect-error: this module DOES exist in the full repo's own
+      // typecheck (only missing from the runner-extracted tree), so there's no error to
+      // "expect" here in that context — ts-expect-error would itself error as unused.
+      // @ts-ignore
+      const mod = await import("./webhookSigningKey.js");
+      return mod.loadWebhookSigningConfig() as Promise<WebhookSigningConfig>;
+    });
 
   const delivery = await store.getDelivery(deliveryId);
   if (!delivery) {
@@ -172,7 +202,11 @@ async function deliverSigned(
     now: ctx.now,
   });
   const body = JSON.stringify(envelope);
-  const { headers } = await signWebhookRequest({
+  // Absent from the public storefront-runner (dropped; see SignWebhookRequestResult above);
+  // ts-ignore not ts-expect-error, same reasoning as loadSigningConfig above.
+  // @ts-ignore
+  const { signWebhookRequest } = await import("./signing.js");
+  const { headers }: SignWebhookRequestResult = await signWebhookRequest({
     method: "POST",
     url: install.webhookEndpoint!,
     body,

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

@@ -48,7 +48,7 @@
 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 { getRegistryService } from "../apps/registryAccess.js";
 import type { AppInstall } from "../apps/registryService.js";
 import { fromD1 } from "../d1/catalog.js";
 import { readD1 } from "../env.js";

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

@@ -21,7 +21,7 @@ import { CloudflareQueueDispatcher, type CloudflareQueueSender } from "./cloudfl
 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 { json } from "../apps/registryAccess.js";
 import { fromD1 } from "../d1/catalog.js";
 import { readD1, readEnv, readQueue } from "../env.js";
 

package/apps/storefront/src/pages/api/admin/interaction-insights.ts

@@ -0,0 +1,101 @@
+/**
+ * `GET /api/admin/interaction-insights` — dt-tenant-isolation. The first
+ * merchant-visible read over the per-tenant declarative-interaction D1
+ * databases `dt-storage-per-tenant-d1` built. The release-order doc's hard
+ * invariant — "no merchant-visible surface ships until dt-tenant-isolation
+ * lands" — is this route: it is the read authorization layer, not a rebuild
+ * of the storage layer underneath it.
+ *
+ * AUTH mirrors `/api/admin/activity-alerts` and every other tenant-scoped
+ * admin JSON route: `requireAdminApiEntry` — fail-closed, bound to
+ * `Astro.locals.tenant` (Host-resolved, never client input). The tenant this
+ * route reads for is `context.locals.tenant.tenant_id`, ALWAYS — there is no
+ * code path here that reads a tenant id from the query string, the body, or
+ * any header, so a malicious/malformed request cannot make this route open a
+ * different tenant's database no matter what it sends.
+ *
+ * ISOLATION — `resolveTenantStore` (dt-storage-per-tenant-d1) returns a
+ * handle bound to exactly one tenant's database UUID; `assertStoreOwnership`
+ * (dt-tenant-isolation, `tenantReadAccess.ts`) additionally confirms the
+ * resolved store's own `interaction_store_meta` row names THIS tenant before
+ * any row is read. Every query in `tenantReadAccess.ts` runs against that one
+ * scoped handle — never a query spanning tenants.
+ *
+ * No cross-tenant ADMIN/operator path is added here. There is no concrete
+ * near-term consumer for "ToT ops views any tenant's interaction data" (the
+ * existing staff cross-vendor path — `staffAdmits`/`enter-vendor` — grants
+ * DASHBOARD entry to a vendor, not a bypass of this route's own tenant
+ * scoping) — see the unit's completion report for the reasoning.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import { readD1 } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { resolveTenantStore, trackingNamePrefix } from "@/lib/tracking/tenantD1Registry";
+import { readD1Control } from "@/lib/tracking/d1Control";
+import { readTenantInteractionInsights } from "@/lib/tracking/tenantReadAccess";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+/** Query-string cap on the recent-events feed; clamped again in tenantReadAccess. */
+const MAX_LIMIT = 200;
+
+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 access = await requireAdminApiEntry(context);
+  if (!access.ok) return json({ ok: false, reason: access.reason }, access.status);
+
+  // The ONLY tenant id this route ever uses. Host-resolved by tenant-routing
+  // middleware, never taken from `context.request` — see the module header.
+  const tenantId = context.locals.tenant?.tenant_id;
+  if (!tenantId) return json({ ok: false, status: "no_tenant", message: "no store resolved for this request" }, 400);
+
+  const rawLimit = Number(new URL(context.request.url).searchParams.get("limit") ?? "");
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, MAX_LIMIT) : undefined;
+
+  const [appsD1, control, namePrefix] = await Promise.all([
+    readD1("STOREFRONT_APPS_DB"),
+    readD1Control(),
+    trackingNamePrefix(),
+  ]);
+  if (!appsD1 || !control) {
+    // Sink not provisioned in this environment (local dev, an un-provisioned
+    // tier) — best-effort, same posture as activity-alerts' dbAvailable:false.
+    return json({ ok: true, dbAvailable: false, totalEvents: 0, byAction: [], recent: [] });
+  }
+
+  const store = await resolveTenantStore(tenantId, {
+    apps: fromD1(appsD1),
+    control,
+    namePrefix,
+    at: new Date().toISOString(),
+  });
+  if (!store) {
+    return json({ ok: true, dbAvailable: false, totalEvents: 0, byAction: [], recent: [] });
+  }
+
+  const insights = await readTenantInteractionInsights(store, { limit });
+  if (!insights) {
+    // Ownership assertion failed — fail-closed, never serve a store we could
+    // not verify belongs to this tenant.
+    return json({ ok: false, status: "store_unverified", message: "could not verify tenant store ownership" }, 503);
+  }
+
+  return json({
+    ok: true,
+    dbAvailable: true,
+    tenantId,
+    totalEvents: insights.totalEvents,
+    byAction: insights.byAction,
+    recent: insights.recent,
+  });
+}

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -25,7 +25,7 @@ import {
 } from "@/lib/auth/identityToken";
 import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
 import { normalizeEmailHint } from "@/lib/privacy/emailHint";
-import { acceptDeveloperInvite } from "@/lib/grants/developerInvites";
+import { acceptDeveloperInvite } from "@/lib/shared/developerInvites";
 
 export const prerender = false;