borgmcp-shared 0.4.2 → 0.5.0

package/docs/releasing.md

@@ -1,313 +1,130 @@
 # Publishing `borgmcp-shared`
 
-This repository publishes immutable public releases from a protected GitHub
-Actions environment. A release is built once, audited as a tarball, and then
-published from that exact tarball. Local publication and publication from an
-unreviewed branch are not supported.
-
-The active release policy is governed by the ratified
-`shared-package-consumption`, `borgmcp-shared-coordinator-autonomy`, and
-`npm-publish-sole-operator-approval` decisions. This document describes the
-operator procedure; it does not authorize a release.
-
-## Permanent Repository Configuration
-
-Configure these controls before creating a release tag:
-
-1. Keep `.github/workflows/publish.yml` as the only npm trusted-publisher
-   workflow. The workflow uses a GitHub-hosted runner, exact Node and npm
-   versions, no dependency cache, and only `contents: read` plus
-   `id-token: write` in the protected publish job. npm is installed with
-   lifecycle scripts disabled under an isolated `${RUNNER_TEMP}` prefix; only
-   that prefix's bin directory enters `GITHUB_PATH`. Never update the active
-   global npm installation from within npm itself.
-2. Create a GitHub environment named `npm-publish`. Require an authorized
-   approval from the sole operator `TheodorStorm`, allow self-review so that the
-   sole-operator path remains executable, and prevent administrators from
-   bypassing its protection rules. Store npm bootstrap credentials only in this
-   environment. This exact shape is ratified by
-   `npm-publish-sole-operator-approval`; adding any other reviewer or bypass
-   actor requires a new decision.
-3. Add an active tag ruleset whose only included ref is
-   `refs/tags/v*.*.*`. Enable creation, update (without fetch-and-merge),
-   deletion, and non-fast-forward restrictions. The sole bypass actor is the
-   release-operator user `TheodorStorm` (GitHub user ID `12745431`), with no
-   role, administrator, team, application, or deploy-key bypass. Require an
-   annotated tag; the workflow rejects lightweight tags and tags whose commit is
-   not on `main`.
-4. Set the environment variable `NPM_EXPECTED_OWNER` to `byteventures`, the npm
-   maintainer returned by `npm view borgmcp maintainers`. Do not infer this value
-   from package metadata.
-5. Keep the GitHub repository public when provenance is generated. npm cannot
-   issue provenance for a public package built from a private GitHub repository,
-   and the workflow stops if the repository is private.
-6. Protect `refs/heads/main` with an active ruleset and no bypass actors. Require
-   resolved review threads and the `package (20)` and `package (22)` checks from
-   GitHub Actions application ID `15368`, with strict status checking. Set the
-   GitHub approval count to zero and disable stale-review dismissal, code-owner
-   review, and last-push approval: the separately recorded cube CR, Security,
-   and Release Quality gates are the human evidence, while a GitHub approval
-   requirement would be inoperable for the sole repository operator. Allow
-   merge commits only and protect deletion and non-fast-forward operations. Do
-   not add a restrictive update rule, which would block normal pull-request
-   merges without a bypass.
-7. Restrict Actions to selected GitHub-owned actions and require full commit-SHA
-   pins. Do not allow all verified Marketplace publishers or any custom pattern.
-   The CI and publish workflows need only `actions/checkout`,
-   `actions/setup-node`, `actions/upload-artifact`, and
-   `actions/download-artifact`, each pinned in source. Keep workflow tokens
-   read-only and prohibit them from approving pull requests.
-8. Enable GitHub private vulnerability reporting, secret scanning, push
-   protection, and Dependabot security updates unconditionally. Enable secret
-   validity checks and non-provider pattern detection whenever the organization
-   plan licenses them. GitHub requires a paid plan with GitHub Secret Protection
-   for [validity checks](https://docs.github.com/en/code-security/how-tos/secure-your-secrets/customize-leak-detection/enable-validity-checks)
-   and [non-provider patterns](https://docs.github.com/en/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns).
-   The configuration guard accepts those two controls as disabled only while the
-   live organization plan is exactly `free`; a plan change makes them mandatory.
-   `SECURITY.md` directs reporters to the private reporting path, so disabled
-   reporting is always a release-blocking documentation failure.
-
-The environment approval is the final technical control. It appears only on the
-`publish` job, after `validate` has verified the SR approval tuple. Approval must
-remain pending while Security reviews the artifact produced by the `verify` job.
-GitHub's ephemeral workflow token cannot read every repository-administration
-setting checked by `scripts/verify-release-configuration.mjs`. An authorized
-operator must run the guard with an administration-capable token before creating
-the tag and again immediately before approving the environment:
+This repository publishes immutable public releases through one protected workflow job
+in GitHub Actions. The active `minimal-package-release-assurance` decision replaces the
+former cross-run artifact approval protocol. This runbook describes the current
+operator procedure; it does not authorize a tag or publication.
+
+## Assurance Boundary
+
+The release lane has one build, test, package, and publication authority:
+`.github/workflows/publish.yml` on an annotated `v*.*.*` tag. The job:
+
+1. verifies the public repository context, exact package version, annotated tag,
+   tag commit, and ancestry on protected `main`;
+2. installs locked dependencies without lifecycle scripts and runs dependency
+   audit, type checks, the full test suite, one clean build, and generated-output
+   drift detection;
+3. creates one local tarball, enforces the packed-artifact policy, and installs
+   that tarball into a clean consumer that imports every public export;
+4. rejects an existing immutable version or a package not owned solely by the
+   configured npm owner before any registry mutation;
+5. publishes that exact local tarball through npm Trusted Publishing with
+   provenance; and
+6. uses bounded registry-propagation retries to compare the published
+   `dist.integrity` with the tarball, then installs the exact registry version
+   with scripts disabled and runs `npm audit signatures`.
+
+npm and GitHub verify the registry signature and publish attestation. The
+repository does not reconstruct DSSE or SLSA statements, transfer approval
+tuples between runs, rebuild in a second job, or place checksum, SBOM, and report
+bundles on the critical publication path. SBOM portability remains covered by
+CI and the repository's dedicated deterministic SBOM tests.
+
+## Permanent Configuration
+
+Keep these controls in place:
+
+1. `publish.yml` is the only npm Trusted Publisher workflow for organization
+   `Byte-Ventures`, repository `borg-mcp-shared`, and environment `npm-publish`.
+2. The `npm-publish` environment requires the authorized sole operator
+   `TheodorStorm`, permits that operator's self-review, prevents administrator
+   bypass, and allows only protected `v*.*.*` tags.
+3. `NPM_EXPECTED_OWNER` is `byteventures`. It comes from the live npm package
+   maintainer record, not package metadata.
+4. No `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or committed `.npmrc` participates in an
+   owned-package release. Authentication is the job's short-lived OIDC exchange.
+5. The publish job uses a GitHub-hosted runner with only `contents: read` and
+   `id-token: write`. Actions are GitHub-owned and pinned to full commit SHAs.
+6. Protected `main`, the release-tag ruleset, private vulnerability reporting,
+   secret scanning, push protection, and dependency security updates remain
+   enabled as checked by `scripts/verify-release-configuration.mjs`. Secret
+   scanning validity checks and non-provider patterns remain mandatory whenever
+   the organization plan licenses them.
+
+Before creating a tag and again before approving the environment, an authorized
+operator runs:
 
 ```sh
 GITHUB_TOKEN="$(gh auth token)" node scripts/verify-release-configuration.mjs
 ```
 
-The token is read from the operator's credential store and must not be written
-to the repository, an artifact, or workflow output. Any guard failure blocks the
-tag or environment approval.
-
-Every release and verification-only run must be a first attempt. The workflow
-logs `GITHUB_RUN_ID` and `GITHUB_RUN_ATTEMPT`, rejects any attempt other than `1`
-before dependency installation, and includes the same values in the uploaded
-`RUN_EVIDENCE` file. Never use the Actions rerun controls to advance a failed
-immutable tag or proof run.
-
-All three jobs reject a repository-root `.npmrc` before their first npm command. The
-exact npm bootstrap uses isolated runner-temp prefix, user config, and cache
-paths, forces `https://registry.npmjs.org`, disables scripts, and verifies both
-the installed npm version and registry before adding its bin directory to
-`GITHUB_PATH`.
-
-## First-Publish Bootstrap
-
-npm trusted publishing cannot be configured until the unscoped package exists.
-The initial `v0.2.0` bootstrap run, `29353763609`, failed during verification
-before producing an artifact or reaching publication. The failed `v0.2.0` tag is
-immutable and MUST NOT be moved, reused, or rerun. The separately authorized
-`v0.2.1` tag run, `29355823822`, also failed verification before dependency
-installation or artifact creation because the checkout action replaced its local
-annotated-tag ref with the peeled commit. The remote `v0.2.1` tag remains valid
-and immutable and MUST NOT be moved, reused, or rerun.
-
-The first protected-main verification-only proof run, `29356980492`, confirmed
-the repaired tag/source trust checks, then failed before artifact upload because
-npm 11 interpreted the bare `release/<tarball>` argument as a package/GitHub spec
-instead of a local file. It produced no auditable artifact and MUST NOT be rerun.
-The workflow now passes generated tarballs to both npm dry-run and publication as
-explicit `./release/<tarball>` filesystem paths.
-
-The next protected-main proof run, `29357632667`, passed every verification gate
-against immutable `v0.2.1`, structurally skipped the publish job, and produced an
-exact artifact that passed Security audit. This proved the corrected tag,
-protected-main, input, artifact, and npm local-file handling without reusing the
-tag for publication.
-
-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.
-
-Before creating the tag, the release operator must verify all of the following:
-
-- The npm account is the account that owns `borgmcp`, uses authentication-and-
-  writes 2FA, and has tested, protected recovery methods.
-- `borgmcp-shared` is still unclaimed. An `E404` is expected. Any package or
-  ownership result that differs from the reviewed state is a stop condition.
-- Code Review, load-bearing Security Review, and Release Quality approved the
-  exact commit on `main`.
-- The Queen explicitly authorized generating the final release artifact. This
-  authorization does not by itself approve the later environment deployment.
-
-Create a short-lived, least-privilege npm publish token under the verified owner
-account. Store it as the `NPM_TOKEN` secret in the `npm-publish` environment;
-never place it in repository variables, workflow files, shell history,
-`package.json`, a committed `.npmrc`, or an issue. Set the protected environment
-variable `ALLOW_UNCLAIMED_FIRST_PUBLISH` to `true` only for this bootstrap.
-
-The `0.2.2` package, lockfile, runbook, and version assertions must pass fresh CR,
-Security, and Release Quality gates and merge to protected `main` before the
-Coordinator creates its matching annotated tag under
-`borgmcp-shared-first-publish-autonomy`. The tag starts the workflow but does not
-immediately publish. The unprivileged `verify` job performs the following gates
-first:
-
-- verifies the public repository, annotated tag, exact package version, and
-  ancestry on `main`;
-- installs the lockfile without lifecycle scripts and runs audit, type checks,
-  all tests, a clean build, and the tracked-`dist` drift check;
-- creates one tarball with lifecycle scripts disabled;
-- enforces the explicit public file allowlist, legal files, dependency and
-  lifecycle policy, size limits, and resolvable source maps;
-- exercises npm's publish metadata in dry-run mode; and
-- installs the exact tarball with scripts disabled in a clean consumer, verifies
-  its production tree, and imports every reviewed public export; and
-- uploads the tarball, verifier report, SHA-512 checksum, SBOM, and
-  `RUN_EVIDENCE` for seven days.
-
-Security must download and audit that exact workflow artifact. After Security
-approves the tarball, Release Quality confirms the operator procedure, and the
-Queen explicitly authorizes the public flip, the Coordinator writes the SR
-approval tuple (`ARTIFACT_SR_SHA512`, `ARTIFACT_SR_RUN_ID`,
-`ARTIFACT_SR_RUN_ATTEMPT`) to environment variables and dispatches the
-`publish.yml` workflow with the tag. The `validate` job runs first (outside
-the `npm-publish` environment): it re-verifies the source, queries the source
-run's workflow path, tag, conclusion, and attempt via the GitHub API, downloads
-the artifact, binds the SR tuple to the exact tarball, and confirms run identity.
-Only after `validate` succeeds does the `publish` job run, which surfaces the
-`npm-publish` environment approval dialog. The `publish` job re-downloads and
-checksum-verifies the same artifact, re-binds the SR tuple, repeats the artifact
-verifier, checks that `0.2.2` is absent and the name is unclaimed as expected,
-and publishes only the downloaded tarball with `--access public --provenance`.
-
-Immediately after a successful first publish:
-
-1. Confirm the workflow's registry-integrity, owner, and SLSA provenance checks
-   passed before changing any consumer dependency.
-2. Configure npm's trusted publisher for organization `Byte-Ventures`, repository
-   `borg-mcp-shared`, workflow filename `publish.yml`, environment
-   `npm-publish`, and the `npm publish` action.
-3. Remove the `NPM_TOKEN` environment secret, revoke the bootstrap token at npm,
-   and set `ALLOW_UNCLAIMED_FIRST_PUBLISH` to `false`.
-4. Configure npm publishing access to require 2FA and disallow traditional
-   tokens. Future releases authenticate through short-lived OIDC credentials.
-5. Only then replace consumers' exact Git SHA dependencies with
-   `borgmcp-shared@^0.2.0` and commit their registry lockfiles.
-
-## Later Releases
-
-### 0.4.2 Cross-Platform SBOM Recovery
-
-`borgmcp-shared@0.4.0` is the published, immutable clean-slate v2 contract, but
-its registry artifact was built before the public package's local/self-hosted
-topology cleanup. The immutable `v0.4.1` run `29701429995` built the cleaned
-artifact, but independent macOS verification proved that the SBOM verifier used
-the auditor's installed optional-dependency tree instead of a deterministic
-release graph. The `v0.4.1` tag, run, and artifact are failed evidence: never
-publish, move, reuse, rerun, or substitute them.
-
-Version `0.4.2` carries the reviewed cleanup with a lockfile-derived SBOM graph
-for the fixed release target `{os: linux, cpu: x64, libc: glibc}`. It does not
-change the protocol tag or runtime behavior. This source now identifies `0.4.2`.
-The reviewed recovery bump does not authorize creating `v0.4.2` or publishing
-the package.
-
-Before a separately authorized `v0.4.2` tag is created:
-
-1. The exact `0.4.2` source commit must be merged to protected `main` after Code
-   Review, Security, and Release Quality approve the package identity, public
-   API, generated output, and release documentation.
-2. The package and root lockfile, `SHARED_PACKAGE_VERSION`, packed-artifact and
-   SBOM verifiers, generated declarations, and version assertions must all
-   identify `0.4.2`. The protocol tag remains unchanged.
-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.2` 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 lockfile-derived release-target graph and zero package runtime
-   dependencies. The graph starts from root development dependencies, follows
-   required dependencies and peers, includes only target-compatible optional
-   dependencies, and includes optional peers only when another reachable edge
-   installs them. Root manifest and lock selectors must match and permit the
-   fixed target. Verification must not inspect the auditor's operating system,
-   installed dependency tree, or `node_modules`. 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 must pin exact
-`borgmcp-shared@0.4.2` and commit their registry lockfiles. They must not ship a
-Git dependency, a version range that can resolve to the pre-cleanup artifact, or
-a fallback to the incompatible `0.3.0` v1 enrollment response.
-
-Later releases follow the same source gates, annotated protected tag, exact
-tarball audit, Coordinator authorization under the ratified shared release
-autonomy, and environment approval. The registry
-preflight requires the package to be owned by `NPM_EXPECTED_OWNER` and rejects
-an existing target version. It also fails if
-`ALLOW_UNCLAIMED_FIRST_PUBLISH` is not `false` or any `NPM_TOKEN` remains;
-npm must exchange the workflow's OIDC identity through the configured trusted
-publisher.
-
-## Stop and Recovery Conditions
-
-Stop without approving the environment when any of these conditions occurs:
-
-- the repository is private, the tag is lightweight or unprotected, the tag
-  does not exactly match `v<package version>`, or its commit is not on `main`;
-- the approved commit, tag target, tarball checksum, or audit artifact differs;
-- `GITHUB_RUN_ATTEMPT` is not `1`, or run/attempt evidence is missing;
-- tests, audit, build, tracked output, artifact policy, legal metadata, or dry
-  run fails;
-- the npm name, expected owner, account 2FA, recovery methods, credential scope,
-  trusted-publisher configuration, or environment protection cannot be verified;
-- the target version already exists, npm returns anything other than the
-  expected ownership/availability response, or npm/GitHub is degraded; or
-- final CR, Security, Release Quality, exact-tarball Security approval, or Queen
-  authorization is missing.
-
-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.
+The token must remain in the operator credential store. Never write it to the
+repository, workflow output, artifact, issue, or shell history.
+
+## Release Procedure
+
+1. Merge the exact version, lockfile, generated output, and release documentation
+   to protected `main` after the required exact-SHA Code Review, Security Review,
+   and Release Quality gates.
+2. Verify repository controls with the configuration guard above. Confirm the
+   target version does not already exist and `borgmcp-shared` is owned solely by
+   `byteventures`.
+3. Obtain the separately required exact-commit tag authorization. Create and push
+   one annotated `v<package-version>` tag at that protected-main commit.
+4. The tag starts the single publish job and leaves it pending at the protected
+   `npm-publish` environment. Do not use workflow rerun controls; every immutable
+   tag gets one first attempt.
+5. Obtain the separately required environment approval, then approve that exact
+   pending job. Approval does not permit a local rebuild or alternate artifact.
+6. Require every job step to pass, including exact registry integrity and
+   `npm audit signatures`, before announcing the version or updating consumers.
+
+The workflow publishes only `./release/<tarball>`. It never publishes from the
+repository directory, a package name, a URL, a prior workflow artifact, or a
+locally rebuilt replacement.
+
+## Stop And Recovery
+
+Stop before publication when source identity, tag ancestry, repository
+visibility, environment protection, expected owner, target-version absence,
+tests, build output, tarball policy, clean-consumer imports, or Trusted Publishing
+configuration cannot be verified.
+
+If a first-attempt tag run fails before npm accepts the version, preserve the tag
+and run as immutable evidence. Fix the source and begin a separately reviewed and
+authorized version/tag plan. Never move, reuse, rerun, or force-update the failed
+tag.
+
+If npm accepts the version but a bounded integrity or signature check fails, do
+not rerun or republish. Preserve the run, inspect the live registry integrity and
+`npm audit signatures` result, and require an explicit recovery decision before
+consumer adoption. npm versions are immutable; never overwrite, unpublish, or
+silently substitute a replacement.
+
+## Immutable Historical Evidence
+
+These records remain evidence, not reusable release inputs:
+
+- `v0.2.0` run `29353763609` and `v0.2.1` run `29355823822` failed before
+  artifact creation or publication.
+- Protected-main proof runs `29356980492` and `29357632667` diagnosed and then
+  verified the earlier tag/source and local-file handling. They are not publish
+  artifacts.
+- Run `29360398007` published `borgmcp-shared@0.2.2`; its initial ownership
+  readback hit registry propagation. Independent integrity, ownership,
+  provenance, and npm signature verification completed before consumer adoption.
+- `v0.4.1` run `29701429995` exposed a non-deterministic cross-platform SBOM
+  audit path and was never published.
+- `borgmcp-shared@0.4.2` is accepted as published and verified. Its registry
+  integrity matches the audited tarball and npm verifies its signature and
+  attestation. Publish run `29729515410` must not be rerun; the failed custom
+  postpublish check reconstructed the wrong workflow identity and is the reason
+  that machinery was removed.
+
+`borgmcp-shared@0.4.3` is published and immutable. This source identifies the
+unpublished `0.5.0` protocol v3 release. Its release requires reviewed source and
+explicit publication authorization through one protected publish run, followed by
+postpublish registry integrity, signature, and attestation verification. Consumers
+must update the reviewed shared artifact before adopting the matching server and
+client releases; protocol v2 and v3 peers fail closed at credential-free preflight.

package/package.json

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

package/src/conformance/adapter.ts

@@ -1543,9 +1543,9 @@ export async function runAdapterConformance(
     const expiredCredential = await environment.admin.issueManagedDroneSession(expiredDrone);
     await environment.admin.revokeManagedDroneSession(revokedDrone);
     await environment.admin.expireManagedDroneSession(expiredDrone);
-    for (const [label, credential] of [
-      ['revoked', revokedCredential],
-      ['expired', expiredCredential],
+    for (const [label, credential, code] of [
+      ['revoked', revokedCredential, ErrorCode.SESSION_REVOKED],
+      ['expired', expiredCredential, ErrorCode.AUTH_EXPIRED],
     ] as const) {
       expectError(
         await environment.operations.read(
@@ -1554,14 +1554,15 @@ export async function runAdapterConformance(
           createProtocolEnvelope(`${label}-seat-probe`, { cursor: null, limit: 1 }),
         ),
         401,
-        ErrorCode.SESSION_REVOKED,
+        code,
         `${label} seat probe`,
       );
     }
     return {
       revoked_status: 401,
       expired_status: 401,
-      code: ErrorCode.SESSION_REVOKED,
+      revoked_code: ErrorCode.SESSION_REVOKED,
+      expired_code: ErrorCode.AUTH_EXPIRED,
     };
   });
 

package/src/conformance/index.ts

@@ -1,5 +1,5 @@
 import type { BroadcastHwm } from '../log-stream-hwm.js';
-import type { EnrollmentExchangeRequest } from '../protocol/contract.js';
+import type { AttachResponse, EnrollmentExchangeRequest } from '../protocol/contract.js';
 
 export * from './adapter.js';
 
@@ -205,3 +205,35 @@ export const ENROLLMENT_REDACTION_CONFORMANCE: readonly ConformanceVector<string
     expected: `cube_id=${ENROLLMENT_RETRY_KEY}`,
   },
 ];
+
+export interface AttachSessionConformanceVector {
+  name: string;
+  response: unknown;
+  accepts: boolean;
+}
+
+const ATTACH_RESPONSE = {
+  result: 'created',
+  cube: { id: '10000000-0000-4000-8000-000000000001', name: 'test-cube' },
+  role: { id: '20000000-0000-4000-8000-000000000001', name: 'Coordinator' },
+  drone: { id: '30000000-0000-4000-8000-000000000001', label: 'one-of-one-coordinator' },
+  session: { id: '40000000-0000-4000-8000-000000000001' },
+} satisfies AttachResponse;
+
+/** Wire vectors for the v3 non-expiring attach-session response. */
+export const ATTACH_SESSION_CONFORMANCE: readonly AttachSessionConformanceVector[] = [
+  { name: 'accepts exact non-expiring session id', response: ATTACH_RESPONSE, accepts: true },
+  {
+    name: 'rejects retired expires_at field',
+    response: {
+      ...ATTACH_RESPONSE,
+      session: { ...ATTACH_RESPONSE.session, expires_at: '2026-07-18T15:00:00.000Z' },
+    },
+    accepts: false,
+  },
+  {
+    name: 'rejects session fields beyond id',
+    response: { ...ATTACH_RESPONSE, session: { ...ATTACH_RESPONSE.session, extra: 'value' } },
+    accepts: false,
+  },
+];

package/src/protocol/contract.ts

@@ -2,7 +2,7 @@ import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.4.2' as const;
+export const SHARED_PACKAGE_VERSION = '0.5.0' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
@@ -28,6 +28,9 @@ export const PROTOCOL_HTTP_CONTRACT = {
   },
   auth_missing_status: 401,
   auth_invalid_status: 401,
+  auth_expired_status: 401,
+  session_revoked_status: 401,
+  session_rejected_status: 401,
   cursor_expired_status: 410,
   drone_evicted_status: 410,
   content_too_large_status: 413,
@@ -604,7 +607,7 @@ export function maxLogCursor(a: LogCursor | null, b: LogCursor | null): LogCurso
   return compareLogCursor(a, b) >= 0 ? decodeLogCursor(a) : decodeLogCursor(b);
 }
 
-// ── v2 clean-slate wire types ──────────────────────────────────────────────
+// ── v3 clean-slate wire types ──────────────────────────────────────────────
 
 export const ATTACH_PATH = '/api/client/attach' as const;
 
@@ -636,7 +639,6 @@ export interface AttachDrone {
 
 export interface AttachSession {
   id: string;
-  expires_at: string;
 }
 
 export interface AttachResponse {
@@ -689,15 +691,14 @@ function decodeAttachDrone(value: unknown, path: readonly (string | number)[]):
 
 function decodeAttachSession(value: unknown, path: readonly (string | number)[]): AttachSession {
   const input = record(value, path);
-  exactKeys(input, ['id', 'expires_at'], ['id', 'expires_at'], path);
+  exactKeys(input, ['id'], ['id'], path);
   return {
     id: decodeUuid(input.id, [...path, 'id']),
-    expires_at: decodeCanonicalTimestamp(input.expires_at, [...path, 'expires_at']),
   };
 }
 
 /**
- * Decode a v2 attach request. Strict: exact keys, bounded sizes,
+ * Decode a v3 attach request. Strict: exact keys, bounded sizes,
  * session_credential is token-safe and never echoed in errors.
  */
 export function decodeAttachRequest(value: unknown): AttachRequest {
@@ -719,7 +720,7 @@ export function decodeAttachRequest(value: unknown): AttachRequest {
 }
 
 /**
- * Create a v2 attach request envelope. Stamps the canonical protocol version.
+ * Create a v3 attach request envelope. Stamps the canonical protocol version.
  */
 export function createAttachRequestEnvelope(
   requestId: string,
@@ -733,7 +734,7 @@ export function createAttachRequestEnvelope(
 }
 
 /**
- * Decode a v2 attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
+ * Decode a v3 attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
  * BEFORE decoding the payload — a wrong tag never invokes the payload decoder
  * and never exposes or returns the supplied session_credential.
  * Uses a static token-safe diagnostic; does not interpolate attacker-controlled text.
@@ -763,8 +764,7 @@ export function decodeAttachRequestEnvelope(
 }
 
 /**
- * Decode a v2 attach response. Strict: exact keys, result discriminant,
- * expires_at required non-null finite ISO-8601.
+ * Decode a v3 attach response. Strict: exact keys and result discriminant.
  */
 export function decodeAttachResponse(value: unknown): AttachResponse {
   const input = record(value);
@@ -788,7 +788,7 @@ export function decodeAttachResponse(value: unknown): AttachResponse {
 }
 
 /**
- * Decode a v2 attach response wrapped in a ProtocolEnvelope.
+ * Decode a v3 attach response wrapped in a ProtocolEnvelope.
  * Verifies protocol_version === PROTOCOL_VERSION before decoding payload.
  */
 export function decodeAttachResponseEnvelope(value: unknown): ProtocolEnvelope<AttachResponse> {