borgmcp 2.0.11 → 2.1.0

package/src/repository-identity.ts

@@ -0,0 +1,199 @@
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { basename, isAbsolute, join } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import type { CreateCubeRepository, CubeTemplate } from 'borgmcp-shared/protocol';
+import { canonicalizeWorkingRepoIdentity } from './working-repo.js';
+import { normalizeCubeName } from './cube-name.js';
+import { borgConfigRoot, ensurePrivateBorgConfigRoot } from './private-root.js';
+import { atomicWrite0600, readStoreFile, withStoreLock } from './seat-store.js';
+
+const STORE_VERSION = 1;
+const SECRET_FILE = 'repository-identity.key';
+const STATE_FILE = 'repository-identities.json';
+const LOCK_FILE = 'repository-identities.lock';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DISPLAY_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+export interface GitRepositoryContext {
+  root: string;
+  commonDir: string;
+  derivedName: string;
+  publicRepository: Extract<CreateCubeRepository, { kind: 'origin' }> | null;
+  publicRepositoryName: string | null;
+}
+
+export interface RepositoryAssociation {
+  cubeId: string;
+  name: string;
+  workingRepoName: string;
+  template: CubeTemplate;
+}
+
+interface RepositoryIdentityState {
+  version: 1;
+  localIdentities: Record<string, string>;
+  associations: Record<string, RepositoryAssociation>;
+}
+
+export interface RepositoryIdentityDeps {
+  runGit?: (cwd: string, args: string[]) => { status: number | null; stdout?: string | null };
+  canonicalPath?: (path: string) => Promise<string>;
+  root?: string;
+}
+
+function defaultRunGit(cwd: string, args: string[]) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return { status: result.status, stdout: result.stdout };
+}
+
+function output(result: { status: number | null; stdout?: string | null }): string | null {
+  const value = result.status === 0 ? result.stdout?.trim() : null;
+  return value || null;
+}
+
+export async function resolveGitRepositoryContext(
+  cwd: string,
+  deps: RepositoryIdentityDeps = {},
+): Promise<GitRepositoryContext | null> {
+  const runGit = deps.runGit ?? defaultRunGit;
+  const canonicalPath = deps.canonicalPath ?? realpath;
+  const rootRaw = output(runGit(cwd, ['rev-parse', '--show-toplevel']));
+  if (!rootRaw || !isAbsolute(rootRaw)) return null;
+  const bare = output(runGit(cwd, ['rev-parse', '--is-bare-repository']));
+  if (bare === 'true') throw new Error('BARE_REPOSITORY');
+  const commonRaw = output(runGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  if (!commonRaw || !isAbsolute(commonRaw)) return null;
+  const root = await canonicalPath(rootRaw);
+  const commonDir = await canonicalPath(commonRaw);
+  const derivedName = normalizeCubeName(basename(root));
+  if (!derivedName) return null;
+
+  const originRaw = output(runGit(root, ['config', '--get', 'remote.origin.url']));
+  const canonical = originRaw ? canonicalizeWorkingRepoIdentity(originRaw) : null;
+  return {
+    root,
+    commonDir,
+    derivedName,
+    publicRepository: canonical?.origin
+      ? { kind: 'origin', value: canonical.origin }
+      : null,
+    publicRepositoryName: canonical?.name ?? null,
+  };
+}
+
+function parseSecret(raw: string | null): Buffer | null {
+  if (raw === null) return null;
+  if (!/^[a-f0-9]{64}$/.test(raw.trim())) {
+    throw new Error('Borg repository identity secret is malformed');
+  }
+  return Buffer.from(raw.trim(), 'hex');
+}
+
+function emptyState(): RepositoryIdentityState {
+  return { version: STORE_VERSION, localIdentities: {}, associations: {} };
+}
+
+function parseState(raw: string | null): RepositoryIdentityState {
+  if (raw === null) return emptyState();
+  const parsed = JSON.parse(raw) as Partial<RepositoryIdentityState>;
+  if (
+    parsed.version !== STORE_VERSION ||
+    !parsed.localIdentities || typeof parsed.localIdentities !== 'object' || Array.isArray(parsed.localIdentities) ||
+    !parsed.associations || typeof parsed.associations !== 'object' || Array.isArray(parsed.associations)
+  ) {
+    throw new Error('Borg repository identity store is malformed or unsupported');
+  }
+  for (const [key, value] of Object.entries(parsed.localIdentities)) {
+    if (!/^[a-f0-9]{64}$/.test(key) || typeof value !== 'string' || !UUID_RE.test(value)) {
+      throw new Error('Borg repository identity store is malformed or unsupported');
+    }
+  }
+  for (const [key, value] of Object.entries(parsed.associations)) {
+    if (
+      !/^[a-f0-9]{64}$/.test(key) ||
+      !value || typeof value !== 'object' || Array.isArray(value) ||
+      typeof value.cubeId !== 'string' || !UUID_RE.test(value.cubeId) ||
+      typeof value.name !== 'string' || Buffer.byteLength(value.name, 'utf8') > 120 ||
+      !DISPLAY_NAME_RE.test(value.name) ||
+      typeof value.workingRepoName !== 'string' || Buffer.byteLength(value.workingRepoName, 'utf8') > 120 ||
+      !DISPLAY_NAME_RE.test(value.workingRepoName) ||
+      (value.template !== 'software-dev' && value.template !== 'starter' && value.template !== 'default')
+    ) {
+      throw new Error('Borg repository identity store is malformed or unsupported');
+    }
+  }
+  return parsed as RepositoryIdentityState;
+}
+
+function digest(secret: Buffer, purpose: string, value: string): string {
+  return createHmac('sha256', secret).update(purpose).update('\0').update(value).digest('hex');
+}
+
+async function withIdentityState<T>(
+  operation: (secret: Buffer, state: RepositoryIdentityState) => Promise<{ result: T; changed?: boolean }>,
+  deps: RepositoryIdentityDeps = {},
+): Promise<T> {
+  const root = deps.root ?? borgConfigRoot();
+  await ensurePrivateBorgConfigRoot(root);
+  const options = { secureRoot: root, rootMode: 'private' as const };
+  return withStoreLock(join(root, LOCK_FILE), async () => {
+    const secretPath = join(root, SECRET_FILE);
+    let secret = parseSecret(await readStoreFile(secretPath, options));
+    if (!secret) {
+      secret = randomBytes(32);
+      await atomicWrite0600(secretPath, `${secret.toString('hex')}\n`, options);
+    }
+    const statePath = join(root, STATE_FILE);
+    const state = parseState(await readStoreFile(statePath, options));
+    const outcome = await operation(secret, state);
+    if (outcome.changed) {
+      await atomicWrite0600(statePath, `${JSON.stringify(state, null, 2)}\n`, options);
+    }
+    return outcome.result;
+  }, options);
+}
+
+export async function getOrCreateRepositoryIdentity(
+  context: GitRepositoryContext,
+  deps: RepositoryIdentityDeps = {},
+): Promise<CreateCubeRepository> {
+  if (context.publicRepository) return context.publicRepository;
+  return withIdentityState(async (secret, state) => {
+    const key = digest(secret, 'git-common-dir', context.commonDir);
+    let value = state.localIdentities[key];
+    let changed = false;
+    if (!value) {
+      value = randomUUID();
+      state.localIdentities[key] = value;
+      changed = true;
+    }
+    return { result: { kind: 'local' as const, value }, changed };
+  }, deps);
+}
+
+function associationBinding(secret: Buffer, trustIdentity: string, repository: CreateCubeRepository): string {
+  return digest(secret, 'association', `${trustIdentity}\0${repository.kind}\0${repository.value}`);
+}
+
+export async function getRepositoryAssociation(
+  trustIdentity: string,
+  repository: CreateCubeRepository,
+  deps: RepositoryIdentityDeps = {},
+): Promise<RepositoryAssociation | null> {
+  return withIdentityState(async (secret, state) => ({
+    result: state.associations[associationBinding(secret, trustIdentity, repository)] ?? null,
+  }), deps);
+}
+
+export async function saveRepositoryAssociation(
+  trustIdentity: string,
+  repository: CreateCubeRepository,
+  association: RepositoryAssociation,
+  deps: RepositoryIdentityDeps = {},
+): Promise<void> {
+  await withIdentityState(async (secret, state) => {
+    state.associations[associationBinding(secret, trustIdentity, repository)] = association;
+    return { result: undefined, changed: true };
+  }, deps);
+}

package/src/server-errors.ts

@@ -92,6 +92,20 @@ export class BorgServerUnreachableError extends Error {
   }
 }
 
+export class CubeCreationOutcomeUnknownError extends Error {
+  constructor() {
+    super('Cube creation outcome is unknown.');
+    this.name = 'CubeCreationOutcomeUnknownError';
+  }
+}
+
+export class CubeCreationConfirmationError extends Error {
+  constructor(message = 'The Borg server returned conflicting repository cube state.') {
+    super(message);
+    this.name = 'CubeCreationConfirmationError';
+  }
+}
+
 /** Exact retired TTL-replacement state: two saved bearers and no safe implicit winner. */
 export class LegacySessionCredentialCollisionError extends Error {
   constructor(public readonly origin: string) {

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

@@ -14,7 +14,9 @@ import {
   decodeProtocolErrorEnvelope,
   decodeProtocolTagPreflight,
   ErrorCode,
+  type CreateCubeRepository,
   type CreateCubeResponse,
+  type CubeTemplate,
   type DroneRuntimeMetadata,
   type ProtocolTagPreflight,
   type ServerCapability,
@@ -45,6 +47,8 @@ import {
   BorgServerError,
   BorgServerTrustError,
   BorgServerUnreachableError,
+  CubeCreationConfirmationError,
+  CubeCreationOutcomeUnknownError,
 } from './server-errors.js';
 import { DroneEvictedError, DRONE_EVICTED_CODE } from './drone-lifecycle.js';
 import { readBoundedResponseBody } from './server-response.js';
@@ -181,7 +185,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 v4.
  * 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 —
@@ -564,7 +568,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 +598,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 +635,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,7 +649,7 @@ 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})`);
@@ -648,6 +663,12 @@ export async function createBorgServerCube(
     if (error instanceof Error && error.message.includes('response limit')) throw error;
     throw new Error('Borg server returned an invalid cube creation envelope');
   }
+  if (
+    decoded.payload.repository.kind !== pending.repository.kind ||
+    decoded.payload.repository.value !== pending.repository.value
+  ) {
+    throw new CubeCreationConfirmationError();
+  }
   await (deps.clearCubeCreation ?? clearPendingServerCubeCreation)(
     pending as PendingServerCubeCreationRecord,
   );
@@ -658,7 +679,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);