consolidation of some of the modules, localization fixes, product advisories work, qa work
This commit is contained in:
master
@@ -1,13 +1,19 @@
|
||||
# IssuerDirectory
|
||||
|
||||
**Status:** Implemented
|
||||
**Source:** `src/IssuerDirectory/`
|
||||
**Owner:** VEX Guild
|
||||
**Status:** Implemented (source relocated by Sprint 216)
|
||||
**Source:** `src/Authority/StellaOps.IssuerDirectory/` (previously `src/IssuerDirectory/`)
|
||||
**Owner:** Authority domain (Identity & Trust)
|
||||
|
||||
## Purpose
|
||||
|
||||
IssuerDirectory maintains a trust registry of CSAF publishers and VEX statement issuers. Provides discovery, validation, and trust scoring for upstream vulnerability advisories and VEX statements.
|
||||
|
||||
## Domain ownership
|
||||
|
||||
As of Sprint 216, IssuerDirectory source is owned by the Authority domain. The runtime service identity, container, and database schema remain independent. Schema isolation from AuthorityDbContext is a deliberate security feature.
|
||||
|
||||
See `docs/modules/authority/architecture.md` (sections 21.1--21.4) for schema ownership and the no-merge ADR.
|
||||
|
||||
## Components
|
||||
|
||||
**Services:**
|
||||
@@ -34,11 +40,8 @@ Key settings:
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- Architecture: `./architecture.md`
|
||||
- Architecture: `../authority/architecture.md` (sections 21.1--21.4)
|
||||
- Archived original: `docs-archived/modules/issuer-directory/`
|
||||
- Concelier: `../concelier/`
|
||||
- VexHub: `../vexhub/`
|
||||
- VexLens: `../vex-lens/`
|
||||
|
||||
## Current Status
|
||||
|
||||
Implemented with CSAF publisher discovery and validation. Supports issuer metadata storage and trust registry queries. Integrated with VEX ingestion pipeline.
|
||||
|
||||
@@ -1,105 +1,19 @@
|
||||
# Issuer Directory Architecture
|
||||
# Issuer Directory Architecture -- Redirect
|
||||
|
||||
> **Status:** Initial service scaffold (Sprint 100 – Identity & Signing)
|
||||
> **Moved by Sprint 216 (2026-03-04).** IssuerDirectory is now owned by the Authority domain.
|
||||
|
||||
## 1. Purpose
|
||||
## Current documentation
|
||||
|
||||
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.
|
||||
- **Architecture and schema ownership:** `docs/modules/authority/architecture.md` (sections 21.1--21.4)
|
||||
- **Source code:** `src/Authority/StellaOps.IssuerDirectory/`
|
||||
- **Client library:** `src/Authority/__Libraries/StellaOps.IssuerDirectory.Client/`
|
||||
- **Persistence:** `src/Authority/__Libraries/StellaOps.IssuerDirectory.Persistence/`
|
||||
|
||||
## 2. Runtime Topology
|
||||
## Archived original
|
||||
|
||||
- **Service name:** `stellaops/issuer-directory`
|
||||
- **Framework:** ASP.NET Core minimal APIs (`net10.0`)
|
||||
- **Persistence:** PostgreSQL (`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.
|
||||
- `docs-archived/modules/issuer-directory/architecture.md`
|
||||
|
||||
```
|
||||
Clients ──> Authority (DPoP/JWT) ──> IssuerDirectory WebService ──> PostgreSQL
|
||||
│
|
||||
└─> Audit sink (PostgreSQL)
|
||||
```
|
||||
## Runtime identity
|
||||
|
||||
## 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
|
||||
Postgres:
|
||||
connectionString: Host=localhost;Port=5432;Database=issuer_directory;Username=stellaops;Password=secret
|
||||
schema: issuer_directory
|
||||
issuersTable: issuers
|
||||
issuerKeysTable: issuer_keys
|
||||
auditTable: 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). |
|
||||
| `GET` | `/issuer-directory/issuers/{id}/trust` | `issuer-directory:read` | Retrieve tenant/global trust overrides with effective weight. |
|
||||
| `PUT` | `/issuer-directory/issuers/{id}/trust` | `issuer-directory:write` | Set or update a tenant trust override; reason may be supplied in body/header. |
|
||||
| `DELETE` | `/issuer-directory/issuers/{id}/trust` | `issuer-directory:admin` | Remove a tenant trust override (falls back to global/default weight). |
|
||||
|
||||
All write/delete operations accept an optional audit reason header (`X-StellaOps-Reason`) which is persisted alongside trust override changes.
|
||||
|
||||
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` — PostgreSQL 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.
|
||||
|
||||
## 9. Operations & runbooks
|
||||
- [Deployment guide](operations/deployment.md)
|
||||
- [Backup & restore](operations/backup-restore.md)
|
||||
- [Offline kit notes](operations/offline-kit.md)
|
||||
|
||||
---
|
||||
|
||||
*Document owner: Issuer Directory Guild*
|
||||
The IssuerDirectory service retains its own container, hostname, and endpoints.
|
||||
Schema isolation from AuthorityDbContext is a deliberate security feature (see ADR in Authority architecture).
|
||||
|
||||
Reference in New Issue
Block a user