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

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

@@ -18,6 +18,7 @@ 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";
+import { ManagedAnalyticsApiV1Facade } from "./managedAnalyticsService.js";
 
 /**
  * No-store JSON response — install/rotate bodies carry a one-time client
@@ -44,6 +45,13 @@ export async function getRegistryService(): Promise<AppRegistryService | Respons
   return new AppRegistryService(db, credentials);
 }
 
+/** Build the managed-analytics v1 service over the same tenant control-plane D1. */
+export async function getManagedAnalyticsService(): Promise<ManagedAnalyticsApiV1Facade | Response> {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "app registry not configured" }, 503);
+  return new ManagedAnalyticsApiV1Facade(fromD1(d1));
+}
+
 /** HTTP status per `RegistryError` code — the one shared fail-closed mapping. */
 const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
   scope_denied: 400,
@@ -52,6 +60,8 @@ const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
   invalid_state: 409,
   invalid_webhook_endpoint: 400,
   invalid_widget_placement: 400,
+  unknown_version: 404,
+  invalid_version_facets: 400,
 };
 
 /** Map a `RegistryError` to its HTTP status. Never echoes internals — code + message only. */

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

@@ -27,7 +27,7 @@
  *      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`
+ *      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

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

@@ -0,0 +1,281 @@
+/**
+ * The managed-app version-retention + atomic-rollback spine (ext-apps-02) — the
+ * MANAGED-APP analog of the tenant integration lifecycle's known-good/rollback
+ * (`integrationLifecycle.ts`). Where that module keeps a tenant's own resolved
+ * integration revisions and repoints `live` to a known-good one, this persists
+ * every activated managed-app VERSION's COMPLETE restorable facet set and rolls an
+ * installed app back to a prior version's whole facet set in one atomic step.
+ *
+ * Two acceptance properties are schema-level, not conventions:
+ *   - RETAINED — every activation is a new immutable `app_version_snapshots` row
+ *     carrying the app's FULL restorable facet set (code ref/digest + entry module,
+ *     public config, contributions, granted scopes, consent declaration, CSP
+ *     origins) as one JSON blob. Nothing is mutated in place; the row list IS the
+ *     retention history and audit trail (actor + time per activation).
+ *   - ATOMIC ROLLBACK — a rollback restores a retained version's COMPLETE facet set
+ *     in a SINGLE-ROW insert that copies that version's `facets` blob verbatim. You
+ *     get the whole prior facet set or nothing — never a partial/mixed activation,
+ *     never a silently-defaulted facet. It is forward-only (records `restoredFromSeq`
+ *     and appends a new activation), so history is never rewritten and the rollback
+ *     is itself an audited row.
+ *
+ * Fail-closed, mirroring the tenant lifecycle's discipline: a retained/restored
+ * facet set is scanned for secret material ({@link findForbiddenFields}) BEFORE any
+ * write, and a rollback to a version that was never retained is REFUSED with the
+ * store left completely untouched (no new row, current version unchanged).
+ *
+ * Pure over the `Queryable` seam (same shape `ConsentConfigStore`/`AppRegistryService`
+ * use), so it runs unchanged against real D1 in the Worker
+ * (`fromD1(env.STOREFRONT_APPS_DB)`) and an in-memory `node:sqlite` in tests. The
+ * current active version is `MAX(seq)` per install — the same "the latest row is
+ * current" model as `consent_config_revisions`.
+ */
+import type {
+  ExecutionTier,
+  PlanIntegrationEntry,
+  PlanIntegrationConsent,
+  NormalizedContribution,
+} from "@tot/public-runtime";
+import { findForbiddenFields } from "@tot/public-runtime";
+import type { Queryable, QueryStatement } from "../d1/catalog.js";
+
+/**
+ * One managed-app version's COMPLETE restorable facet set — everything a rollback
+ * must put back to reconstitute the prior version with no missing or defaulted
+ * facet. All values are public (no secret material); the store proves it with a
+ * secret scan before persisting.
+ */
+export interface AppVersionFacets {
+  /** The app package version this activation serves. */
+  appVersion: string;
+  /** The code identity — content digest of the pinned package. */
+  digest: string;
+  /** Where this version's code runs (elevated vs boxed). */
+  executionTier: ExecutionTier;
+  /** The exact-version entry module the lifecycle runtime imports. */
+  entry: PlanIntegrationEntry;
+  /** Resolved per-version public config; carries no secret material. */
+  publicConfig: Record<string, unknown>;
+  /** The normalized contributions this version registers. */
+  contributions: NormalizedContribution[];
+  /** The scopes granted to this version. */
+  scopes: string[];
+  /** The consent declaration the entry loader gates on. */
+  consent: PlanIntegrationConsent;
+  /** Sorted, deduped exact CSP origins this version needs. */
+  cspOrigins: string[];
+}
+
+/** One retained activation — an immutable version-retention/audit-trail entry. */
+export interface AppVersionSnapshot {
+  id: string;
+  installId: string;
+  tenantId: string;
+  /** Monotonic per install; the largest is the currently active version. */
+  seq: number;
+  /** Mirror of `facets.appVersion` for cheap listing/filtering. */
+  appVersion: string;
+  /** The complete restorable facet set. */
+  facets: AppVersionFacets;
+  /** Opaque actor id — never PII. */
+  actor: string;
+  note: string | null;
+  /** The source `seq` when this activation is a rollback, else null. */
+  restoredFromSeq: number | null;
+  createdAt: string;
+}
+
+/** Retain (activate) a new managed-app version, persisting its full facet set. */
+export interface RetainVersionInput {
+  installId: string;
+  tenantId: string;
+  facets: AppVersionFacets;
+  actor: string;
+  note?: string | null;
+}
+
+/** Roll an install back to a retained version, restoring its complete facet set. */
+export interface RollbackVersionInput {
+  installId: string;
+  /** The retained activation's `seq` — its stable version handle — to restore. */
+  toSeq: number;
+  actor: string;
+  note?: string | null;
+}
+
+export interface PlannedVersionWrite {
+  snapshot: AppVersionSnapshot;
+  statement: QueryStatement;
+}
+
+export type AppVersionErrorCode = "unknown_target" | "integrity";
+
+/** Thrown by every fail-closed refusal here — callers branch on `.code`. */
+export class AppVersionError extends Error {
+  constructor(
+    message: string,
+    readonly code: AppVersionErrorCode,
+    readonly detail?: string[],
+  ) {
+    super(message);
+    this.name = "AppVersionError";
+  }
+}
+
+interface SnapshotRow {
+  id: string;
+  install_id: string;
+  tenant_id: string;
+  seq: number;
+  app_version: string;
+  facets: string;
+  actor: string;
+  note: string | null;
+  restored_from_seq: number | null;
+  created_at: string;
+}
+
+function toSnapshot(row: SnapshotRow): AppVersionSnapshot {
+  return {
+    id: row.id,
+    installId: row.install_id,
+    tenantId: row.tenant_id,
+    seq: row.seq,
+    appVersion: row.app_version,
+    facets: JSON.parse(row.facets) as AppVersionFacets,
+    actor: row.actor,
+    note: row.note,
+    restoredFromSeq: row.restored_from_seq,
+    createdAt: row.created_at,
+  };
+}
+
+export class AppVersionStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+    private readonly newId: () => string = () => crypto.randomUUID(),
+  ) {}
+
+  /**
+   * Retain (activate) a managed-app version by appending a new immutable snapshot
+   * carrying its COMPLETE restorable facet set. The `seq` is assigned as
+   * `MAX(seq)+1` for that install; the UNIQUE `(install_id, seq)` index makes a
+   * concurrent double-assignment fail loudly rather than overwrite an earlier
+   * activation. Fail-closed: a facet set naming secret material is REFUSED before
+   * any write (defense in depth over the plan/evidence contracts that produced it).
+   */
+  async retainVersion(input: RetainVersionInput): Promise<AppVersionSnapshot> {
+    const planned = await this.planRetainVersion(input);
+    await this.db.run(planned.statement.sql, ...(planned.statement.params ?? []));
+    return planned.snapshot;
+  }
+
+  /** Validate and plan retention without writing, for a caller-owned D1 batch. */
+  async planRetainVersion(input: RetainVersionInput): Promise<PlannedVersionWrite> {
+    return this.planAppend(input.installId, input.tenantId, input.facets, input.actor, input.note ?? null, null);
+  }
+
+  /**
+   * Roll an install back to a retained version, restoring its COMPLETE facet set in
+   * one atomic single-row insert that copies the target activation's `facets` blob
+   * verbatim (forward-only: records `restoredFromSeq`). No partial/mixed state is
+   * reachable — the whole prior facet set is restored or nothing is. Fail-closed: a
+   * `toSeq` that was never retained is REFUSED (`unknown_target`) and the store is
+   * left completely untouched — no new row, the current version unchanged.
+   */
+  async rollbackTo(input: RollbackVersionInput): Promise<AppVersionSnapshot> {
+    const planned = await this.planRollbackTo(input);
+    await this.db.run(planned.statement.sql, ...(planned.statement.params ?? []));
+    return planned.snapshot;
+  }
+
+  /** Plan a forward rollback without advancing MAX(seq) until the batch commits. */
+  async planRollbackTo(input: RollbackVersionInput): Promise<PlannedVersionWrite> {
+    const target = await this.getSnapshot(input.installId, input.toSeq);
+    if (!target) {
+      throw new AppVersionError(
+        `Cannot roll back install "${input.installId}" to version seq ${input.toSeq}: no such retained version.`,
+        "unknown_target",
+      );
+    }
+    const note = input.note ?? `Rollback to version ${target.appVersion} (seq ${input.toSeq}).`;
+    return this.planAppend(
+      input.installId,
+      target.tenantId,
+      target.facets,
+      input.actor,
+      note,
+      input.toSeq,
+    );
+  }
+
+  /** The current (active) version of an install — `MAX(seq)` — or null if none retained. */
+  async currentVersion(installId: string): Promise<AppVersionSnapshot | null> {
+    const row = await this.db.first<SnapshotRow>(
+      `SELECT * FROM app_version_snapshots WHERE install_id = ? ORDER BY seq DESC LIMIT 1`,
+      installId,
+    );
+    return row ? toSnapshot(row) : null;
+  }
+
+  /** A specific retained activation by its `seq`, or null if absent. */
+  async getSnapshot(installId: string, seq: number): Promise<AppVersionSnapshot | null> {
+    const row = await this.db.first<SnapshotRow>(
+      `SELECT * FROM app_version_snapshots WHERE install_id = ? AND seq = ?`,
+      installId,
+      seq,
+    );
+    return row ? toSnapshot(row) : null;
+  }
+
+  /** An install's full retention history, newest first — the version audit trail. */
+  async listVersions(installId: string): Promise<AppVersionSnapshot[]> {
+    const rows = await this.db.all<SnapshotRow>(
+      `SELECT * FROM app_version_snapshots WHERE install_id = ? ORDER BY seq DESC`,
+      installId,
+    );
+    return rows.map(toSnapshot);
+  }
+
+  /**
+   * Append a new activation. Shared by retain (source `null`) and rollback (source
+   * `restoredFromSeq`). Scans the facet set for secret material BEFORE the insert,
+   * then writes exactly one row — the atomicity boundary: the whole facet set lands
+   * or nothing does.
+   */
+  private async planAppend(
+    installId: string,
+    tenantId: string,
+    facets: AppVersionFacets,
+    actor: string,
+    note: string | null,
+    restoredFromSeq: number | null,
+  ): Promise<PlannedVersionWrite> {
+    const forbidden = findForbiddenFields(facets, "facets");
+    if (forbidden.length > 0) {
+      throw new AppVersionError(
+        `Refusing to persist version facets naming secret material: ${forbidden.map((v) => v.path).join(", ")}.`,
+        "integrity",
+        forbidden.map((v) => v.path),
+      );
+    }
+    const maxRow = await this.db.first<{ max_seq: number | null }>(
+      `SELECT MAX(seq) AS max_seq FROM app_version_snapshots WHERE install_id = ?`,
+      installId,
+    );
+    const seq = (maxRow?.max_seq ?? 0) + 1;
+    const createdAt = this.now();
+    const id = `avs_${this.newId()}`;
+    const statement: QueryStatement = {
+      sql: `INSERT INTO app_version_snapshots
+         (id, install_id, tenant_id, seq, app_version, facets, actor, note, restored_from_seq, created_at)
+       VALUES (?,?,?,?,?,?,?,?,?,?)`,
+      params: [id, installId, tenantId, seq, facets.appVersion, JSON.stringify(facets), actor, note, restoredFromSeq, createdAt],
+    };
+    return {
+      statement,
+      snapshot: { id, installId, tenantId, seq, appVersion: facets.appVersion, facets, actor, note, restoredFromSeq, createdAt },
+    };
+  }
+}

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

@@ -0,0 +1,228 @@
+/**
+ * The merchant consent configuration store — the durable spine behind ext-admin-03.
+ * It persists a tenant's consent configuration as an APPEND-ONLY revision history and
+ * the demonstrated-CMP-demand ledger, and reads back exactly the shapes the pure
+ * ext-policy-03 layer consumes.
+ *
+ * Two acceptance properties are schema-level, not conventions:
+ *   - AUDITED — every save is a new immutable revision that names its actor and time;
+ *     nothing is mutated in place, so the revision list IS the audit trail.
+ *   - REVERSIBLE — a revert is a forward-only new revision that copies a prior config
+ *     and records `revertedFrom`; history is never rewritten, and rolling back leaves
+ *     its own audited entry.
+ *
+ * Pure over the `Queryable` seam (same shape `CandidateStore`/`OrdersStore` use), so it
+ * runs unchanged against real D1 in the Worker (`fromD1(env.STOREFRONT_APPS_DB)`) and an
+ * in-memory `node:sqlite` in tests. This is the DATA MODEL + repository API only — the
+ * validation (`validateConsentConfig`) and the broker materialization
+ * (`toTenantConsentPolicy`/`buildTenantConsentBroker`) live in `@tot/public-runtime`;
+ * this store persists already-validated JSON and never re-derives policy.
+ */
+import type { Queryable } from "../d1/catalog.js";
+import type { CmpDemandLedger, TenantConsentConfig } from "@tot/public-runtime";
+
+/** One persisted consent-config revision — an immutable audit-trail entry. */
+export interface ConsentConfigRevision {
+  id: string;
+  tenantId: string;
+  /** Monotonic per tenant; the largest is the current config. */
+  revision: number;
+  config: TenantConsentConfig;
+  /** Opaque actor id — never PII. */
+  actor: string;
+  note: string | null;
+  /** The source revision when this one is a revert, else null. */
+  revertedFrom: number | null;
+  createdAt: string;
+}
+
+/** Save a new revision of a tenant's (already-validated) consent configuration. */
+export interface SaveConsentConfigInput {
+  tenantId: string;
+  config: TenantConsentConfig;
+  actor: string;
+  note?: string | null;
+}
+
+/** Revert a tenant's consent configuration to a prior revision (forward-only). */
+export interface RevertConsentConfigInput {
+  tenantId: string;
+  /** The revision whose config to restore as a NEW revision. */
+  toRevision: number;
+  actor: string;
+  note?: string | null;
+}
+
+/** Record demonstrated demand for a CMP adapter from one tenant. */
+export interface RecordCmpDemandInput {
+  tenantId: string;
+  adapterId: string;
+  source?: string | null;
+}
+
+interface RevisionRow {
+  id: string;
+  tenant_id: string;
+  revision: number;
+  config: string;
+  actor: string;
+  note: string | null;
+  reverted_from: number | null;
+  created_at: string;
+}
+
+interface DemandRow {
+  id: string;
+  tenant_id: string;
+  adapter_id: string;
+  source: string | null;
+  at: string;
+}
+
+function toRevision(row: RevisionRow): ConsentConfigRevision {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    revision: row.revision,
+    config: JSON.parse(row.config) as TenantConsentConfig,
+    actor: row.actor,
+    note: row.note,
+    revertedFrom: row.reverted_from,
+    createdAt: row.created_at,
+  };
+}
+
+export class ConsentConfigStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+    private readonly newId: () => string = () => crypto.randomUUID(),
+  ) {}
+
+  /**
+   * Append a new revision of a tenant's consent config. The revision number is
+   * assigned as `MAX(revision)+1` for that tenant; the UNIQUE `(tenant_id, revision)`
+   * index makes a concurrent double-assignment fail loudly rather than overwrite an
+   * earlier entry. The prior revisions are never touched — the history is the audit.
+   */
+  async saveRevision(input: SaveConsentConfigInput): Promise<ConsentConfigRevision> {
+    return this.appendRevision(input.tenantId, input.config, input.actor, input.note ?? null, null);
+  }
+
+  /**
+   * Restore a prior revision as a NEW revision (forward-only revert). Reads the target
+   * revision's config and appends it again with `revertedFrom` set — so a rollback is
+   * itself an audited entry and no history is rewritten. Throws if the target is absent.
+   */
+  async revertTo(input: RevertConsentConfigInput): Promise<ConsentConfigRevision> {
+    const target = await this.getRevision(input.tenantId, input.toRevision);
+    if (!target) {
+      throw new Error(
+        `Cannot revert tenant "${input.tenantId}" to revision ${input.toRevision}: no such revision.`,
+      );
+    }
+    const note = input.note ?? `Revert to revision ${input.toRevision}.`;
+    return this.appendRevision(input.tenantId, target.config, input.actor, note, input.toRevision);
+  }
+
+  private async appendRevision(
+    tenantId: string,
+    config: TenantConsentConfig,
+    actor: string,
+    note: string | null,
+    revertedFrom: number | null,
+  ): Promise<ConsentConfigRevision> {
+    const maxRow = await this.db.first<{ max_revision: number | null }>(
+      `SELECT MAX(revision) AS max_revision FROM consent_config_revisions WHERE tenant_id = ?`,
+      tenantId,
+    );
+    const revision = (maxRow?.max_revision ?? 0) + 1;
+    const createdAt = this.now();
+    await this.db.run(
+      `INSERT INTO consent_config_revisions
+         (id, tenant_id, revision, config, actor, note, reverted_from, created_at)
+       VALUES (?,?,?,?,?,?,?,?)`,
+      `ccr_${this.newId()}`,
+      tenantId,
+      revision,
+      JSON.stringify(config),
+      actor,
+      note,
+      revertedFrom,
+      createdAt,
+    );
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? AND revision = ?`,
+      tenantId,
+      revision,
+    );
+    return toRevision(row!);
+  }
+
+  /** The current (latest) revision of a tenant's consent config, or null if none saved. */
+  async currentRevision(tenantId: string): Promise<ConsentConfigRevision | null> {
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ?
+        ORDER BY revision DESC LIMIT 1`,
+      tenantId,
+    );
+    return row ? toRevision(row) : null;
+  }
+
+  /** A specific revision, or null if absent. */
+  async getRevision(tenantId: string, revision: number): Promise<ConsentConfigRevision | null> {
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? AND revision = ?`,
+      tenantId,
+      revision,
+    );
+    return row ? toRevision(row) : null;
+  }
+
+  /** A tenant's full revision history, newest first — the audit trail. */
+  async listRevisions(tenantId: string): Promise<ConsentConfigRevision[]> {
+    const rows = await this.db.all<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? ORDER BY revision DESC`,
+      tenantId,
+    );
+    return rows.map(toRevision);
+  }
+
+  /**
+   * Record demonstrated demand for a CMP adapter from one tenant. Idempotent per
+   * `(tenant, adapter)` — a tenant re-asking updates the recorded time/source on the
+   * SAME row and never inflates the distinct-tenant demand count.
+   */
+  async recordCmpDemand(input: RecordCmpDemandInput): Promise<void> {
+    await this.db.run(
+      `INSERT INTO consent_cmp_demand (id, tenant_id, adapter_id, source, at)
+       VALUES (?,?,?,?,?)
+       ON CONFLICT(tenant_id, adapter_id) DO UPDATE SET
+         source = excluded.source,
+         at = excluded.at`,
+      `cmd_${this.newId()}`,
+      input.tenantId,
+      input.adapterId,
+      input.source ?? null,
+      this.now(),
+    );
+  }
+
+  /**
+   * The whole demand ledger, in the `@tot/public-runtime` shape — passed straight into
+   * `validateConsentConfig` so a CMP choice is admitted only from demonstrated demand.
+   */
+  async demandLedger(): Promise<CmpDemandLedger> {
+    const rows = await this.db.all<DemandRow>(
+      `SELECT * FROM consent_cmp_demand ORDER BY adapter_id ASC, tenant_id ASC`,
+    );
+    return {
+      signals: rows.map((r) => ({
+        adapterId: r.adapter_id,
+        tenantPublicId: r.tenant_id,
+        at: r.at,
+        source: r.source ?? undefined,
+      })),
+    };
+  }
+}