borgmcp-server 0.1.1

package/src/credentials.ts

@@ -0,0 +1,319 @@
+import {
+  createHmac,
+  randomBytes,
+  randomUUID,
+  timingSafeEqual,
+} from "node:crypto";
+
+import {
+  clientPrincipal,
+  droneSessionPrincipal,
+  type Principal,
+} from "./principal.js";
+import type {
+  CredentialStore,
+  DigestPair,
+  ScopedStore,
+  SeatAttachRecord,
+} from "./store.js";
+import { operatorErrors } from "./operator-error.js";
+
+const tokenPattern = /^[A-Za-z0-9_-]{43,1024}$/u;
+const dummyVerifier = Buffer.alloc(32);
+type CredentialPurpose = "recovery" | "invitation" | "client" | "drone-session";
+
+export interface EnrollmentRequest {
+  readonly invitation: string;
+  readonly retryKey: string;
+  readonly clientCredential: string;
+  readonly clientName?: string;
+}
+
+export interface EnrollmentResponse {
+  readonly purpose: "owner" | "client";
+  readonly clientId: string;
+  readonly serverCapabilities: readonly [] | readonly ["create_cube"];
+}
+
+export interface SeatAttachResponse extends SeatAttachRecord {
+  readonly credential: string;
+}
+
+export class CredentialDigester {
+  readonly #key: Buffer;
+
+  constructor(key: Buffer) {
+    if (key.length !== 32) throw new Error("Credential digest key must contain 32 bytes.");
+    this.#key = Buffer.from(key);
+  }
+
+  digest(secret: string, purpose: CredentialPurpose): DigestPair {
+    if (!tokenPattern.test(secret)) throw new Error("Credential must be unpadded base64url.");
+    const lookup = createHmac("sha256", this.#key)
+      .update(`lookup:${purpose}:`)
+      .update(secret)
+      .digest()
+      .subarray(0, 16);
+    const verifier = createHmac("sha256", this.#key)
+      .update(`verify:${purpose}:`)
+      .update(secret)
+      .digest();
+    return { lookup, verifier };
+  }
+
+  verify(secret: string, purpose: CredentialPurpose, stored?: Buffer): boolean {
+    let candidate: Buffer;
+    let valid = true;
+    try {
+      candidate = this.digest(secret, purpose).verifier;
+    } catch {
+      candidate = dummyVerifier;
+      valid = false;
+    }
+    const expected = stored?.length === 32 ? stored : dummyVerifier;
+    return timingSafeEqual(candidate, expected) && stored !== undefined && valid;
+  }
+
+  destroy(): void {
+    this.#key.fill(0);
+  }
+}
+
+export class LiveCredentialRegistry {
+  readonly #sessions = new Map<string, Set<AbortController>>();
+  readonly #keys = new Map<AbortController, readonly string[]>();
+
+  register(identities: string | readonly string[]): {
+    readonly signal: AbortSignal;
+    readonly release: () => void;
+  } {
+    const controller = new AbortController();
+    const keys = [...new Set(typeof identities === "string" ? [identities] : identities)];
+    this.#keys.set(controller, keys);
+    for (const key of keys) {
+      const sessions = this.#sessions.get(key) ?? new Set<AbortController>();
+      sessions.add(controller);
+      this.#sessions.set(key, sessions);
+    }
+    return {
+      signal: controller.signal,
+      release: () => this.#release(controller),
+    };
+  }
+
+  invalidate(identity: string): void {
+    const sessions = this.#sessions.get(identity);
+    if (sessions === undefined) return;
+    for (const controller of [...sessions]) {
+      this.#release(controller);
+      controller.abort();
+    }
+  }
+
+  activeSessionCount(clientId: string): number {
+    return this.#sessions.get(clientId)?.size ?? 0;
+  }
+
+  #release(controller: AbortController): void {
+    const keys = this.#keys.get(controller);
+    if (keys === undefined) return;
+    this.#keys.delete(controller);
+    for (const key of keys) {
+      const sessions = this.#sessions.get(key);
+      sessions?.delete(controller);
+      if (sessions?.size === 0) this.#sessions.delete(key);
+    }
+  }
+}
+
+export class CredentialAuthority {
+  readonly #store: CredentialStore;
+  readonly #digester: CredentialDigester;
+  readonly #clock: () => Date;
+  readonly #registry: LiveCredentialRegistry;
+
+  constructor(
+    store: CredentialStore,
+    digester: CredentialDigester,
+    clock: () => Date = () => new Date(),
+    registry = new LiveCredentialRegistry(),
+  ) {
+    this.#store = store;
+    this.#digester = digester;
+    this.#clock = clock;
+    this.#registry = registry;
+  }
+
+  createRecoveryCredential(): string {
+    const secret = generateSecret();
+    this.#store.createRecoveryCredential(
+      randomUUID(),
+      this.#digester.digest(secret, "recovery"),
+    );
+    return secret;
+  }
+
+  createBootstrapInvitation(ttlMs: number): string {
+    return this.#createInvitation("owner", ttlMs);
+  }
+
+  createInvitation(recoveryCredential: string, ttlMs: number): string | null {
+    const digest = safeDigest(this.#digester, recoveryCredential, "recovery");
+    const stored = this.#store.findRecoveryCredential(digest.lookup);
+    if (!this.#digester.verify(recoveryCredential, "recovery", stored?.verifier)) return null;
+    return this.#createInvitation("client", ttlMs);
+  }
+
+  replaceOwnerInvitation(recoveryCredential: string, ttlMs: number): string | null {
+    const digest = safeDigest(this.#digester, recoveryCredential, "recovery");
+    const stored = this.#store.findRecoveryCredential(digest.lookup);
+    if (!this.#digester.verify(recoveryCredential, "recovery", stored?.verifier)) return null;
+    return this.#createInvitation("owner", ttlMs);
+  }
+
+  #createInvitation(purpose: "owner" | "client", ttlMs: number): string {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1_000 || ttlMs > 86_400_000) {
+      throw new Error("Invitation TTL must be an integer from 1000 to 86400000 milliseconds.");
+    }
+    const secret = generateSecret();
+    this.#store.createInvitation({
+      id: randomUUID(),
+      digest: this.#digester.digest(secret, "invitation"),
+      expiresAt: new Date(this.#clock().getTime() + ttlMs).toISOString(),
+      purpose,
+    });
+    return secret;
+  }
+
+  exchangeInvitation(request: EnrollmentRequest): EnrollmentResponse | null {
+    const invitationDigest = safeDigest(this.#digester, request.invitation, "invitation");
+    const stored = this.#store.findInvitation(invitationDigest.lookup);
+    const verified = this.#digester.verify(
+      request.invitation,
+      "invitation",
+      stored?.verifier,
+    );
+    const clientId = randomUUID();
+    const claimed = this.#store.claimInvitation({
+      invitationId: stored?.id ?? "00000000-0000-4000-8000-000000000000",
+      clientId,
+      requestedClientName: request.clientName ?? null,
+      retryKey: request.retryKey,
+      credentialId: randomUUID(),
+      credentialDigest: safeDigest(this.#digester, request.clientCredential, "client"),
+    });
+    return !verified || stored?.expiresAt === undefined || claimed === null ? null : {
+      purpose: claimed.purpose,
+      clientId: claimed.clientId,
+      serverCapabilities: claimed.serverCapabilities,
+    };
+  }
+
+  authenticate(authorization: string | undefined): Principal | null {
+    const result = this.authenticateStatus(authorization);
+    return typeof result === "object" ? result : null;
+  }
+
+  authenticateStatus(
+    authorization: string | undefined,
+  ): Principal | "missing" | "invalid" | "revoked" {
+    if (authorization === undefined) return "missing";
+    const secret = bearerSecret(authorization);
+    const clientDigest = safeDigest(this.#digester, secret, "client");
+    const droneDigest = safeDigest(this.#digester, secret, "drone-session");
+    const client = this.#store.findClientCredential(clientDigest.lookup);
+    const drone = this.#store.findDroneSessionCredential(droneDigest.lookup);
+    const clientValid = this.#digester.verify(secret, "client", client?.verifier) &&
+      client?.clientId !== undefined;
+    const droneValid = this.#digester.verify(secret, "drone-session", drone?.verifier) &&
+      drone !== null;
+    if (clientValid) {
+      if (client!.revokedAt != null) return "revoked";
+      return clientPrincipal(client!.clientId!);
+    }
+    if (droneValid) {
+      if (drone!.revokedAt != null || drone!.expiresAt <= this.#clock().toISOString()) {
+        return "revoked";
+      }
+      return droneSessionPrincipal({
+        id: drone!.sessionId,
+        clientId: drone!.clientId,
+        cubeId: drone!.cubeId,
+        droneId: drone!.droneId,
+      });
+    }
+    return "invalid";
+  }
+
+  attachSeat(
+    store: ScopedStore,
+    request: {
+      readonly cubeId: string;
+      readonly roleId: string;
+      readonly retryKey: string;
+      readonly priorDroneId?: string;
+    },
+  ): SeatAttachResponse {
+    const credential = generateSecret();
+    const record = store.attachSeat({
+      ...request,
+      droneId: randomUUID(),
+      sessionId: randomUUID(),
+      credentialId: randomUUID(),
+      credentialDigest: this.#digester.digest(credential, "drone-session"),
+      expiresAt: new Date(this.#clock().getTime() + 86_400_000).toISOString(),
+    });
+    for (const sessionId of record.revokedSessionIds) this.#registry.invalidate(sessionId);
+    return { ...record, credential };
+  }
+
+  rotateClient(clientId: string): string {
+    if (!this.#store.clientIsActive(clientId)) throw operatorErrors.CLIENT_NOT_FOUND;
+    const secret = generateSecret();
+    const rotated = this.#store.rotateClientCredential({
+      clientId,
+      credentialId: randomUUID(),
+      credentialDigest: this.#digester.digest(secret, "client"),
+    });
+    if (!rotated) throw operatorErrors.CLIENT_NOT_FOUND;
+    this.#registry.invalidate(clientId);
+    return secret;
+  }
+
+  revokeClient(clientId: string): void {
+    if (!this.#store.clientExists(clientId)) throw operatorErrors.CLIENT_NOT_FOUND;
+    this.#store.revokeClientCredentials(clientId);
+    this.#registry.invalidate(clientId);
+  }
+
+  registerLiveSession(principal: string | Principal) {
+    if (typeof principal === "string") return this.#registry.register(principal);
+    return this.#registry.register(
+      principal.kind === "drone-session"
+        ? [principal.id, principal.clientId]
+        : principal.id,
+    );
+  }
+}
+
+export function generateSecret(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+function bearerSecret(authorization: string | undefined): string {
+  if (authorization === undefined) return "";
+  const match = /^Bearer ([A-Za-z0-9_-]{43,1024})$/u.exec(authorization);
+  return match?.[1] ?? "";
+}
+
+function safeDigest(
+  digester: CredentialDigester,
+  secret: string,
+  purpose: CredentialPurpose,
+): DigestPair {
+  try {
+    return digester.digest(secret, purpose);
+  } catch {
+    return { lookup: Buffer.alloc(16), verifier: dummyVerifier };
+  }
+}

package/src/enrollment.ts

@@ -0,0 +1,156 @@
+import type { CredentialAuthority } from "./credentials.js";
+import { StorageCapacityError } from "./store.js";
+
+interface EnrollmentEnvelope {
+  readonly protocol_version: "1";
+  readonly request_id: string;
+  readonly payload: {
+    readonly invitation: string;
+    readonly retry_key: string;
+    readonly client_credential: string;
+    readonly client_name?: string;
+  };
+}
+
+export function createEnrollmentExchange(authority: CredentialAuthority) {
+  return async (body: unknown): Promise<{
+    readonly status: 201 | 400 | 401 | 507;
+    readonly body?: unknown;
+  }> => {
+    let envelope: EnrollmentEnvelope;
+    try {
+      envelope = decodeEnrollmentEnvelope(body);
+    } catch {
+      return {
+        status: 400,
+        body: errorEnvelope(
+          "INVALID_INPUT",
+          "Invalid enrollment request.",
+          safeRequestId(body),
+        ),
+      };
+    }
+    let response;
+    try {
+      response = authority.exchangeInvitation({
+        invitation: envelope.payload.invitation,
+        retryKey: envelope.payload.retry_key,
+        clientCredential: envelope.payload.client_credential,
+        ...(envelope.payload.client_name === undefined
+          ? {}
+          : { clientName: envelope.payload.client_name }),
+      });
+    } catch (error) {
+      if (!(error instanceof StorageCapacityError)) throw error;
+      return {
+        status: 507,
+        body: errorEnvelope("CAPACITY_EXCEEDED", error.message, envelope.request_id),
+      };
+    }
+    if (response === null) {
+      return {
+        status: 401,
+        body: errorEnvelope(
+          "AUTH_INVALID",
+          "Enrollment authentication failed.",
+          envelope.request_id,
+        ),
+      };
+    }
+    return {
+      status: 201,
+      body: {
+        protocol_version: "1",
+        request_id: envelope.request_id,
+        payload: {
+          purpose: response.purpose,
+          client_id: response.clientId,
+          server_capabilities: response.serverCapabilities,
+        },
+      },
+    };
+  };
+}
+
+function errorEnvelope(
+  code: "INVALID_INPUT" | "AUTH_INVALID" | "CAPACITY_EXCEEDED",
+  message: string,
+  requestId?: string,
+) {
+  return {
+    protocol_version: "1" as const,
+    ...(requestId === undefined ? {} : { request_id: requestId }),
+    error: { code, message },
+  };
+}
+
+function safeRequestId(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const requestId = (value as Record<string, unknown>)["request_id"];
+  return typeof requestId === "string" && /^[A-Za-z0-9._-]{8,128}$/u.test(requestId)
+    ? requestId
+    : undefined;
+}
+
+export function decodeEnrollmentEnvelope(value: unknown): EnrollmentEnvelope {
+  const envelope = exactRecord(value, ["protocol_version", "request_id", "payload"]);
+  if (envelope["protocol_version"] !== "1") throw new Error("Invalid enrollment request.");
+  const requestId = envelope["request_id"];
+  if (typeof requestId !== "string" || !/^[A-Za-z0-9._-]{8,128}$/u.test(requestId)) {
+    throw new Error("Invalid enrollment request.");
+  }
+  const payload = exactRecord(
+    envelope["payload"],
+    ["invitation", "retry_key", "client_credential"],
+    ["client_name"],
+  );
+  const invitation = payload["invitation"];
+  if (typeof invitation !== "string" || !/^[A-Za-z0-9_-]{43,1024}$/u.test(invitation)) {
+    throw new Error("Invalid enrollment request.");
+  }
+  const retryKey = payload["retry_key"];
+  if (typeof retryKey !== "string" ||
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(retryKey)) {
+    throw new Error("Invalid enrollment request.");
+  }
+  const clientCredential = payload["client_credential"];
+  if (typeof clientCredential !== "string" ||
+      !/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/u.test(clientCredential)) {
+    throw new Error("Invalid enrollment request.");
+  }
+  const clientName = payload["client_name"];
+  if (clientName !== undefined &&
+      (typeof clientName !== "string" || Buffer.byteLength(clientName) > 120 ||
+       !/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/u.test(clientName))) {
+    throw new Error("Invalid enrollment request.");
+  }
+  return {
+    protocol_version: "1",
+    request_id: requestId,
+    payload: clientName === undefined
+      ? { invitation, retry_key: retryKey.toLowerCase(), client_credential: clientCredential }
+      : {
+          invitation,
+          retry_key: retryKey.toLowerCase(),
+          client_credential: clientCredential,
+          client_name: clientName,
+        },
+  };
+}
+
+function exactRecord(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Invalid enrollment request.");
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set([...required, ...optional]);
+  if (Object.keys(record).some((key) => !allowed.has(key)) ||
+      required.some((key) => !Object.hasOwn(record, key))) {
+    throw new Error("Invalid enrollment request.");
+  }
+  return record;
+}