git.stella-ops.org/docs/modules/registry/architecture.md

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
• Authorization decisions based on (a) Authority-issued identity token claims and (b) either persisted or static plan rules

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.

Plan administration storage

• The admin IPlanRuleStore is backed by PostgreSQL when RegistryTokenService:Postgres:ConnectionString is configured.
• Startup migrations run automatically on host startup for the registry-token schema.
• The in-memory store is restricted to Testing hosts only; live runtime composition requires the durable backend.
• The persistence schema stores plan rules plus audit history so plan CRUD, audit endpoints, and /token authorization survive process restarts.

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

Durable plan-rule persistence is configured separately under RegistryTokenService:Postgres. When Postgres persistence is configured, the host may start without any statically configured Plans; persisted plan rules become the canonical source for admin CRUD and token issuance.

References

• Operations/runbook: docs/modules/registry/operations/token-service.md