borgmcp 2.0.2 → 2.0.3

package/src/seat-store.ts

@@ -13,7 +13,9 @@
  *   2. ATOMIC RENAME — temp in the SAME dir/fs, created 0600, fsync THEN rename;
  *      a crash never leaves a torn/readable partial, and the temp is cleaned up
  *      on any write failure.
- *   3. PARENT DIR 0700 — created with mode 0700.
+ *   3. PARENT DIR — private stores require 0700. The canonical ~/.borg parent
+ *      may explicitly use the owner-controlled policy (0755 accepted, 0022
+ *      forbidden) without rewriting its established mode.
  *   4. flock DISCIPLINE — a single advisory lock (O_EXCL lockfile), RULED option
  *      (b) (Coordinator cca6957a): NO automatic reclaim, EVER. Acquire is an atomic
  *      `open(lockPath,'wx',0o600)`; the whole read-compare-write runs inside ONE
@@ -29,8 +31,9 @@
  * callers keeps the raw bearer from leaving the store owner.
  */
 
-import { open, link, mkdir, readFile, rename, stat, unlink } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { constants } from 'node:fs';
+import { open, link, lstat, mkdir, readFile, realpath, rename, stat, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 const LOCK_WAIT_MS = 10;
@@ -42,6 +45,78 @@ interface LockPayload {
   startTime: string;
 }
 
+export interface SecureStoreOptions {
+  secureRoot?: string;
+  rootMode?: 'private' | 'owner-controlled';
+}
+
+function expectedUid(): number | null {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+async function assertSecureRoot(
+  root: string,
+  rootMode: SecureStoreOptions['rootMode'] = 'private',
+): Promise<void> {
+  if (!isAbsolute(root) || resolve(root) !== root) {
+    throw new Error(`Borg credential store path ${root} is not canonical`);
+  }
+  let metadata: Awaited<ReturnType<typeof lstat>>;
+  try {
+    metadata = await lstat(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    metadata = await lstat(root);
+  }
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    throw new Error(`Borg credential store root ${root} must be a real directory, not a symlink`);
+  }
+  const mode = metadata.mode & 0o777;
+  if (rootMode === 'private' ? mode !== 0o700 : (mode & 0o022) !== 0) {
+    throw new Error(
+      `Borg credential store root ${root} has insecure permissions; ` +
+      (rootMode === 'private' ? 'expected 0700' : 'group/world write access is forbidden'),
+    );
+  }
+  const uid = expectedUid();
+  if (uid !== null && metadata.uid !== uid) {
+    throw new Error(`Borg credential store root ${root} is not owned by the current user`);
+  }
+  if (await realpath(root) !== root) {
+    throw new Error(`Borg credential store root ${root} is not canonical or contains a symlink`);
+  }
+}
+
+async function assertSecureFile(filePath: string): Promise<Awaited<ReturnType<typeof lstat>> | null> {
+  let metadata: Awaited<ReturnType<typeof lstat>>;
+  try {
+    metadata = await lstat(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    throw new Error(`Borg credential store file ${filePath} must be a regular file, not a symlink`);
+  }
+  if ((metadata.mode & 0o777) !== 0o600) {
+    throw new Error(`Borg credential store file ${filePath} has insecure permissions; expected 0600`);
+  }
+  const uid = expectedUid();
+  if (uid !== null && metadata.uid !== uid) {
+    throw new Error(`Borg credential store file ${filePath} is not owned by the current user`);
+  }
+  return metadata;
+}
+
+async function assertSecurePath(filePath: string, options: SecureStoreOptions): Promise<void> {
+  const secureRoot = options.secureRoot!;
+  if (!isAbsolute(filePath) || resolve(filePath) !== filePath || dirname(filePath) !== secureRoot) {
+    throw new Error(`Borg credential store file path ${filePath} is not canonical`);
+  }
+  await assertSecureRoot(secureRoot, options.rootMode);
+}
+
 /**
  * Liveness check for the alive/dead branch (RULED option b). `process.kill(pid, 0)`
  * sends no signal but validates the target: ESRCH ⇒ no such process (DEAD → fail
@@ -103,20 +178,30 @@ function staleLockError(lockPath: string, held: LockPayload | null): Error {
  * beneath it.
  */
 async function ensureParentDir(filePath: string): Promise<void> {
+  if (!isAbsolute(filePath) || resolve(filePath) !== filePath) {
+    throw new Error(`Borg store file path ${filePath} is not canonical`);
+  }
   const dir = dirname(filePath);
-  let existing: Awaited<ReturnType<typeof stat>> | null = null;
+  let existing: Awaited<ReturnType<typeof lstat>> | null = null;
   try {
-    existing = await stat(dir);
+    existing = await lstat(dir);
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
   }
   if (existing) {
+    if (existing.isSymbolicLink() || !existing.isDirectory()) {
+      throw new Error(`Borg store directory ${dir} must be a real directory, not a symlink`);
+    }
     if ((existing.mode & 0o777) !== 0o700) {
       throw new Error(
         `Borg store directory ${dir} has insecure permissions ` +
           `(0${(existing.mode & 0o777).toString(8)}, expected 0700); refusing to write a credential under it`,
       );
     }
+    const uid = expectedUid();
+    if (uid !== null && existing.uid !== uid) {
+      throw new Error(`Borg store directory ${dir} is not owned by the current user`);
+    }
     return;
   }
   await mkdir(dir, { recursive: true, mode: 0o700 });
@@ -128,8 +213,14 @@ async function ensureParentDir(filePath: string): Promise<void> {
  * rename over the target (atomic; the mode carries across). A failed write
  * cleans up the temp so no leftover file ever holds the secret.
  */
-export async function atomicWrite0600(filePath: string, data: string): Promise<void> {
-  await ensureParentDir(filePath);
+export async function atomicWrite0600(
+  filePath: string,
+  data: string,
+  options: SecureStoreOptions = {},
+): Promise<void> {
+  if (options.secureRoot) await assertSecurePath(filePath, options);
+  else await ensureParentDir(filePath);
+  if (options.secureRoot) await assertSecureFile(filePath);
   const tmp = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
   const handle = await open(tmp, 'wx', 0o600);
   try {
@@ -142,6 +233,10 @@ export async function atomicWrite0600(filePath: string, data: string): Promise<v
   }
   await handle.close();
   try {
+    if (options.secureRoot) {
+      await assertSecurePath(filePath, options);
+      await assertSecureFile(filePath);
+    }
     await rename(tmp, filePath);
   } catch (err) {
     await unlink(tmp).catch(() => {});
@@ -187,14 +282,53 @@ async function assertSecureStorePerms(
  * perms are enforced BEFORE the bytes are read (CR#2) — a loosely-permissioned
  * secret fails closed and is never read.
  */
-export async function readStoreFile(filePath: string): Promise<string | null> {
-  let fileStat: Awaited<ReturnType<typeof stat>>;
+export async function readStoreFile(
+  filePath: string,
+  options: SecureStoreOptions = {},
+): Promise<string | null> {
+  if (!isAbsolute(filePath) || resolve(filePath) !== filePath) {
+    throw new Error(`Borg store file path ${filePath} is not canonical`);
+  }
+  if (options.secureRoot) await assertSecurePath(filePath, options);
+  if (options.secureRoot) {
+    const before = await assertSecureFile(filePath);
+    if (!before) return null;
+    let handle;
+    try {
+      handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw error;
+    }
+    try {
+      const opened = await handle.stat();
+      if (opened.dev !== before.dev || opened.ino !== before.ino) {
+        throw new Error('Borg credential store file changed while it was being opened');
+      }
+      const raw = await handle.readFile('utf8');
+      const after = await handle.stat();
+      if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size) {
+        throw new Error('Borg credential store file changed while it was being read');
+      }
+      return raw;
+    } finally {
+      await handle.close();
+    }
+  }
+  let fileStat: Awaited<ReturnType<typeof lstat>>;
   try {
-    fileStat = await stat(filePath);
+    fileStat = await lstat(filePath);
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
     throw err;
   }
+  if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+    throw new Error(`Borg store file ${filePath} must be a regular file, not a symlink`);
+  }
+  const uid = expectedUid();
+  if (uid !== null && fileStat.uid !== uid) {
+    throw new Error(`Borg store file ${filePath} is not owned by the current user`);
+  }
   await assertSecureStorePerms(filePath, fileStat.mode);
   try {
     return await readFile(filePath, 'utf8');
@@ -220,11 +354,12 @@ export async function readStoreFile(filePath: string): Promise<string | null> {
 export async function withStoreLock<T>(
   lockPath: string,
   op: () => Promise<T>,
-  opts: { attempts?: number; waitMs?: number } = {},
+  opts: { attempts?: number; waitMs?: number } & SecureStoreOptions = {},
 ): Promise<T> {
   const attempts = opts.attempts ?? LOCK_ATTEMPTS;
   const waitMs = opts.waitMs ?? LOCK_WAIT_MS;
-  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  if (opts.secureRoot) await assertSecurePath(lockPath, opts);
+  else await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
   const myPayload = JSON.stringify({ pid: process.pid, startTime: processStartTime() });
   // Stage the FULLY-WRITTEN payload in a same-dir temp, then acquire by atomically
   // hard-linking it into place. `link` is atomic (EEXIST when the lock is held), and
@@ -248,7 +383,14 @@ export async function withStoreLock<T>(
         // The lock is held. Inspect the holder — but NEVER reclaim/steal it.
         let raw: string;
         try {
-          raw = await readFile(lockPath, 'utf8');
+          const stored = await readStoreFile(
+            lockPath,
+            opts.secureRoot
+              ? { secureRoot: opts.secureRoot, rootMode: opts.rootMode }
+              : {},
+          );
+          if (stored === null) continue;
+          raw = stored;
         } catch (readErr) {
           if ((readErr as NodeJS.ErrnoException).code === 'ENOENT') continue; // released — retry
           throw readErr;
@@ -298,9 +440,10 @@ export async function withStore<S, T>(
   emptyState: () => S,
   parse: (raw: string) => S | null,
   op: (txn: StoreTxn<S>) => Promise<T>,
+  options: SecureStoreOptions = {},
 ): Promise<T> {
   return withStoreLock(`${storePath}.lock`, async () => {
-    const raw = await readStoreFile(storePath);
+    const raw = await readStoreFile(storePath, options);
     // CR4 fail-closed: ONLY a missing file (ENOENT → readStoreFile returns null)
     // may initialize an empty state. A present-but-malformed / wrong-version /
     // schema-invalid store must NEVER be silently mapped to empty and then
@@ -326,8 +469,8 @@ export async function withStore<S, T>(
     }
     const txn: StoreTxn<S> = {
       data,
-      commit: () => atomicWrite0600(storePath, JSON.stringify(data, null, 2) + '\n'),
+      commit: () => atomicWrite0600(storePath, JSON.stringify(data, null, 2) + '\n', options),
     };
     return op(txn);
-  });
+  }, options);
 }

package/src/server-facade.ts

@@ -0,0 +1,192 @@
+import { spawn as spawnChild, type SpawnOptions } from 'node:child_process';
+import { constants } from 'node:os';
+import { serverHelpText } from './cli-help.js';
+
+export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'status', 'update', 'invite'] as const;
+export type ServerLifecycleCommand = typeof SERVER_LIFECYCLE_COMMANDS[number];
+
+export type ParsedServerFacadeArgs =
+  | { kind: 'help' }
+  | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
+  | { kind: 'error'; reason: 'unknown-command'; command: string };
+
+export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFacadeArgs {
+  const [command, ...rest] = args;
+  if (command === undefined || command === '--help' || command === '-h') {
+    return { kind: 'help' };
+  }
+  if (!(SERVER_LIFECYCLE_COMMANDS as readonly string[]).includes(command)) {
+    return { kind: 'error', reason: 'unknown-command', command };
+  }
+  return {
+    kind: 'command',
+    command: command as ServerLifecycleCommand,
+    args: rest,
+  };
+}
+
+interface ServerFacadeChild {
+  once(event: 'error', listener: (error: Error) => void): this;
+  once(
+    event: 'exit',
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+  ): this;
+  kill(signal: NodeJS.Signals): boolean;
+}
+
+export interface ServerFacadeProcessDeps {
+  spawn(
+    command: string,
+    args: readonly string[],
+    options: Pick<SpawnOptions, 'shell' | 'stdio'>,
+  ): ServerFacadeChild;
+  addSignalListener(signal: NodeJS.Signals, listener: () => void): void;
+  removeSignalListener(signal: NodeJS.Signals, listener: () => void): void;
+}
+
+export interface ServerFacadeOutputDeps {
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+}
+
+export type ServerFacadeProcessResult =
+  | { kind: 'exited'; code: number }
+  | { kind: 'signaled'; signal: NodeJS.Signals }
+  | { kind: 'spawn-error'; error: Error };
+
+const defaultProcessDeps: ServerFacadeProcessDeps = {
+  spawn: (command, args, options) => spawnChild(command, [...args], options),
+  addSignalListener: (signal, listener) => process.on(signal, listener),
+  removeSignalListener: (signal, listener) => process.off(signal, listener),
+};
+
+const defaultOutputDeps: ServerFacadeOutputDeps = {
+  writeStdout: (text) => process.stdout.write(text),
+  writeStderr: (text) => process.stderr.write(text),
+};
+
+const MAX_RENDERED_COMMAND_CODE_POINTS = 80;
+
+function inertCommand(command: string): string {
+  const rendered: string[] = [];
+  let truncated = false;
+  for (const codePoint of command) {
+    if (rendered.length === MAX_RENDERED_COMMAND_CODE_POINTS) {
+      truncated = true;
+      break;
+    }
+    rendered.push(/\p{Cc}/u.test(codePoint) ? '?' : codePoint);
+  }
+  if (truncated) {
+    return `${rendered.slice(0, MAX_RENDERED_COMMAND_CODE_POINTS - 3).join('')}...`;
+  }
+  return rendered.join('');
+}
+
+export function unknownServerCommandText(command: string): string {
+  return (
+    `Unknown server command: ${inertCommand(command)}.\n` +
+    `Available commands: setup, start, status, update, invite.\n` +
+    `Next: run borg server --help.\n`
+  );
+}
+
+export function missingServerExecutableText(command: ServerLifecycleCommand): string {
+  return (
+    `Local server command is unavailable: borg-mcp-server was not found.\n` +
+    `Next: install a verified borgmcp-server release, then rerun borg server ${command}.\n` +
+    `No checkout fallback is attempted.\n`
+  );
+}
+
+export function serverCommandStartupFailureText(command: ServerLifecycleCommand): string {
+  return (
+    `Local server command could not be started.\n` +
+    `Next: check local permissions and system resources, then rerun borg server ${inertCommand(command)}.\n` +
+    `No server command was started.\n`
+  );
+}
+
+function isMissingServerExecutable(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+export function runServerFacadeProcess(
+  input: { command: ServerLifecycleCommand; args: readonly string[] },
+  deps: ServerFacadeProcessDeps = defaultProcessDeps,
+): Promise<ServerFacadeProcessResult> {
+  const child = deps.spawn(
+    'borg-mcp-server',
+    [input.command, ...input.args],
+    { shell: false, stdio: 'inherit' },
+  );
+  const signals = ['SIGINT', 'SIGTERM'] as const;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const forwarders = new Map<NodeJS.Signals, () => void>();
+    const cleanup = () => {
+      for (const [signal, listener] of forwarders) {
+        deps.removeSignalListener(signal, listener);
+      }
+      forwarders.clear();
+    };
+    const settle = (result: ServerFacadeProcessResult) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    for (const signal of signals) {
+      const listener = () => {
+        child.kill(signal);
+      };
+      forwarders.set(signal, listener);
+      deps.addSignalListener(signal, listener);
+    }
+
+    child.once('error', (error) => settle({ kind: 'spawn-error', error }));
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        settle({ kind: 'signaled', signal });
+        return;
+      }
+      settle({ kind: 'exited', code: code ?? 1 });
+    });
+  });
+}
+
+function processResultExitCode(result: ServerFacadeProcessResult): number {
+  if (result.kind === 'exited') return result.code;
+  if (result.kind === 'spawn-error') return isMissingServerExecutable(result.error) ? 127 : 1;
+  return 128 + (constants.signals[result.signal] ?? 1);
+}
+
+/** Routes every facade outcome before client initialization or network work. */
+export async function runEarlyServerFacade(
+  argv: readonly string[],
+  deps: ServerFacadeProcessDeps = defaultProcessDeps,
+  output: ServerFacadeOutputDeps = defaultOutputDeps,
+): Promise<number | null> {
+  if (argv[2] !== 'server') return null;
+  const parsed = parseServerFacadeArgs(argv.slice(3));
+  if (parsed.kind === 'help') {
+    output.writeStdout(serverHelpText());
+    return 0;
+  }
+  if (parsed.kind === 'error') {
+    output.writeStderr(unknownServerCommandText(parsed.command));
+    return 1;
+  }
+
+  const result = await runServerFacadeProcess(parsed, deps);
+  if (result.kind === 'spawn-error') {
+    output.writeStderr(
+      isMissingServerExecutable(result.error)
+        ? missingServerExecutableText(parsed.command)
+        : serverCommandStartupFailureText(parsed.command),
+    );
+  }
+  return processResultExitCode(result);
+}

package/src/token-store.ts

@@ -7,7 +7,8 @@
  * private keys; there is no keychain and no obfuscation-grade fallback.
  */
 
-import { atomicWrite0600, readStoreFile } from './seat-store.js';
+import { atomicWrite0600, readStoreFile, type SecureStoreOptions } from './seat-store.js';
+import { dirname } from 'node:path';
 
 // The OS-keychain backend was retired with the Queen rescope; the only backend
 // name is the 0600 file store.
@@ -37,9 +38,13 @@ export interface TokenBackend {
  * lockfile. Pure reads (get) are safe lock-free because atomicWrite0600's rename
  * guarantees a reader only ever sees a complete file.
  */
-export function makeFileBackend(filePath: string): TokenBackend {
+export function makeFileBackend(
+  filePath: string,
+  storeOptions: SecureStoreOptions = {},
+): TokenBackend {
+  const options = { secureRoot: dirname(filePath), ...storeOptions };
   const load = async (): Promise<Record<string, string>> => {
-    const raw = await readStoreFile(filePath);
+    const raw = await readStoreFile(filePath, options);
     // CR4 fail-closed: ONLY a missing file initializes empty. A present-but-
     // malformed / wrong-version / schema-invalid credential store MUST NOT read as
     // empty — a subsequent set/delete would OVERWRITE it and erase every stored
@@ -79,7 +84,7 @@ export function makeFileBackend(filePath: string): TokenBackend {
     return { ...(accounts as Record<string, string>) };
   };
   const save = (accounts: Record<string, string>): Promise<void> =>
-    atomicWrite0600(filePath, JSON.stringify({ version: 1, accounts }, null, 2) + '\n');
+    atomicWrite0600(filePath, JSON.stringify({ version: 1, accounts }, null, 2) + '\n', options);
   return {
     name: 'file',
     async get(account) {

package/src/unknown-subcommand.ts

@@ -20,6 +20,7 @@ export const KNOWN_SUBCOMMANDS = [
   'sync',
   'cleanup',
   'launch-all',
+  'server',
 ] as const;
 
 /**