borgmcp 1.1.15 → 2.0.2

package/src/server-response.ts

@@ -0,0 +1,76 @@
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error('Borg server request was aborted');
+}
+
+type ByteReadResult = Awaited<
+  ReturnType<ReadableStreamDefaultReader<Uint8Array>['read']>
+>;
+
+async function readWithAbort(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  signal?: AbortSignal,
+): Promise<ByteReadResult> {
+  if (!signal) return reader.read();
+  if (signal.aborted) throw abortError(signal);
+
+  return new Promise<ByteReadResult>((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    reader.read().then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+/** Read one server response without trusting Content-Length or stream EOF. */
+export async function readBoundedResponseBody(
+  response: Response,
+  maxBytes: number,
+  limitMessage: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const declaredLength = response.headers.get('content-length');
+  if (declaredLength !== null) {
+    const parsed = Number(declaredLength);
+    if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > maxBytes) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(limitMessage);
+    }
+  }
+  if (!response.body) return '';
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await readWithAbort(reader, signal);
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {});
+        throw new Error(limitMessage);
+      }
+      chunks.push(value);
+    }
+  } catch (error) {
+    await reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // The stream may already be canceled.
+    }
+  }
+
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder('utf-8', { fatal: true }).decode(body);
+}

package/src/server-trust.ts

@@ -0,0 +1,245 @@
+import { createHash, timingSafeEqual, X509Certificate } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { request as httpsRequest } from 'node:https';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { BorgServerTrustError } from './server-errors.js';
+
+// CR5 TLS LATTICE: OpenSSL/Node TLS certificate-verification error codes. A raw
+// CA / cert-chain / SAN failure from the pinned transport is a potential MITM and
+// MUST be a TERMINAL trust-mismatch verdict — never a transient 'restart' blip.
+// Connection refusal / reset / timeout are NOT in here: those stay raw transport
+// errors so the seat probe classifies them as `unreachable` (genuinely transient).
+const TLS_TRUST_ERROR_CODES = new Set([
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'CERT_UNTRUSTED',
+  'CERT_CHAIN_TOO_LONG',
+  'HOSTNAME_MISMATCH',
+  'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+
+/**
+ * True iff `code` is a PINNED-TRANSPORT certificate-verification failure (bad CA,
+ * unverifiable chain, self-signed leaf, expired/not-yet-valid cert, or a SAN /
+ * hostname mismatch). These are terminal trust-mismatch — a restart never fixes a
+ * wrong cert. `CERT_*` covers the OpenSSL verify family (CERT_HAS_EXPIRED,
+ * CERT_NOT_YET_VALID, CERT_REVOKED, …); `ERR_TLS_CERT*` covers Node's SAN check.
+ */
+function isPinnedTransportTrustFailure(code: string | undefined): boolean {
+  if (!code) return false;
+  return (
+    code.startsWith('CERT_') ||
+    code.startsWith('ERR_TLS_CERT') ||
+    TLS_TRUST_ERROR_CODES.has(code)
+  );
+}
+
+export type ServerFetch = typeof fetch;
+
+export interface BorgServerTrust {
+  identity: string;
+  fetchImpl: ServerFetch;
+}
+
+interface ServerTrustConfig {
+  ca_spki_sha256: string;
+}
+
+const trustCache = new Map<string, Promise<BorgServerTrust>>();
+
+function serverDataDirectory(): string {
+  return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(homedir(), '.borg', 'server'));
+}
+
+async function readTrustFile(path: string): Promise<string> {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error('Borg server trust files were not found');
+    }
+    throw new Error('Borg server trust files could not be opened safely');
+  }
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || (metadata.mode & 0o077) !== 0) {
+      throw new Error('Borg server trust files must be private regular files');
+    }
+    if (typeof process.getuid === 'function' && metadata.uid !== process.getuid()) {
+      throw new Error('Borg server trust files must be owned by the current user');
+    }
+    return await handle.readFile('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+function decodeTrustConfig(value: string): ServerTrustConfig {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error('Borg server trust metadata is invalid');
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('Borg server trust metadata is invalid');
+  }
+  const fingerprint = (parsed as Record<string, unknown>).ca_spki_sha256;
+  if (typeof fingerprint !== 'string' || !/^[a-f0-9]{64}$/i.test(fingerprint)) {
+    throw new Error('Borg server trust metadata is missing a valid CA identity');
+  }
+  return { ca_spki_sha256: fingerprint.toLowerCase() };
+}
+
+function verifyCaIdentity(certificate: string, expected: string): string {
+  let parsed: X509Certificate;
+  try {
+    parsed = new X509Certificate(certificate);
+  } catch {
+    throw new Error('Borg server CA certificate is invalid');
+  }
+  if (!parsed.ca) throw new Error('Borg server trust anchor is not a CA certificate');
+  const actual = createHash('sha256')
+    .update(parsed.publicKey.export({ type: 'spki', format: 'der' }))
+    .digest();
+  const expectedBytes = Buffer.from(expected, 'hex');
+  if (expectedBytes.length !== actual.length || !timingSafeEqual(actual, expectedBytes)) {
+    throw new Error('Borg server CA certificate does not match its pinned identity');
+  }
+  return `spki-sha256:${actual.toString('hex')}`;
+}
+
+function responseHeaders(rawHeaders: string[]): Headers {
+  const headers = new Headers();
+  for (let index = 0; index < rawHeaders.length; index += 2) {
+    const name = rawHeaders[index];
+    const value = rawHeaders[index + 1];
+    if (name !== undefined && value !== undefined) headers.append(name, value);
+  }
+  return headers;
+}
+
+function requestBody(value: unknown): string | Uint8Array | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === 'string') return value;
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new Error('Borg server transport received an unsupported request body');
+}
+
+/**
+ * Minimal fetch-compatible HTTPS transport bound to one origin and one
+ * explicit local CA. Node's global fetch cannot consume the server-owned CA,
+ * and disabling certificate validation would collapse the authority boundary.
+ */
+export function createPinnedServerFetch(origin: string, caCertificate: string): ServerFetch {
+  const authority = new URL(origin);
+  if (authority.protocol !== 'https:' || authority.origin !== origin) {
+    throw new Error('Borg server trust requires a canonical HTTPS origin');
+  }
+
+  return (async (input: string | URL | Request, init: RequestInit = {}): Promise<Response> => {
+    const url = input instanceof Request ? new URL(input.url) : new URL(input.toString());
+    if (url.origin !== authority.origin || url.protocol !== 'https:') {
+      throw new Error('Borg server transport refused a cross-authority request');
+    }
+    if (input instanceof Request) {
+      throw new Error('Borg server transport requires an explicit URL and request options');
+    }
+    if (init.signal?.aborted) throw new DOMException('This operation was aborted', 'AbortError');
+
+    const body = requestBody(init.body);
+    const headers = new Headers(init.headers);
+    return await new Promise<Response>((resolvePromise, rejectPromise) => {
+      const request = httpsRequest({
+        protocol: 'https:',
+        hostname: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+        port: url.port || 443,
+        path: `${url.pathname}${url.search}`,
+        method: init.method ?? 'GET',
+        headers: Object.fromEntries(headers.entries()),
+        ca: caCertificate,
+        rejectUnauthorized: true,
+        minVersion: 'TLSv1.3',
+      }, (incoming) => {
+        const status = incoming.statusCode ?? 500;
+        if (init.redirect === 'error' && status >= 300 && status < 400) {
+          incoming.resume();
+          rejectPromise(new Error('Borg server redirect refused'));
+          return;
+        }
+        const noBody = init.method === 'HEAD' || status === 204 || status === 304;
+        const stream = noBody
+          ? null
+          : Readable.toWeb(incoming) as ReadableStream<Uint8Array>;
+        if (noBody) incoming.resume();
+        resolvePromise(new Response(stream, {
+          status,
+          statusText: incoming.statusMessage,
+          headers: responseHeaders(incoming.rawHeaders),
+        }));
+      });
+
+      const abort = (): void => {
+        request.destroy(new DOMException('This operation was aborted', 'AbortError'));
+      };
+      init.signal?.addEventListener('abort', abort, { once: true });
+      request.once('close', () => init.signal?.removeEventListener('abort', abort));
+      request.once('error', (error) => {
+        // CR5: a pinned-transport CERT/CA/SAN verification failure is TERMINAL trust
+        // — type it as BorgServerTrustError so the seat probe returns `trust-mismatch`
+        // (never `indeterminate` → "restart"). Connection refusal/reset/timeout carry
+        // a transport errno (or an AbortError) and are rethrown RAW so the probe
+        // classifies them as `unreachable`.
+        const code = (error as NodeJS.ErrnoException).code;
+        if (isPinnedTransportTrustFailure(code)) {
+          rejectPromise(
+            new BorgServerTrustError(
+              `Borg server presented a certificate that failed pinned verification (${code})`,
+            ),
+          );
+          return;
+        }
+        rejectPromise(error);
+      });
+      if (body !== undefined) request.write(body);
+      request.end();
+    });
+  }) as ServerFetch;
+}
+
+export async function loadBorgServerTrust(
+  origin: string,
+  dataDirectory = serverDataDirectory(),
+): Promise<BorgServerTrust> {
+  const key = `${dataDirectory}\0${origin}`;
+  let pending = trustCache.get(key);
+  if (!pending) {
+    pending = (async () => {
+      const [certificate, configText] = await Promise.all([
+        readTrustFile(join(dataDirectory, 'ca.crt')),
+        readTrustFile(join(dataDirectory, 'server.json')),
+      ]);
+      const config = decodeTrustConfig(configText);
+      const identity = verifyCaIdentity(certificate, config.ca_spki_sha256);
+      return {
+        identity,
+        fetchImpl: createPinnedServerFetch(origin, certificate),
+      };
+    })();
+    trustCache.set(key, pending);
+    pending.catch(() => trustCache.delete(key));
+  }
+  return pending;
+}
+
+export function __clearServerTrustCacheForTest(): void {
+  trustCache.clear();
+}

package/src/session-continuity.ts

@@ -0,0 +1,280 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { getServerCredential } from './config.js';
+import { getActiveCube, type ActiveCube } from './cubes.js';
+import { DroneEvictedError } from './drone-lifecycle.js';
+import { sendBorgServerAttach } from './server-handshake.js';
+import { BorgServerError, BorgServerTrustError } from './server-errors.js';
+import { loadBorgServerTrust } from './server-trust.js';
+import {
+  getActiveSeat,
+  prepareSeatReplacement,
+  promoteSeatReplacement,
+  refreshActiveSeatSession,
+  scrubSeatReplacement,
+  seatRef,
+  type SeatRecord,
+} from './seats.js';
+
+export const SESSION_RENEWAL_LEAD_MS = 5 * 60_000;
+
+interface AttachOutcome {
+  result: 'created' | 'reused';
+  droneId: string;
+  sessionId: string;
+  expiresAt: string;
+}
+
+interface SessionContinuityDeps {
+  now(): number;
+  randomCredential(): string;
+  getSeat(ref: string, binding: { origin: string; trustIdentity: string; cubeId: string }): Promise<SeatRecord | null>;
+  getActive(): Promise<ActiveCube | null>;
+  getParentCredential(origin: string, trustIdentity: string): Promise<string | null>;
+  sendAttach(record: SeatRecord, bearer: string, parentCredential: string): Promise<AttachOutcome>;
+  prepareReplacement: typeof prepareSeatReplacement;
+  refreshSession: typeof refreshActiveSeatSession;
+  promoteReplacement: typeof promoteSeatReplacement;
+  scrubReplacement: typeof scrubSeatReplacement;
+}
+
+const defaultDeps: SessionContinuityDeps = {
+  now: Date.now,
+  randomCredential: () => randomBytes(32).toString('base64url'),
+  getSeat: getActiveSeat,
+  getActive: getActiveCube,
+  getParentCredential: getServerCredential,
+  async sendAttach(record, bearer, parentCredential) {
+    const trust = await loadBorgServerTrust(record.origin);
+    if (trust.identity !== record.trustIdentity) {
+      throw new BorgServerTrustError('Borg server trust identity changed; refusing session renewal');
+    }
+    const attached = await sendBorgServerAttach(
+      record.origin,
+      record.trustIdentity,
+      parentCredential,
+      {
+        cubeId: record.cubeId,
+        roleId: record.roleId,
+        operation: record.operation,
+        priorDroneId: record.droneId,
+      },
+      bearer,
+      { fetchImpl: trust.fetchImpl },
+    );
+    return {
+      result: attached.result,
+      droneId: attached.drone.id,
+      sessionId: attached.session.sessionId,
+      expiresAt: attached.session.expiresAt,
+    };
+  },
+  prepareReplacement: prepareSeatReplacement,
+  refreshSession: refreshActiveSeatSession,
+  promoteReplacement: promoteSeatReplacement,
+  scrubReplacement: scrubSeatReplacement,
+};
+
+const inflight = new Map<string, Promise<ActiveCube>>();
+const digestOf = (value: string) => createHash('sha256').update(value).digest('hex');
+
+function sameSeat(active: ActiveCube, candidate: ActiveCube | null): candidate is ActiveCube {
+  return candidate !== null &&
+    candidate.apiUrl === active.apiUrl &&
+    candidate.serverTrustIdentity === active.serverTrustIdentity &&
+    candidate.cubeId === active.cubeId &&
+    candidate.droneId === active.droneId &&
+    candidate.localSessionCredentialRef === active.localSessionCredentialRef;
+}
+
+function seatBinding(record: SeatRecord) {
+  return {
+    origin: record.origin,
+    trustIdentity: record.trustIdentity,
+    cubeId: record.cubeId,
+  };
+}
+
+function validActiveRecord(active: ActiveCube, record: SeatRecord | null): record is SeatRecord {
+  return record !== null &&
+    record.state === 'active' &&
+    record.origin === active.apiUrl &&
+    record.trustIdentity === active.serverTrustIdentity &&
+    record.cubeId === active.cubeId &&
+    record.droneId === active.droneId &&
+    seatRef(record) === active.localSessionCredentialRef;
+}
+
+function deterministicAttachFailure(error: unknown): boolean {
+  return error instanceof BorgServerError ||
+    error instanceof BorgServerTrustError ||
+    error instanceof DroneEvictedError;
+}
+
+async function reloadSameSeat(
+  active: ActiveCube,
+  deps: SessionContinuityDeps,
+  requireFreshCredential = false,
+): Promise<ActiveCube> {
+  const current = await deps.getActive();
+  if (!sameSeat(active, current) || (requireFreshCredential && current.sessionToken === active.sessionToken)) {
+    throw new Error('Session renewal no longer targets the same saved seat');
+  }
+  return current;
+}
+
+async function performRenewal(
+  active: ActiveCube,
+  mode: 'proactive' | 'expired',
+  deps: SessionContinuityDeps,
+): Promise<ActiveCube> {
+  if (!active.serverTrustIdentity || !active.localSessionCredentialRef) {
+    throw new Error('Selected Borg server authority state is missing or unreadable');
+  }
+  const binding = {
+    origin: active.apiUrl,
+    trustIdentity: active.serverTrustIdentity,
+    cubeId: active.cubeId,
+  };
+  const record = await deps.getSeat(active.localSessionCredentialRef, binding);
+  if (!validActiveRecord(active, record)) {
+    throw new Error('Session renewal no longer targets the same saved seat');
+  }
+  const activeDigest = digestOf(active.sessionToken);
+  if (digestOf(record.credential) !== activeDigest) {
+    return reloadSameSeat(active, deps, true);
+  }
+  const expiresIn = Date.parse(record.expiresAt!) - deps.now();
+  if (mode === 'proactive' && expiresIn > SESSION_RENEWAL_LEAD_MS && record.replacement === undefined) {
+    return active;
+  }
+  const parentCredential = await deps.getParentCredential(record.origin, record.trustIdentity);
+  if (!parentCredential) throw new Error('Selected Borg server parent credential is missing or unreadable');
+  const recordBinding = seatBinding(record);
+
+  let restoreRequired = mode === 'expired' || expiresIn <= 0 || record.replacement !== undefined;
+  if (!restoreRequired) {
+    let attached: AttachOutcome | null = null;
+    try {
+      attached = await deps.sendAttach(record, record.credential, parentCredential);
+    } catch (error) {
+      if (error instanceof BorgServerError && error.code === 'AUTH_EXPIRED') {
+        restoreRequired = true;
+      } else {
+        throw error;
+      }
+    }
+    if (!restoreRequired) {
+      if (!attached) throw new Error('Session renewal returned no result');
+      const renewedExpiry = Date.parse(attached.expiresAt);
+      if (
+        attached.result !== 'reused' ||
+        attached.droneId !== record.droneId ||
+        attached.sessionId !== record.sessionId ||
+        !Number.isFinite(renewedExpiry) ||
+        renewedExpiry <= Date.parse(record.expiresAt!)
+      ) {
+        throw new Error('Session renewal did not preserve the same saved seat');
+      }
+      const refreshed = await deps.refreshSession({
+        ref: active.localSessionCredentialRef,
+        binding: recordBinding,
+        expectedDroneId: record.droneId!,
+        expectedActiveDigest: activeDigest,
+        expectedSessionId: record.sessionId!,
+        expiresAt: attached.expiresAt,
+      });
+      if (!refreshed) return reloadSameSeat(active, deps);
+      return reloadSameSeat(active, deps);
+    }
+  }
+
+  const replacement = await deps.prepareReplacement({
+    ref: active.localSessionCredentialRef,
+    binding: recordBinding,
+    expectedDroneId: record.droneId!,
+    expectedActiveDigest: activeDigest,
+    replacementCredential: deps.randomCredential(),
+  });
+  if (!replacement.ok) return reloadSameSeat(active, deps, true);
+
+  let attached: AttachOutcome;
+  try {
+    attached = await deps.sendAttach(record, replacement.credential, parentCredential);
+  } catch (error) {
+    if (deterministicAttachFailure(error)) {
+      await deps.scrubReplacement({
+        ref: active.localSessionCredentialRef,
+        binding: recordBinding,
+        expectedActiveDigest: activeDigest,
+        expectedReplacementDigest: replacement.digest,
+      });
+    }
+    throw error;
+  }
+  const restoredExpiry = Date.parse(attached.expiresAt);
+  if (
+    (attached.result !== 'created' && attached.result !== 'reused') ||
+    attached.droneId !== record.droneId ||
+    attached.sessionId === record.sessionId ||
+    !Number.isFinite(restoredExpiry) ||
+    restoredExpiry <= deps.now()
+  ) {
+    await deps.scrubReplacement({
+      ref: active.localSessionCredentialRef,
+      binding: recordBinding,
+      expectedActiveDigest: activeDigest,
+      expectedReplacementDigest: replacement.digest,
+    });
+    throw new Error('Session renewal did not preserve the same saved seat');
+  }
+  const promoted = await deps.promoteReplacement({
+    ref: active.localSessionCredentialRef,
+    binding: recordBinding,
+    expectedDroneId: record.droneId!,
+    expectedActiveDigest: activeDigest,
+    expectedReplacementDigest: replacement.digest,
+    sessionId: attached.sessionId,
+    expiresAt: attached.expiresAt,
+  });
+  if (promoted !== 'promoted') return reloadSameSeat(active, deps, true);
+  return reloadSameSeat(active, deps, true);
+}
+
+function renewLocalSession(
+  active: ActiveCube,
+  mode: 'proactive' | 'expired',
+  deps: SessionContinuityDeps,
+): Promise<ActiveCube> {
+  const key = active.localSessionCredentialRef;
+  if (!key) return Promise.reject(new Error('Selected Borg server authority state is missing or unreadable'));
+  const existing = inflight.get(key);
+  if (existing) return existing;
+  const renewal = performRenewal(active, mode, deps);
+  inflight.set(key, renewal);
+  void renewal.finally(() => {
+    if (inflight.get(key) === renewal) inflight.delete(key);
+  }).catch(() => {});
+  return renewal;
+}
+
+export function ensureLocalSessionFresh(active: ActiveCube): Promise<ActiveCube> {
+  return renewLocalSession(active, 'proactive', defaultDeps);
+}
+
+export function recoverExpiredLocalSession(active: ActiveCube): Promise<ActiveCube> {
+  return renewLocalSession(active, 'expired', defaultDeps);
+}
+
+/** @internal */
+export function __renewLocalSessionForTest(
+  active: ActiveCube,
+  mode: 'proactive' | 'expired',
+  deps: SessionContinuityDeps,
+): Promise<ActiveCube> {
+  return renewLocalSession(active, mode, deps);
+}
+
+/** @internal */
+export function __resetSessionContinuityForTest(): void {
+  inflight.clear();
+}