# Story 3.4c: Supply-Chain Security & Release Compliance

## Status: Planned

## Priority: High

## Estimated Effort: Medium (2-3 days)

## Dependencies: None

## Epic / Series

Part of Epic 3: Plugin Ecosystem Foundation / Series 3.x

---

## Context / Background

Release engineers need supply-chain security in CI so that enterprise plugins meet governance requirements. This includes signed wheels, SBOM generation, and vulnerability scanning.

---

## User Story

**As a** release engineer  
**I want** supply-chain security in CI  
**So that** enterprise plugins meet governance requirements

---

## Scope (In / Out)

### In Scope

- Signed wheels (Sigstore or equivalent)
- SBOM generation
- Vulnerability scanning in release CI
- Publishing flow documentation

### Out of Scope

- Fixing vulnerabilities (separate work)
- Real-time scanning (CI-based is sufficient)
- Custom signing infrastructure

---

## Acceptance Criteria

### AC1: Signed Wheels

- [ ] CI jobs for signing wheels
- [ ] Sigstore or equivalent signing
- [ ] Signatures verified in release workflow
- [ ] Documentation for signing process

### AC2: SBOM Generation

- [ ] SBOM generation in release CI
- [ ] CycloneDX format
- [ ] SBOM published with release

### AC3: Vulnerability Scanning

- [ ] Vulnerability scanning in release CI
- [ ] Scan results stored
- [ ] Configurable severity thresholds

### AC4: Publishing Flow

- [ ] Document release and verification steps
- [ ] Document artifact locations
- [ ] Document verification process
- [ ] Clear workflow documentation

---

## Technical Design / Implementation Notes

### CI Workflow

Location: `.github/workflows/release.yml`

Add steps for:
1. Build wheels
2. Sign wheels (Sigstore)
3. Generate SBOM
4. Run vulnerability scan
5. Publish artifacts

### Artifact Storage

- Signed wheels: PyPI + GitHub releases
- SBOM: GitHub releases
- Scan results: GitHub releases

---

## Tasks

### Phase 1: CI Jobs
- [ ] Add signing job to release workflow
- [ ] Add SBOM generation job
- [ ] Add vulnerability scanning job
- [ ] Configure artifact storage

### Phase 2: Documentation
- [ ] Document release workflow
- [ ] Document verification steps
- [ ] Document artifact locations

---

## Tests

### Manual Verification

- [ ] Release workflow runs successfully
- [ ] Wheels are signed correctly
- [ ] SBOM is generated correctly
- [ ] Vulnerability scan runs
- [ ] Artifacts are published

---

## Documentation Updates

- [ ] Release workflow documentation
- [ ] Verification process documentation
- [ ] Artifact location documentation

---

## Definition of Done

Story is complete when ALL of the following are true:

### Code Complete
- [ ] All acceptance criteria met and verified
- [ ] All tasks completed
- [ ] Code follows project style guide
- [ ] No linting errors or warnings
- [ ] Type checking passes (mypy strict)

### Quality Assurance
- [ ] Unit tests: >90% coverage of new code
- [ ] Integration tests: all scenarios passing
- [ ] Regression tests: no existing functionality broken
- [ ] Performance tests: no regression vs baseline
- [ ] Manual testing completed (if applicable)

### Documentation
- [ ] User-facing docs updated
- [ ] API reference updated (if applicable)
- [ ] Code examples added/updated
- [ ] CHANGELOG.md updated
- [ ] Inline code documentation complete

### Review & Release
- [ ] Code review approved
- [ ] Documentation reviewed for clarity
- [ ] CI/CD pipeline passing
- [ ] Ready for merge to main branch

### Backwards Compatibility
- [ ] No breaking changes OR breaking changes documented with migration guide
- [ ] Existing tests still pass
- [ ] Deprecation warnings added (if applicable)

---

## Risks / Rollback / Monitoring

### Risks

- **Risk:** Signing infrastructure failures
  - **Mitigation:** Test signing process thoroughly, have backup procedures

- **Risk:** SBOM generation breaks on dependency changes
  - **Mitigation:** Test with various dependency configurations, handle edge cases

- **Risk:** Vulnerability scanning slows down releases
  - **Mitigation:** Optimize scan process, allow configurable thresholds

### Rollback Plan

- Disable signing/SBOM steps if needed
- Keep artifacts in GitHub Actions only
- No code changes, so easy to rollback

### Success Metrics / Monitoring

- Successful releases with signed wheels
- SBOM generation success rate
- Vulnerability scan completion time

---

## Related Documents

- [Story 4.13: CI Security Scanning & SBOM Publishing](./4.13.ci-security-scanning-sbom.md)

---

## Change Log

| Date       | Change                    | Author |
| ---------- | ------------------------- | ------ |
| 2025-01-10 | Initial story creation    | System |
