From 30896e40447c1e0c36bf28db46a9b5ee7d7aaed9 Mon Sep 17 00:00:00 2001
From: moonyue-w <300878504+moonyue-w@users.noreply.github.com>
Date: Thu, 24 Sep 2026 17:56:29 +0800
Subject: [PATCH] fix(release): use npm with working provenance dependencies

---
 .github/workflows/release.yml | 15 +++++++++++----
 CONTRIBUTING.md               |  6 +++++-
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7fcc12e..395bf91 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -8,7 +8,7 @@ on:
         required: true
         type: string
       commit_sha:
-        description: 'Full 40-character lowercase SHA of the current main commit'
+        description: 'Full 40-character lowercase SHA of current main, or the existing release tag commit when resuming'
         required: true
         type: string
       batch_id:
@@ -25,6 +25,7 @@ concurrency:
 
 env:
   NODE_VERSION: '22.x'
+  NPM_VERSION: '12.0.2'
   NPM_REGISTRY: 'https://registry.npmjs.org'
   PACKAGE_NAME: 'qca-sdk'
 
@@ -69,7 +70,7 @@ jobs:
           registry-url: ${{ env.NPM_REGISTRY }}
 
       - name: Use trusted-publishing npm version
-        run: npm install --global npm@12.0.0
+        run: npm install --global "npm@$NPM_VERSION"
 
       - name: Validate release version and commit
         run: |
@@ -220,6 +221,12 @@ jobs:
           echo "tarball_name=$tarball_name" >> "$GITHUB_OUTPUT"
           echo "tarball_sha256=$tarball_sha256" >> "$GITHUB_OUTPUT"
 
+      - name: Smoke-test npm publishing without uploading
+        env:
+          TARBALL_NAME: ${{ steps.pack.outputs.tarball_name }}
+          DIST_TAG: ${{ steps.release-meta.outputs.dist_tag }}
+        run: npm publish "./$TARBALL_NAME" --dry-run --ignore-scripts --registry "$NPM_REGISTRY" --tag "$DIST_TAG" --access public --provenance
+
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: ${{ steps.pack.outputs.artifact_name }}
@@ -276,7 +283,7 @@ jobs:
           registry-url: ${{ env.NPM_REGISTRY }}
 
       - name: Use trusted-publishing npm version
-        run: npm install --global npm@12.0.0
+        run: npm install --global "npm@$NPM_VERSION"
 
       - id: state
         name: Revalidate main, tag, and registry
@@ -391,7 +398,7 @@ jobs:
           registry-url: ${{ env.NPM_REGISTRY }}
 
       - name: Use verification npm version
-        run: npm install --global npm@12.0.0
+        run: npm install --global "npm@$NPM_VERSION"
 
       - name: Wait for and verify registry artifact
         env:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8823437..7d2daa1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -97,7 +97,7 @@ or republish historical packages.
 
 ## Release
 
-Before the first release, create the GitHub `release` Environment with required reviewers and a deployment-branch rule limited to `main`. Add a tag ruleset for `refs/tags/v*` that blocks updates and deletions and allows creation only by the release automation identity. Using npm 12.0.0 or newer, replace the existing npm trust entry so it requires the same Environment:
+Before the first release, create the GitHub `release` Environment with required reviewers and a deployment-branch rule limited to `main`. Add a tag ruleset for `refs/tags/v*` that blocks updates and deletions and allows creation only by the release automation identity. Using npm 12.0.1 or newer, replace the existing npm trust entry so it requires the same Environment:
 
 ```bash
 npm trust list qca-sdk --registry https://registry.npmjs.org
@@ -123,6 +123,10 @@ Do not dispatch the workflow until all settings are active.
 
 npm versions are immutable. Never reuse or overwrite one: fix forward with a new release pull request and version, and deprecate an unusable version when necessary. A safe rerun must use the same SHA, version, and `batch_id`; it verifies the existing registry tarball without uploading it again.
 
+The release workflow pins npm `12.0.2`; npm `12.0.0` omitted a required `sigstore` dependency and cannot publish packages ([upstream fix](https://github.com/npm/cli/pull/9740)). Preflight runs `npm publish --dry-run` on the packed artifact to check the publishing command before tag creation. This checks CLI loading and package handling; trusted-publishing authorization is still checked during the actual upload.
+
+If a workflow-only fix is needed after the release tag was created, merge that fix into `main`, then start a new workflow run from `main` with the original version, tagged commit SHA, and `batch_id`. Re-running the old workflow run uses its original workflow revision and will not pick up the fix. The existing tag must remain unchanged; validation permits the original commit when that version's tag already points to it.
+
 ## Pull requests
 
 Complete the pull request template, include exact verification commands and results, and identify public API, documentation, integration-test, and cross-SDK effects. Do not combine unrelated refactors with behavior changes.