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

package/apps/storefront/src/lib/activity/uiActor.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared emit helper for UI-ORIGINATED operational activity (card D6).
+ *
+ * The UI cohort's entry point onto the D0 actor×action telemetry contract. It sits
+ * ON TOP of D1's server emitter ({@link recordActivity}) — every admin/cockpit action
+ * handler already runs SERVER-SIDE in the same Worker, so a UI action reaches
+ * telemetry through the same in-process `recordActivity()` call D1 uses (one
+ * structured Workers-Logs line), NOT a client-side `fetch` to the D4 ingest endpoint.
+ * There is no browser-only signal to capture: an admin/cockpit "Publish / Connect /
+ * Invite / Approve / Rollback" click is a server-rendered form/JSON POST to an API
+ * route, so the route handler that already does the work is exactly where the emit
+ * belongs (zero extra HTTP round-trip, no new auth/trust boundary). The D4 HMAC
+ * ingest path exists for emitters that CAN'T call `recordActivity()` directly (the
+ * out-of-process CLI cohort, D3) — it is not this cohort's path.
+ *
+ * WHAT THIS ADDS over calling `recordActivity()` raw: it stamps `source: "ui"` and,
+ * critically, resolves the ACTOR KIND from the authenticated session so the timeline
+ * (D5) can attribute an action to the right cohort:
+ *
+ *   • "admin"    — a ToT-STAFF viewer (the session carries `staff[]` scope). ToT
+ *                  operators acting through the admin shell / staff vendor selection.
+ *   • "merchant" — a store OWNER acting on THEIR OWN store (a signed-in viewer whose
+ *                  host-bound capability is owner/admin). The self-serve cohort.
+ *   • "dev"      — a signed-in DEVELOPER viewer who is neither staff nor owner (e.g. a
+ *                  ship-on-behalf developer invited onto someone else's store).
+ *   • "agent"    — a HEADLESS, capability-driven caller with no human viewer session
+ *                  (the Bearer/CLI operator seam) — automation acting on the surface.
+ *
+ * The classifier is a PURE function ({@link classifyActorKind}) so the cohort mapping
+ * is unit-tested without a live request. The opaque `actor.id` is the salted,
+ * non-reversible hash of the acting identity (never raw PII in the core zone) — the
+ * SAME {@link hashActorId} + `ACTIVITY_ACTOR_SALT` D1 established, so one person stays
+ * correlatable across the CLI, server, and UI cohorts.
+ *
+ * USAGE (mirrors D1's reject.ts — resolve the actor ONCE after auth, emit at each
+ * exit point, zero change to the handler's control flow):
+ *
+ *   const actor = await resolveUiActor(context, { owner: auth.owner });
+ *   // …do the work…
+ *   recordUiActivity(actor, { action: "change.ship", outcome: { status: "succeeded" }, scope });
+ */
+import type { APIContext } from "astro";
+import type {
+  ActivityActor,
+  ActorKind,
+  ActivityOutcome,
+  ActivityScope,
+  ActivityPayload,
+} from "@tot/public-runtime";
+import type { ActionKey } from "@tot/public-runtime";
+import { readViewerSession } from "@/lib/auth/route";
+import { isStaffSession } from "@/lib/dashboard/staffAdmission";
+import { readEnv } from "@/lib/env";
+import { hashActorId, recordActivity } from "./recordActivity";
+
+/** The host-bound capabilities that mark a viewer as the store OWNER (merchant). */
+const OWNER_CAPABILITIES = new Set(["owner", "admin"]);
+
+/** The minimal viewer chrome the middleware stamps on `locals.viewer`. */
+interface ViewerLike {
+  email?: string;
+  capability?: string;
+}
+
+/**
+ * Classify the acting cohort from the authenticated session — PURE so the mapping is
+ * testable without a request. Order matters and is fail-safe:
+ *
+ *   1. no signed-in viewer  → "agent" (headless Bearer/CLI operator — capability-
+ *      driven automation; there is no human identity on this request).
+ *   2. ToT-staff session    → "admin" (checked BEFORE ownership: a staff viewer who
+ *      entered a vendor via a live selection carries an owner-ish host capability, but
+ *      they are ToT staff, not the merchant).
+ *   3. owner/admin capability on this host → "merchant" (the store owner on their own store).
+ *   4. otherwise            → "dev" (a signed-in developer without ownership, e.g.
+ *      ship-on-behalf).
+ */
+export function classifyActorKind(
+  viewer: ViewerLike | null | undefined,
+  session: { staff?: string[] } | null | undefined,
+): ActorKind {
+  if (!viewer?.email) return "agent";
+  if (isStaffSession(session)) return "admin";
+  if (viewer.capability && OWNER_CAPABILITIES.has(viewer.capability)) return "merchant";
+  return "dev";
+}
+
+export interface ResolveUiActorInput {
+  /**
+   * Fallback acting identity for the HEADLESS path (no signed-in viewer) — typically
+   * the resolved tenant owner (`auth.owner`). Only used to seed the opaque id when
+   * there is no viewer email; never stored raw (always hashed).
+   */
+  owner?: string;
+}
+
+/**
+ * Resolve the {@link ActivityActor} for a UI-originated action from the request's
+ * authenticated session. Reads the full viewer session ONCE (for the staff scope the
+ * host-bound `locals.viewer` chrome doesn't carry) and computes the opaque, salted
+ * actor id. Best-effort: any read fault degrades to a coarse non-PII actor rather
+ * than throwing — telemetry must never break the action it describes. Resolve this
+ * ONCE per request (after auth) and reuse the result across every emit exit point.
+ */
+export async function resolveUiActor(
+  context: APIContext,
+  input: ResolveUiActorInput = {},
+): Promise<ActivityActor> {
+  // The host-bound `locals.viewer` chrome omits `staff[]`, so read the full session
+  // to tell a ToT-staff (admin) actor from a store owner (merchant). Best-effort.
+  const session = await readViewerSession(context).catch(() => null);
+  // Prefer the host-scoped `locals.viewer` (set by middleware for tenant-gated
+  // surfaces — the ship/grants routes); fall back to the raw session's
+  // email/capability for a route that never went through that host gate (e.g. the
+  // /dev cockpit's rendezvous-approval endpoint) but still has a real signed-in
+  // viewer. Both describe the SAME signed-in-or-not shape.
+  const viewer: ViewerLike | undefined =
+    (context.locals?.viewer as ViewerLike | undefined) ??
+    (session ? { email: session.email, capability: session.capability } : undefined);
+  const kind = classifyActorKind(viewer, session);
+  const identifier = viewer?.email ?? input.owner ?? "system";
+  const id = await hashActorId(identifier, await readEnv("ACTIVITY_ACTOR_SALT"));
+  return { kind, id };
+}
+
+/**
+ * Emit ONE UI-originated activity event with a PRE-RESOLVED actor. A thin, SYNC
+ * wrapper over D1's {@link recordActivity} that stamps `source: "ui"` — so a handler
+ * calls it at each exit point (succeeded / failed / refused) exactly as D1's server
+ * emitters do, with no control-flow change. Best-effort + never throws (inherited
+ * from `recordActivity`).
+ */
+export function recordUiActivity(
+  actor: ActivityActor,
+  input: {
+    action: ActionKey;
+    outcome: ActivityOutcome;
+    scope?: ActivityScope;
+    payload?: ActivityPayload;
+  },
+): void {
+  recordActivity({
+    action: input.action,
+    actor,
+    source: "ui",
+    outcome: input.outcome,
+    ...(input.scope ? { scope: input.scope } : {}),
+    ...(input.payload ? { payload: input.payload } : {}),
+  });
+}

package/apps/storefront/src/lib/activity/workerCommit.ts

@@ -0,0 +1,70 @@
+/**
+ * worker_commit — build provenance for the running Worker (card D2).
+ *
+ * The commit SHA THIS Worker build was cut from, made available REPO-WIDE at
+ * runtime so every server-emitted ActivityEvent can carry it (see event.ts
+ * `ActivityScope.workerCommit`) and D5 can later derive **deploy skew** — "is the
+ * build serving this request == the pushed umbrella tip, or is a stale worker
+ * still live?".
+ *
+ * HOW IT GETS HERE. Workers have no filesystem/git at runtime, so the SHA is
+ * baked in at BUILD time: astro.config.mjs's Vite `define` replaces the
+ * `__GIT_SHA__` token with a string literal of the build's commit (CI-provided
+ * `GIT_SHA`/`WORKERS_CI_COMMIT_SHA`/`GITHUB_SHA`, else local `git rev-parse`,
+ * else "unknown"). This is the SAME source /health already reports (lib/health.ts)
+ * — we read it through the identical `typeof` guard so both agree by construction,
+ * and so the value is safe under vitest (where the define isn't applied → "unknown").
+ *
+ * This is the single accessor the whole repo threads through: D1's recordActivity()
+ * spreads serverActivityScope() into every server event; D2's deploy.version_observed
+ * emitter (deployVersion.ts) reads workerCommit() directly.
+ */
+import type { ActivityScope } from "@tot/public-runtime";
+
+/** Sentinel when the build had no git context (also the vitest value). */
+export const UNKNOWN_COMMIT = "unknown";
+
+/**
+ * The commit SHA this Worker build was cut from, or "unknown". Never throws; the
+ * `typeof` guard keeps it safe under vitest (the `__GIT_SHA__` define is only
+ * applied by the Astro/Vite build). Optionally overridable for tests.
+ */
+export function workerCommit(override?: string): string {
+  if (override != null) return override;
+  return typeof __GIT_SHA__ !== "undefined" ? __GIT_SHA__ : UNKNOWN_COMMIT;
+}
+
+/** First 7 chars of the build commit for eyeballing against `git log`, or "unknown". */
+export function workerCommitShort(override?: string): string {
+  const sha = workerCommit(override);
+  return sha === UNKNOWN_COMMIT ? UNKNOWN_COMMIT : sha.slice(0, 7);
+}
+
+/**
+ * True when the build has a real git commit (not the "unknown" sentinel). D5's
+ * skew derivation only compares against the umbrella tip when this holds — an
+ * "unknown" build can't be meaningfully skew-checked.
+ */
+export function hasKnownWorkerCommit(override?: string): boolean {
+  return workerCommit(override) !== UNKNOWN_COMMIT;
+}
+
+/**
+ * Build the CORE scope for a SERVER-sourced ActivityEvent with `worker_commit`
+ * stamped in. This is the seam D1's recordActivity() spreads into every server
+ * event so provenance is present WITHOUT each call site remembering it:
+ *
+ *   createActivityEvent({ ..., source: "server", scope: serverActivityScope({ tenantId }) })
+ *
+ * Pass the event's other scope fields (tenantId/changeId/traceId) as `extra`;
+ * workerCommit always wins for the `workerCommit` slot. Omits the field entirely
+ * when the build commit is "unknown" so a downstream skew query never mistakes the
+ * sentinel for a real deployed SHA.
+ */
+export function serverActivityScope(extra?: ActivityScope): ActivityScope {
+  const sha = workerCommit();
+  return {
+    ...extra,
+    ...(sha !== UNKNOWN_COMMIT ? { workerCommit: sha } : {}),
+  };
+}

package/apps/storefront/src/lib/analytics/budgets.json

@@ -0,0 +1,69 @@
+{
+  "$comment": "F14 performance budgets manifest — the checked-in, tool-neutral source of truth for the storefront go-live framework's perf gate. Consumed by (1) the lab budget-assertion harness (perf/assert-budgets.ts), (2) the Lighthouse budgets exporter (toLighthouseBudgets), and (3) the field RUM regression-alert contract (rumAlert.ts). Edit HERE — everything else derives from it. Shape + validation: src/lib/analytics/perfBudgets.ts (parsePerfBudgets).",
+  "version": 1,
+  "webVitals": {
+    "$comment": "Core Web Vitals thresholds, evaluated at the 75th percentile (p75) of the field distribution — the same percentile Google's CrUX / the RUM alert contract use.",
+    "lcpMs": 2500,
+    "inpMs": 200,
+    "cls": 0.1
+  },
+  "resourceBudgets": {
+    "$comment": "Per-page transfer budgets in kibibytes (KiB), compressed-over-the-wire. Defaults; a route may tighten or (rarely) loosen them via its own resourceBudgets.",
+    "jsKib": 180,
+    "cssKib": 90,
+    "imageKib": 900,
+    "totalKib": 1300
+  },
+  "thirdPartyScriptAllowlist": [
+    "static.cloudflareinsights.com",
+    "cdn.foxycart.com"
+  ],
+  "routes": [
+    {
+      "id": "home",
+      "label": "Home",
+      "samplePath": "/",
+      "match": ["="]
+    },
+    {
+      "id": "plp",
+      "label": "Product listing",
+      "samplePath": "/collections/all",
+      "match": ["/collections"]
+    },
+    {
+      "id": "pdp",
+      "label": "Product detail",
+      "samplePath": "/products/",
+      "match": ["/products/"],
+      "resourceBudgets": {
+        "$comment": "PDP carries the largest hero + gallery imagery.",
+        "imageKib": 1100,
+        "totalKib": 1500
+      }
+    },
+    {
+      "id": "search",
+      "label": "Search results",
+      "samplePath": "/search?q=cap",
+      "match": ["/search"]
+    },
+    {
+      "id": "account",
+      "label": "Account / dashboard",
+      "samplePath": "/dashboard",
+      "match": ["/dashboard", "/account", "/saved"]
+    },
+    {
+      "id": "checkout",
+      "label": "Checkout entry",
+      "samplePath": "/cart",
+      "match": ["/cart", "/checkout"],
+      "resourceBudgets": {
+        "$comment": "The managed-checkout loader (cdn.foxycart.com) ships its own JS bundle; give this route headroom the on-site pages do not need.",
+        "jsKib": 320,
+        "totalKib": 1600
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,109 @@
+/**
+ * F14 — Lighthouse result → budget measurement (the lab hook, pure half).
+ *
+ * The budget gate (`perfBudgets.ts`) evaluates a tool-neutral `RouteMeasurement`.
+ * This module is the one adapter that turns a Lighthouse result object (LHR JSON,
+ * as `lighthouse --output=json` / LHCI emit) into that shape, so a live
+ * Lighthouse run in preview validation feeds the SAME gate the unit tests do.
+ *
+ * Kept pure (LHR in → measurement out, no fs/network) so `lighthouseReport.test.ts`
+ * can prove the extraction against a fixture LHR without running Lighthouse; the
+ * thin CLI (`perf/assert-budgets.ts`) does the fs + Lighthouse invocation.
+ *
+ * We read only the stable, documented LHR fields:
+ *  - `audits['largest-contentful-paint'].numericValue`  (ms)      → webVitals.lcpMs
+ *  - `audits['cumulative-layout-shift'].numericValue`   (unitless)→ webVitals.cls
+ *  - `audits['resource-summary'].details.items[]`       (bytes)   → resource KiB
+ *  - `audits['network-requests'].details.items[]`       (url)     → third-party origins
+ * INP is intentionally absent — it has no lab value; it is enforced from field
+ * RUM (`rumAlert.ts`), matching `toLighthouseBudgets`' note.
+ *
+ * Third-party origins are taken from `network-requests` (real request URLs →
+ * hostnames), NOT `third-party-summary` — the latter reports entity DISPLAY
+ * names ("Google Fonts"), which would never match the manifest's hostname
+ * allowlist. We keep hostnames that loaded a Script and are cross-origin to the
+ * page, so the gate's allowlist check compares like-for-like.
+ */
+import type { RouteId, RouteMeasurement } from "./perfBudgets.js";
+
+/** The (loose) slice of a Lighthouse result we read. */
+export interface LighthouseResult {
+  audits?: Record<
+    string,
+    {
+      numericValue?: number;
+      details?: {
+        items?: Array<Record<string, unknown>>;
+      };
+    }
+  >;
+  finalUrl?: string;
+  requestedUrl?: string;
+}
+
+const hostnameOf = (url: string | undefined): string | undefined => {
+  if (!url) return undefined;
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return undefined;
+  }
+};
+
+const BYTES_PER_KIB = 1024;
+const toKib = (bytes: unknown): number | undefined =>
+  typeof bytes === "number" && Number.isFinite(bytes)
+    ? Math.round((bytes / BYTES_PER_KIB) * 10) / 10
+    : undefined;
+
+/** Map a Lighthouse `resource-summary` resourceType onto our budget keys. */
+const RESOURCE_TYPE_KEY: Record<string, "jsKib" | "cssKib" | "imageKib" | "totalKib"> = {
+  script: "jsKib",
+  stylesheet: "cssKib",
+  image: "imageKib",
+  total: "totalKib",
+};
+
+/**
+ * Extract a `RouteMeasurement` for `routeId` from a Lighthouse result. Missing
+ * audits simply yield missing dimensions — the gate only checks what was
+ * measured — so a partial/failed audit under-reports rather than crashing.
+ */
+export function lhrToMeasurement(lhr: LighthouseResult, routeId: RouteId): RouteMeasurement {
+  const audits = lhr.audits ?? {};
+
+  const resources: NonNullable<RouteMeasurement["resources"]> = {};
+  const summaryItems = audits["resource-summary"]?.details?.items ?? [];
+  for (const item of summaryItems) {
+    const type = typeof item["resourceType"] === "string" ? (item["resourceType"] as string) : "";
+    const key = RESOURCE_TYPE_KEY[type];
+    const kib = toKib(item["transferSize"]);
+    if (key && kib !== undefined) resources[key] = kib;
+  }
+
+  const webVitals: NonNullable<RouteMeasurement["webVitals"]> = {};
+  const lcp = audits["largest-contentful-paint"]?.numericValue;
+  if (typeof lcp === "number") webVitals.lcpMs = Math.round(lcp);
+  const cls = audits["cumulative-layout-shift"]?.numericValue;
+  if (typeof cls === "number") webVitals.cls = Math.round(cls * 1e4) / 1e4;
+
+  // Third-party SCRIPT hostnames, cross-origin to the page, from real requests.
+  const pageHost = hostnameOf(lhr.finalUrl ?? lhr.requestedUrl);
+  const netItems = audits["network-requests"]?.details?.items ?? [];
+  const thirdPartyOrigins: string[] = [];
+  for (const item of netItems) {
+    const type = typeof item["resourceType"] === "string" ? (item["resourceType"] as string) : "";
+    if (type.toLowerCase() !== "script") continue;
+    const host = hostnameOf(typeof item["url"] === "string" ? (item["url"] as string) : undefined);
+    if (!host || host === pageHost) continue;
+    if (!thirdPartyOrigins.includes(host)) thirdPartyOrigins.push(host);
+  }
+
+  return {
+    routeId,
+    ...(lhr.finalUrl || lhr.requestedUrl ? { url: lhr.finalUrl ?? lhr.requestedUrl } : {}),
+    ...(Object.keys(resources).length ? { resources } : {}),
+    ...(Object.keys(webVitals).length ? { webVitals } : {}),
+    ...(thirdPartyOrigins.length ? { thirdPartyOrigins } : {}),
+  };
+}