borgmcp-server 0.1.1

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "borgmcp-server",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Self-hosted Borg coordination server",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byte-Ventures/borg-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Byte-Ventures/borg-mcp-server/issues"
+  },
+  "homepage": "https://github.com/Byte-Ventures/borg-mcp-server#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0",
+    "npm": ">=10.0.0"
+  },
+  "bin": {
+    "borg-mcp-server": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "SECURITY.md",
+    "THIRD_PARTY_NOTICES.md",
+    "npm-shrinkwrap.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run build && npm run typecheck && npm test",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify:artifact": "node scripts/verify-packed-artifact.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "borgmcp-shared": "0.3.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "dependencies": {
+    "selfsigned": "5.5.0"
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,127 @@
+import { createHash, randomBytes, randomUUID, X509Certificate } from "node:crypto";
+import { lstat, readFile, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { generate } from "selfsigned";
+
+import { CredentialAuthority, CredentialDigester } from "./credentials.js";
+import { openStore } from "./store.js";
+
+export interface BootstrapResult {
+  readonly serverId: string;
+  readonly caFingerprint: string;
+  readonly recoveryCredential: string;
+  readonly initialInvitation: string;
+  readonly paths: {
+    readonly database: string;
+    readonly digestKey: string;
+    readonly caKey: string;
+    readonly caCertificate: string;
+    readonly serverKey: string;
+    readonly serverCertificate: string;
+    readonly config: string;
+  };
+}
+
+export async function bootstrapServer(
+  dataDirectory: string,
+  bindHost = "127.0.0.1",
+  clock: () => Date = () => new Date(),
+): Promise<BootstrapResult> {
+  const directory = resolve(dataDirectory);
+  const paths = {
+    database: join(directory, "borg.db"),
+    digestKey: join(directory, "credential-digest.key"),
+    caKey: join(directory, "ca.key"),
+    caCertificate: join(directory, "ca.crt"),
+    serverKey: join(directory, "server.key"),
+    serverCertificate: join(directory, "server.crt"),
+    config: join(directory, "server.json"),
+  };
+  const ca = await generate([{ name: "commonName", value: "Borg Local CA" }], {
+    algorithm: "sha256",
+    keyType: "ec",
+    extensions: [
+      { name: "basicConstraints", cA: true, pathLenConstraint: 0, critical: true },
+      { name: "keyUsage", keyCertSign: true, cRLSign: true, critical: true },
+    ],
+  });
+  const server = await generate([{ name: "commonName", value: "Borg Local Server" }], {
+    algorithm: "sha256",
+    keyType: "ec",
+    ca: { key: ca.private, cert: ca.cert },
+    extensions: [
+      { name: "basicConstraints", cA: false, critical: true },
+      { name: "keyUsage", digitalSignature: true, keyAgreement: true, critical: true },
+      { name: "extKeyUsage", serverAuth: true },
+      { name: "subjectAltName", altNames: [{ type: 7, ip: bindHost }] },
+    ],
+  });
+  const serverId = randomUUID();
+  const caCertificate = new X509Certificate(ca.cert);
+  const caFingerprint = createHash("sha256")
+    .update(caCertificate.publicKey.export({ type: "spki", format: "der" }))
+    .digest("hex");
+  const digestKey = randomBytes(32);
+  const runtime = await openStore({ path: paths.database, clock });
+  try {
+    await Promise.all([
+      writePrivate(paths.digestKey, digestKey),
+      writePrivate(paths.caKey, ca.private),
+      writePrivate(paths.caCertificate, ca.cert),
+      writePrivate(paths.serverKey, server.private),
+      writePrivate(paths.serverCertificate, server.cert),
+      writePrivate(paths.config, JSON.stringify({
+        server_id: serverId,
+        ca_spki_sha256: caFingerprint,
+        bind_host: bindHost,
+      }, null, 2)),
+    ]);
+    const digester = new CredentialDigester(digestKey);
+    digestKey.fill(0);
+    try {
+      const authority = new CredentialAuthority(runtime.credentials, digester, clock);
+      const recoveryCredential = authority.createRecoveryCredential();
+      const initialInvitation = authority.createBootstrapInvitation(15 * 60_000);
+      return {
+        serverId,
+        caFingerprint,
+        recoveryCredential,
+        initialInvitation,
+        paths,
+      };
+    } finally {
+      digester.destroy();
+    }
+  } finally {
+    digestKey.fill(0);
+    runtime.close();
+  }
+}
+
+async function writePrivate(path: string, value: string | Buffer): Promise<void> {
+  await writeFile(path, value, { flag: "wx", mode: 0o600 });
+  if (((await stat(path)).mode & 0o777) !== 0o600) {
+    throw new Error("Bootstrap file permissions are not private.");
+  }
+}
+
+export async function loadDigestKey(path: string): Promise<Buffer> {
+  const key = await loadPrivateFile(path, "Credential digest key");
+  if (key.length !== 32) {
+    key.fill(0);
+    throw new Error("Credential digest key is invalid or not private.");
+  }
+  return key;
+}
+
+export async function loadTlsPrivateKey(path: string): Promise<Buffer> {
+  return loadPrivateFile(path, "TLS private key");
+}
+
+async function loadPrivateFile(path: string, label: string): Promise<Buffer> {
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || (metadata.mode & 0o077) !== 0) {
+    throw new Error(`${label} is invalid or not private.`);
+  }
+  return readFile(path);
+}

package/src/cli.ts

@@ -0,0 +1,102 @@
+import type { ServerService } from "./service.js";
+
+export interface CliIo {
+  readonly stdout: (message: string) => void;
+  readonly stderr: (message: string) => void;
+  readonly readSecret?: (prompt: string) => Promise<string>;
+}
+
+const usage = `Usage: borg-mcp-server <command> [options]
+
+Commands:
+  setup    Prepare an offline server installation
+  start    Start the server process
+  client-rotate <client-id>  Rotate one client credential offline
+  client-revoke <client-id>  Revoke one client and its credentials offline
+  client-grant <client-id> <cube-id> <read|write|manage>  Set one offline cube grant
+  client-ungrant <client-id> <cube-id>  Remove one offline cube grant
+  client-invite  Create one ordinary client invitation using a private recovery prompt
+  owner-invite   Replace the unclaimed owner invitation using a private recovery prompt
+  help     Show this help
+
+Start options:
+  --host <ip>      Explicit bind address (default: 127.0.0.1)
+  --port <number>  Listen port (default: 7091)
+  --lan            Consent to this start on a private LAN address
+
+TLS files:
+  BORG_SERVER_DATA_DIR (default: ~/.borg/server), or explicit
+  BORG_SERVER_TLS_KEY_FILE, BORG_SERVER_TLS_CERT_FILE, and BORG_SERVER_TLS_CA_FILE
+
+Stop the server before running offline client administration commands.`;
+
+export async function runCli(
+  args: readonly string[],
+  service: ServerService,
+  io: CliIo,
+): Promise<number> {
+  const [command, ...extraArgs] = args;
+
+  switch (command) {
+    case "setup":
+      if (extraArgs.length !== 0) return invalidArguments(io);
+      if (service.setup === undefined) {
+        io.stderr("Server setup is unavailable.");
+        return 1;
+      }
+      const result = await service.setup();
+      io.stdout(`Server setup complete.\nRecovery credential (shown once): ${result.recoveryCredential}\nInitial enrollment invitation (shown once): ${result.initialInvitation}`);
+      return 0;
+    case "start":
+      await service.start(extraArgs);
+      return 0;
+    case "client-rotate":
+      if (extraArgs.length !== 1 || service.rotateClient === undefined) return invalidArguments(io);
+      io.stdout(`Client credential rotated (shown once): ${await service.rotateClient(extraArgs[0]!)}`);
+      return 0;
+    case "client-revoke":
+      if (extraArgs.length !== 1 || service.revokeClient === undefined) return invalidArguments(io);
+      await service.revokeClient(extraArgs[0]!);
+      io.stdout("Client revoked.");
+      return 0;
+    case "client-grant": {
+      if (extraArgs.length !== 3 || service.grantClient === undefined) return invalidArguments(io);
+      const access = extraArgs[2];
+      if (access !== "read" && access !== "write" && access !== "manage") return invalidArguments(io);
+      await service.grantClient(extraArgs[0]!, extraArgs[1]!, access);
+      io.stdout("Client cube grant updated.");
+      return 0;
+    }
+    case "client-ungrant":
+      if (extraArgs.length !== 2 || service.ungrantClient === undefined) return invalidArguments(io);
+      await service.ungrantClient(extraArgs[0]!, extraArgs[1]!);
+      io.stdout("Client cube grant removed.");
+      return 0;
+    case "client-invite":
+    case "owner-invite": {
+      if (extraArgs.length !== 0 || io.readSecret === undefined) return invalidArguments(io);
+      const operation = command === "client-invite"
+        ? service.createClientInvitation
+        : service.replaceOwnerInvitation;
+      if (operation === undefined) return invalidArguments(io);
+      const recovery = await io.readSecret("Recovery credential: ");
+      const invitation = await operation(recovery);
+      io.stdout(`Enrollment invitation (shown once): ${invitation}`);
+      return 0;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      io.stdout(usage);
+      return 0;
+    default:
+      io.stderr("Unknown command.");
+      return 1;
+  }
+}
+
+function invalidArguments(io: CliIo): 1 {
+  io.stderr("Invalid command arguments.");
+  return 1;
+}