borgmcp-shared 0.7.0 → 0.8.0

package/src/conformance/adapter.ts

@@ -4,10 +4,12 @@ import {
   createProtocolEnvelope,
   decodeAssociateRepositoryCubeResponseEnvelope,
   decodeCreateCubeResponseEnvelope,
+  decodeDeleteCubeResponseEnvelope,
   decodeAppendLogResultEnvelope,
   decodeDecisionResultEnvelope,
   decodeDecisionsResultEnvelope,
   decodeEnrollmentExchangeResponseEnvelope,
+  decodeInvitationArtifact,
   decodeAttachResponseEnvelope,
   decodeDroneRuntimeMetadataPatch,
   decodeEvictDroneResultEnvelope,
@@ -34,6 +36,7 @@ import {
 import {
   CREATE_CUBE_ASSOCIATION_CONFORMANCE,
   CREATE_CUBE_RETRY_CONFORMANCE,
+  INVITATION_ARTIFACT_CONFORMANCE,
   ENROLLMENT_RETRY_CONFORMANCE,
 } from './index.js';
 
@@ -130,6 +133,20 @@ export interface ConformanceCreatedCubeState {
   default_worker_role_matches: boolean;
 }
 
+export interface ConformanceDeletedCubeState {
+  readonly cube_exists: boolean;
+  readonly role_count: number;
+  readonly drone_count: number;
+  readonly log_count: number;
+  readonly claim_count: number;
+  readonly decision_count: number;
+  readonly grant_count: number;
+  readonly cube_create_binding_count: number;
+  readonly repository_association_count: number;
+  readonly active_stream_count: number;
+  readonly terminal_credential_count: number;
+}
+
 export interface ConformanceRepositoryCubeFixture {
   cube_id: string;
   name: string;
@@ -168,6 +185,8 @@ export interface ConformanceStreamResponse extends ConformanceHttpResponse {
  */
 export interface ConformanceAdmin {
   reset(): Promise<void>;
+  /** Restarts the authority while preserving durable state. */
+  restartAuthority(): Promise<void>;
   createPrincipal(name: string): Promise<ConformancePrincipal>;
   createCube(name: string): Promise<ConformanceCube>;
   /** Grants the requested cube authority; omitted access defaults to manage. */
@@ -205,6 +224,7 @@ export interface ConformanceAdmin {
     creator: ConformancePrincipal,
     response: CreateCubeResponse,
   ): Promise<ConformanceCreatedCubeState>;
+  inspectDeletedCube(cube: ConformanceCube): Promise<ConformanceDeletedCubeState>;
   prepareRepositoryCube(
     cube: ConformanceCube,
     input: {
@@ -227,6 +247,11 @@ export interface ConformanceOperations {
   protocol(credential: string | null): Promise<ConformanceHttpResponse>;
   enroll(request: unknown): Promise<ConformanceHttpResponse>;
   createCube(credential: string | null, request: unknown): Promise<ConformanceHttpResponse>;
+  deleteCube(
+    credential: string,
+    cube: ConformanceCube,
+    request: unknown,
+  ): Promise<ConformanceHttpResponse>;
   resolveRepositoryCube(credential: string | null, request: unknown): Promise<ConformanceHttpResponse>;
   associateRepositoryCube(credential: string | null, request: unknown): Promise<ConformanceHttpResponse>;
   attach(credential: string, request: unknown): Promise<ConformanceHttpResponse>;
@@ -312,6 +337,7 @@ export interface ConformanceEnvironment {
 export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'http.unauthenticated-liveness', area: 'http' },
   { id: 'protocol.credential-free-preflight', area: 'protocol' },
+  { id: 'enrollment.invitation-artifact', area: 'enrollment' },
   { id: 'enrollment.retry-authority', area: 'enrollment' },
   { id: 'repository.explicit-association', area: 'repository' },
   { id: 'security.adapter-boundary-injection', area: 'security' },
@@ -337,6 +363,7 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'security.metadata-noninterference', area: 'security' },
   { id: 'security.metadata-secret-non-echo', area: 'security' },
   { id: 'security.active-stream-revocation', area: 'security' },
+  { id: 'cubes.delete-terminal-cascade', area: 'cubes' },
 ] as const;
 
 export type AdapterConformanceFixtureId =
@@ -618,6 +645,30 @@ export async function runAdapterConformance(
     return { authenticated: false, mutation_free: true, protocol_version: preflight.protocol_version };
   });
 
+  await record('enrollment.invitation-artifact', async () => {
+    const errors: string[] = [];
+    for (const vector of INVITATION_ARTIFACT_CONFORMANCE) {
+      if (vector.expected === null) {
+        let rejected = false;
+        try {
+          decodeInvitationArtifact(vector.input);
+        } catch {
+          rejected = true;
+        }
+        if (!rejected) errors.push(`${vector.name}: permissive decoder accepted the invalid artifact.`);
+        continue;
+      }
+      try {
+        const decoded = decodeInvitationArtifact(vector.input);
+        invariant(same(decoded, vector.expected), `${vector.name} decoded a different artifact.`);
+      } catch (error) {
+        errors.push(`${vector.name}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    invariant(errors.length === 0, errors.join(' | '));
+    return { vectors: INVITATION_ARTIFACT_CONFORMANCE.length };
+  });
+
   await record('enrollment.retry-authority', async () => {
     const retryVectorErrors: string[] = [];
     for (const [index, vector] of ENROLLMENT_RETRY_CONFORMANCE.entries()) {
@@ -2431,6 +2482,276 @@ export async function runAdapterConformance(
     return { stream_terminated: true, subsequent_status: 401, subsequent_code: ErrorCode.SESSION_REVOKED };
   });
 
+  await record('cubes.delete-terminal-cascade', async () => {
+    const enrollParent = async (
+      name: string,
+      marker: string,
+      retrySuffix: string,
+    ): Promise<{ principal: ConformancePrincipal; credential: string }> => {
+      const principal = await environment.admin.createPrincipal(name);
+      const invitation = await environment.admin.issueSingleUseInvitation(principal, 'client');
+      const credential = `${marker.repeat(41)}AQ`;
+      expectStatus(await environment.operations.enroll(createProtocolEnvelope(
+        `delete-${name}-enroll`,
+        {
+          invitation,
+          retry_key: `00000000-0000-4000-8000-${retrySuffix.padStart(12, '0')}`,
+          client_credential: credential,
+          client_name: name,
+        },
+      )), 201, `${name} enrollment`);
+      return { principal, credential };
+    };
+    const creator = await enrollParent('delete-creator', 'C', '701');
+    const manager = await enrollParent('delete-manager', 'M', '702');
+    const reader = await enrollParent('delete-reader', 'R', '703');
+    const writer = await enrollParent('delete-writer', 'W', '704');
+    const outsider = await enrollParent('delete-outsider', 'O', '705');
+    await environment.admin.grantCreateCubeCapability(creator.principal);
+    const createResponse = await environment.operations.createCube(
+      creator.credential,
+      createProtocolEnvelope('delete-cube-create', {
+        retry_key: '00000000-0000-4000-8000-000000000706',
+        name: 'Disposable Cube',
+        working_repo_name: 'disposable-cube',
+        repository: { kind: 'local', value: '00000000-0000-4000-8000-000000000707' },
+        template: 'default',
+      }),
+    );
+    expectStatus(createResponse, 201, 'Disposable cube creation');
+    const created = decodeCreateCubeResponseEnvelope(createResponse.body).payload;
+    const cube = { id: created.cube_id };
+    const role = { id: created.default_worker_role_id };
+    await environment.admin.grantCube(manager.principal, cube, 'manage');
+    await environment.admin.grantCube(reader.principal, cube, 'read');
+    await environment.admin.grantCube(writer.principal, cube, 'write');
+    const drone = await environment.admin.createDrone(creator.principal, cube, role);
+    const droneCredential = await environment.admin.issueManagedDroneSession(drone);
+    const append = await environment.operations.append(
+      creator.credential,
+      cube,
+      createProtocolEnvelope('delete-log', { message: 'deleted with cube' }),
+    );
+    expectStatus(append, 201, 'Deletion fixture log');
+    const entry = decodeAppendLogResultEnvelope(append.body).payload.entry;
+    expectStatus(await environment.operations.ack(
+      creator.credential,
+      cube,
+      createProtocolEnvelope('delete-claim', { entry_id: entry.id, kind: 'claim' }),
+    ), 204, 'Deletion fixture claim');
+    expectStatus(await environment.operations.recordDecision(
+      manager.credential,
+      cube,
+      createProtocolEnvelope('delete-decision', { topic: 'cleanup', decision: 'delete' }),
+    ), 201, 'Deletion fixture decision');
+
+    const beforeDenied = await environment.admin.inspectCubeManagementState(cube);
+    for (const [kind, credential] of [
+      ['read', reader.credential],
+      ['write', writer.credential],
+      ['drone-session', droneCredential],
+    ] as const) {
+      expectError(
+        await environment.operations.deleteCube(
+          credential,
+          cube,
+          createProtocolEnvelope(`delete-${kind}-denied`, {}),
+        ),
+        403,
+        ErrorCode.ACCESS_DENIED,
+        `${kind} cube deletion`,
+      );
+      invariant(
+        same(await environment.admin.inspectCubeManagementState(cube), beforeDenied),
+        `${kind} cube deletion denial mutated the cube.`,
+      );
+    }
+    expectError(
+      await environment.operations.deleteCube(
+        outsider.credential,
+        cube,
+        createProtocolEnvelope('delete-outsider-denied', {}),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Never-authorized cube deletion',
+    );
+
+    const parentStream = await environment.operations.openStream(manager.credential, cube, null);
+    const droneStream = await environment.operations.openStream(droneCredential, cube, null);
+    expectStatus(parentStream, 200, 'Deletion parent stream');
+    expectStatus(droneStream, 200, 'Deletion drone stream');
+    invariant(parentStream.stream && droneStream.stream, 'Deletion fixture streams did not open.');
+    const parentEvents = new SseEventReader(parentStream.stream);
+    const droneEvents = new SseEventReader(droneStream.stream);
+    for (const streamReader of [parentEvents, droneEvents]) {
+      invariant((await streamReader.next()).type === 'log', 'Deletion stream omitted replay log.');
+      const bookmark = await streamReader.next();
+      invariant(bookmark.type === 'bookmark' && bookmark.replay_complete, 'Deletion stream omitted bookmark.');
+    }
+    const parentTerminal = parentEvents.next();
+    const droneTerminal = droneEvents.next();
+    await provePending(parentTerminal, 'Parent deletion terminal event', pendingProbeMs);
+    await provePending(droneTerminal, 'Drone deletion terminal event', pendingProbeMs);
+
+    const deleted = await environment.operations.deleteCube(
+      manager.credential,
+      cube,
+      createProtocolEnvelope('delete-managed-cube', {}),
+    );
+    expectStatus(deleted, 200, 'Managed cube deletion');
+    invariant(
+      same(decodeDeleteCubeResponseEnvelope(deleted.body).payload, {
+        cube_id: cube.id,
+        deleted: true,
+      }),
+      'Cube deletion response did not identify the terminal cube.',
+    );
+    for (const [kind, event] of [
+      ['parent', await within(parentTerminal, 'Parent deletion terminal event', streamDeadlineMs)],
+      ['drone', await within(droneTerminal, 'Drone deletion terminal event', streamDeadlineMs)],
+    ] as const) {
+      invariant(
+        event.type === 'error' && event.error.error.code === ErrorCode.CUBE_DELETED,
+        `${kind} stream did not receive CUBE_DELETED.`,
+      );
+    }
+    for (const streamReader of [parentEvents, droneEvents]) {
+      let closed = false;
+      try {
+        await within(streamReader.next(), 'Deleted cube stream close', streamDeadlineMs);
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('did not settle')) throw error;
+        closed = true;
+      }
+      invariant(closed, 'Deleted cube stream yielded after its terminal error.');
+      await streamReader.close();
+    }
+
+    invariant(
+      same(await environment.admin.inspectDeletedCube(cube), {
+        cube_exists: false,
+        role_count: 0,
+        drone_count: 0,
+        log_count: 0,
+        claim_count: 0,
+        decision_count: 0,
+        grant_count: 0,
+        cube_create_binding_count: 0,
+        repository_association_count: 0,
+        active_stream_count: 0,
+        terminal_credential_count: 5,
+      }),
+      'Cube deletion did not atomically remove cube-owned state and preserve only terminal credentials.',
+    );
+    for (const [kind, credential] of [
+      ['creator', creator.credential],
+      ['manager', manager.credential],
+      ['reader', reader.credential],
+      ['writer', writer.credential],
+      ['drone', droneCredential],
+    ] as const) {
+      expectError(
+        await environment.operations.read(
+          credential,
+          cube,
+          createProtocolEnvelope(`delete-${kind}-terminal`, { cursor: null, limit: 1 }),
+        ),
+        PROTOCOL_HTTP_CONTRACT.cube_deleted_status,
+        ErrorCode.CUBE_DELETED,
+        `${kind} post-delete request`,
+      );
+      expectError(
+        await environment.operations.deleteCube(
+          credential,
+          cube,
+          createProtocolEnvelope(`delete-${kind}-repeat-terminal`, {}),
+        ),
+        PROTOCOL_HTTP_CONTRACT.cube_deleted_status,
+        ErrorCode.CUBE_DELETED,
+        `${kind} post-delete DELETE`,
+      );
+    }
+    expectError(
+      await environment.operations.deleteCube(
+        outsider.credential,
+        cube,
+        createProtocolEnvelope('delete-outsider-hidden-repeat', {}),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Never-authorized post-delete DELETE',
+    );
+    expectError(
+      await environment.operations.read(
+        outsider.credential,
+        cube,
+        createProtocolEnvelope('delete-outsider-hidden', { cursor: null, limit: 1 }),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Never-authorized post-delete request',
+    );
+    await environment.admin.restartAuthority();
+    for (const [kind, credential] of [
+      ['creator', creator.credential],
+      ['manager', manager.credential],
+      ['reader', reader.credential],
+      ['writer', writer.credential],
+      ['drone', droneCredential],
+    ] as const) {
+      expectError(
+        await environment.operations.read(
+          credential,
+          cube,
+          createProtocolEnvelope(`delete-${kind}-after-restart`, { cursor: null, limit: 1 }),
+        ),
+        PROTOCOL_HTTP_CONTRACT.cube_deleted_status,
+        ErrorCode.CUBE_DELETED,
+        `${kind} post-restart deleted-cube request`,
+      );
+      expectError(
+        await environment.operations.deleteCube(
+          credential,
+          cube,
+          createProtocolEnvelope(`delete-${kind}-repeat-after-restart`, {}),
+        ),
+        PROTOCOL_HTTP_CONTRACT.cube_deleted_status,
+        ErrorCode.CUBE_DELETED,
+        `${kind} post-restart DELETE`,
+      );
+    }
+    expectError(
+      await environment.operations.deleteCube(
+        outsider.credential,
+        cube,
+        createProtocolEnvelope('delete-outsider-hidden-repeat-after-restart', {}),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Never-authorized post-restart DELETE',
+    );
+    expectError(
+      await environment.operations.read(
+        outsider.credential,
+        cube,
+        createProtocolEnvelope('delete-outsider-hidden-after-restart', { cursor: null, limit: 1 }),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Never-authorized post-restart request',
+    );
+    return {
+      deletion_status: 200,
+      cascade_complete: true,
+      terminal_stream_error: ErrorCode.CUBE_DELETED,
+      terminal_http_status: 410,
+      terminal_state_durable_after_restart: true,
+      unknown_hidden_status: 404,
+      non_member_manager: true,
+    };
+  });
+
   const normalizedTranscript = results.map(({ id, observations }) => ({ id, observations }));
   return { ok: results.every((result) => result.ok), results, normalizedTranscript };
 }

package/src/conformance/index.ts

@@ -3,9 +3,14 @@ import type {
   AttachResponse,
   AssociateRepositoryCubeRequest,
   CreateCubeRequest,
+  DeleteCubeRequest,
   EnrollmentExchangeRequest,
   ResolveRepositoryCubeRequest,
 } from '../protocol/contract.js';
+import {
+  encodeInvitationArtifact,
+  type InvitationArtifact,
+} from '../protocol/contract.js';
 import type { EnrichedStreamEntry } from '../protocol/types.js';
 
 export * from './adapter.js';
@@ -229,7 +234,51 @@ export interface EnrollmentRetryConformanceVector {
     };
 }
 
-const ENROLLMENT_INVITATION = 'I'.repeat(43);
+const ENROLLMENT_ARTIFACT: InvitationArtifact = {
+  version: 2,
+  endpoint: 'https://borg.example.test:7091',
+  ca_spki_sha256: 'a'.repeat(64),
+  authority: 'client',
+  secret: 'S'.repeat(43),
+  integrity: 'I'.repeat(43),
+};
+const ENROLLMENT_ARTIFACT_TOKEN = encodeInvitationArtifact(ENROLLMENT_ARTIFACT);
+
+export const INVITATION_ARTIFACT_CONFORMANCE: readonly ConformanceVector<
+  string,
+  InvitationArtifact | null
+>[] = [
+  {
+    name: 'decodes the canonical v2 invitation artifact',
+    input: ENROLLMENT_ARTIFACT_TOKEN,
+    expected: ENROLLMENT_ARTIFACT,
+  },
+  {
+    name: 'rejects a legacy opaque invitation before use',
+    input: 'I'.repeat(43),
+    expected: null,
+  },
+  {
+    name: 'rejects a mangled noncanonical invitation token',
+    input: `${ENROLLMENT_ARTIFACT_TOKEN}=`,
+    expected: null,
+  },
+  {
+    name: 'rejects an invitation token above the outer bound',
+    input: 'A'.repeat(1025),
+    expected: null,
+  },
+  {
+    name: 'rejects a token with a duplicate trailing field',
+    input: `${ENROLLMENT_ARTIFACT_TOKEN}A`,
+    expected: null,
+  },
+];
+
+const ENROLLMENT_INVITATION = encodeInvitationArtifact({
+  ...ENROLLMENT_ARTIFACT,
+  authority: 'client',
+});
 const ENROLLMENT_CREDENTIAL = 'A'.repeat(43);
 const ENROLLMENT_RETRY_KEY = '00000000-0000-4000-8000-000000000101';
 
@@ -443,6 +492,58 @@ readonly CreateCubeAssociationConformanceVector[] = [
   },
 ];
 
+export interface DeleteCubeConformanceVector {
+  name: string;
+  request: DeleteCubeRequest;
+  expected: {
+    status: 200 | 403 | 404 | 410;
+    error?: 'ACCESS_DENIED' | 'NOT_FOUND' | 'CUBE_DELETED';
+    response?: { deleted: true };
+    terminal_sse?: { event: 'error'; error: 'CUBE_DELETED'; closes_after_event: true };
+    durable_after_restart?: true;
+    mutation: 'cascade' | 'none';
+  };
+}
+
+/** Cube deletion is manage-gated, cascading, terminal, and durable across authority restart. */
+export const DELETE_CUBE_CONFORMANCE: readonly DeleteCubeConformanceVector[] = [
+  {
+    name: 'non-member managing parent deletes the cube atomically',
+    request: {},
+    expected: { status: 200, response: { deleted: true }, mutation: 'cascade' },
+  },
+  {
+    name: 'known read and write grants and drone sessions cannot delete',
+    request: {},
+    expected: { status: 403, error: 'ACCESS_DENIED', mutation: 'none' },
+  },
+  {
+    name: 'never-authorized and unknown callers cannot enumerate the cube',
+    request: {},
+    expected: { status: 404, error: 'NOT_FOUND', mutation: 'none' },
+  },
+  {
+    name: 'connected clients receive one terminal error frame before close',
+    request: {},
+    expected: {
+      status: 410,
+      error: 'CUBE_DELETED',
+      terminal_sse: { event: 'error', error: 'CUBE_DELETED', closes_after_event: true },
+      mutation: 'none',
+    },
+  },
+  {
+    name: 'former authorized credentials retain the typed terminal state after restart',
+    request: {},
+    expected: {
+      status: 410,
+      error: 'CUBE_DELETED',
+      durable_after_restart: true,
+      mutation: 'none',
+    },
+  },
+];
+
 export interface ResolveRepositoryCubeConformanceVector {
   name: string;
   request: ResolveRepositoryCubeRequest;