@legionworks/facet 1.9.0

package/src/service/server.ts

@@ -0,0 +1,356 @@
+/**
+ * Loopback service server.
+ *
+ * Bind order (security-critical — D3 review):
+ *   1. Acquire the process lock FIRST with a minimal metadata record
+ *      (pid + startTime; port=0). A second cold start cannot race the
+ *      install-token create, DB migrate, or port bind while we hold
+ *      the lock.
+ *   2. Open the database + run migrations (idempotent under lock).
+ *   3. Create the install token atomically (temp-file + rename under
+ *      lock; a second starter that wins the lock reads what we wrote).
+ *   4. Read the operator promote token (read-only, may be absent).
+ *   5. Bind Bun.serve on 127.0.0.1:<os-assigned port>.
+ *   6. Update the lock metadata with the assigned port + complete
+ *      record — STILL holding the lock so a parallel starter cannot
+ *      observe a port-less lock and assume the service is unready.
+ *
+ * Idle-driven stop: release the lock, close the server, WAL checkpoint.
+ */
+
+import { dirname } from "node:path";
+
+import { FacetError } from "../shared/errors/facet-error";
+import { createLogger, type FacetLogger } from "../shared/logging/logger";
+import { computeFacetPaths } from "../shared/config/paths";
+
+import { openDatabase } from "./store/database";
+import { runMigrations } from "./store/migrations";
+import { ArtifactRepository } from "./store/repository";
+import { buildRouter } from "./router";
+import { createInstallTokenStore, createPromoteTokenStore } from "./security/token-store";
+import { createLeaseManager, type GalleryLeaseManager } from "./security/leases";
+import {
+  assertHeartbeatBeforeLeaseTtl,
+  createRevisionBroadcaster,
+  STREAM_HEARTBEAT_INTERVAL_MS,
+} from "./stream";
+import { defaultInsecureReason } from "./verdict-enrichment";
+import {
+  InsecureLevelSchema,
+  type InsecureLevel,
+  type Tier0Runner,
+  type Tier1Runner,
+} from "../shared/contracts/validation";
+import {
+  acquireLock,
+  releaseLock,
+  writeLockMetadata,
+  readPidStartTimeTicks,
+  type LockMetadata,
+} from "./lifecycle/process-lock";
+import { runOrphanCleanup } from "./lifecycle/orphan-cleanup";
+import { createIdleController, type IdleController } from "./lifecycle/idle-controller";
+import { ensureEvidenceRoot } from "./store/evidence-retention";
+import { ensureOwnerOnlyDirectory } from "../shared/util/dir-permissions";
+
+const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+const LEASE_TTL_MS = 5 * 60_000;
+export const BUN_SOCKET_IDLE_TIMEOUT_S = 45;
+
+export interface StartServiceOptions {
+  readonly insecureLevel?: InsecureLevel;
+  readonly insecureReason?: string | null;
+  readonly dbPath?: string;
+  readonly installTokenPath?: string;
+  readonly promoteTokenPath?: string;
+  readonly lockPath?: string;
+  readonly evidencePath?: string;
+  readonly idleTimeoutMs?: number;
+  readonly leaseTtlMs?: number;
+  readonly heartbeatIntervalMs?: number;
+  readonly logger?: FacetLogger;
+  readonly host?: string;
+  readonly onIdle?: () => void;
+  /**
+   * Tier 0 runner. Production callers pass the default from
+   * `src/validation/tier0/runner.ts`; tests inject a stub so they
+   * can exercise the publish path without spawning a worker. The
+   * type lives in `dispatcher.ts` so the server does not need to
+   * know which module implements it.
+   */
+  readonly tier0Runner?: Tier0Runner;
+  /**
+   * Optional Tier 1 verifier. When present, publish records BOTH a
+   * Tier 0 and a Tier 1 render_run; read-back of tier 1 returns the
+   * Tier 1 verdict. When absent, tier 1 is never recorded and
+   * read-back of tier 1 surfaces `revision_not_found`.
+   */
+  readonly tier1Runner?: Tier1Runner;
+}
+
+export interface RunningService {
+  readonly port: number;
+  readonly pid: number;
+  readonly url: string;
+  readonly installToken: string;
+  readonly promoteToken: string | null;
+  stop(): Promise<void>;
+  waitUntilIdle(): Promise<void>;
+}
+
+export async function startFacetService(
+  options: StartServiceOptions = {},
+): Promise<RunningService> {
+  const logger = options.logger ?? createLogger({ component: "service" });
+  const insecureLevel = InsecureLevelSchema.parse(options.insecureLevel ?? 0);
+  const paths = computeFacetPaths();
+  const dbPath = options.dbPath ?? paths.database;
+  const installTokenPath =
+    options.installTokenPath ?? paths.token.replace(/promote\.token$/, "install.token");
+  const promoteTokenPath = options.promoteTokenPath ?? paths.token;
+  const lockPath = options.lockPath ?? paths.lock;
+  const evidenceRoot = options.evidencePath ?? paths.evidence;
+  // When the parent CLI threaded an explicit evidence root, the child's own
+  // FACET_HOME-derived root (`paths.evidence`) is the legacy child-derived
+  // root from pre-threading installs. Retain it as a READ-ONLY fallback so
+  // old evidence stays reachable; new evidence always lands in evidenceRoot.
+  const legacyEvidenceRoot =
+    options.evidencePath !== undefined && options.evidencePath !== paths.evidence
+      ? paths.evidence
+      : undefined;
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const leaseTtlMs = options.leaseTtlMs ?? LEASE_TTL_MS;
+  const heartbeatIntervalMs = options.heartbeatIntervalMs ?? STREAM_HEARTBEAT_INTERVAL_MS;
+  assertHeartbeatBeforeLeaseTtl(heartbeatIntervalMs, leaseTtlMs);
+  const host = options.host ?? "127.0.0.1";
+
+  // Pre-lock: orphan cleanup (read-only inspection of disk state).
+  runOrphanCleanup({ lockPath, databasePath: dbPath });
+
+  // Ensure the evidence root exists with mode 0700 before any
+  // service writes land there. Idempotent and best-effort — the
+  // directory may already exist (e.g. from a prior run) in which case
+  // ensureEvidenceRoot rechmods to enforce the secret-bearing layout.
+  ensureEvidenceRoot(evidenceRoot);
+
+  // 1. Lock FIRST. port=0 because the kernel-assigned port is not yet
+  //    known. A second cold start that races this one will be refused
+  //    by acquireLock (live foreign pid contention) until we either
+  //    succeed (lock released on stop) or fail (typed constraint).
+  const lockStartTime = Date.now();
+  const lockMetadata: LockMetadata = {
+    pid: process.pid,
+    startTime: lockStartTime,
+    startTimeTicks: readPidStartTimeTicks(process.pid),
+    port: 0,
+    contractVersion: "facet.v1",
+  };
+  const lockResult = acquireLock(lockPath, lockMetadata);
+  if (!lockResult.ok) {
+    throw lockResult.error;
+  }
+
+  let boundServer: ReturnType<typeof Bun.serve> | null = null;
+  // Capture the hook before initialization so every later startup failure reaps a lazy worker.
+  let tier0Close: (() => void) | null = options.tier0Runner?.close ?? null;
+  let databaseClose: (() => void) | null = null;
+  let leasesClear: (() => void) | null = null;
+  const cleanup = (): void => {
+    if (boundServer !== null) {
+      try {
+        boundServer.stop(true);
+      } catch {
+        // already stopped
+      }
+      boundServer = null;
+    }
+    if (tier0Close !== null) {
+      try {
+        tier0Close();
+      } catch {
+        // A worker can die before service cleanup reaches it.
+      }
+      tier0Close = null;
+    }
+    if (databaseClose !== null) {
+      try {
+        databaseClose();
+      } catch {
+        // already closed
+      }
+      databaseClose = null;
+    }
+    if (leasesClear !== null) {
+      try {
+        leasesClear();
+      } catch {
+        // already cleared
+      }
+      leasesClear = null;
+    }
+    releaseLock(lockPath);
+  };
+
+  try {
+    // 2. Open the database under lock.
+    ensureOwnerOnlyDirectory(dirname(dbPath));
+    const db = openDatabase({ databasePath: dbPath });
+    databaseClose = () => db.close();
+    runMigrations(db);
+    const repository = new ArtifactRepository(db, {
+      onCommitted: (revision) => {
+        logger.info("revision.committed", {
+          artifactId: revision.artifactId,
+          revisionSha: revision.sha256,
+        });
+      },
+      // Evidence retention runs inside the write path; the root must
+      // match the Tier 1 runner's screenshot/console destination so
+      // the cleanup unlink lands on the same path the runner wrote.
+      evidenceRoot,
+      ...(legacyEvidenceRoot !== undefined ? { legacyEvidenceRoot } : {}),
+    });
+
+    // 3. Install token (atomic create under lock). The token store uses
+    //    write-tmp + rename so a second starter that later wins the lock
+    //    reads the persisted token; we never cache a token that is not
+    //    on disk.
+    const installTokenStore = createInstallTokenStore({ tokenPath: installTokenPath });
+    const installToken = installTokenStore.read();
+
+    // 4. Promote token (read-only; absence is a typed state).
+    const promoteTokenStore = createPromoteTokenStore({ tokenPath: promoteTokenPath });
+    const promoteToken = promoteTokenStore.read();
+
+    // 5. Idle + lease managers.
+    let resolveStop: (() => void) | null = null;
+    const idle: IdleController = createIdleController({
+      idleTimeoutMs,
+      onIdle: () => {
+        logger.info("service.idle", { idleTimeoutMs });
+        options.onIdle?.();
+        resolveStop?.();
+      },
+    });
+    const leases: GalleryLeaseManager = createLeaseManager({
+      leaseTtlMs,
+      onExpire: (entry) => {
+        logger.info("lease.expired", { leaseId: entry.leaseId, artifactId: entry.artifactId });
+        idle.release(`lease:${entry.leaseId}`);
+      },
+    });
+    leasesClear = () => leases.clear();
+
+    // 6. Bind Bun.serve on 127.0.0.1:<os-assigned port>. Host guards
+    //    must reject (not inject) a missing Host header.
+    const hostState: { value: string | null } = { value: null };
+    // The Tier 0 runner is required because the service is byte-dumb
+    // and may not import `src/validation`. The default runner lives
+    // there; callers (CLI, tests) construct it externally and inject.
+    if (options.tier0Runner === undefined) {
+      throw new FacetError(
+        "internal",
+        "Tier 0 runner is not configured; pass startFacetService({ tier0Runner })",
+        { retryable: false },
+      );
+    }
+    const tier0Runner: Tier0Runner = options.tier0Runner;
+    const tier1Runner: Tier1Runner | undefined = options.tier1Runner;
+    // Write-path → SSE seam: the dispatcher emits the canonical
+    // revision:committed event after commit + verdict runs; the
+    // broadcaster fans it out to the live gallery streams.
+    const broadcaster = createRevisionBroadcaster();
+    const router = buildRouter({
+      insecureLevel,
+      insecureReason: options.insecureReason ?? null,
+      ...(tier1Runner !== undefined ? { tier1Runner } : {}),
+      repository,
+      installToken,
+      promoteToken,
+      leases,
+      idle,
+      logger: logger.child("router"),
+      expectedHost: () => hostState.value ?? "127.0.0.1:0",
+      ownOrigin: () => `http://${hostState.value ?? "127.0.0.1:0"}`,
+      startTime: lockStartTime,
+      tier0Runner,
+      tier1Runner,
+      broadcaster,
+      heartbeatIntervalMs,
+      onPublished: (event) => broadcaster.emit(event),
+    });
+    let server: ReturnType<typeof Bun.serve>;
+    try {
+      server = Bun.serve({
+        hostname: host,
+        port: 0,
+        idleTimeout: BUN_SOCKET_IDLE_TIMEOUT_S,
+        fetch: (req) => router.fetch(req),
+      });
+    } catch (error) {
+      throw new FacetError("internal", "Failed to bind loopback port", {
+        retryable: false,
+        cause: error,
+      });
+    }
+    const actualPort = server.port ?? 0;
+    if (actualPort === 0) {
+      try {
+        server.stop(true);
+      } catch {
+        // ignore
+      }
+      throw new FacetError("internal", "Failed to bind loopback port", { retryable: false });
+    }
+    const expectedHost = `${host}:${actualPort}`;
+    const ownOrigin = `http://${expectedHost}`;
+    hostState.value = expectedHost;
+    boundServer = server;
+
+    // 7. Update lock metadata with the now-known port while still
+    //    holding the lock. This is the LAST step before serving; a
+    //    parallel starter that observes this lock sees a live service.
+    writeLockMetadata(lockPath, {
+      pid: process.pid,
+      startTime: lockStartTime,
+      port: actualPort,
+      contractVersion: "facet.v1",
+    });
+
+    logger.info("service.ready", {
+      port: actualPort,
+      pid: process.pid,
+      ...(insecureLevel > 0
+        ? {
+            insecureLevel,
+            insecureReason: options.insecureReason ?? defaultInsecureReason(insecureLevel),
+          }
+        : {}),
+    });
+
+    const stopPromise = new Promise<void>((resolve) => {
+      resolveStop = () => {
+        cleanup();
+        logger.info("service.stopped", { port: actualPort });
+        resolve();
+      };
+    });
+
+    return {
+      port: actualPort,
+      pid: process.pid,
+      url: ownOrigin,
+      installToken,
+      promoteToken,
+      stop: async () => {
+        idle.stop();
+        await stopPromise;
+      },
+      waitUntilIdle: () => idle.waitUntilIdle(),
+    };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}

package/src/service/store/database.ts

@@ -0,0 +1,61 @@
+import { chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { Database } from "bun:sqlite";
+
+import { FacetStoreError } from "../../shared/errors/store-error";
+import { ensureOwnerOnlyDirectory } from "../../shared/util/dir-permissions";
+
+// `FacetStoreError` + `asStoreError` + `StoreErrorCode` live in
+// `shared/errors/store-error.ts` so they can extend `FacetError`
+// without an upward import from `shared/` to `service/`. Re-exported
+// here so existing `import { ... } from "./database"` call sites keep
+// working unchanged.
+export {
+  FacetStoreError,
+  asStoreError,
+  type StoreErrorCode,
+} from "../../shared/errors/store-error";
+
+export interface DatabasePaths {
+  readonly databasePath?: string;
+  readonly dbPath?: string;
+  readonly path?: string;
+  readonly busyTimeoutMs?: number;
+}
+
+export type FacetDatabase = Database;
+
+export function openDatabase(paths: DatabasePaths | string): FacetDatabase {
+  const config = typeof paths === "string" ? { databasePath: paths } : paths;
+  const databasePath = config.databasePath ?? config.dbPath ?? config.path;
+  if (!databasePath) throw new FacetStoreError("constraint", "A database path is required");
+  if (databasePath !== ":memory:") ensureOwnerOnlyDirectory(dirname(databasePath));
+  let db: Database;
+  try {
+    db = new Database(databasePath, { create: true, strict: true });
+    db.exec(
+      `PRAGMA journal_mode = WAL; PRAGMA busy_timeout = ${Math.max(1, config.busyTimeoutMs ?? 1_000)}; PRAGMA foreign_keys = ON;`,
+    );
+    db.query("PRAGMA quick_check").get();
+    hardenDatabaseFiles(databasePath);
+  } catch (error) {
+    throw new FacetStoreError(
+      "database_corrupt",
+      error instanceof Error ? error.message : String(error),
+      { cause: error },
+    );
+  }
+  return db;
+}
+
+/** SQLite can recreate WAL sidecars with the process umask; chmod is repeated after writes where paths exist. */
+export function hardenDatabaseFiles(databasePath: string): void {
+  if (databasePath === ":memory:") return;
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      chmodSync(`${databasePath}${suffix}`, 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}

package/src/service/store/evidence-retention.ts

@@ -0,0 +1,234 @@
+/**
+ * Evidence retention policy.
+ *
+ * One canonical knob (`EVIDENCE_LAST_N_PER_ARTIFACT`) governs how many
+ * render_runs + their on-disk evidence files are kept per artifact.
+ * The policy runs INSIDE the write path (`recordRenderRun` invokes
+ * `enforceEvidenceRetention`) so a fresh publish can never leave the
+ * state growing without bound.
+ *
+ * Retained-evidence carve-out: the `retained` column on `render_runs`
+ * marks rows the policy must NOT delete (pinned/template revisions
+ * — the call sites set the flag at the pin/template command site).
+ * Cleanup walks oldest-first, skipping retained rows; the eviction
+ * stops at N non-retained rows.
+ *
+ * On-disk evidence lives under the XDG-state evidence root (mode
+ * 0700). Files referenced by `screenshot_path` and `console_path` are
+ * unlinked alongside their row so a non-retained eviction leaves no
+ * orphan pixels behind. Failures to unlink are best-effort — the row
+ * is the authoritative state; a stale file under the 0700 root is
+ * recoverable by the next orphan sweep.
+ *
+ * The umask-parity mkdir (mkdirSync + stat + chmodSync when the
+ * post-mkdir mode disagrees with 0700) is delegated to the shared
+ * `ensureOwnerOnlyDirectory` helper in `src/shared/util/dir-permissions.ts`
+ * so the service and the validation runner share ONE canonical
+ * implementation. A fix in one place lands in both.
+ */
+
+import { existsSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { Database } from "bun:sqlite";
+
+import { asStoreError } from "../../shared/errors/store-error";
+import { ensureOwnerOnlyDirectory } from "../../shared/util/dir-permissions";
+
+/**
+ * Default retention depth per artifact. Tuned to bound the on-disk
+ * evidence footprint while preserving enough recent runs to debug a
+ * regression: every artifact keeps the last ten runs.
+ */
+export const EVIDENCE_LAST_N_PER_ARTIFACT = 10;
+
+export interface EnforceRetentionOptions {
+  readonly db: Database;
+  readonly artifactId: string;
+  readonly evidenceRoot: string;
+  readonly limit?: number;
+}
+
+export function removeUnreferencedEvidence(
+  db: Database,
+  paths: readonly (string | null | undefined)[],
+): void {
+  const candidates = [...new Set(paths.filter((path): path is string => path != null))];
+  if (candidates.length === 0) return;
+  let hasCompiledPath = false;
+  try {
+    const pragma = db.query("PRAGMA table_info(render_runs)");
+    if (typeof pragma.all === "function") {
+      hasCompiledPath = (pragma.all() as Array<{ name: string }>).some(
+        (column) => column.name === "compiled_path",
+      );
+    }
+  } catch {
+    hasCompiledPath = false;
+  }
+  const release = (): void => {
+    for (const path of candidates) {
+      const referenced = db
+        .query(
+          hasCompiledPath
+            ? "SELECT 1 FROM render_runs WHERE screenshot_path = ? OR console_path = ? OR compiled_path = ? LIMIT 1"
+            : "SELECT 1 FROM render_runs WHERE screenshot_path = ? OR console_path = ? LIMIT 1",
+        )
+        .get(...(hasCompiledPath ? [path, path, path] : [path, path]));
+      if (referenced === null || referenced === undefined) unlinkEvidenceFiles(path, null);
+    }
+  };
+  const transaction = (
+    db as unknown as { transaction?: (fn: () => void) => { immediate: () => void } }
+  ).transaction;
+  if (transaction === undefined) release();
+  else transaction.call(db, release).immediate();
+}
+
+interface RenderRunRow {
+  readonly id: string;
+  readonly screenshot_path: string | null;
+  readonly console_path: string | null;
+  readonly compiled_path: string | null;
+  readonly retained: number;
+}
+
+/**
+ * Enforce last-N retention for one artifact. Deletes the oldest
+ * non-retained render_runs beyond `limit` AND unlinks their on-disk
+ * evidence files. Retained rows are never deleted.
+ *
+ * Idempotent: a fresh database, or an artifact with fewer than `limit`
+ * runs, is a no-op. Safe to call on every write — the query is
+ * bounded and `rmSync` is best-effort.
+ */
+export function enforceEvidenceRetention(options: EnforceRetentionOptions): void {
+  const limit = options.limit ?? EVIDENCE_LAST_N_PER_ARTIFACT;
+  try {
+    ensureEvidenceRoot(options.evidenceRoot);
+    let hasCompiledPath = false;
+    try {
+      const pragma = options.db.query("PRAGMA table_info(render_runs)");
+      if (typeof pragma.all === "function") {
+        hasCompiledPath = (pragma.all() as Array<{ name: string }>).some(
+          (column) => column.name === "compiled_path",
+        );
+      }
+    } catch {
+      hasCompiledPath = false;
+    }
+    const candidates = options.db
+      .query(
+        (hasCompiledPath
+          ? "SELECT id, screenshot_path, console_path, compiled_path, retained "
+          : "SELECT id, screenshot_path, console_path, retained ") +
+          "FROM render_runs " +
+          "WHERE revision_id IN (SELECT id FROM revisions WHERE artifact_id = ?) " +
+          "AND retained = 0 " +
+          "ORDER BY finished_at DESC",
+      )
+      .all(options.artifactId) as RenderRunRow[];
+    const evictable = candidates.slice(limit);
+    for (const row of evictable) {
+      const evict = (): void => {
+        options.db.query("DELETE FROM render_runs WHERE id = ?").run(row.id);
+        removeUnreferencedEvidence(options.db, [
+          row.screenshot_path,
+          row.console_path,
+          row.compiled_path,
+        ]);
+      };
+      const transaction = (
+        options.db as unknown as { transaction?: (fn: () => void) => { immediate: () => void } }
+      ).transaction;
+      if (transaction === undefined) evict();
+      else transaction.call(options.db, evict).immediate();
+    }
+  } catch (error) {
+    throw asStoreError(error);
+  }
+}
+
+export interface EnsureEvidenceDirectoryOptions {
+  readonly evidenceRoot: string;
+  readonly artifactId: string;
+  readonly revisionSha: string;
+  readonly runId: string;
+}
+
+export interface EvidenceSubpaths {
+  readonly directory: string;
+  readonly screenshotPath: string;
+  readonly consolePath: string;
+}
+
+/**
+ * Compute the canonical per-run evidence directory and ensure it
+ * exists with mode 0700. Returns the deterministic paths callers
+ * write to. The directory shape is:
+ *
+ *   <evidenceRoot>/<artifactId>/<revisionSha>/<runId>/
+ *     screenshot.png
+ *     console.txt
+ *
+ * Deterministic-by-content lets a future orphan sweep reconstruct
+ * paths from the DB without a side index.
+ */
+export function ensureRunEvidenceDirectory(
+  options: EnsureEvidenceDirectoryOptions,
+): EvidenceSubpaths {
+  const directory = join(
+    options.evidenceRoot,
+    options.artifactId,
+    options.revisionSha,
+    options.runId,
+  );
+  ensureOwnerOnlyDirectory(directory);
+  return {
+    directory,
+    screenshotPath: join(directory, "screenshot.png"),
+    consolePath: join(directory, "console.txt"),
+  };
+}
+
+/**
+ * Ensure the evidence directory exists with mode 0700. Idempotent —
+ * a pre-existing directory is rechmodded so the canonical secret-
+ * bearing layout survives every startup.
+ */
+export function ensureEvidenceRoot(directory: string): void {
+  ensureOwnerOnlyDirectory(directory);
+}
+
+function unlinkEvidenceFiles(
+  screenshotPath: string | null,
+  consolePath: string | null,
+  compiledPath: string | null = null,
+): void {
+  for (const path of [screenshotPath, consolePath, compiledPath]) {
+    if (path === null) continue;
+    unlinkIfExists(path);
+    // Walk up parent directories that became empty after the unlink.
+    let parent = dirname(path);
+    while (parent.length > 1) {
+      try {
+        const stat = statSync(parent);
+        if (!stat.isDirectory()) break;
+        const entries = (require("node:fs") as typeof import("node:fs")).readdirSync(parent);
+        if (entries.length > 0) break;
+        rmSync(parent, { recursive: true, force: true });
+      } catch {
+        break;
+      }
+      parent = dirname(parent);
+    }
+  }
+}
+
+function unlinkIfExists(path: string): void {
+  try {
+    if (existsSync(path)) rmSync(path, { force: true });
+  } catch {
+    // best-effort — the row is authoritative, a stale file is recoverable
+  }
+}