docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,34 +1,31 @@
|
||||
# StellaOps Registry Token Service
|
||||
|
||||
The registry module issues scoped pull tokens for mirrored container registries while enforcing plan and licence constraints.
|
||||
|
||||
## Responsibilities
|
||||
- Validate Authority-issued OpToks and tenant scopes before issuance.
|
||||
- Mint time-bound registry tokens and record issuance ledgers.
|
||||
- Expose revocation and audit endpoints for security teams.
|
||||
- Integrate with Offline Kit for deterministic token manifests.
|
||||
|
||||
## Key components
|
||||
- `StellaOps.Registry.TokenService` minimal API host.
|
||||
- Mongo-backed issuance ledger.
|
||||
- Tests under `src/Registry/__Tests`.
|
||||
|
||||
## Integrations & dependencies
|
||||
- Authority for identity & scope verification.
|
||||
- Export Center/Offline Kit for distribution.
|
||||
- DevOps runbooks for deployment and rotation.
|
||||
|
||||
## Operational notes
|
||||
- Operational guide at ./operations/token-service.md.
|
||||
- Telemetry dashboards pending (see ../../TASKS.md).
|
||||
|
||||
## Related resources
|
||||
- ./operations/token-service.md
|
||||
|
||||
## Backlog references
|
||||
- DEVOPS-REGISTRY items in ../../TASKS.md (future work).
|
||||
- Registry automation stories tracked in src/Registry/TASKS.md if present.
|
||||
|
||||
## Epic alignment
|
||||
- **Epic 10 – Export Center:** provide signed, auditable registry token bundles for mirror distribution.
|
||||
- **Epic 14 – Identity & Tenancy:** enforce tenant-aware scopes, PoE alignment, and revocation policies.
|
||||
# StellaOps Registry Token Service
|
||||
|
||||
Registry Token Service issues short-lived Docker registry bearer tokens for private or mirrored registries.
|
||||
It exchanges an Authority-issued access token for a registry-compatible JWT after enforcing plan/licence constraints.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Validate Authority-issued caller identity and required scopes (default `registry.token.issue`).
|
||||
- Authorize requested repository scopes against a local plan catalogue (`stellaops:plan` claim + configured rules).
|
||||
- Block issuance for revoked licences (`stellaops:license` claim + configured deny list).
|
||||
- Mint registry tokens with a bounded lifetime (default 5 minutes) signed by a local RSA key.
|
||||
|
||||
## Key endpoints
|
||||
|
||||
- `GET /token` - Docker registry token exchange endpoint.
|
||||
- `GET /healthz` - liveness probe.
|
||||
|
||||
## Code locations
|
||||
|
||||
- Service: `src/Registry/StellaOps.Registry.TokenService`
|
||||
- Tests: `src/Registry/__Tests/StellaOps.Registry.TokenService.Tests`
|
||||
|
||||
## Configuration
|
||||
|
||||
- File: `etc/registry-token.yaml`
|
||||
- Environment variables: `REGISTRY_TOKEN_*`
|
||||
|
||||
## Related docs
|
||||
|
||||
- Architecture: `docs/modules/registry/architecture.md`
|
||||
- Operations: `docs/modules/registry/operations/token-service.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`
|
||||
|
||||
Reference in New Issue
Block a user