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

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

@@ -9,18 +9,29 @@
  * event, so the two concerns stay separate: analytics stays anonymized, and
  * this stays a narrow, owner-only-readable accountability record.
  *
- * `sub` (the tot20-issued, stable user id) would be a better key than email —
- * email is a mutable account attribute, not the identity itself — but `sub`
- * is dropped before `SessionRecord` today (see `auth/session.ts`). Threading
- * it through is a real follow-up, not done here; email is what every call site
- * already has.
+ * MCP-submitted candidates carry the tot20-issued stable subject plus a verified
+ * email/display label. Storefront-local UI actions still use their authenticated
+ * session email until the same subject is threaded through `SessionRecord`.
  */
 import { displayNameFromEmail } from "./recordActivity";
 
 export type ChangeActorAction = "submit" | "reject" | "resolve" | "accept" | "ship" | "build";
 
+export interface ChangeActorIdentity {
+  kind: "human" | "service";
+  /** Immutable identity-provider subject for a person, or app subject for a service. */
+  subject: string;
+  /** Present only for a verified human identity. */
+  email: string | null;
+  /** Owner-facing label. */
+  name: string;
+}
+
 export interface ChangeActorRecord {
-  email: string;
+  /** Older records may predate structured identity and omit these two fields. */
+  kind?: ChangeActorIdentity["kind"];
+  subject?: string;
+  email: string | null;
   /** Best-effort display name — no real name is captured anywhere today, so
    *  this is always {@link displayNameFromEmail}'s local-part guess. Swap the
    *  source here (not the callers) if a real name ever becomes available. */
@@ -37,6 +48,14 @@ function attributionKey(tenantId: string, subjectId: string, action: ChangeActor
   return `cust:change-actor:${tenantId}:${subjectId}:${action}`;
 }
 
+function submitAuthorizationKey(
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): string {
+  return `cust:change-actor-authorization:${tenantId}:${changeId}:${authorizationId}`;
+}
+
 /**
  * Persist who took `action` on `subjectId` (a `changeId` for reject/accept/build,
  * or the aggregate id for ship). Best-effort — never blocks or fails the
@@ -51,6 +70,8 @@ export async function recordChangeActor(
 ): Promise<void> {
   try {
     const record: ChangeActorRecord = {
+      kind: "human",
+      subject: `email:${email.trim().toLowerCase()}`,
       email,
       name: displayNameFromEmail(email),
       at: new Date().toISOString(),
@@ -61,6 +82,65 @@ export async function recordChangeActor(
   }
 }
 
+/**
+ * Persist an actor as a required part of a privileged mutation's authorization
+ * boundary. Unlike {@link recordChangeActor}, storage failures propagate so the
+ * caller can fail closed before performing the mutation.
+ */
+export async function recordRequiredChangeActor(
+  kv: ChangeActorKv,
+  tenantId: string,
+  subjectId: string,
+  action: ChangeActorAction,
+  actor: ChangeActorIdentity,
+  at: string,
+): Promise<void> {
+  const record: ChangeActorRecord = { ...actor, at };
+  await kv.put(attributionKey(tenantId, subjectId, action), JSON.stringify(record));
+}
+
+/**
+ * Stage an immutable, per-attempt submit authorization before the forge write.
+ * This deliberately does not replace the canonical `submit` actor: a failed
+ * Gitea update must never make an older PR look like it was submitted by the
+ * actor whose later attempt failed.
+ */
+export async function recordCandidateSubmitAuthorization(
+  kv: ChangeActorKv,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+  actor: ChangeActorIdentity,
+  authorizedAt: string,
+): Promise<void> {
+  const record: ChangeActorRecord = { ...actor, at: authorizedAt };
+  await kv.put(
+    submitAuthorizationKey(tenantId, changeId, authorizationId),
+    JSON.stringify(record),
+  );
+}
+
+/** Read one exact pre-forge authorization. Missing/corrupt data fails closed. */
+export async function readCandidateSubmitAuthorization(
+  kv: ChangeActorKv,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): Promise<ChangeActorRecord | null> {
+  try {
+    const raw = await kv.get(submitAuthorizationKey(tenantId, changeId, authorizationId));
+    return raw ? JSON.parse(raw) as ChangeActorRecord : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Browser responses never need the immutable identity-provider subject. */
+export function ownerVisibleChangeActor(record: ChangeActorRecord): ChangeActorRecord {
+  const { subject: _subject, ...visible } = record;
+  return visible;
+}
+
 /** Read every recorded action's attribution for one subject. Best-effort per
  *  action: a missing/corrupt record is simply absent from the result, never
  *  a thrown error. */

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

@@ -101,7 +101,7 @@ export function observeDeployVersion(
   input: DeployVersionObservedInput = {},
 ): ActivityEvent | undefined {
   if (observedThisIsolate) return undefined;
-  // Kill switch (D8): telemetry off ⇒ skip the observation entirely (fail-open). Do
+  // Kill switch: telemetry off ⇒ skip the observation entirely (fail-open). Do
   // NOT set the per-isolate guard, so re-enabling emits the observation on the next call.
   if (isActivityDisabled()) return undefined;
   observedThisIsolate = true;

package/apps/storefront/src/lib/admin/adminShell.ts

@@ -22,6 +22,7 @@ const TAB_IDS = [
   "ai-workflows",
   "blog",
   "publish",
+  "integrations",
   "settings",
 ] as const;
 
@@ -35,6 +36,7 @@ const ASK_CONTEXTS: Record<string, string> = {
   "ai-workflows": "AI Workflows",
   blog: "Blog",
   publish: "Publish",
+  integrations: "Integrations",
   settings: "Settings",
 };
 

package/apps/storefront/src/lib/admin/envelope.ts

@@ -4,7 +4,6 @@
  * staff-override authorization (`resolveAdminTenantMode`) that admin.astro
  * actually runs. This module re-exports that type so every mock service under
  * `lib/admin/**` can keep importing it from a stable relative path
- * (`../../envelope`) without declaring a second, competing interface (decision
- * `envelope-type-duplication-follow-up`).
+ * (`../../envelope`) without declaring a second, competing interface.
  */
 export type { AdminTenantEnvelope } from "@/lib/adminTenantEnvelope";

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