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

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

@@ -0,0 +1,188 @@
+/**
+ * Ingest validation + server-side redaction for `POST /api/activity`.
+ *
+ * PURE (no I/O) so it is unit-testable and the route stays a thin auth/parse/
+ * respond shell. Takes the raw JSON events an emitter posted (the CLI and UI
+ * cohorts — both send JSON matching the `ActivityEvent` shape) plus the
+ * AUTHENTICATED tenant id, and returns the accepted events (already rebuilt
+ * through `createActivityEvent`, so re-redacted server-side) and the rejections.
+ *
+ * DEFENSE IN DEPTH. Even though every emitter is
+ * expected to have run the redaction contract itself, ingest NEVER trusts that:
+ * it rebuilds each event through `createActivityEvent()`, which re-applies the
+ * default-deny allowlist + canary scan. A malicious/careless client that posts a
+ * secret in an un-allowlisted (or even allowlisted) payload field has it dropped/
+ * redacted here regardless of what it claimed to send.
+ *
+ * TENANT ISOLATION. `scope.tenantId` on the stored event is ALWAYS the
+ * authenticated tenant (from the HMAC-bound header), never the client-supplied
+ * body value — a client cannot write into another tenant's scope.
+ */
+import {
+  createActivityEvent,
+  isActionKey,
+  isActorAllowed,
+  isIsoTimestamp,
+  getActionSpec,
+  scanCoreIdentifier,
+  type ActivityEvent,
+  type ActorKind,
+  type ActivitySource,
+  type ActivityStatus,
+  type ActivityPayload,
+  type RedactionFieldHit,
+} from "@tot/public-runtime";
+
+const ACTOR_KINDS = new Set<ActorKind>(["dev", "merchant", "admin", "agent", "system"]);
+const SOURCES = new Set<ActivitySource>(["cli", "server", "ui"]);
+const STATUSES = new Set<ActivityStatus>(["invoked", "succeeded", "failed", "refused"]);
+
+export interface IngestRejection {
+  /** Index of the offending event in the posted batch. */
+  index: number;
+  /** Coarse machine reason — mirrors the `system.ingest.rejected` catalog args. */
+  reason:
+    | "not_object"
+    | "unknown_action"
+    | "actor_invalid"
+    | "actor_not_allowed"
+    | "source_invalid"
+    | "source_mismatch"
+    | "status_invalid"
+    | "bad_timestamp"
+    /** A client-supplied CORE-zone id (actor.id/ref, scope.changeId/traceId) carried a
+     *  raw PII/secret SHAPE. The core zone is unredacted, so this is refused outright
+     *  (never stored) rather than scrubbed — see `scanCoreIdentifier`. */
+    | "core_pii";
+  /** The action string the client attempted (for self-telemetry), when present. */
+  attemptedAction?: string;
+}
+
+export interface AcceptedActivity {
+  event: ActivityEvent;
+  /** True when a value-canary fired during server-side redaction — the signal
+   *  the route emits self-telemetry for and alerting reads. */
+  canaryTripped: boolean;
+  /** The redaction hits (fact-of, never the value) for audit / logging. */
+  redactionHits: RedactionFieldHit[];
+}
+
+export interface IngestOutcome {
+  accepted: AcceptedActivity[];
+  rejected: IngestRejection[];
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Validate + redact one posted event under the authenticated tenant. Returns the
+ * accepted (rebuilt) event or a rejection. The rebuild forces the tenant scope
+ * and re-runs redaction; it preserves the client's `id` (idempotency key) and
+ * `at` (emit clock) when they are well-formed.
+ */
+export function ingestOne(index: number, raw: unknown, tenantId: string): AcceptedActivity | IngestRejection {
+  if (!raw || typeof raw !== "object") return { index, reason: "not_object" };
+  const e = raw as Record<string, unknown>;
+
+  const action = e.action;
+  if (typeof action !== "string" || !isActionKey(action)) {
+    return { index, reason: "unknown_action", attemptedAction: typeof action === "string" ? action : undefined };
+  }
+  const spec = getActionSpec(action)!;
+
+  const rawActor = e.actor;
+  if (!rawActor || typeof rawActor !== "object") return { index, reason: "actor_invalid", attemptedAction: action };
+  const actorKind = (rawActor as Record<string, unknown>).kind;
+  const actorId = (rawActor as Record<string, unknown>).id;
+  const actorRef = (rawActor as Record<string, unknown>).ref;
+  if (typeof actorKind !== "string" || !ACTOR_KINDS.has(actorKind as ActorKind) || typeof actorId !== "string" || !actorId) {
+    return { index, reason: "actor_invalid", attemptedAction: action };
+  }
+  // Spoof guard: a `dev`-cohort caller cannot claim an `admin` lifecycle action.
+  if (!isActorAllowed(action, actorKind as ActorKind)) {
+    return { index, reason: "actor_not_allowed", attemptedAction: action };
+  }
+
+  const source = e.source;
+  if (typeof source !== "string" || !SOURCES.has(source as ActivitySource)) {
+    return { index, reason: "source_invalid", attemptedAction: action };
+  }
+  // The catalog declares exactly one legitimate source per action (1:1 grounding).
+  if (source !== spec.source) return { index, reason: "source_mismatch", attemptedAction: action };
+
+  const rawOutcome = e.outcome;
+  const status = rawOutcome && typeof rawOutcome === "object" ? (rawOutcome as Record<string, unknown>).status : undefined;
+  if (typeof status !== "string" || !STATUSES.has(status as ActivityStatus)) {
+    return { index, reason: "status_invalid", attemptedAction: action };
+  }
+  const errorClass = asString((rawOutcome as Record<string, unknown>).errorClass);
+  const durationRaw = (rawOutcome as Record<string, unknown>).durationMs;
+  const durationMs = typeof durationRaw === "number" && Number.isFinite(durationRaw) ? durationRaw : undefined;
+
+  // `at`: keep the emit clock when well-formed; a PRESENT-but-malformed `at` is a
+  // reject (a broken clock corrupts the timeline ordering), a MISSING one is
+  // stamped server-side by createActivityEvent.
+  const at = e.at;
+  if (at !== undefined && !isIsoTimestamp(at)) return { index, reason: "bad_timestamp", attemptedAction: action };
+
+  const rawScope = (e.scope && typeof e.scope === "object" ? e.scope : {}) as Record<string, unknown>;
+
+  // CORE-ZONE PII GUARD. actor.id / actor.ref and the client-supplied
+  // scope ids land UNREDACTED in the core zone, whose contract is "opaque, never raw
+  // PII/secret". The payload contract is enforced by re-redaction below, but the core
+  // ids were NOT checked — a buggy/malicious (though authenticated) emitter could
+  // smuggle a raw email/token into actor.id and have it stored in D1/Analytics/logs
+  // verbatim. Refuse any core id with a raw PII/secret SHAPE (opaque hashes/UUIDs pass;
+  // see `scanCoreIdentifier`). Rejected → self-telemetried as `system.ingest.rejected`.
+  const changeId = asString(rawScope.changeId);
+  const traceId = asString(rawScope.traceId);
+  if (
+    scanCoreIdentifier(actorId) ||
+    (typeof actorRef === "string" && actorRef && scanCoreIdentifier(actorRef)) ||
+    (changeId && scanCoreIdentifier(changeId)) ||
+    (traceId && scanCoreIdentifier(traceId))
+  ) {
+    return { index, reason: "core_pii", attemptedAction: action };
+  }
+
+  const built = createActivityEvent({
+    action,
+    actor: {
+      kind: actorKind as ActorKind,
+      id: actorId,
+      ...(typeof actorRef === "string" && actorRef ? { ref: actorRef } : {}),
+    },
+    source: source as ActivitySource,
+    outcome: {
+      status: status as ActivityStatus,
+      ...(errorClass ? { errorClass } : {}),
+      ...(durationMs !== undefined ? { durationMs } : {}),
+    },
+    scope: {
+      // AUTHENTICATED tenant only — the client's scope.tenantId is DISCARDED.
+      tenantId,
+      ...(changeId ? { changeId } : {}),
+      ...(traceId ? { traceId } : {}),
+    },
+    ...(typeof at === "string" ? { at } : {}),
+    ...(asString(e.id) ? { id: e.id as string } : {}),
+    // RAW payload — createActivityEvent re-redacts it (defense in depth).
+    ...(e.payload && typeof e.payload === "object" ? { payload: e.payload as ActivityPayload } : {}),
+  });
+
+  return { event: built.event, canaryTripped: built.report.canaryTripped, redactionHits: built.report.hits };
+}
+
+/** Validate + redact a whole posted batch under the authenticated tenant. */
+export function ingestEvents(events: unknown[], tenantId: string): IngestOutcome {
+  const accepted: AcceptedActivity[] = [];
+  const rejected: IngestRejection[] = [];
+  events.forEach((raw, i) => {
+    const r = ingestOne(i, raw, tenantId);
+    if ("event" in r) accepted.push(r);
+    else rejected.push(r);
+  });
+  return { accepted, rejected };
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Service-auth for `POST /api/activity` — HMAC-SHA256 over the raw
+ * body, with the authenticated TENANT bound into the signed material.
+ *
+ * WHY HMAC (not the bare `x-mcp-service-secret` shared-secret seam the
+ * webhook receivers use). Those receivers authenticate ONE trusted forwarder
+ * (tot-mcp) and read the tenant from a body the forwarder itself constructed —
+ * fine there. Activity ingest is different in two ways that make a plain shared
+ * secret insufficient:
+ *   1. It is fed by MANY emitters (the CLI dev cohort, the UI cohort) whose
+ *      payloads must not be tamperable in flight — the redaction canaries key
+ *      off byte-exact values, so body INTEGRITY is load-bearing.
+ *   2. Every row is TENANT-SCOPED and the scope must come from the authenticated
+ *      identity, not a client-set field. So the tenant is part of the SIGNED
+ *      material (`<tenant>\n<body>`): a caller cannot assert a tenant it was not
+ *      issued a signature for without holding the ingest secret, and cannot swap
+ *      the tenant without invalidating the signature. The route then writes
+ *      `scope.tenantId` from THIS verified header and discards any body value.
+ *
+ * The signing key is the `ACTIVITY_INGEST_SECRET` Worker secret, shared with the
+ * emitters' gateway (the CLI/UI post through a signer that holds it — the
+ * per-emitter key-distribution/rotation story is a downstream concern, noted as
+ * a TODO). Everything here is WebCrypto (`crypto.subtle`) so the edge bundle
+ * never imports `node:crypto`, matching the node-free posture of the contract.
+ */
+
+/** Header carrying the authenticated tenant assertion (bound into the HMAC). */
+export const TENANT_HEADER = "x-tot-activity-tenant";
+/** Header carrying the hex HMAC-SHA256 signature over `<tenant>\n<rawBody>`. */
+export const SIGNATURE_HEADER = "x-tot-activity-signature";
+
+export type IngestAuthResult =
+  | { ok: true; tenantId: string }
+  | { ok: false; status: 401 | 503; reason: string };
+
+/** Length-independent constant-time string compare — mirrors the shared-secret
+ *  seam in `api/changes/candidate-reconcile.ts`; avoids leaking the signature by
+ *  timing. */
+export function timingSafeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
+
+const encoder = new TextEncoder();
+
+function toHex(buf: ArrayBuffer): string {
+  const b = new Uint8Array(buf);
+  let out = "";
+  for (let i = 0; i < b.length; i++) out += (b[i] as number).toString(16).padStart(2, "0");
+  return out;
+}
+
+/**
+ * Hex HMAC-SHA256 of `message` under `secret`. Exported so the tests (and any
+ * server-side signer/gateway) sign with the exact same construction the verifier
+ * checks — a single source of truth for the wire format.
+ */
+export async function hmacSha256Hex(secret: string, message: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return toHex(sig);
+}
+
+/** The exact bytes signed: the authenticated tenant, then the raw request body,
+ *  separated by a newline the tenant can never contain (it is validated as a
+ *  single-line id upstream). Binding both means neither can be swapped
+ *  independently of the signature. */
+export function signingMaterial(tenantId: string, rawBody: string): string {
+  return `${tenantId}\n${rawBody}`;
+}
+
+/**
+ * Verify an inbound ingest request. `secret` is the resolved
+ * `ACTIVITY_INGEST_SECRET` (the route returns 503 BEFORE calling this when it is
+ * unset — an unconfigured seam is not an auth failure). Returns the authenticated
+ * `tenantId` on success; a 401 with a coarse reason otherwise (never echoes the
+ * expected signature or the secret).
+ */
+export async function verifyIngestAuth(
+  headers: Headers,
+  rawBody: string,
+  secret: string,
+): Promise<IngestAuthResult> {
+  const tenantId = (headers.get(TENANT_HEADER) ?? "").trim();
+  const presented = (headers.get(SIGNATURE_HEADER) ?? "").trim();
+  if (!tenantId) return { ok: false, status: 401, reason: "missing tenant" };
+  // A newline in the tenant id would let a caller forge the material framing.
+  if (/[\r\n]/.test(tenantId)) return { ok: false, status: 401, reason: "invalid tenant" };
+  if (!presented) return { ok: false, status: 401, reason: "missing signature" };
+  const expected = await hmacSha256Hex(secret, signingMaterial(tenantId, rawBody));
+  if (!timingSafeEqual(presented.toLowerCase(), expected)) {
+    return { ok: false, status: 401, reason: "bad signature" };
+  }
+  return { ok: true, tenantId };
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The single operational KILL SWITCH for the whole activity-telemetry pipeline.
+ *
+ * ONE flag — the `ACTIVITY_TELEMETRY_DISABLED` env var / Worker secret — switches
+ * EVERY server-side emit path to a no-op in one place:
+ *   • `recordActivity()` (the server emitter) — and therefore `recordUiActivity()`
+ *     (the UI cohort), which is a thin wrapper over it;
+ *   • `observeDeployVersion()` (the deploy-provenance observer);
+ *   • `POST /api/activity` (ingest) — accepts-and-drops so emitters never error.
+ * The out-of-process CLI (`emitActivity`) honours the SAME flag name in its own
+ * JS mirror. Wiring it at these SHARED chokepoints means no call site checks it.
+ *
+ * FAIL-OPEN — this gates ONLY the observability layer. The underlying operation
+ * (reconcile, preview-serve, ship, invite, a CLI command) never depends on telemetry
+ * and is never blocked by it; flipping the switch turns emits into no-ops while
+ * everything else runs unchanged. An unset/unknown flag ⇒ telemetry ENABLED (the
+ * normal state). Reading the flag can never throw.
+ *
+ * SYNC + PRIMED — `recordActivity()` is a synchronous, fire-and-forget best-effort
+ * call, so the switch must be checkable WITHOUT awaiting. `isActivityDisabled()`
+ * consults (a) a value PRIMED once per isolate from the async Worker env
+ * (`primeActivityKillSwitch()`, called at the middleware front door) and (b) the
+ * synchronously-available build/process env — so a build-time var takes effect in
+ * dev/tests immediately, and a Worker secret takes effect from the first primed
+ * request of each isolate.
+ */
+import { readEnv } from "../env.js";
+
+/** The one canonical flag name — shared verbatim by the server and the CLI mirror. */
+export const ACTIVITY_KILL_SWITCH_FLAG = "ACTIVITY_TELEMETRY_DISABLED";
+
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
+function truthy(v: string | null | undefined): boolean {
+  return typeof v === "string" && TRUTHY.has(v.trim().toLowerCase());
+}
+
+/** Primed once per isolate from the async Worker env. `undefined` until primed. */
+let primedDisabled: boolean | undefined;
+
+/** Synchronously-available env only (build-time `import.meta.env` + `process.env`) —
+ *  does NOT see Worker-only secrets, which arrive via {@link primeActivityKillSwitch}. */
+function fromSyncEnv(): boolean {
+  try {
+    const meta = (import.meta as unknown as { env?: Record<string, string | undefined> }).env;
+    if (meta && truthy(meta[ACTIVITY_KILL_SWITCH_FLAG])) return true;
+  } catch {
+    /* import.meta.env unavailable — ignore */
+  }
+  if (typeof process !== "undefined" && process.env && truthy(process.env[ACTIVITY_KILL_SWITCH_FLAG])) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * True when the entire activity pipeline is switched off. Sync + never throws.
+ * Fail-open: an unknown/unset flag ⇒ `false` (telemetry enabled).
+ */
+export function isActivityDisabled(): boolean {
+  return primedDisabled === true || fromSyncEnv();
+}
+
+/**
+ * Prime the kill switch from the (async) Worker env, once per isolate. Best-effort:
+ * a read fault leaves telemetry ENABLED (fail-open). Call at the middleware front door
+ * so every subsequent route emit in the isolate observes a Worker-secret flag.
+ */
+export async function primeActivityKillSwitch(): Promise<void> {
+  try {
+    primedDisabled = truthy(await readEnv(ACTIVITY_KILL_SWITCH_FLAG));
+  } catch {
+    primedDisabled = false;
+  }
+}
+
+/** Test-only: clear the primed cache so a test can re-exercise the prime path. */
+export function __resetActivityKillSwitchForTest(): void {
+  primedDisabled = undefined;
+}