borgmcp 2.0.11 → 2.1.1

package/src/server-facade.ts

@@ -1,12 +1,14 @@
 import { spawn as spawnChild, type SpawnOptions } from 'node:child_process';
 import { constants } from 'node:os';
-import { serverHelpText } from './cli-help.js';
+import { cubeInitHelpText, isHelpFlag, serverHelpText } from './cli-help.js';
 
 export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'stop', 'status', 'update', 'invite'] as const;
 export type ServerLifecycleCommand = typeof SERVER_LIFECYCLE_COMMANDS[number];
 
 export type ParsedServerFacadeArgs =
   | { kind: 'help' }
+  | { kind: 'cube-init-help' }
+  | { kind: 'cube-init'; args: string[] }
   | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
   | { kind: 'error'; reason: 'unknown-command'; command: string };
 
@@ -15,6 +17,12 @@ export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFaca
   if (command === undefined || command === '--help' || command === '-h') {
     return { kind: 'help' };
   }
+  if (command === 'cube' && rest[0] === 'init') {
+    const args = rest.slice(1);
+    return args.some(isHelpFlag)
+      ? { kind: 'cube-init-help' }
+      : { kind: 'cube-init', args };
+  }
   if (!(SERVER_LIFECYCLE_COMMANDS as readonly string[]).includes(command)) {
     return { kind: 'error', reason: 'unknown-command', command };
   }
@@ -49,6 +57,12 @@ export interface ServerFacadeOutputDeps {
   writeStderr(text: string): void;
 }
 
+export interface ServerFacadeClientDeps {
+  cubeInit(args: readonly string[]): Promise<number>;
+}
+
+export type AssimilateDepsBuilder = typeof import('./assimilate-deps.js').buildDefaultAssimilateDeps;
+
 export type ServerFacadeProcessResult =
   | { kind: 'exited'; code: number }
   | { kind: 'signaled'; signal: NodeJS.Signals }
@@ -65,6 +79,31 @@ const defaultOutputDeps: ServerFacadeOutputDeps = {
   writeStderr: (text) => process.stderr.write(text),
 };
 
+export function buildDefaultServerFacadeClientDeps(
+  buildDeps?: AssimilateDepsBuilder,
+): ServerFacadeClientDeps {
+  return {
+    cubeInit: async (args) => {
+      const [{ parseAssimilateArgs }, { buildDefaultAssimilateDeps }, { runAssimilate }] = await Promise.all([
+        import('./parse-assimilate-args.js'),
+        import('./assimilate-deps.js'),
+        import('./assimilate-cmd.js'),
+      ]);
+      const parsed = parseAssimilateArgs([...args]);
+      if (!parsed.ok || parsed.role !== undefined) {
+        process.stderr.write(`${parsed.ok ? 'borg server cube init does not accept a role' : parsed.error}\n`);
+        return 1;
+      }
+      return runAssimilate(
+        { role: undefined, flags: parsed.flags, mode: 'cube-init' },
+        (buildDeps ?? buildDefaultAssimilateDeps)(),
+      );
+    },
+  };
+}
+
+const defaultClientDeps = buildDefaultServerFacadeClientDeps();
+
 const MAX_RENDERED_COMMAND_CODE_POINTS = 80;
 
 function inertCommand(command: string): string {
@@ -86,7 +125,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.\n` +
+    `Available commands: setup, start, stop, status, update, invite, cube init.\n` +
     `Next: run borg server --help.\n`
   );
 }
@@ -168,6 +207,7 @@ export async function runEarlyServerFacade(
   argv: readonly string[],
   deps: ServerFacadeProcessDeps = defaultProcessDeps,
   output: ServerFacadeOutputDeps = defaultOutputDeps,
+  client: ServerFacadeClientDeps = defaultClientDeps,
 ): Promise<number | null> {
   if (argv[2] !== 'server') return null;
   const parsed = parseServerFacadeArgs(argv.slice(3));
@@ -175,10 +215,15 @@ export async function runEarlyServerFacade(
     output.writeStdout(serverHelpText());
     return 0;
   }
+  if (parsed.kind === 'cube-init-help') {
+    output.writeStdout(cubeInitHelpText());
+    return 0;
+  }
   if (parsed.kind === 'error') {
     output.writeStderr(unknownServerCommandText(parsed.command));
     return 1;
   }
+  if (parsed.kind === 'cube-init') return client.cubeInit(parsed.args);
 
   const result = await runServerFacadeProcess(parsed, deps);
   if (result.kind === 'spawn-error') {

package/src/server-handshake.ts

@@ -4,8 +4,12 @@ import {
   ENROLLMENT_EXCHANGE_PATH,
   HEALTH_PATH,
   PROTOCOL_INFO_PATH,
+  REPOSITORY_CUBE_ASSOCIATION_PATH,
+  REPOSITORY_CUBE_RESOLVE_PATH,
   createAttachRequestEnvelope,
   createProtocolEnvelope,
+  decodeAssociateRepositoryCubeRequest,
+  decodeAssociateRepositoryCubeResponseEnvelope,
   decodeAttachResponseEnvelope,
   decodeCreateCubeRequest,
   decodeCreateCubeResponseEnvelope,
@@ -13,10 +17,16 @@ import {
   decodeEnrollmentExchangeResponseEnvelope,
   decodeProtocolErrorEnvelope,
   decodeProtocolTagPreflight,
+  decodeResolveRepositoryCubeRequest,
+  decodeResolveRepositoryCubeResponseEnvelope,
   ErrorCode,
+  type AssociateRepositoryCubeResponse,
+  type CreateCubeRepository,
   type CreateCubeResponse,
+  type CubeTemplate,
   type DroneRuntimeMetadata,
   type ProtocolTagPreflight,
+  type ResolveRepositoryCubeResponse,
   type ServerCapability,
 } from 'borgmcp-shared/protocol';
 import { createHash, randomUUID } from 'node:crypto';
@@ -45,6 +55,11 @@ import {
   BorgServerError,
   BorgServerTrustError,
   BorgServerUnreachableError,
+  CubeCreationConfirmationError,
+  CubeCreationOutcomeUnknownError,
+  RepositoryAssociationOperationError,
+  RepositoryAssociationOutcomeUnknownError,
+  RepositoryAssociationResolutionError,
 } from './server-errors.js';
 import { DroneEvictedError, DRONE_EVICTED_CODE } from './drone-lifecycle.js';
 import { readBoundedResponseBody } from './server-response.js';
@@ -181,7 +196,7 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v3.
+ * Attach an enrolled client principal to one granted cube/role over protocol v5.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
  * interrupted/lost response is recovered by re-sending the exact same bearer —
@@ -554,6 +569,210 @@ export async function resumeBorgServerEnrollment(
   });
 }
 
+async function requireMatchingServerCredential(
+  origin: string,
+  trustIdentity: string,
+  parentCredential: string,
+  loadCredentialRecord: typeof getServerCredentialRecord,
+): Promise<void> {
+  const active = await loadCredentialRecord(origin, trustIdentity);
+  if (!active || active.credential !== parentCredential || !active.clientId) {
+    throw new BorgServerError('CREDENTIAL_REJECTED', 'stored Borg server credential was rejected');
+  }
+}
+
+async function protocolErrorCode(response: Response): Promise<ErrorCode | undefined> {
+  try {
+    return decodeProtocolErrorEnvelope(
+      JSON.parse(await readHandshakeBodyWithTimeout(response)),
+    ).error.code;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve one client-scoped repository association without mutation. */
+export async function resolveBorgServerRepositoryCube(
+  origin: string,
+  trustIdentity: string,
+  parentCredential: string,
+  input: { workingRepoName: string; repository: CreateCubeRepository },
+  deps: {
+    fetchImpl?: FetchLike;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+  } = {},
+): Promise<ResolveRepositoryCubeResponse> {
+  await requireMatchingServerCredential(
+    origin,
+    trustIdentity,
+    parentCredential,
+    deps.loadCredentialRecord ?? getServerCredentialRecord,
+  );
+  const request = decodeResolveRepositoryCubeRequest({
+    working_repo_name: input.workingRepoName,
+    repository: input.repository,
+  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), HANDSHAKE_TIMEOUT_MS);
+  let response: Response;
+  try {
+    response = await (deps.fetchImpl ?? fetch)(handshakeUrl(origin, REPOSITORY_CUBE_RESOLVE_PATH), {
+      method: 'POST',
+      redirect: 'error',
+      signal: controller.signal,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${parentCredential}`,
+      },
+      body: JSON.stringify(createProtocolEnvelope(randomUUID(), request)),
+    });
+  } catch (error) {
+    throw new RepositoryAssociationResolutionError();
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server enrollment was rejected');
+  }
+  if (response.status !== 200) {
+    throw new RepositoryAssociationResolutionError();
+  }
+  try {
+    const decoded = decodeResolveRepositoryCubeResponseEnvelope(
+      JSON.parse(await readHandshakeBodyWithTimeout(response)),
+    ).payload;
+    if (
+      decoded.result === 'resolved' &&
+      (decoded.repository.kind !== request.repository.kind ||
+        decoded.repository.value !== request.repository.value ||
+        decoded.working_repo_name !== request.working_repo_name)
+    ) {
+      throw new Error('association mismatch');
+    }
+    return decoded;
+  } catch {
+    throw new RepositoryAssociationResolutionError();
+  }
+}
+
+export async function resolveLocalBorgServerRepositoryCube(
+  origin: string,
+  trustIdentity: string,
+  parentCredential: string,
+  input: { workingRepoName: string; repository: CreateCubeRepository },
+  deps: { loadTrust?: typeof loadBorgServerTrust } = {},
+): Promise<ResolveRepositoryCubeResponse> {
+  const trust = await (deps.loadTrust ?? loadBorgServerTrust)(origin);
+  if (trust.identity !== trustIdentity) {
+    throw new BorgServerTrustError('Borg server trust identity changed; refusing repository resolution');
+  }
+  return resolveBorgServerRepositoryCube(origin, trustIdentity, parentCredential, input, {
+    fetchImpl: trust.fetchImpl,
+  });
+}
+
+/** Atomically associate an explicit accessible cube after local confirmation. */
+export async function associateBorgServerRepositoryCube(
+  origin: string,
+  trustIdentity: string,
+  parentCredential: string,
+  input: { cubeId: string; workingRepoName: string; repository: CreateCubeRepository },
+  deps: {
+    fetchImpl?: FetchLike;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+  } = {},
+): Promise<AssociateRepositoryCubeResponse> {
+  await requireMatchingServerCredential(
+    origin,
+    trustIdentity,
+    parentCredential,
+    deps.loadCredentialRecord ?? getServerCredentialRecord,
+  );
+  const request = decodeAssociateRepositoryCubeRequest({
+    cube_id: input.cubeId,
+    working_repo_name: input.workingRepoName,
+    repository: input.repository,
+  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), HANDSHAKE_TIMEOUT_MS);
+  let response: Response;
+  try {
+    response = await (deps.fetchImpl ?? fetch)(handshakeUrl(origin, REPOSITORY_CUBE_ASSOCIATION_PATH), {
+      method: 'PUT',
+      redirect: 'error',
+      signal: controller.signal,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${parentCredential}`,
+      },
+      body: JSON.stringify(createProtocolEnvelope(randomUUID(), request)),
+    });
+  } catch {
+    throw new RepositoryAssociationOutcomeUnknownError();
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (response.status === 401) {
+    throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server enrollment was rejected');
+  }
+  if (response.status === 403) {
+    if (await protocolErrorCode(response) !== ErrorCode.ACCESS_DENIED) {
+      throw new RepositoryAssociationOutcomeUnknownError();
+    }
+    throw new RepositoryAssociationOperationError('access-denied');
+  }
+  if (response.status === 409) {
+    const code = await protocolErrorCode(response);
+    if (code === ErrorCode.REPOSITORY_ALREADY_ASSOCIATED) {
+      throw new RepositoryAssociationOperationError('repository-already-associated');
+    }
+    if (code === ErrorCode.CUBE_ALREADY_ASSOCIATED) {
+      throw new RepositoryAssociationOperationError('cube-already-associated');
+    }
+    if (code === ErrorCode.INVALID_INPUT) {
+      throw new RepositoryAssociationOperationError('invalid-cube');
+    }
+    throw new RepositoryAssociationOutcomeUnknownError();
+  }
+  if (response.status !== 200) {
+    throw new RepositoryAssociationOutcomeUnknownError();
+  }
+  try {
+    const decoded = decodeAssociateRepositoryCubeResponseEnvelope(
+      JSON.parse(await readHandshakeBodyWithTimeout(response)),
+    ).payload;
+    if (
+      decoded.cube_id !== request.cube_id ||
+      decoded.repository.kind !== request.repository.kind ||
+      decoded.repository.value !== request.repository.value ||
+      decoded.working_repo_name !== request.working_repo_name
+    ) {
+      throw new Error('association mismatch');
+    }
+    return decoded;
+  } catch (error) {
+    throw new RepositoryAssociationOutcomeUnknownError();
+  }
+}
+
+export async function associateLocalBorgServerRepositoryCube(
+  origin: string,
+  trustIdentity: string,
+  parentCredential: string,
+  input: { cubeId: string; workingRepoName: string; repository: CreateCubeRepository },
+  deps: { loadTrust?: typeof loadBorgServerTrust } = {},
+): Promise<AssociateRepositoryCubeResponse> {
+  const trust = await (deps.loadTrust ?? loadBorgServerTrust)(origin);
+  if (trust.identity !== trustIdentity) {
+    throw new BorgServerTrustError('Borg server trust identity changed; refusing repository association');
+  }
+  return associateBorgServerRepositoryCube(origin, trustIdentity, parentCredential, input, {
+    fetchImpl: trust.fetchImpl,
+  });
+}
+
 /**
  * Create one repository cube through the narrow owner capability. The retry
  * key is persisted in the OS keychain before network I/O and reused exactly
@@ -564,7 +783,12 @@ export async function createBorgServerCube(
   origin: string,
   trustIdentity: string,
   parentCredential: string,
-  input: { projectRoot: string; name: string },
+  input: {
+    name: string;
+    workingRepoName: string;
+    repository: CreateCubeRepository;
+    template: CubeTemplate;
+  },
   deps: {
     fetchImpl?: FetchLike;
     loadCredentialRecord?: typeof getServerCredentialRecord;
@@ -589,13 +813,16 @@ export async function createBorgServerCube(
     origin,
     trustIdentity,
     clientId: active.clientId,
-    projectRoot: input.projectRoot,
     name: input.name,
-    template: 'default',
+    workingRepoName: input.workingRepoName,
+    repository: input.repository,
+    template: input.template,
   });
   const request = decodeCreateCubeRequest({
     retry_key: pending.retryKey,
     name: pending.name,
+    working_repo_name: pending.workingRepoName,
+    repository: pending.repository,
     template: pending.template,
   });
 
@@ -623,7 +850,10 @@ export async function createBorgServerCube(
       clearTimeout(timeout);
     }
   }
-  if (!response) throw lastTransportError;
+  if (!response) {
+    void lastTransportError;
+    throw new CubeCreationOutcomeUnknownError();
+  }
   if (response.status === 401 || response.status === 403) {
     throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server enrollment was rejected');
   }
@@ -634,23 +864,32 @@ export async function createBorgServerCube(
     );
   }
   if (response.status === 409) {
-    throw new Error('Borg server cube creation retry state conflicted');
+    throw new CubeCreationConfirmationError('The Borg server rejected the repository cube operation identity.');
   }
   if (response.status !== 201) {
-    throw new Error(`Borg server cube creation failed (HTTP ${response.status})`);
+    throw new CubeCreationOutcomeUnknownError();
   }
   let decoded: ReturnType<typeof decodeCreateCubeResponseEnvelope>;
   try {
     decoded = decodeCreateCubeResponseEnvelope(
       JSON.parse(await readHandshakeBodyWithTimeout(response)),
     );
-  } catch (error) {
-    if (error instanceof Error && error.message.includes('response limit')) throw error;
-    throw new Error('Borg server returned an invalid cube creation envelope');
+  } catch {
+    throw new CubeCreationOutcomeUnknownError();
+  }
+  if (
+    decoded.payload.repository.kind !== pending.repository.kind ||
+    decoded.payload.repository.value !== pending.repository.value
+  ) {
+    throw new CubeCreationConfirmationError();
+  }
+  try {
+    await (deps.clearCubeCreation ?? clearPendingServerCubeCreation)(
+      pending as PendingServerCubeCreationRecord,
+    );
+  } catch {
+    throw new CubeCreationConfirmationError('The server confirmed the cube, but local retry state could not be finalized.');
   }
-  await (deps.clearCubeCreation ?? clearPendingServerCubeCreation)(
-    pending as PendingServerCubeCreationRecord,
-  );
   return decoded.payload;
 }
 
@@ -658,7 +897,12 @@ export async function createLocalBorgServerCube(
   origin: string,
   trustIdentity: string,
   parentCredential: string,
-  input: { projectRoot: string; name: string },
+  input: {
+    name: string;
+    workingRepoName: string;
+    repository: CreateCubeRepository;
+    template: CubeTemplate;
+  },
   deps: { loadTrust?: typeof loadBorgServerTrust } = {},
 ): Promise<CreateCubeResponse> {
   const trust = await (deps.loadTrust ?? loadBorgServerTrust)(origin);