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

package/apps/storefront/src/lib/analytics/webVitals.ts

@@ -0,0 +1,269 @@
+/**
+ * F14 — Field Web Vitals (Real User Monitoring).
+ *
+ * This is the BROWSER-side beacon that F16's `core-web-vitals` monitor names as
+ * its signal source ("F14 RUM beacon (web-vitals: LCP, INP, CLS)"). It measures
+ * the three Core Web Vitals from real visitors, buckets each sample into the
+ * SAME budgeted route id the lab harness uses (`classifyPath`, from
+ * `perfBudgets.ts`), rates it against the checked-in budget, and hands finished
+ * samples to a pluggable reporter — by default a single `navigator.sendBeacon`
+ * to the RUM sink.
+ *
+ * Why hand-rolled instead of the `web-vitals` npm package: the field metrics we
+ * need (LCP last-candidate, CLS session-window, INP high-percentile) are a small
+ * amount of `PerformanceObserver` code, and adding a runtime dep to every page's
+ * critical path to MEASURE the critical path is self-defeating. The measurement
+ * algorithms here mirror `web-vitals`' definitions (session-windowed CLS, the
+ * (n/50)th-worst interaction for INP) closely enough for a p75 regression gate;
+ * if we ever need attribution-grade precision, swap `startWebVitals` for the
+ * library behind the same `WebVitalsSample` contract and nothing downstream
+ * changes.
+ *
+ * Split for testability: everything above the `startWebVitals` line is PURE
+ * (no DOM, no `PerformanceObserver`) so `webVitals.test.ts` can exercise rating
+ * + bucketing in node; `startWebVitals` is the thin browser wiring, guarded so
+ * importing this module in a non-browser context (SSR, tests) is a no-op.
+ *
+ * Field CWV is emitted TWICE, deliberately: Cloudflare Web Analytics
+ * (PUBLIC_CF_ANALYTICS_TOKEN, Layout.astro) already gives aggregate field CWV;
+ * this beacon adds the PER-ROUTE-TEMPLATE breakdown the budget gate + the
+ * regression alert (`rumAlert.ts`) reason over, which CF's aggregate cannot.
+ */
+import { classifyPath, PERF_BUDGETS, type PerfBudgetManifest, type RouteClass } from "./perfBudgets.js";
+
+/** The three field metrics we collect. INP is field-only (no lab equivalent). */
+export type WebVitalName = "lcp" | "inp" | "cls";
+
+/** Google's CWV rating buckets. `good` is the budget; `poor` is the far edge. */
+export type WebVitalRating = "good" | "needs-improvement" | "poor";
+
+/**
+ * The upper edge of the `needs-improvement` band — i.e. the "poor" threshold —
+ * for each metric. These are Google's fixed CWV boundaries and are NOT in the
+ * budget manifest: the manifest owns the `good` line (our gate), while the
+ * `poor` line is an industry constant used only to label a sample's severity.
+ */
+export const CWV_POOR_THRESHOLDS: Readonly<Record<WebVitalName, number>> = {
+  lcp: 4000,
+  inp: 500,
+  cls: 0.25,
+};
+
+/** One finished field measurement, ready to send to the RUM sink. */
+export interface WebVitalsSample {
+  metric: WebVitalName;
+  /** Milliseconds for lcp/inp; unitless for cls. */
+  value: number;
+  rating: WebVitalRating;
+  /** Budgeted route bucket (or "other") — shared with the lab harness. */
+  route: RouteClass;
+  /** The pathname the sample was collected on (for debugging, not grouping). */
+  path: string;
+  /** Navigation type, when the browser exposes it (navigate|reload|back_forward). */
+  navigationType?: string;
+}
+
+/**
+ * Rate a raw metric value against the budget (the `good` line) and the fixed
+ * `poor` line. `<=` budget is good — the same comparison the lab gate uses, so
+ * a field sample and a lab measurement agree on where "good" ends.
+ */
+export function rateMetric(
+  metric: WebVitalName,
+  value: number,
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): WebVitalRating {
+  const goodMax =
+    metric === "lcp"
+      ? manifest.webVitals.lcpMs
+      : metric === "inp"
+        ? manifest.webVitals.inpMs
+        : manifest.webVitals.cls;
+  if (value <= goodMax) return "good";
+  if (value <= CWV_POOR_THRESHOLDS[metric]) return "needs-improvement";
+  return "poor";
+}
+
+/** Build a finished sample from a raw reading (pure — used by the collector + tests). */
+export function toSample(
+  metric: WebVitalName,
+  value: number,
+  path: string,
+  navigationType?: string,
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): WebVitalsSample {
+  // CLS is unitless and small; round to 4dp. Timings round to whole ms.
+  const rounded = metric === "cls" ? Math.round(value * 1e4) / 1e4 : Math.round(value);
+  return {
+    metric,
+    value: rounded,
+    rating: rateMetric(metric, rounded, manifest),
+    route: classifyPath(path, manifest),
+    path,
+    ...(navigationType ? { navigationType } : {}),
+  };
+}
+
+/** A sink for finished samples. The default posts a JSON beacon to `endpoint`. */
+export type WebVitalsReporter = (sample: WebVitalsSample) => void;
+
+/** Where the browser beacon POSTs field samples. Kept here so the sink owns it. */
+export const RUM_BEACON_PATH = "/api/rum/vitals";
+
+/**
+ * Default reporter: one `sendBeacon` per finished metric to the RUM endpoint.
+ * `sendBeacon` is fire-and-forget and survives page unload — the moment CWV are
+ * finalized. Falls back to a keepalive `fetch` where `sendBeacon` is absent.
+ */
+export function beaconReporter(endpoint: string = RUM_BEACON_PATH): WebVitalsReporter {
+  return (sample) => {
+    if (typeof navigator === "undefined") return;
+    const body = JSON.stringify(sample);
+    try {
+      if (typeof navigator.sendBeacon === "function") {
+        navigator.sendBeacon(endpoint, body);
+      } else if (typeof fetch === "function") {
+        void fetch(endpoint, { method: "POST", body, keepalive: true });
+      }
+    } catch {
+      // Never let telemetry throw into the page.
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Browser collection (thin wiring — everything above is pure + unit-tested)
+// ---------------------------------------------------------------------------
+
+interface PerfEntryLS extends PerformanceEntry {
+  value: number;
+  hadRecentInput: boolean;
+}
+interface PerfEntryEvent extends PerformanceEntry {
+  interactionId?: number;
+}
+interface LcpEntry extends PerformanceEntry {
+  renderTime: number;
+  loadTime: number;
+}
+
+/**
+ * Start field Web Vitals collection for the current page. Idempotent-safe to
+ * call once from the client entry. No-op (returns a no-op teardown) when
+ * `PerformanceObserver` is unavailable (SSR, old browsers, tests) so callers
+ * don't need their own guard.
+ *
+ * Metrics are finalized and reported when the page is first backgrounded
+ * (`visibilitychange` → hidden) or on `pagehide` — the last reliable moment on
+ * mobile — because CWV are "worst-so-far" values that only settle at end of life.
+ */
+export function startWebVitals(
+  report: WebVitalsReporter = beaconReporter(),
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): () => void {
+  if (typeof PerformanceObserver === "undefined" || typeof document === "undefined") {
+    return () => {};
+  }
+
+  const path = typeof location !== "undefined" ? location.pathname : "/";
+  const navEntry =
+    typeof performance !== "undefined"
+      ? (performance.getEntriesByType("navigation")[0] as PerformanceNavigationTiming | undefined)
+      : undefined;
+  const navigationType = navEntry?.type;
+
+  // --- LCP: the last largest-contentful-paint candidate before input/hide. ---
+  let lcp = 0;
+  const lcpObs = new PerformanceObserver((list) => {
+    const entries = list.getEntries() as LcpEntry[];
+    const last = entries[entries.length - 1];
+    if (last) lcp = last.renderTime || last.loadTime || last.startTime;
+  });
+
+  // --- CLS: max session window (gap <1s, cap 5s), ignoring input-driven shifts. ---
+  let clsMax = 0;
+  let sessionValue = 0;
+  let sessionFirst = 0;
+  let sessionLast = 0;
+  const clsObs = new PerformanceObserver((list) => {
+    for (const raw of list.getEntries()) {
+      const e = raw as PerfEntryLS;
+      if (e.hadRecentInput) continue;
+      if (sessionValue && e.startTime - sessionLast < 1000 && e.startTime - sessionFirst < 5000) {
+        sessionValue += e.value;
+        sessionLast = e.startTime;
+      } else {
+        sessionValue = e.value;
+        sessionFirst = e.startTime;
+        sessionLast = e.startTime;
+      }
+      if (sessionValue > clsMax) clsMax = sessionValue;
+    }
+  });
+
+  // --- INP: the (n/50)th-worst interaction latency (web-vitals' definition). ---
+  const interactionDurations: number[] = [];
+  const seenInteraction = new Map<number, number>();
+  const inpObs = new PerformanceObserver((list) => {
+    for (const raw of list.getEntries()) {
+      const e = raw as PerfEntryEvent;
+      if (!e.interactionId) continue;
+      // Keep the WORST duration per interactionId (a tap can emit several events).
+      const prev = seenInteraction.get(e.interactionId);
+      if (prev === undefined || e.duration > prev) {
+        seenInteraction.set(e.interactionId, e.duration);
+      }
+    }
+  });
+
+  const observe = (obs: PerformanceObserver, type: string, opts: PerformanceObserverInit = {}) => {
+    try {
+      obs.observe({ type, buffered: true, ...opts });
+    } catch {
+      // Unsupported entry type in this browser — skip that metric silently.
+    }
+  };
+  observe(lcpObs, "largest-contentful-paint");
+  observe(clsObs, "layout-shift");
+  observe(inpObs, "event", { durationThreshold: 40 } as PerformanceObserverInit);
+
+  const computeInp = (): number | undefined => {
+    interactionDurations.length = 0;
+    for (const d of seenInteraction.values()) interactionDurations.push(d);
+    if (!interactionDurations.length) return undefined;
+    interactionDurations.sort((a, b) => b - a);
+    const idx = Math.min(Math.floor(interactionDurations.length / 50), interactionDurations.length - 1);
+    return interactionDurations[idx];
+  };
+
+  let reported = false;
+  const flush = () => {
+    if (reported) return;
+    reported = true;
+    lcpObs.takeRecords();
+    clsObs.takeRecords();
+    inpObs.takeRecords();
+    lcpObs.disconnect();
+    clsObs.disconnect();
+    inpObs.disconnect();
+
+    if (lcp > 0) report(toSample("lcp", lcp, path, navigationType, manifest));
+    report(toSample("cls", clsMax, path, navigationType, manifest));
+    const inp = computeInp();
+    if (inp !== undefined) report(toSample("inp", inp, path, navigationType, manifest));
+  };
+
+  const onVisibility = () => {
+    if (document.visibilityState === "hidden") flush();
+  };
+  document.addEventListener("visibilitychange", onVisibility, { capture: true });
+  window.addEventListener("pagehide", flush, { capture: true });
+
+  return () => {
+    document.removeEventListener("visibilitychange", onVisibility, { capture: true });
+    window.removeEventListener("pagehide", flush, { capture: true });
+    lcpObs.disconnect();
+    clsObs.disconnect();
+    inpObs.disconnect();
+  };
+}

package/apps/storefront/src/lib/apps/adminService.ts

@@ -0,0 +1,106 @@
+/**
+ * Composition root + shared helpers for the `/api/apps/admin/*` routes
+ * (PrivateApps epic, D2 Chunk C) — builds an `AppRegistryService` over the
+ * `STOREFRONT_APPS_DB` `Queryable` binding and a `D1CredentialStore`, the same
+ * construction `api/apps/oauth/token.ts` (Chunk B) uses, and mirrors
+ * `../grants/route.ts`'s `getService()` + no-store `json()` + 503-when-
+ * unconfigured pattern. Kept out of the pure service module so that stays
+ * transport-free and unit-testable against a fake `Queryable`.
+ */
+import {
+  AppRegistryService,
+  RegistryError,
+  type AppInstall,
+  type RegistryErrorCode,
+} from "./registryService.js";
+import { D1CredentialStore } from "./credentials.js";
+import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "./gatewayKeys.js";
+import { fromD1 } from "../d1/catalog.js";
+import { readD1, readEnv } from "../env.js";
+import { MANAGE_ROLES, type AdminAuthResult } from "./adminSession.js";
+
+/**
+ * No-store JSON response — install/rotate bodies carry a one-time client
+ * secret and must never be edge- or browser-cached.
+ */
+export function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * Build an `AppRegistryService` over the real `STOREFRONT_APPS_DB` D1
+ * binding, or return a 503 Response when that binding isn't configured in
+ * this runtime. Never leaks binding/secret detail in the response body.
+ */
+export async function getRegistryService(): Promise<AppRegistryService | Response> {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "app registry not configured" }, 503);
+  const db = fromD1(d1);
+  const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
+  const credentials = new D1CredentialStore(db, activeKid);
+  return new AppRegistryService(db, credentials);
+}
+
+/** HTTP status per `RegistryError` code — the one shared fail-closed mapping. */
+const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
+  scope_denied: 400,
+  not_found: 404,
+  already_installed: 409,
+  invalid_state: 409,
+  invalid_webhook_endpoint: 400,
+  invalid_widget_placement: 400,
+};
+
+/** Map a `RegistryError` to its HTTP status. Never echoes internals — code + message only. */
+export function registryErrorResponse(err: RegistryError): Response {
+  const body: Record<string, unknown> = { error: err.message, code: err.code };
+  if (err.denials) body.denials = err.denials;
+  return json(body, STATUS_BY_REGISTRY_CODE[err.code]);
+}
+
+/** Parse `{ installId }` from a JSON body — shared by every installId-bearing admin route. */
+export function parseInstallId(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const installId = (body as { installId?: unknown }).installId;
+  return typeof installId === "string" && installId.trim() ? installId.trim() : null;
+}
+
+/**
+ * Resolve `installId` and verify it belongs to `tenantId` — every mutating
+ * admin route (update/suspend/resume/uninstall/rotate) MUST call this BEFORE
+ * invoking a service method, since those methods take a bare `installId` with
+ * no tenant check of their own (Chunk A assumption #1). A foreign-tenant
+ * `installId` is reported IDENTICALLY to a truly-missing one — 404, same
+ * body shape as `RegistryError("not_found")` — so there is no cross-tenant
+ * existence oracle.
+ */
+export async function requireOwnedInstall(
+  registry: AppRegistryService,
+  installId: string,
+  tenantId: string,
+): Promise<AppInstall | Response> {
+  const install = await registry.get(installId);
+  if (!install || install.tenantId !== tenantId) {
+    return json({ error: "App install not found.", code: "not_found" }, 404);
+  }
+  return install;
+}
+
+/**
+ * Gate a mutating admin route on the resolved auth's role — call AFTER
+ * `resolveOperatorSession` for every write route (suspend/resume/uninstall/
+ * update/rotate/replay). A console session's `role` must be in
+ * `MANAGE_ROLES`: a `developer` is read-only and gets a 403 here. The
+ * host-bound/Bearer path (`resolveAdminSession`) carries no `role` at all —
+ * it is already manage-capable (gated by `ADMIN_CAPABILITIES`/the dedicated
+ * secret) — so an `undefined` role is exempt, not denied.
+ */
+export function requireManageRole(auth: Extract<AdminAuthResult, { ok: true }>): Response | null {
+  if (auth.role !== undefined && !MANAGE_ROLES.has(auth.role)) {
+    return json({ error: "not authorized to manage apps for this tenant" }, 403);
+  }
+  return null;
+}

package/apps/storefront/src/lib/apps/adminSession.ts

@@ -0,0 +1,205 @@
+/**
+ * Operator-session resolution for the Private Apps admin API
+ * (`/api/apps/admin/*`, PrivateApps epic, D2 Chunk C). Adapted from
+ * `../grants/session.ts`'s owner-session resolution — same two paths, same
+ * fail-closed shape — but resolves `{ tenantId, actor }` instead of `{ owner }`:
+ *
+ *   - `tenantId` is the `AppInstall.tenantId` scope. It MUST equal the
+ *     host-resolved `appDomain` the OAuth token issuer checks installs
+ *     against (`tokenIssuer.ts` compares `install.tenantId` to the caller's
+ *     `context.locals.tenant.appDomain`) — so an app installed through this
+ *     admin API is later discoverable by the SAME tenant identity a minted
+ *     token is scoped to.
+ *   - `actor` is an OPAQUE id for the audit log (`app_audit_log.actor` —
+ *     "never email/PII", see `../d1/schema.ts`). A signed-in viewer's verified
+ *     email is one-way hashed (`sha256Hex`, the same primitive `credentials.ts`
+ *     uses for secrets) so distinct operators still produce distinct, stable
+ *     audit actors without the trail ever holding an email address.
+ *
+ * Two resolution paths, tried in order:
+ *   1. SIGNED-IN TENANT OPERATOR (primary). `context.locals.viewer` (set by
+ *      the login-gate middleware from the `tot_session` cookie) plus
+ *      `context.locals.tenant`. Admitted only for an owner/admin capability
+ *      on the resolved tenant — a lower-capability viewer is a resolved
+ *      session with insufficient authority, so this fails closed with 403
+ *      rather than silently falling through to path 2.
+ *   2. BEARER OPERATOR SECRET (fallback, headless console). Gated by a
+ *      DEDICATED `APPS_ADMIN_SECRET` only — unlike grants' session, this does
+ *      NOT fall back to the shared `PREVIEW_RECONCILE_SECRET`, since that
+ *      secret must not double as a cross-tenant app-registry master key
+ *      (decision d2-admin-auth-dedicated-secret). Unconfigured `APPS_ADMIN_SECRET`
+ *      means this path is unavailable — fails closed rather than trusting
+ *      another deployment's secret. The tenant is resolved server-side from
+ *      `APPS_ADMIN_TENANT` env or the `X-Tot-Tenant` header (honoured only
+ *      for an already-authenticated caller) — never from the request body.
+ *      There is no per-caller identity on this path, so `actor` is the fixed
+ *      literal below.
+ *
+ * Routes depend only on the `{ ok, tenantId, actor }` result. `authorizeAdmin`
+ * is the pure core of path 2 (unit-testable, no I/O).
+ *
+ * D8 ADDITION — console admin session. The two paths above are host-bound:
+ * they resolve exactly one tenant (`context.locals.tenant`). The
+ * `/api/apps/admin/*` surface is also reachable from the multi-tenant vendor
+ * console, where a signed-in viewer may hold memberships on several vendors —
+ * so `resolveConsoleAdminSession` mirrors `../grants/team-members.ts`'s
+ * pattern instead: `readViewerSession` (the FULL session, all `tenants[]`)
+ * plus an explicit `requestedTenant` from the request, admitted via
+ * `viewerCanAccess`/`membershipFor` (deny-by-default, staff-selection-aware).
+ * Its `role` is the caller's resolved membership role
+ * (`developer`|`appAdmin`|`appOwner`) so routes can gate mutations against
+ * `MANAGE_ROLES` — a `developer` is read-only. `resolveOperatorSession` is
+ * the single entry point routes call: it tries the console path first and
+ * only falls back to `resolveAdminSession` (path 1/2 above) when there is NO
+ * console session at all (401) — a console session that exists but lacks
+ * access to `requestedTenant` fails closed with its own 403, the same
+ * no-fall-through discipline path 1 already uses for an insufficient
+ * capability.
+ */
+import type { APIContext } from "astro";
+import { sha256Hex } from "@tot/public-runtime";
+import { readEnv } from "@/lib/env";
+import { readViewerSession } from "@/lib/auth/route.js";
+import { viewerCanAccess, membershipFor } from "@/lib/dashboard/tenantSelection.js";
+
+/** Capabilities that make a signed-in viewer an app-registry operator for their tenant. */
+const ADMIN_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
+
+/** Console membership roles authorized to mutate installs — a `developer` is read-only. */
+export const MANAGE_ROLES: ReadonlySet<string> = new Set(["appOwner", "appAdmin"]);
+
+/** Opaque `actor` stamped for the shared Bearer fallback — no per-caller identity to hash. */
+const BEARER_ACTOR = "bearer-operator";
+
+/** How many hex chars of the email digest to keep — enough entropy to distinguish operators. */
+const ACTOR_HASH_LENGTH = 32;
+
+/** Pure inputs to the Bearer-fallback authorization decision (env + request, no I/O). */
+export interface AdminAuthInput {
+  /** The request `Authorization` header, if any. */
+  authHeader: string | null;
+  /** The configured operator gate secret (or undefined if unconfigured). */
+  gateSecret: string | undefined;
+  /** Server-configured tenant for this deployment (APPS_ADMIN_TENANT), if any. */
+  configuredTenant: string | undefined;
+  /** `X-Tot-Tenant` header — honoured only once the caller is authenticated. */
+  requestedTenant: string | null;
+}
+
+export type AdminAuthResult =
+  | { ok: true; tenantId: string; actor: string; role?: string }
+  | { ok: false; status: number; message: string };
+
+/**
+ * Decide the authenticated tenant from env + request, with NO I/O —
+ * unit-testable. Fail-closed: unconfigured gate → 503, bad/absent Bearer →
+ * 401, no resolvable tenant → 400.
+ */
+export function authorizeAdmin(input: AdminAuthInput): AdminAuthResult {
+  if (!input.gateSecret) {
+    return {
+      ok: false,
+      status: 503,
+      message: "apps admin operator secret not configured",
+    };
+  }
+  if (input.authHeader !== `Bearer ${input.gateSecret}`) {
+    return { ok: false, status: 401, message: "Unauthorized" };
+  }
+  const tenantId = (input.configuredTenant ?? input.requestedTenant ?? "").trim();
+  if (!tenantId) {
+    return {
+      ok: false,
+      status: 400,
+      message: "tenant unresolved (set APPS_ADMIN_TENANT or X-Tot-Tenant)",
+    };
+  }
+  return { ok: true, tenantId, actor: BEARER_ACTOR };
+}
+
+/** One-way, stable pseudonym for an audit `actor` — never the email itself. */
+async function actorFromEmail(email: string): Promise<string> {
+  return `viewer:${(await sha256Hex(email)).slice(0, ACTOR_HASH_LENGTH)}`;
+}
+
+/**
+ * Resolve the authenticated `{ tenantId, actor }` for a Private Apps admin
+ * request from the runtime env + the incoming request. Never reads `tenantId`
+ * from the body.
+ */
+export async function resolveAdminSession(context: APIContext): Promise<AdminAuthResult> {
+  // Path 1: a signed-in tenant-operator session. The tenant IS the resolved
+  // host's appDomain — never from the request body.
+  const viewer = context.locals?.viewer;
+  const tenantId = context.locals?.tenant?.appDomain;
+  if (viewer && tenantId) {
+    if (!ADMIN_CAPABILITIES.has(viewer.capability)) {
+      return {
+        ok: false,
+        status: 403,
+        message: "not authorized to manage apps for this tenant",
+      };
+    }
+    return { ok: true, tenantId, actor: await actorFromEmail(viewer.email) };
+  }
+
+  // Path 2 (fallback): the headless-console Bearer operator secret. Dedicated
+  // secret only — no fallback to another deployment's secret.
+  const gateSecret = await readEnv("APPS_ADMIN_SECRET");
+  const configuredTenant = await readEnv("APPS_ADMIN_TENANT");
+  return authorizeAdmin({
+    authHeader: context.request.headers.get("authorization"),
+    gateSecret,
+    configuredTenant,
+    requestedTenant: context.request.headers.get("x-tot-tenant"),
+  });
+}
+
+/**
+ * Resolve a signed-in console viewer's admin session for `requestedTenant`
+ * (the `?tenant=` query param every admin route now reads) — the multi-tenant
+ * counterpart to `resolveAdminSession`'s host-bound path 1, mirroring
+ * `../grants/team-members.ts`'s `readViewerSession` + `viewerCanAccess`
+ * pattern instead of the single-tenant `locals.tenant`/`locals.viewer` gate.
+ * Fail-closed: no session → 401 (the signal `resolveOperatorSession` uses to
+ * fall back to the host-bound/Bearer path); a session with no membership or
+ * live staff admission for `requestedTenant` → 403 (does NOT fall back — an
+ * authenticated-but-denied caller is not the "no console session" case).
+ * `role` is the caller's resolved membership role for routes to gate
+ * mutations against `MANAGE_ROLES`.
+ */
+export async function resolveConsoleAdminSession(
+  context: APIContext,
+  requestedTenant: string | null,
+): Promise<AdminAuthResult> {
+  const session = await readViewerSession(context);
+  if (!session) return { ok: false, status: 401, message: "not signed in" };
+
+  const tenantId = (requestedTenant ?? "").trim();
+  const staff = { selection: session.staffSelection, nowSeconds: Math.floor(Date.now() / 1000) };
+  if (!viewerCanAccess(session.tenants, tenantId, staff)) {
+    return {
+      ok: false,
+      status: 403,
+      message: "not authorized to manage apps for this tenant",
+    };
+  }
+  const role = membershipFor(session.tenants, tenantId, staff)?.role ?? "developer";
+  return { ok: true, tenantId, actor: await actorFromEmail(session.email), role };
+}
+
+/**
+ * The single entry point admin routes call: try the signed-in console
+ * viewer's session first, and only fall back to the host-bound/Bearer path
+ * (`resolveAdminSession`) when there is no console session at all (401) — see
+ * {@link resolveConsoleAdminSession}'s doc for why a denied console session
+ * (403) does not fall through.
+ */
+export async function resolveOperatorSession(
+  context: APIContext,
+  requestedTenant: string | null,
+): Promise<AdminAuthResult> {
+  const consoleAuth = await resolveConsoleAdminSession(context, requestedTenant);
+  if (consoleAuth.ok || consoleAuth.status !== 401) return consoleAuth;
+  return resolveAdminSession(context);
+}

package/apps/storefront/src/lib/apps/apiAuth.ts

@@ -0,0 +1,91 @@
+/**
+ * The D3 scoped-API authorization boundary (PrivateApps epic) — every
+ * `/api/apps/v1/*` route calls `authorizeAppRequest` FIRST. Verifies the
+ * app-gateway bearer JWT (D2's `AppTokenVerifier`), resolves the calling
+ * install from the registry, and enforces the single scope the route
+ * requires per `docs/private-apps/contract/openapi.yaml`'s `x-requiredScope`.
+ *
+ * Tenant is ALWAYS the host-resolved `context.locals.tenant.appDomain` —
+ * never a header or query param — the same binding `tokenIssuer.ts` and
+ * `oauth/token.ts` use, so a token can't be replayed against a different
+ * tenant than the one it was minted for.
+ *
+ * Fail-closed throughout: an unconfigured signing key, a missing/invalid/
+ * expired token, and an install that's gone missing/cross-tenant/suspended/
+ * uninstalled are ALL reported identically as the generic 401 the contract's
+ * `Unauthorized` response documents (no detail that would let a caller
+ * distinguish "wrong tenant" from "suspended" from "never existed" — the
+ * same no-oracle discipline `registryService.ts`'s `mustFindRow` and
+ * `tokenIssuer.ts`'s `invalid_client` already keep).
+ */
+import type { APIContext } from "astro";
+import { getAppTokenVerifier, type AppTokenClaims } from "./tokenVerifier.js";
+import { getRegistryService } from "./adminService.js";
+import type { AppInstall } from "./registryService.js";
+import { json } from "./apiRoute.js";
+
+export interface AuthorizedAppRequest {
+  ok: true;
+  claims: AppTokenClaims;
+  install: AppInstall;
+}
+
+export type AuthorizeAppResult = AuthorizedAppRequest | { ok: false; response: Response };
+
+/** Generic, no-detail 401 — see the fail-closed note above. */
+function unauthorized(): Response {
+  return json({ error: "Unauthorized", code: "invalid_token" }, 401);
+}
+
+/**
+ * Authorize one `/api/apps/v1/*` request. Pass the single scope id the route
+ * requires (per the contract's `x-requiredScope`), or `null` for the
+ * metadata endpoints that only require a valid token.
+ */
+export async function authorizeAppRequest(
+  context: APIContext,
+  requiredScope: string | null,
+): Promise<AuthorizeAppResult> {
+  const tenant = context.locals.tenant.appDomain;
+
+  const verifier = await getAppTokenVerifier(tenant);
+  if (!verifier) {
+    return { ok: false, response: json({ error: "app gateway not configured", code: "unconfigured" }, 503) };
+  }
+
+  const authHeader = context.request.headers.get("authorization");
+  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice("Bearer ".length).trim() : "";
+  if (!token) {
+    return { ok: false, response: unauthorized() };
+  }
+
+  let claims: AppTokenClaims;
+  try {
+    claims = await verifier.verify(token);
+  } catch {
+    return { ok: false, response: unauthorized() };
+  }
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return { ok: false, response: registry };
+
+  const install = await registry.get(claims.sub);
+  if (!install || install.tenantId !== tenant || install.status !== "active") {
+    return { ok: false, response: unauthorized() };
+  }
+
+  // Enforce the scope against BOTH the live install grant and the token claims.
+  // install.scopes is the authoritative, real-time grant — so an operator
+  // narrowing scopes via update() takes effect immediately (not only after the
+  // ~300s token TTL), matching how install *status* is already live-checked
+  // above. Requiring it in the token too keeps a token from ever exceeding the
+  // grant it was minted with. Fail-closed: absent from either → denied.
+  if (
+    requiredScope &&
+    !(install.scopes.includes(requiredScope) && claims.scopes.includes(requiredScope))
+  ) {
+    return { ok: false, response: json({ error: "scope_denied", code: "scope_denied" }, 403) };
+  }
+
+  return { ok: true, claims, install };
+}