borgmcp 2.8.0 → 2.10.0

package/src/regen-format.ts

@@ -19,6 +19,7 @@ import {
 import { shellEscape } from './shell-escape.js';
 import { resolveInboxMonitorPath } from './self-path.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
+import { isBorgSession } from './launch-gate.js';
 
 /**
  * Extract the SessionStart `source` from a Claude Code hook payload (gh#926).
@@ -46,6 +47,30 @@ export function parseHookSource(raw: string): string | null {
   }
 }
 
+/** Best-effort relay directive for a plain Claude/Codex session. */
+export function formatPlainSessionReminder(): string {
+  return [
+    'Relay exactly this one line to the user once, without paraphrasing:',
+    'This repository is connected to a Borg cube, but this session was not launched with `borg`; cube coordination is inactive for this session. Relaunch with `borg` to use cube coordination.',
+  ].join('\n');
+}
+
+export function shouldRelayPlainSessionReminder(args: {
+  source: string | null;
+  agentKind: AgentKind;
+  hasActiveCube: boolean;
+  borgSession: string | undefined;
+  disabled: string | undefined;
+}): boolean {
+  return (
+    args.source === 'startup' &&
+    args.agentKind !== 'opencode' &&
+    args.hasActiveCube &&
+    !isBorgSession({ BORG_SESSION: args.borgSession }) &&
+    args.disabled === undefined
+  );
+}
+
 /** The agent runtime a session runs under — drives the wake-path branch. */
 export type AgentKind = 'claude' | 'codex' | 'opencode';
 

package/src/regen.ts

@@ -22,12 +22,18 @@ import { monitorStateRootForWorktree } from './inbox-monitor.js';
 import {
   parseHookSource,
   formatLeanOrientation,
+  formatPlainSessionReminder,
+  shouldRelayPlainSessionReminder,
   type AgentKind,
 } from './regen-format.js';
 import { resolveSessionAgentKind } from './codex-app-wake.js';
 import { resolveReportableSessionAgentKind } from './agent-runtime.js';
 import { handleVersionFlag } from './version.js';
-import { gateAllowsActivation } from './launch-gate.js';
+import {
+  BORG_LAUNCH_REMINDER_DISABLED_ENV,
+  BORG_SESSION_ENV,
+  gateAllowsActivation,
+} from './launch-gate.js';
 import { resolveWorkingRepo } from './working-repo.js';
 import {
   confirmDisplayIdentity,
@@ -56,18 +62,40 @@ async function readStdin(): Promise<string> {
 
 async function main(): Promise<void> {
   handleVersionFlag();
+  const hookSource = parseHookSource(await readStdin());
   // gh#673 P1 (WI-4): the SessionStart orientation only activates in
   // borg-launched sessions — a vanilla `claude` anywhere (including an
   // assimilated repo) stays vanilla. Exit-0 no-op: a hook must never
   // block session start. ACTIVATION-only, never a security gate.
   if (!gateAllowsActivation('borg-regen SessionStart hook')) {
+    // launch-reminder-ux: plain sessions get one model-mediated relay only on
+    // the initial SessionStart event. No repo connection means no output.
+    let hasActiveCube = false;
+    try {
+      hasActiveCube = (await getActiveCube()) !== null;
+    } catch {
+      hasActiveCube = false;
+    }
+    if (shouldRelayPlainSessionReminder({
+      source: hookSource,
+      agentKind: resolveSessionAgentKind(),
+      hasActiveCube,
+      borgSession: process.env[BORG_SESSION_ENV],
+      disabled: process.env[BORG_LAUNCH_REMINDER_DISABLED_ENV],
+    })) {
+      try {
+        process.stdout.write(`${formatPlainSessionReminder()}\n`);
+      } catch {
+        // Plain-session discovery is best-effort and must stay silent on failure.
+      }
+    }
     return;
   }
   // gh#926/gh#927: the SessionStart `source` (startup/resume/clear/compact)
   // tags the orientation; on `/clear` Claude Code has cleared the
   // session-scoped `/loop` + `ScheduleWakeup`, and the kickoff prompt is
   // gone, so the lean orientation adds a "re-establish your wake path" note.
-  const source = parseHookSource(await readStdin());
+  const source = hookSource;
 
   const active = await getActiveCube();
   if (!active) {

package/src/remote-client.ts

@@ -1041,7 +1041,7 @@ export async function regen(
   opts: {
     since?: string;
     /** Advisory self-report from the running agent; never model-routing config. */
-    reportedModel?: string;
+    reportedModel?: string | null;
     /** Positively identified running Agent CLI; null means explicitly unknown. */
     agentKind?: AgentKind | null;
     /** Current cwd-derived identity; refreshed each regen to avoid stale routing data. */
@@ -1077,7 +1077,7 @@ export async function regen(
   ) {
     const patch = buildRuntimeMetadataPatch({
       agentKind: opts.agentKind ?? null,
-      reportedModel: opts.reportedModel,
+      reportedModel: opts.reportedModel ?? null,
       workingRepo: opts.workingRepo,
     });
     try {

package/src/runtime-metadata.ts

@@ -53,13 +53,14 @@ export function buildRuntimeMetadataReport(input: {
 
 export function buildRuntimeMetadataPatch(input: {
   agentKind: AgentKind | null;
-  reportedModel?: string;
+  reportedModel?: string | null;
   workingRepo?: WorkingRepo;
 }): DroneRuntimeMetadataPatch {
   const patch: DroneRuntimeMetadataPatch = { agent_kind: input.agentKind };
   if (input.reportedModel !== undefined) {
-    const model = safeReportedModel(input.reportedModel);
-    if (model !== null) patch.reported_model = model;
+    patch.reported_model = input.reportedModel === null
+      ? null
+      : validateReportedModel(input.reportedModel);
   }
   const repository = reportableRepository(input.workingRepo);
   if (repository) Object.assign(patch, repository);

package/src/seat-store.ts

@@ -238,6 +238,12 @@ export async function atomicWrite0600(
       await assertSecureFile(filePath);
     }
     await rename(tmp, filePath);
+    const parent = await open(dirname(filePath), 'r');
+    try {
+      await parent.sync();
+    } finally {
+      await parent.close();
+    }
   } catch (err) {
     await unlink(tmp).catch(() => {});
     throw err;

package/src/server-errors.ts

@@ -2,6 +2,7 @@ export type BorgServerErrorCode =
   | 'NOT_ENROLLED'
   | 'CREDENTIAL_REJECTED'
   | 'INVITATION_REJECTED'
+  | 'LOCAL_CREDENTIAL_EXISTS'
   | 'CREATE_CUBE_DENIED'
   | 'ATTACH_CONFLICT'
   | 'SESSION_REJECTED'

package/src/server-facade.ts

@@ -5,7 +5,7 @@ import { cubeInitHelpText, isHelpFlag, serverHelpText } from './cli-help.js';
 import { consolePrefix } from './console-prefix.js';
 import { getPackageVersion } from './version.js';
 
-export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'stop', 'status', 'update', 'invite', 'dashboard'] as const;
+export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'stop', 'status', 'update', 'invite', 'cert-reissue', 'dashboard'] as const;
 export type ServerLifecycleCommand = typeof SERVER_LIFECYCLE_COMMANDS[number];
 
 export type ParsedServerFacadeArgs =
@@ -162,7 +162,7 @@ function inertCommand(command: string): string {
 export function unknownServerCommandText(command: string): string {
   return (
     `Unknown server command: ${inertCommand(command)}.\n` +
-    `Available commands: setup, start, stop, status, update, invite, dashboard, cube init.\n` +
+    `Available commands: setup, start, stop, status, update, invite, cert-reissue, dashboard, cube init.\n` +
     `Next: run borg server --help.\n`
   );
 }

package/src/server-handshake.ts

@@ -8,6 +8,7 @@ import {
   REPOSITORY_CUBE_RESOLVE_PATH,
   createAttachRequestEnvelope,
   createProtocolEnvelope,
+  encodeInvitationArtifact,
   decodeAssociateRepositoryCubeRequest,
   decodeAssociateRepositoryCubeResponseEnvelope,
   decodeAttachResponseEnvelope,
@@ -17,6 +18,7 @@ import {
   decodeEnrollmentExchangeResponseEnvelope,
   decodeProtocolErrorEnvelope,
   decodeProtocolTagPreflight,
+  type InvitationArtifact,
   decodeResolveRepositoryCubeRequest,
   decodeResolveRepositoryCubeResponseEnvelope,
   ErrorCode,
@@ -36,6 +38,7 @@ import {
   clearPendingServerEnrollment,
   getServerCredential,
   getServerCredentialRecord,
+  hasServerCredentialForOrigin,
   getPendingServerEnrollment,
   getOrCreatePendingServerCubeCreation,
   getOrCreatePendingServerEnrollment,
@@ -65,8 +68,17 @@ import { DroneEvictedError, DRONE_EVICTED_CODE } from './drone-lifecycle.js';
 import { readBoundedResponseBody } from './server-response.js';
 import {
   loadBorgServerTrust,
+  loadBorgServerTrustFromPresentedChain,
   type BorgServerTrust,
+  type StagedBorgServerTrust,
 } from './server-trust.js';
+import {
+  InvitationArtifactCompatibilityError,
+  InvitationArtifactStorageError,
+  InvitationArtifactTransportError,
+  InvitationArtifactTrustError,
+  decodeAndVerifyInvitationArtifact,
+} from './invitation-artifact.js';
 
 const HANDSHAKE_BODY_LIMIT = 64 * 1024;
 const HANDSHAKE_TIMEOUT_MS = 5_000;
@@ -452,20 +464,57 @@ export async function enrollBorgServer(
     prepareEnrollment?: typeof getOrCreatePendingServerEnrollment;
     activateEnrollment?: typeof activatePendingServerEnrollment;
     clearPendingEnrollment?: typeof clearPendingServerEnrollment;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+    hasCredentialForOrigin?: typeof hasServerCredentialForOrigin;
+    confirmReplacement?: () => Promise<boolean>;
     clientName?: string;
+    expectedAuthority?: InvitationArtifact['authority'];
+    commitTrust?: (activate: () => Promise<void>) => Promise<void>;
+    discardTrust?: () => Promise<void>;
   } = {},
 ): Promise<NewServerEnrollment> {
   const fetchImpl = deps.fetchImpl ?? fetch;
   // Credential-free tag preflight FIRST (CR fb4d6eba): after pinned TLS, an
   // incompatible server must be rejected before any credential is created or
   // persisted and before any invitation/secret-bearing request is sent.
-  const protocol = await preflightBorgServerTag(origin, fetchImpl);
+  let protocol: ProtocolTagPreflight;
+  try {
+    protocol = await preflightBorgServerTag(origin, fetchImpl);
+  } catch (error) {
+    await deps.discardTrust?.();
+    throw error;
+  }
+
+  const existingCredential = await (deps.loadCredentialRecord ?? getServerCredentialRecord)(
+    origin,
+    trustIdentity,
+  );
+  const existingOriginCredential = existingCredential !== null || await (
+    deps.hasCredentialForOrigin ?? hasServerCredentialForOrigin
+  )(origin);
+  let replacementConfirmed = false;
+  let replacementCapability: string | undefined;
+  if (existingOriginCredential) {
+    const confirmed = deps.confirmReplacement !== undefined
+      ? await deps.confirmReplacement()
+      : false;
+    if (!confirmed) {
+      await deps.discardTrust?.();
+      throw new BorgServerError(
+        'LOCAL_CREDENTIAL_EXISTS',
+        'a local enrollment already exists for this server and was not replaced',
+      );
+    }
+    replacementConfirmed = true;
+    replacementCapability = randomUUID();
+  }
 
   const pending = await (deps.prepareEnrollment ?? getOrCreatePendingServerEnrollment)({
     origin,
     trustIdentity,
     invitation,
     ...(deps.clientName ? { clientName: deps.clientName } : {}),
+    ...(replacementCapability === undefined ? {} : { replacementCapability }),
   });
   const request = decodeEnrollmentExchangeRequest({
     invitation: pending.invitation,
@@ -495,9 +544,13 @@ export async function enrollBorgServer(
       clearTimeout(timeout);
     }
   }
-  if (!response) throw lastTransportError;
+  if (!response) {
+    await deps.discardTrust?.();
+    throw lastTransportError;
+  }
 
   if (response.status === 401 || response.status === 403) {
+    await deps.discardTrust?.();
     await (deps.clearPendingEnrollment ?? clearPendingServerEnrollment)(
       origin,
       trustIdentity,
@@ -509,6 +562,7 @@ export async function enrollBorgServer(
     );
   }
   if (response.status !== 201) {
+    await deps.discardTrust?.();
     throw new Error(`Borg server enrollment failed (HTTP ${response.status})`);
   }
   let decoded: ReturnType<typeof decodeEnrollmentExchangeResponseEnvelope>;
@@ -517,18 +571,37 @@ export async function enrollBorgServer(
       JSON.parse(await readHandshakeBodyWithTimeout(response)),
     );
   } catch (error) {
+    await deps.discardTrust?.();
     if (error instanceof Error && error.message.includes('response limit')) throw error;
     throw new Error('Borg server returned an invalid enrollment envelope');
   }
 
-  await (deps.activateEnrollment ?? activatePendingServerEnrollment)({
+  if (deps.expectedAuthority !== undefined) {
+    const owner = decoded.payload.server_capabilities.length > 0;
+    if ((deps.expectedAuthority === 'owner') !== owner) {
+      await (deps.clearPendingEnrollment ?? clearPendingServerEnrollment)(
+        origin,
+        trustIdentity,
+        pending.retryKey,
+      );
+      await deps.discardTrust?.();
+      throw new InvitationArtifactTrustError();
+    }
+  }
+
+  const activate = () => (deps.activateEnrollment ?? activatePendingServerEnrollment)({
     origin,
     trustIdentity,
     retryKey: pending.retryKey,
     credential: pending.credential,
     clientId: decoded.payload.client_id,
     serverCapabilities: decoded.payload.server_capabilities,
+     ...(replacementConfirmed || pending.replacementCapability !== undefined
+       ? { allowReplacement: true, ...(pending.replacementCapability === undefined ? {} : { replacementCapability: pending.replacementCapability }) }
+       : {}),
   });
+  if (deps.commitTrust) await deps.commitTrust(activate);
+  else await activate();
   return {
     token: pending.credential,
     trustIdentity,
@@ -1011,6 +1084,8 @@ export async function enrollLocalBorgServer(
     prepareEnrollment?: typeof getOrCreatePendingServerEnrollment;
     activateEnrollment?: typeof activatePendingServerEnrollment;
     clearPendingEnrollment?: typeof clearPendingServerEnrollment;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+    confirmReplacement?: () => Promise<boolean>;
     clientName?: string;
   } = {},
 ): Promise<NewServerEnrollment> {
@@ -1022,7 +1097,62 @@ export async function enrollLocalBorgServer(
     ...(deps.clearPendingEnrollment === undefined
       ? {}
       : { clearPendingEnrollment: deps.clearPendingEnrollment }),
+    ...(deps.loadCredentialRecord === undefined
+      ? {}
+      : { loadCredentialRecord: deps.loadCredentialRecord }),
+    ...(deps.confirmReplacement === undefined
+      ? {}
+      : { confirmReplacement: deps.confirmReplacement }),
+    ...(deps.clientName === undefined ? {} : { clientName: deps.clientName }),
+  });
+}
+
+/** Enroll from a verified v2 artifact whose endpoint and CA pin are authoritative. */
+export async function enrollLocalBorgServerArtifact(
+  artifact: InvitationArtifact,
+  deps: {
+    invitation?: string;
+    confirmReplacement?: () => Promise<boolean>;
+    clientName?: string;
+    loadTrustFromPresentedChain?: typeof loadBorgServerTrustFromPresentedChain;
+    prepareEnrollment?: typeof getOrCreatePendingServerEnrollment;
+    activateEnrollment?: typeof activatePendingServerEnrollment;
+    clearPendingEnrollment?: typeof clearPendingServerEnrollment;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+    hasCredentialForOrigin?: typeof hasServerCredentialForOrigin;
+  } = {},
+): Promise<NewServerEnrollment> {
+  // Preserve the byte-exact opaque artifact from the operator's prompt. The
+  // decoded object is enough to inspect the endpoint/pin, but it is not the
+  // enrollment protocol's invitation material: replacing it with
+  // `verifiedArtifact.secret` silently degrades v2 composite artifacts.
+  const opaqueArtifact = deps.invitation ?? encodeInvitationArtifact(artifact);
+  const verifiedArtifact = decodeAndVerifyInvitationArtifact(opaqueArtifact);
+  let trust: StagedBorgServerTrust;
+  try {
+    trust = await (deps.loadTrustFromPresentedChain ?? loadBorgServerTrustFromPresentedChain)(
+      verifiedArtifact.endpoint,
+      verifiedArtifact.ca_spki_sha256,
+    );
+  } catch (error) {
+    if (error instanceof InvitationArtifactCompatibilityError) throw error;
+    if (error instanceof InvitationArtifactTransportError) throw error;
+    if (error instanceof InvitationArtifactTrustError) throw error;
+    if (error instanceof InvitationArtifactStorageError) throw error;
+    throw new InvitationArtifactTransportError();
+  }
+  return enrollBorgServer(verifiedArtifact.endpoint, trust.identity, opaqueArtifact, {
+    fetchImpl: trust.fetchImpl,
+    ...(deps.confirmReplacement === undefined ? {} : { confirmReplacement: deps.confirmReplacement }),
     ...(deps.clientName === undefined ? {} : { clientName: deps.clientName }),
+    ...(deps.prepareEnrollment === undefined ? {} : { prepareEnrollment: deps.prepareEnrollment }),
+    ...(deps.activateEnrollment === undefined ? {} : { activateEnrollment: deps.activateEnrollment }),
+    ...(deps.clearPendingEnrollment === undefined ? {} : { clearPendingEnrollment: deps.clearPendingEnrollment }),
+    ...(deps.loadCredentialRecord === undefined ? {} : { loadCredentialRecord: deps.loadCredentialRecord }),
+    ...(deps.hasCredentialForOrigin === undefined ? {} : { hasCredentialForOrigin: deps.hasCredentialForOrigin }),
+    expectedAuthority: verifiedArtifact.authority,
+    commitTrust: trust.commitTrust,
+    discardTrust: trust.discardTrust,
   });
 }
 
@@ -1035,7 +1165,13 @@ export async function resumeLocalBorgServerEnrollment(
     onPending?: () => void;
   } = {},
 ): Promise<NewServerEnrollment | null> {
-  const trust = await (deps.loadTrust ?? loadBorgServerTrust)(origin);
+  let trust: BorgServerTrust;
+  try {
+    trust = await (deps.loadTrust ?? loadBorgServerTrust)(origin);
+  } catch (error) {
+    if (error instanceof Error && /trust files were not found|trust metadata/i.test(error.message)) return null;
+    throw error;
+  }
   return resumeBorgServerEnrollment(origin, trust.identity, {
     fetchImpl: trust.fetchImpl,
     ...(deps.loadPendingEnrollment === undefined

package/src/server-trust.ts

@@ -1,12 +1,20 @@
 import { Buffer } from 'node:buffer';
 import { createHash, timingSafeEqual, X509Certificate } from 'node:crypto';
 import { constants } from 'node:fs';
-import { open } from 'node:fs/promises';
+import { access, mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
 import { request as httpsRequest } from 'node:https';
+import { connect as tlsConnect } from 'node:tls';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { Readable } from 'node:stream';
 import { BorgServerTrustError } from './server-errors.js';
+import {
+  InvitationArtifactCompatibilityError,
+  InvitationArtifactRecoveryError,
+  InvitationArtifactStorageError,
+  InvitationArtifactTransportError,
+  InvitationArtifactTrustError,
+} from './invitation-artifact.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
@@ -48,6 +56,11 @@ export interface BorgServerTrust {
   fetchImpl: ServerFetch;
 }
 
+export interface StagedBorgServerTrust extends BorgServerTrust {
+  commitTrust: (activate: () => Promise<void>) => Promise<void>;
+  discardTrust: () => Promise<void>;
+}
+
 interface ServerTrustConfig {
   ca_spki_sha256: string;
 }
@@ -58,6 +71,20 @@ function serverDataDirectory(): string {
   return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(homedir(), '.borg', 'server'));
 }
 
+function remoteTrustDirectory(origin: string): string {
+  const key = createHash('sha256').update(origin).digest('hex');
+  return join(homedir(), '.borg', 'server-trust', key);
+}
+
+async function trustFilesExist(directory: string): Promise<boolean> {
+  try {
+    await Promise.all([access(join(directory, 'ca.crt')), access(join(directory, 'server.json'))]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function readTrustFile(path: string): Promise<string> {
   let handle;
   try {
@@ -82,6 +109,15 @@ async function readTrustFile(path: string): Promise<string> {
   }
 }
 
+async function syncPath(path: string): Promise<void> {
+  const handle = await open(path, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
 function decodeTrustConfig(value: string): ServerTrustConfig {
   let parsed: unknown;
   try {
@@ -228,15 +264,22 @@ export function createPinnedServerFetch(origin: string, caCertificate: string):
 
 export async function loadBorgServerTrust(
   origin: string,
-  dataDirectory = serverDataDirectory(),
+  dataDirectory?: string,
 ): Promise<BorgServerTrust> {
-  const key = `${dataDirectory}\0${origin}`;
+  const requestedDirectory = dataDirectory ?? serverDataDirectory();
+  const key = `${requestedDirectory}\0${origin}`;
   let pending = trustCache.get(key);
   if (!pending) {
     pending = (async () => {
+      const remoteDirectory = remoteTrustDirectory(origin);
+      const directory = dataDirectory === undefined && await trustFilesExist(remoteDirectory)
+        ? remoteDirectory
+        : dataDirectory === undefined && !(await trustFilesExist(requestedDirectory))
+          ? remoteDirectory
+          : requestedDirectory;
       const [certificate, configText] = await Promise.all([
-        readTrustFile(join(dataDirectory, 'ca.crt')),
-        readTrustFile(join(dataDirectory, 'server.json')),
+        readTrustFile(join(directory, 'ca.crt')),
+        readTrustFile(join(directory, 'server.json')),
       ]);
       const config = decodeTrustConfig(configText);
       const identity = verifyCaIdentity(certificate, config.ca_spki_sha256);
@@ -251,6 +294,138 @@ export async function loadBorgServerTrust(
   return pending;
 }
 
+function pemCertificate(raw: Buffer): string {
+  const body = raw.toString('base64').match(/.{1,64}/g)?.join('\n') ?? '';
+  return `-----BEGIN CERTIFICATE-----\n${body}\n-----END CERTIFICATE-----\n`;
+}
+
+function chainCertificates(socket: { getPeerCertificate(detailed: true): any }): Buffer[] {
+  const result: Buffer[] = [];
+  const seen = new Set<string>();
+  let current = socket.getPeerCertificate(true);
+  while (current?.raw instanceof Buffer) {
+    const key = current.raw.toString('base64');
+    if (seen.has(key)) break;
+    seen.add(key);
+    result.push(current.raw);
+    current = current.issuerCertificate;
+  }
+  return result;
+}
+
+async function fetchPresentedChain(origin: string): Promise<Buffer[]> {
+  const url = new URL(origin);
+  return new Promise((resolveChain, rejectChain) => {
+    const socket = tlsConnect({
+      host: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+      port: url.port === '' ? 443 : Number(url.port),
+      rejectUnauthorized: false,
+      servername: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+    });
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      rejectChain(new InvitationArtifactTransportError());
+    }, 5_000);
+    socket.once('secureConnect', () => {
+      clearTimeout(timeout);
+      const chain = chainCertificates(socket);
+      socket.destroy();
+      resolveChain(chain);
+    });
+    socket.once('error', () => {
+      clearTimeout(timeout);
+      rejectChain(new InvitationArtifactTransportError());
+    });
+  });
+}
+
+/** Bootstrap a remote pinned transport from the CA chain presented by the server. */
+export async function loadBorgServerTrustFromPresentedChain(
+  origin: string,
+  caSpkiSha256: string,
+): Promise<StagedBorgServerTrust> {
+  const chain = await fetchPresentedChain(origin);
+  let sawCa = false;
+  for (const raw of chain) {
+    try {
+      const certificate = new X509Certificate(raw);
+      if (!certificate.ca) continue;
+      sawCa = true;
+      const actual = createHash('sha256')
+        .update(certificate.publicKey.export({ type: 'spki', format: 'der' }))
+        .digest('hex');
+      if (actual !== caSpkiSha256) continue;
+      return stageBorgServerTrust(origin, pemCertificate(raw), `spki-sha256:${actual}`);
+    } catch {
+      // Ignore malformed chain members; the typed compatibility failure below is safer.
+    }
+  }
+  if (!sawCa) throw new InvitationArtifactCompatibilityError();
+  throw new InvitationArtifactTrustError();
+}
+
+export async function stageBorgServerTrust(
+  origin: string,
+  certificate: string,
+  identity: string,
+): Promise<StagedBorgServerTrust> {
+  const directory = remoteTrustDirectory(origin);
+  const parent = resolve(directory, '..');
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const suffix = `${process.pid}-${Date.now()}`;
+  const temporaryDirectory = `${directory}.tmp-${suffix}`;
+  const temporaryCertificate = join(temporaryDirectory, 'ca.crt');
+  const temporaryConfig = join(temporaryDirectory, 'server.json');
+  try {
+    await mkdir(temporaryDirectory, { recursive: false, mode: 0o700 });
+    await Promise.all([
+      writeFile(temporaryCertificate, certificate, { mode: 0o600, flag: 'wx' }),
+      writeFile(temporaryConfig, JSON.stringify({ ca_spki_sha256: identity.replace(/^spki-sha256:/, '') }), { mode: 0o600, flag: 'wx' }),
+    ]);
+    await Promise.all([syncPath(temporaryCertificate), syncPath(temporaryConfig), syncPath(temporaryDirectory)]);
+  } catch {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    throw new InvitationArtifactStorageError();
+  }
+  let committed = false;
+  return {
+    identity,
+    fetchImpl: createPinnedServerFetch(origin, certificate),
+    commitTrust: async (activate) => {
+      if (committed) return;
+      const backupDirectory = `${directory}.backup-${suffix}`;
+      let backedUp = false;
+      try {
+        await rename(directory, backupDirectory).then(() => { backedUp = true; }).catch((error: unknown) => {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        });
+        await rename(temporaryDirectory, directory);
+        await syncPath(resolve(directory, '..'));
+        await activate();
+        committed = true;
+        await rm(backupDirectory, { recursive: true, force: true }).catch(() => undefined);
+      } catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        await rm(temporaryDirectory, { recursive: true, force: true });
+        if (backedUp) {
+          await rename(backupDirectory, directory);
+          await syncPath(resolve(directory, '..'));
+        }
+        throw new InvitationArtifactRecoveryError();
+      }
+    },
+    discardTrust: async () => {
+      if (committed) return;
+      await rm(temporaryDirectory, { recursive: true, force: true });
+    },
+  };
+}
+
 export function __clearServerTrustCacheForTest(): void {
   trustCache.clear();
 }
+
+export async function clearBorgServerTrust(origin: string): Promise<void> {
+  await rm(remoteTrustDirectory(origin), { recursive: true, force: true });
+  trustCache.delete(`${serverDataDirectory()}\0${origin}`);
+}