borgmcp-shared 0.7.0 → 0.8.0

package/src/protocol/contract.ts

@@ -13,12 +13,13 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.7.0' as const;
+export const SHARED_PACKAGE_VERSION = '0.8.0' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
 export const ENROLLMENT_EXCHANGE_PATH = '/api/enrollment/exchange' as const;
 export const CUBES_PATH = '/api/cubes' as const;
+export const CUBE_PATH = '/api/cubes/:cubeId' as const;
 export const REPOSITORY_CUBE_RESOLVE_PATH = '/api/repository-cubes/resolve' as const;
 export const REPOSITORY_CUBE_ASSOCIATION_PATH = '/api/repository-cubes/association' as const;
 export const ATTACH_PATH = '/api/client/attach' as const;
@@ -29,6 +30,13 @@ export const PROTOCOL_HTTP_CONTRACT = {
   protocol: { method: 'GET', path: PROTOCOL_INFO_PATH, authenticated: false, success_status: 200 },
   enrollment: { method: 'POST', path: ENROLLMENT_EXCHANGE_PATH, authenticated: 'invitation', success_status: 201 },
   cubes: { method: 'POST', path: CUBES_PATH, authenticated: true, success_status: 201 },
+  cube_delete: {
+    method: 'DELETE',
+    path: CUBE_PATH,
+    authenticated: true,
+    success_status: 200,
+    mutation: true,
+  },
   repository_cube_resolve: {
     method: 'POST',
     path: REPOSITORY_CUBE_RESOLVE_PATH,
@@ -68,6 +76,7 @@ export const PROTOCOL_HTTP_CONTRACT = {
   session_revoked_status: 401,
   session_rejected_status: 401,
   cursor_expired_status: 410,
+  cube_deleted_status: 410,
   drone_evicted_status: 410,
   content_too_large_status: 413,
   unsupported_protocol_status: 426,
@@ -116,6 +125,23 @@ export interface EnrollmentExchangeRequest {
   client_name?: string;
 }
 
+export const INVITATION_ARTIFACT_VERSION = 2 as const;
+export type InvitationAuthority = 'client' | 'owner';
+
+/**
+ * The single opaque value transported between machines for enrollment. The
+ * integrity field is produced and verified by the issuing implementation; the
+ * shared codec preserves it as a bounded canonical field.
+ */
+export interface InvitationArtifact {
+  version: typeof INVITATION_ARTIFACT_VERSION;
+  endpoint: string;
+  ca_spki_sha256: string;
+  authority: InvitationAuthority;
+  secret: string;
+  integrity: string;
+}
+
 export const SERVER_CAPABILITIES = ['create_cube'] as const;
 export type ServerCapability = (typeof SERVER_CAPABILITIES)[number];
 
@@ -164,6 +190,13 @@ export interface CreateCubeResponse {
   access: 'manage';
 }
 
+export type DeleteCubeRequest = Record<string, never>;
+
+export interface DeleteCubeResponse {
+  cube_id: string;
+  deleted: true;
+}
+
 export interface ResolveRepositoryCubeRequest {
   working_repo_name: string;
   repository: CreateCubeRepository;
@@ -299,6 +332,207 @@ function opaqueToken(value: unknown, path: readonly (string | number)[]): string
   return token;
 }
 
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const INVITATION_MAGIC = 'B2';
+const INVITATION_LENGTH_HEX_DIGITS = 3;
+
+function encodeBase64UrlAscii(value: string): string {
+  let output = '';
+  for (let index = 0; index < value.length; index += 3) {
+    const first = value.charCodeAt(index);
+    const hasSecond = index + 1 < value.length;
+    const hasThird = index + 2 < value.length;
+    const second = hasSecond ? value.charCodeAt(index + 1) : 0;
+    const third = hasThird ? value.charCodeAt(index + 2) : 0;
+    output += BASE64URL_ALPHABET[first >> 2];
+    output += BASE64URL_ALPHABET[((first & 0x03) << 4) | (second >> 4)];
+    if (hasSecond) output += BASE64URL_ALPHABET[((second & 0x0f) << 2) | (third >> 6)];
+    if (hasThird) output += BASE64URL_ALPHABET[third & 0x3f];
+  }
+  return output;
+}
+
+function decodeBase64UrlAscii(value: string, path: readonly (string | number)[]): string {
+  if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
+    fail('Expected an unpadded base64url value.', path);
+  }
+  let output = '';
+  for (let index = 0; index < value.length; index += 4) {
+    const first = BASE64URL_ALPHABET.indexOf(value[index]);
+    const second = BASE64URL_ALPHABET.indexOf(value[index + 1]);
+    const third = index + 2 < value.length ? BASE64URL_ALPHABET.indexOf(value[index + 2]) : 0;
+    const fourth = index + 3 < value.length ? BASE64URL_ALPHABET.indexOf(value[index + 3]) : 0;
+    if (first < 0 || second < 0 || (index + 2 < value.length && third < 0) ||
+        (index + 3 < value.length && fourth < 0)) {
+      fail('Expected an unpadded base64url value.', path);
+    }
+    const bytes = [
+      (first << 2) | (second >> 4),
+      ((second & 0x0f) << 4) | (third >> 2),
+      ((third & 0x03) << 6) | fourth,
+    ];
+    const byteCount = Math.min(3, value.length - index - 1);
+    for (let byteIndex = 0; byteIndex < byteCount; byteIndex++) {
+      if (bytes[byteIndex] > 0x7f) fail('Invitation fields must contain ASCII bytes.', path);
+      output += String.fromCharCode(bytes[byteIndex]);
+    }
+  }
+  if (encodeBase64UrlAscii(output) !== value) {
+    fail('Expected canonical unpadded base64url encoding.', path);
+  }
+  return output;
+}
+
+function encodedBase64UrlLength(byteLength: number): number {
+  const remainder = byteLength % 3;
+  return Math.floor(byteLength / 3) * 4 + (remainder === 0 ? 0 : remainder + 1);
+}
+
+function invitationFieldLength(value: string, path: readonly (string | number)[]): string {
+  const length = value.length;
+  if (length > 0xfff) fail('Invitation field is too long.', path);
+  return length.toString(16).padStart(INVITATION_LENGTH_HEX_DIGITS, '0');
+}
+
+function decodeInvitationField(
+  payload: string,
+  cursor: { value: number },
+  path: readonly (string | number)[],
+): string {
+  const lengthText = payload.slice(cursor.value, cursor.value + INVITATION_LENGTH_HEX_DIGITS);
+  if (!/^[0-9a-f]{3}$/.test(lengthText)) fail('Invitation field length is invalid.', path);
+  cursor.value += INVITATION_LENGTH_HEX_DIGITS;
+  const byteLength = Number.parseInt(lengthText, 16);
+  const encodedLength = encodedBase64UrlLength(byteLength);
+  const encoded = payload.slice(cursor.value, cursor.value + encodedLength);
+  if (encoded.length !== encodedLength) fail('Invitation field is truncated.', path);
+  cursor.value += encodedLength;
+  const decoded = decodeBase64UrlAscii(encoded, path);
+  if (decoded.length !== byteLength) fail('Invitation field length does not match its value.', path);
+  return decoded;
+}
+
+function canonicalInvitationEndpoint(value: unknown, path: readonly (string | number)[]): string {
+  const endpoint = boundedString(value, 1, 512, path);
+  type ParsedUrl = {
+    protocol: string;
+    origin: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    username: string;
+    password: string;
+  };
+  const UrlParser = (globalThis as unknown as { URL?: new (value: string) => ParsedUrl }).URL;
+  if (UrlParser === undefined) fail('Invitation endpoint URL parsing is unavailable.', path);
+  let parsed: ParsedUrl;
+  try {
+    parsed = new UrlParser(endpoint);
+  } catch {
+    fail('Invitation endpoint must be a valid URL.', path);
+  }
+  if (parsed.protocol !== 'https:' || !parsed.hostname || parsed.username || parsed.password ||
+      parsed.pathname !== '/' || parsed.search || parsed.hash || endpoint !== parsed.origin ||
+      (parsed.port !== '' && (Number.parseInt(parsed.port, 10) < 1 || Number.parseInt(parsed.port, 10) > 65_535))) {
+    fail('Invitation endpoint must be a canonical HTTPS origin.', path);
+  }
+  return endpoint;
+}
+
+function validateInvitationArtifact(value: unknown): InvitationArtifact {
+  const input = record(value);
+  exactKeys(input, ['version', 'endpoint', 'ca_spki_sha256', 'authority', 'secret', 'integrity'], [
+    'version',
+    'endpoint',
+    'ca_spki_sha256',
+    'authority',
+    'secret',
+    'integrity',
+  ]);
+  if (input.version !== INVITATION_ARTIFACT_VERSION) {
+    fail('Unsupported invitation artifact version.', ['version']);
+  }
+  const endpoint = canonicalInvitationEndpoint(input.endpoint, ['endpoint']);
+  const caSpkiSha256 = boundedString(input.ca_spki_sha256, 64, 64, ['ca_spki_sha256']);
+  if (!/^[0-9a-f]{64}$/.test(caSpkiSha256)) {
+    fail('CA SPKI SHA-256 must be lowercase hexadecimal.', ['ca_spki_sha256']);
+  }
+  if (input.authority !== 'client' && input.authority !== 'owner') {
+    fail('Invitation authority is invalid.', ['authority']);
+  }
+  return {
+    version: INVITATION_ARTIFACT_VERSION,
+    endpoint,
+    ca_spki_sha256: caSpkiSha256,
+    authority: input.authority,
+    secret: opaqueToken(input.secret, ['secret']),
+    integrity: opaqueToken(input.integrity, ['integrity']),
+  };
+}
+
+/**
+ * Return the canonical ASCII preimage for the artifact integrity binding.
+ * Implementations hash these exact bytes with their agreed secret algorithm;
+ * the shared package intentionally does not own a crypto runtime.
+ */
+export function getInvitationArtifactIntegrityInput(value: InvitationArtifact): string {
+  const artifact = validateInvitationArtifact(value);
+  const endpoint = encodeBase64UrlAscii(artifact.endpoint);
+  const secret = encodeBase64UrlAscii(artifact.secret);
+  return [
+    INVITATION_MAGIC,
+    invitationFieldLength(artifact.endpoint, ['endpoint']),
+    endpoint,
+    artifact.ca_spki_sha256,
+    artifact.authority === 'client' ? 'c' : 'o',
+    invitationFieldLength(artifact.secret, ['secret']),
+    secret,
+  ].join('');
+}
+
+/** Encode an invitation artifact as one canonical, unpadded base64url token. */
+export function encodeInvitationArtifact(value: InvitationArtifact): string {
+  const artifact = validateInvitationArtifact(value);
+  const payload = [
+    getInvitationArtifactIntegrityInput(artifact),
+    invitationFieldLength(artifact.integrity, ['integrity']),
+    encodeBase64UrlAscii(artifact.integrity),
+  ].join('');
+  const token = encodeBase64UrlAscii(payload);
+  if (token.length < 43 || token.length > 1024) {
+    fail('Encoded invitation artifact exceeds the supported token bound.');
+  }
+  return token;
+}
+
+/** Decode and strictly validate a canonical invitation artifact token. */
+export function decodeInvitationArtifact(value: unknown): InvitationArtifact {
+  const token = opaqueToken(value, ['invitation']);
+  const payload = decodeBase64UrlAscii(token, ['invitation']);
+  if (!payload.startsWith(INVITATION_MAGIC)) {
+    fail('Invitation uses an unsupported or legacy format.', ['invitation']);
+  }
+  const cursor = { value: INVITATION_MAGIC.length };
+  const endpoint = decodeInvitationField(payload, cursor, ['endpoint']);
+  const caSpkiSha256 = payload.slice(cursor.value, cursor.value + 64);
+  if (caSpkiSha256.length !== 64) fail('Invitation pin is truncated.', ['ca_spki_sha256']);
+  cursor.value += 64;
+  const authority = payload[cursor.value++];
+  const secret = decodeInvitationField(payload, cursor, ['secret']);
+  const integrity = decodeInvitationField(payload, cursor, ['integrity']);
+  if (cursor.value !== payload.length) fail('Invitation contains trailing fields.', ['invitation']);
+  return validateInvitationArtifact({
+    version: INVITATION_ARTIFACT_VERSION,
+    endpoint,
+    ca_spki_sha256: caSpkiSha256,
+    authority: authority === 'c' ? 'client' : authority === 'o' ? 'owner' : authority,
+    secret,
+    integrity,
+  });
+}
+
 function decodeRequestId(value: unknown, path: readonly (string | number)[]): string {
   const decoded = boundedString(value, 8, 128, path);
   if (!/^[A-Za-z0-9._-]+$/.test(decoded)) {
@@ -327,7 +561,7 @@ export function decodeProtocolTagPreflight(value: unknown): ProtocolTagPreflight
   exactKeys(input, ['protocol_version'], ['protocol_version']);
   if (input.protocol_version !== PROTOCOL_VERSION) {
     throw new ProtocolContractError(
-      'This client requires protocol v6. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
+      'This client requires protocol v7. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
       ErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
       ['protocol_version'],
     );
@@ -596,6 +830,30 @@ export function decodeCreateCubeResponseEnvelope(value: unknown): ProtocolEnvelo
   return decodeProtocolEnvelope(value, decodeCreateCubeResponse);
 }
 
+export function decodeDeleteCubeRequest(value: unknown): DeleteCubeRequest {
+  const input = record(value);
+  exactKeys(input, [], []);
+  return {};
+}
+
+export function decodeDeleteCubeRequestEnvelope(value: unknown): ProtocolEnvelope<DeleteCubeRequest> {
+  return decodeProtocolEnvelope(value, decodeDeleteCubeRequest);
+}
+
+export function decodeDeleteCubeResponse(value: unknown): DeleteCubeResponse {
+  const input = record(value);
+  exactKeys(input, ['cube_id', 'deleted'], ['cube_id', 'deleted']);
+  if (input.deleted !== true) fail('Cube deletion result must be terminal.', ['deleted']);
+  return {
+    cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    deleted: true,
+  };
+}
+
+export function decodeDeleteCubeResponseEnvelope(value: unknown): ProtocolEnvelope<DeleteCubeResponse> {
+  return decodeProtocolEnvelope(value, decodeDeleteCubeResponse);
+}
+
 export function decodeResolveRepositoryCubeRequest(value: unknown): ResolveRepositoryCubeRequest {
   const input = record(value);
   exactKeys(input, ['working_repo_name', 'repository'], ['working_repo_name', 'repository']);

package/src/protocol/errors.ts

@@ -17,6 +17,7 @@ export enum ErrorCode {
   CUBE_ALREADY_ASSOCIATED = 'CUBE_ALREADY_ASSOCIATED',
   ROLE_IN_USE = 'ROLE_IN_USE',
   ROLE_HAS_FROZEN_DRONES = 'ROLE_HAS_FROZEN_DRONES',
+  CUBE_DELETED = 'CUBE_DELETED',
   DRONE_EVICTED = 'DRONE_EVICTED',
   DRONE_FROZEN = 'DRONE_FROZEN',
   UNSUPPORTED_PROTOCOL_VERSION = 'UNSUPPORTED_PROTOCOL_VERSION',

package/src/protocol/sse.ts

@@ -2,11 +2,13 @@ import type { EnrichedStreamEntry } from './types.js';
 import {
   ProtocolContractError,
   decodeCanonicalTimestamp,
+  decodeProtocolErrorEnvelope,
   decodeLogCursor,
   decodeOpaqueIdentifier,
   decodeUuid,
   utf8ByteLength,
   type LogCursor,
+  type ProtocolErrorEnvelope,
 } from './contract.js';
 
 export const SSE_LIMITS = {
@@ -31,6 +33,7 @@ export type StreamEvent =
       actor_drone_id: string;
       occurred_at: string;
     }
+  | StreamErrorEvent
   | { type: 'heartbeat'; at: string; broadcast_hwm: LogCursor | null }
   | {
       type: 'bookmark';
@@ -41,6 +44,12 @@ export type StreamEvent =
     }
   | { type: 'unknown'; event: string; raw_data: string };
 
+/** A terminal stream failure; the server sends this frame once and then closes. */
+export interface StreamErrorEvent {
+  type: 'error';
+  error: ProtocolErrorEnvelope;
+}
+
 function object(value: unknown): Record<string, unknown> {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     throw new ProtocolContractError('SSE data must be a JSON object.');
@@ -124,7 +133,7 @@ export function decodeEnrichedStreamEntry(value: unknown): EnrichedStreamEntry {
 
 export function encodeSseEvent(event: Exclude<StreamEvent, { type: 'unknown' }>): string {
   const lines = [`event: ${event.type}`];
-  let data: Record<string, unknown>;
+  let data: unknown;
   if (event.type === 'log') {
     const cursor = decodeLogCursor(event.cursor);
     const entry = decodeEnrichedStreamEntry(event.entry);
@@ -142,6 +151,8 @@ export function encodeSseEvent(event: Exclude<StreamEvent, { type: 'unknown' }>)
       actor_drone_id: decodeUuid(event.actor_drone_id, ['actor_drone_id']),
       occurred_at: decodeCanonicalTimestamp(event.occurred_at, ['occurred_at']),
     };
+  } else if (event.type === 'error') {
+    data = decodeProtocolErrorEnvelope(event.error);
   } else if (event.type === 'heartbeat') {
     data = {
       at: decodeCanonicalTimestamp(event.at, ['at']),
@@ -217,7 +228,7 @@ function decodeFrame(frame: string): StreamEvent {
   if (rawDataBytes > SSE_LIMITS.data_bytes) {
     throw new ProtocolContractError('SSE data exceeds the byte limit.');
   }
-  if (!['log', 'ack', 'claim', 'heartbeat', 'bookmark'].includes(eventName)) {
+  if (!['log', 'ack', 'claim', 'error', 'heartbeat', 'bookmark'].includes(eventName)) {
     if (rawDataBytes > SSE_LIMITS.unknown_data_bytes) {
       throw new ProtocolContractError('Unknown SSE event data exceeds the byte limit.');
     }
@@ -247,6 +258,10 @@ function decodeFrame(frame: string): StreamEvent {
     throw new ProtocolContractError(`${eventName} SSE events must not carry a resume id.`);
   }
 
+  if (eventName === 'error') {
+    return { type: 'error', error: decodeProtocolErrorEnvelope(parsed) };
+  }
+
   if (eventName === 'ack' || eventName === 'claim') {
     exactKeys(data, ['log_entry_id', 'actor_drone_id', 'occurred_at'], [
       'log_entry_id',

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v6. */
-export const PROTOCOL_VERSION = '6' as const;
+/** Current Borg coordination protocol generation. Clean-slate v7. */
+export const PROTOCOL_VERSION = '7' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/templates.ts

@@ -136,6 +136,18 @@ Push discipline:
 - Push only the assigned branch after verifying the staged paths and final diff.
 - Do not force-push, rebase a shared branch, or publish from a local substitute artifact.`;
 
+export const SAME_REPOSITORY_WORKFLOW_DISCIPLINE = `
+
+Same-repository worktrees and handover:
+- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository are worktrees of the same clone family, sharing its object database and refs.
+- Start each new work item by switching branches in that seat's worktree with \`git checkout -b <branch>\`; never create a new worktree or folder per work item.
+- Create a branch only for a routed work item and announce its name in STARTING. One branch equals one work item and one owning seat; hand a branch to another seat only through an explicit log event.
+- Use merge-only history: no rebases and no force-pushes, because another seat may have the branch checked out or fetched.
+- Hand over a ref and exact commit SHA, never a filesystem path. Reviewers check out the SHA in their own worktree with \`git checkout --detach <SHA>\`; never read another seat's folder. Each review round binds to one exact SHA, and a new SHA restarts the gate sequence.
+- With a hosted origin, push the branch at creation with \`git push -u origin <branch>\`; a branch is cube-visible and REVIEW-READY only after that push.
+- With no hosted remote, the commit itself is the durable handover artifact because clone-family worktrees share refs; omit the push step. If push/fetch semantics are needed locally, use a local bare repository as the origin path.
+- After every merge to the protected or main branch, broadcast the merge SHA. When an origin exists, include \`git fetch origin && git merge origin/main\` as the merge-only sync instruction.`;
+
 export const UNIVERSAL_SAFETY_DISCIPLINES = [WAKE_PATH_MONITOR_DISCIPLINE];
 
 export const ROLE_SCOPED_SAFETY_DISCIPLINES = [
@@ -162,7 +174,7 @@ const SOFTWARE_DEV_DIRECTIVE = `## Scope and coordination
 - Reviewers assess the routed exact revision and do not create or expand work.
 - Waiting is valid when no authorized action is available.
 - Merge, deploy, publish, tag, release, credential, and live-operator actions require explicit authority.
-- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.`;
+- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`;
 
 const SOFTWARE_DEV_TAXONOMY: MessageTaxonomy = [
   {
@@ -469,7 +481,7 @@ const STARTER: Template = {
 - Assignment, review, and completion do not authorize unrelated work or integration.
 - ACK is receipt only; STARTING or substantive PROGRESS confirms activation.
 - Findings outside scope are reported, not automatically fixed.
-- Waiting is valid when no authorized action is available.`,
+- Waiting is valid when no authorized action is available.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`,
   message_taxonomy: STARTER_TAXONOMY,
   roles: [
     {
@@ -591,7 +603,7 @@ const LOCAL_MODEL_DIRECTIVE = `## Verification-cost workflow
 - A fourth seat is optional: add a second Executor when throughput-bound, or a second capable Director as an independent review lens when correctness-bound. Never use a cheap model as a review lens.
 - Waiting is valid only when no authorized action or active assigned work remains, or while a role is awaiting a named predecessor and has no independent action it can advance.
 - Dispatch, packet echo, status, and answers are not completion. Each role continues its active item in the same turn until it posts a terminal signal from its own vocabulary.
-- Merge, publish, deploy, tag, release, credential, and irreversible actions require explicit authority.`;
+- Merge, publish, deploy, tag, release, credential, and irreversible actions require explicit authority.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`;
 
 const LOCAL_MODEL_DIRECTOR = `You own authorized intent, priorities, decisions, and verification that requires careful reading. Never implement a change.