borgmcp 2.0.1 → 2.0.3

package/src/log-stream.ts

@@ -28,6 +28,7 @@ import { Buffer } from 'node:buffer';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { compareBroadcastHwm, type BroadcastHwm } from 'borgmcp-shared/log-stream-hwm';
+import { decodeProtocolErrorEnvelope, ErrorCode } from 'borgmcp-shared/protocol';
 import { getActiveCube, inboxPathForDrone } from './cubes.js';
 import { assertUuidShape } from './evict-drone.js';
 import { loadBorgServerTrust } from './server-trust.js';
@@ -53,6 +54,8 @@ import {
   wakeCodexViaAppServer,
 } from './codex-app-wake.js';
 import { readBoundedResponseBody } from './server-response.js';
+import { BorgServerError, BorgServerUnreachableError } from './server-errors.js';
+import { recoverExpiredLocalSession } from './session-continuity.js';
 import {
   acquireStreamLease,
   readOwnershipSnapshot,
@@ -97,6 +100,13 @@ export class StreamCursorExpiredError extends Error {
   }
 }
 
+class TerminalStreamError extends Error {
+  constructor() {
+    super('terminal local session state');
+    this.name = 'TerminalStreamError';
+  }
+}
+
 function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -322,6 +332,7 @@ function runStreamLoopForever(): void {
         await runLoop();
         process.stderr.write('[borg-mcp log stream] runLoop returned unexpectedly; restarting in 5s\n');
       } catch (err: any) {
+        if (err instanceof TerminalStreamError) return;
         process.stderr.write(`[borg-mcp log stream] runLoop threw: ${err?.message ?? err}; restarting in 5s\n`);
       }
       streamState.runLoopRestartCount += 1;
@@ -417,6 +428,7 @@ export interface RunLoopTestDeps {
   getActiveCube?: typeof getActiveCube;
   acquireStreamLease?: typeof acquireStreamLease;
   streamOnce?: typeof streamOnce;
+  recoverExpiredSession?: typeof recoverExpiredLocalSession;
   sleep?: (ms: number) => Promise<void>;
   maxIterations?: number;
 }
@@ -425,6 +437,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
   const _getActiveCube = testDeps.getActiveCube ?? getActiveCube;
   const _acquireStreamLease = testDeps.acquireStreamLease ?? acquireStreamLease;
   const _streamOnce = testDeps.streamOnce ?? streamOnce;
+  const _recoverExpiredSession = testDeps.recoverExpiredSession ?? recoverExpiredLocalSession;
   const _sleep = testDeps.sleep ?? sleep;
   const _maxIterations = testDeps.maxIterations ?? Infinity;
   let _iterations = 0;
@@ -434,6 +447,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
   let currentCubeId: string | null = null;
   let lease: StreamLease | null = null;
   let leaseKey: string | null = null;
+  let lastRecoveredToken: string | null = null;
 
   try {
     while (_iterations < _maxIterations) {
@@ -534,6 +548,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
       }
       // Clean disconnect (e.g. server-side rollout). Reset backoff.
       attempt = 0;
+      lastRecoveredToken = null;
       streamState.reconnectAttempts = 0;
     } catch (err: any) {
       if (ownerLost) {
@@ -559,7 +574,28 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
         process.stderr.write(
           `[borg-mcp log stream] drone evicted — stream terminated (no reconnect).\n`
         );
-        return;
+        throw new TerminalStreamError();
+      }
+      if (err instanceof BorgServerError) {
+        if (err.code !== 'AUTH_EXPIRED' || lastRecoveredToken === active.sessionToken) {
+          throw new TerminalStreamError();
+        }
+        try {
+          const renewed = await _recoverExpiredSession(active);
+          lastRecoveredToken = renewed.sessionToken;
+          attempt = 0;
+          streamState.reconnectAttempts = 0;
+          continue;
+        } catch (recoveryError) {
+          if (!(recoveryError instanceof BorgServerUnreachableError)) {
+            throw new TerminalStreamError();
+          }
+          // The replacement bearer is durable and intentionally survives an
+          // ambiguous transport failure. Fall through to the ordinary bounded
+          // reconnect backoff; the next AUTH_EXPIRED response resumes that exact
+          // replacement instead of permanently silencing the stream.
+          err = recoveryError;
+        }
       }
       streamState.connected = false;
       const delay =
@@ -603,6 +639,8 @@ export interface ActiveCube {
   sessionToken: string;
   apiUrl: string;
   serverTrustIdentity?: string;
+  localSessionCredentialRef?: string;
+  localSessionExpiresAt?: string | null;
 }
 
 export async function streamOnce(
@@ -762,7 +800,7 @@ export async function streamOnce(
   // Set + FIFO array for O(1) membership + bounded memory.
   const recentIds = new Set<string>();
   const recentIdsOrder: string[] = [];
-  let isCatchingUp = lastEventId !== null;
+  let isCatchingUp = lastEventId !== null || cursor !== null;
 
   // gh#29 quality-stream (#5): shared inbox-write + cursor-advance helpers,
   // extracted from the previously-duplicated ack / regular-log branches in the
@@ -856,6 +894,30 @@ export async function streamOnce(
     // off forever against a dead seat. Keyed on the structured code, not the
     // bare status (SEC R2). Any other status falls through to the generic throw
     // so the reconnect loop keeps retrying transient failures.
+    if (response.status === 401) {
+      const body = await readBoundedResponseBody(
+        response,
+        LOCAL_SERVER_SSE_FRAME_LIMIT_BYTES,
+        'Local Borg server SSE response exceeded the response limit',
+        ac.signal,
+      ).catch(() => '');
+      let code: ErrorCode | undefined;
+      try {
+        code = decodeProtocolErrorEnvelope(JSON.parse(body)).error.code;
+      } catch {
+        code = undefined;
+      }
+      if (code === ErrorCode.AUTH_EXPIRED) {
+        throw new BorgServerError('AUTH_EXPIRED', 'Borg server session expired');
+      }
+      if (code === ErrorCode.SESSION_REJECTED) {
+        throw new BorgServerError('SESSION_REJECTED', 'Borg server session was rejected');
+      }
+      if (code === ErrorCode.SESSION_REVOKED) {
+        throw new BorgServerError('SESSION_REVOKED', 'Borg server session was revoked');
+      }
+      throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server rejected the stream credential');
+    }
     if (response.status === 410) {
       const body = await readBoundedResponseBody(
         response,

package/src/remote-client.ts

@@ -47,6 +47,7 @@ import {
 } from './local-server-cursor.js';
 import { readBoundedResponseBody } from './server-response.js';
 import { resolveLocalLogRecipients } from './local-log-routing.js';
+import { ensureLocalSessionFresh, recoverExpiredLocalSession } from './session-continuity.js';
 
 export interface RemoteConnection {
   apiUrl: string;
@@ -228,20 +229,31 @@ async function localServerRequest<T>(
   method: 'GET' | 'POST' | 'PUT' | 'PATCH',
   payload?: Record<string, unknown>,
 ): Promise<T | null> {
-  return decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
-    method,
-    signal,
-    droneSession: active.sessionToken,
-    apiUrl: active.apiUrl,
-    serverTrustIdentity: active.serverTrustIdentity,
-    redirect: 'error',
-    ...(payload === undefined
-      ? { headers: { Accept: 'application/json' } }
-      : {
-        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-        body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
-      }),
-  }), true);
+  let current = active.localSessionCredentialRef && active.localSessionExpiresAt
+    ? await ensureLocalSessionFresh(active)
+    : active;
+  const request = (candidate: ActiveCube) => decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
+      method,
+      signal,
+      droneSession: candidate.sessionToken,
+      apiUrl: candidate.apiUrl,
+      serverTrustIdentity: candidate.serverTrustIdentity,
+      redirect: 'error',
+      ...(payload === undefined
+        ? { headers: { Accept: 'application/json' } }
+        : {
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
+        }),
+    }), true);
+  try {
+    return await request(current);
+  } catch (error) {
+    if (!(error instanceof BorgServerError) || error.code !== 'AUTH_EXPIRED') throw error;
+    if (current.sessionToken !== active.sessionToken) throw error;
+    current = await recoverExpiredLocalSession(current);
+    return request(current);
+  }
 }
 
 export interface LocalManageOperation {
@@ -404,6 +416,66 @@ async function localReadLogPage(
   return payload;
 }
 
+interface PendingWakePage {
+  entries: Array<{
+    drone_id?: unknown;
+    message?: unknown;
+    visibility?: unknown;
+    recipient_drone_ids?: unknown;
+  }>;
+  cursor: LocalServerCursor | null;
+  has_more: boolean;
+}
+
+function isPendingWakeEntry(
+  entry: PendingWakePage['entries'][number],
+  droneId: string,
+): boolean {
+  if (entry.visibility === 'direct') {
+    const recipients = Array.isArray(entry.recipient_drone_ids)
+      ? entry.recipient_drone_ids.filter((recipient): recipient is string => typeof recipient === 'string')
+      : [];
+    if (!recipients.includes(droneId)) return false;
+  }
+
+  const isHeartbeatPing =
+    typeof entry.message === 'string' && entry.message.startsWith('[HEARTBEAT-PING]');
+  return entry.drone_id !== droneId || isHeartbeatPing;
+}
+
+/**
+ * client#76: inspect authoritative unread log state without advancing the
+ * agent-owned unread cursor. The scan mirrors the SSE wake filters: unaddressed
+ * direct entries and ordinary own posts are not work for this seat. A full
+ * paginated scan prevents a run of skipped entries from hiding later real work.
+ */
+export async function hasPendingWakeActivity(
+  active: ActiveCube,
+  deps: {
+    getCursor?: typeof getLocalServerCursor;
+    readPage?: (active: ActiveCube, opts: { cursor: LocalServerCursor | null; limit: number }) => Promise<PendingWakePage>;
+  } = {},
+): Promise<boolean> {
+  if (!active.serverTrustIdentity) {
+    throw new Error('Selected Borg server authority state is missing or unreadable');
+  }
+
+  const getCursor = deps.getCursor ?? getLocalServerCursor;
+  const readPage = deps.readPage ?? localReadLogPage;
+  let cursor = await getCursor(localCursorBinding(active));
+
+  for (;;) {
+    const page: PendingWakePage = await readPage(active, { cursor, limit: 500 });
+    if (page.entries.some((entry) => isPendingWakeEntry(entry, active.droneId))) return true;
+    if (!page.has_more) return false;
+    if (!page.cursor ||
+      (cursor && page.cursor.id === cursor.id && page.cursor.created_at === cursor.created_at)) {
+      throw new Error('Local Borg server returned a non-advancing log cursor');
+    }
+    cursor = page.cursor;
+  }
+}
+
 async function resolveLocalLogCursor(
   active: ActiveCube,
   since: string,
@@ -549,6 +621,12 @@ async function authedFetch(
     } catch {
       rejectedCode = undefined;
     }
+    if (droneSession !== undefined && rejectedCode === ErrorCode.AUTH_EXPIRED) {
+      throw new BorgServerError(
+        'AUTH_EXPIRED',
+        'the selected Borg server session expired',
+      );
+    }
     if (droneSession !== undefined && rejectedCode === ErrorCode.SESSION_REJECTED) {
       throw new BorgServerError(
         'SESSION_REJECTED',

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);
 }