borgmcp-server 0.1.1 → 0.1.4

package/src/debug-log.ts

@@ -0,0 +1,165 @@
+import type { Principal } from "./principal.js";
+
+export type DebugRoute =
+  | "health"
+  | "protocol"
+  | "enrollment_exchange"
+  | "client_attach"
+  | "cubes"
+  | "cube"
+  | "cube_roles"
+  | "cube_role"
+  | "cube_role_section_patch"
+  | "cube_drones"
+  | "cube_logs"
+  | "cube_acks"
+  | "cube_decisions"
+  | "cube_stream"
+  | "unknown";
+
+export type DebugEvent =
+  | { readonly event: "startup"; readonly bindMode: "loopback" | "lan"; readonly port: number; readonly dataDirectory: "configured" | "tls_only" }
+  | { readonly event: "lifecycle"; readonly action: "listening" | "stopped" }
+  | { readonly event: "request"; readonly route: DebugRoute; readonly method: string; readonly authentication: "not_required" | "missing" | "invalid" | "revoked" | "accepted"; readonly authorization: "not_checked" | "accepted" | "denied_or_not_found"; readonly principal?: Principal; readonly status: number; readonly durationMs: number }
+  | { readonly event: "activity_append"; readonly cubeId: string; readonly entryId: string; readonly principal: Principal; readonly droneId: string | null; readonly visibility: "broadcast" | "direct"; readonly recipientDroneIds: readonly string[] }
+  | { readonly event: "cursor_replay"; readonly mode: "page" | "sse"; readonly cubeId: string; readonly cursorId: string | null; readonly returnedCount: number; readonly behindBy: number; readonly truncated: boolean }
+  | { readonly event: "ack_write"; readonly cubeId: string; readonly entryId: string; readonly kind: "ack" | "claim"; readonly principal: Principal }
+  | { readonly event: "decision_write"; readonly cubeId: string; readonly decisionId: string; readonly principal: Principal }
+  | { readonly event: "sse_subscribe"; readonly connectionId: string; readonly cubeId: string; readonly principal: Principal; readonly replayCount: number; readonly truncated: boolean }
+  | { readonly event: "sse_unsubscribe"; readonly connectionId: string; readonly cubeId: string; readonly principal: Principal; readonly deliveryCount: number }
+  | { readonly event: "credential"; readonly action: "invitation_created" | "enrollment_accepted" | "enrollment_rejected" | "session_created" | "session_revoked" | "client_rotated" | "client_revoked"; readonly purpose?: "owner" | "client"; readonly clientId?: string; readonly cubeId?: string; readonly droneId?: string; readonly sessionId?: string; readonly generation?: number }
+  | { readonly event: "transport_rejection"; readonly reason: "tls_client_error" | "http_parser_error" };
+
+export interface DebugLogger {
+  readonly emit: (event: DebugEvent) => void;
+}
+
+export const disabledDebugLogger: DebugLogger = Object.freeze({ emit: () => undefined });
+
+export function createDebugLogger(write: ((line: string) => void) | undefined): DebugLogger {
+  if (write === undefined) return disabledDebugLogger;
+  return Object.freeze({
+    emit(event: DebugEvent): void {
+      try {
+        const projected = projectEvent(event);
+        if (projected !== null) write(JSON.stringify({ level: "debug", ...projected }));
+      } catch {
+        // Operator diagnostics cannot alter request or server behavior.
+      }
+    },
+  });
+}
+
+function projectEvent(event: DebugEvent): Record<string, unknown> | null {
+  const value = event as unknown as Record<string, unknown>;
+  switch (value["event"]) {
+    case "startup":
+      return {
+        event: "startup",
+        bind_mode: enumValue(value["bindMode"], ["loopback", "lan"], "loopback"),
+        port: boundedInteger(value["port"], 0, 65_535),
+        data_directory: enumValue(value["dataDirectory"], ["configured", "tls_only"], "tls_only"),
+      };
+    case "request": {
+      const principal = principalFields(value["principal"]);
+      return {
+        event: "request",
+        route: enumValue(value["route"], DEBUG_ROUTES, "unknown"),
+        method: enumValue(value["method"], HTTP_METHODS, "OTHER"),
+        authentication: enumValue(value["authentication"], AUTH_RESULTS, "invalid"),
+        authorization: enumValue(value["authorization"], AUTHZ_RESULTS, "not_checked"),
+        ...principal,
+        status: boundedInteger(value["status"], 0, 599),
+        duration_ms: boundedInteger(value["durationMs"], 0, Number.MAX_SAFE_INTEGER),
+      };
+    }
+    case "lifecycle":
+      return { event: "lifecycle", action: enumValue(value["action"], ["listening", "stopped"], "stopped") };
+    case "activity_append":
+      return {
+        event: "activity_append",
+        cube_id: uuid(value["cubeId"]),
+        entry_id: uuid(value["entryId"]),
+        ...principalFields(value["principal"]),
+        drone_id: nullableUuid(value["droneId"]),
+        visibility: enumValue(value["visibility"], ["broadcast", "direct"], "broadcast"),
+        recipient_count: uuidArray(value["recipientDroneIds"]).length,
+        recipient_drone_ids: uuidArray(value["recipientDroneIds"]),
+      };
+    case "cursor_replay":
+      return {
+        event: "cursor_replay",
+        mode: enumValue(value["mode"], ["page", "sse"], "page"),
+        cube_id: uuid(value["cubeId"]),
+        cursor_id: nullableUuid(value["cursorId"]),
+        returned_count: boundedInteger(value["returnedCount"], 0, 500),
+        behind_by: boundedInteger(value["behindBy"], 0, Number.MAX_SAFE_INTEGER),
+        truncated: value["truncated"] === true,
+      };
+    case "ack_write":
+      return { event: "ack_write", cube_id: uuid(value["cubeId"]), entry_id: uuid(value["entryId"]), kind: enumValue(value["kind"], ["ack", "claim"], "ack"), ...principalFields(value["principal"]) };
+    case "decision_write":
+      return { event: "decision_write", cube_id: uuid(value["cubeId"]), decision_id: uuid(value["decisionId"]), ...principalFields(value["principal"]) };
+    case "sse_subscribe":
+      return { event: "sse_subscribe", connection_id: uuid(value["connectionId"]), cube_id: uuid(value["cubeId"]), ...principalFields(value["principal"]), replay_count: boundedInteger(value["replayCount"], 0, 200), truncated: value["truncated"] === true };
+    case "sse_unsubscribe":
+      return { event: "sse_unsubscribe", connection_id: uuid(value["connectionId"]), cube_id: uuid(value["cubeId"]), ...principalFields(value["principal"]), delivery_count: boundedInteger(value["deliveryCount"], 0, Number.MAX_SAFE_INTEGER) };
+    case "credential":
+      return {
+        event: "credential",
+        action: enumValue(value["action"], CREDENTIAL_ACTIONS, "enrollment_rejected"),
+        ...(value["purpose"] === "owner" || value["purpose"] === "client" ? { purpose: value["purpose"] } : {}),
+        ...optionalUuid("client_id", value["clientId"]),
+        ...optionalUuid("cube_id", value["cubeId"]),
+        ...optionalUuid("drone_id", value["droneId"]),
+        ...optionalUuid("session_id", value["sessionId"]),
+        ...(Number.isSafeInteger(value["generation"]) ? { generation: value["generation"] } : {}),
+      };
+    case "transport_rejection":
+      return { event: "transport_rejection", reason: enumValue(value["reason"], ["tls_client_error", "http_parser_error"], "tls_client_error") };
+    default:
+      return null;
+  }
+}
+
+function principalFields(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return {};
+  const principal = value as Record<string, unknown>;
+  const kind = enumValue(principal["kind"], ["operator", "client", "drone-session"], "client");
+  return { principal_kind: kind, ...optionalUuid("principal_id", principal["id"]) };
+}
+
+function uuid(value: unknown): string | null {
+  return typeof value === "string" && UUID_PATTERN.test(value) ? value.toLowerCase() : null;
+}
+
+function nullableUuid(value: unknown): string | null {
+  return value === null ? null : uuid(value);
+}
+
+function optionalUuid(key: string, value: unknown): Record<string, string> {
+  const safe = uuid(value);
+  return safe === null ? {} : { [key]: safe };
+}
+
+function uuidArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 100).map(uuid).filter((item): item is string => item !== null);
+}
+
+function boundedInteger(value: unknown, minimum: number, maximum: number): number {
+  return Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum
+    ? value as number
+    : minimum;
+}
+
+function enumValue<const T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === "string" && allowed.includes(value as T) ? value as T : fallback;
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const DEBUG_ROUTES: readonly DebugRoute[] = ["health", "protocol", "enrollment_exchange", "client_attach", "cubes", "cube", "cube_roles", "cube_role", "cube_role_section_patch", "cube_drones", "cube_logs", "cube_acks", "cube_decisions", "cube_stream", "unknown"];
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OTHER"] as const;
+const AUTH_RESULTS = ["not_required", "missing", "invalid", "revoked", "accepted"] as const;
+const AUTHZ_RESULTS = ["not_checked", "accepted", "denied_or_not_found"] as const;
+const CREDENTIAL_ACTIONS = ["invitation_created", "enrollment_accepted", "enrollment_rejected", "session_created", "session_revoked", "client_rotated", "client_revoked"] as const;

package/src/https-server.ts

@@ -6,6 +6,7 @@ import { createHash, X509Certificate } from "node:crypto";
 import { resolveBindOptions, type BindOptionsInput } from "./network-policy.js";
 import type { CoordinationRequest, CoordinationResponse } from "./coordination-api.js";
 import type { Principal } from "./principal.js";
+import { disabledDebugLogger, type DebugLogger, type DebugRoute } from "./debug-log.js";
 
 export interface ProtocolInfoDocument {
   readonly protocol_version: string;
@@ -74,6 +75,7 @@ export interface RequestHandlerContext {
     signal: AbortSignal,
   ) => Promise<Principal | "missing" | "invalid" | "revoked">;
   readonly handleCoordination?: (request: CoordinationRequest) => Promise<CoordinationResponse>;
+  readonly debugLogger: DebugLogger;
 }
 
 export interface HttpsServerOptions {
@@ -89,6 +91,7 @@ export interface HttpsServerOptions {
   readonly authorizeCoordination?: RequestHandlerContext["authorizeCoordination"];
   readonly handleCoordination?: RequestHandlerContext["handleCoordination"];
   readonly limits?: ServiceLimits;
+  readonly debugLogger?: DebugLogger;
   readonly testHooks?: {
     readonly identifyRemoteAddress?: (socket: Socket) => string;
   };
@@ -126,8 +129,14 @@ export async function startHttpsServer(options: HttpsServerOptions): Promise<Run
 
   const acceptedSockets = applyServerLimits(server, limits);
   server.on("secureConnection", (socket) => socket.disableRenegotiation());
-  server.on("tlsClientError", (_error, socket) => socket.destroy());
-  server.on("clientError", (_error, socket) => socket.end("HTTP/1.1 400 Bad Request\r\n\r\n"));
+  server.on("tlsClientError", (_error, socket) => {
+    handlerContext.debugLogger.emit({ event: "transport_rejection", reason: "tls_client_error" });
+    socket.destroy();
+  });
+  server.on("clientError", (_error, socket) => {
+    handlerContext.debugLogger.emit({ event: "transport_rejection", reason: "http_parser_error" });
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+  });
   server.on("checkContinue", (_request, response) => sendEmpty(response, 417, true));
 
   try {
@@ -170,6 +179,7 @@ export function createRequestHandlerContext(
     ...(options.handleCoordination === undefined
       ? {}
       : { handleCoordination: options.handleCoordination }),
+    debugLogger: options.debugLogger ?? disabledDebugLogger,
   });
 }
 
@@ -182,6 +192,32 @@ function createRequestListener(
   const credentialRateLimiter = new RequestRateLimiter(limits, limits.maxRequestsPerWindow);
   const streamQuota = new ConcurrentQuota(limits.maxStreamsPerCredential);
   return (request, response) => {
+    const startedAt = Date.now();
+    const trace: RequestTrace = {
+      route: debugRoute(request.url),
+      method: debugMethod(request.method),
+      authentication: "not_required",
+    };
+    let debugEmitted = false;
+    const emitDebug = (): void => {
+      if (debugEmitted) return;
+      debugEmitted = true;
+      const status = response.headersSent ? response.statusCode : 0;
+      context.debugLogger.emit({
+        event: "request",
+        route: trace.route,
+        method: trace.method,
+        authentication: trace.authentication,
+        authorization: trace.authentication === "accepted"
+          ? status === 403 || status === 404 ? "denied_or_not_found" : "accepted"
+          : "not_checked",
+        ...(trace.principal === undefined ? {} : { principal: trace.principal }),
+        status,
+        durationMs: Math.max(0, Date.now() - startedAt),
+      });
+    };
+    response.once("finish", emitDebug);
+    response.once("close", emitDebug);
     const controller = new AbortController();
     response.once("close", () => controller.abort());
     let timer: NodeJS.Timeout | undefined;
@@ -202,6 +238,7 @@ function createRequestListener(
       streamQuota,
       identifyRemoteAddress,
       controller.signal,
+      trace,
     )
       .then(() => "handled" as const);
 
@@ -226,6 +263,7 @@ async function handleRequest(
   streamQuota: ConcurrentQuota,
   identifyRemoteAddress: (socket: Socket) => string,
   signal: AbortSignal,
+  trace: RequestTrace,
 ): Promise<void> {
   const addressIdentity = `address:${identifyRemoteAddress(request.socket)}`;
   const preAuthRetry = admissionLimiter.consume(addressIdentity);
@@ -261,6 +299,7 @@ async function handleRequest(
   if (path === "/api/protocol") {
     if (requestBody.length !== 0) return sendEmpty(response, 400, true);
     const authorized = await context.authorizeProtocol(request.headers.authorization, signal);
+    trace.authentication = authorized === true ? "accepted" : authorized === false ? "invalid" : authorized;
     if (signal.aborted) return;
     if (authorized !== true) {
       const code = authorized === "revoked"
@@ -330,6 +369,7 @@ async function handleRequest(
       return;
     }
     const authentication = await authorizeCoordination(authorization, signal);
+    trace.authentication = typeof authentication === "string" ? authentication : "accepted";
     if (signal.aborted) return;
     if (typeof authentication === "string") {
       const code = authentication === "revoked"
@@ -338,6 +378,7 @@ async function handleRequest(
       sendJson(response, 401, protocolError(code, "Authentication failed."));
       return;
     }
+    trace.principal = authentication;
     const clientIdentity = `client:${authentication.kind === "drone-session"
       ? authentication.clientId
       : authentication.id}`;
@@ -378,6 +419,38 @@ async function handleRequest(
   sendEmpty(response, 404);
 }
 
+interface RequestTrace {
+  readonly route: DebugRoute;
+  readonly method: string;
+  authentication: "not_required" | "missing" | "invalid" | "revoked" | "accepted";
+  principal?: Principal;
+}
+
+function debugMethod(method: string | undefined): string {
+  return method === "GET" || method === "POST" || method === "PUT" ||
+    method === "PATCH" || method === "DELETE" ? method : "OTHER";
+}
+
+function debugRoute(rawUrl: string | undefined): DebugRoute {
+  const path = parseRequestPath(rawUrl);
+  if (path === null) return "unknown";
+  if (path === "/healthz") return "health";
+  if (path === "/api/protocol") return "protocol";
+  if (path === "/api/enrollment/exchange") return "enrollment_exchange";
+  if (path === "/api/client/attach") return "client_attach";
+  if (path === "/api/cubes") return "cubes";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}$/iu.test(path)) return "cube";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles$/iu.test(path)) return "cube_roles";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles\/[0-9a-f-]{36}$/iu.test(path)) return "cube_role";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles\/[0-9a-f-]{36}\/section-patch$/iu.test(path)) return "cube_role_section_patch";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/drones$/iu.test(path)) return "cube_drones";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/logs$/iu.test(path)) return "cube_logs";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/acks$/iu.test(path)) return "cube_acks";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/decisions$/iu.test(path)) return "cube_decisions";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/stream$/iu.test(path)) return "cube_stream";
+  return "unknown";
+}
+
 async function closeRejectedStream(stream: AsyncIterable<string>): Promise<void> {
   const iterator = stream[Symbol.asyncIterator]();
   try {

package/src/index.ts

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

package/src/migrations.ts

@@ -7,6 +7,13 @@ export interface Migration {
   readonly sql: string;
 }
 
+export class MigrationCompatibilityError extends Error {
+  constructor() {
+    super("Database migrations do not exactly match this server version.");
+    this.name = "MigrationCompatibilityError";
+  }
+}
+
 export const STORE_MIGRATIONS: readonly Migration[] = Object.freeze([
   {
     version: 1,
@@ -303,6 +310,46 @@ export const STORE_MIGRATIONS: readonly Migration[] = Object.freeze([
         ON seat_attach_bindings (drone_id, client_id, cube_id);
     `,
   },
+  {
+    version: 7,
+    name: "role_management_foundation",
+    sql: `
+      ALTER TABLE roles ADD COLUMN is_mandatory INTEGER NOT NULL DEFAULT 0
+        CHECK (is_mandatory IN (0, 1));
+      ALTER TABLE roles ADD COLUMN can_broadcast INTEGER NOT NULL DEFAULT 0
+        CHECK (can_broadcast IN (0, 1));
+      ALTER TABLE roles ADD COLUMN receives_all_direct INTEGER NOT NULL DEFAULT 0
+        CHECK (receives_all_direct IN (0, 1));
+
+      CREATE UNIQUE INDEX roles_one_default_per_cube_idx
+        ON roles (cube_id) WHERE is_default = 1;
+    `,
+  },
+  {
+    version: 8,
+    name: "cube_scoped_invitations",
+    sql: `
+      ALTER TABLE enrollment_invitations ADD COLUMN cube_id TEXT;
+      ALTER TABLE enrollment_invitations ADD COLUMN access TEXT
+        CHECK (access IS NULL OR access IN ('read', 'write', 'manage'));
+
+      CREATE TRIGGER enrollment_invitations_scope_insert
+      BEFORE INSERT ON enrollment_invitations
+      WHEN (NEW.cube_id IS NULL) <> (NEW.access IS NULL)
+        OR (NEW.cube_id IS NOT NULL AND NEW.purpose <> 'client')
+      BEGIN
+        SELECT RAISE(ABORT, 'invalid invitation cube scope');
+      END;
+
+      CREATE TRIGGER enrollment_invitations_scope_update
+      BEFORE UPDATE OF cube_id, access, purpose ON enrollment_invitations
+      WHEN (NEW.cube_id IS NULL) <> (NEW.access IS NULL)
+        OR (NEW.cube_id IS NOT NULL AND NEW.purpose <> 'client')
+      BEGIN
+        SELECT RAISE(ABORT, 'invalid invitation cube scope');
+      END;
+    `,
+  },
 ]);
 
 interface AppliedMigrationRow {
@@ -366,6 +413,33 @@ export function applyMigrations(
   }
 }
 
+export function assertMigrationsCurrent(
+  database: DatabaseSync,
+  migrations: readonly Migration[] = STORE_MIGRATIONS,
+): void {
+  validateMigrationOrder(migrations);
+  let rows: Record<string, unknown>[];
+  try {
+    rows = database.prepare(
+      "SELECT version, name, checksum FROM schema_migrations ORDER BY version",
+    ).all();
+  } catch {
+    throw new MigrationCompatibilityError();
+  }
+  if (rows.length !== migrations.length) throw new MigrationCompatibilityError();
+  for (let index = 0; index < migrations.length; index += 1) {
+    let applied: AppliedMigrationRow;
+    try {
+      applied = appliedMigrationRow(rows[index]!);
+    } catch {
+      throw new MigrationCompatibilityError();
+    }
+    const expected = migrations[index]!;
+    if (applied.version !== expected.version || applied.name !== expected.name ||
+        applied.checksum !== checksum(expected)) throw new MigrationCompatibilityError();
+  }
+}
+
 function validateMigrationOrder(migrations: readonly Migration[]): void {
   migrations.forEach((migration, index) => {
     if (migration.version !== index + 1 || migration.name.length === 0 || migration.sql.length === 0) {

package/src/operator-error.ts

@@ -5,6 +5,9 @@ export type OperatorErrorCode =
   | "START_HOST_MISSING"
   | "START_PORT_MISSING"
   | "START_PORT_INVALID"
+  | "START_LOG_LEVEL_DUPLICATE"
+  | "START_LOG_LEVEL_MISSING"
+  | "START_LOG_LEVEL_INVALID"
   | "START_OPTION_UNKNOWN"
   | "BIND_PORT_INVALID"
   | "BIND_HOST_INVALID"
@@ -13,6 +16,7 @@ export type OperatorErrorCode =
   | "BIND_LAN_CONSENT"
   | "SERVER_FILES_MISSING"
   | "DATA_PATH_SYMLINK"
+  | "INSTALLATION_EXISTS"
   | "LAN_CA_KEY_ONLINE"
   | "RUNTIME_ACTIVE"
   | "RUNTIME_LOCK_UNSAFE"
@@ -23,7 +27,13 @@ export type OperatorErrorCode =
   | "DISK_RESERVE_INVALID"
   | "CLIENT_NOT_FOUND"
   | "GRANT_NOT_FOUND"
-  | "RECOVERY_INVALID";
+  | "RECOVERY_INVALID"
+  | "INVITATION_BUSY"
+  | "INVITATION_CONTENTION"
+  | "INVITATION_SCHEMA_MISMATCH"
+  | "INVITATION_CUBE_NOT_FOUND"
+  | "INVITATION_CUBE_SELECTOR_INVALID"
+  | "INVITATION_CUBE_AMBIGUOUS";
 
 const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freeze({
   START_LAN_DUPLICATE: "Provide --lan only once.",
@@ -32,6 +42,9 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   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_LOG_LEVEL_DUPLICATE: "Provide --log-level only once.",
+  START_LOG_LEVEL_MISSING: "Provide debug after --log-level.",
+  START_LOG_LEVEL_INVALID: "Use --log-level debug or omit the option.",
   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.",
@@ -40,8 +53,9 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   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.",
+  INSTALLATION_EXISTS: "An installation already exists in BORG_SERVER_DATA_DIR. To destroy and recreate it, stop the server and run borg-mcp-server setup --reinitialize.",
   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_ACTIVE: "Stop the server before running setup or offline 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.",
@@ -51,22 +65,30 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   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.",
+  INVITATION_BUSY: "Confirm no invitation or offline administration command is running, then remove invitation-mint.lock.",
+  INVITATION_CONTENTION: "Retry invitation minting after the current server database write completes.",
+  INVITATION_SCHEMA_MISMATCH: "Invitation minting is unavailable while a server with an incompatible schema is running. Stop the server and rerun this command, or use the CLI version that matches the running server.",
+  INVITATION_CUBE_NOT_FOUND: "Provide an existing cube name or full cube ID.",
+  INVITATION_CUBE_SELECTOR_INVALID: "Provide a full canonical cube UUID or an exact case-sensitive cube name.",
+  INVITATION_CUBE_AMBIGUOUS: "Cube name is ambiguous. Rerun with the full cube ID.",
 });
 
 const operatorErrorCodes = new WeakMap<object, OperatorErrorCode>();
+const operatorErrorMessages = new WeakMap<object, string>();
 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.");
+  constructor(capability: object, code: OperatorErrorCode, publicMessage?: string) {
+    super(publicMessage ?? (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);
+    operatorErrorMessages.set(this, this.message);
     Object.freeze(this);
   }
 
@@ -75,7 +97,7 @@ class OperatorError extends Error {
   }
 
   get publicMessage(): string {
-    return publicMessages[this.#operatorCode];
+    return operatorErrorMessages.get(this) ?? publicMessages[this.#operatorCode];
   }
 }
 
@@ -93,5 +115,17 @@ export function operatorPublicMessage(error: unknown): string | 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];
+  return operatorErrorMessages.get(error) ?? publicMessages[code];
+}
+
+export function invitationCubeAmbiguousError(candidateIds: readonly string[]): Error {
+  if (candidateIds.length < 2 || candidateIds.some((id) =>
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(id))) {
+    throw new Error("Ambiguous cube candidates must contain canonical cube IDs.");
+  }
+  return new OperatorError(
+    operatorErrorCapability,
+    "INVITATION_CUBE_AMBIGUOUS",
+    `Cube name is ambiguous. Rerun with the full cube ID. Candidate cube IDs: ${candidateIds.join(", ")}`,
+  );
 }

package/src/role-section.ts

@@ -0,0 +1,108 @@
+export type RoleSectionPatchOp =
+  | { readonly action: "replace"; readonly heading: string; readonly body: string }
+  | {
+    readonly action: "insert";
+    readonly heading: string;
+    readonly body: string;
+    readonly after?: string | null;
+  }
+  | { readonly action: "delete"; readonly heading: string };
+
+interface RoleSection {
+  readonly heading: string | null;
+  readonly body: string;
+}
+
+export function patchRoleSectionText(text: string, operation: RoleSectionPatchOp): string {
+  validateHeading(operation.heading);
+  const sections = parseSections(text);
+  const target = normalizedHeading(operation.heading);
+  const index = sections.findIndex((section) =>
+    section.heading !== null && normalizedHeading(section.heading) === target
+  );
+
+  if (operation.action === "replace") {
+    if (index === -1) throw new Error("Role section not found.");
+    sections[index] = renderedSection(operation.heading, operation.body);
+    return serializeSections(sections);
+  }
+  if (operation.action === "delete") {
+    if (index === -1) throw new Error("Role section not found.");
+    sections.splice(index, 1);
+    return serializeSections(sections);
+  }
+  if (index !== -1) throw new Error("Role section already exists.");
+
+  const section = renderedSection(operation.heading, operation.body);
+  if (operation.after == null) {
+    ensureTrailingNewline(sections, sections.length - 1);
+    sections.push(section);
+    return serializeSections(sections);
+  }
+  validateHeading(operation.after);
+  const after = normalizedHeading(operation.after);
+  const afterIndex = sections.findIndex((candidate) =>
+    candidate.heading !== null && normalizedHeading(candidate.heading) === after
+  );
+  if (afterIndex === -1) throw new Error("Role section insertion point does not exist.");
+  ensureTrailingNewline(sections, afterIndex);
+  sections.splice(afterIndex + 1, 0, section);
+  return serializeSections(sections);
+}
+
+function parseSections(text: string): RoleSection[] {
+  const sections: RoleSection[] = [];
+  const lines = text.split("\n");
+  let heading: string | null = null;
+  let body = "";
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    const sourceLine = index < lines.length - 1 ? `${line}\n` : line;
+    if (isLabelLine(line)) {
+      sections.push({ heading, body });
+      heading = line.slice(0, -1).trim();
+      body = sourceLine;
+    } else {
+      body += sourceLine;
+    }
+  }
+  sections.push({ heading, body });
+  return sections;
+}
+
+function isLabelLine(line: string): boolean {
+  if (/^\s/u.test(line) || !line.endsWith(":")) return false;
+  const label = line.slice(0, -1);
+  return label.length > 0 && label.length <= 60 && !label.includes(":") &&
+    !/^[*\-#>`]/u.test(label);
+}
+
+function renderedSection(heading: string, body: string): RoleSection {
+  const normalizedBody = body === "" || body.endsWith("\n") ? body : `${body}\n`;
+  return {
+    heading: heading.trim(),
+    body: `${heading.trim()}:\n${normalizedBody}`,
+  };
+}
+
+function ensureTrailingNewline(sections: RoleSection[], index: number): void {
+  const section = sections[index];
+  if (section !== undefined && section.body !== "" && !section.body.endsWith("\n")) {
+    sections[index] = { ...section, body: `${section.body}\n` };
+  }
+}
+
+function serializeSections(sections: readonly RoleSection[]): string {
+  return sections.map((section) => section.body).join("");
+}
+
+function normalizedHeading(heading: string): string {
+  return heading.trim().toLowerCase();
+}
+
+function validateHeading(heading: string): void {
+  if (typeof heading !== "string" || /[\r\n]/u.test(heading) ||
+      !isLabelLine(`${heading.trim()}:`)) {
+    throw new TypeError("Role section heading is invalid.");
+  }
+}