# Surface.Secrets Provider Chain

## Module
Scanner

## Status
VERIFIED

## Description
Pluggable secret provider chain with backends for Kubernetes mounted secrets, file-based secrets, and offline credential stores. Provides typed handles for attestation signing keys, CAS tokens, and registry credentials.

## Implementation Details
- **Provider Interface**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/ISurfaceSecretProvider.cs` - `ISurfaceSecretProvider` interface for pluggable secret providers
- **Provider Implementations**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/CompositeSurfaceSecretProvider.cs` - `CompositeSurfaceSecretProvider` chaining multiple providers with fallback
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/KubernetesSurfaceSecretProvider.cs` - `KubernetesSurfaceSecretProvider` reading secrets from Kubernetes mounted volumes
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/FileSurfaceSecretProvider.cs` - `FileSurfaceSecretProvider` reading secrets from file system paths
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/InlineSurfaceSecretProvider.cs` - `InlineSurfaceSecretProvider` for inline/environment-variable secrets
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/InMemorySurfaceSecretProvider.cs` - In-memory provider for testing
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/OfflineSurfaceSecretProvider.cs` - `OfflineSurfaceSecretProvider` for air-gapped credential stores
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/AuditingSurfaceSecretProvider.cs` - `AuditingSurfaceSecretProvider` wrapping providers with access auditing
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/Providers/CachingSurfaceSecretProvider.cs` - `CachingSurfaceSecretProvider` caching secret lookups
- **Typed Secret Handles**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/AttestationSecret.cs` - `AttestationSecret` typed handle for attestation signing keys
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/CasAccessSecret.cs` - `CasAccessSecret` typed handle for CAS (Content-Addressable Storage) tokens
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/RegistryAccessSecret.cs` - `RegistryAccessSecret` typed handle for container registry credentials
- **Request Model**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/SurfaceSecretRequest.cs` - Request model for secret retrieval
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/SurfaceSecretHandle.cs` - Handle wrapping resolved secrets
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/SurfaceSecretNotFoundException.cs` - Exception when secrets are not found
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/SurfaceSecretsOptions.cs` - Configuration options
- **DI & Integration**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets/ServiceCollectionExtensions.cs` - DI registration for surface secrets
  - `src/Scanner/StellaOps.Scanner.Worker/Options/ScannerStorageSurfaceSecretConfigurator.cs` - Worker-side secret configuration
  - `src/Scanner/StellaOps.Scanner.WebService/Options/ScannerSurfaceSecretConfigurator.cs` - WebService-side secret configuration
- **Tests**:
  - `src/Scanner/__Tests/StellaOps.Scanner.Surface.Secrets.Tests/InlineSurfaceSecretProviderTests.cs` - Inline provider tests
  - `src/Scanner/__Tests/StellaOps.Scanner.Surface.Secrets.Tests/FileSurfaceSecretProviderTests.cs` - File provider tests

## E2E Test Plan
- [ ] Configure a composite provider chain (Kubernetes -> File -> Offline) and verify secrets are resolved from the first available provider
- [ ] Verify `KubernetesSurfaceSecretProvider` reads secrets from Kubernetes mounted volumes at expected paths
- [ ] Verify `AttestationSecret` typed handle correctly provides attestation signing key material
- [ ] Verify `RegistryAccessSecret` typed handle provides registry credentials for authenticated pulls
- [ ] Verify `AuditingSurfaceSecretProvider` logs all secret access for audit trail
- [ ] Verify `OfflineSurfaceSecretProvider` works in air-gapped environments without network access

---

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source files exist | PASS |
| Tier 1 - Build + code review | PASS |
| Tier 2 - Integration tests | PASS |
| Verified | 2026-02-13T18:10:00Z |