npm-provenance-easy

Easily publish npm packages with provenance (SLSA attestations) and verify them.

Why Provenance Matters

Provenance (SLSA) ensures your npm package was built and published securely from the source you expect, reducing supply chain risks. It helps users trust that your published code matches your repository and build process.

✨ Features

• 🛠 Easy GitHub Actions workflow scaffolding for provenance-enabled publishing
• 🔍 One-command verification of provenance for any npm package
• 📊 Monorepo dashboard to check provenance status across all packages
• 📦 Optional SBOM generation (CycloneDX) for enhanced security
• 🎯 Strict verification mode to check SBOM and security metadata
• 🚀 GitHub release automation with changelogs
• ⚙️ Config file support for custom workflows and badges
• 🔄 Self-update checking to keep CLI current
• 🎨 Beautiful UI with spinners, colors, and interactive menus
• 🐚 Shell completion for bash, zsh, and fish
• 🎓 First-run onboarding for new users

🚀 Quick Start

Install

npm i -D npm-provenance-easy

Or use directly with npx:

npx npm-provenance-easy --help

First Time Setup

Run the CLI for an interactive setup experience:

npx npm-provenance-easy

📖 Usage

1. Scaffold Provenance Workflow

npx npm-provenance-easy init

Features:

• Creates .github/workflows/release.yml for provenance-enabled publishing
• Optional SBOM generation - choose whether to include CycloneDX SBOM
• Monorepo detection - automatically detects pnpm/yarn workspaces
• GitHub release automation - optional automatic releases with changelogs
• Custom configuration - supports .provenancerc.json for advanced options
• Generates a badge for your README

Example Output

✅ GitHub Actions workflow created at .github/workflows/release.yml
🧩 Monorepo detected (pnpm). Scaffolding monorepo-aware workflow.
📦 SBOM generation included.
📝 GitHub release automation included.
Add this badge to your README:
![npm-provenance](https://img.shields.io/badge/provenance-enabled-brightgreen)

2. Publish with Provenance

Commit and push your code, then push a tag:

git add .
git commit -m "Release: provenance-enabled publish"
git tag v1.0.0
git push --tags

The workflow will:

• Build your project
• Generate SBOM (if enabled)
• Run npm publish --provenance --access public
• Create GitHub release (if enabled)

3. Verify a Package

Check if a published npm package has provenance:

npx npm-provenance-easy verify <package>@<version>

Strict mode (check SBOM and security metadata):

npx npm-provenance-easy verify <package>@<version> --strict

Examples:

npx npm-provenance-easy verify [email protected]
npx npm-provenance-easy verify [email protected] --strict

4. Monorepo Dashboard

Check provenance status for all packages in your monorepo:

npx npm-provenance-easy dashboard

Shows:

• ✅ Provenance status for each package
• 📦 SBOM attachment status
• 📈 Summary statistics
• 💡 Recommendations for missing features

5. Check for Updates

Keep your CLI up to date:

npx npm-provenance-easy update

6. Shell Completion

Setup autocomplete for your shell:

# Show setup instructions
npx npm-provenance-easy completion

# Generate completion script
npx npm-provenance-easy completion bash
npx npm-provenance-easy completion zsh
npx npm-provenance-easy completion fish

⚙️ Configuration

Create .provenancerc.json for custom settings:

{
  "workflow": {
    "nodeVersion": "20",
    "includeReleases": true,
    "customSteps": [
      "- name: Custom step",
      "  run: echo 'Custom action'"
    ]
  },
  "badge": {
    "style": "flat-square",
    "color": "brightgreen",
    "label": "provenance",
    "message": "enabled"
  },
  "sbom": {
    "enabled": true,
    "format": "xml",
    "includeDevDeps": false
  },
  "monorepo": {
    "packages": ["@myorg/core", "@myorg/ui"],
    "publishStrategy": "all"
  }
}

📋 Example Workflow Files

name: Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Generate SBOM (CycloneDX)
        run: npx @cyclonedx/cyclonedx-npm --output-format xml --output-file sbom.xml
      - name: Publish with provenance and attach SBOM
        run: npm publish --provenance --access public --sbom=sbom.xml || npm publish --provenance --access public
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref_name }}
          body: |
            ## What's Changed
            
            This release includes provenance-enabled packages with SBOM attachments.
            
            ### Security Features
            - ✅ SLSA Level 3+ provenance
            - 📦 CycloneDX SBOM attached
            - 🔒 Supply chain security verified
          draft: false
          prerelease: false

name: Monorepo Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ["@myorg/core", "@myorg/ui"]
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - name: Build all packages
        run: npm run build --workspaces
      - name: Generate SBOM (CycloneDX)
        run: npx @cyclonedx/cyclonedx-npm --output-format xml --output-file sbom.xml
      - name: Publish with provenance and attach SBOM
        run: npm publish --provenance --access public --workspaces --sbom=sbom.xml || npm publish --provenance --access public --workspaces
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref_name }}
          body: |
            ## What's Changed
            
            This release includes provenance-enabled packages with SBOM attachments.
            
            ### Security Features
            - ✅ SLSA Level 3+ provenance
            - 📦 CycloneDX SBOM attached
            - 🔒 Supply chain security verified
          draft: false
          prerelease: false

🎨 Add the Badge

Add this to your README to show provenance support:

![npm-provenance](https://img.shields.io/badge/provenance-enabled-brightgreen)

🎯 Interactive Menu

Run without arguments for a beautiful interactive experience:

npx npm-provenance-easy

Features:

• 🎨 Colorful ASCII banner
• 📋 Interactive menu with all commands
• 🎯 Guided setup process
• 💡 Helpful suggestions and tips

🔧 Troubleshooting

• npm login required: Make sure you are logged in to npm before publishing.
• Workflow not running?: Ensure you push a tag (e.g., v1.0.0).
• Provenance not detected?: Check that your workflow uses npm publish --provenance.
• SBOM not attaching?: Ensure you have @cyclonedx/cyclonedx-npm installed.
• Monorepo issues?: Verify your workspace configuration (pnpm-workspace.yaml or package.json workspaces).

🚀 Advanced Features

Strict Verification

npx npm-provenance-easy verify [email protected] --strict

Checks for:

• ✅ Provenance attestation
• 📦 SBOM attachment
• 🔒 Security audit metadata

Monorepo Dashboard

npx npm-provenance-easy dashboard

Provides:

• 📊 Status overview for all packages
• 🎯 Actionable recommendations
• 📈 Progress tracking

Custom Configuration

Use .provenancerc.json to customize:

• Workflow templates
• Badge styles
• SBOM settings
• Monorepo strategies

🤝 Contributing

PRs and issues welcome! See LICENSE.

📄 License

MIT