ci(release): switch npm publishing to OIDC trusted publishing; document verified releases (#1298)

All seven published packages (@colbymchenry/codegraph + six platform
bundles) now have this repo's release.yml configured as their trusted
publisher on npmjs.com, so publishes authenticate via the workflow's
OIDC identity instead of a long-lived NPM_TOKEN. The runner upgrades to
npm 11 (trusted publishing needs >= 11.5; Node 22 bundles npm 10) and
setup-node no longer writes a token-referencing .npmrc.

README gains a 'Verified releases' section + badges: how npm provenance
and the GitHub Release attestations work and the commands to verify them
(npm audit signatures / gh attestation verify).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

.github/workflows/release.yml

@@ -13,7 +13,13 @@ name: Release
 #   5. publishes the npm thin-installer (shim + per-platform packages).
 #
 # Before triggering: bump package.json. CHANGELOG.md entries can live under
-# `## [Unreleased]` — step 2 takes care of moving them. Set the NPM_TOKEN secret.
+# `## [Unreleased]` — step 2 takes care of moving them.
+#
+# npm auth is OIDC trusted publishing (no NPM_TOKEN): every published package
+# (@colbymchenry/codegraph + the per-platform bundles) has this repo +
+# release.yml configured as its trusted publisher on npmjs.com. Adding a new
+# platform package means configuring its trusted publisher there before the
+# first release that includes it.
 on:
   workflow_dispatch: {}
 
@@ -47,7 +53,13 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 22
-          registry-url: https://registry.npmjs.org
+          # No registry-url here: it writes an .npmrc that requires a
+          # NODE_AUTH_TOKEN env var to exist, and we publish via OIDC
+          # trusted publishing instead of a token.
+
+      - name: Upgrade npm for OIDC trusted publishing
+        # Trusted publishing needs npm >= 11.5; Node 22 bundles npm 10.
+        run: npm install -g npm@11 && npm --version
 
       - name: Sync package-lock.json if version drifted
         # When the maintainer bumps the version on package.json only — for
@@ -168,8 +180,11 @@ jobs:
           fi
 
       - name: Publish to npm
-        env:
+        # Auth is OIDC trusted publishing (id-token: write above) — npm mints
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        # a short-lived credential from the workflow's identity; there is no
+        # NPM_TOKEN. Provenance is generated automatically on this path; the
+        # explicit --provenance keeps the intent visible and fails loudly if
+        # OIDC is ever unavailable.
         run: |
           V="${{ steps.ver.outputs.version }}"
           bash scripts/pack-npm.sh "$V"

README.md

@@ -17,6 +17,8 @@ Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates.
 [![npm version](https://img.shields.io/npm/v/@colbymchenry/codegraph.svg)](https://www.npmjs.com/package/@colbymchenry/codegraph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Self-contained](https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen.svg)](https://nodejs.org/)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-brightgreen.svg)](#verified-releases)
+[![Attested builds](https://img.shields.io/badge/releases-signed%20%26%20attested-brightgreen.svg)](#verified-releases)
 
 [![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#supported-platforms)
 [![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#supported-platforms)
@@ -56,6 +58,7 @@ Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates.
 - [Library Usage](#library-usage)
 - [Configuration](#configuration)
 - [Telemetry](#telemetry)
+- [Verified releases](#verified-releases)
 - [Supported Platforms](#supported-platforms)
 - [Supported Agents](#supported-agents)
 - [Supported Languages](#supported-languages)
@@ -743,6 +746,33 @@ codegraph telemetry off    # or: CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1
 [`TELEMETRY.md`](TELEMETRY.md) lists every field, with the off-switches and the
 full data-handling story.
 
+## Verified releases
+
+Every artifact is built and published by the public
+[Release workflow](.github/workflows/release.yml) — never from a laptop — and
+carries cryptographic proof of it:
+
+- **npm packages** are published via [trusted publishing](https://docs.npmjs.com/trusted-publishers)
+  (OIDC — no long-lived npm tokens exist that could be stolen) with
+  [provenance attestations](https://docs.npmjs.com/generating-provenance-statements)
+  linking every version to the exact commit and workflow run that built it.
+  Verify what's installed:
+
+  ```bash
+  npm audit signatures
+  ```
+
+- **GitHub Release bundles** (and `SHA256SUMS`) carry signed
+  [build attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
+  (SLSA v1.0 Build Level 2). Verify any downloaded bundle:
+
+  ```bash
+  gh attestation verify codegraph-darwin-arm64.tar.gz -R colbymchenry/codegraph
+  ```
+
+Releases published before July 2026 predate this pipeline and don't carry
+attestations.
+
 ## Supported Platforms
 
 Every release ships a self-contained build (bundled Node runtime — nothing to