@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,6 +1,6 @@
 /**
  * Operator-session resolution for the Private Apps admin API
- * (`/api/apps/admin/*`, PrivateApps epic, D2 Chunk C). Adapted from
+ * (`/api/apps/admin/*`). Mirrors
  * `../grants/session.ts`'s owner-session resolution — same two paths, same
  * fail-closed shape — but resolves `{ tenantId, actor }` instead of `{ owner }`:
  *
@@ -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
@@ -38,7 +38,7 @@
  * 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:
+ * 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 —
@@ -61,6 +61,11 @@ 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";
+import {
+  authorizeBearerOperator,
+  resolveHostBoundSession,
+  type SessionFailure,
+} from "@/lib/auth/operatorSession.js";
 
 /** Capabilities that make a signed-in viewer an app-registry operator for their tenant. */
 const ADMIN_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
@@ -88,33 +93,30 @@ export interface AdminAuthInput {
 
 export type AdminAuthResult =
   | { ok: true; tenantId: string; actor: string; role?: string }
-  | { ok: false; status: number; message: string };
+  | SessionFailure;
+
+/** The one authorized-success shape both host-bound and Bearer admin paths return. */
+type AdminAuthOk = Extract<AdminAuthResult, { ok: true }>;
 
 /**
  * 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.
+ * 401, no resolvable tenant → 400. A thin adapter over the shared
+ * Bearer-operator core that maps its resolved `principal` to this surface's
+ * `tenantId` and stamps the fixed `BEARER_ACTOR` (no per-caller identity here).
  */
 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 };
+  const res = authorizeBearerOperator({
+    authHeader: input.authHeader,
+    gateSecret: input.gateSecret,
+    configuredPrincipal: input.configuredTenant,
+    requestedPrincipal: input.requestedTenant,
+    unconfiguredMessage: "apps admin operator secret not configured",
+    unresolvedMessage: "tenant unresolved (set APPS_ADMIN_TENANT or X-Tot-Tenant)",
+  });
+  return res.ok
+    ? { ok: true, tenantId: res.principal, actor: BEARER_ACTOR }
+    : res;
 }
 
 /** One-way, stable pseudonym for an audit `actor` — never the email itself. */
@@ -128,30 +130,37 @@ async function actorFromEmail(email: string): Promise<string> {
  * 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 {
+  return resolveHostBoundSession<AdminAuthOk>(context, {
+    capabilities: ADMIN_CAPABILITIES,
+    // A resolved-but-insufficient viewer fails closed with 403 and does NOT
+    // fall through to the Bearer gate — an authenticated-but-under-privileged
+    // caller must not be silently admitted by a secret it also presents.
+    onInsufficientCapability: {
+      mode: "failClosed",
+      failure: {
         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"),
+      },
+    },
+    // Path 1: the tenant IS the resolved host's appDomain — never the body.
+    resolveViewer: async (viewer, tenantId) => ({
+      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.
+    resolveBearer: async (ctx) => {
+      const gateSecret = await readEnv("APPS_ADMIN_SECRET");
+      const configuredTenant = await readEnv("APPS_ADMIN_TENANT");
+      return authorizeAdmin({
+        authHeader: ctx.request.headers.get("authorization"),
+        gateSecret,
+        configuredTenant,
+        requestedTenant: ctx.request.headers.get("x-tot-tenant"),
+      });
+    },
   });
 }
 

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

@@ -1,7 +1,7 @@
 /**
- * The D3 scoped-API authorization boundary (PrivateApps epic) — every
+ * The scoped-API authorization boundary — every
  * `/api/apps/v1/*` route calls `authorizeAppRequest` FIRST. Verifies the
- * app-gateway bearer JWT (D2's `AppTokenVerifier`), resolves the calling
+ * app-gateway bearer JWT (`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`.
  *

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

@@ -1,6 +1,6 @@
 /**
- * Response helpers shared by every `/api/apps/v1/*` route (PrivateApps epic,
- * D3) — a no-store JSON responder (mirrors `../grants/route.ts` /
+ * Response helpers shared by every `/api/apps/v1/*` route — a no-store JSON
+ * responder (mirrors `../grants/route.ts` /
  * `./adminService.ts`'s pattern) plus the `tot-request-id` / `traceparent`
  * response headers `docs/private-apps/contract/openapi.yaml` documents on
  * every operation.

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/catalogMapper.ts

@@ -1,5 +1,5 @@
 /**
- * Maps the internal `CatalogProduct` read model to the D3 contract's
+ * Maps the internal `CatalogProduct` read model to the scoped-API contract's
  * `Product` shape (`docs/private-apps/contract/openapi.yaml`, schema
  * `Product` — `additionalProperties: false`). Drops every internal field
  * the contract doesn't declare (variants, images, metafields, source, …) so

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,
+      })),
+    };
+  }
+}