borgmcp-shared 0.3.0 → 0.4.0

package/docs/enrollment.md

@@ -5,15 +5,22 @@ shared by clients and servers. It does not define offline operator commands,
 database transactions, or keychain APIs, but implementations must preserve the
 security properties below.
 
-This contract replaces the server-generated bearer response used by
-`borgmcp-shared@0.2.2`. It is selected for `0.3.0` as a breaking wire change and
-requires a coordinated client/server migration. Version preparation does not
-authorize a tag or publication. There is no compatibility path that returns a
-bearer from the server.
-
-Servers implementing this contract advertise the required
-`auth.retry-safe-enrollment` capability. Negotiation fails closed when it is
-absent.
+This contract replaces the server-generated bearer response used by the
+published `borgmcp-shared@0.3.0` v1 baseline. It is a breaking clean-slate v2
+wire change; this source now identifies the still-unpublished `0.4.0` candidate
+and requires a coordinated client/server release. The version bump grants no tag
+or publication authority — creating the `v0.4.0` tag and the registry
+publication remain separate, independently gated steps. There is no
+compatibility path that returns a bearer from the server.
+
+A client verifies the credential-free `GET /api/protocol` tag preflight before
+it creates or sends any enrollment secret; a peer that presents a different
+protocol tag is rejected outright. The exact protocol tag is the sole acceptance
+authority, so there is no capability a server advertises or a client negotiates
+for this contract. The enrollment
+response still carries the enrolled principal's `server_capabilities` (owner
+enrollment grants `['create_cube']`; ordinary enrollment grants none) — that is
+an authorization fact about the principal, not a negotiated protocol capability.
 
 ## Client Preconditions
 

package/docs/releasing.md

@@ -137,9 +137,10 @@ Recover out of band without rerunning the workflow:
 2. With `GITHUB_SHA=508f2dc88658d8e00ff036b7ce6913fcfbef239b` and
    `NPM_EXPECTED_OWNER=byteventures`, run
    `node scripts/verify-registry-release.mjs postpublish <audited-tarball>`. The
-   verifier retries only transient HTTP 404 propagation responses with bounded
-   backoff; non-404 failures and integrity, owner, or provenance mismatches remain
-   immediate terminal failures.
+   verifier retries only transient HTTP 404 propagation responses. Its production
+   envelope performs at most 18 reads over approximately three and a half minutes
+   (1, 2, 4, and 8 second waits, then a 15 second cap). Non-404 failures and
+   integrity, owner, or provenance mismatches remain immediate terminal failures.
 3. Install exact `borgmcp-shared@0.2.2` from the registry into a clean temporary
    prefix with scripts disabled and run `npm audit signatures` against that
    prefix.
@@ -216,25 +217,30 @@ Immediately after a successful first publish:
 
 ## Later Releases
 
-### 0.3.0 Enrollment Contract
+### 0.4.0 Clean-Slate v2 Contract
 
-The ratified `borgmcp-shared-enrollment-version` decision selects `0.3.0` for
-the breaking retry-safe enrollment and idempotent multi-cube contract. Updating
-package metadata, lockfiles, assertions, compatibility documentation, and this
-runbook does not authorize creating `v0.3.0` or publishing the package.
+The ratified `borgmcp-shared-enrollment-version` decision defined this breaking
+retry-safe enrollment and idempotent multi-cube contract. `borgmcp-shared@0.3.0`
+is now the published, immutable v1 baseline on the registry, so the clean-slate
+v2 contract — credential-free tag preflight included — is versioned as the
+still-unpublished `0.4.0` candidate (a breaking change on a `0.x` package bumps
+the minor). This source now identifies `0.4.0`. That reviewed version bump
+does not authorize creating `v0.4.0` or publishing the package, and the source
+branch must not republish `0.3.0`.
 
-Before a separately authorized `v0.3.0` tag is created:
+Before a separately authorized `v0.4.0` tag is created:
 
-1. The exact `0.3.0` source commit must be merged to protected `main` after Code
+1. The exact `0.4.0` source commit must be merged to protected `main` after Code
    Review, Security, and Release Quality approve the package identity, public
    API, conformance behavior, generated output, and release documentation.
-2. The package and root lockfile, `SHARED_PACKAGE_VERSION`, compatibility matrix,
-   packed-artifact verifier, and version assertions must all identify `0.3.0`.
+2. The package and root lockfile, `SHARED_PACKAGE_VERSION`, the exact protocol
+   version tag, packed-artifact verifier, and version assertions all identify
+   `0.4.0` (done in this source bump).
 3. The protected workflow must build one exact tarball and pass its full source,
    test, audit, public-export, source-map, install/import, dry-run, lock-derived
    CycloneDX SBOM, integrity, and provenance gates. Security must approve that
    exact workflow artifact.
-4. The `0.3.0` workflow must generate a CycloneDX SBOM, canonicalize npm's
+4. The `0.4.0` workflow must generate a CycloneDX SBOM, canonicalize npm's
    checkout-derived root display name to the already-verified manifest name,
    and validate every component's exact canonical registry tarball URL, single
    matching CycloneDX distribution reference, purl, and lock SHA-512 plus the
@@ -246,9 +252,9 @@ Before a separately authorized `v0.3.0` tag is created:
 
 After registry publication and independent integrity/provenance verification,
 the first borgmcp client and borgmcp-server releases may replace their temporary
-development dependency with the reviewed registry range `^0.3.0`. They must not
-ship a Git dependency or fall back to the incompatible `0.2.x` enrollment
-response.
+development dependency with the reviewed registry range `^0.4.0`. They must not
+ship a Git dependency or fall back to the incompatible published `0.3.0` v1
+enrollment response.
 
 Later releases follow the same source gates, annotated protected tag, exact
 tarball audit, Queen authorization, and environment approval. The registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",

package/src/conformance/adapter.ts

@@ -1,6 +1,5 @@
 import {
   ErrorCode,
-  ProtocolContractError,
   compareLogCursor,
   createProtocolEnvelope,
   decodeCreateCubeResponseEnvelope,
@@ -9,15 +8,14 @@ import {
   decodeDecisionsResultEnvelope,
   decodeEnrollmentExchangeResponseEnvelope,
   decodeProtocolErrorEnvelope,
-  decodeProtocolInfoEnvelope,
+  decodeProtocolTagPreflight,
   decodeReadLogResultEnvelope,
   decodeSseFrames,
-  negotiateProtocol,
+  PROTOCOL_LIMIT_CEILINGS,
+  PROTOCOL_VERSION,
   utf8ByteLength,
-  type Capability,
   type CreateCubeResponse,
   type LogCursor,
-  type ProtocolInfo,
   type StreamEvent,
 } from '../protocol/index.js';
 import { ENROLLMENT_RETRY_CONFORMANCE } from './index.js';
@@ -57,6 +55,13 @@ export interface ConformanceCreatedCubeState {
 export interface ConformanceEnrollmentPrincipalState {
   response_client_matches: boolean;
   active_credential_bindings: number;
+  /**
+   * The principal's currently-bound credential still equals the one it enrolled
+   * with. Since the credential-free tag preflight cannot probe credentials, this
+   * out-of-band authority check is what proves a rejected mismatch retry did not
+   * overwrite the good credential.
+   */
+  bound_credential_matches_enrollment: boolean;
 }
 
 export interface ConformanceReplayBarrier {
@@ -147,7 +152,8 @@ export interface ConformanceEnvironment {
 
 export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'http.unauthenticated-liveness', area: 'http' },
-  { id: 'protocol.enrollment-auth', area: 'protocol' },
+  { id: 'protocol.credential-free-preflight', area: 'protocol' },
+  { id: 'enrollment.retry-authority', area: 'enrollment' },
   { id: 'security.adapter-boundary-injection', area: 'security' },
   { id: 'security.oversize-request', area: 'security' },
   { id: 'security.cross-cube-isolation', area: 'security' },
@@ -157,7 +163,6 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'acks.idempotent', area: 'acks' },
   { id: 'claims.durable-noncursor', area: 'claims' },
   { id: 'decisions.topic-supersession', area: 'decisions' },
-  { id: 'capabilities.unsupported-fails-closed', area: 'capabilities' },
   { id: 'security.active-stream-revocation', area: 'security' },
 ] as const;
 
@@ -410,8 +415,6 @@ export async function runAdapterConformance(
 
   let credentialA = '';
   let credentialB = '';
-  let protocolBody: unknown;
-  let protocolInfo: ProtocolInfo | null = null;
   await record('http.unauthenticated-liveness', async () => {
     const response = await environment.operations.health();
     expectStatus(response, 204, 'Unauthenticated liveness');
@@ -419,9 +422,23 @@ export async function runAdapterConformance(
     return { status: 204, bodyless: true };
   });
 
-  await record('protocol.enrollment-auth', async () => {
-    expectError(await environment.operations.protocol(null), 401, ErrorCode.AUTH_MISSING, 'Unauthenticated protocol request');
+  await record('protocol.credential-free-preflight', async () => {
+    // The tag preflight is credential-free (no bearer) and mutation-free: a
+    // client verifies pinned TLS and the exact tag before it creates or sends any
+    // credential. The server must answer 200 with ONLY the exact tag.
+    const before = await environment.admin.observeAuthorityState();
+    const response = await environment.operations.protocol(null);
+    expectStatus(response, 200, 'Credential-free protocol-tag preflight');
+    const preflight = decodeProtocolTagPreflight(response.body);
+    invariant(
+      Object.keys(preflight).length === 1 && preflight.protocol_version === PROTOCOL_VERSION,
+      'Protocol-tag preflight exposed more than the exact tag.',
+    );
+    assertStateDelta(before, await environment.admin.observeAuthorityState(), {}, 'Protocol-tag preflight');
+    return { authenticated: false, mutation_free: true, protocol_version: preflight.protocol_version };
+  });
 
+  await record('enrollment.retry-authority', async () => {
     const retryVectorErrors: string[] = [];
     for (const [index, vector] of ENROLLMENT_RETRY_CONFORMANCE.entries()) {
       for (const purpose of ['client', 'owner'] as const) {
@@ -474,23 +491,11 @@ export async function runAdapterConformance(
             );
           }
           assertStateDelta(beforeRetry, await environment.admin.observeAuthorityState(), {}, `${purpose} ${vector.name} retry`);
-          expectStatus(
-            await environment.operations.protocol(vector.initial.client_credential),
-            200,
-            `${purpose} ${vector.name} original credential continuity`,
-          );
-          if (vector.retry.client_credential !== vector.initial.client_credential) {
-            expectError(
-              await environment.operations.protocol(vector.retry.client_credential),
-              401,
-              ErrorCode.AUTH_INVALID,
-              `${purpose} ${vector.name} mismatched credential rejection`,
-            );
-          }
           invariant(
             same(await environment.admin.inspectEnrollmentPrincipal(principal, initial.client_id), {
               response_client_matches: true,
               active_credential_bindings: 1,
+              bound_credential_matches_enrollment: true,
             }),
             `${purpose} ${vector.name} changed enrollment binding ownership.`,
           );
@@ -710,37 +715,23 @@ export async function runAdapterConformance(
       ErrorCode.AUTH_INVALID,
       'Enrollment retry mismatch',
     );
-    const protocolResponse = await environment.operations.protocol(credentialA);
-    expectStatus(protocolResponse, 200, 'Authenticated protocol request');
-    protocolBody = protocolResponse.body;
-    protocolInfo = negotiateProtocol(decodeProtocolInfoEnvelope(protocolBody).payload, [
-      'log.cursor',
-      'stream.sse',
-      'stream.replay',
-      'acks',
-      'claims',
-      'decisions',
-    ]);
     return {
-      unauthenticated: ErrorCode.AUTH_MISSING,
       enrollment_status: 201,
       exact_retry_status: 201,
       mismatched_retry: ErrorCode.AUTH_INVALID,
       response_secret_free: true,
-      protocol_version: protocolInfo.protocol_version,
     };
   });
 
   await record('security.adapter-boundary-injection', async () => {
-    invariant(protocolInfo, 'Protocol fixture did not produce request limits.');
     const injectedMessage = "'); DROP TABLE log_entries; --\r\ndata: forged-sse-frame";
     const injectedBody = JSON.stringify(
       createProtocolEnvelope('inject-b1', { message: injectedMessage }),
     );
     invariant(
-      utf8ByteLength(injectedBody) <= protocolInfo.limits.max_request_bytes &&
-        utf8ByteLength(injectedMessage) <= protocolInfo.limits.max_log_message_bytes,
-      'Injection fixture exceeded an advertised request limit.',
+      utf8ByteLength(injectedBody) <= PROTOCOL_LIMIT_CEILINGS.max_request_bytes &&
+        utf8ByteLength(injectedMessage) <= PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes,
+      'Injection fixture exceeded the shared request-limit ceiling.',
     );
     const injected = await environment.operations.appendRaw(
       credentialB,
@@ -800,15 +791,14 @@ export async function runAdapterConformance(
   });
 
   await record('security.oversize-request', async () => {
-    invariant(protocolInfo, 'Protocol fixture did not produce request limits.');
     const baseBody = JSON.stringify(
       createProtocolEnvelope('oversize-a1', { message: 'must-not-persist' }),
     );
     const oversizedBody = baseBody + ' '.repeat(
-      Math.max(0, protocolInfo.limits.max_request_bytes - utf8ByteLength(baseBody) + 1),
+      Math.max(0, PROTOCOL_LIMIT_CEILINGS.max_request_bytes - utf8ByteLength(baseBody) + 1),
     );
     invariant(
-      utf8ByteLength(oversizedBody) > protocolInfo.limits.max_request_bytes,
+      utf8ByteLength(oversizedBody) > PROTOCOL_LIMIT_CEILINGS.max_request_bytes,
       'Oversize fixture did not exceed max_request_bytes.',
     );
     const response = await environment.operations.appendRaw(credentialA, cubeA, oversizedBody);
@@ -995,22 +985,6 @@ export async function runAdapterConformance(
     return { active_count: 1, active_decision: 'second', supersedes_first: true };
   });
 
-  await record('capabilities.unsupported-fails-closed', async () => {
-    invariant(protocolBody, 'Protocol fixture did not produce an envelope.');
-    let code: ErrorCode | null = null;
-    try {
-      negotiateProtocol(
-        decodeProtocolInfoEnvelope(protocolBody).payload,
-        ['future.required' as Capability],
-      );
-    } catch (error) {
-      if (error instanceof ProtocolContractError) code = error.code;
-      else throw error;
-    }
-    invariant(code === ErrorCode.UNSUPPORTED_CAPABILITY, 'Unsupported capability did not fail closed client-side.');
-    return { code };
-  });
-
   await record('security.active-stream-revocation', async () => {
     invariant(liveCursor, 'Stream fixture did not produce a live cursor.');
     const opened = await environment.operations.openStream(credentialA, cubeA, liveCursor);