borgmcp-shared 0.2.2 → 0.4.0

package/docs/compatibility.md

@@ -1,38 +1,57 @@
 # Protocol Compatibility
 
-`borgmcp-shared` versions the contracts shared by Borg MCP clients and server
-implementations. Package versions and protocol generations are related but are
-not interchangeable: a package release can add helpers without changing the
-wire protocol.
-
-| Package range | Protocol generation | Status |
-| --- | --- | --- |
-| `>=0.2.0 <0.3.0` | `1` | Versioned envelope, runtime codecs, and adapter conformance |
+`borgmcp-shared` carries the wire contract shared by the Borg MCP client and
+server. The client and server are a single clean-slate product: they ship and
+update together, so the contract has no negotiation surface and no
+backwards-compatibility machinery.
+
+## Exact Protocol Tag
+
+`PROTOCOL_VERSION` is the sole acceptance authority. The credential-free,
+mutation-free `GET /api/protocol` preflight returns only the exact tag, and
+`decodeProtocolTagPreflight` fails closed on any other tag, an extra field, or a
+non-object body with a clear static mismatch diagnostic — so a client verifies
+pinned TLS and the tag before it creates or sends any credential. Every
+subsequent envelope also carries the tag and decodes it before any payload as
+defense in depth. There is no capability negotiation, no supported-version list,
+no compatibility matrix, and no package-range or version-range fallback. A peer
+that presents a different tag is rejected — it is never adapted to.
 
 ## Change Policy
 
-Consumers must pin `^0.2.0`, which npm interprets as `>=0.2.0 <0.3.0`. During
-the pre-1.0 series, a breaking envelope or wire-contract change requires a
-minor release (`0.3.0`); additive compatible contracts and corrections use a
-patch release (`0.2.x`). Consumers widen the minor range only after deliberate
-compatibility review. A broad `<1.0.0` range is unsafe because pre-1.0 minor
-versions may break the wire contract.
+A wire-shape change is simply made: the protocol tag increments and both the
+client and server adopt the new tag together in a coordinated release. There is
+no mixed-version window in which an old client and a new server (or the reverse)
+interoperate; incompatible peers fail closed rather than degrade.
 
-A wire-shape change must include all of the following:
+A wire-shape change must include:
 
 1. A new or updated implementation-neutral conformance vector.
 2. A documented client and server rollout order.
-3. A compatibility entry that identifies the affected package and protocol
-   versions.
-4. A migration window when older deployed clients or servers can still be in
-   use.
+3. A package version bump so the new protocol tag never ships under a version
+   whose already-published artifact carries a different tag.
 
 Removing or reinterpreting an existing field is a protocol-breaking change even
 when TypeScript permits it. Implementations must not infer compatibility from a
-successful build alone; they should check the declared protocol generation and
-run the shared conformance suite.
+successful build alone — they must run the shared conformance suite against the
+exact tag they implement.
+
+## Coordinated Rollout
+
+The rollout order is fail-closed:
+
+1. Publish the reviewed `borgmcp-shared` registry artifact only after its
+   separate tag and publication gates pass, under a version that has never been
+   published with a different protocol tag.
+2. Update the client and server releases to the reviewed registry range; Git
+   dependencies are not an authorized release input.
+3. Run the shared adapter conformance suite in both consumers before release.
+4. Deploy client and server support together. A peer on the prior protocol tag
+   and a peer on the new tag are incompatible; neither side falls back.
+
+## Model/Provider Selection
 
-Model/provider selection is intentionally absent from the `0.2.x` coordination
-contract. Agent CLIs own model configuration; Borg servers may expose the
-separate advisory `reported_model` field for session observability, but clients
-must not use it for routing, launch configuration, or authorization.
+Model/provider selection is intentionally absent from the coordination contract.
+Agent CLIs own model configuration; Borg servers may expose the separate
+advisory `reported_model` field for session observability, but clients must not
+use it for routing, launch configuration, or authorization.

package/docs/enrollment.md

@@ -0,0 +1,167 @@
+# Retry-Safe Enrollment and Cube Creation Contract
+
+This document defines the data-only enrollment and cube-creation boundaries
+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 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
+
+Before network I/O, the client generates:
+
+- a cryptographically random 256-bit client bearer, encoded as canonical
+  unpadded base64url; and
+- a canonical UUID retry key.
+
+The client persists both values as a pending enrollment in the operating-system
+keychain before sending the request. It retains and reuses the exact pending
+tuple after an ambiguous timeout or connection loss. The wire contract never
+permits a file fallback, URL/argv/environment transport, or diagnostic output
+for these secrets.
+
+## Exchange Request
+
+`POST /api/enrollment/exchange` receives one strict payload inside the protocol
+envelope:
+
+```json
+{
+  "invitation": "<opaque invitation>",
+  "retry_key": "00000000-0000-4000-8000-000000000101",
+  "client_credential": "<43-character canonical base64url>",
+  "client_name": "optional presentation label"
+}
+```
+
+`client_name` is bounded presentation data. All other fields are required.
+Unknown fields, weak credentials, noncanonical UUIDs, controls, and ambiguous
+aliases fail closed. Invitation purpose is server-owned persisted state; the
+request has no caller-controlled owner flag, plan, role, grant, or cube.
+
+## Secret-Free Responses
+
+Ordinary enrollment returns only:
+
+```json
+{
+  "purpose": "client",
+  "client_id": "<canonical UUID>",
+  "server_capabilities": []
+}
+```
+
+An ordinary enrollment creates no cube grant. It cannot infer access from
+enrollment order, owner metadata, or a role label.
+
+A successful purpose-bound owner enrollment returns only the narrow server
+capability persisted for that client:
+
+```json
+{
+  "purpose": "owner",
+  "client_id": "<canonical UUID>",
+  "server_capabilities": ["create_cube"]
+}
+```
+
+The response never contains, echoes, rotates, or recovers the client bearer,
+invitation, retry key, recovery credential, or a session credential. Owner
+enrollment creates zero cubes, roles, and cube grants. `create_cube` authorizes
+only authenticated cube creation; it does not reveal or grant access to any
+existing cube and is never inferred from enrollment order, owner metadata, or a
+role label.
+
+## Retry Semantics
+
+The server binds the consumed invitation to the canonical retry tuple and stores
+only a keyed client credential digest. A retry is successful only when the retry key,
+submitted credential proof, optional client name, invitation purpose, and
+server-owned owner-claim epoch exactly match the original enrollment. It
+returns the same non-secret response and performs no mutation.
+
+A reused invitation with a different retry key, credential, client name,
+purpose, epoch, or plan receives the same non-enumerating `AUTH_INVALID` class as
+an absent, expired, revoked, malformed, or already-consumed invitation. It never
+rotates credentials or creates another client, capability, cube, role, or grant.
+
+## Server Transaction Boundary
+
+For an owner invitation, the server capacity-preflights and atomically binds the
+invitation/retry tuple, inserts the keyed client credential digest, persists the
+`create_cube` capability, and marks the invitation/owner epoch claimed. It
+creates no cube, role, or cube grant. Any failure rolls back every mutation,
+including invitation consumption.
+
+Ordinary invitation exchange atomically creates only the client and credential
+digest. Explicit grants are a separate offline administrative operation. Network
+enrollment and attach routes never create or widen grants.
+
+## Cube Creation
+
+`POST /api/cubes` requires an active parent-client credential with the persisted
+`create_cube` server capability. Ordinary clients, revoked clients, and drone
+sessions cannot use it. Its strict payload is:
+
+```json
+{
+  "retry_key": "00000000-0000-4000-8000-000000000201",
+  "name": "repository presentation name",
+  "template": "default"
+}
+```
+
+The client persists the pending retry tuple before network I/O and reuses it
+after ambiguous transport failure. `name` is bounded presentation data and
+`template` selects allowlisted, server-owned inert data. The request cannot
+supply cube or role IDs, an owner, access, grant target, capability, arbitrary
+template data, paths, URLs, modules, commands, or repository credentials.
+
+The server binds `(authenticated client, retry_key)` to the exact canonical name
+and template. A successful transaction atomically creates one cube, exactly one
+human-seat role, exactly one default worker role, and exactly one creator
+`manage` grant. It returns:
+
+```json
+{
+  "cube_id": "<canonical UUID>",
+  "human_seat_role_id": "<canonical UUID>",
+  "default_worker_role_id": "<canonical UUID>",
+  "access": "manage"
+}
+```
+
+An exact retry returns that stable response without mutation. Reusing the same
+retry key with a different name or template returns non-enumerating HTTP `409`
+`INVALID_INPUT` and creates nothing. A fresh retry key may create another cube,
+subject to implementation quotas. `owner_id` and role labels remain metadata;
+cube access derives only from the explicit cube-scoped grant.
+
+## Conformance
+
+`ENROLLMENT_RETRY_CONFORMANCE` covers exact retry stability plus retry-key,
+credential, and client-name mismatches. `ENROLLMENT_REDACTION_CONFORMANCE` pins
+diagnostic redaction for invitation, bearer, and contextual retry-key values
+while preserving unrelated public UUIDs. `ENROLLMENT_AUTHORITY_CONFORMANCE`
+distinguishes ordinary zero-authority enrollment from owner `create_cube`
+authority with zero initial cube state. The executable adapter runner drives
+every retry vector, observes client/capability/cube/role/grant counts, verifies
+secret-free errors, and proves authorized idempotent cube creation. Hostile
+reference adapters demonstrate that each retry, authority, and idempotency
+violation fails conformance.

package/docs/releasing.md

@@ -122,6 +122,38 @@ Under the ratified `borgmcp-shared-recovery-version` decision, `0.2.2` is the
 selected recovery version. The source bump does not itself authorize a tag,
 environment approval, or publication.
 
+Run `29360398007` published `borgmcp-shared@0.2.2` from the exact approved
+artifact, and the registry integrity and maintainer matched that artifact. The
+workflow then failed during immediate postpublish verification when the package
+ownership read returned HTTP 404 before registry propagation completed. The run
+and `v0.2.2` tag are immutable and MUST NOT be rerun, moved, or reused. Consumer
+migration was blocked until provenance and signatures were independently verified
+and Security approved the recovery evidence.
+
+Recover out of band without rerunning the workflow:
+
+1. Download artifact `8321897865` from run `29360398007` and recheck its recorded
+   ZIP digest, `RUN_EVIDENCE`, tarball SHA-512, and artifact verifier report.
+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. 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.
+4. Record the independent integrity, ownership, signed-provenance, and signature
+   evidence for a fresh Security verdict before changing any consumer dependency.
+
+That recovery completed successfully: the registry tarball is byte-identical to
+the audited artifact, its sole maintainer is `byteventures`, the signed in-toto
+SLSA provenance binds the protected workflow/tag/commit/run, and npm verified one
+registry signature plus one publish attestation. Security approved the recovery
+evidence. Complete the bootstrap credential and Trusted Publisher cleanup below
+before migrating consumers.
+
 The eventual first publication will use one temporary credential while still
 generating provenance from GitHub Actions.
 
@@ -185,6 +217,45 @@ Immediately after a successful first publish:
 
 ## Later Releases
 
+### 0.4.0 Clean-Slate v2 Contract
+
+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.4.0` tag is created:
+
+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`, 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.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
+   exact installed dependency graph and zero package runtime dependencies. The
+   tarball, SBOM, and SBOM validation report must be
+   checksummed and uploaded together for Security audit.
+5. The tag and publication each require their own explicit authorization. A
+   source-version approval, merge, or successful verification run grants neither.
+
+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.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
 preflight requires the package to be owned by `NPM_EXPECTED_OWNER` and rejects
@@ -210,11 +281,11 @@ Stop without approving the environment when any of these conditions occurs:
 - final CR, Security, Release Quality, exact-tarball Security approval, or Queen
   authorization is missing.
 
-npm versions are immutable. Never retry by overwriting `0.2.0`, moving the tag,
-force-pushing a branch, or publishing from a local rebuild. A failed verification
-before publication requires fixing the source and beginning again with a new
-reviewed version/tag plan. If npm accepted the version but integrity or
-provenance verification failed, block every consumer migration, preserve the
-workflow logs and artifact, and escalate as a release incident. Do not unpublish,
+npm versions are immutable. Never retry by overwriting any published version,
+moving a release tag, force-pushing a branch, or publishing from a local rebuild.
+A failed verification before publication requires fixing the source and
+beginning again with a new reviewed version/tag plan. If npm accepted the version
+but integrity or provenance verification failed, block every consumer migration,
+preserve the workflow logs and artifact, and escalate as a release incident. Do not unpublish,
 deprecate, or publish a replacement version without a separately reviewed and
 authorized recovery decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,6 +56,7 @@
     "check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "verify:artifact": "node scripts/verify-packed-artifact.mjs",
+    "verify:sbom": "node scripts/verify-release-sbom.mjs",
     "prepack": "npm run check && npm test && npm run build"
   },
   "keywords": [