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

package/apps/storefront/tsconfig.json

@@ -1,4 +1,9 @@
 {
+  // Unlike the packages/* configs (which extend the repo's ../../tsconfig.base.json),
+  // the storefront extends Astro's own preset: it wires up .astro type resolution
+  // (.astro/types.d.ts), Astro/Vite bundler module resolution, and the Preact JSX
+  // runtime the client islands compile against. verbatimModuleSyntax is turned off
+  // (the base sets it on) because the JSX/Preact + Astro compilation model needs it.
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "strict": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "1.4.0",
+  "version": "1.4.2-rc.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@tot/public-runtime",
   "version": "0.1.0",
+  "description": "Public, edge-shipped storefront runtime model — renderer-safe tenant/product/catalog types, the CSP builder, the customization read/apply runtime, and the activity-telemetry contract. Node-free and open-sourceable; bundles into the Cloudflare Worker and must not import @tot/private-controlplane.",
   "private": true,
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/packages/public-runtime/src/activity/README.md

@@ -0,0 +1,146 @@
+# Operational activity telemetry — the actor×action contract (card D0)
+
+The foundation the D1–D8 cards build on. Everything here is **pure types + pure
+functions** in `@tot/public-runtime` (the node-free, dependency-free edge base),
+so the storefront server, the Cloudflare Worker edge bundle, and the CLI's JS
+mirror can all consume it. Nothing here does I/O or picks a store — the store
+**decision** and cost model live in the repo-root `DECISIONS.md` §8; the
+per-action store **routing** lives on each catalog entry (`sinks`).
+
+Files:
+
+| File | What |
+|------|------|
+| `event.ts` | The `ActivityEvent` envelope, `ACTIVITY_SCHEMA_VERSION`, `newEventId()`. |
+| `catalog.ts` | The allowlisted `ACTION_CATALOG` registry + `ActionKey` + guards. |
+| `redaction.ts` | Default-deny redaction contract + `createActivityEvent()` (the safe constructor). |
+
+## The envelope
+
+One event says: **an ACTOR performed an ACTION, here is the OUTCOME**, scoped to
+a tenant/change, from a source, at a time. The design invariant is a hard split
+between two zones:
+
+- **Core fields** (`v`, `id`, `at`, `actor`, `action`, `source`, `scope`,
+  `outcome`) — *always safe to store, never redacted*. They carry no free text
+  and no third-party PII **by construction**: `actor.id` is opaque, `action` is
+  an allowlisted catalog key, `outcome.errorClass` is a low-cardinality class
+  (never a raw message).
+- **`payload`** (`args` + `rendered`) — the *extensible, always-redacted* zone.
+  Whatever a call site puts here is default-**denied**.
+
+```ts
+import { createActivityEvent } from "@tot/public-runtime";
+
+const { event, report } = createActivityEvent({
+  action: "cli.command.result",          // must be a catalog key (compile-checked)
+  actor:  { kind: "dev", id: hashedDevId },
+  source: "cli",
+  scope:  { tenantId, traceId },
+  outcome:{ status: "succeeded", durationMs: 812 },
+  payload:{ args: { command: "ship", cliVersion: "1.4.0", exitCode: 0,
+                    secretToken: "…" } }, // ← dropped: not allowlisted / key canary
+});
+// event.payload.args === { command: "ship", cliVersion: "1.4.0", exitCode: 0 }
+```
+
+`createActivityEvent()` is the **only** sanctioned constructor: it fills
+`v`/`id`/`at` and runs the raw payload through the redaction contract, so you
+**cannot** produce an event whose payload skipped redaction.
+
+## The action catalog
+
+`action` is never a free string — it is a key of `ACTION_CATALOG`. Each entry
+declares `actors` (who may emit it), `source`, `sinks` (store routing), and the
+default-deny `argsAllow` / `renderedAllow` payload allowlists. Adding a new
+action = a deliberate edit to `catalog.ts` (+ the CLI mirror, below), never an
+ad-hoc string at a call site. This is what keeps the D5 query surface and the
+D6/D7 alert rules tractable.
+
+### The naming standard (two tiers)
+
+Every key is dot-namespaced and its **first segment is a `<domain>`** — there are
+**no un-namespaced keys**. The domain prefix is stable so dashboards and alert rules
+can glob it (`change.*`, `preview.*`, …). Within that, the catalog uses **two shapes**,
+chosen by whether the action is atomic or two-phase:
+
+- **`<domain>.<verb>` (imperative)** — an **atomic** action that happens in one shot.
+  Examples: `change.ship`, `change.revert`, `change.go_live`, `grant.invite`,
+  `grant.revoke`, `store.connect`, `preview.override`.
+- **`<domain>.<entity>.<verb|state>` (participle/state)** — a **two-phase / async**
+  action that **opens then closes** (an invoke/result pair, or a received→terminal span).
+  Examples: `cli.command.invoked` + `cli.command.result`, `preview.build.requested` +
+  `preview.build.completed`, `webhook.reconcile.received` + `reconcile.terminal`.
+
+The **domain must be one of the closed set**: `cli`, `dev`, `preview`, `webhook`,
+`reconcile`, `deploy`, `change`, `content`, `grant`, `store`, `app`, `agent`, `system`.
+Adding a key with a new domain is a deliberate decision — widen this list here first.
+
+**Two-phase pairing going forward:** a **new** two-phase action pairs `.invoked` /
+`.result`. The pre-existing `.requested` / `.completed` (`preview.build.*`) and
+`.received` / `.terminal` (`webhook.reconcile.received` + `reconcile.terminal`) pairs are
+**grandfathered as-is — do not rename them** (`alerts.ts` hardcodes some of these literals,
+so a rename would silently break the D7 detectors).
+
+The initial catalog was reverse-engineered from the activity surfaces that **already
+exist informally** in this repo (CLI dispatch + `~/.tot/activity.log`, the obstacle
+beacon, the local→hosted dev bridge, preview/reconcile/webhook, deploy provenance, the
+ShipLoop `CHANGE_STATES` + admin ship routes, app installs), so D1–D3 map onto it 1:1.
+
+## The redaction contract (the D8 attack surface)
+
+Applied to `payload` for every event, in order:
+
+1. **Default-deny allowlist** — only the top-level keys named by the action's
+   `argsAllow`/`renderedAllow` are eligible. Everything else is **dropped**: not
+   stored, not logged, never "kept raw and redacted later".
+2. **Primitive-only values** — an allowlisted value must be string/number/bool.
+   Objects/arrays are dropped (nested structures are where secrets hide; we do
+   not walk them). Structured args flatten into named primitive keys at the call
+   site.
+3. **Canary scan** — allowlisted primitives are scanned for secret/PII **shapes**
+   (JWT, bearer, AWS/GitHub/Slack/OpenAI keys, private keys, email, card, phone,
+   high-entropy tokens) and secret-looking **key names** (`token`, `secret`,
+   `password`, `authorization`, …). A value hit → replaced with `«redacted»` and
+   reported (`report.canaryTripped`); a key-name hit → dropped outright.
+
+The `RedactionReport` returned alongside the event carries **the fact of** each
+drop/hit (lane, key, reason, canary label) — never the offending value. D4's
+ingest logs it and emits `system.ingest.rejected` when a canary trips; D6/D7
+alert on `canaryTripped`.
+
+## Consuming this from the downstream cards
+
+- **D1 server `recordActivity()`** — import `createActivityEvent`, build the
+  event, fan out to the sinks named on the action's `spec.sinks` (start with
+  `logs`; supersede the interim `apps/storefront/src/lib/activity/recordActivity.ts`
+  slice, whose `candidate.reject` becomes `change.reject`).
+- **D2 deploy provenance** — emit `deploy.version_observed`.
+- **D3 CLI `emitActivity`** — the CLI is **pure JS and does not import TS
+  packages** (it publishes to npm standalone and mirrors TS contracts with
+  keep-in-step tests, e.g. `no-gitea-links.test.mjs`). So D3 ships a small JS
+  mirror of the `ActionKey` list + the safe-constructor shape, plus a
+  keep-in-step test that fails the build if the mirror drifts from
+  `catalog.ts`. **Do not** make the CLI depend on `@tot/public-runtime`.
+- **D4 ingest + store** — validate with `isActionKey` + `isActorAllowed`, run
+  `redactPayload` (belt-and-suspenders even though emitters already redacted),
+  route by `spec.sinks`. See `DECISIONS.md` §8 for the D1 table (`activity_events`
+  in `STOREFRONT_APPS_DB`, alongside the existing `app_audit_log`) and the
+  Analytics Engine binding to provision.
+- **D5 query/timeline UI** — reads the `timeline`-sink rows from D1.
+
+## Open questions deliberately left for downstream
+
+- **Actor-id pseudonymization salt** (D1/D4). This module scrubs PII that leaks
+  into the *payload*, but `actor.id` in the core zone is the emitter's job to
+  pseudonymize. A shared salted non-reversible hash helper (salt as a Worker
+  secret) should land with D1/D4 — do **not** bake a weak unsalted hash into this
+  edge-shipped package.
+- **Analytics Engine binding + D1 `activity_events` schema** (D4). Named in
+  `DECISIONS.md` §8; the actual `wrangler.toml` binding and the Drizzle migration
+  are D4's to write.
+- **Retention/pruning job for the D1 timeline** (D4/D5). Arbitrary retention is
+  the reason the queryable cohort is in D1 not Analytics Engine; the pruning
+  cron is downstream.
+- **Agent cohort payload** — `agent.action.*` keys are a placeholder spine with
+  minimal args until the agent-cohort card defines what an agent may record.