move docs/**/archived/* to docs-archived/**/*

2026-01-05 16:02:11 +02:00
parent dfab8a29c3
commit d0a7b88398
1083 changed files with 4 additions and 1 deletions
--- a/docs-archived/implplan/sprints/20251226/SPRINT_20251226_001_BE_cicd_gate_integration.md
+++ b/docs-archived/implplan/sprints/20251226/SPRINT_20251226_001_BE_cicd_gate_integration.md
@@ -0,0 +1,62 @@
+# Sprint 20251226 · CI/CD Release Gate Integration
+
+**Status:** DONE
+
+## Topic & Scope
+- Wire existing `DriftGateEvaluator` into CI/CD pipelines for automated release gating.
+- Provide webhook endpoint for Zastava/registry triggers, scheduler job integration, and CI exit codes.
+- Deliver example workflows for GitHub Actions and GitLab CI.
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`, `src/Scheduler/StellaOps.Scheduler`
+
+## Dependencies & Concurrency
+- Depends on: `DriftGateEvaluator` (complete), `DeltaComputer` (complete), `DeltaVerdict` (complete).
+- Can run in parallel with: SPRINT_20251226_005_SCANNER (reachability extractors).
+- Blocks: SPRINT_20251226_004_FE (dashboard needs API endpoints from this sprint).
+
+## Documentation Prerequisites
+- `docs/modules/policy/architecture.md`
+- `docs/modules/scheduler/architecture.md`
+- `docs/modules/zastava/architecture.md`
+- `CLAUDE.md` (project conventions)
+
+## Delivery Tracker
+| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
+| --- | --- | --- | --- | --- | --- |
+| 1 | CICD-GATE-01 | DONE | None | Policy Guild | Create `POST /api/v1/policy/gate/evaluate` endpoint accepting image digest + baseline ref; returns `DeltaVerdict` with Pass/Warn/Fail status |
+| 2 | CICD-GATE-02 | DONE | CICD-GATE-01 | Policy Guild | Add webhook handler for Zastava image-push events; trigger async gate evaluation job |
+| 3 | CICD-GATE-03 | DONE | CICD-GATE-01 | Scheduler Guild | Create `GateEvaluationJob` in Scheduler; wire to Policy Engine gate endpoint |
+| 4 | CICD-GATE-04 | DONE | CICD-GATE-01 | Policy Guild | Define CI exit codes: 0=Pass, 1=Warn (configurable pass-through), 2=Fail/Block |
+| 5 | CICD-GATE-05 | DONE | CICD-GATE-04 | Policy Guild | CLI command `stella gate evaluate --image <digest> --baseline <ref>` with exit code support |
+| 6 | CICD-GATE-06 | DONE | CICD-GATE-02 | Policy Guild | Gate bypass audit logging: record who/when/why for any override; persist to audit table |
+| 7 | CICD-GATE-07 | DONE | CICD-GATE-05 | DevOps Guild | GitHub Actions example workflow using `stella gate evaluate` |
+| 8 | CICD-GATE-08 | DONE | CICD-GATE-05 | DevOps Guild | GitLab CI example workflow using `stella gate evaluate` |
+| 9 | CICD-GATE-09 | DONE | CICD-GATE-03 | Policy Guild + Zastava Guild | Integration tests: Zastava webhook -> Scheduler -> Policy Engine -> verdict |
+| 10 | CICD-GATE-10 | DONE | CICD-GATE-09 | Policy Guild | Documentation: update `docs/modules/policy/architecture.md` with gate API section |
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2025-12-26 | Sprint created from product advisory analysis; consolidates diff-aware release gate requirements. | Project Mgmt |
+| 2025-12-26 | CICD-GATE-01, CICD-GATE-04 DONE. Created GateEndpoints.cs and GateContracts.cs with POST /api/v1/policy/gate/evaluate endpoint. Defined GateStatus enum and GateExitCodes constants (0=Pass, 1=Warn, 2=Fail). | Impl |
+| 2025-12-26 | BLOCKED: Policy.Gateway build fails due to pre-existing errors in PostgresBudgetStore.cs (missing RiskBudget, BudgetEntry, IBudgetStore types from incomplete sprint). New gate files compile successfully when isolated. | Impl |
+| 2025-12-26 | UNBLOCKED: Fixed pre-existing build errors in Policy.Storage.Postgres (ServiceCollectionExtensions interface alias), Telemetry.Core (TagList using), Replay.Core (duplicate CompressionAlgorithm, missing interface methods, Span conversions), and Policy.Engine (OperationalContext/MitigationFactors property mapping). Policy.Gateway now builds successfully. | Impl |
+| 2025-12-26 | CICD-GATE-02 DONE. Created RegistryWebhookEndpoints.cs with Docker Registry v2, Harbor, and generic webhook handlers at /api/v1/webhooks/registry/*. Created InMemoryGateEvaluationQueue.cs with Channel-based async queue and GateEvaluationWorker background service. Fixed duplicate IBudgetStore interface (consolidated in BudgetLedger.cs with ListAsync method). | Impl |
+| 2025-12-26 | CICD-GATE-05 DONE. Created GateCommandGroup.cs with `stella gate evaluate` and `stella gate status` commands. Supports --image, --baseline, --policy, --allow-override, --justification options. Returns GateExitCodes (0=Pass, 1=Warn, 2=Fail, 10+=errors). Outputs table/JSON formats via Spectre.Console. Registered in CommandFactory.cs. | Impl |
+| 2025-12-26 | CICD-GATE-06 DONE. Created GateBypassAuditEntry, IGateBypassAuditRepository, InMemoryGateBypassAuditRepository, and GateBypassAuditor service. Integrated into GateEndpoints to record bypasses with actor, justification, IP, and CI context. Includes rate limiting support. | Impl |
+| 2025-12-26 | CICD-GATE-07, CICD-GATE-08 DONE. Created GitHub Actions example workflow (.github/workflows/stellaops-gate-example.yml) and GitLab CI example (deploy/gitlab/stellaops-gate-example.gitlab-ci.yml). Both demonstrate gate evaluation, baseline strategies, override workflows, and deployment gating. | Impl |
+| 2025-12-26 | Sprint archived. Core gate endpoint, CLI, webhook handlers, audit logging, and CI examples complete. Remaining tasks (CICD-GATE-03, 09, 10) are Scheduler integration and documentation - can be done in follow-up sprint. | Impl |
+| 2025-12-26 | CICD-GATE-03 DONE. Created GateEvaluationJob.cs in Scheduler Worker with IGateEvaluationScheduler interface, GateEvaluationRequest/Result records, GateEvaluationBatchSummary, retry logic with exponential backoff, and HttpPolicyGatewayClient for gate evaluation. | Impl |
+| 2025-12-26 | CICD-GATE-09 DONE. Created CicdGateIntegrationTests.cs with 20+ tests covering: gate evaluation (pass/block/warn), bypass logic (valid/invalid justification), exit codes (0/1/2), batch evaluation, audit logging, disabled gate handling, baseline comparison, and webhook parsing (Docker Registry v2, Harbor). | Impl |
+| 2025-12-26 | CICD-GATE-10 DONE. Updated docs/modules/policy/architecture.md with section 6.2 "CI/CD Release Gate API" covering gate endpoint, request/response format, gate status values, webhook endpoints, bypass auditing, and CLI integration examples. Sprint COMPLETE. | Impl |
+| 2025-12-26 | Pre-existing issue fixes. Fixed Scheduler Worker build errors: PartitionMaintenanceWorker.cs (GetConnectionAsync→OpenSystemConnectionAsync), PlannerQueueDispatchService.cs (Queue.SurfaceManifestPointer namespace, removed EmptyReadOnlyDictionary), IJobHistoryRepository (added GetRecentFailedAsync for cross-tenant indexing), GraphJobRepository (added cross-tenant ListBuildJobsAsync/ListOverlayJobsAsync overloads). Updated FailureSignatureIndexer to use new GetRecentFailedAsync method with JobHistoryEntity-to-FailedJobRecord conversion. Also fixed RedisSchedulerQueueTests.cs to use modern Testcontainers.Redis API. Scheduler Worker builds successfully. | Impl |
+
+## Decisions & Risks
+- Decision needed: Should Warn status block CI by default or pass-through? Recommend: configurable per-environment.
+- Decision needed: Gate evaluation timeout for long-running reachability analysis. Recommend: 60s default, configurable.
+- Risk: High evaluation latency may slow CI pipelines. Mitigation: async evaluation with cached baseline snapshots.
+- Risk: Gate bypass abuse. Mitigation: audit logging + Authority scope enforcement for bypass permission.
+
+## Next Checkpoints
+- 2025-12-30 | CICD-GATE-01 complete | Gate endpoint accepting requests |
+- 2026-01-03 | CICD-GATE-05 complete | CLI integration verified |
+- 2026-01-06 | CICD-GATE-09 complete | End-to-end integration tested |
--- a/docs-archived/implplan/sprints/20251226/SPRINT_20251226_001_SIGNER_fulcio_keyless_client.md
+++ b/docs-archived/implplan/sprints/20251226/SPRINT_20251226_001_SIGNER_fulcio_keyless_client.md
@@ -0,0 +1,509 @@
+# SPRINT_20251226_001_SIGNER_fulcio_keyless_client
+
+**Sprint ID:** 20251226_001_SIGNER
+**Topic:** Fulcio Keyless Signing Client Implementation
+**Status:** DONE
+**Priority:** P0 (Critical Path)
+**Created:** 2025-12-26
+**Working Directory:** `src/Signer/`
+
+---
+
+## Executive Summary
+
+Implement Sigstore Fulcio integration for keyless signing in CI/CD pipelines. This enables ephemeral X.509 certificates (~10 min TTL) obtained via OIDC identity tokens, eliminating the need for persistent signing keys in CI environments while maintaining cryptographic non-repudiation through Rekor transparency logging.
+
+**Business Value:**
+- Zero key management overhead in CI pipelines
+- Eliminates credential sprawl and secret rotation complexity
+- Enables audit-grade non-repudiation via OIDC identity binding
+- Aligns with Sigstore industry standard (adopted by Kubernetes, npm, PyPI)
+
+**Dependencies:**
+- Attestor module for Rekor submission (Sprint 20251226_002)
+- Authority module for OIDC token minting (existing)
+- RFC 8785 canonicalization (existing in `StellaOps.Canonicalization`)
+
+---
+
+## Prerequisites
+
+**Required Reading (complete before DOING):**
+- [ ] `docs/modules/signer/architecture.md` - Signer architecture dossier
+- [ ] `docs/modules/attestor/architecture.md` - Attestor architecture (§2.1 for Rekor)
+- [ ] `CLAUDE.md` - Project coding standards
+- [ ] `src/Signer/AGENTS.md` - Module charter (if exists, create if not)
+- [ ] Sigstore Fulcio documentation: https://docs.sigstore.dev/certificate_authority/overview/
+
+**Technical Prerequisites:**
+- [ ] Authority OIDC endpoint operational (`/oauth/token`)
+- [ ] BouncyCastle crypto library available for ECDSA/Ed25519
+- [ ] HTTP/2 client infrastructure for Fulcio API calls
+
+---
+
+## Scope & Boundaries
+
+### In Scope
+- Fulcio OIDC client implementation
+- Ephemeral keypair generation (ECDSA P-256, Ed25519)
+- Certificate chain handling and validation
+- Integration with existing `IDsseSigner` interface
+- Configuration schema for Fulcio endpoints
+- Unit and integration tests
+
+### Out of Scope
+- Rekor submission (handled by Attestor - Sprint 002)
+- Bundle rotation workflows (Sprint 002)
+- CLI integration (Sprint 003)
+- CI/CD templates (Sprint 004)
+
+### Guardrails
+- No hard-coded external URLs; all endpoints configurable
+- Ephemeral keys MUST NOT persist to disk
+- Certificate chains MUST validate to configured Fulcio roots
+- All timestamps in UTC ISO-8601
+
+---
+
+## Architecture
+
+### Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Signer Service                           │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌──────────────────┐    ┌──────────────────┐                   │
+│  │ SignerPipeline   │───▶│ IDsseSigner      │                   │
+│  └──────────────────┘    └────────┬─────────┘                   │
+│                                   │                              │
+│           ┌───────────────────────┼───────────────────────┐     │
+│           ▼                       ▼                       ▼     │
+│  ┌────────────────┐    ┌──────────────────┐    ┌──────────────┐ │
+│  │ CryptoDsseSigner│    │ KeylessDsseSigner│    │ KmsDsseSigner │ │
+│  │ (existing)     │    │ (NEW)            │    │ (existing)   │ │
+│  └────────────────┘    └────────┬─────────┘    └──────────────┘ │
+│                                 │                               │
+│                    ┌────────────┴────────────┐                  │
+│                    ▼                         ▼                  │
+│           ┌──────────────────┐    ┌──────────────────┐          │
+│           │ IFulcioClient    │    │ IEphemeralKeyGen │          │
+│           │ (NEW)            │    │ (NEW)            │          │
+│           └────────┬─────────┘    └──────────────────┘          │
+│                    │                                            │
+└────────────────────┼────────────────────────────────────────────┘
+                     │
+                     ▼ HTTPS (mTLS optional)
+            ┌──────────────────┐
+            │ Fulcio CA        │
+            │ (external)       │
+            └──────────────────┘
+```
+
+### New Interfaces
+
+```csharp
+// src/Signer/__Libraries/StellaOps.Signer.Keyless/IFulcioClient.cs
+public interface IFulcioClient
+{
+    Task<FulcioCertificateResult> GetCertificateAsync(
+        FulcioCertificateRequest request,
+        CancellationToken cancellationToken = default);
+}
+
+public record FulcioCertificateRequest(
+    byte[] PublicKey,
+    string Algorithm,           // "ECDSA_P256" | "Ed25519"
+    string OidcIdentityToken,
+    string? ProofOfPossession); // Optional signed challenge
+
+public record FulcioCertificateResult(
+    byte[] Certificate,
+    byte[][] CertificateChain,
+    string SignedCertificateTimestamp,
+    DateTimeOffset NotBefore,
+    DateTimeOffset NotAfter,
+    FulcioIdentity Identity);
+
+public record FulcioIdentity(
+    string Issuer,
+    string Subject,
+    string? SubjectAlternativeName);
+```
+
+```csharp
+// src/Signer/__Libraries/StellaOps.Signer.Keyless/IEphemeralKeyGenerator.cs
+public interface IEphemeralKeyGenerator
+{
+    EphemeralKeyPair Generate(string algorithm);
+    void Dispose(EphemeralKeyPair keyPair); // Secure erasure
+}
+
+public sealed class EphemeralKeyPair : IDisposable
+{
+    public byte[] PublicKey { get; }
+    public byte[] PrivateKey { get; } // In-memory only, never persisted
+    public string Algorithm { get; }
+    public DateTimeOffset CreatedAt { get; }
+
+    public void Dispose(); // Zeros memory
+}
+```
+
+---
+
+## Delivery Tracker
+
+| ID | Task | Owner | Status | Dependencies | Acceptance Criteria |
+|----|------|-------|--------|--------------|---------------------|
+| 0001 | Create `StellaOps.Signer.Keyless` library project | — | DONE | — | Project compiles, referenced by Signer.Infrastructure |
+| 0002 | Implement `IEphemeralKeyGenerator` interface | — | DONE | 0001 | Generates ECDSA P-256 and Ed25519 keypairs |
+| 0003 | Implement `EphemeralKeyPair` with secure disposal | — | DONE | 0002 | Memory zeroed on Dispose(), finalizer backup |
+| 0004 | Implement `IFulcioClient` interface | — | DONE | 0001 | Contract defined, mockable |
+| 0005 | Implement `HttpFulcioClient` | — | DONE | 0004 | HTTP/2 client, retries, circuit breaker |
+| 0006 | Add Fulcio response parsing (X.509 chain) | — | DONE | 0005 | PEM/DER parsing, chain ordering |
+| 0007 | Implement `KeylessDsseSigner` | — | DONE | 0003, 0006 | Signs DSSE with ephemeral key + Fulcio cert |
+| 0008 | Add `verdict.stella/v1` predicate type | — | DONE | — | PredicateTypes.cs updated, schema defined |
+| 0009 | Add configuration schema `SignerKeylessOptions` | — | DONE | 0005 | YAML/JSON config, validation |
+| 0010 | Wire DI registration in `ServiceCollectionExtensions` | — | DONE | 0007, 0009 | `services.AddKeylessSigning()` |
+| 0011 | Implement certificate chain validation | — | DONE | 0006 | Validates to configured Fulcio roots |
+| 0012 | Add OIDC token acquisition from Authority | — | DONE | — | Client credentials flow, caching |
+| 0013 | Unit tests: EphemeralKeyGenerator | — | DONE | 0003 | Key generation, disposal, algorithm coverage |
+| 0014 | Unit tests: HttpFulcioClient (mocked) | — | DONE | 0005 | Happy path, error handling, retries |
+| 0015 | Unit tests: KeylessDsseSigner | — | DONE | 0007 | Signing roundtrip, cert attachment |
+| 0016 | Unit tests: Certificate chain validation | — | DONE | 0011 | Valid chain, expired cert, untrusted root |
+| 0017 | Integration test: Full keyless signing flow | — | DONE | 0010 | End-to-end with mock Fulcio |
+| 0018 | Integration test: Verify signed bundle | — | DONE | 0017 | Signature verification, cert chain |
+| 0019 | Documentation: Keyless signing guide | — | DONE | 0017 | `docs/modules/signer/guides/keyless-signing.md` |
+| 0020 | Update `src/Signer/AGENTS.md` | — | DONE | 0019 | Add keyless components to charter |
+
+---
+
+## Technical Specifications
+
+### Configuration Schema
+
+```yaml
+# etc/signer.yaml
+signer:
+  signing:
+    mode: "keyless"  # "keyless" | "kms" | "hybrid"
+    keyless:
+      enabled: true
+      fulcio:
+        url: "https://fulcio.sigstore.dev"
+        # For private deployments:
+        # url: "https://fulcio.internal.example.com"
+        timeout: 30s
+        retries: 3
+        backoffBase: 1s
+        backoffMax: 30s
+      oidc:
+        # Use Authority as OIDC provider
+        issuer: "https://authority.internal"
+        clientId: "signer-keyless"
+        clientSecretRef: "env:SIGNER_OIDC_CLIENT_SECRET"
+        # Alternative: use ambient OIDC (CI runner tokens)
+        useAmbientToken: false
+        ambientTokenPath: "/var/run/secrets/tokens/oidc"
+      algorithms:
+        preferred: "ECDSA_P256"
+        allowed: ["ECDSA_P256", "Ed25519"]
+      certificate:
+        # Fulcio roots for validation
+        rootBundlePath: "/etc/stellaops/fulcio-roots.pem"
+        # Allow additional roots for private Fulcio instances
+        additionalRoots: []
+        validateChain: true
+        requireSCT: true  # Require Signed Certificate Timestamp
+      identity:
+        # Expected OIDC issuer for verification
+        expectedIssuers:
+          - "https://authority.internal"
+          - "https://token.actions.githubusercontent.com"
+          - "https://gitlab.com"
+        # Expected SAN patterns (regex)
+        expectedSubjectPatterns:
+          - "^https://github\\.com/stella-ops/.*$"
+          - "^urn:stellaops:signer$"
+```
+
+### Error Handling
+
+```csharp
+public abstract class KeylessSigningException : SignerException
+{
+    protected KeylessSigningException(string message, Exception? inner = null)
+        : base(message, inner) { }
+}
+
+public class FulcioUnavailableException : KeylessSigningException
+{
+    public string FulcioUrl { get; }
+    public int HttpStatus { get; }
+}
+
+public class OidcTokenAcquisitionException : KeylessSigningException
+{
+    public string Issuer { get; }
+    public string Reason { get; }
+}
+
+public class CertificateChainValidationException : KeylessSigningException
+{
+    public string[] ChainSubjects { get; }
+    public string ValidationError { get; }
+}
+
+public class EphemeralKeyGenerationException : KeylessSigningException
+{
+    public string Algorithm { get; }
+}
+```
+
+### Metrics
+
+```csharp
+// Prometheus metrics
+signer.keyless.cert_requests_total{result="success|failure|timeout"}
+signer.keyless.cert_latency_seconds{quantile="0.5|0.9|0.99"}
+signer.keyless.oidc_token_refresh_total{result="success|failure"}
+signer.keyless.ephemeral_keys_generated_total{algorithm="ECDSA_P256|Ed25519"}
+signer.keyless.cert_chain_validation_total{result="valid|expired|untrusted"}
+```
+
+### OpenTelemetry Traces
+
+```
+signer.keyless.sign
+├── signer.keyless.generate_ephemeral_key
+├── signer.keyless.acquire_oidc_token
+├── signer.keyless.request_certificate
+│   ├── http.request POST /api/v2/signingCert
+│   └── signer.keyless.parse_certificate_chain
+├── signer.keyless.validate_certificate_chain
+└── signer.keyless.sign_payload
+```
+
+---
+
+## Testing Requirements
+
+### Unit Test Coverage
+
+| Component | Test File | Coverage Target |
+|-----------|-----------|-----------------|
+| EphemeralKeyGenerator | `EphemeralKeyGeneratorTests.cs` | 100% |
+| HttpFulcioClient | `HttpFulcioClientTests.cs` | 95% |
+| KeylessDsseSigner | `KeylessDsseSignerTests.cs` | 95% |
+| CertificateChainValidator | `CertificateChainValidatorTests.cs` | 100% |
+| SignerKeylessOptions | `SignerKeylessOptionsTests.cs` | 100% |
+
+### Integration Tests
+
+```csharp
+[Fact]
+public async Task KeylessSigning_WithMockFulcio_ProducesValidDsse()
+{
+    // Arrange: Mock Fulcio server returning valid cert chain
+    // Act: Sign a verdict payload
+    // Assert: DSSE envelope contains valid signature + cert chain
+}
+
+[Fact]
+public async Task KeylessSigning_CertificateExpired_ThrowsValidationException()
+{
+    // Arrange: Mock Fulcio returning expired certificate
+    // Act/Assert: CertificateChainValidationException thrown
+}
+
+[Fact]
+public async Task KeylessSigning_FulcioUnavailable_RetriesWithBackoff()
+{
+    // Arrange: Mock Fulcio returning 503 then 200
+    // Act: Sign payload
+    // Assert: Success after retry, metrics recorded
+}
+
+[Fact]
+public async Task KeylessSigning_OidcTokenInvalid_ThrowsAcquisitionException()
+{
+    // Arrange: Authority returns 401
+    // Act/Assert: OidcTokenAcquisitionException thrown
+}
+
+[Fact]
+public async Task EphemeralKeyPair_Disposal_ZerosMemory()
+{
+    // Arrange: Generate keypair
+    // Act: Dispose
+    // Assert: Private key memory is zeroed (via reflection/unsafe)
+}
+```
+
+### Property-Based Tests
+
+```csharp
+[Property]
+public void KeylessSigning_SamePayload_DifferentSignatures(byte[] payload)
+{
+    // Ephemeral keys mean different signatures each time
+    var sig1 = await signer.SignAsync(payload);
+    var sig2 = await signer.SignAsync(payload);
+    Assert.NotEqual(sig1.Signature, sig2.Signature);
+    Assert.NotEqual(sig1.Certificate, sig2.Certificate);
+}
+
+[Property]
+public void KeylessSigning_SignatureDeterminism_SameKeyPair(
+    byte[] payload, EphemeralKeyPair keyPair)
+{
+    // Same ephemeral key produces same signature for same payload
+    var sig1 = Sign(payload, keyPair);
+    var sig2 = Sign(payload, keyPair);
+    Assert.Equal(sig1, sig2);
+}
+```
+
+---
+
+## Security Considerations
+
+### Threat Model
+
+| Threat | Mitigation |
+|--------|------------|
+| Private key theft | Keys exist only in memory, zeroed on disposal |
+| Fulcio impersonation | TLS certificate validation, root pinning |
+| OIDC token replay | Short-lived tokens, audience validation |
+| Certificate forgery | Chain validation to trusted Fulcio roots |
+| Timing attacks | Constant-time comparison for signatures |
+
+### Security Checklist
+
+- [ ] Ephemeral keys never written to disk or logs
+- [ ] Private key memory zeroed in Dispose() and finalizer
+- [ ] Fulcio TLS certificate validated
+- [ ] OIDC token audience matches expected value
+- [ ] Certificate chain validates to configured roots
+- [ ] SCT (Signed Certificate Timestamp) verified when required
+- [ ] No secrets in configuration (use refs: `env:`, `file:`, `vault:`)
+
+---
+
+## Decisions & Risks
+
+| ID | Decision/Risk | Status | Owner | Notes |
+|----|---------------|--------|-------|-------|
+| D001 | Use ECDSA P-256 as default algorithm | DECIDED | — | Widest compatibility, Fulcio default |
+| D002 | Support Ed25519 as alternative | DECIDED | — | Better performance, growing adoption |
+| R001 | Fulcio availability dependency | OPEN | — | Mitigate with retries, circuit breaker, fallback to KMS |
+| R002 | OIDC token acquisition latency | OPEN | — | Cache tokens, refresh proactively |
+| R003 | Air-gap incompatibility | ACCEPTED | — | Keyless requires network; use KMS mode for air-gap |
+
+---
+
+## Upcoming Checkpoints
+
+| Date | Milestone | Exit Criteria |
+|------|-----------|---------------|
+| +3 days | Core interfaces complete | 0001-0004 DONE |
+| +7 days | Fulcio client working | 0005-0006 DONE, manual test passing |
+| +10 days | Keyless signer integrated | 0007-0012 DONE |
+| +14 days | Full test coverage | 0013-0018 DONE |
+| +15 days | Documentation complete | 0019-0020 DONE, sprint DONE |
+
+---
+
+## Execution Log
+
+| Date | Role | Action | Notes |
+|------|------|--------|-------|
+| 2025-12-26 | PM | Sprint created | Initial planning from keyless signing advisory |
+| 2025-12-26 | Impl | Tasks 0001-0006, 0009-0010 DONE | Created StellaOps.Signer.Keyless library with IEphemeralKeyGenerator, EphemeralKeyPair, IFulcioClient, HttpFulcioClient, SignerKeylessOptions, and DI extensions. Library compiles successfully. |
+| 2025-12-26 | Impl | Tasks 0007, 0012 DONE | Implemented KeylessDsseSigner (IDsseSigner) with full DSSE envelope creation, PAE encoding, and in-toto statement generation. Created IOidcTokenProvider interface and AmbientOidcTokenProvider for CI runner ambient tokens. All new code compiles successfully. |
+| 2025-12-26 | Impl | Tasks 0008, 0011 DONE | Added CertificateChainValidator with Fulcio root validation, identity verification, and expected issuer/subject pattern matching. Added StellaOpsVerdict and StellaOpsVerdictAlt predicate types to PredicateTypes.cs with IsVerdictType() helper. |
+| 2025-12-26 | Impl | Tasks 0013, 0015 DONE | Created comprehensive unit tests for EphemeralKeyGenerator (14 tests) and KeylessDsseSigner (14 tests) in src/Signer/StellaOps.Signer/StellaOps.Signer.Tests/Keyless/. Fixed pre-existing build errors: added X509Certificates using to SigstoreSigningService.cs, fixed IList-to-IReadOnlyList conversion in KeyRotationService.cs, added KeyManagement project reference to WebService. Note: Pre-existing test files (TemporalKeyVerificationTests.cs, KeyRotationWorkflowIntegrationTests.cs) have stale entity references blocking full test build. |
+| 2025-12-26 | Impl | Pre-existing test fixes | Fixed stale entity references in TemporalKeyVerificationTests.cs and KeyRotationWorkflowIntegrationTests.cs (Id→AnchorId, KeyHistories→KeyHistory, TrustAnchorId→AnchorId, added PublicKey property). Signer.Tests now builds successfully with 0 errors. |
+| 2025-12-26 | Impl | Tasks 0014-0020 DONE | Created HttpFulcioClientTests.cs (14 tests for retry, error handling, certificate parsing), CertificateChainValidatorTests.cs (12 tests for chain validation, identity verification), KeylessSigningIntegrationTests.cs (10+ end-to-end tests with mock Fulcio server). Created comprehensive keyless-signing.md documentation. Updated Signer AGENTS.md with keyless components. Sprint COMPLETE. |
+| 2025-12-26 | Impl | Pre-existing issue fixes | Fixed namespace corruption in KeylessSigningIntegrationTests.cs (StellaOps.Signaturener→StellaOps.Signer, SignaturenAsync→SignAsync, Signaturenatures→Signatures). Signer solution builds successfully with only deprecation warnings (SYSLIB0057 for X509Certificate2 constructor). |
+
+---
+
+## Related Documents
+
+- **Parent Advisory:** `docs/product-advisories/25-Dec-2025 - Planning Keyless Signing for Verdicts.md`
+- **Related Advisory:** `docs/product-advisories/25-Dec-2025 - Building a Deterministic Verdict Engine.md`
+- **Signer Architecture:** `docs/modules/signer/architecture.md`
+- **Attestor Architecture:** `docs/modules/attestor/architecture.md`
+- **Successor Sprint:** `SPRINT_20251226_002_ATTESTOR_bundle_rotation.md`
+
+---
+
+## Appendix A: Fulcio API Contract
+
+### Request: POST /api/v2/signingCert
+
+```json
+{
+  "credentials": {
+    "oidcIdentityToken": "eyJhbGciOiJSUzI1NiIs..."
+  },
+  "publicKeyRequest": {
+    "publicKey": {
+      "algorithm": "ECDSA",
+      "content": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
+    },
+    "proofOfPossession": "MEUCIQD..."  // Optional
+  }
+}
+```
+
+### Response: 200 OK
+
+```json
+{
+  "signedCertificateEmbeddedSct": {
+    "chain": {
+      "certificates": [
+        "-----BEGIN CERTIFICATE-----\nMIIC...",
+        "-----BEGIN CERTIFICATE-----\nMIIB..."
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Appendix B: DSSE Bundle with Keyless Certificate
+
+```json
+{
+  "payloadType": "application/vnd.in-toto+json",
+  "payload": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEi...",
+  "signatures": [
+    {
+      "keyid": "",
+      "sig": "MEUCIQDx5z...",
+      "cert": "-----BEGIN CERTIFICATE-----\nMIIC..."
+    }
+  ],
+  "certificateChain": [
+    "-----BEGIN CERTIFICATE-----\nMIIC...",
+    "-----BEGIN CERTIFICATE-----\nMIIB..."
+  ],
+  "signedCertificateTimestamp": "AO3W9T...",
+  "signingMode": "keyless",
+  "signingIdentity": {
+    "issuer": "https://authority.internal",
+    "subject": "signer@stella-ops.org",
+    "san": "urn:stellaops:signer"
+  }
+}
+```
+
+---
+
+*End of Sprint Document*
--- a/docs-archived/implplan/sprints/20251226/SPRINT_20251226_003_BE_exception_approval.md
+++ b/docs-archived/implplan/sprints/20251226/SPRINT_20251226_003_BE_exception_approval.md
@@ -0,0 +1,80 @@
+# Sprint 20251226 · Exception Approval Workflow
+
+**Status:** DONE
+
+## Topic & Scope
+- Implement role-based exception approval workflows building on existing `ExceptionAdapter`.
+- Add approval request entity, time-limited overrides, and comprehensive audit trails.
+- Integrate with Authority for approver role enforcement.
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`, `src/Authority/StellaOps.Authority`
+
+## Dependencies & Concurrency
+- Depends on: `ExceptionAdapter.cs` (complete), `ExceptionLifecycleService` (complete).
+- Depends on: SPRINT_20251226_001_BE (gate bypass requires approval workflow).
+- Can run in parallel with: SPRINT_20251226_002_BE (budget enforcement).
+
+## Documentation Prerequisites
+- `docs/modules/policy/architecture.md`
+- `docs/modules/authority/architecture.md`
+- `docs/product-advisories/26-Dec-2026 - Diff-Aware Releases and Auditable Exceptions.md`
+
+## Delivery Tracker
+| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
+| --- | --- | --- | --- | --- | --- |
+| 1 | EXCEPT-01 | DONE | None | Policy Guild | Create `exception_approval_requests` PostgreSQL table: request_id, exception_id, requestor_id, approver_ids[], status, justification, evidence_refs[], created_at, expires_at |
+| 2 | EXCEPT-02 | DONE | EXCEPT-01 | Policy Guild | Implement `ExceptionApprovalRepository` with request/approve/reject operations |
+| 3 | EXCEPT-03 | DONE | EXCEPT-02 | Policy Guild | Approval rules engine: define required approvers by gate level (G1=1 peer, G2=code owner, G3+=DM+PM) |
+| 4 | EXCEPT-04 | DONE | EXCEPT-03 | Authority Guild | Create `exception:approve` and `exception:request` scopes in Authority |
+| 5 | EXCEPT-05 | DONE | EXCEPT-04 | Policy Guild | API endpoint `POST /api/v1/policy/exception/request` to initiate approval workflow |
+| 6 | EXCEPT-06 | DONE | EXCEPT-04 | Policy Guild | API endpoint `POST /api/v1/policy/exception/{id}/approve` for approver action |
+| 7 | EXCEPT-07 | DONE | EXCEPT-04 | Policy Guild | API endpoint `POST /api/v1/policy/exception/{id}/reject` for rejection with reason |
+| 8 | EXCEPT-08 | DONE | EXCEPT-02 | Policy Guild | Time-limited overrides: max TTL enforcement (30d default), auto-expiry with notification |
+| 9 | EXCEPT-09 | DONE | EXCEPT-06 | Policy Guild | Audit trail: log all approval actions with who/when/why/evidence to `exception_audit` table |
+| 10 | EXCEPT-10 | DONE | EXCEPT-06 | Policy Guild | CLI command `stella exception request --cve <id> --scope <image> --reason <text> --ttl <days>` |
+| 11 | EXCEPT-11 | DONE | EXCEPT-06 | Policy Guild | CLI command `stella exception approve --request <id>` for approvers |
+| 12 | EXCEPT-12 | DEFERRED | EXCEPT-08 | Notify Guild | Approval request notifications to designated approvers |
+| 13 | EXCEPT-13 | DEFERRED | EXCEPT-08 | Notify Guild | Expiry warning notifications (7d, 1d before expiry) |
+| 14 | EXCEPT-14 | DEFERRED | EXCEPT-09 | Policy Guild | Integration tests: request/approve/reject flows, TTL enforcement, audit trail |
+| 15 | EXCEPT-15 | DONE | EXCEPT-14 | Policy Guild | Documentation: add exception workflow section to policy architecture doc |
+| 16 | EXCEPT-16 | DEFERRED | EXCEPT-08 | Scheduler Guild | Auto-revalidation job: re-test exceptions on expiry, "fix available" feed signal, or EPSS increase |
+| 17 | EXCEPT-17 | DEFERRED | EXCEPT-16 | Policy Guild | Flip gate to "needs re-review" on revalidation failure with notification |
+| 18 | EXCEPT-18 | DEFERRED | EXCEPT-01 | Policy Guild | Exception inheritance: repo->image->env scoping with explicit shadowing |
+| 19 | EXCEPT-19 | DEFERRED | EXCEPT-18 | Policy Guild | Conflict surfacing: detect and report shadowed exceptions in evaluation |
+| 20 | EXCEPT-20 | DEFERRED | EXCEPT-09 | Attestor Guild | OCI-attached exception attestation: store exception as `application/vnd.stellaops.exception+json` |
+| 21 | EXCEPT-21 | DEFERRED | EXCEPT-20 | Policy Guild | CLI command `stella exception export --id <id> --format oci-attestation` |
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2025-12-26 | Sprint created from product advisory analysis; implements auditable exceptions from diff-aware release gates advisory. | Project Mgmt |
+| 2025-12-26 | Added EXCEPT-16 through EXCEPT-21 from "Diff-Aware Releases and Auditable Exceptions" advisory (auto-revalidation, inheritance, OCI attestation). Advisory marked SUPERSEDED. | Project Mgmt |
+| 2025-12-26 | EXCEPT-01 DONE. Created migration 013_exception_approval.sql with exception_approval_requests, exception_approval_audit, and exception_approval_rules tables. Includes RLS policies, indexes, default approval rules per gate level, and helper functions (expire_pending_approval_requests, get_approval_requirements). | Impl |
+| 2025-12-26 | EXCEPT-02 DONE. Created ExceptionApprovalEntity.cs with entity models (ExceptionApprovalRequestEntity, ExceptionApprovalAuditEntity, ExceptionApprovalRuleEntity) and enums (ApprovalRequestStatus, GateLevel, ExceptionReasonCode). Created IExceptionApprovalRepository.cs interface and ExceptionApprovalRepository.cs implementation with full CRUD, approve/reject/cancel, audit trail, and optimistic concurrency. | Impl |
+| 2025-12-26 | EXCEPT-03 DONE. Created ExceptionApprovalRulesService.cs with IExceptionApprovalRulesService interface. Implements gate-level requirements (G0=auto-approve, G1=1 peer, G2=code owner, G3=DM+PM, G4=CISO+DM+PM), request validation, approval action validation, and required approver determination. Supports tenant-specific rules with fallback to defaults. | Impl |
+| 2025-12-26 | EXCEPT-04 DONE. Added ExceptionsRequest scope ("exceptions:request") to StellaOpsScopes.cs in Authority. ExceptionsApprove already existed. | Impl |
+| 2025-12-26 | EXCEPT-05 to EXCEPT-07 DONE. Created ExceptionApprovalEndpoints.cs with POST /request, POST /{requestId}/approve, POST /{requestId}/reject, POST /{requestId}/cancel, GET /request/{requestId}, GET /requests, GET /pending, GET /{requestId}/audit, GET /rules endpoints. Registered services and endpoints in Policy.Gateway Program.cs. | Impl |
+| 2025-12-26 | EXCEPT-08, EXCEPT-09 DONE. TTL enforcement implemented in entity model (RequestedTtlDays, ExceptionExpiresAt), validation in rules service (MaxTtlDays per gate level), and database (CHECK constraint 1-365 days). Audit trail implemented in repository (RecordAuditAsync), migration (exception_approval_audit table), and endpoints (auto-records on create/approve/reject). | Impl |
+| 2025-12-26 | EXCEPT-10, EXCEPT-11 DONE. Created ExceptionCommandGroup.cs with CLI commands: `stella exception request`, `stella exception approve`, `stella exception reject`, `stella exception list`, `stella exception status`. Supports --cve, --purl, --image, --digest, --reason, --rationale, --ttl, --gate-level, --reason-code, --ticket, --evidence, --control, --env, --approver options. Registered in CommandFactory.cs. | Impl |
+| 2025-12-26 | EXCEPT-15 DONE. Sprint marked as done. Core approval workflow complete (EXCEPT-01 through EXCEPT-11). Deferred tasks (EXCEPT-12-14, EXCEPT-16-21) are enhancements requiring Notify Guild, Scheduler Guild, and Attestor Guild integration - can be done in follow-up sprints. | Impl |
+
+## Decisions & Risks
+- Decision: Self-approval allowed for G0-G1, not for G2+. Implemented in ApprovalRequirements.GetDefault().
+- Decision: Evidence required for G2+, optional for G0-G1. Implemented in rules validation.
+- Decision: Exception inheritance (repo -> image -> env) deferred to follow-up sprint (EXCEPT-18).
+- Risk: Approval bottleneck slowing releases. Mitigation: parallel approval paths via RequiredApproverIds array.
+- Risk: Expired exceptions causing sudden build failures. Mitigation: 7-day request expiry window, TTL enforcement.
+
+## Next Checkpoints
+- 2025-12-30 | EXCEPT-03 complete | Approval rules engine implemented | DONE
+- 2026-01-03 | EXCEPT-07 complete | All API endpoints functional | DONE
+- 2026-01-06 | EXCEPT-14 complete | Full workflow integration tested | DEFERRED
+
+## Summary of Deliverables
+- **Database Migration:** `src/Policy/__Libraries/StellaOps.Policy.Storage.Postgres/Migrations/013_exception_approval.sql`
+- **Entity Models:** `src/Policy/__Libraries/StellaOps.Policy.Storage.Postgres/Models/ExceptionApprovalEntity.cs`
+- **Repository Interface:** `src/Policy/__Libraries/StellaOps.Policy.Storage.Postgres/Repositories/IExceptionApprovalRepository.cs`
+- **Repository Implementation:** `src/Policy/__Libraries/StellaOps.Policy.Storage.Postgres/Repositories/ExceptionApprovalRepository.cs`
+- **Rules Service:** `src/Policy/StellaOps.Policy.Engine/Services/ExceptionApprovalRulesService.cs`
+- **API Endpoints:** `src/Policy/StellaOps.Policy.Gateway/Endpoints/ExceptionApprovalEndpoints.cs`
+- **CLI Commands:** `src/Cli/StellaOps.Cli/Commands/ExceptionCommandGroup.cs`
+- **Authority Scope:** `src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs` (ExceptionsRequest added)