git.stella-ops.org/docs/modules/signer/implementation_plan.md

Implementation plan — Signer

Delivery phases

• Phase 1 – Core service & PoE
  Harden OpTok validation, Proof-of-Entitlement (PoE) checks, quota enforcement, scanner release verification, and DSSE signing pipeline (keyless + keyful).
• Phase 2 – Export Center integration
  Produce signing bundles with provenance manifests for Export Center, deliver cosign-compatible outputs, and document verification workflows for offline exports.
• Phase 3 – Attestor alignment
  Emit DSSE envelopes, metadata, and signer identity information required by Attestor (key metadata, certificate chains, bundle hashes); expose audit APIs.
• Phase 4 – Observability & resilience
  Complete telemetry, throttling dashboards, audit trails, fallback key rotation, and offline kit packaging.

Work breakdown

• Authentication & entitlement
  • Enforce Authority-issued DPoP/mTLS tokens with signer.sign scope and tenant checks.
  • Integrate PoE introspection (cloud licensing) and plan quotas.
  • Validate scanner release signature via OCI referrers before signing reports/SBOMs.
• Signing pipeline
  • Implement DSSE canonicalisation, keyless (Fulcio) and keyful (KMS/HSM/FIDO2) signing.
  • Support multi-signature output, certificate chain embedding, and deterministic bundle hashing.
  • Provide policy metadata (policy digest, view set) for report predicates.
• Integrations
  • Coordinate with Attestor on bundle schema, signer identity payload, and error codes.
  • Expose Export Center-ready signing API (/sign/export) that returns manifest + signature tuple.
  • Surface CLI flows (stella sign sbom/report, offline verification helpers).
• Security & key management
  • Key rotation and revocation runbooks; separation of signing keys per tenancy/plan.
  • Hardware-backed key support (HSM/FIDO2) with audit logging and attested builds.
• Observability
  • Metrics: signing latency, PoE failures, quota hits, key usage distribution.
  • Structured logs with trace/context IDs, subject digests, issuer mode, decision outcome.
  • Alerts for PoE outages, key exhaustion, quota breach, signing failure spikes.
• Documentation & runbooks
  • Update README/architecture/implementation plan, operator runbooks, offline verification guidance, and CLI reference.

Acceptance criteria

• Signer only signs requests that satisfy OpTok, PoE, quota, and scanner provenance checks.
• DSSE outputs (keyless + keyful) verify with standard cosign tooling; Attestor logs them without additional transformation.
• Export Center receives signed bundles, provenance manifests, and signature metadata to package exports deterministically.
• Audit logs capture every signing request with tenant, issuer, subject digest, PoE state, and key source.
• Observability dashboards/alerts reflect latency, failure rate, PoE status, and quota usage.
• CLI/Offline workflows verify signatures using Offline Kit trust roots.

Risks & mitigations

• PoE/entitlement outages: cache last-known entitlement within TTL, provide emergency bypass toggles with audit trail.
• Key compromise: enforce hardware-backed keys, rotation cadence, immediate revocation workflow, incident runbook.
• Release verification failures: maintain allowlist for trusted scanner digests, fallback to manual approval with audit.
• Determinism drift: canonicalise JSON, lock timestamp sources, regression tests for DSSE hashing.

Test strategy

• Unit: OpTok/PoE validation, quota enforcement, scanner signature verification, DSSE canonicalisation, multi-sig bundling.
• Integration: end-to-end signing for SBOM, report, export artifacts; Attestor ingestion; Export Center bundle signing.
• Security: fuzz signing inputs, simulate PoE tampering, ensure unauthorized actors are rejected.
• Performance: signing throughput benchmarks (keyless vs keyful), quota pressure, concurrency checks.
• Offline: verify signatures using Offline Kit trust roots and cosign CLI without network access.

Definition of done

• Signing pipeline deployed with observability and incident runbooks.
• Export Center + Attestor dependencies validated; CLI parity confirmed.
• Documentation updated (README, architecture, runbooks, CLI guides) with imposed rule compliance.
• ./TASKS.md and ../../TASKS.md reflect the latest status transitions.

---

Sprint readiness tracker

Last updated: 2025-11-27 (SIGNER-ENG-0001)

This section maps delivery phases to implementation sprints and tracks readiness checkpoints.

Phase 1 — Core service & PoE

Task ID	Status	Sprint	Notes
KMSI-73-001	✅ DONE (2025-11-03)	SPRINT_100_identity_signing	KMS key management foundations with staffing + DSSE contract.
KMSI-73-002	✅ DONE (2025-11-03)	SPRINT_100_identity_signing	FIDO2 profile integration.
PROV-OBS-53-001	✅ DONE (2025-11-17)	SPRINT_0513_0001_0001_provenance	DSSE/SLSA BuildDefinition + BuildMetadata models with canonical JSON serializer.
PROV-OBS-53-002	✅ DONE (2025-11-23)	SPRINT_0513_0001_0001_provenance	Signer abstraction (cosign/KMS/offline) with key rotation hooks and audit logging.
SEC-CRYPTO-90-020	🔄 IN PROGRESS	SPRINT_0514_0001_0001_sovereign_crypto	CryptoPro signer plugin; Windows CSP runner pending.

Checkpoint: Core signing infrastructure operational — KMS drivers, signer abstractions, and DSSE models delivered.

Phase 2 — Export Center integration

Task ID	Status	Sprint	Notes
PROV-OBS-53-003	✅ DONE (2025-11-23)	SPRINT_0513_0001_0001_provenance	PromotionAttestationBuilder feeding canonicalised payloads to Signer.
SIGN-REPLAY-186-003	📝 TODO	SPRINT_186_record_deterministic_execution	Extend Signer/Authority DSSE flows for replay manifest/bundle payloads.
SIGN-CORE-186-004	📝 TODO	SPRINT_186_record_deterministic_execution	Replace HMAC demo with StellaOps.Cryptography providers (keyless + KMS).
SIGN-CORE-186-005	📝 TODO	SPRINT_186_record_deterministic_execution	Refactor SignerStatementBuilder for StellaOps predicate types.
SIGN-TEST-186-006	📝 TODO	SPRINT_186_record_deterministic_execution	Upgrade signer integration tests with real crypto + fixture predicates.

Checkpoint: Export Center signing APIs partially complete; replay manifest support and crypto provider refactoring pending.

Phase 3 — Attestor alignment

Task ID	Status	Sprint	Notes
AUTH-REACH-401-005	📝 TODO	SPRINT_0401_0001_0001_reachability_evidence_chain	DSSE predicate types for SBOM/Graph/VEX/Replay; blocked on predicate definitions.
SIGN-VEX-401-018	📝 TODO	SPRINT_0401_0001_0001_reachability_evidence_chain	Extend predicate catalog with stella.ops/vexDecision@v1.
PROV-OBS-54-001	📝 TODO	SPRINT_0513_0001_0001_provenance	Verification library for DSSE signatures, Merkle roots, timeline chain.
PROV-OBS-54-002	📝 TODO	SPRINT_0513_0001_0001_provenance	.NET global tool for local verification + CLI stella forensic verify.

Checkpoint: Attestor DSSE alignment pending; predicate catalog extension and verification library not started.

Phase 4 — Observability & resilience

Task ID	Status	Sprint	Notes
DOCS-PROMO-70-001	📝 TODO	SPRINT_0304_0001_0004_docs_tasks_md_iv	Promotion attestations doc (CLI commands, Signer/Attestor integration, offline verification).
CLI-PROMO-70-002	📝 TODO	SPRINT_203_cli_iii	stella promotion attest / promotion verify commands.
CLI-FORENSICS-54-002	📝 TODO	SPRINT_202_cli_ii	stella forensic attest show <artifact> listing signer details.

Checkpoint: Observability and CLI integration pending; waiting on upstream signing pipeline completion.

---

Overall readiness summary

Phase	Status	Blocking items
1 – Core service & PoE	✅ Complete	—
2 – Export Center integration	🔄 In progress	SIGN-CORE-186-004/005 crypto provider refactoring
3 – Attestor alignment	📝 Not started	AUTH-REACH-401-005 predicate definitions
4 – Observability & resilience	📝 Not started	Upstream phase completion

Cross-module dependencies

Dependency	Required by	Status
Attestor DSSE bundle schema	SIGN-VEX-401-018	Documented in docs/modules/attestor/architecture.md §1
Provenance library canonicalisation	SIGN-CORE-186-005	Available via PROV-OBS-53-001/002
Export Center bundle manifest	SIGN-REPLAY-186-003	Pending Sprint 162/163 deliverables
Authority predicate definitions	AUTH-REACH-401-005	Schema draft pending

Next actions

1. Complete CryptoPro signer plugin Windows smoke test (SEC-CRYPTO-90-020, Sprint 0514).
2. Start SIGN-CORE-186-004 once replay bundle schema finalises (Sprint 186).
3. Track AUTH-REACH-401-005 predicate schema draft for Attestor alignment (Sprint 401).
4. Monitor PROV-OBS-54-001/002 for verification library availability.