borgmcp-shared 0.2.2 → 0.3.0

package/docs/enrollment.md

@@ -0,0 +1,160 @@
+# 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
+`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.
+
+## 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,37 @@ 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 with bounded
+   backoff; 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 +216,40 @@ Immediately after a successful first publish:
 
 ## Later Releases
 
+### 0.3.0 Enrollment 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.
+
+Before a separately authorized `v0.3.0` tag is created:
+
+1. The exact `0.3.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`.
+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
+   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.3.0`. They must not
+ship a Git dependency or fall back to the incompatible `0.2.x` 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 +275,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.3.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": [