# Evidence Locker

Status: Draft (2025-11-26) — DOCS-FORENSICS-53-001.

## Purpose
Capture forensic artefacts (bundles, logs, attestations) in a WORM-friendly store with retention/legal-hold controls.

## Storage model
- Object storage (preferred) with:
  - Bucket per tenant (or tenant prefix) and immutable retention policy.
  - Server-side encryption (KMS) and optional client-side DSSE envelopes.
  - Versioning enabled; deletion disabled during legal hold.
- Index (Mongo/Postgres) for metadata:
  - `artifactId`, `tenant`, `type` (bundle/attestation/log), `sha256`, `size`, `createdAt`, `retentionUntil`, `legalHold`.
  - `provenance`: source service, job/run ID, DSSE envelope hash, signer.
  - `immutability`: `worm=true|false`, `legalHold=true|false`, `expiresAt`.

## Ingest rules
- Only append; no overwrite. Use content-addressed paths: `tenant/<type>/<sha256>/<filename>`.
- Every artefact must include:
  - SHA256 (and size)
  - DSSE or Sigstore bundle for attestations
  - Source metadata (service, run ID)
  - Retention/hold directives
- Reject uploads lacking tenant, hash, or provenance.

## Retention & legal hold
- Default retention per tenant (e.g., 180d); configurable via policy.
- Legal hold flag prevents deletion/expiry; requires dual-approval to clear.
- Expiry job runs daily; deletes only items past `retentionUntil` and not on hold; produce audit log.

## Access & audit
- RBAC scopes: `locker:read`, `locker:write`, `locker:hold`.
- All actions logged with tenant, actor, artefact ID, hash, and result.
- Provide `/locker/manifest` endpoint to list artefacts by tenant/time/type with pagination.

## Verification
- `locker verify <artifactId>`:
  - Recompute SHA256
  - Verify DSSE/Sigstore signature and signer against trust roots
  - Return status + provenance summary
- Periodic background verification: sample N artefacts/day; emit `locker.verify.failed` events on mismatch.

## Bundle format (minimum)
- Manifest (`manifest.json`):
  - `artifactId`, `tenant`, `type`, `hashes`, `createdAt`, `retentionUntil`, `legalHold`
  - `provenance` (source, signer, dsseEnvelopeHash)
  - `paths` with bytes and hashes
- Data files under `data/` (gzip/zstd optional)
- Signature under `signatures/` if provided

## Migration from legacy storage
- Export legacy artefacts with hashes; import via Locker API with retention/hold fields.
- Maintain mapping of legacy IDs → new `artifactId` in index.
- Keep legacy store read-only until verification completes.

## Operational runbook (abridged)
- On ingest failure: log and return 400 with reason; do not partially store.
- On verification failure: mark artefact `suspect=true`, emit event, and investigate signer and storage integrity.
- For legal hold requests: require ticket/approval metadata; set `legalHold=true` and extend retention.

## References
- DSSE: in-toto DSSE spec.
- Sigstore bundles: `docs/forensics/provenance-attestation.md` (pending).
- Export Center mirror imports and policy attestations feed artefacts here.