borgmcp-server 0.1.1 → 0.1.5

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,10 +37,12 @@ export interface EnrollmentResponse {
   readonly serverCapabilities: readonly [] | readonly ["create_cube"];
 }
 
-export interface SeatAttachResponse extends SeatAttachRecord {
-  readonly credential: string;
+export interface CubeInvitationResult extends InvitationCubeScope {
+  readonly invitation: string;
 }
 
+export type SeatAttachResponse = SeatAttachRecord;
+
 export class CredentialDigester {
   readonly #key: Buffer;
 
@@ -82,8 +86,9 @@ export class CredentialDigester {
 export class LiveCredentialRegistry {
   readonly #sessions = new Map<string, Set<AbortController>>();
   readonly #keys = new Map<AbortController, readonly string[]>();
+  readonly #timers = new Map<AbortController, NodeJS.Timeout>();
 
-  register(identities: string | readonly string[]): {
+  register(identities: string | readonly string[], expiresInMs?: number): {
     readonly signal: AbortSignal;
     readonly release: () => void;
   } {
@@ -95,6 +100,15 @@ export class LiveCredentialRegistry {
       sessions.add(controller);
       this.#sessions.set(key, sessions);
     }
+    if (expiresInMs !== undefined) {
+      if (expiresInMs <= 0) {
+        this.#expire(controller);
+      } else {
+        const timer = setTimeout(() => this.#expire(controller), expiresInMs);
+        timer.unref();
+        this.#timers.set(controller, timer);
+      }
+    }
     return {
       signal: controller.signal,
       release: () => this.#release(controller),
@@ -115,6 +129,11 @@ export class LiveCredentialRegistry {
   }
 
   #release(controller: AbortController): void {
+    const timer = this.#timers.get(controller);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      this.#timers.delete(controller);
+    }
     const keys = this.#keys.get(controller);
     if (keys === undefined) return;
     this.#keys.delete(controller);
@@ -124,6 +143,11 @@ export class LiveCredentialRegistry {
       if (sessions?.size === 0) this.#sessions.delete(key);
     }
   }
+
+  #expire(controller: AbortController): void {
+    this.#release(controller);
+    controller.abort();
+  }
 }
 
 export class CredentialAuthority {
@@ -131,17 +155,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 +191,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 +210,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 +264,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 {
@@ -216,7 +287,7 @@ export class CredentialAuthority {
 
   authenticateStatus(
     authorization: string | undefined,
-  ): Principal | "missing" | "invalid" | "revoked" {
+  ): Principal | "missing" | "invalid" | "revoked" | "evicted" {
     if (authorization === undefined) return "missing";
     const secret = bearerSecret(authorization);
     const clientDigest = safeDigest(this.#digester, secret, "client");
@@ -232,6 +303,7 @@ export class CredentialAuthority {
       return clientPrincipal(client!.clientId!);
     }
     if (droneValid) {
+      if (drone!.evictedAt !== null) return "evicted";
       if (drone!.revokedAt != null || drone!.expiresAt <= this.#clock().toISOString()) {
         return "revoked";
       }
@@ -250,21 +322,30 @@ export class CredentialAuthority {
     request: {
       readonly cubeId: string;
       readonly roleId: string;
-      readonly retryKey: string;
+      readonly sessionCredential: string;
       readonly priorDroneId?: string;
     },
   ): SeatAttachResponse {
-    const credential = generateSecret();
     const record = store.attachSeat({
-      ...request,
+      cubeId: request.cubeId,
+      roleId: request.roleId,
+      ...(request.priorDroneId === undefined ? {} : { priorDroneId: request.priorDroneId }),
       droneId: randomUUID(),
       sessionId: randomUUID(),
       credentialId: randomUUID(),
-      credentialDigest: this.#digester.digest(credential, "drone-session"),
+      credentialDigest: this.#digester.digest(request.sessionCredential, "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 };
+    if (record.result === "created") {
+      this.#debugLogger.emit({
+        event: "credential",
+        action: "session_created",
+        sessionId: record.sessionId,
+        cubeId: record.cube.id,
+        droneId: record.drone.id,
+      });
+    }
+    return record;
   }
 
   rotateClient(clientId: string): string {
@@ -277,6 +358,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,15 +366,17 @@ 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) {
     if (typeof principal === "string") return this.#registry.register(principal);
-    return this.#registry.register(
-      principal.kind === "drone-session"
-        ? [principal.id, principal.clientId]
-        : principal.id,
-    );
+    if (principal.kind !== "drone-session") return this.#registry.register(principal.id);
+    const expiresAt = this.#store.findActiveDroneSessionExpiry(principal.id);
+    const expiresInMs = expiresAt === null
+      ? 0
+      : new Date(expiresAt).getTime() - this.#clock().getTime();
+    return this.#registry.register([principal.id, principal.clientId], expiresInMs);
   }
 }
 

package/src/debug-log.ts

@@ -0,0 +1,165 @@
+import type { Principal } from "./principal.js";
+
+export type DebugRoute =
+  | "health"
+  | "protocol"
+  | "enrollment_exchange"
+  | "client_attach"
+  | "cubes"
+  | "cube"
+  | "cube_roles"
+  | "cube_role"
+  | "cube_role_section_patch"
+  | "cube_taxonomy_patch"
+  | "cube_drones"
+  | "cube_logs"
+  | "cube_acks"
+  | "cube_decisions"
+  | "cube_stream"
+  | "unknown";
+
+export type DebugEvent =
+  | { readonly event: "startup"; readonly bindMode: "loopback" | "lan"; readonly port: number; readonly dataDirectory: "configured" | "tls_only" }
+  | { readonly event: "lifecycle"; readonly action: "listening" | "stopped" }
+  | { readonly event: "request"; readonly route: DebugRoute; readonly method: string; readonly authentication: "not_required" | "missing" | "invalid" | "revoked" | "evicted" | "accepted"; readonly authorization: "not_checked" | "accepted" | "denied_or_not_found"; readonly principal?: Principal; readonly status: number; readonly durationMs: number }
+  | { readonly event: "activity_append"; readonly cubeId: string; readonly entryId: string; readonly principal: Principal; readonly droneId: string | null; readonly visibility: "broadcast" | "direct"; readonly recipientDroneIds: readonly string[] }
+  | { readonly event: "cursor_replay"; readonly mode: "page" | "sse"; readonly cubeId: string; readonly cursorId: string | null; readonly returnedCount: number; readonly behindBy: number; readonly truncated: boolean }
+  | { readonly event: "ack_write"; readonly cubeId: string; readonly entryId: string; readonly kind: "ack" | "claim"; readonly principal: Principal }
+  | { readonly event: "decision_write"; readonly cubeId: string; readonly decisionId: string; readonly principal: Principal }
+  | { readonly event: "sse_subscribe"; readonly connectionId: string; readonly cubeId: string; readonly principal: Principal; readonly replayCount: number; readonly truncated: boolean }
+  | { readonly event: "sse_unsubscribe"; readonly connectionId: string; readonly cubeId: string; readonly principal: Principal; readonly deliveryCount: number }
+  | { readonly event: "credential"; readonly action: "invitation_created" | "enrollment_accepted" | "enrollment_rejected" | "session_created" | "session_revoked" | "client_rotated" | "client_revoked"; readonly purpose?: "owner" | "client"; readonly clientId?: string; readonly cubeId?: string; readonly droneId?: string; readonly sessionId?: string }
+  | { readonly event: "transport_rejection"; readonly reason: "tls_client_error" | "http_parser_error" };
+
+export interface DebugLogger {
+  readonly emit: (event: DebugEvent) => void;
+}
+
+export const disabledDebugLogger: DebugLogger = Object.freeze({ emit: () => undefined });
+
+export function createDebugLogger(write: ((line: string) => void) | undefined): DebugLogger {
+  if (write === undefined) return disabledDebugLogger;
+  return Object.freeze({
+    emit(event: DebugEvent): void {
+      try {
+        const projected = projectEvent(event);
+        if (projected !== null) write(JSON.stringify({ level: "debug", ...projected }));
+      } catch {
+        // Operator diagnostics cannot alter request or server behavior.
+      }
+    },
+  });
+}
+
+function projectEvent(event: DebugEvent): Record<string, unknown> | null {
+  const value = event as unknown as Record<string, unknown>;
+  switch (value["event"]) {
+    case "startup":
+      return {
+        event: "startup",
+        bind_mode: enumValue(value["bindMode"], ["loopback", "lan"], "loopback"),
+        port: boundedInteger(value["port"], 0, 65_535),
+        data_directory: enumValue(value["dataDirectory"], ["configured", "tls_only"], "tls_only"),
+      };
+    case "request": {
+      const principal = principalFields(value["principal"]);
+      return {
+        event: "request",
+        route: enumValue(value["route"], DEBUG_ROUTES, "unknown"),
+        method: enumValue(value["method"], HTTP_METHODS, "OTHER"),
+        authentication: enumValue(value["authentication"], AUTH_RESULTS, "invalid"),
+        authorization: enumValue(value["authorization"], AUTHZ_RESULTS, "not_checked"),
+        ...principal,
+        status: boundedInteger(value["status"], 0, 599),
+        duration_ms: boundedInteger(value["durationMs"], 0, Number.MAX_SAFE_INTEGER),
+      };
+    }
+    case "lifecycle":
+      return { event: "lifecycle", action: enumValue(value["action"], ["listening", "stopped"], "stopped") };
+    case "activity_append":
+      return {
+        event: "activity_append",
+        cube_id: uuid(value["cubeId"]),
+        entry_id: uuid(value["entryId"]),
+        ...principalFields(value["principal"]),
+        drone_id: nullableUuid(value["droneId"]),
+        visibility: enumValue(value["visibility"], ["broadcast", "direct"], "broadcast"),
+        recipient_count: uuidArray(value["recipientDroneIds"]).length,
+        recipient_drone_ids: uuidArray(value["recipientDroneIds"]),
+      };
+    case "cursor_replay":
+      return {
+        event: "cursor_replay",
+        mode: enumValue(value["mode"], ["page", "sse"], "page"),
+        cube_id: uuid(value["cubeId"]),
+        cursor_id: nullableUuid(value["cursorId"]),
+        returned_count: boundedInteger(value["returnedCount"], 0, 500),
+        behind_by: boundedInteger(value["behindBy"], 0, Number.MAX_SAFE_INTEGER),
+        truncated: value["truncated"] === true,
+      };
+    case "ack_write":
+      return { event: "ack_write", cube_id: uuid(value["cubeId"]), entry_id: uuid(value["entryId"]), kind: enumValue(value["kind"], ["ack", "claim"], "ack"), ...principalFields(value["principal"]) };
+    case "decision_write":
+      return { event: "decision_write", cube_id: uuid(value["cubeId"]), decision_id: uuid(value["decisionId"]), ...principalFields(value["principal"]) };
+    case "sse_subscribe":
+      return { event: "sse_subscribe", connection_id: uuid(value["connectionId"]), cube_id: uuid(value["cubeId"]), ...principalFields(value["principal"]), replay_count: boundedInteger(value["replayCount"], 0, 200), truncated: value["truncated"] === true };
+    case "sse_unsubscribe":
+      return { event: "sse_unsubscribe", connection_id: uuid(value["connectionId"]), cube_id: uuid(value["cubeId"]), ...principalFields(value["principal"]), delivery_count: boundedInteger(value["deliveryCount"], 0, Number.MAX_SAFE_INTEGER) };
+    case "credential":
+      return {
+        event: "credential",
+        action: enumValue(value["action"], CREDENTIAL_ACTIONS, "enrollment_rejected"),
+        ...(value["purpose"] === "owner" || value["purpose"] === "client" ? { purpose: value["purpose"] } : {}),
+        ...optionalUuid("client_id", value["clientId"]),
+        ...optionalUuid("cube_id", value["cubeId"]),
+        ...optionalUuid("drone_id", value["droneId"]),
+        ...optionalUuid("session_id", value["sessionId"]),
+      };
+    case "transport_rejection":
+      return { event: "transport_rejection", reason: enumValue(value["reason"], ["tls_client_error", "http_parser_error"], "tls_client_error") };
+    default:
+      return null;
+  }
+}
+
+function principalFields(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return {};
+  const principal = value as Record<string, unknown>;
+  const kind = enumValue(principal["kind"], ["operator", "client", "drone-session"], "client");
+  return { principal_kind: kind, ...optionalUuid("principal_id", principal["id"]) };
+}
+
+function uuid(value: unknown): string | null {
+  return typeof value === "string" && UUID_PATTERN.test(value) ? value.toLowerCase() : null;
+}
+
+function nullableUuid(value: unknown): string | null {
+  return value === null ? null : uuid(value);
+}
+
+function optionalUuid(key: string, value: unknown): Record<string, string> {
+  const safe = uuid(value);
+  return safe === null ? {} : { [key]: safe };
+}
+
+function uuidArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 100).map(uuid).filter((item): item is string => item !== null);
+}
+
+function boundedInteger(value: unknown, minimum: number, maximum: number): number {
+  return Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum
+    ? value as number
+    : minimum;
+}
+
+function enumValue<const T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === "string" && allowed.includes(value as T) ? value as T : fallback;
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const DEBUG_ROUTES: readonly DebugRoute[] = ["health", "protocol", "enrollment_exchange", "client_attach", "cubes", "cube", "cube_roles", "cube_role", "cube_role_section_patch", "cube_taxonomy_patch", "cube_drones", "cube_logs", "cube_acks", "cube_decisions", "cube_stream", "unknown"];
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OTHER"] as const;
+const AUTH_RESULTS = ["not_required", "missing", "invalid", "revoked", "evicted", "accepted"] as const;
+const AUTHZ_RESULTS = ["not_checked", "accepted", "denied_or_not_found"] as const;
+const CREDENTIAL_ACTIONS = ["invitation_created", "enrollment_accepted", "enrollment_rejected", "session_created", "session_revoked", "client_rotated", "client_revoked"] as const;

package/src/enrollment.ts

@@ -1,26 +1,37 @@
+import {
+  ErrorCode,
+  PROTOCOL_VERSION,
+  ProtocolContractError,
+  createProtocolEnvelope,
+  decodeEnrollmentExchangeRequestEnvelope,
+  type EnrollmentExchangeRequest,
+  type ProtocolEnvelope,
+} from "borgmcp-shared/protocol";
 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;
-  };
-}
+type EnrollmentEnvelope = ProtocolEnvelope<EnrollmentExchangeRequest>;
 
 export function createEnrollmentExchange(authority: CredentialAuthority) {
   return async (body: unknown): Promise<{
-    readonly status: 201 | 400 | 401 | 507;
+    readonly status: 201 | 400 | 401 | 426 | 507;
     readonly body?: unknown;
   }> => {
     let envelope: EnrollmentEnvelope;
     try {
       envelope = decodeEnrollmentEnvelope(body);
-    } catch {
+    } catch (error) {
+      if (error instanceof ProtocolContractError &&
+          error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION) {
+        return {
+          status: 426,
+          body: errorEnvelope(
+            ErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
+            "Unsupported protocol version.",
+            safeRequestId(body),
+          ),
+        };
+      }
       return {
         status: 400,
         body: errorEnvelope(
@@ -59,26 +70,22 @@ export function createEnrollmentExchange(authority: CredentialAuthority) {
     }
     return {
       status: 201,
-      body: {
-        protocol_version: "1",
-        request_id: envelope.request_id,
-        payload: {
+      body: createProtocolEnvelope(envelope.request_id, {
           purpose: response.purpose,
           client_id: response.clientId,
           server_capabilities: response.serverCapabilities,
-        },
-      },
+      }),
     };
   };
 }
 
 function errorEnvelope(
-  code: "INVALID_INPUT" | "AUTH_INVALID" | "CAPACITY_EXCEEDED",
+  code: "INVALID_INPUT" | "AUTH_INVALID" | "CAPACITY_EXCEEDED" | "UNSUPPORTED_PROTOCOL_VERSION",
   message: string,
   requestId?: string,
 ) {
   return {
-    protocol_version: "1" as const,
+    protocol_version: PROTOCOL_VERSION,
     ...(requestId === undefined ? {} : { request_id: requestId }),
     error: { code, message },
   };
@@ -93,64 +100,11 @@ function safeRequestId(value: unknown): string | 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))) {
+  try {
+    return decodeEnrollmentExchangeRequestEnvelope(value);
+  } catch (error) {
+    if (error instanceof ProtocolContractError &&
+        error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION) throw error;
     throw new Error("Invalid enrollment request.");
   }
-  return record;
 }