docs consolidation

docs/modules/registry/architecture.md

@@ -1,7 +1,86 @@
-# Registry Token Service architecture
-
-> Grounded in the Export Center and Authority module guides, which describe token issuance, provenance, tenant isolation, and offline packaging expectations.
-
-This placeholder summarises the planned architecture for Registry Token Service. Consolidate design details from implementation plans and upcoming epics before coding.
-
-Refer to the module README and implementation plan for immediate context, and update this document once component boundaries and data flows are finalised.
+# Registry Token Service architecture
+
+## Overview
+
+Registry Token Service issues short-lived Docker registry bearer tokens for private or mirrored registries.
+It is designed for offline/self-hosted operation and enforces plan/licence constraints before minting any registry token.
+
+The service is intentionally small:
+- One HTTP endpoint: `GET /token`
+- Stateless authorization decisions based on (a) Authority-issued identity token claims and (b) local configuration
+
+## Primary responsibilities
+
+- Validate caller identity using Authority-issued tokens (deployment profile may use bearer-only, DPoP, and/or mTLS).
+- Authorize requested registry scopes against a configured plan catalogue.
+- Deny issuance for revoked licences.
+- Mint a Docker-registry-compatible JWT with an `access` claim covering the permitted repository actions.
+- Emit deterministic observability signals (metrics + structured logs) for audits and ops.
+
+## Runtime components
+
+**Minimal API host**
+- Project: `src/Registry/StellaOps.Registry.TokenService`
+- Endpoints:
+  - `GET /token` (authorized)
+  - `GET /healthz` (unauthenticated liveness)
+
+**Auth integration**
+- Resource server validation is configured from `RegistryTokenService:Authority`.
+- Authorization policy name: `registry.token.issue`
+- Required scopes default to `registry.token.issue` (configurable via `RegistryTokenService:Authority:RequiredScopes`).
+
+**Plan registry (authorization rules)**
+- The caller's plan is read from `stellaops:plan` claim (fallback: configured `DefaultPlan`).
+- Licence revocation uses `stellaops:license` claim and configured `RevokedLicenses`.
+- Plan rules match repositories by wildcard pattern (`*`) and validate requested actions (`pull`, `push`, etc.) as a subset of allowed actions.
+
+**Token issuer**
+- Tokens are signed with an RSA private key loaded from `RegistryTokenService:Signing:KeyPath` (PEM or PFX).
+- `aud` defaults to the requested registry `service` value unless `Signing:Audience` is configured.
+- Token lifetime is configured and bounded (1s..1h, default 5m).
+
+**Observability**
+- OpenTelemetry metrics:
+  - `registry_token_issued_total{plan=...}`
+  - `registry_token_rejected_total{reason=...}`
+- Structured logs via Serilog request logging.
+
+## Request flow
+
+1. Docker/OCI client receives a `401` from the registry with a `WWW-Authenticate: Bearer realm=...,service=...,scope=repository:...` challenge.
+2. Client obtains an Authority token with the `registry.token.issue` scope (and any required sender constraints for the deployment).
+3. Client calls `GET /token?service=<service>&scope=repository:<repo>:<actions>` on Registry Token Service.
+4. Service validates:
+   - `service` is present (and is allow-listed if `AllowedServices` is configured)
+   - requested scopes parse correctly
+   - caller plan/licence claims authorize all requested repository actions
+5. Service returns a JSON response containing the signed registry token.
+
+Denial paths:
+- `400` for malformed requests (`service` missing, invalid `scope` query).
+- `403` for authorization failures (plan/licence/policy denies).
+
+## Token shape (Docker registry compatible)
+
+The issued JWT includes:
+- `sub`: subject derived from `nameidentifier`/`client_id`/`sub` claims
+- `service`: the requested registry service
+- `access`: array of `{ type, name, actions[] }` entries (type is `repository`)
+- Optional: `stellaops:license` passthrough claim (for downstream correlation)
+
+## Configuration
+
+Configuration is loaded from:
+- `etc/registry-token.yaml` (optional)
+- environment variables prefixed with `REGISTRY_TOKEN_`
+
+Key sections are defined by `RegistryTokenServiceOptions`:
+- `Authority` (issuer/metadata, audiences, required scopes)
+- `Signing` (issuer, key, lifetime, optional audience/kid)
+- `Registry` (realm, allow-listed `service` values)
+- `Plans`, `DefaultPlan`, `RevokedLicenses`
+
+## References
+
+- Operations/runbook: `docs/modules/registry/operations/token-service.md`