feat: switch npm publishing to OIDC trusted publishing (#107)

- Move publish job to ubuntu-latest (OIDC requires GitHub-hosted runners)
- Add --provenance flag for production releases (conditional on event type)
- Pin npm to v11 (trusted publishing requires 11.5.1+)
- Add NPM_TOKEN fallback for manual workflow_dispatch
- Add post-publish verification step for all 4 packages
- Update release docs with trusted publisher setup and manual publishing procedure
- Remove NPM_TOKEN secret from CreateRelease.yml workflow_call

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

.github/workflows/CreateRelease.yml

@@ -106,5 +106,3 @@ jobs:
     with:
       version: ${{ needs.publish-hyperlight-js-packages-and-create-release.outputs.version }}
       dry-run: false
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/npm-publish.yml

@@ -14,6 +14,11 @@ on:
         required: false
         type: boolean
         default: false
+  # IMPORTANT: Trusted publishing (OIDC) is configured on npmjs.com with
+  # workflow filename 'CreateRelease.yml'. npm checks the *calling* workflow
+  # for workflow_call, not the reusable workflow that runs npm publish.
+  # Calling this workflow from a different parent workflow will fail OIDC auth.
+  # See: https://docs.npmjs.com/trusted-publishers#troubleshooting
   workflow_call:
     inputs:
       version:
@@ -25,9 +30,6 @@ on:
         required: false
         type: boolean
         default: false
-    secrets:
-      NPM_TOKEN:
-        required: true
 
 permissions:
   contents: read
@@ -114,7 +116,10 @@ jobs:
 
   publish:
     needs: build
-    runs-on: [self-hosted, Linux, X64, "1ES.Pool=hld-kvm-amd"]
+    # Trusted publishing (OIDC) requires GitHub-hosted runners.
+    # The publish job only downloads pre-built artifacts and runs npm publish,
+    # so it does not need self-hosted runners with KVM/Hyperlight.
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
 
@@ -126,6 +131,10 @@ jobs:
           cache: 'npm'
           cache-dependency-path: 'src/js-host-api/package-lock.json'
 
+      # Trusted publishing requires npm 11.5.1+ (Node 22 ships with npm 10.x)
+      - name: Upgrade npm for trusted publishing
+        run: npm install -g npm@11 && npm --version
+
       - name: Validate version format
         run: npx --yes semver "$VERSION"
         env:
@@ -218,33 +227,91 @@ jobs:
         working-directory: ${{ env.WORKING_DIR }}
         run: ./test-pack.sh
 
+      # ── Authentication strategy ────────────────────────────────────
+      # Production releases via CreateRelease.yml use trusted publishing
+      # (OIDC) — npm auto-detects the id-token and exchanges it for a
+      # short-lived publish credential. Provenance attestations are
+      # generated automatically. The --provenance flag is added explicitly
+      # so the build fails loudly if OIDC is misconfigured.
+      #
+      # Manual workflow_dispatch requires an NPM_TOKEN repo secret because
+      # trusted publishing is configured for CreateRelease.yml only.
+      # Provenance is NOT available for token-based publishing.
+      # You should almost never need to publish manually — if you do,
+      # see docs/release.md for the full (deliberately painful) steps.
+      - name: Validate NPM_TOKEN for manual dispatch
+        if: ${{ github.event_name == 'workflow_dispatch' && !inputs['dry-run'] }}
+        run: |
+          if [ -z "$NPM_TOKEN" ]; then
+            echo "::error::NPM_TOKEN repo secret is required for manual workflow_dispatch publishing."
+            echo "::error::See docs/release.md 'Manual npm publishing (emergency only)' for instructions."
+            exit 1
+          fi
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Set provenance flag once — OIDC path gets --provenance (fails loud
+      # if misconfigured), token path skips it (not supported).
+      - name: Set publish flags
+        id: publish-flags
+        run: |
+          if [ "${{ github.event_name }}" != "workflow_dispatch" ]; then
+            echo "provenance=--provenance" >> "$GITHUB_OUTPUT"
+          else
+            echo "provenance=" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Publish Linux GNU package
         if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-gnu
-        run: npm publish --access public --ignore-scripts
+        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
 
       - name: Publish Linux musl package
         if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-musl
-        run: npm publish --access public --ignore-scripts
+        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
 
       - name: Publish Windows package
         if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}/npm/win32-x64-msvc
-        run: npm publish --access public --ignore-scripts
+        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
 
       - name: Publish main package
         if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}
-        run: npm publish --access public --ignore-scripts
+        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
+        env:
+          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
+
+      - name: Verify all packages published
+        if: ${{ !inputs['dry-run'] }}
+        run: |
+          echo "Waiting for registry propagation..."
+          sleep 15
+          FAILED=0
+          for pkg in "@hyperlight-dev/js-host-api" \
+                     "@hyperlight-dev/js-host-api-linux-x64-gnu" \
+                     "@hyperlight-dev/js-host-api-linux-x64-musl" \
+                     "@hyperlight-dev/js-host-api-win32-x64-msvc"; do
+            if npm view "$pkg@$VERSION" version > /dev/null 2>&1; then
+              echo "✅ $pkg@$VERSION published"
+            else
+              echo "::error::❌ $pkg@$VERSION NOT found on registry!"
+              FAILED=1
+            fi
+          done
+          if [ "$FAILED" -eq 1 ]; then
+            echo "::error::Some packages failed to publish. Check above for details."
+            exit 1
+          fi
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          VERSION: ${{ inputs.version }}
 
       - name: Dry run - show what would be published
         if: ${{ inputs['dry-run'] }}

docs/release.md

@@ -53,8 +53,67 @@ This release contains the benchmark results and the source code for the release
 
 In addition the hyperlight-js crates will be published to crates.io. You can verify this by going to the [hyperlight-js page on crates.io](https://crates.io/crates/hyperlight-js) and checking that the new version is listed.
 
+The npm packages (`@hyperlight-dev/js-host-api` and platform-specific binaries) are also published automatically as part of this workflow. Publishing uses [npm trusted publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) — no `NPM_TOKEN` secret is needed for the `CreateRelease` workflow. Provenance attestations are generated automatically.
+
+You can verify the npm publish by checking the [npmjs.com package page](https://www.npmjs.com/package/@hyperlight-dev/js-host-api).
+
+### npm trusted publishing setup
+
+Trusted publishing is configured on [npmjs.com](https://www.npmjs.com/) for each package. If you add a new platform package, you must configure its trusted publisher:
+
+1. Go to the package on npmjs.com → Settings → Trusted Publisher
+2. Select **GitHub Actions**
+3. Set **Organization**: `hyperlight-dev`, **Repository**: `hyperlight-js`, **Workflow**: `CreateRelease.yml`
+4. Save
+
+This must be done for all 4 packages:
+- `@hyperlight-dev/js-host-api`
+- `@hyperlight-dev/js-host-api-linux-x64-gnu`
+- `@hyperlight-dev/js-host-api-linux-x64-musl`
+- `@hyperlight-dev/js-host-api-win32-x64-msvc`
+
+> **Note:** Trusted publishing only works via `CreateRelease.yml` (the production release path). Manual publishing is deliberately discouraged — see [Manual npm publishing (emergency only)](#manual-npm-publishing-emergency-only) below.
+
 ## Patching a release
 
 If you need to update a previously released version of hyperlight-js then you should open a Pull Request against the release branch you want to patch, for example if you wish to patch the release `v0.18.0` then you should open a PR against the `release/v0.18.0` branch.
 
 Once the PR is merged, then you should follow the instructions above. In this instance the version number of the tag should be a patch version, for example if you are patching the `release/v0.18.0` branch and this is the first patch release to that branch then the tag should be `v0.18.1`. If you are patching a patch release then the tag should be `v0.18.2` and the target branch should be `release/v0.18.1` and so on.
+
+## Manual npm publishing (emergency only)
+
+> ⚠️ **Do not use this for regular releases.** Use the `CreateRelease` workflow instead. Manual publishing bypasses OIDC trusted publishing and will **not** generate provenance attestations — meaning publish will show up without the "Published via trusted publishing" badge on npmjs.com. Only use this if the automated release pipeline is broken and you need to ship an urgent fix.
+
+If you need to publish npm packages manually via `workflow_dispatch`, you'll need to:
+
+1. **Temporarily allow token-based publishing on npmjs.com**
+   - Go to each package on [npmjs.com](https://www.npmjs.com/) → Settings → Publishing access
+   - Change from "Require two-factor authentication and disallow tokens" to "Require two-factor authentication or automation tokens"
+   - Do this for all 4 packages:
+     - `@hyperlight-dev/js-host-api`
+     - `@hyperlight-dev/js-host-api-linux-x64-gnu`
+     - `@hyperlight-dev/js-host-api-linux-x64-musl`
+     - `@hyperlight-dev/js-host-api-win32-x64-msvc`
+
+2. **Create an npm automation token**
+   - Go to [npmjs.com](https://www.npmjs.com/) → Access Tokens → Generate New Token → Granular Access Token
+   - Set scope to the `@hyperlight-dev` org, packages: read and write, expiry: shortest available
+   - Copy the token
+
+3. **Add the token as a repo secret**
+   - Go to the repo on GitHub → Settings → Secrets and variables → Actions → New repository secret
+   - Name: `NPM_TOKEN`
+   - Value: paste the token from the previous step
+   - Save
+
+4. **Run the workflow**
+   - Go to Actions → "Publish npm packages" → Run workflow
+   - Select the correct branch
+   - Enter the version (e.g. `0.2.1`)
+   - Set `dry-run` to `false`
+
+5. **Clean up immediately after publishing**
+   - Delete the `NPM_TOKEN` repo secret on GitHub → Settings → Secrets and variables → Actions
+   - Revoke the npm token on npmjs.com → Access Tokens
+   - Re-enable "Require two-factor authentication and disallow tokens" on all 4 packages
+   - Verify the packages published correctly: `npm view @hyperlight-dev/js-host-api versions`

src/js-host-api/.npmignore

@@ -24,6 +24,7 @@ examples/
 *.config.mjs
 .prettierrc
 TYPE_NAMING.md
+DEVELOPMENT.md
 build.rs
 src/
 Cargo.toml

src/js-host-api/DEVELOPMENT.md

@@ -0,0 +1,76 @@
+# Hyperlight JS Host API — Development Guide
+
+Development, build, and publishing instructions for contributors.
+
+## Requirements
+
+- **Node.js** >= 18
+- **Rust** toolchain (see `rust-toolchain.toml` in repository root)
+- **just** (build automation) — install via `cargo install just` or your package manager
+
+## Building from Source
+
+### Build Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Release builds (optimized)
+npm run build
+
+# Debug builds (with symbols)
+npm run build:debug
+
+# Run tests
+npm test
+```
+
+### Using Just (Build Automation)
+
+From the repository root:
+
+```bash
+# Build js-host-api
+just build-js-host-api release
+
+# Build with debug symbols
+just build-js-host-api debug
+
+# Run js-host-api examples
+just run-js-host-api-examples release
+
+# Run js-host-api tests
+just test-js-host-api release
+
+# Build and test everything (all runtimes and targets)
+just build-all
+just test-all release
+```
+
+## Publishing to npm
+
+The package is published to npmjs.com as `@hyperlight-dev/js-host-api` with platform-specific binary packages using [npm trusted publishing (OIDC)](https://docs.npmjs.com/trusted-publishers).
+
+> **Note:** You cannot `npm publish` from your local machine. Publishing is handled by CI via the `CreateRelease` workflow, which uses OIDC for authentication. Trusted publishing must be configured on npmjs.com — see [docs/release.md](../../docs/release.md) for full setup and release instructions.
+
+**For release instructions, see [docs/release.md](../../docs/release.md).**
+
+### Package Structure
+
+The npm release consists of the following packages:
+
+| Package | Description |
+|---------|-------------|
+| `@hyperlight-dev/js-host-api` | Main package (installs correct binary automatically) |
+| `@hyperlight-dev/js-host-api-linux-x64-gnu` | Linux x86_64 (glibc) native binary |
+| `@hyperlight-dev/js-host-api-linux-x64-musl` | Linux x86_64 (musl/Alpine) native binary |
+| `@hyperlight-dev/js-host-api-win32-x64-msvc` | Windows x86_64 native binary |
+
+### How Platform Selection Works
+
+This project uses the [napi-rs](https://napi.rs/docs/deep-dive/release#3-the-native-addon-for-different-platforms-is-distributed-through-different-npm-packages) approach for distributing native addons across platforms. Each platform-specific binary is published as a separate npm package and listed as an `optionalDependency` of the main package.
+
+**At install time:** npm uses the `os`, `cpu`, and `libc` fields in each platform sub-package's `package.json` to determine which optional dependency to install. Packages that don't match the user's platform are silently skipped. The main package itself does **not** have `os`/`cpu` fields because it contains only JavaScript — restricting it would prevent installation on unsupported platforms even for type-checking or development purposes.
+
+**At runtime:** The napi-rs generated `index.js` detects the platform (including glibc vs musl on Linux) and loads the correct `.node` binary.