borgmcp-server 0.1.1

package/src/index.ts

@@ -0,0 +1,3 @@
+export { runCli } from "./cli.js";
+export type { CliIo } from "./cli.js";
+export type { ServerService } from "./service.js";

package/src/main.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { runCli, type CliIo } from "./cli.js";
+import { isFatalTeardownError, nodeServerService } from "./service.js";
+import { operatorPublicMessage } from "./operator-error.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const io = {
+  stdout: (message: string): void => console.log(message),
+  stderr: (message: string): void => console.error(message),
+  readSecret: readHiddenSecret,
+};
+
+async function readHiddenSecret(prompt: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || process.stdin.setRawMode === undefined) {
+    throw new Error("Private terminal input is unavailable.");
+  }
+  process.stdout.write(prompt);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  return new Promise<string>((resolve, reject) => {
+    let value = "";
+    const cleanup = (): void => {
+      process.stdin.off("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk: Buffer | string): void => {
+      for (const byte of Buffer.from(chunk)) {
+        if (byte === 3) {
+          cleanup();
+          reject(new Error("Private terminal input was cancelled."));
+          return;
+        }
+        if (byte === 13 || byte === 10) {
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (byte === 8 || byte === 127) value = value.slice(0, -1);
+        else if (byte >= 32 && byte <= 126 && value.length < 1_024) value += String.fromCharCode(byte);
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+export async function runMain(
+  args: readonly string[] = process.argv.slice(2),
+  service = nodeServerService,
+  output: CliIo = io,
+  fatalExit: (code: number) => never = process.exit,
+): Promise<void> {
+  try {
+    process.exitCode = await runCli(args, service, output);
+  } catch (error) {
+    if (isFatalTeardownError(error)) {
+      output.stderr("Server command failed.");
+      fatalExit(1);
+    }
+    const operatorMessage = operatorPublicMessage(error);
+    output.stderr(operatorMessage === null
+      ? "Server command failed."
+      : `Server command failed: ${operatorMessage}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await runMain();
+}

package/src/migrations.ts

@@ -0,0 +1,394 @@
+import { createHash } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+export interface Migration {
+  readonly version: number;
+  readonly name: string;
+  readonly sql: string;
+}
+
+export const STORE_MIGRATIONS: readonly Migration[] = Object.freeze([
+  {
+    version: 1,
+    name: "initial_scoped_store",
+    sql: `
+      CREATE TABLE clients (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 120),
+        created_at TEXT NOT NULL,
+        revoked_at TEXT
+      ) STRICT;
+
+      CREATE TABLE cubes (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 120),
+        directive TEXT NOT NULL CHECK (length(directive) <= 100000),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      ) STRICT;
+
+      CREATE TABLE client_cube_grants (
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        access TEXT NOT NULL CHECK (access IN ('read', 'write', 'manage')),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (client_id, cube_id)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE TABLE roles (
+        id TEXT NOT NULL,
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 120),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (id),
+        UNIQUE (id, cube_id),
+        UNIQUE (cube_id, name)
+      ) STRICT;
+
+      CREATE TABLE drones (
+        id TEXT NOT NULL,
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        role_id TEXT NOT NULL,
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        label TEXT NOT NULL CHECK (length(label) BETWEEN 1 AND 120),
+        created_at TEXT NOT NULL,
+        evicted_at TEXT,
+        PRIMARY KEY (id),
+        UNIQUE (id, cube_id),
+        UNIQUE (id, client_id, cube_id),
+        UNIQUE (cube_id, label),
+        FOREIGN KEY (role_id, cube_id) REFERENCES roles(id, cube_id)
+      ) STRICT;
+
+      CREATE TABLE drone_sessions (
+        id TEXT PRIMARY KEY,
+        client_id TEXT NOT NULL,
+        cube_id TEXT NOT NULL,
+        drone_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        FOREIGN KEY (drone_id, client_id, cube_id)
+          REFERENCES drones(id, client_id, cube_id) ON DELETE CASCADE
+      ) STRICT;
+
+      CREATE TABLE activity_log (
+        id TEXT PRIMARY KEY,
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        drone_id TEXT,
+        actor_kind TEXT NOT NULL CHECK (actor_kind IN ('operator', 'client', 'drone-session')),
+        actor_id TEXT NOT NULL,
+        message TEXT NOT NULL CHECK (length(message) BETWEEN 1 AND 10240),
+        created_at TEXT NOT NULL,
+        FOREIGN KEY (drone_id, cube_id) REFERENCES drones(id, cube_id)
+      ) STRICT;
+
+      CREATE TABLE activity_acks (
+        entry_id TEXT NOT NULL REFERENCES activity_log(id) ON DELETE CASCADE,
+        principal_kind TEXT NOT NULL CHECK (principal_kind IN ('operator', 'client', 'drone-session')),
+        principal_id TEXT NOT NULL,
+        kind TEXT NOT NULL CHECK (kind IN ('ack', 'claim')),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (entry_id, principal_kind, principal_id, kind)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE INDEX client_cube_grants_cube_idx
+        ON client_cube_grants (cube_id, access, client_id);
+      CREATE INDEX drone_sessions_scope_idx
+        ON drone_sessions (client_id, cube_id, drone_id, expires_at)
+        WHERE revoked_at IS NULL;
+      CREATE INDEX activity_log_cube_cursor_idx
+        ON activity_log (cube_id, created_at, id);
+    `,
+  },
+  {
+    version: 2,
+    name: "credential_authority",
+    sql: `
+      CREATE TABLE recovery_credentials (
+        id TEXT PRIMARY KEY,
+        lookup_digest BLOB NOT NULL UNIQUE,
+        verifier_digest BLOB NOT NULL,
+        created_at TEXT NOT NULL,
+        revoked_at TEXT
+      ) STRICT;
+
+      CREATE TABLE enrollment_invitations (
+        id TEXT PRIMARY KEY,
+        lookup_digest BLOB NOT NULL UNIQUE,
+        verifier_digest BLOB NOT NULL,
+        expires_at TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        consumed_at TEXT
+      ) STRICT;
+
+      CREATE TABLE client_credentials (
+        id TEXT PRIMARY KEY,
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        lookup_digest BLOB NOT NULL UNIQUE,
+        verifier_digest BLOB NOT NULL,
+        created_at TEXT NOT NULL,
+        revoked_at TEXT
+      ) STRICT;
+
+      CREATE INDEX enrollment_invitations_expiry_idx
+        ON enrollment_invitations (expires_at)
+        WHERE consumed_at IS NULL;
+      CREATE INDEX client_credentials_client_idx
+        ON client_credentials (client_id, revoked_at);
+    `,
+  },
+  {
+    version: 3,
+    name: "coordination_protocol",
+    sql: `
+      ALTER TABLE cubes ADD COLUMN owner_id TEXT NOT NULL
+        DEFAULT '00000000-0000-4000-8000-000000000000';
+      ALTER TABLE roles ADD COLUMN short_description TEXT NOT NULL DEFAULT '';
+      ALTER TABLE roles ADD COLUMN detailed_description TEXT NOT NULL DEFAULT '';
+      ALTER TABLE roles ADD COLUMN is_default INTEGER NOT NULL DEFAULT 0
+        CHECK (is_default IN (0, 1));
+      ALTER TABLE roles ADD COLUMN is_human_seat INTEGER NOT NULL DEFAULT 0
+        CHECK (is_human_seat IN (0, 1));
+      ALTER TABLE drones ADD COLUMN last_seen TEXT;
+      ALTER TABLE drones ADD COLUMN hostname TEXT;
+      ALTER TABLE activity_log ADD COLUMN visibility TEXT NOT NULL DEFAULT 'broadcast'
+        CHECK (visibility IN ('broadcast', 'direct'));
+      ALTER TABLE activity_acks ADD COLUMN claimant_drone_id TEXT;
+
+      CREATE TABLE activity_log_recipients (
+        entry_id TEXT NOT NULL REFERENCES activity_log(id) ON DELETE CASCADE,
+        drone_id TEXT NOT NULL REFERENCES drones(id) ON DELETE CASCADE,
+        PRIMARY KEY (entry_id, drone_id)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE TABLE expired_activity_cursors (
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        entry_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (cube_id, entry_id, created_at)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE TABLE decisions (
+        id TEXT PRIMARY KEY,
+        cube_id TEXT NOT NULL REFERENCES cubes(id) ON DELETE CASCADE,
+        topic TEXT NOT NULL CHECK (length(topic) BETWEEN 1 AND 120),
+        decision TEXT NOT NULL CHECK (length(decision) BETWEEN 1 AND 100000),
+        rationale TEXT CHECK (rationale IS NULL OR length(rationale) <= 100000),
+        ratified_by TEXT,
+        status TEXT NOT NULL CHECK (status IN ('active', 'superseded', 'removed')),
+        supersedes TEXT REFERENCES decisions(id),
+        created_at TEXT NOT NULL
+      ) STRICT;
+
+      CREATE INDEX activity_log_recipients_drone_idx
+        ON activity_log_recipients (drone_id, entry_id);
+      CREATE INDEX activity_acks_claim_idx
+        ON activity_acks (kind, entry_id, created_at);
+      CREATE UNIQUE INDEX decisions_active_topic_idx
+        ON decisions (cube_id, topic) WHERE status = 'active';
+      CREATE INDEX decisions_cube_status_idx
+        ON decisions (cube_id, status, created_at, id);
+    `,
+  },
+  {
+    version: 4,
+    name: "seat_attach_credentials",
+    sql: `
+      ALTER TABLE drones ADD COLUMN retry_key TEXT;
+      ALTER TABLE drones ADD COLUMN attach_generation INTEGER NOT NULL DEFAULT 0
+        CHECK (attach_generation >= 0);
+      ALTER TABLE roles ADD COLUMN role_class TEXT NOT NULL DEFAULT 'worker'
+        CHECK (role_class IN ('queen', 'worker'));
+
+      CREATE UNIQUE INDEX drones_client_retry_key_idx
+        ON drones (client_id, retry_key) WHERE retry_key IS NOT NULL;
+
+      CREATE TABLE drone_session_credentials (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES drone_sessions(id) ON DELETE CASCADE,
+        lookup_digest BLOB NOT NULL UNIQUE,
+        verifier_digest BLOB NOT NULL,
+        created_at TEXT NOT NULL,
+        revoked_at TEXT
+      ) STRICT;
+
+      CREATE INDEX drone_session_credentials_session_idx
+        ON drone_session_credentials (session_id, revoked_at);
+    `,
+  },
+  {
+    version: 5,
+    name: "owner_enrollment_and_cube_creation",
+    sql: `
+      ALTER TABLE enrollment_invitations ADD COLUMN purpose TEXT NOT NULL DEFAULT 'client'
+        CHECK (purpose IN ('owner', 'client'));
+      ALTER TABLE enrollment_invitations ADD COLUMN owner_epoch INTEGER
+        CHECK (owner_epoch IS NULL OR owner_epoch > 0);
+      ALTER TABLE enrollment_invitations ADD COLUMN revoked_at TEXT;
+
+      CREATE TABLE owner_enrollment_state (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        epoch INTEGER NOT NULL CHECK (epoch > 0),
+        claimed_client_id TEXT REFERENCES clients(id),
+        claimed_at TEXT,
+        CHECK ((claimed_client_id IS NULL) = (claimed_at IS NULL))
+      ) STRICT;
+
+      CREATE TABLE enrollment_claims (
+        invitation_id TEXT PRIMARY KEY REFERENCES enrollment_invitations(id) ON DELETE CASCADE,
+        retry_key TEXT NOT NULL,
+        client_id TEXT NOT NULL UNIQUE REFERENCES clients(id) ON DELETE CASCADE,
+        requested_client_name TEXT,
+        credential_lookup_digest BLOB NOT NULL,
+        credential_verifier_digest BLOB NOT NULL,
+        purpose TEXT NOT NULL CHECK (purpose IN ('owner', 'client')),
+        owner_epoch INTEGER,
+        created_at TEXT NOT NULL,
+        CHECK ((purpose = 'owner') = (owner_epoch IS NOT NULL))
+      ) STRICT;
+
+      CREATE TABLE client_server_capabilities (
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        capability TEXT NOT NULL CHECK (capability = 'create_cube'),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (client_id, capability)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE TABLE cube_create_bindings (
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        retry_key TEXT NOT NULL,
+        name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 120),
+        template TEXT NOT NULL CHECK (template = 'default'),
+        cube_id TEXT NOT NULL UNIQUE REFERENCES cubes(id) ON DELETE CASCADE,
+        human_seat_role_id TEXT NOT NULL UNIQUE,
+        default_worker_role_id TEXT NOT NULL UNIQUE,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (client_id, retry_key),
+        FOREIGN KEY (human_seat_role_id, cube_id) REFERENCES roles(id, cube_id),
+        FOREIGN KEY (default_worker_role_id, cube_id) REFERENCES roles(id, cube_id)
+      ) STRICT, WITHOUT ROWID;
+
+      CREATE INDEX cube_create_bindings_cube_idx ON cube_create_bindings (cube_id);
+      CREATE INDEX enrollment_invitations_owner_idx
+        ON enrollment_invitations (purpose, owner_epoch, expires_at)
+        WHERE consumed_at IS NULL AND revoked_at IS NULL;
+    `,
+  },
+  {
+    version: 6,
+    name: "seat_reattach_bindings",
+    sql: `
+      CREATE TABLE seat_attach_bindings (
+        client_id TEXT NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+        retry_key TEXT NOT NULL,
+        cube_id TEXT NOT NULL,
+        requested_role_id TEXT NOT NULL,
+        drone_id TEXT NOT NULL,
+        prior_drone_id TEXT,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (client_id, retry_key),
+        FOREIGN KEY (requested_role_id, cube_id) REFERENCES roles(id, cube_id),
+        FOREIGN KEY (drone_id, client_id, cube_id)
+          REFERENCES drones(id, client_id, cube_id) ON DELETE CASCADE
+      ) STRICT, WITHOUT ROWID;
+
+      INSERT INTO seat_attach_bindings (
+        client_id, retry_key, cube_id, requested_role_id, drone_id, prior_drone_id, created_at
+      )
+      SELECT client_id, retry_key, cube_id, role_id, id, NULL, created_at
+      FROM drones WHERE retry_key IS NOT NULL;
+
+      CREATE INDEX seat_attach_bindings_drone_idx
+        ON seat_attach_bindings (drone_id, client_id, cube_id);
+    `,
+  },
+]);
+
+interface AppliedMigrationRow {
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+}
+
+export function applyMigrations(
+  database: DatabaseSync,
+  migrations: readonly Migration[] = STORE_MIGRATIONS,
+): void {
+  validateMigrationOrder(migrations);
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      checksum TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    ) STRICT;
+  `);
+
+  const applied = database.prepare(
+    "SELECT version, name, checksum FROM schema_migrations ORDER BY version",
+  ).all().map(appliedMigrationRow);
+  const knownVersions = new Set(migrations.map((migration) => migration.version));
+  for (const row of applied) {
+    const migration = migrations.find((candidate) => candidate.version === row.version);
+    if (migration === undefined || !knownVersions.has(row.version)) {
+      throw new Error(`Database contains unknown migration ${row.version}.`);
+    }
+    if (row.name !== migration.name || row.checksum !== checksum(migration)) {
+      throw new Error(`Migration ${row.version} does not match its recorded checksum.`);
+    }
+  }
+
+  const appliedVersions = new Set(applied.map((row) => row.version));
+  const record = database.prepare(
+    "INSERT INTO schema_migrations (version, name, checksum, applied_at) VALUES (?, ?, ?, ?)",
+  );
+  for (const migration of migrations) {
+    if (appliedVersions.has(migration.version)) continue;
+    database.exec("BEGIN IMMEDIATE");
+    try {
+      database.exec(migration.sql);
+      record.run(
+        migration.version,
+        migration.name,
+        checksum(migration),
+        new Date().toISOString(),
+      );
+      database.exec("COMMIT");
+    } catch (error) {
+      try {
+        database.exec("ROLLBACK");
+      } catch {
+        // The original migration error is the actionable failure.
+      }
+      throw error;
+    }
+  }
+}
+
+function validateMigrationOrder(migrations: readonly Migration[]): void {
+  migrations.forEach((migration, index) => {
+    if (migration.version !== index + 1 || migration.name.length === 0 || migration.sql.length === 0) {
+      throw new Error("Migrations must be non-empty and ordered contiguously from version 1.");
+    }
+  });
+}
+
+function checksum(migration: Migration): string {
+  return createHash("sha256")
+    .update(`${migration.version}\0${migration.name}\0${migration.sql}`)
+    .digest("hex");
+}
+
+function appliedMigrationRow(row: Record<string, unknown>): AppliedMigrationRow {
+  if (!Number.isSafeInteger(row["version"]) ||
+      typeof row["name"] !== "string" ||
+      typeof row["checksum"] !== "string") {
+    throw new Error("Database contains an invalid migration record.");
+  }
+  return {
+    version: row["version"] as number,
+    name: row["name"],
+    checksum: row["checksum"],
+  };
+}

package/src/network-policy.ts

@@ -0,0 +1,65 @@
+import { isIP } from "node:net";
+import { operatorErrors } from "./operator-error.js";
+
+export const DEFAULT_BIND_HOST = "127.0.0.1";
+export const DEFAULT_PORT = 7_091;
+
+export interface BindOptionsInput {
+  readonly host?: string;
+  readonly port?: number;
+  readonly lanConsent?: boolean;
+}
+
+export interface ResolvedBindOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly mode: "loopback" | "lan";
+}
+
+export function resolveBindOptions(input: BindOptionsInput): ResolvedBindOptions {
+  const host = input.host ?? DEFAULT_BIND_HOST;
+  const port = input.port ?? DEFAULT_PORT;
+
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw operatorErrors.BIND_PORT_INVALID;
+  }
+  if (isIP(host) === 0) {
+    throw operatorErrors.BIND_HOST_INVALID;
+  }
+  if (host === "0.0.0.0" || host === "::") {
+    throw operatorErrors.BIND_WILDCARD;
+  }
+  if (isLoopback(host)) {
+    return { host, port, mode: "loopback" };
+  }
+  if (!isPrivateLan(host)) {
+    throw operatorErrors.BIND_PUBLIC;
+  }
+  if (input.lanConsent !== true) {
+    throw operatorErrors.BIND_LAN_CONSENT;
+  }
+
+  return { host, port, mode: "lan" };
+}
+
+function isLoopback(host: string): boolean {
+  if (host === "::1") return true;
+  if (isIP(host) !== 4) return false;
+  return Number(host.split(".")[0]) === 127;
+}
+
+function isPrivateLan(host: string): boolean {
+  const family = isIP(host);
+  if (family === 4) {
+    const octets = host.split(".").map(Number);
+    const first = octets[0];
+    const second = octets[1];
+    return first === 10 ||
+      (first === 172 && second !== undefined && second >= 16 && second <= 31) ||
+      (first === 192 && second === 168) ||
+      (first === 169 && second === 254);
+  }
+
+  const normalized = host.toLowerCase();
+  return normalized.startsWith("fc") || normalized.startsWith("fd") || /^fe[89ab]/u.test(normalized);
+}

package/src/operator-error.ts

@@ -0,0 +1,97 @@
+export type OperatorErrorCode =
+  | "START_LAN_DUPLICATE"
+  | "START_HOST_DUPLICATE"
+  | "START_PORT_DUPLICATE"
+  | "START_HOST_MISSING"
+  | "START_PORT_MISSING"
+  | "START_PORT_INVALID"
+  | "START_OPTION_UNKNOWN"
+  | "BIND_PORT_INVALID"
+  | "BIND_HOST_INVALID"
+  | "BIND_WILDCARD"
+  | "BIND_PUBLIC"
+  | "BIND_LAN_CONSENT"
+  | "SERVER_FILES_MISSING"
+  | "DATA_PATH_SYMLINK"
+  | "LAN_CA_KEY_ONLINE"
+  | "RUNTIME_ACTIVE"
+  | "RUNTIME_LOCK_UNSAFE"
+  | "RUNTIME_LOCK_INVALID"
+  | "RUNTIME_LOCK_STALE"
+  | "ACTIVITY_LIMIT_INVALID"
+  | "DATABASE_LIMIT_INVALID"
+  | "DISK_RESERVE_INVALID"
+  | "CLIENT_NOT_FOUND"
+  | "GRANT_NOT_FOUND"
+  | "RECOVERY_INVALID";
+
+const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freeze({
+  START_LAN_DUPLICATE: "Provide --lan only once.",
+  START_HOST_DUPLICATE: "Provide --host only once.",
+  START_PORT_DUPLICATE: "Provide --port only once.",
+  START_HOST_MISSING: "Provide an IP address after --host.",
+  START_PORT_MISSING: "Provide a port number after --port.",
+  START_PORT_INVALID: "Provide --port as an integer from 0 to 65535.",
+  START_OPTION_UNKNOWN: "Use only documented start options; run borg-mcp-server help.",
+  BIND_PORT_INVALID: "Configure the listen port as an integer from 0 to 65535.",
+  BIND_HOST_INVALID: "Configure --host as an explicit IP address.",
+  BIND_WILDCARD: "Choose a specific loopback or private-LAN IP; wildcard binds are prohibited.",
+  BIND_PUBLIC: "Choose a loopback or private-LAN IP; public-routable binds are unsupported.",
+  BIND_LAN_CONSENT: "Add --lan to consent to this private-LAN start.",
+  SERVER_FILES_MISSING: "Configure BORG_SERVER_DATA_DIR or the required TLS file variables.",
+  DATA_PATH_SYMLINK: "Choose a BORG_SERVER_DATA_DIR path that contains no symbolic links.",
+  LAN_CA_KEY_ONLINE: "Move ca.key out of the runtime data directory before private-LAN startup.",
+  RUNTIME_ACTIVE: "Stop the server before running offline client administration.",
+  RUNTIME_LOCK_UNSAFE: "Ensure runtime.lock is a private regular file before retrying.",
+  RUNTIME_LOCK_INVALID: "Confirm the server is stopped, then remove the invalid runtime.lock.",
+  RUNTIME_LOCK_STALE: "Confirm the recorded server process is stopped, then remove runtime.lock.",
+  ACTIVITY_LIMIT_INVALID: "Set BORG_SERVER_MAX_ACTIVITY_ENTRIES_PER_CUBE to a positive integer.",
+  DATABASE_LIMIT_INVALID: "Set BORG_SERVER_MAX_DATABASE_BYTES to a positive integer.",
+  DISK_RESERVE_INVALID: "Set BORG_SERVER_MIN_FREE_DISK_BYTES to a positive integer.",
+  CLIENT_NOT_FOUND: "Provide an existing active client ID.",
+  GRANT_NOT_FOUND: "Provide an existing client cube grant.",
+  RECOVERY_INVALID: "Provide the active recovery credential through the private prompt.",
+});
+
+const operatorErrorCodes = new WeakMap<object, OperatorErrorCode>();
+const operatorErrorCapability = Object.freeze({});
+
+class OperatorError extends Error {
+  readonly #operatorCode: OperatorErrorCode;
+
+  constructor(capability: object, code: OperatorErrorCode) {
+    super(Object.hasOwn(publicMessages, code) ? publicMessages[code] : "Operator error rejected.");
+    if (capability !== operatorErrorCapability || !Object.hasOwn(publicMessages, code)) {
+      throw new Error("Operator error construction is unavailable.");
+    }
+    this.name = "OperatorError";
+    this.#operatorCode = code;
+    operatorErrorCodes.set(this, code);
+    Object.freeze(this);
+  }
+
+  get code(): OperatorErrorCode {
+    return this.#operatorCode;
+  }
+
+  get publicMessage(): string {
+    return publicMessages[this.#operatorCode];
+  }
+}
+
+export const operatorErrors: Readonly<Record<OperatorErrorCode, Error>> = Object.freeze(
+  Object.fromEntries(
+    (Object.keys(publicMessages) as OperatorErrorCode[]).map((code) => [
+      code,
+      new OperatorError(operatorErrorCapability, code),
+    ]),
+  ) as unknown as Record<OperatorErrorCode, Error>,
+);
+
+export function operatorPublicMessage(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) return null;
+  const code = operatorErrorCodes.get(error);
+  if (code === undefined) return null;
+  if (Object.getPrototypeOf(error) !== OperatorError.prototype || !Object.isFrozen(error)) return null;
+  return publicMessages[code];
+}