@aashari/mcp-server-atlassian-bitbucket/docs/OIDC-TRUSTED-PUBLISHING-SETUP.md

Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MC

# npm OIDC Trusted Publishing Setup Guide

**Package:** @aashari/mcp-server-atlassian-bitbucket
**Migration Date:** 2026-02-04
**Version:** v3.0.0+

---

## Overview

This repository has migrated from legacy npm token authentication to **OIDC Trusted Publishing**, announced by npm in December 2025. This is a permanent, zero-maintenance solution for secure package publishing.

### Why OIDC?

**Problems with npm tokens:**
- ❌ Classic tokens permanently revoked December 9, 2025
- ❌ Granular tokens max 90-day expiry (constant rotation burden)
- ❌ Token leaks expose your entire npm account
- ❌ Manual token management across multiple repos

**Benefits of OIDC:**
- ✅ **Never expires** - no rotation needed
- ✅ **Zero token management** - no secrets to maintain
- ✅ **Cryptographic verification** - GitHub signs JWT tokens
- ✅ **Signed provenance** - verifiable build attestations
- ✅ **npm recommended** - official long-term solution

---

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                     GitHub Actions Workflow                      │
│                                                                   │
│  1. Job runs with id-token: write permission                     │
│  2. GitHub generates OIDC JWT token (signed)                     │
│  3. semantic-release requests npm publish                        │
│  4. npm validates JWT token with GitHub                          │
│  5. npm verifies trusted publisher configuration                 │
│  6. npm publishes package with signed provenance                 │
│                                                                   │
│  NO NPM_TOKEN NEEDED - Cryptographic proof via OIDC!             │
└─────────────────────────────────────────────────────────────────┘
```

**Key Security Features:**
- GitHub cryptographically signs tokens proving workflow identity
- npm verifies tokens directly with GitHub (no shared secrets)
- Provenance attestations link published packages to exact source commits
- Impossible to forge - requires private keys held by GitHub

---

## Migration Steps

### Step 1: Update GitHub Actions Workflow

**File:** `.github/workflows/ci-semantic-release.yml`

**Add OIDC permission:**
```yaml
jobs:
  release:
    permissions:
      id-token: write        # ← ADD THIS LINE
      contents: write
      issues: write
      pull-requests: write
```

**Remove NPM_TOKEN from env:**
```yaml
- name: Semantic Release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    # NPM_TOKEN removed - no longer needed with OIDC
  run: npx semantic-release
```

### Step 2: Verify .releaserc.json

Ensure npm publishing is enabled (should already be configured):

```json
{
  "plugins": [
    ["@semantic-release/npm", {
      "npmPublish": true,
      "pkgRoot": "."
    }]
  ]
}
```

### Step 3: Commit and Push Changes

Use conventional commit format with BREAKING CHANGE:

```bash
git add .github/workflows/ci-semantic-release.yml
git commit -m "feat!: migrate to npm OIDC trusted publishing

BREAKING CHANGE: Publishing workflow now requires OpenID Connect (OIDC)
authentication. GitHub Actions workflow permissions updated to include
id-token: write for secure npm authentication.

Publishing now uses npm's recommended OIDC trusted publishing with:
- Zero token management and maintenance
- Never-expiring authentication
- Cryptographic verification
- Signed provenance statements

For configuration details, see docs/OIDC-TRUSTED-PUBLISHING-SETUP.md"

git push origin main
```

**Note:** The `BREAKING CHANGE:` footer triggers a major version bump (v2.3.0 → v3.0.0).

### Step 4: Configure Trusted Publisher on npmjs.com

**CRITICAL:** This step must be completed **immediately after pushing** to prevent workflow failure.

1. **Go to npm package settings:**
   - Visit: https://www.npmjs.com/package/@aashari/mcp-server-atlassian-bitbucket
   - Click "Settings" tab
   - Scroll to "Publishing access" section
   - Click "Configure trusted publisher"

2. **Select GitHub Actions:**
   - Provider: **GitHub Actions**

3. **Enter exact repository details:**
   ```
   Owner:       aashari
   Repository:  mcp-server-atlassian-bitbucket
   Workflow:    .github/workflows/ci-semantic-release.yml
   Environment: (leave empty)
   ```

4. **Save configuration**

**Important Notes:**
- Configuration must match **exactly** (case-sensitive)
- Workflow path must match file in repository
- Environment field should be **empty** (not "production" or "default")
- Save before the workflow runs, or it will fail with 404 error

### Step 5: Verify Successful Release

**Watch workflow run:**
```bash
gh run list --limit 1
gh run watch <run-id>
```

**Check published version:**
```bash
npm view @aashari/mcp-server-atlassian-bitbucket version
# Should show v3.0.0
```

**Verify provenance attestation:**
1. Visit: https://www.npmjs.com/package/@aashari/mcp-server-atlassian-bitbucket
2. Look for green "Provenance" badge on package page
3. Click badge to view signed attestation details

**Expected attestation:**
- ✅ Build environment: GitHub Actions
- ✅ Repository: github.com/aashari/mcp-server-atlassian-bitbucket
- ✅ Commit SHA: (exact commit that triggered release)
- ✅ Workflow: .github/workflows/ci-semantic-release.yml
- ✅ Signature: Verified by Sigstore

---

## Troubleshooting

### Error: "404 OIDC token exchange error - package not found"

**Cause:** Trusted publisher not configured on npmjs.com.

**Solution:**
1. Verify package exists: `npm view @aashari/mcp-server-atlassian-bitbucket`
2. Configure trusted publisher on npmjs.com (Step 4 above)
3. Re-run workflow: `gh run rerun <run-id>`

### Error: "Invalid OIDC token subject"

**Cause:** Workflow path mismatch between GitHub and npmjs.com configuration.

**Solution:**
1. Check workflow path in repo: `ls .github/workflows/ci-semantic-release.yml`
2. Edit trusted publisher on npmjs.com
3. Ensure workflow path matches **exactly**

### Error: "id-token permission not granted"

**Cause:** Missing `id-token: write` permission in workflow.

**Solution:**
```yaml
permissions:
  id-token: write  # Add this line
  contents: write
  issues: write
  pull-requests: write
```

### No Provenance Badge on npm

**Cause:** OIDC not properly configured or package published with old method.

**Solution:**
1. Verify workflow has `id-token: write` permission
2. Verify trusted publisher configured on npmjs.com
3. Publish new version to generate provenance

---

## Verification Checklist

After migration, verify:

- [ ] Workflow has `id-token: write` permission
- [ ] NPM_TOKEN removed from workflow env
- [ ] Trusted publisher configured on npmjs.com
- [ ] Workflow runs successfully without errors
- [ ] New version published (v3.0.0+)
- [ ] Provenance badge visible on npm package page
- [ ] Package installable: `npm install -g @aashari/mcp-server-atlassian-bitbucket`
- [ ] Attestation verifiable with Sigstore

---

## Comparison: Before vs After

### Before (NPM_TOKEN)

```yaml
# Workflow
permissions:
  contents: write
  issues: write
  pull-requests: write

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}  # ⚠️ Expires, requires rotation
```

**Issues:**
- Manual token creation and rotation (90 days max)
- Security risk if token leaked
- Same token across all repositories
- No provenance attestations

### After (OIDC)

```yaml
# Workflow
permissions:
  id-token: write           # ✅ Enables OIDC
  contents: write
  issues: write
  pull-requests: write

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  # No NPM_TOKEN needed! ✅
```

**Benefits:**
- Zero maintenance (never expires)
- Cryptographic verification
- Per-repository authentication
- Automatic provenance attestations

---

## Additional Resources

- **npm OIDC Announcement:** https://github.blog/security/supply-chain-security/introducing-npm-package-provenance/
- **npm Docs:** https://docs.npmjs.com/generating-provenance-statements
- **GitHub OIDC:** https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
- **Sigstore Verification:** https://www.sigstore.dev/

---

## Migration Summary

✅ **Completed:** 2026-02-04
✅ **Version:** v3.0.0
✅ **Method:** OIDC Trusted Publishing
✅ **Status:** Active and verified
✅ **Maintenance:** Zero ongoing effort required

**Next steps:** None. OIDC publishing is fully automated and maintenance-free.