borgmcp-server 0.1.1 → 0.1.4

package/src/coordination-api.ts

@@ -1,11 +1,16 @@
+import { randomUUID } from "node:crypto";
 import type { Principal } from "./principal.js";
 import { assertServerDerivedPrincipal } from "./principal.js";
+import { disabledDebugLogger, type DebugLogger } from "./debug-log.js";
 import type { CredentialAuthority } from "./credentials.js";
 import {
   CursorExpiredError,
   AttachConflictError,
   AccessDeniedError,
   CreateCubeConflictError,
+  DefaultRoleRequiredError,
+  RoleConflictError,
+  RoleSectionConflictError,
   ScopedStoreError,
   StorageCapacityError,
   type EnrichedActivityRecord,
@@ -42,11 +47,17 @@ interface ReplayBarrier {
 export class CoordinationApi {
   readonly #runtime: StoreRuntime;
   readonly #authority: CredentialAuthority;
+  readonly #debugLogger: DebugLogger;
   #replayBarrier: ReplayBarrier | undefined;
 
-  constructor(runtime: StoreRuntime, authority: CredentialAuthority) {
+  constructor(
+    runtime: StoreRuntime,
+    authority: CredentialAuthority,
+    debugLogger: DebugLogger = disabledDebugLogger,
+  ) {
     this.#runtime = runtime;
     this.#authority = authority;
+    this.#debugLogger = debugLogger;
   }
 
   armReplayTransition(): { readonly reached: Promise<void>; readonly release: () => void } {
@@ -92,6 +103,7 @@ export class CoordinationApi {
             token: attachment.credential,
             expires_at: attachment.expiresAt,
             generation: attachment.generation,
+            posture: attachment.posture,
           },
           reattached: attachment.reattached,
         });
@@ -159,14 +171,20 @@ export class CoordinationApi {
       }
     }
 
+    const roleMatch = /^\/api\/cubes\/([0-9a-f-]{36})\/roles\/([0-9a-f-]{36})(\/section-patch)?$/u
+      .exec(request.path);
     const match = /^\/api\/cubes\/([0-9a-f-]{36})(?:\/(roles|drones|logs|acks|decisions|stream))?$/u
       .exec(request.path);
-    if (match === null) return failure(404, "NOT_FOUND", "The requested resource was not found.");
-    const cubeId = match[1]!;
-    if (!uuidPattern.test(cubeId)) {
+    if (match === null && roleMatch === null) {
+      return failure(404, "NOT_FOUND", "The requested resource was not found.");
+    }
+    const cubeId = (roleMatch?.[1] ?? match?.[1])!;
+    const roleId = roleMatch?.[2];
+    if (!uuidPattern.test(cubeId) || (roleId !== undefined && !uuidPattern.test(roleId))) {
       return failure(404, "NOT_FOUND", "The requested resource was not found.");
     }
-    const resource = match[2];
+    const resource = roleMatch === null ? match?.[2] : "role";
+    const sectionPatch = roleMatch?.[3] !== undefined;
     const store = this.#runtime.forPrincipal(authentication);
 
     try {
@@ -187,6 +205,95 @@ export class CoordinationApi {
       if (resource === "roles" && request.method === "GET") {
         return success(200, "roles-read", { roles: store.listRoles(cubeId) });
       }
+      if (resource === "roles" && request.method === "POST") {
+        const envelope = decodeEnvelope(request.body);
+        exactKeys(envelope.payload, ["name"], [
+          "short_description",
+          "detailed_description",
+          "is_default",
+          "is_mandatory",
+          "is_human_seat",
+          "can_broadcast",
+          "receives_all_direct",
+        ]);
+        const role = store.createRole(cubeId, {
+          name: requiredRoleName(envelope.payload, "name"),
+          shortDescription: optionalText(envelope.payload, "short_description", 1_024) ?? "",
+          detailedDescription: optionalText(envelope.payload, "detailed_description", 51_200) ?? "",
+          isDefault: optionalBoolean(envelope.payload["is_default"]),
+          isMandatory: optionalBoolean(envelope.payload["is_mandatory"]),
+          isHumanSeat: optionalBoolean(envelope.payload["is_human_seat"]),
+          canBroadcast: optionalBoolean(envelope.payload["can_broadcast"]),
+          receivesAllDirect: optionalBoolean(envelope.payload["receives_all_direct"]),
+        });
+        return success(201, envelope.requestId, { role });
+      }
+      if (resource === "role" && !sectionPatch && request.method === "PATCH") {
+        const envelope = decodeEnvelope(request.body);
+        exactKeys(envelope.payload, [], [
+          "name",
+          "short_description",
+          "detailed_description",
+          "is_default",
+          "is_mandatory",
+          "is_human_seat",
+          "can_broadcast",
+          "receives_all_direct",
+        ]);
+        if (Object.keys(envelope.payload).length === 0) throw new InputError();
+        const name = envelope.payload["name"] === undefined
+          ? undefined
+          : requiredRoleName(envelope.payload, "name");
+        const shortDescription = optionalText(envelope.payload, "short_description", 1_024);
+        const detailedDescription = optionalText(envelope.payload, "detailed_description", 51_200);
+        const isDefault = optionalBooleanValue(envelope.payload["is_default"]);
+        const isMandatory = optionalBooleanValue(envelope.payload["is_mandatory"]);
+        const isHumanSeat = optionalBooleanValue(envelope.payload["is_human_seat"]);
+        const canBroadcast = optionalBooleanValue(envelope.payload["can_broadcast"]);
+        const receivesAllDirect = optionalBooleanValue(envelope.payload["receives_all_direct"]);
+        const role = store.updateRole(cubeId, roleId!, {
+          ...(name === undefined ? {} : { name }),
+          ...(shortDescription === undefined ? {} : { shortDescription }),
+          ...(detailedDescription === undefined ? {} : { detailedDescription }),
+          ...(isDefault === undefined ? {} : { isDefault }),
+          ...(isMandatory === undefined ? {} : { isMandatory }),
+          ...(isHumanSeat === undefined ? {} : { isHumanSeat }),
+          ...(canBroadcast === undefined ? {} : { canBroadcast }),
+          ...(receivesAllDirect === undefined ? {} : { receivesAllDirect }),
+        });
+        return success(200, envelope.requestId, { role });
+      }
+      if (resource === "role" && sectionPatch && request.method === "POST") {
+        const envelope = decodeEnvelope(request.body);
+        const action = envelope.payload["action"];
+        if (action === "delete") {
+          exactKeys(envelope.payload, ["action", "heading"]);
+          const role = store.patchRoleSection(cubeId, roleId!, {
+            action,
+            heading: requiredSectionHeading(envelope.payload, "heading"),
+          });
+          return success(200, envelope.requestId, { role });
+        }
+        if (action !== "replace" && action !== "insert") throw new InputError();
+        exactKeys(envelope.payload, ["action", "heading", "body"], action === "insert" ? ["after"] : []);
+        const body = optionalText(envelope.payload, "body", 51_200);
+        if (body === undefined) throw new InputError();
+        const heading = requiredSectionHeading(envelope.payload, "heading");
+        if (action === "replace") {
+          return success(200, envelope.requestId, {
+            role: store.patchRoleSection(cubeId, roleId!, { action, heading, body }),
+          });
+        }
+        const after = optionalNullableSectionHeading(envelope.payload["after"]);
+        return success(200, envelope.requestId, {
+          role: store.patchRoleSection(cubeId, roleId!, {
+            action,
+            heading,
+            body,
+            ...(after === undefined ? {} : { after }),
+          }),
+        });
+      }
       if (resource === "drones" && request.method === "GET") {
         return success(200, "drones-read", { drones: store.listDrones(cubeId) });
       }
@@ -205,6 +312,15 @@ export class CoordinationApi {
           ...(visibility === undefined ? {} : { visibility }),
           ...(recipientDroneIds === undefined ? {} : { recipientDroneIds }),
         });
+        this.#debugLogger.emit({
+          event: "activity_append",
+          cubeId,
+          entryId: entry.id,
+          principal: authentication,
+          droneId: entry.drone_id,
+          visibility: entry.visibility,
+          recipientDroneIds: entry.recipient_drone_ids,
+        });
         return success(201, envelope.requestId, { entry });
       }
       if (resource === "logs" && request.method === "PUT") {
@@ -212,7 +328,17 @@ export class CoordinationApi {
         exactKeys(envelope.payload, ["cursor"], ["limit"]);
         const cursor = decodeCursor(envelope.payload["cursor"]);
         const limit = optionalLimit(envelope.payload["limit"]);
-        return success(200, envelope.requestId, store.readLog(cubeId, cursor, limit));
+        const page = store.readLog(cubeId, cursor, limit);
+        this.#debugLogger.emit({
+          event: "cursor_replay",
+          mode: "page",
+          cubeId,
+          cursorId: cursor?.id ?? null,
+          returnedCount: page.entries.length,
+          behindBy: page.behind_by,
+          truncated: page.has_more,
+        });
+        return success(200, envelope.requestId, page);
       }
       if (resource === "acks" && request.method === "POST") {
         const envelope = decodeEnvelope(request.body);
@@ -221,6 +347,7 @@ export class CoordinationApi {
         if (kind !== "ack" && kind !== "claim") throw new InputError();
         exactKeys(envelope.payload, ["entry_id", "kind"]);
         store.acknowledge(cubeId, entryId, kind);
+        this.#debugLogger.emit({ event: "ack_write", cubeId, entryId, kind, principal: authentication });
         return { status: 204 };
       }
       if (resource === "decisions" && request.method === "POST") {
@@ -229,13 +356,18 @@ export class CoordinationApi {
         const topic = requiredString(envelope.payload, "topic", 120);
         const decision = requiredString(envelope.payload, "decision", 100_000);
         const rationale = optionalString(envelope.payload, "rationale", 100_000);
-        return success(201, envelope.requestId, {
-          decision: store.recordDecision(cubeId, {
+        const decisionRecord = store.recordDecision(cubeId, {
             topic,
             decision,
             ...(rationale === undefined ? {} : { rationale }),
-          }),
+          });
+        this.#debugLogger.emit({
+          event: "decision_write",
+          cubeId,
+          decisionId: decisionRecord.id,
+          principal: authentication,
         });
+        return success(201, envelope.requestId, { decision: decisionRecord });
       }
       if (resource === "decisions" && request.method === "PUT") {
         const envelope = decodeEnvelope(request.body);
@@ -253,6 +385,15 @@ export class CoordinationApi {
       if (error instanceof ScopedStoreError) {
         return failure(404, "NOT_FOUND", error.message);
       }
+      if (error instanceof RoleConflictError) {
+        return failure(409, error.code, error.message, safeRequestId(request.body));
+      }
+      if (error instanceof DefaultRoleRequiredError) {
+        return failure(409, error.code, error.message, safeRequestId(request.body));
+      }
+      if (error instanceof RoleSectionConflictError) {
+        return failure(409, error.code, error.message, safeRequestId(request.body));
+      }
       if (error instanceof StorageCapacityError) {
         return failure(507, "CAPACITY_EXCEEDED", error.message, safeRequestId(request.body));
       }
@@ -270,13 +411,25 @@ export class CoordinationApi {
     requestSignal: AbortSignal,
   ): Promise<CoordinationResponse> {
     const store = this.#runtime.forPrincipal(principal);
+    const connectionId = randomUUID();
     const session = this.#authority.registerLiveSession(principal);
     const signal = AbortSignal.any([requestSignal, session.signal]);
     let unsubscribe = (): void => undefined;
+    let subscribed = false;
+    let deliveryCount = 0;
     const queue = new AsyncStringQueue(() => {
       unsubscribe();
       session.release();
-    });
+      if (subscribed) {
+        this.#debugLogger.emit({
+          event: "sse_unsubscribe",
+          connectionId,
+          cubeId,
+          principal,
+          deliveryCount,
+        });
+      }
+    }, () => { deliveryCount += 1; });
     const pending: EnrichedActivityRecord[] = [];
     let live = false;
     try {
@@ -290,7 +443,17 @@ export class CoordinationApi {
         else pending.push(entry);
       });
       signal.addEventListener("abort", () => queue.close(), { once: true });
-      const replay = store.readLog(cubeId, cursor, 200).entries;
+      const replayPage = store.readLog(cubeId, cursor, 200);
+      const replay = replayPage.entries;
+      this.#debugLogger.emit({
+        event: "cursor_replay",
+        mode: "sse",
+        cubeId,
+        cursorId: cursor?.id ?? null,
+        returnedCount: replay.length,
+        behindBy: replayPage.behind_by,
+        truncated: replayPage.has_more,
+      });
       const barrier = this.#replayBarrier;
       this.#replayBarrier = undefined;
       if (barrier !== undefined) {
@@ -311,6 +474,15 @@ export class CoordinationApi {
         replay_complete: true,
       })}\n\n`);
       live = true;
+      subscribed = true;
+      this.#debugLogger.emit({
+        event: "sse_subscribe",
+        connectionId,
+        cubeId,
+        principal,
+        replayCount: replay.length,
+        truncated: replayPage.has_more,
+      });
       return { status: 200, stream: queue };
     } catch (error) {
       queue.close();
@@ -327,10 +499,12 @@ class AsyncStringQueue implements AsyncIterable<string> {
   readonly #values: string[] = [];
   readonly #waiters: Array<(result: IteratorResult<string>) => void> = [];
   readonly #cleanup: () => void;
+  readonly #onDelivered: () => void;
   #closed = false;
 
-  constructor(cleanup: () => void) {
+  constructor(cleanup: () => void, onDelivered: () => void = () => undefined) {
     this.#cleanup = cleanup;
+    this.#onDelivered = onDelivered;
   }
 
   push(value: string): void {
@@ -341,7 +515,10 @@ class AsyncStringQueue implements AsyncIterable<string> {
     }
     const waiter = this.#waiters.shift();
     if (waiter === undefined) this.#values.push(value);
-    else waiter({ value, done: false });
+    else {
+      this.#onDelivered();
+      waiter({ value, done: false });
+    }
   }
 
   close(): void {
@@ -355,7 +532,10 @@ class AsyncStringQueue implements AsyncIterable<string> {
     return {
       next: async () => {
         const value = this.#values.shift();
-        if (value !== undefined) return { value, done: false };
+        if (value !== undefined) {
+          this.#onDelivered();
+          return { value, done: false };
+        }
         if (this.#closed) return { value: undefined, done: true };
         return new Promise<IteratorResult<string>>((resolve) => this.#waiters.push(resolve));
       },
@@ -403,6 +583,12 @@ function requiredPresentationName(record: Record<string, unknown>, key: string):
   return value;
 }
 
+function requiredRoleName(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.length < 1 || value.length > 64) throw new InputError();
+  return value;
+}
+
 function optionalString(
   record: Record<string, unknown>,
   key: string,
@@ -413,6 +599,42 @@ function optionalString(
   return requiredString(record, key, maxBytes);
 }
 
+function optionalText(
+  record: Record<string, unknown>,
+  key: string,
+  maxCharacters: number,
+): string | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length > maxCharacters) throw new InputError();
+  return value;
+}
+
+function optionalBoolean(value: unknown): boolean {
+  if (value === undefined) return false;
+  if (typeof value !== "boolean") throw new InputError();
+  return value;
+}
+
+function optionalBooleanValue(value: unknown): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new InputError();
+  return value;
+}
+
+function requiredSectionHeading(record: Record<string, unknown>, key: string): string {
+  const value = requiredString(record, key, 60);
+  const heading = value.trim();
+  if (heading.length === 0 || /^\s/u.test(value) || /[:\n\r]/u.test(heading) ||
+      /^[*\-#>`]/u.test(heading)) throw new InputError();
+  return heading;
+}
+
+function optionalNullableSectionHeading(value: unknown): string | null | undefined {
+  if (value === undefined || value === null) return value;
+  return requiredSectionHeading({ value }, "value");
+}
+
 function requiredUuid(record: Record<string, unknown>, key: string): string {
   const value = record[key];
   if (typeof value !== "string" || !uuidPattern.test(value)) throw new InputError();

package/src/credentials.ts

@@ -13,10 +13,12 @@ import {
 import type {
   CredentialStore,
   DigestPair,
+  InvitationCubeScope,
   ScopedStore,
   SeatAttachRecord,
 } from "./store.js";
 import { operatorErrors } from "./operator-error.js";
+import { disabledDebugLogger, type DebugLogger } from "./debug-log.js";
 
 const tokenPattern = /^[A-Za-z0-9_-]{43,1024}$/u;
 const dummyVerifier = Buffer.alloc(32);
@@ -35,6 +37,10 @@ export interface EnrollmentResponse {
   readonly serverCapabilities: readonly [] | readonly ["create_cube"];
 }
 
+export interface CubeInvitationResult extends InvitationCubeScope {
+  readonly invitation: string;
+}
+
 export interface SeatAttachResponse extends SeatAttachRecord {
   readonly credential: string;
 }
@@ -131,17 +137,20 @@ export class CredentialAuthority {
   readonly #digester: CredentialDigester;
   readonly #clock: () => Date;
   readonly #registry: LiveCredentialRegistry;
+  readonly #debugLogger: DebugLogger;
 
   constructor(
     store: CredentialStore,
     digester: CredentialDigester,
     clock: () => Date = () => new Date(),
     registry = new LiveCredentialRegistry(),
+    debugLogger: DebugLogger = disabledDebugLogger,
   ) {
     this.#store = store;
     this.#digester = digester;
     this.#clock = clock;
     this.#registry = registry;
+    this.#debugLogger = debugLogger;
   }
 
   createRecoveryCredential(): string {
@@ -164,6 +173,18 @@ export class CredentialAuthority {
     return this.#createInvitation("client", ttlMs);
   }
 
+  createCubeInvitation(
+    recoveryCredential: string,
+    cubeSelector: { readonly kind: "id" | "name"; readonly value: string },
+    access: "read" | "write" | "manage",
+    ttlMs: number,
+  ): CubeInvitationResult | 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, { cubeSelector, access });
+  }
+
   replaceOwnerInvitation(recoveryCredential: string, ttlMs: number): string | null {
     const digest = safeDigest(this.#digester, recoveryCredential, "recovery");
     const stored = this.#store.findRecoveryCredential(digest.lookup);
@@ -171,18 +192,41 @@ export class CredentialAuthority {
     return this.#createInvitation("owner", ttlMs);
   }
 
-  #createInvitation(purpose: "owner" | "client", ttlMs: number): string {
+  #createInvitation(purpose: "owner" | "client", ttlMs: number): string;
+  #createInvitation(
+    purpose: "client",
+    ttlMs: number,
+    scoped: {
+      readonly cubeSelector: { readonly kind: "id" | "name"; readonly value: string };
+      readonly access: "read" | "write" | "manage";
+    },
+  ): CubeInvitationResult;
+  #createInvitation(
+    purpose: "owner" | "client",
+    ttlMs: number,
+    scoped?: {
+      readonly cubeSelector: { readonly kind: "id" | "name"; readonly value: string };
+      readonly access: "read" | "write" | "manage";
+    },
+  ): string | CubeInvitationResult {
     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({
+    const scope = this.#store.createInvitation({
       id: randomUUID(),
       digest: this.#digester.digest(secret, "invitation"),
       expiresAt: new Date(this.#clock().getTime() + ttlMs).toISOString(),
       purpose,
+      ...(scoped === undefined ? {} : scoped),
     });
-    return secret;
+    this.#debugLogger.emit({
+      event: "credential",
+      action: "invitation_created",
+      purpose,
+      ...(scope === null ? {} : { cubeId: scope.cubeId }),
+    });
+    return scope === null ? secret : { invitation: secret, ...scope };
   }
 
   exchangeInvitation(request: EnrollmentRequest): EnrollmentResponse | null {
@@ -202,11 +246,20 @@ export class CredentialAuthority {
       credentialId: randomUUID(),
       credentialDigest: safeDigest(this.#digester, request.clientCredential, "client"),
     });
-    return !verified || stored?.expiresAt === undefined || claimed === null ? null : {
+    const result = !verified || stored?.expiresAt === undefined || claimed === null ? null : {
       purpose: claimed.purpose,
       clientId: claimed.clientId,
       serverCapabilities: claimed.serverCapabilities,
     };
+    this.#debugLogger.emit(result === null
+      ? { event: "credential", action: "enrollment_rejected" }
+      : {
+          event: "credential",
+          action: "enrollment_accepted",
+          purpose: result.purpose,
+          clientId: result.clientId,
+        });
+    return result;
   }
 
   authenticate(authorization: string | undefined): Principal | null {
@@ -263,7 +316,18 @@ export class CredentialAuthority {
       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);
+    for (const sessionId of record.revokedSessionIds) {
+      this.#registry.invalidate(sessionId);
+      this.#debugLogger.emit({ event: "credential", action: "session_revoked", sessionId });
+    }
+    this.#debugLogger.emit({
+      event: "credential",
+      action: "session_created",
+      sessionId: record.sessionId,
+      cubeId: record.cube.id,
+      droneId: record.drone.id,
+      generation: record.generation,
+    });
     return { ...record, credential };
   }
 
@@ -277,6 +341,7 @@ export class CredentialAuthority {
     });
     if (!rotated) throw operatorErrors.CLIENT_NOT_FOUND;
     this.#registry.invalidate(clientId);
+    this.#debugLogger.emit({ event: "credential", action: "client_rotated", clientId });
     return secret;
   }
 
@@ -284,6 +349,7 @@ export class CredentialAuthority {
     if (!this.#store.clientExists(clientId)) throw operatorErrors.CLIENT_NOT_FOUND;
     this.#store.revokeClientCredentials(clientId);
     this.#registry.invalidate(clientId);
+    this.#debugLogger.emit({ event: "credential", action: "client_revoked", clientId });
   }
 
   registerLiveSession(principal: string | Principal) {