# OpenSpec Change: enterprise-slsa

- **Change ID**: enterprise-slsa
- **Package**: `@suaveplan/slsa`
- **Category**: universal / auth
- **Target path**: `universal/auth/slsa`
- **Status**: SHIPPED
- **Date**: 2026-04-19

## Why

The genesis `@suaveplan/slsa` package previously shipped a thin, flat
`src/lib/*.ts` layout that produced in-toto/SLSA provenance, verified it
against a policy, emitted CycloneDX 1.5 SBOMs, and assessed the build
environment. That surface is foundational but well short of the
CLAUDE.md target for the package, which calls out DSSE attestation
envelopes, a Sigstore Rekor transparency-log client (upload + inclusion
proof verification), a composite policy evaluator, structured errors via
`@suaveplan/error`, Zod schemas on every wire-format type, OTel audit
events, and the standard four-file feature-module layout.

## What Changes

### ADDED

- Four-file co-located feature-module layout under
  `universal/auth/slsa/src/<category>/<feature>/`.
- Structured errors: `SlsaError` base + stable `SLSA.*` code registry
  via `defineCodes`, plus per-domain subclasses
  (`InvalidProvenanceError`, `InvalidSbomError`,
  `VerificationFailedError`, `PolicyViolationError`, `RekorUploadError`,
  `RekorInclusionError`, `AttestationInvalidError`,
  `EnvironmentUnsupportedError`).
- Zod schemas for every wire-format type: `ProvenanceStatementSchema`,
  `SlsaProvenancePredicateSchema`, `BuildDefinitionSchema`,
  `RunDetailsSchema`, `BuilderSchema`, `BuildMetadataSchema`,
  `ResourceDescriptorSchema`, `DigestSetSchema`,
  `VerificationPolicySchema`, `VerificationResultSchema`, `SbomSchema`,
  `SbomComponentSchema`, `SbomInputSchema`, `SlsaAssessmentSchema`,
  `AssessmentEnvironmentSchema`, `RekorEntrySchema`,
  `InclusionProofSchema`, `DsseEnvelopeSchema`, `AttestationSchema` with
  `parseProvenance` / `parseSbom` helpers.
- DSSE PAE + envelope: `encodeDssePae`, `wrapInDsse`,
  `verifyDsseEnvelope` (ed25519, keyid-scoped trust).
- Sigstore Rekor client: `RekorClient` with injectable `fetch`,
  `uploadHashedrekord` / `uploadIntoto` (v0.0.2),
  `getEntryByUuid` / `getEntryByLogIndex`, `verifyInclusionProof`
  (RFC 6962 with `0x00`/`0x01` domain separators, odd-size carry-up).
- Composite policy evaluator `evaluatePolicy` layering
  `verifyProvenance` + DSSE signatures + Rekor inclusion + min SLSA
  level.
- OTel audit adapter: `createSlsaOtelAdapter` emitting
  `slsa.provenance.generated`, `slsa.provenance.verified`,
  `slsa.rekor.upload`, `slsa.rekor.inclusion_verified`,
  `slsa.policy.violation`.
- Canonical JSON helper (`canonicalize`) for deterministic hashing /
  signing.
- `computeDigest` routed through `@suaveplan/crypto-hash` — no direct
  `node:crypto` imports.
- Rekor-inclusion signal on the L3 assessment gate.
- Per-feature subpath `exports` in `package.json`.
- Root `README.md` linking every co-located module `.md`.

### REMOVED

- `src/lib/*.ts` flat layout and its `node:crypto` digest path.
- Plain `new Error(...)` throws in favour of structured
  `SlsaError` subclasses.

## Impact

- `@suaveplan/slsa` gains workspace deps `@suaveplan/error`,
  `@suaveplan/types`, `@suaveplan/crypto`, `@suaveplan/crypto-hash`,
  `@suaveplan/crypto-utils`, `@suaveplan/serialize`, plus
  `@opentelemetry/api` and `zod` from catalogs.
- Downstream consumers (publish pipeline, release gates) can now call
  `evaluatePolicy` for a single pass/fail decision and will receive
  typed errors with `instanceof` narrowing.
- No other packages depend on `@suaveplan/slsa` today, so there is no
  cross-package migration burden.

## Verification

- `bunx turbo lint typecheck test --filter=@suaveplan/slsa` — all green.
- Istanbul coverage: 99.2% statements, 100% functions, 99.44% lines,
  95.15% branches. Meets the 95% floor on every axis.
- 13 test files, 170 test cases.