cursedbelt 2.7.0 → 3.0.0

package/src/server/runtime/localHost.ts

@@ -1,530 +0,0 @@
-/**
- * The LOCAL profile's host plumbing (02 §1) — everything `bootEngineApp`
- * deliberately does not construct.
- *
- * The recipe refuses to invent paths, keys or a telemetry database, and that
- * refusal is a law (handle injection, 01 §1.1.3): a library that opens its own
- * files puts the storage layout back inside the library, where a generated app
- * can never change it. But the work still has to happen somewhere, and "somewhere"
- * must not be N copies of the same twenty lines pasted into N generated
- * `server.ts` files — that is precisely the divergence the recipe exists to end.
- *
- * So this is the local host, once, as a tested unit. It owns four things a
- * machine-level host owns and a library must not:
- *
- *   1. **Where the app's data lives** — `<app-data-home>/instances/<appId>`, where
- *      the home is CONFIGURATION ({@link resolveAppDataHome}): an explicit
- *      argument, else `$APP_DATA_HOME`, else the OS convention. Never a bespoke
- *      `~/.<app>` directory, and never a folder named after one machine's owner.
- *   2. **Key custody.** The object-store URL signing key and the telemetry row
- *      integrity key are minted once, persisted `0600`, and read back **as bytes**
- *      — never as a string (V6 `key-material-as-string`; a hex string of a key
- *      lands in GC-managed RAM with no way to zeroize it).
- *   3. **The telemetry tier**, opened and migrated, with the row signer
- *      `meter_events.row_signature` is NOT NULL for.
- *   4. **The GuardEngine's identity tier** ({@link createLocalGuardServices}) —
- *      the app's own registry file, the argon2id binding, and the
- *      manager/secrets/identity trio `bootEngineApp({ guardDeps })` needs. Split
- *      out rather than folded in, so an app with no guard engine opens no
- *      registry file and loads no native KDF.
- *   5. **The DevStudio's registry handle** ({@link createLocalDevServices}) —
- *      same split, same reason.
- *
- * A SaaS host wires its own equivalents (pooled Postgres, S3, a shared telemetry
- * database); nothing here is reachable from that path.
- */
-import { Database } from 'bun:sqlite';
-import { generateKeyPairSync } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, type Stats, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import {
-  assertArgon2idReady,
-  CC_SALT_BYTES,
-  createRowSigner,
-  createSecretEnvelopeManager,
-  SecureKey,
-} from 'cwip/guard';
-import {
-  CC_REGISTRY_MIGRATIONS,
-  CC_REGISTRY_NAMESPACE,
-  createRegistryIdentityStore,
-  createRegistrySecretsStore,
-} from 'cwip/cc-registry';
-import { assertCcPragmas, getTxnLifetimeGuard, runNamespacedMigrations } from 'cwip/sqlite';
-import { createSqliteExecutor, type StatementExecutor } from 'cwip/storage';
-import { registerNodeRsArgon2id } from '../guard/argon2Binding';
-import { createSessionSigner, type SessionSigner } from '../guard/sessionSigner';
-import type { ScreenshotSource } from '../services';
-import type { ScreenshotView } from '../mixins/services';
-import type { DevServiceDeps, GuardServiceDeps } from './recipe';
-import {
-  createTelemetryWriter,
-  openTelemetryDatabase,
-  type TelemetryDatabase,
-  type TelemetryWriter,
-} from 'cwip/telemetry';
-import { resolveAppDataHome } from '../paths/appDataHome';
-
-/** Bytes in a minted key file. Matches cwip's `CC_KEY_BYTES`. */
-export const HOST_KEY_BYTES = 32;
-
-export interface ResolveAppDataRootOptions {
-  readonly appId: string;
-  /** Explicit override (a `--data-root` flag, `CC_DATA_ROOT`). Wins outright. */
-  readonly override?: string;
-  /** Environment to read `APP_DATA_HOME` from. Injected by tests. */
-  readonly env?: Record<string, string | undefined>;
-}
-
-/**
- * `<app-data-home>/instances/<appId>` — the app's data root.
- *
- * A HOST function, not a library one: `openDomainHandles` still refuses to derive
- * a path, and this is the thing that hands it one. The home underneath it is
- * {@link resolveAppDataHome} — configuration, then the OS convention, and nothing
- * else. A published package may not go looking for a directory it invented in
- * somebody's home.
- */
-export function resolveAppDataRoot(options: ResolveAppDataRootOptions): string {
-  const override = options.override?.trim();
-  if (override) return path.resolve(override);
-  return path.join(resolveAppDataHome({ env: options.env }), 'instances', options.appId);
-}
-
-/**
- * Read a persisted key file, minting it on first boot. Bytes in, bytes out —
- * the material is never rendered as a string, and the file is `0600` from the
- * moment it exists (written to a temp name and chmod'd before the rename would be
- * stricter still; `writeFileSync` with `mode` is applied at create time, which
- * closes the window for a file this process creates).
- */
-export function loadOrMintKeyFile(file: string, byteLength: number = HOST_KEY_BYTES): Uint8Array {
-  if (existsSync(file)) {
-    const bytes = new Uint8Array(readFileSync(file));
-    if (bytes.byteLength === byteLength) return bytes;
-    throw new Error(
-      `Key file ${file} holds ${bytes.byteLength} bytes, expected ${byteLength}. Refusing to sign with a truncated key — move the file aside to mint a fresh one (this invalidates URLs signed with the old key).`,
-    );
-  }
-  mkdirSync(path.dirname(file), { recursive: true });
-  const key = SecureKey.random(byteLength, path.basename(file));
-  const material = key.use((bytes) => new Uint8Array(bytes));
-  writeFileSync(file, material, { mode: 0o600 });
-  chmodSync(file, 0o600); // umask cannot loosen an explicit chmod
-  key.destroy();
-  return material;
-}
-
-/**
- * The app's session-signing key, minted once and persisted `0600` as a PKCS8 PEM.
- *
- * `createSessionSigner()` with no key generates an EPHEMERAL Ed25519 pair, which
- * is correct only for a single-process dev server: every restart invalidates
- * every live session (a deploy silently logs every user out) and a second
- * process — the saas worker, a companion — cannot verify a token the server
- * minted. Persisting the key is what makes both work, so the local host does it
- * rather than leaving each generated app to rediscover the problem.
- */
-export function loadOrMintSessionKey(file: string): string {
-  if (existsSync(file)) return readFileSync(file, 'utf8');
-  const { privateKey } = generateKeyPairSync('ed25519');
-  const pem = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string;
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, pem, { mode: 0o600 });
-  chmodSync(file, 0o600);
-  return pem;
-}
-
-export interface CreateLocalHostServicesOptions {
-  readonly appId: string;
-  /** The app data root (see {@link resolveAppDataRoot}). Created if absent. */
-  readonly root: string;
-  /** Override the machine-tier telemetry home (tests, sandboxed runs). */
-  readonly appManagedHome?: string;
-  /** Session lifetime. Feed it `guard.features.sessionTtlMinutes × 60`. Default 1h. */
-  readonly sessionTtlSeconds?: number;
-}
-
-export interface LocalHostServices {
-  readonly root: string;
-  readonly telemetry: TelemetryWriter;
-  /**
-   * The opened telemetry tier — the WRITER's own handle, exposed because
-   * `meter_events` is also the only source of truth for USAGE (01 §4.1), and
-   * `createBillingService` reads it. Without this a host that needs billing (the
-   * saas profile composes it unconditionally) had to open a SECOND connection to
-   * the same file, which is two handles racing one WAL for a read the writer's
-   * own connection could serve.
-   */
-  readonly telemetryDb: TelemetryDatabase;
-  /** Where `createFsObjectStore` keeps bytes. */
-  readonly objectStoreRoot: string;
-  /** The HMAC key behind local signed object URLs — persisted, never regenerated per boot. */
-  readonly objectStoreSigningKey: Uint8Array;
-  /** The jobs queue handle the local broker runs on. */
-  readonly jobsDb: Database;
-  /**
-   * `governance.db` — the audit trail's own file, and an executor over it.
-   *
-   * Its OWN file on purpose. `createGovernanceTier`'s audit sink must not reach
-   * the storage provider the interceptor is attached to: a sink that writes back
-   * into an intercepted domain deadlocks on that domain's op mutex, permanently
-   * (see `cwip`'s `auditTrail.ts`). A separate handle makes that structurally
-   * impossible rather than a rule somebody has to remember, and it also means an
-   * audit trail survives a `rm` of a domain file — which is exactly the sequence
-   * of events an audit trail exists to describe.
-   */
-  readonly governanceDb: Database;
-  readonly governanceExecutor: StatementExecutor;
-  /**
-   * The session signer, over a PERSISTED key: sessions survive a restart and a
-   * second process can verify what this one minted.
-   */
-  readonly signer: SessionSigner;
-  /** Flush telemetry, close the handles this created. */
-  close(): Promise<void>;
-}
-
-/**
- * Build the local host's services. Idempotent across boots: the keys persist, so
- * a signed media URL minted before a restart still verifies after it (regenerating
- * the signing key per boot silently 404s every `<img>` on the page after a deploy).
- */
-export function createLocalHostServices(options: CreateLocalHostServicesOptions): LocalHostServices {
-  const root = path.resolve(options.root);
-  mkdirSync(root, { recursive: true });
-
-  const objectStoreRoot = path.join(root, 'objects');
-  mkdirSync(objectStoreRoot, { recursive: true });
-  const objectStoreSigningKey = loadOrMintKeyFile(path.join(root, 'object-signing.key'));
-
-  let telemetryDb: TelemetryDatabase | null = null;
-  telemetryDb = openTelemetryDatabase({
-    open: (file: string) => new Database(file, { create: true }) as never,
-    ...(options.appManagedHome === undefined ? {} : { appManagedHome: options.appManagedHome }),
-  });
-  const integrityKey = SecureKey.adopt(loadOrMintKeyFile(path.join(root, 'row-integrity.key')), 'machine-integrity');
-  const telemetry = createTelemetryWriter({
-    db: telemetryDb.db,
-    spillPath: telemetryDb.paths.spillPath,
-    signer: createRowSigner({ integrityKey }),
-  });
-
-  const jobsDb = new Database(path.join(root, 'jobs.db'), { create: true });
-  const governanceDb = new Database(path.join(root, 'governance.db'), { create: true });
-  const governanceExecutor = createSqliteExecutor(governanceDb);
-  const signer = createSessionSigner({
-    privateKey: loadOrMintSessionKey(path.join(root, 'session.key')),
-    ttlSeconds: options.sessionTtlSeconds ?? 3600,
-  });
-
-  return {
-    root,
-    telemetry,
-    telemetryDb,
-    objectStoreRoot,
-    objectStoreSigningKey,
-    jobsDb,
-    governanceDb,
-    governanceExecutor,
-    signer,
-    async close() {
-      // Flush BEFORE closing the handle: queued meter events are billing rows,
-      // and dropping them on shutdown is the one loss this tier may never take.
-      await telemetry.flush?.();
-      await telemetry.close?.();
-      integrityKey.destroy();
-      jobsDb.close();
-      governanceDb.close();
-      telemetryDb?.close();
-    },
-  };
-}
-
-/* ------------------------------------------------------------------ guard */
-
-export interface CreateLocalGuardServicesOptions {
-  /** The app data root (see {@link resolveAppDataRoot}). Created if absent. */
-  readonly root: string;
-  /**
-   * Arm the process-wide argon2id seam. Default: {@link registerNodeRsArgon2id}
-   * (the optional `@node-rs/argon2` peer). A host with a different binding —
-   * libsodium, a Worker-backed one — passes its own registration here; a test
-   * passes a deterministic stub. There is deliberately no "no KDF" path: the
-   * `assertArgon2idReady()` below turns a forgotten binding into a boot failure
-   * rather than a 500 on the first user's login.
-   */
-  readonly registerKdf?: () => void | Promise<void>;
-  /** Open the registry file. Injected by tests (`:memory:`). */
-  readonly openDatabase?: (file: string) => Database;
-}
-
-export interface LocalGuardServices {
-  /** The app's registry file — `<root>/registry.db`. */
-  readonly registryFile: string;
-  /**
-   * The opened handle. Exposed because the DEV engine wants the same one
-   * (`devDeps.registry`): two handles on one sqlite file is two write locks
-   * contending, and the second one's pragma assertion fighting the first.
-   */
-  readonly registryDb: Database;
-  /** Exactly what `bootEngineApp({ guardDeps })` takes. */
-  readonly deps: GuardServiceDeps;
-  /** Dispose the txn-lifetime guard, close the handle, zeroize the integrity key. */
-  close(): void;
-}
-
-/**
- * The GuardEngine half of the local host (02 §2-tail) — the seam that makes a
- * generated app genuinely loginable.
- *
- * `AccountService`, the auth routes and the wired limiter all landed in 02 §1/§2,
- * but no SHIPPING host ever constructed `guardDeps`, so a real generated app
- * still answered 404 on `/api/guard/login`: the whole tier was reachable only
- * from `recipe.spec.ts`. This function is what a `server.ts` calls, and it owns
- * the four things a library must not decide:
- *
- *   1. **Which file the identity lives in.** `<root>/registry.db` — the app's
- *      OWN registry, never the machine-wide `cc-registry.db`. The station is the
- *      sole DDL owner of that shared file (V6 `client-ddl-on-shared-db`), and
- *      two generated apps sharing one account table is a tenancy decision no
- *      generator gets to make silently. Same schema, same station-authored
- *      migration chain, per-app file.
- *   2. **Row integrity.** The identity and secrets tables are HMAC-signed with
- *      the SAME persisted machine key the telemetry tier signs with — one key
- *      file per data root, minted `0600` on first boot.
- *   3. **The envelope salt**, persisted beside the registry. Minting it per boot
- *      would change every new envelope's `kdf` block and orphan yesterday's
- *      secrets behind a reseal.
- *   4. **The KDF.** cwip ships no argon2id; the binding is registered here, once,
- *      and `assertArgon2idReady()` proves it took before a single route mounts.
- *
- * Async solely because the argon2id binding is an optional native module loaded
- * with a dynamic `import()` — the generated `server.ts` is already a top-level
- * `await` module.
- */
-export async function createLocalGuardServices(options: CreateLocalGuardServicesOptions): Promise<LocalGuardServices> {
-  const root = path.resolve(options.root);
-  mkdirSync(root, { recursive: true });
-
-  // FIRST, before a handle is opened: a missing binding must fail the boot, not
-  // leave a half-built tier behind on the way out.
-  await (options.registerKdf ?? registerNodeRsArgon2id)();
-  assertArgon2idReady();
-
-  const registryFile = path.join(root, 'registry.db');
-  const registryDb = (options.openDatabase ?? ((file: string) => new Database(file, { create: true })))(registryFile);
-  assertCcPragmas(registryDb);
-  runNamespacedMigrations(registryDb, CC_REGISTRY_MIGRATIONS, { namespace: CC_REGISTRY_NAMESPACE });
-
-  // A SECOND SecureKey over the same key file the telemetry writer signs with —
-  // deliberately not a shared instance: each owner zeroizes its own copy on
-  // close, and sharing one would make either close() a use-after-destroy for the
-  // other.
-  const integrityKey = SecureKey.adopt(loadOrMintKeyFile(path.join(root, 'row-integrity.key')), 'machine-integrity');
-  const signer = createRowSigner({ integrityKey });
-
-  // The KDF salt is NOT secret (envelopes carry it in the clear), but it must be
-  // STABLE — `loadOrMintKeyFile` is the persistence path already proven `0600`.
-  const manager = createSecretEnvelopeManager({
-    salt: loadOrMintKeyFile(path.join(root, 'envelope.salt'), CC_SALT_BYTES),
-  });
-
-  return {
-    registryFile,
-    registryDb,
-    deps: {
-      manager,
-      secrets: createRegistrySecretsStore(registryDb, { manager, signer }),
-      identity: createRegistryIdentityStore(registryDb, { signer }),
-    },
-    close() {
-      manager.lock();
-      getTxnLifetimeGuard(registryDb)?.dispose();
-      registryDb.close();
-      integrityKey.destroy();
-    },
-  };
-}
-
-/* -------------------------------------------------------------------- dev */
-
-export interface CreateLocalDevServicesOptions {
-  /** The app data root (see {@link resolveAppDataRoot}). Created if absent. */
-  readonly root: string;
-  /**
-   * Reuse an already-open registry handle — pass
-   * {@link LocalGuardServices.registryDb} whenever the guard engine is also
-   * active. Two handles on one SQLite file is two write locks contending and a
-   * second txn-lifetime guard fighting the first.
-   */
-  readonly registryDb?: Database;
-  /** Open the registry file. Injected by tests (`:memory:`). */
-  readonly openDatabase?: (file: string) => Database;
-  /**
-   * Where the `screenshots` surface (03 §1e) reads captures from. Defaults to
-   * `<root>/screenshots` — the app's OWN data root, on the same reasoning as the
-   * registry file above: a generated app reaching into a machine-wide capture
-   * directory is not a decision a generator gets to make.
-   */
-  readonly screenshotRoot?: string;
-}
-
-export interface LocalDevServices {
-  readonly registryFile: string;
-  readonly registryDb: Database;
-  /** Where {@link LocalDevServices.deps}'s screenshot source reads from. */
-  readonly screenshotRoot: string;
-  /** Exactly what `bootEngineApp({ devDeps })` takes. */
-  readonly deps: DevServiceDeps;
-  close(): void;
-}
-
-/** Extensions the screenshot source publishes, and the type each is served as. */
-const SCREENSHOT_TYPES: Readonly<Record<string, string>> = Object.freeze({
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.gif': 'image/gif',
-});
-
-/**
- * The local `ScreenshotSource` — a flat directory of captures.
- *
- * Three properties make it safe to hand a URL segment to, and all three come
- * from the same decision: the LISTING is the authority, not the caller's string.
- *
- *   * Only files whose extension is in {@link SCREENSHOT_TYPES} are published,
- *     so the source can never serve an `.env` that happens to be in the folder.
- *   * The list is FLAT — sub-directories are not descended and a name containing
- *     a separator is never produced, so no listed name can traverse.
- *   * `read` re-checks the name against the same rules before it opens anything;
- *     `DevService.readScreenshot` also matches the name against the live listing
- *     first. Two independent checks, because this is the one dev route that
- *     turns a caller-supplied segment into a file handle.
- *
- * A missing directory is an EMPTY listing, not a boot failure: an operator who
- * turned the feature on before their first capture should see "no screenshots
- * yet", and the directory appears the moment something writes one.
- */
-export function createLocalScreenshotSource(root: string): ScreenshotSource {
-  const resolvedRoot = path.resolve(root);
-
-  const publishable = (name: string): string | null => {
-    if (name !== path.basename(name)) return null; // never a path, only a name
-    if (name.startsWith('.')) return null;
-    return SCREENSHOT_TYPES[path.extname(name).toLowerCase()] ?? null;
-  };
-
-  return {
-    list(): readonly ScreenshotView[] {
-      let names: string[];
-      try {
-        names = readdirSync(resolvedRoot);
-      } catch {
-        return [];
-      }
-      const entries: ScreenshotView[] = [];
-      for (const name of names) {
-        const contentType = publishable(name);
-        if (!contentType) continue;
-        let stats: Stats;
-        try {
-          stats = statSync(path.join(resolvedRoot, name));
-        } catch {
-          continue; // vanished between readdir and stat
-        }
-        if (!stats.isFile()) continue;
-        entries.push({ name, bytes: stats.size, capturedAt: stats.mtime.toISOString(), contentType });
-      }
-      // Newest first — a capture gallery is read from the most recent shot.
-      return entries.sort((a, b) => b.capturedAt.localeCompare(a.capturedAt));
-    },
-
-    read(name: string): { bytes: Uint8Array; contentType: string } | null {
-      const contentType = publishable(name);
-      if (!contentType) return null;
-      try {
-        return { bytes: new Uint8Array(readFileSync(path.join(resolvedRoot, name))), contentType };
-      } catch {
-        return null;
-      }
-    },
-  };
-}
-
-/**
- * The DevStudio half of the local host (03 §2c) — the seam whose absence made
- * the `dev` engine **unbootable in a generated app**.
- *
- * `DevService`, `dev.mixin.ts` and the five DevStudio views all landed arcs ago,
- * and `buildEngineServices` has always thrown `DEV_DEPS_MISSING` when the engine
- * is active with no `devDeps` — but no shipping host ever constructed them, and
- * the generated `server.ts` emitted nothing for dev. Every app whose config
- * activated the engine died at boot with a 500 before serving a byte. The
- * migrator found it on the first real app, because `plugin-app-info` maps to
- * `dev.appRegistry` and the then-live local-gallery app mounted it.
- *
- * What it decides — the two things a library must not:
- *
- *   1. **Which registry the app board reads.** `<root>/registry.db`, the app's
- *      OWN file, for exactly the reason the guard tier uses it: the station is
- *      the sole DDL owner of the machine-wide `cc-registry.db` (V6
- *      `client-ddl-on-shared-db`), and a generated app silently attaching to the
- *      machine fleet database is a decision no generator gets to make. A host
- *      that genuinely wants the machine board passes that handle in.
- *   2. **That it is ONE handle.** With the guard engine active the caller passes
- *      `guard.registryDb` and this opens nothing — same file, same chain, one
- *      lock.
- *
- * `snapshotRoot`/`snapshot` are deliberately NOT set here: the recipe defaults
- * them from the domain handles it opens, which is the only place those handles
- * exist (see {@link DevServiceDeps.snapshot}).
- */
-export function createLocalDevServices(options: CreateLocalDevServicesOptions): LocalDevServices {
-  const root = path.resolve(options.root);
-  mkdirSync(root, { recursive: true });
-
-  const registryFile = path.join(root, 'registry.db');
-  const shared = options.registryDb !== undefined;
-  const registryDb =
-    options.registryDb ?? (options.openDatabase ?? ((file: string) => new Database(file, { create: true })))(registryFile);
-  if (!shared) {
-    assertCcPragmas(registryDb);
-    runNamespacedMigrations(registryDb, CC_REGISTRY_MIGRATIONS, { namespace: CC_REGISTRY_NAMESPACE });
-  }
-
-  const screenshotRoot = path.resolve(options.screenshotRoot ?? path.join(root, 'screenshots'));
-
-  // The `ports` row signer (05 §A5). A THIRD SecureKey over the same persisted
-  // machine key file the guard tier and the telemetry writer sign with — one key
-  // per data root, and deliberately not a shared instance, because each owner
-  // zeroizes its own copy on `close()` and sharing one would make either close a
-  // use-after-destroy for the other.
-  //
-  // Not optional and not defaulted-to-nothing: `DevService` reads `ports` (a
-  // signed table) to render the fleet board, and a read that skips
-  // `assertVerified` serves a row edited outside the app as though the registry
-  // had said it — the exact thing `SECURITY_INTEGRITY_VIOLATION` exists to catch.
-  const integrityKey = SecureKey.adopt(loadOrMintKeyFile(path.join(root, 'row-integrity.key')), 'machine-integrity');
-  const portSigner = createRowSigner({ integrityKey });
-
-  return {
-    registryFile,
-    registryDb,
-    screenshotRoot,
-    deps: { registry: registryDb, portSigner, screenshots: createLocalScreenshotSource(screenshotRoot) },
-    close() {
-      // The key is ours either way — a shared HANDLE is the guard tier's, but
-      // this SecureKey is a copy this function adopted.
-      integrityKey.destroy();
-      // A SHARED handle belongs to whoever opened it — closing it here would
-      // pull the registry out from under the guard tier mid-request.
-      if (shared) return;
-      getTxnLifetimeGuard(registryDb)?.dispose();
-      registryDb.close();
-    },
-  };
-}