Add Authority Advisory AI and API Lifecycle Configuration

- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings. - Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations. - Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration. - Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options. - Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations. - Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client. - Updated project file to include necessary package references for the new Issuer Directory Client library.
2025-11-02 13:40:38 +02:00
parent 66cb6c4b8a
commit f98cea3bcf
516 changed files with 68157 additions and 24754 deletions
--- a/docs/modules/issuer-directory/architecture.md
+++ b/docs/modules/issuer-directory/architecture.md
@@ -0,0 +1,95 @@
+# Issuer Directory Architecture
+
+> **Status:** Initial service scaffold (Sprint 100 – Identity & Signing)
+
+## 1. Purpose
+
+Issuer Directory centralises trusted VEX/CSAF publisher metadata so downstream services (VEX Lens, Excititor, Policy Engine) can resolve issuer identity, active keys, and trust weights. The initial milestone delivers tenant-scoped CRUD APIs with audit logging plus bootstrap import for CSAF publishers.
+
+## 2. Runtime Topology
+
+- **Service name:** `stellaops/issuer-directory`
+- **Framework:** ASP.NET Core minimal APIs (`net10.0`)
+- **Persistence:** MongoDB (`issuer-directory.issuers`, `issuer-directory.issuer_keys`, `issuer-directory.issuer_audit`)
+- **AuthZ:** StellaOps resource server scopes (`issuer-directory:read`, `issuer-directory:write`, `issuer-directory:admin`)
+- **Audit:** Every create/update/delete emits an audit record with actor, reason, and context.
+- **Bootstrap:** On startup, the service imports `data/csaf-publishers.json` into the global tenant (`@global`) and records a `seeded` audit the first time each publisher is added.
+- **Key lifecycle:** API validates Ed25519 public keys, X.509 certificates, and DSSE public keys, enforces future expiries, deduplicates fingerprints, and records audit entries for create/rotate/revoke actions.
+
+```
+Clients ──> Authority (DPoP/JWT) ──> IssuerDirectory WebService ──> MongoDB
+                                            │
+                                            └─> Audit sink (Mongo)
+```
+
+## 3. Configuration
+
+Configuration is resolved via `IssuerDirectoryWebServiceOptions` (section name `IssuerDirectory`). The default YAML sample lives at `etc/issuer-directory.yaml.sample` and exposes:
+
+```yaml
+IssuerDirectory:
+  telemetry:
+    minimumLogLevel: Information
+  authority:
+    enabled: true
+    issuer: https://authority.example.com/realms/stellaops
+    requireHttpsMetadata: true
+    audiences:
+      - stellaops-platform
+    readScope: issuer-directory:read
+    writeScope: issuer-directory:write
+    adminScope: issuer-directory:admin
+  tenantHeader: X-StellaOps-Tenant
+  seedCsafPublishers: true
+  csafSeedPath: data/csaf-publishers.json
+  Mongo:
+    connectionString: mongodb://localhost:27017
+    database: issuer-directory
+    issuersCollection: issuers
+    issuerKeysCollection: issuer_keys
+    auditCollection: issuer_audit
+```
+
+## 4. API Surface (v0)
+
+| Method | Route | Scope | Description |
+|--------|-------|-------|-------------|
+| `GET`  | `/issuer-directory/issuers` | `issuer-directory:read` | List tenant issuers (optionally include global seeds). |
+| `GET`  | `/issuer-directory/issuers/{id}` | `issuer-directory:read` | Fetch a single issuer by identifier. |
+| `POST` | `/issuer-directory/issuers` | `issuer-directory:write` | Create a tenant issuer. Requires `X-StellaOps-Tenant` header and optional `X-StellaOps-Reason`. |
+| `PUT`  | `/issuer-directory/issuers/{id}` | `issuer-directory:write` | Update issuer metadata/endpoints/tags. |
+| `DELETE` | `/issuer-directory/issuers/{id}` | `issuer-directory:admin` | Delete issuer (records audit). |
+| `GET`  | `/issuer-directory/issuers/{id}/keys` | `issuer-directory:read` | List issuer keys (tenant + optional `@global` seeds). |
+| `POST` | `/issuer-directory/issuers/{id}/keys` | `issuer-directory:write` | Add a signing key (validates format, deduplicates fingerprint, audits). |
+| `POST` | `/issuer-directory/issuers/{id}/keys/{keyId}/rotate` | `issuer-directory:write` | Retire an active key and create a replacement atomically. |
+| `DELETE` | `/issuer-directory/issuers/{id}/keys/{keyId}` | `issuer-directory:admin` | Revoke a key (status → revoked, audit logged). |
+
+Payloads follow the contract in `Contracts/IssuerDtos.cs` and align with domain types (`IssuerRecord`, `IssuerMetadata`, `IssuerEndpoint`).
+
+## 5. Dependencies & Reuse
+
+- `StellaOps.IssuerDirectory.Core` — domain model (`IssuerRecord`, `IssuerKeyRecord`) + application services.
+- `StellaOps.IssuerDirectory.Infrastructure` — MongoDB persistence, audit sink, seed loader.
+- `StellaOps.IssuerDirectory.WebService` — minimal API host, authentication wiring.
+- Shared libraries: `StellaOps.Configuration`, `StellaOps.Auth.ServerIntegration`.
+
+## 6. Testing
+
+- Unit coverage for issuer CRUD (`IssuerDirectoryServiceTests`) and key lifecycle (`IssuerKeyServiceTests`) in `StellaOps.IssuerDirectory.Core.Tests`.
+- Test infrastructure leverages `FakeTimeProvider` for deterministic timestamps and in-memory fakes for repository + audit sink.
+
+## 7. Observability
+
+- **Metrics.** `issuer_directory_changes_total` (labels: `tenant`, `issuer`, `action`) tracks issuer create/update/delete events; `issuer_directory_key_operations_total` (labels: `tenant`, `issuer`, `operation`, `key_type`) covers key create/rotate/revoke flows; `issuer_directory_key_validation_failures_total` (labels: `tenant`, `issuer`, `reason`) captures validation/verification failures. The WebService exports these via OpenTelemetry (`StellaOps.IssuerDirectory` meter).
+- **Logs.** Service-level `ILogger` instrumentation records structured entries for issuer CRUD, key lifecycle operations, and validation failures; audit logs remain the authoritative trail.
+
+## 8. Roadmap (next milestones)
+
+1. **Key management APIs (ISSUER-30-002)** — manage signing keys, enforce expiry, integrate with KMS.
+2. **Trust weight overrides (ISSUER-30-003)** — expose policy-friendly trust weighting with audit trails.
+3. **SDK integration (ISSUER-30-004)** — supply cached issuer metadata to VEX Lens and Excititor clients.
+4. **Observability & Ops (ISSUER-30-005/006)** — metrics, dashboards, deployment automation, offline kit.
+
+---
+
+*Document owner: Issuer Directory Guild*