cursedbelt 2.7.0 → 3.0.0

package/src/server/services/devService.ts

@@ -1,453 +0,0 @@
-/**
- * `DevService` (02 §1.3) — the registry-backed app board, deploys, config and
- * database export.
- *
- * Two of its methods are `infra:write`-gated at the route (J2-2), and this file
- * assumes that gate rather than re-implementing it: `writeConfig` and
- * `exportDatabase` are only reachable behind `privileged`. What it does NOT
- * assume is the *path* boundary — a config editor that trusts its caller to
- * stay inside the root is one `../../.ssh/id_rsa` away from being a file-read
- * primitive, so `readConfig`/`writeConfig` resolve inside a declared root and
- * refuse anything that escapes it.
- *
- * `exportDatabase` goes through `VACUUM INTO` (01 §6.1). Copying a live `.db`
- * with a `-wal` beside it produces a snapshot that is silently missing the most
- * recent committed transactions — a backup that restores to the wrong state is
- * worse than no backup, which is why a live-file copy is a V6 ERROR.
- *
- * **03 §1e (second half) — the five unbacked DEV views got their far side here.**
- * `app-detail`, `docs`, `pipelines`, `screenshots` and `orchestration` rendered a
- * placeholder for the whole arc, and the gap was on THIS side: `dev.mixin.ts`
- * mounted no route behind any of them. Each is now a real read of a real source —
- * the registry row and its ports/aliases; the docs an app's own manifest
- * declares; the exec driver's whitelist and run log; a host-wired screenshot
- * source; the durable job-result store — and three of them take an injected seam
- * (`exec`/`screenshots`/`jobResults`) because a library cannot decide which
- * directory holds an operator's captures or which queue their jobs ran on. A
- * feature switched on with its seam unwired is a typed 501 naming the wiring, not
- * an empty list that looks like "nothing has happened yet".
- */
-import { type AppRow, listVerifiedAppPorts } from 'cwip/cc-registry';
-import type { RowSigner } from 'cwip/guard';
-import type { SqliteWritableDatabase } from 'cwip/sqlite';
-import { readFile } from 'node:fs/promises';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import type { ExecutionDriver, JobBroker, JobResultStore } from '../drivers';
-import { AppError } from '../errors';
-import type {
-  AppDetailView,
-  AppSummary,
-  CallScope,
-  DevService,
-  DocContentView,
-  DocEntryView,
-  JobRunView,
-  PipelineRunView,
-  PipelineView,
-  ScreenshotView,
-} from '../mixins/services';
-
-/** Job kind `deploy` enqueues — deploys are long-running, so they never hold a request. */
-export const DEV_DEPLOY_JOB = 'deploy';
-
-/** Snapshot one domain database. `createSqliteBackupService` is the usual impl. */
-export type SnapshotFn = (domain: string, destination: string) => Promise<void> | void;
-
-/** Read/write an app's env file. Injected so the local and SaaS shapes can differ. */
-export interface ConfigStore {
-  read(appId: string): Promise<Record<string, string>> | Record<string, string>;
-  write(appId: string, patch: Record<string, string>): Promise<void> | void;
-}
-
-/** Directory sizes for the `diskUsage` feature. */
-export type DiskUsageFn = () => Promise<{ path: string; bytes: number }[]> | { path: string; bytes: number }[];
-
-/**
- * Where captured screenshots come from (03 §1e, the `screenshots` surface).
- *
- * A seam rather than a built-in directory walk for the same reason the config
- * editor takes a {@link ConfigStore}: WHICH directory (or bucket) holds an
- * operator's captures is a host decision, and a library that picked one would be
- * wrong for every host that already has a convention. `createLocalDevServices`
- * wires the local one.
- */
-export interface ScreenshotSource {
-  list(): Promise<readonly ScreenshotView[]> | readonly ScreenshotView[];
-  /** The bytes of one listed entry, or `null` if it is gone. */
-  read(name: string): Promise<{ bytes: Uint8Array; contentType: string } | null> | { bytes: Uint8Array; contentType: string } | null;
-}
-
-/** Read a doc file's text. Injected so a test needs no tree on disk. */
-export type ReadTextFileFn = (absolutePath: string) => Promise<string>;
-
-export interface DevServiceOptions {
-  /** The machine registry handle (`cc-registry.db`) — apps, ports, aliases. */
-  registry: SqliteWritableDatabase;
-  /**
-   * The row signer the registry's `ports` rows were written with (05 §A5).
-   *
-   * REQUIRED, and deliberately not optional. `ports` is an HMAC-signed table;
-   * this service used to read it with a raw `SELECT`, so a row edited outside
-   * the app was rendered on the fleet board as though the registry had said it —
-   * `SECURITY_INTEGRITY_VIOLATION` exists precisely to make that impossible, and
-   * a bypassing read is the one thing that switches it off. An optional signer
-   * would mean "verified unless someone forgot", which is the same as unverified.
-   *
-   * `apps` and `aliases` are UNSIGNED by design and are read as they always were.
-   */
-  portSigner: RowSigner;
-  broker: JobBroker;
-  /** Where `exportDatabase` writes snapshots. Every snapshot path stays inside it. */
-  snapshotRoot: string;
-  snapshot: SnapshotFn;
-  config?: ConfigStore;
-  diskUsage?: DiskUsageFn;
-  /** Probe whether a recorded `boot_pid` is alive. Default: `process.kill(pid, 0)`. */
-  isProcessAlive?: (pid: number) => boolean;
-  /**
-   * The driver the `pipelines` surface reads. The SAME instance the dev mixin
-   * holds on `ctx.exec` — a second driver would list a whitelist nothing runs
-   * from and a run log that never fills.
-   */
-  exec?: ExecutionDriver;
-  /** Durable job outcomes — the `orchestration` surface's read side. */
-  jobResults?: JobResultStore;
-  screenshots?: ScreenshotSource;
-  /** Default `node:fs`; injected by tests and by a host with a virtual doc tree. */
-  readTextFile?: ReadTextFileFn;
-}
-
-const defaultIsAlive = (pid: number): boolean => {
-  try {
-    // Signal 0 performs the permission/existence check without delivering a signal.
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/** Domain names that may be snapshotted — the same closed set the storage tier owns. */
-const EXPORTABLE_DOMAINS = new Set(['knowledge', 'media', 'search', 'system', 'staging']);
-
-/**
- * The slice of an app's recorded `manifest` blob this service reads.
- *
- * The column is opaque JSON written by whoever registered the app (the station,
- * `gen-app`'s `cursed` block, a hand-written row), so every field is read
- * defensively: a manifest that is `'{}'`, malformed, or shaped differently
- * yields empty lists rather than throwing. An app board that 500s because ONE
- * row has a manifest written by an older tool is a worse failure than an app
- * whose detail page shows no docs.
- */
-interface AppManifestFacts {
-  commands: Record<string, string>;
-  docs: string[];
-}
-
-const stringRecord = (value: unknown): Record<string, string> => {
-  if (typeof value !== 'object' || value === null) return {};
-  return Object.fromEntries(
-    Object.entries(value as Record<string, unknown>).filter(
-      (entry): entry is [string, string] => typeof entry[1] === 'string',
-    ),
-  );
-};
-
-const readManifestFacts = (raw: string): AppManifestFacts => {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return { commands: {}, docs: [] };
-  }
-  if (typeof parsed !== 'object' || parsed === null) return { commands: {}, docs: [] };
-  // Accept both the whole `package.json` `cursed` block (`{schemaVersion, app}`)
-  // and a bare `app` block — a registrar may record either, and guessing wrong
-  // silently empties the docs surface.
-  const outer = parsed as { app?: unknown };
-  const app = (typeof outer.app === 'object' && outer.app !== null ? outer.app : parsed) as {
-    commands?: unknown;
-    docs?: unknown;
-  };
-  return {
-    commands: stringRecord(app.commands),
-    docs: Array.isArray(app.docs) ? app.docs.filter((entry): entry is string => typeof entry === 'string') : [],
-  };
-};
-
-export function createDevService(options: DevServiceOptions): DevService {
-  const isAlive = options.isProcessAlive ?? defaultIsAlive;
-  const readTextFile = options.readTextFile ?? ((absolutePath: string) => readFile(absolutePath, 'utf8'));
-
-  const readApps = (): AppRow[] =>
-    options.registry.query('SELECT * FROM apps ORDER BY app_id').all() as AppRow[];
-
-  const readApp = (appId: string): AppRow => {
-    const row = options.registry.query('SELECT * FROM apps WHERE app_id = ?').get(appId) as AppRow | null;
-    if (!row)
-      throw new AppError(`No registered app '${appId}'.`, {
-        code: 'APP_NOT_REGISTERED',
-        status: 404,
-        context: { appId },
-      });
-    return row;
-  };
-
-  /**
-   * Every port an app owns, signature-verified (05 §A5).
-   *
-   * ONE read for both the summary and the detail view: `AppSummary.port` is just
-   * `ports[0]`. Two reads meant two SQL statements to keep honest, and the
-   * summary's was the raw one that skipped verification — a board showing a
-   * tampered port while the detail page it links to would have refused it.
-   */
-  const portsOf = (appId: string): number[] => listVerifiedAppPorts(options.registry, appId, options.portSigner);
-
-  const toSummary = (row: AppRow): AppSummary => ({
-    appId: row.app_id,
-    title: row.title,
-    // "Running" is a live PID probe, not a stale column. A `boot_pid` left
-    // behind by a crashed process would otherwise report a dead app as healthy —
-    // and the promotion tool reads the same signal before touching a DB file
-    // (01 §5.4).
-    running: row.boot_pid !== null && isAlive(row.boot_pid),
-    // The LOWEST claimed port — an app may own several; the board shows the one
-    // you would open.
-    port: portsOf(row.app_id)[0],
-  });
-
-  const requireConfigStore = (): ConfigStore => {
-    if (options.config) return options.config;
-    throw new AppError('This host enabled the config editor but wired no ConfigStore.', {
-      code: 'CONFIG_STORE_MISSING',
-      status: 501,
-    });
-  };
-
-  /**
-   * The unwired-seam refusal, shared by the three surfaces whose far side is a
-   * host decision. 501 and not 500: the route exists and the feature is on; what
-   * is missing is wiring only this host can supply, and the message names it.
-   */
-  const unwired = (code: string, message: string): AppError =>
-    new AppError(message, { code, status: 501 });
-
-  const requireExec = (): ExecutionDriver => {
-    if (options.exec) return options.exec;
-    throw unwired(
-      'EXEC_DRIVER_MISSING',
-      'This app enabled the pipelines feature but wired no ExecutionDriver.',
-    );
-  };
-
-  const requireScreenshots = (): ScreenshotSource => {
-    if (options.screenshots) return options.screenshots;
-    throw unwired(
-      'SCREENSHOT_SOURCE_MISSING',
-      'This app enabled the screenshots feature but wired no ScreenshotSource.',
-    );
-  };
-
-  const requireJobResults = (): JobResultStore => {
-    if (options.jobResults) return options.jobResults;
-    throw unwired(
-      'JOB_RESULTS_MISSING',
-      'This app enabled the orchestration feature but wired no JobResultStore.',
-    );
-  };
-
-  return {
-    async listApps(_scope: CallScope): Promise<readonly AppSummary[]> {
-      return readApps().map(toSummary);
-    },
-
-    async appDetail(_scope, appId): Promise<AppDetailView> {
-      const row = readApp(appId);
-      const facts = readManifestFacts(row.manifest);
-      const aliases = options.registry
-        .query('SELECT name, command FROM aliases WHERE app_id = ? ORDER BY name')
-        .all(appId) as { name: string; command: string }[];
-      const running = row.boot_pid !== null && isAlive(row.boot_pid);
-      const ports = portsOf(appId);
-      return {
-        ...toSummary(row),
-        kind: row.kind,
-        localPath: row.local_path,
-        // Only while it is actually up: a pid from a crashed boot is not a
-        // running process, and printing it invites `kill`ing a recycled one.
-        ...(running && row.boot_pid !== null ? { pid: row.boot_pid } : {}),
-        ...(row.last_booted === null ? {} : { lastBooted: row.last_booted }),
-        ports,
-        aliases,
-        commands: facts.commands,
-        docs: facts.docs,
-      };
-    },
-
-    async fleet(_scope: CallScope): Promise<readonly AppSummary[]> {
-      // The fleet view is the registry board filtered to what is actually up.
-      return readApps().map(toSummary).filter((app) => app.running);
-    },
-
-    async listDocs(_scope): Promise<readonly DocEntryView[]> {
-      return readApps().flatMap((row) =>
-        readManifestFacts(row.manifest).docs.map((path_) => ({
-          appId: row.app_id,
-          appTitle: row.title,
-          path: path_,
-        })),
-      );
-    },
-
-    async readDoc(_scope, appId, docPath): Promise<DocContentView> {
-      const row = readApp(appId);
-      const { docs } = readManifestFacts(row.manifest);
-      // The DECLARED set is the allowlist, and it is the whole containment story:
-      // an app's manifest names which files are documentation, so a path that is
-      // not in it is refused before any path arithmetic happens. Resolving the
-      // request and then checking whether it escaped the root would make this a
-      // general file reader that merely tries to stay in bounds — one `..`
-      // normalization bug away from serving `.env`.
-      if (!docs.includes(docPath))
-        throw new AppError(`'${docPath}' is not a document '${appId}' declares.`, {
-          code: 'DOC_NOT_DECLARED',
-          status: 404,
-          category: 'security',
-          context: { appId, docPath },
-        });
-
-      const root = resolve(row.local_path);
-      const file = resolve(join(root, docPath));
-      // Belt and braces on the join, exactly as `exportDatabase` does it: the
-      // allowlist above is the authority, but a manifest is written by a tool and
-      // a declared `../../secrets` must not become a read.
-      const relativePath = relative(root, file);
-      if (relativePath.startsWith('..') || isAbsolute(relativePath))
-        throw new AppError('Refusing to read a document outside the app directory.', {
-          code: 'DOC_PATH_ESCAPE',
-          status: 400,
-          category: 'security',
-          context: { appId, docPath },
-        });
-
-      let text: string;
-      try {
-        text = await readTextFile(file);
-      } catch {
-        // A declared doc whose file is gone is a 404 about THAT doc, never the
-        // host's absolute path in an error message.
-        throw new AppError(`Document '${docPath}' of '${appId}' could not be read.`, {
-          code: 'DOC_UNREADABLE',
-          status: 404,
-          context: { appId, docPath },
-        });
-      }
-      return { appId, appTitle: row.title, path: docPath, text };
-    },
-
-    async pipelines(_scope): Promise<readonly PipelineView[]> {
-      return requireExec().commands();
-    },
-
-    async pipelineRuns(_scope): Promise<readonly PipelineRunView[]> {
-      return requireExec().runs();
-    },
-
-    async screenshots(_scope): Promise<readonly ScreenshotView[]> {
-      return await requireScreenshots().list();
-    },
-
-    async readScreenshot(_scope, name): Promise<{ bytes: Uint8Array; contentType: string }> {
-      const source = requireScreenshots();
-      // Resolve against what the source LISTS rather than trusting the name: the
-      // segment arrives from a URL, and "the entries this source published" is a
-      // closed set no traversal can widen.
-      const entries = await source.list();
-      if (!entries.some((entry) => entry.name === name))
-        throw new AppError(`No screenshot '${name}'.`, {
-          code: 'SCREENSHOT_NOT_FOUND',
-          status: 404,
-          context: { name },
-        });
-      const found = await source.read(name);
-      if (!found)
-        throw new AppError(`Screenshot '${name}' is listed but its bytes are gone.`, {
-          code: 'SCREENSHOT_NOT_FOUND',
-          status: 404,
-          context: { name },
-        });
-      return found;
-    },
-
-    async jobs(scope): Promise<readonly JobRunView[]> {
-      // Scoped to the caller's tenant by the STORE, not filtered afterwards —
-      // a job outcome carries a payload summary, and "read everything then drop
-      // the rows that are not yours" is the shape that leaks when someone later
-      // adds a count beside the list.
-      const recorded = await requireJobResults().list({ tenantId: scope.claims.tenantId });
-      return recorded.map((result) => ({
-          jobId: result.jobId,
-          ok: result.ok,
-          ...(result.error === undefined ? {} : { error: result.error }),
-          at: result.at ?? '',
-          ...(result.instanceId === undefined ? {} : { instanceId: result.instanceId }),
-        }));
-    },
-
-    async deploy(scope, appId): Promise<{ jobId: string }> {
-      readApp(appId); // typed 404 for an unregistered id, one definition
-      const jobId = await options.broker.enqueue({
-        kind: DEV_DEPLOY_JOB,
-        tenantId: scope.claims.tenantId,
-        instanceId: scope.instanceId,
-        payload: { appId, requestedBy: scope.claims.userId },
-      });
-      return { jobId };
-    },
-
-    async readConfig(_scope, appId): Promise<Record<string, string>> {
-      return await requireConfigStore().read(appId);
-    },
-
-    async writeConfig(_scope, appId, patch): Promise<void> {
-      await requireConfigStore().write(appId, patch);
-    },
-
-    async exportDatabase(_scope, domain): Promise<{ snapshotPath: string }> {
-      if (!EXPORTABLE_DOMAINS.has(domain))
-        throw new AppError(`'${domain}' is not an exportable domain.`, {
-          code: 'UNKNOWN_DOMAIN',
-          status: 400,
-          context: { domain },
-        });
-
-      const root = resolve(options.snapshotRoot);
-      // Timestamped so two exports never race for one filename, and so an
-      // operator can tell snapshots apart without opening them.
-      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-      const snapshotPath = join(root, `${domain}-${stamp}.snapshot.db`);
-
-      // Belt and braces on the join: `domain` is already allowlisted, but a
-      // path that escapes its root is the failure this check exists to make
-      // impossible rather than unlikely.
-      const relativePath = relative(root, snapshotPath);
-      if (relativePath.startsWith('..') || isAbsolute(relativePath))
-        throw new AppError('Refusing to write a snapshot outside the snapshot root.', {
-          code: 'SNAPSHOT_PATH_ESCAPE',
-          status: 400,
-          category: 'security',
-          context: { domain },
-        });
-
-      // `VACUUM INTO`, never a copy of the live file (01 §6.1).
-      await options.snapshot(domain, snapshotPath);
-      return { snapshotPath };
-    },
-
-    async diskUsage(_scope): Promise<{ path: string; bytes: number }[]> {
-      if (!options.diskUsage) return [];
-      return await options.diskUsage();
-    },
-  };
-}

package/src/server/services/guardService.spec.ts

@@ -1,98 +0,0 @@
-/**
- * `GuardService` — unlock mints, lock revokes the PRESENTED session (02 §1c, L13).
- *
- * The L13 defect: `lock` ignored the caller's claims and revoked a single shared
- * `current` closure var — whichever unlock wrote it last. Two devices unlocked,
- * device A locks, and device B's session was the one revoked. This proves the fix:
- * `lock(scope)` revokes exactly `scope.claims.jti`, so device B stays live.
- */
-import { Database } from 'bun:sqlite';
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { assertCcPragmas, getTxnLifetimeGuard, runNamespacedMigrations } from 'cwip/sqlite';
-import {
-  type Argon2idDeriver,
-  createRowSigner,
-  createSecretEnvelopeManager,
-  mintEnvelopeSalt,
-  mintMachineIntegrityKey,
-} from 'cwip/guard';
-import { CC_REGISTRY_MIGRATIONS, createRegistrySecretsStore } from 'cwip/cc-registry';
-import { createSessionSigner, type SessionSigner } from '../guard/sessionSigner';
-import { createGuardService, type UnlockedIdentity } from './guardService';
-import type { CCUserClaims } from '../../core/session/claims';
-import type { GuardService } from '../mixins/services';
-
-const stubArgon2id: Argon2idDeriver = ({ salt, keyLength }) => {
-  const out = new Uint8Array(keyLength);
-  for (let i = 0; i < keyLength; i += 1) out[i] = (salt[i % salt.length] ?? 0) ^ (i & 0xff);
-  return out;
-};
-
-const OWNER: UnlockedIdentity = { tenantId: 't_local', userId: 'u_local', role: 'OWNER', permissions: ['infra:write'] };
-
-let registry: Database;
-let signer: SessionSigner;
-let service: GuardService;
-let lockedClaims: string[];
-
-const unlock = async (): Promise<CCUserClaims> => {
-  // The wire format is "the body IS the passphrase" (custody law).
-  const result = await service.unlock(
-    new Request('http://localhost/api/guard/unlock', { method: 'POST', body: new Uint8Array([9, 9, 9]) }),
-  );
-  return result.claims;
-};
-
-beforeEach(() => {
-  registry = new Database(':memory:');
-  assertCcPragmas(registry);
-  runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
-  const rowSigner = createRowSigner({ integrityKey: mintMachineIntegrityKey() });
-  const manager = createSecretEnvelopeManager({ salt: mintEnvelopeSalt(), deriver: stubArgon2id });
-  const secrets = createRegistrySecretsStore(registry, { manager, signer: rowSigner });
-  signer = createSessionSigner({ ttlSeconds: 300 });
-  lockedClaims = [];
-  service = createGuardService({
-    manager,
-    secrets,
-    signer,
-    appId: 'guard-demo',
-    resolveIdentity: async () => OWNER,
-    onLocked: (claims) => lockedClaims.push(claims?.jti ?? 'null'),
-  });
-});
-
-afterEach(() => {
-  getTxnLifetimeGuard(registry)?.dispose();
-  registry.close();
-});
-
-describe('GuardService — per-session lock (L13)', () => {
-  it('mints a session on unlock whose token verifies', async () => {
-    const claims = await unlock();
-    expect(claims.jti).toMatch(/^jti_/);
-    expect(signer.isRevoked(claims.jti)).toBe(false);
-  });
-
-  it('lock(scope) revokes ONLY the presented session — the other device stays live', async () => {
-    const a = await unlock();
-    const b = await unlock();
-    expect(a.jti).not.toBe(b.jti);
-
-    // Device A locks, presenting A's claims. The old bug revoked "current"
-    // (whichever unlock wrote last — here device B); the fix revokes exactly A.
-    await service.lock({ claims: a });
-
-    expect(signer.isRevoked(a.jti)).toBe(true); // A is closed
-    expect(signer.isRevoked(b.jti)).toBe(false); // B survives — the L13 fix
-    expect(lockedClaims).toEqual([a.jti]);
-  });
-
-  it('device B can independently lock its own session afterwards', async () => {
-    const a = await unlock();
-    const b = await unlock();
-    await service.lock({ claims: a });
-    await service.lock({ claims: b });
-    expect(signer.isRevoked(b.jti)).toBe(true);
-  });
-});