release.yaml

name: Release

on:
  push:
    tags:
      - '**/v*' # e.g. packages/sdk/v1.2.3 — single-package release
      - 'release/v*' # e.g. release/v2026-05-17 — cascade release (multi-package)
      - 'v*' # legacy monorepo-wide cascade tag
      - '!infra/v*' # infra/v* tags drive infra-release.yaml (Docker images), not npm publish
  workflow_dispatch:
    inputs:
      mode:
        description: 'Release mode'
        type: choice
        options: [cascade, single]
        default: cascade
      filter:
        description: 'pnpm filter (single mode only, e.g. ./packages/sdk)'
        required: false
        default: ''

permissions: {}

concurrency:
  group: npm-release
  cancel-in-progress: false

jobs:
  # The single human gate. It starts at t=0 alongside preparation and mutation
  # qualification, so a maintainer approves once right after dispatch and the
  # rest of the run (npm publish, infra sync, image release) proceeds unattended.
  # Approval authorizes publication only if every automated gate also passes.
  approve:
    name: Approve release
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    environment: release-approval
    permissions: {}
    steps:
      - name: Record release approval
        run: echo "Release of $GITHUB_SHA approved; publication still requires every gate."

  # Build and package without write credentials, an npm production environment,
  # or OIDC. Package lifecycle code therefore cannot mint a publisher token.
  prepare:
    runs-on: ubuntu-24.04
    timeout-minutes: 90
    permissions:
      contents: read
    outputs:
      candidate: ${{ steps.artifacts.outputs.candidate }}
      count: ${{ steps.artifacts.outputs.count }}
      filter: ${{ steps.plan.outputs.filter }}
      mode: ${{ steps.plan.outputs.mode }}

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24.18.0

      - name: Verify trusted release source
        env:
          EVENT_NAME: ${{ github.event_name }}
        run: |
          git fetch origin main
          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
            if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
              echo "::error::Manual npm releases must run from main."
              exit 1
            fi
          elif ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
            echo "::error::Release tags must point to a commit reachable from main."
            exit 1
          fi

      - name: Install dependencies
        # Release builds deny dependency lifecycle scripts. Rebuild only the
        # audited build binary needed by this workspace.
        run: pnpm install --frozen-lockfile --ignore-scripts

      - name: Rebuild the audited build tool
        run: pnpm rebuild esbuild

      - name: Reject high and critical dependency advisories
        run: pnpm audit:security

      - name: Build all packages
        run: pnpm -r --filter '!@bsv/ts-stack' run build

      - name: Typecheck workspace
        run: pnpm typecheck

      - name: Compile documentation examples against exact package tarballs
        run: pnpm docs:examples

      - name: Verify package license payloads
        run: pnpm license:pack-check

      - name: Require incorporated-material rights clearance
        run: pnpm license:release-check

      - name: Verify package artifacts and clean consumers
        run: pnpm -r --if-present --filter '!@bsv/ts-stack' run pack:check

      - name: Verify wallet browser and mobile platform consumers
        run: |
          pnpm --filter @bsv/wallet-toolbox-client run test:browser
          pnpm --filter @bsv/wallet-toolbox-mobile run test:mobile

      # Resolve release mode + filter. Three shapes:
      #
      #   1. Tag `packages/<path>/v*` → single-package publish, filter=./packages/<path>
      #   2. Tag `release/v*`         → cascade across every governed public package
      #                                 whose package.json version is ahead of npm.
      #   3. Tag `v*` or manual cascade → the same full governed-package selection.
      - name: Resolve release plan
        id: plan
        env:
          EVENT_NAME: ${{ github.event_name }}
          DISPATCH_MODE: ${{ inputs.mode }}
          DISPATCH_FILTER: ${{ inputs.filter }}
        run: |
          mode=""
          filter=""

          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
            mode="$DISPATCH_MODE"
            filter="$DISPATCH_FILTER"
            if [[ "$mode" == "single" && -z "$filter" ]]; then
              echo "::error::single mode requires a filter input"
              exit 1
            fi
            if [[ "$mode" == "cascade" && -n "$filter" ]]; then
              echo "::error::cascade mode does not accept a package filter"
              exit 1
            fi
          else
            tag="${GITHUB_REF_NAME}"
            if [[ "$tag" == release/v* || "$tag" == v* ]]; then
              mode="cascade"
            else
              package_path="${tag%/v*}"
              if [[ "$package_path" == "$tag" || ! -f "$package_path/package.json" ]]; then
                echo "::error::Could not resolve package path from tag: $tag"
                exit 1
              fi
              mode="single"
              filter="./$package_path"
            fi
          fi

          echo "mode=$mode" >> "$GITHUB_OUTPUT"
          echo "filter=$filter" >> "$GITHUB_OUTPUT"
          echo "Resolved release plan: mode=$mode filter='${filter:-<all governed packages>}'"

      # Package artifacts cross a single immutable release boundary: pack once,
      # inventory production licenses, create SBOMs, and upload immutable
      # candidate bytes for the credentialed publish job.
      - name: Stage exact npm release artifacts
        id: artifacts
        env:
          PNPM_FILTER: ${{ steps.plan.outputs.filter }}
        run: |
          args=(stage --output release-artifacts)
          if [[ -n "$PNPM_FILTER" ]]; then
            args+=(--filter "$PNPM_FILTER")
          fi
          node scripts/package-release-artifacts.mjs "${args[@]}"
          echo "candidate=npm-release-candidate-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"

      - name: Verify staged npm release artifacts
        if: steps.artifacts.outputs.count != '0'
        run: node scripts/package-release-artifacts.mjs verify release-artifacts/manifest.json

      - name: Upload immutable npm release candidate
        if: steps.artifacts.outputs.count != '0'
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: ${{ steps.artifacts.outputs.candidate }}
          path: release-artifacts
          if-no-files-found: error
          retention-days: 1

  # Runs in parallel with prepare: the campaign builds its own graph from the
  # same exact github.sha, and it also qualifies the infrastructure release.
  full-mutation:
    name: Qualify exact source before publication
    permissions:
      contents: read
    uses: ./.github/workflows/mutation-tests.yml

  # This job receives the protected npm-production environment. It runs no
  # package build or lifecycle code: it verifies, scans, attests, and publishes
  # only the immutable bytes uploaded by prepare.
  publish:
    if: needs.prepare.outputs.count != '0' && needs.approve.result == 'success' && needs.full-mutation.result == 'success' && needs.full-mutation.outputs.qualified-sha == github.sha
    needs: [approve, prepare, full-mutation]
    runs-on: ubuntu-24.04
    environment: npm-production
    timeout-minutes: 90
    permissions:
      attestations: write
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          persist-credentials: false

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24.18.0
          registry-url: https://registry.npmjs.org

      - name: Download immutable npm release candidate
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          name: ${{ needs.prepare.outputs.candidate }}
          path: release-artifacts

      - name: Verify downloaded npm release artifacts
        run: node scripts/package-release-artifacts.mjs verify release-artifacts/manifest.json

      - name: Reject high and critical package findings
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          scan-type: sbom
          scan-ref: release-artifacts/release.cdx.json
          scanners: vuln,license
          vuln-type: library
          severity: CRITICAL,HIGH
          ignore-unfixed: false
          exit-code: '1'
          format: table
          timeout: 15m

      - name: Attest npm package build provenance
        id: provenance
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: release-artifacts/packages/*.tgz

      - name: Attest npm package CycloneDX SBOM
        id: sbom-attestation
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: release-artifacts/packages/*.tgz
          sbom-path: release-artifacts/release.cdx.json

      - name: Verify npm package attestations
        env:
          GH_TOKEN: ${{ github.token }}
          SOURCE_DIGEST: ${{ github.sha }}
          SOURCE_REF: ${{ github.ref }}
        # Every tarball and predicate is verified independently; xargs fails the
        # step if any single verification fails.
        run: |
          verify() {
            gh attestation verify "$1" \
              --repo "$GITHUB_REPOSITORY" \
              --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yaml" \
              --source-digest "$SOURCE_DIGEST" \
              --source-ref "$SOURCE_REF" \
              --predicate-type "$2"
          }
          export -f verify
          for artifact in release-artifacts/packages/*.tgz; do
            printf '%s\0%s\0' "$artifact" https://slsa.dev/provenance/v1
            printf '%s\0%s\0' "$artifact" https://cyclonedx.org/bom
          done | xargs -0 -n 2 -P 8 bash -c 'verify "$1" "$2"' _

      - name: Collect offline attestation bundles
        env:
          PROVENANCE_BUNDLE: ${{ steps.provenance.outputs.bundle-path }}
          SBOM_BUNDLE: ${{ steps.sbom-attestation.outputs.bundle-path }}
        run: |
          mkdir -p release-artifacts/attestations
          cp "$PROVENANCE_BUNDLE" release-artifacts/attestations/provenance.json
          cp "$SBOM_BUNDLE" release-artifacts/attestations/cyclonedx.json

      - name: Retain npm release evidence
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: npm-release-${{ github.run_id }}-${{ github.run_attempt }}
          path: release-artifacts
          if-no-files-found: error
          retention-days: 90

      - name: Publish the attested npm tarballs
        run: node scripts/package-release-artifacts.mjs publish release-artifacts/manifest.json

  # Publication credentials never coexist with source-controlled package build
  # code. The separate sync job receives only repository/PR authority and
  # exposes its GitHub credential solely during the push and PR steps.
  sync-versions:
    if: needs.publish.result == 'success' && needs.prepare.outputs.mode == 'cascade'
    needs: [prepare, publish]
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    permissions:
      contents: write
      pull-requests: write
    outputs:
      source-sha: ${{ steps.source.outputs.source-sha }}

    steps:
      - name: Download published npm release manifest
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          name: ${{ needs.prepare.outputs.candidate }}
          path: ${{ runner.temp }}/release-artifacts

      # Poll instead of sleeping a fixed five minutes: proceed as soon as every
      # published version resolves from the public registry.
      - name: Wait for npm registry propagation
        env:
          MANIFEST: ${{ runner.temp }}/release-artifacts/manifest.json
        run: |
          deadline=$((SECONDS + 600))
          while IFS=$'\t' read -r name version; do
            until [[ "$(npm view "$name@$version" version 2>/dev/null)" == "$version" ]]; do
              if (( SECONDS > deadline )); then
                echo "::error::$name@$version did not appear on the npm registry within 10 minutes."
                exit 1
              fi
              sleep 10
            done
            echo "visible: $name@$version"
          done < <(jq -r '.packages[] | [.name, .version] | @tsv' "$MANIFEST")

      # Branch from the exact qualified release commit, not a newer main, so
      # the image source is github.sha plus only this generated sync commit.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.sha }}

      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24.18.0

      # After a cascade release, update downstream workspace ranges and all
      # standalone infra locks. A single-package release intentionally skips
      # this global operation because other versions on main may be unpublished.
      - name: Prepare published workspace version sync
        id: sync
        env:
          MANIFEST: ${{ runner.temp }}/release-artifacts/manifest.json
          SYNC_BRANCH: automation/sync-published-versions
        run: |
          git fetch origin "$SYNC_BRANCH:refs/remotes/origin/$SYNC_BRANCH" || true
          git switch --force-create "$SYNC_BRANCH" "$GITHUB_SHA"

          pnpm sync-versions
          pnpm install --lockfile-only --ignore-scripts

          # Infra components are not pnpm workspaces. Keep their npm locks
          # peer-aware so Dockerfile npm ci remains reproducible. A lock-only
          # install never moves an already-satisfied transitive entry, so first
          # update every just-published first-party package the lock contains
          # (for example middleware reached only through wallet-toolbox).
          mapfile -t published < <(jq -r '.packages[].name' "$MANIFEST")
          for directory in infra/*/ infra/uhrp-server-cloud-bucket/notifier/; do
            directory="${directory%/}"
            [ -f "$directory/package.json" ] || continue
            [ -f "$directory/package-lock.json" ] || continue
            echo "Refreshing lockfile in $directory"
            mapfile -t present < <(jq -r '.packages | keys[] | select(test("(^|/)node_modules/@bsv/")) | sub("^.*node_modules/"; "") | select(IN($ARGS.positional[]))' --args "${published[@]}" < "$directory/package-lock.json" | sort -u)
            if (( ${#present[@]} > 0 )); then
              (cd "$directory" && npm update "${present[@]}" --package-lock-only --ignore-scripts)
            fi
            (cd "$directory" && npm install --package-lock-only --ignore-scripts)

            # infra-release rebuilds only components whose version is ahead of
            # GHCR. sync-versions bumps components whose @bsv ranges changed;
            # also bump components whose lock alone moved.
            if ! git diff --quiet -- "$directory/package-lock.json" &&
              git diff --quiet -- "$directory/package.json"; then
              node -e '
                const fs = require("node:fs")
                const file = process.argv[1]
                const manifest = JSON.parse(fs.readFileSync(file, "utf8"))
                const match = /^(\d+)\.(\d+)\.(\d+)(.*)$/.exec(manifest.version ?? "")
                if (!match) throw new Error(`Unsupported version ${manifest.version}`)
                manifest.version = `${match[1]}.${match[2]}.${Number(match[3]) + 1}${match[4]}`
                fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`)
                console.log(`  [infra] ${manifest.name}: lock-only change → ${manifest.version}`)
              ' "$directory/package.json"
              (cd "$directory" && npm install --package-lock-only --ignore-scripts)
            fi
          done

          node scripts/generate-stack-facts.mjs

          if git diff --quiet; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add pnpm-lock.yaml docs/reference/stack-facts.md 'packages/**/package.json' 'infra/**/package.json' 'infra/**/package-lock.json'
          git commit -m "chore: sync published workspace versions"

          echo "changed=true" >> "$GITHUB_OUTPUT"
          echo "branch=$SYNC_BRANCH" >> "$GITHUB_OUTPUT"

      - name: Push version sync branch
        if: steps.sync.outputs.changed == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          SYNC_BRANCH: ${{ steps.sync.outputs.branch }}
        run: |
          gh auth setup-git
          git push --force-with-lease origin "HEAD:$SYNC_BRANCH"

      # The infra release builds images from this exact commit: github.sha when
      # nothing changed, otherwise its single generated sync child.
      - name: Resolve infrastructure image source
        id: source
        run: echo "source-sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

      - name: Open version sync PR
        if: steps.sync.outputs.changed == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          SYNC_BRANCH: ${{ steps.sync.outputs.branch }}
        run: |
          existing_pr="$(gh pr list --base main --head "$SYNC_BRANCH" --state open --json number --jq '.[0].number')"

          body="$(cat <<EOF
          ## Program and scope

          - Tracker or issue: protected release run ${GITHUB_RUN_ID}
          - Program gate(s) advanced: published-version reconciliation and reproducible OCI release inputs
          - Why this change is needed: synchronize first-party package floors and standalone infrastructure locks after protected npm publication.
          - Explicitly out of scope: product behavior beyond consuming the already-reviewed package artifacts.
          - Exact head SHA reviewed: generated sync commit; hosted checks bind validation to the PR head.

          ## Impact

          - [x] No public package source or manifest changed
          - [x] Infrastructure source, dependency, image, or deployment configuration changed
          - [x] Security-sensitive boundary changed

          Affected services and intended patch versions are the changed infra package manifests in this PR.

          ## Verification

          - Local commands and results: generated by protected release run ${GITHUB_RUN_ID} after successful npm publication.
          - Hosted CI run: pending for this exact head.
          - Conformance evidence: Not selected because no conformance input changed.
          - Coverage delta: No product source changed.
          - Lint/typecheck delta: Pending hosted affected-graph validation.
          - Browser/mobile/packed-consumer evidence: The protected release passed package, clean-consumer, browser, and mobile verification before publication.
          - Performance or bundle-size delta: No product source or bundle composition changed.
          - [x] I self-reviewed the complete diff for correctness, security, compatibility, public API, artifacts, dependencies, docs, and operations
          - [ ] All applicable checks are terminal and successful on the exact head; any scope-based skip is expected and validated by the merge gate

          ## Security and dependencies

          - [x] Changelog, runtime relevance, peer compatibility, transitive graph, and audit results were reviewed by the protected release
          - [x] No new override, advisory dismissal, quality suppression, or skipped test
          - [x] Workflow permissions and lifecycle-script behavior remain least privilege

          ## Dependency evidence

          - Release notes and necessity: The protected release already validated the coordinated package release notes and migration guidance.
          - Runtime, build, and peer compatibility: The release verified the governed Node, browser, mobile, runtime, and peer-dependency contracts.
          - Deduplicated lockfile: Workspace and standalone npm locks were regenerated once from the published first-party versions without lifecycle scripts.
          - Audit and CodeQL: The release rejected high and critical package findings; exact-head CodeQL runs on this PR.
          - Package and consumer tests: The release passed full builds, typecheck, package artifacts, clean consumers, browser, mobile, registry signatures, provenance, and reconciliation.
          - Bundle and performance impact: No bundle composition changed; affected releases retain their documented compatibility contracts.
          - Affected public package versions: Derived from the published workspace manifests synchronized by this exact commit.

          ## Release and operations

          - [x] No npm publication was performed from a workstation or from this PR
          - [x] Required npm patch bumps are included or intentionally deferred by the controlling program
          - [x] Image/SBOM/provenance/deployment/rollback impact is documented by the protected infrastructure release
          - [x] Documentation, changelog, migration, and operational guidance are current

          The protected infrastructure release builds Linux/amd64 images, rejects high and critical findings, publishes immutable GHCR tags, and attaches SBOM, provenance, and signature evidence after merge. Existing immutable tags remain the rollback path.

          ## Completion evidence

          - [x] Documentation, changelog, migration notes, release notes, and operator guidance are current or concretely not applicable
          - [x] One qualified maintainer approval is sufficient; no last-pusher restriction is assumed
          EOF
          )"
          if [[ -n "$existing_pr" ]]; then
            gh pr edit "$existing_pr" \
              --title "chore: sync published workspace versions" \
              --body "$body"
          else
            gh pr create \
              --base main \
              --head "$SYNC_BRANCH" \
              --title "chore: sync published workspace versions" \
              --body "$body"
          fi

  # Cascade releases continue straight into the infrastructure images: every
  # component whose version is ahead of GHCR at the sync source is built,
  # scanned, attested, signed, and pushed. An npm no-op cascade still releases
  # infra components already bumped on main. Single-package releases skip it
  # because other versions on main may be unpublished.
  infra:
    name: Release infrastructure images
    needs: [approve, prepare, full-mutation, publish, sync-versions]
    if: always() && needs.prepare.outputs.mode == 'cascade' && needs.approve.result == 'success' && needs.full-mutation.result == 'success' && needs.full-mutation.outputs.qualified-sha == github.sha && (needs.sync-versions.result == 'success' || (needs.prepare.outputs.count == '0' && needs.publish.result == 'skipped'))
    permissions:
      artifact-metadata: write
      attestations: write
      contents: read
      id-token: write
      packages: write
    uses: ./.github/workflows/infra-release.yaml
    with:
      source-sha: ${{ needs.sync-versions.outputs.source-sha || github.sha }}
      qualified-sha: ${{ needs.full-mutation.outputs.qualified-sha }}

  post-release-verification:
    if: always() && needs.publish.result != 'failure' && needs.infra.result != 'failure' && (needs.publish.result == 'success' || needs.infra.result == 'success')
    needs: [publish, infra]
    permissions:
      contents: read
      packages: read
    uses: ./.github/workflows/dependency-release-verification.yml