borgmcp-server 0.1.1 → 0.1.5

package/src/service.ts

@@ -9,8 +9,14 @@ import {
   loadTlsPrivateKey,
   type BootstrapResult,
 } from "./bootstrap.js";
-import { CredentialAuthority, CredentialDigester } from "./credentials.js";
+import {
+  CredentialAuthority,
+  CredentialDigester,
+  type CubeInvitationResult,
+} from "./credentials.js";
 import { CoordinationApi } from "./coordination-api.js";
+import { createDebugLogger, disabledDebugLogger } from "./debug-log.js";
+import { MigrationCompatibilityError } from "./migrations.js";
 import { createEnrollmentExchange } from "./enrollment.js";
 import {
   DEFAULT_SERVICE_LIMITS,
@@ -18,24 +24,43 @@ import {
   type HttpsServerOptions,
   type RunningServer,
 } from "./https-server.js";
-import { createPart2ProtocolInfo } from "./protocol-draft.js";
 import { resolveBindOptions } from "./network-policy.js";
-import { operatorErrors, type OperatorErrorCode } from "./operator-error.js";
+import {
+  invitationCubeAmbiguousError,
+  operatorErrors,
+  type OperatorErrorCode,
+} from "./operator-error.js";
 import { parseStartOptions } from "./start-options.js";
-import { DEFAULT_STORAGE_LIMITS, openStore, type StorageLimits } from "./store.js";
+import {
+  DEFAULT_STORAGE_LIMITS,
+  openStore,
+  preparePrivateDataDirectory,
+  InvitationCubeAmbiguousError,
+  InvitationCubeNotFoundError,
+  type LivenessStore,
+  type StorageLimits,
+} from "./store.js";
 import type { CubeAccess } from "./store.js";
 
 export interface ServerService {
   readonly start: (args: readonly string[]) => Promise<void>;
-  readonly setup?: () => Promise<BootstrapResult>;
+  readonly setup?: (options: SetupOptions) => Promise<BootstrapResult>;
   readonly rotateClient?: (clientId: string) => Promise<string>;
   readonly revokeClient?: (clientId: string) => Promise<void>;
   readonly grantClient?: (clientId: string, cubeId: string, access: CubeAccess) => Promise<void>;
   readonly ungrantClient?: (clientId: string, cubeId: string) => Promise<void>;
-  readonly createClientInvitation?: (recoveryCredential: string) => Promise<string>;
+  readonly createClientInvitation?: (
+    recoveryCredential: string,
+    cubeSelector?: string,
+    access?: CubeAccess,
+  ) => Promise<string | CubeInvitationResult>;
   readonly replaceOwnerInvitation?: (recoveryCredential: string) => Promise<string>;
 }
 
+export interface SetupOptions {
+  readonly reinitialize: boolean;
+}
+
 export interface ServerEnvironment {
   readonly BORG_SERVER_TLS_KEY_FILE?: string;
   readonly BORG_SERVER_TLS_CERT_FILE?: string;
@@ -54,8 +79,12 @@ interface ServiceDependencies {
   readonly startServer: (options: HttpsServerOptions) => Promise<RunningServer>;
   readonly onStarted: (origin: string) => void;
   readonly waitForShutdown: (server: RunningServer, signal?: AbortSignal) => Promise<void>;
+  readonly debugOutput?: (line: string) => void;
   readonly installShutdownHandlers?: () => { readonly signal: AbortSignal; readonly dispose: () => void };
   readonly openStore?: typeof openStore;
+  readonly startLivenessScheduler?: (
+    liveness: LivenessStore,
+  ) => { readonly stop: () => void };
   readonly onStartupPhase?: (
     phase: "pre-lock" | "post-lock" | "pre-listen",
   ) => Promise<void>;
@@ -66,6 +95,7 @@ interface RuntimeResources {
   readonly authRuntime: Awaited<ReturnType<typeof openStore>> | undefined;
   readonly digester: CredentialDigester | undefined;
   readonly runtimeLock: RuntimeLock | undefined;
+  readonly livenessScheduler: { readonly stop: () => void } | undefined;
 }
 
 const guardedRuntimeFailures = new Set<RuntimeResources>();
@@ -91,17 +121,27 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
   return {
     async start(args): Promise<void> {
       const shutdown = dependencies.installShutdownHandlers?.();
-      let bind: ReturnType<typeof parseStartOptions>;
+      let bind: ReturnType<typeof parseStartOptions>["bind"];
+      let debugLogger = disabledDebugLogger;
       let dataDirectory: string | undefined;
       let storageLimits: StorageLimits;
       try {
         throwIfShutdown(shutdown?.signal);
         await dependencies.onStartupPhase?.("pre-lock");
         throwIfShutdown(shutdown?.signal);
-        bind = parseStartOptions(args);
-        const bindMode = resolveBindOptions(bind).mode;
+        const parsed = parseStartOptions(args);
+        bind = parsed.bind;
+        debugLogger = createDebugLogger(parsed.logLevel === "debug" ? dependencies.debugOutput : undefined);
+        const resolvedBind = resolveBindOptions(bind);
+        const bindMode = resolvedBind.mode;
         dataDirectory = dependencies.environment.BORG_SERVER_DATA_DIR;
         storageLimits = resolveStorageLimits(dependencies.environment);
+        debugLogger.emit({
+          event: "startup",
+          bindMode,
+          port: resolvedBind.port,
+          dataDirectory: dataDirectory === undefined ? "tls_only" : "configured",
+        });
         if (bindMode === "lan" && dataDirectory !== undefined) {
           await assertLanCaKeyOffline(dataDirectory);
           throwIfShutdown(shutdown?.signal);
@@ -124,7 +164,7 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
 
       let runtimeLock: Awaited<ReturnType<typeof acquireRuntimeLock>> | undefined;
       try {
-        runtimeLock = dataDirectory === undefined ? undefined : await acquireRuntimeLock(dataDirectory);
+        runtimeLock = dataDirectory === undefined ? undefined : await acquireRuntimeLock(dataDirectory, "server");
         await dependencies.onStartupPhase?.("post-lock");
         throwIfShutdown(shutdown?.signal);
       } catch (error) {
@@ -134,6 +174,7 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
         throw error;
       }
       let running: RunningServer | undefined;
+      let livenessScheduler: { readonly stop: () => void } | undefined;
       let key: Buffer | undefined;
       try {
         throwIfShutdown(shutdown?.signal);
@@ -169,8 +210,14 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
           } finally {
             digestKey.fill(0);
           }
-          authority = new CredentialAuthority(authRuntime.credentials, digester);
-          coordinationApi = new CoordinationApi(authRuntime, authority);
+          authority = new CredentialAuthority(
+            authRuntime.credentials,
+            digester,
+            () => new Date(),
+            undefined,
+            debugLogger,
+          );
+          coordinationApi = new CoordinationApi(authRuntime, authority, debugLogger);
         }
         await dependencies.onStartupPhase?.("pre-listen");
         throwIfShutdown(shutdown?.signal);
@@ -178,12 +225,6 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
           bind,
           tls: { key, cert, ...(ca === undefined ? {} : { ca }) },
           limits: DEFAULT_SERVICE_LIMITS,
-          protocolInfo: createPart2ProtocolInfo(DEFAULT_SERVICE_LIMITS),
-          authorizeProtocol: async (authorization) => {
-            if (authority === undefined) return false;
-            const result = authority.authenticateStatus(authorization);
-            return typeof result === "object" ? true : result;
-          },
           ...(authority === undefined
             ? {}
             : { exchangeEnrollment: createEnrollmentExchange(authority) }),
@@ -197,11 +238,17 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
           ...(coordinationApi === undefined
             ? {}
             : { handleCoordination: (request) => coordinationApi.handle(request) }),
+          debugLogger,
         });
         throwIfShutdown(shutdown?.signal);
+        if (authRuntime !== undefined) {
+          livenessScheduler = (dependencies.startLivenessScheduler ?? startLivenessScheduler)(
+            authRuntime.liveness,
+          );
+        }
       } catch (error) {
         try {
-          await teardownRuntime({ running, authRuntime, digester, runtimeLock });
+          await teardownRuntime({ running, authRuntime, digester, runtimeLock, livenessScheduler });
         } catch (cleanupError) {
           shutdown?.dispose();
           throw fatalTeardownError(error, cleanupError);
@@ -217,13 +264,15 @@ export function createNodeServerService(dependencies: ServiceDependencies): Serv
       try {
         throwIfShutdown(shutdown?.signal);
         dependencies.onStarted(running.origin);
+        debugLogger.emit({ event: "lifecycle", action: "listening" });
         await dependencies.waitForShutdown(running, shutdown?.signal);
       } catch (error) {
         failed = true;
         failure = error;
       }
       try {
-        await teardownRuntime({ running, authRuntime, digester, runtimeLock });
+        await teardownRuntime({ running, authRuntime, digester, runtimeLock, livenessScheduler });
+        debugLogger.emit({ event: "lifecycle", action: "stopped" });
       } catch (cleanupError) {
         shutdown?.dispose();
         throw fatalTeardownError(failed ? failure : undefined, cleanupError);
@@ -329,13 +378,69 @@ const startOnlyService = createNodeServerService({
     return handlers;
   },
   waitForShutdown,
+  debugOutput: (line) => console.error(line),
 });
 export const nodeServerService: ServerService = {
   start: startOnlyService.start,
-  setup: () => bootstrapServer(dataDirectory, resolveSetupBindHost(serverEnvironment)),
+  setup: (options) => setupNodeServerInstallation(
+    dataDirectory,
+    resolveSetupBindHost(serverEnvironment),
+    options,
+  ),
   ...createOfflineCredentialService(dataDirectory),
 };
 
+const managedInstallationFiles = Object.freeze([
+  "borg.db",
+  "borg.db-wal",
+  "borg.db-shm",
+  "borg.db-journal",
+  "credential-digest.key",
+  "ca.key",
+  "ca.crt",
+  "server.key",
+  "server.crt",
+  "server.json",
+]);
+
+export async function setupNodeServerInstallation(
+  setupDataDirectory: string,
+  bindHost: string,
+  options: SetupOptions,
+): Promise<BootstrapResult> {
+  const directory = await preparePrivateDataDirectory(setupDataDirectory);
+  const runtimeLock = await acquireRuntimeLock(directory);
+  let invitationLock: RuntimeLock | undefined;
+  try {
+    invitationLock = await acquireInvitationMintLock(directory);
+    const existing = await inspectManagedInstallation(directory);
+    if (existing.length !== 0 && !options.reinitialize) throw operatorErrors.INSTALLATION_EXISTS;
+    if (options.reinitialize) {
+      for (const path of existing) await unlink(path);
+    }
+    return await bootstrapServer(directory, bindHost);
+  } finally {
+    if (invitationLock === undefined) await runtimeLock.release();
+    else await invitationLock.release().finally(() => runtimeLock.release());
+  }
+}
+
+async function inspectManagedInstallation(directory: string): Promise<string[]> {
+  const existing: string[] = [];
+  for (const name of managedInstallationFiles) {
+    const path = join(directory, name);
+    try {
+      const metadata = await lstat(path);
+      if (metadata.isSymbolicLink()) throw operatorErrors.DATA_PATH_SYMLINK;
+      if (!metadata.isFile()) throw new Error("Managed installation paths must be regular files.");
+      existing.push(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+  return existing;
+}
+
 function resolveSetupBindHost(environment: ServerEnvironment): string {
   return resolveBindOptions({
     ...(environment.BORG_SERVER_BIND_HOST === undefined
@@ -356,9 +461,11 @@ export function createOfflineCredentialService(
     runtime: Awaited<ReturnType<typeof openStore>>,
   ) => T): Promise<T> => {
     const runtimeLock = await acquireRuntimeLock(offlineDataDirectory);
+    let invitationLock: RuntimeLock | undefined;
     let runtime: Awaited<ReturnType<typeof openStore>> | undefined;
     let digester: CredentialDigester | undefined;
     try {
+      invitationLock = await acquireInvitationMintLock(offlineDataDirectory);
       runtime = await openStore({ path: join(offlineDataDirectory, "borg.db") });
       const digestKey = await loadDigestKey(join(offlineDataDirectory, "credential-digest.key"));
       digester = new CredentialDigester(digestKey);
@@ -367,7 +474,35 @@ export function createOfflineCredentialService(
     } finally {
       digester?.destroy();
       runtime?.close();
-      await runtimeLock.release();
+      if (invitationLock === undefined) await runtimeLock.release();
+      else await invitationLock.release().finally(() => runtimeLock.release());
+    }
+  };
+  const withInvitationAuthority = async <T>(operation: (authority: CredentialAuthority) => T): Promise<T> => {
+    const invitationLock = await acquireInvitationMintLock(offlineDataDirectory);
+    let offlineRuntimeLock: RuntimeLock | undefined;
+    let runtime: Awaited<ReturnType<typeof openStore>> | undefined;
+    let digester: CredentialDigester | undefined;
+    try {
+      const runtimeState = await invitationRuntimeState(offlineDataDirectory);
+      if (runtimeState === "offline") offlineRuntimeLock = await acquireRuntimeLock(offlineDataDirectory);
+      runtime = await openStore({
+        path: join(offlineDataDirectory, "borg.db"),
+        migrationMode: runtimeState === "live" ? "require-current" : "apply",
+      });
+      const digestKey = await loadDigestKey(join(offlineDataDirectory, "credential-digest.key"));
+      digester = new CredentialDigester(digestKey);
+      digestKey.fill(0);
+      return operation(new CredentialAuthority(runtime.credentials, digester));
+    } catch (error) {
+      if (error instanceof MigrationCompatibilityError) throw operatorErrors.INVITATION_SCHEMA_MISMATCH;
+      if (isSqliteContention(error)) throw operatorErrors.INVITATION_CONTENTION;
+      throw error;
+    } finally {
+      digester?.destroy();
+      runtime?.close();
+      if (offlineRuntimeLock === undefined) await invitationLock.release();
+      else await offlineRuntimeLock.release().finally(() => invitationLock.release());
     }
   };
   return {
@@ -385,12 +520,24 @@ export function createOfflineCredentialService(
         throw operatorErrors.GRANT_NOT_FOUND;
       }
     }),
-    createClientInvitation: (recoveryCredential) => withAuthority((authority) => {
-      const invitation = authority.createInvitation(recoveryCredential, 15 * 60_000);
+    createClientInvitation: (recoveryCredential, cubeSelector, access) => withInvitationAuthority((authority) => {
+      if (cubeSelector === undefined && access !== undefined) {
+        throw operatorErrors.INVITATION_CUBE_SELECTOR_INVALID;
+      }
+      const selector = cubeSelector === undefined ? undefined : parseInvitationCubeSelector(cubeSelector);
+      const invitation = selector === undefined
+        ? authority.createInvitation(recoveryCredential, 15 * 60_000)
+        : authority.createCubeInvitation(recoveryCredential, selector, access ?? "write", 15 * 60_000);
       if (invitation === null) throw operatorErrors.RECOVERY_INVALID;
       return invitation;
+    }).catch((error: unknown) => {
+      if (error instanceof InvitationCubeNotFoundError) throw operatorErrors.INVITATION_CUBE_NOT_FOUND;
+      if (error instanceof InvitationCubeAmbiguousError) {
+        throw invitationCubeAmbiguousError(error.candidateIds);
+      }
+      throw error;
     }),
-    replaceOwnerInvitation: (recoveryCredential) => withAuthority((authority) => {
+    replaceOwnerInvitation: (recoveryCredential) => withInvitationAuthority((authority) => {
       const invitation = authority.replaceOwnerInvitation(recoveryCredential, 15 * 60_000);
       if (invitation === null) throw operatorErrors.RECOVERY_INVALID;
       return invitation;
@@ -398,11 +545,25 @@ export function createOfflineCredentialService(
   };
 }
 
+const canonicalCubeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const uuidLikeCubeSelector = /^[0-9a-fA-F-]{32,36}$/u;
+
+function parseInvitationCubeSelector(
+  value: string,
+): { readonly kind: "id" | "name"; readonly value: string } {
+  if (canonicalCubeUuid.test(value)) return { kind: "id", value };
+  if (value.length === 0 || value.length > 120 || uuidLikeCubeSelector.test(value)) {
+    throw operatorErrors.INVITATION_CUBE_SELECTOR_INVALID;
+  }
+  return { kind: "name", value };
+}
+
 interface RuntimeLock {
   readonly release: () => Promise<void>;
 }
 
 async function teardownRuntime(resources: RuntimeResources): Promise<void> {
+  resources.livenessScheduler?.stop();
   try {
     await resources.running?.close();
   } catch (error) {
@@ -419,6 +580,21 @@ async function teardownRuntime(resources: RuntimeResources): Promise<void> {
   await resources.runtimeLock?.release();
 }
 
+function startLivenessScheduler(liveness: { readonly scan: () => unknown }): { readonly stop: () => void } {
+  let stopped = false;
+  let timer: NodeJS.Timeout;
+  const schedule = (): void => {
+    timer = setTimeout(() => {
+      if (stopped) return;
+      try { liveness.scan(); } catch { /* Retry on the next bounded tick. */ }
+      schedule();
+    }, 60_000);
+    timer.unref();
+  };
+  schedule();
+  return { stop: () => { stopped = true; clearTimeout(timer); } };
+}
+
 const fatalTeardownErrors = new WeakSet<object>();
 const fatalTeardownCapability = Object.freeze({});
 
@@ -445,13 +621,16 @@ function fatalTeardownError(primary: unknown, cleanup: unknown): FatalTeardownEr
   return new FatalTeardownError(fatalTeardownCapability, primary, cleanup);
 }
 
-export async function acquireRuntimeLock(runtimeDataDirectory: string): Promise<RuntimeLock> {
+export async function acquireRuntimeLock(
+  runtimeDataDirectory: string,
+  purpose: "server" | "exclusive-admin" = "exclusive-admin",
+): Promise<RuntimeLock> {
   const path = join(runtimeDataDirectory, "runtime.lock");
   const nonce = randomUUID();
   try {
     const handle = await open(path, "wx", 0o600);
     try {
-      await handle.writeFile(JSON.stringify({ pid: process.pid, nonce }));
+      await handle.writeFile(JSON.stringify({ pid: process.pid, nonce, purpose }));
     } catch (error) {
       await handle.close();
       await unlink(path).catch(() => undefined);
@@ -487,6 +666,68 @@ export async function acquireRuntimeLock(runtimeDataDirectory: string): Promise<
   }
 }
 
+export async function acquireInvitationMintLock(runtimeDataDirectory: string): Promise<RuntimeLock> {
+  const path = join(runtimeDataDirectory, "invitation-mint.lock");
+  const nonce = randomUUID();
+  try {
+    const handle = await open(path, "wx", 0o600);
+    try {
+      await handle.writeFile(JSON.stringify({ pid: process.pid, nonce }));
+    } catch (error) {
+      await handle.close();
+      await unlink(path).catch(() => undefined);
+      throw error;
+    }
+    return {
+      release: async () => {
+        await handle.close();
+        try {
+          const current = JSON.parse(await readFile(path, "utf8")) as { nonce?: unknown };
+          if (current.nonce === nonce) await unlink(path);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        }
+      },
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    throw operatorErrors.INVITATION_BUSY;
+  }
+}
+
+async function invitationRuntimeState(runtimeDataDirectory: string): Promise<"live" | "offline"> {
+  const path = join(runtimeDataDirectory, "runtime.lock");
+  let metadata;
+  try {
+    metadata = await lstat(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "offline";
+    throw error;
+  }
+  if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
+    throw operatorErrors.RUNTIME_LOCK_UNSAFE;
+  }
+  let pid: number;
+  let purpose: unknown;
+  try {
+    const value = JSON.parse(await readFile(path, "utf8")) as { pid?: unknown; purpose?: unknown };
+    if (!Number.isSafeInteger(value.pid) || (value.pid as number) <= 0) throw new Error();
+    pid = value.pid as number;
+    purpose = value.purpose;
+  } catch {
+    throw operatorErrors.RUNTIME_LOCK_INVALID;
+  }
+  if (!processIsAlive(pid)) throw operatorErrors.RUNTIME_LOCK_STALE;
+  if (purpose !== "server") throw operatorErrors.RUNTIME_ACTIVE;
+  return "live";
+}
+
+function isSqliteContention(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const value = error as { code?: unknown; errcode?: unknown };
+  return value.code === "ERR_SQLITE_ERROR" && (value.errcode === 5 || value.errcode === 6);
+}
+
 function processIsAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);

package/src/start-options.ts

@@ -1,10 +1,16 @@
 import type { BindOptionsInput } from "./network-policy.js";
 import { operatorErrors, type OperatorErrorCode } from "./operator-error.js";
 
-export function parseStartOptions(args: readonly string[]): BindOptionsInput {
+export interface ParsedStartOptions {
+  readonly bind: BindOptionsInput;
+  readonly logLevel?: "debug";
+}
+
+export function parseStartOptions(args: readonly string[]): ParsedStartOptions {
   let host: string | undefined;
   let port: number | undefined;
   let lanConsent = false;
+  let logLevel: "debug" | undefined;
 
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
@@ -27,13 +33,24 @@ export function parseStartOptions(args: readonly string[]): BindOptionsInput {
       index += 1;
       continue;
     }
+    if (argument === "--log-level") {
+      if (logLevel !== undefined) throw operatorErrors.START_LOG_LEVEL_DUPLICATE;
+      const value = requiredValue(args, index, "START_LOG_LEVEL_MISSING");
+      if (value !== "debug") throw operatorErrors.START_LOG_LEVEL_INVALID;
+      logLevel = value;
+      index += 1;
+      continue;
+    }
     throw operatorErrors.START_OPTION_UNKNOWN;
   }
 
   return {
-    ...(host === undefined ? {} : { host }),
-    ...(port === undefined ? {} : { port }),
-    ...(lanConsent ? { lanConsent: true } : {}),
+    bind: {
+      ...(host === undefined ? {} : { host }),
+      ...(port === undefined ? {} : { port }),
+      ...(lanConsent ? { lanConsent: true } : {}),
+    },
+    ...(logLevel === undefined ? {} : { logLevel }),
   };
 }