Registry Token Service architecture

Audience: Operators deploying the Registry Token Service and integrators wiring Docker/OCI clients or the plan-administration API. Source: src/Registry/StellaOps.Registry.TokenService. Related: token-service operations runbook.

The OCI registry itself is not in this module. stellaops-registry is the third-party zot registry (ghcr.io/project-zot/zot-linux-amd64:v2.1.3, devops/compose/docker-compose.stella-infra.yml:126-128) — infrastructure, not Stella Ops source. This dossier covers only stellaops-registry-token, the service that issues that registry’s bearer tokens.

Overview

Registry Token Service is the Stella Ops component that 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.

In addition to token exchange, the service exposes an authenticated Plan Administration API for managing the plan-rule catalogue (CRUD, dry-run validation, and audit history) that drives those authorization decisions.

The service surface is small and focused:

• Token exchange: GET /token (gated by the registry.token.issue policy).
• Plan administration: /api/admin/plans/* (gated by the registry.admin policy/scope).
• Operational endpoints: GET /healthz (liveness), GET /openapi/v1.json (anonymous OpenAPI document), and a build-info endpoint.

Authorization decisions are based on (a) Authority-issued identity token claims and (b) plan rules read from the durable PostgreSQL store (or, in non-durable test hosts, an explicitly registered in-memory store).

Primary responsibilities

• Validate caller identity using Authority-issued tokens (deployment profile may use bearer-only, DPoP, and/or mTLS).
• Authorize requested registry scopes against the configured/persisted plan catalogue.
• Deny issuance for revoked licences and for disabled plans.
• Mint a Docker-registry-compatible JWT with an access claim covering the permitted repository actions.
• Provide an admin API for plan CRUD, dry-run validation, and audit history (authorized via the registry.admin scope).
• Emit deterministic observability signals (metrics, traces, structured logs) and unified audit events for audits and ops.

Runtime components

Minimal API host

• Project: src/Registry/StellaOps.Registry.TokenService
• Router service name: registry-token (registered with the Stella Router microservice integration).
• Endpoints:
  • GET /token (authorized via registry.token.issue)
  • GET /api/admin/plans and related plan-admin routes (authorized via registry.admin)
  • GET /healthz (unauthenticated liveness)
  • GET /openapi/v1.json (anonymous OpenAPI discovery document for the gateway aggregator)
  • Build-info endpoint (image provenance for the operator verify aggregator)

Cross-cutting integrations

• Air-gap egress policy (AddAirGapEgressPolicy) consistent with the offline-first posture.
• Tenant services + tenant middleware (AddStellaOpsTenantServices / UseStellaOpsTenantMiddleware).
• Localization + embedded translation bundles (AddStellaOpsLocalization / AddTranslationBundle); admin error messages are localized via translation keys (e.g. registry.error.plan_not_found).
• CORS (AddStellaOpsCors).
• Unified audit emission to the Timeline service (AddAuditEmission).
• OpenTelemetry metrics, runtime instrumentation, and ASP.NET Core / HttpClient tracing (AddStellaOpsTelemetry).

Auth integration

• Resource server validation is configured from RegistryTokenService:Authority (issuer, optional MetadataAddress, RequireHttpsMetadata, audiences). The Authority issuer must be an absolute URI; HTTPS is required unless the issuer is loopback or RequireHttpsMetadata is disabled.
• Authorization policies:
  • registry.token.issue — required to call GET /token. Required scopes default to registry.token.issue (configurable via RegistryTokenService:Authority:RequiredScopes).
  • registry.admin — required to call the plan-admin endpoints. Backed by the StellaOpsScopes.RegistryAdmin (registry.admin) scope.
• Note: registry.admin is a defined constant in StellaOps.Auth.Abstractions/StellaOpsScopes.cs; registry.token.issue is used as a literal scope string in this service and is not (yet) a named constant in that catalogue.

Plan registry (token authorization rules)

• The caller’s plan is read from the stellaops:plan claim (fallback: configured DefaultPlan).
• Licence revocation uses the stellaops:license claim and configured RevokedLicenses (normalized lower-case).
• The plan registry resolves the plan either from the durable IPlanRuleStore (canonical in production) or from the statically configured Plans list when no store is wired (test/in-memory hosts only).
• A resolved plan that is enabled = false is rejected (plan_disabled); an unknown plan name is rejected (plan_unknown). The enabled flag only exists on durable (PostgresPlanRuleStore) plan rules — the statically configured PlanRule model (RegistryTokenServiceOptions.PlanRule) has no enabled field, so plan_disabled can only arise on the durable path.
• Plan rules match repositories by wildcard pattern (* → .*, anchored, case-insensitive) and authorize a request only if every requested action is a subset of the matched repository rule’s allowed actions.

Plan administration API (/api/admin/plans)

• All routes require the registry.admin policy. Routes:
  • GET /api/admin/plans — list plan rules (ordered by name).
  • GET /api/admin/plans/{planId} — get a plan by ID (404 if missing).
  • POST /api/admin/plans — create a plan (201; 400 invalid; 409 name conflict).
  • PUT /api/admin/plans/{planId} — update a plan; requires version for optimistic concurrency (200; 400; 404; 409 version/name conflict).
  • DELETE /api/admin/plans/{planId} — delete a plan (204; 404).
  • POST /api/admin/plans/validate — dry-run validation; optionally evaluates testScopes against the rules without persisting.
  • GET /api/admin/plans/audit — paginated audit history (optional planId filter; page, pageSize clamped to 1…100).
• The actor recorded in audit entries is derived from the caller’s nameidentifier/sub/name claims.
• PlanValidator enforces: required plan name (≤128 chars), valid repository patterns (rejects **, control chars, non-compiling regex), valid actions (pull, push, delete, *), positive rate-limit values, and non-empty allowlist entries; it surfaces warnings for empty repository lists and overlapping patterns.

Plan administration storage

• The admin IPlanRuleStore is backed by PostgreSQL (PostgresPlanRuleStore) when RegistryTokenService:Postgres:ConnectionString is configured.
• Default schema is registry_token (override via RegistryTokenService:Postgres:SchemaName). Tables:
  • plan_rules — id, name, description, enabled, repositories/allowlist/rate_limit (jsonb), timestamps, and an integer version for optimistic concurrency. A case-insensitive unique index enforces unique plan names.
  • plan_audit — append-only change history (action, actor, timestamp, summary, previous/new version).
• Startup migrations run automatically via AddStartupMigrations against the registry_token schema. The migration SQL (Migrations/001_initial_schema.sql) is shipped as an embedded resource, so a fresh database converges on startup without manual scripts.
• The production TokenService assembly does not provide an in-memory IPlanRuleStore; tests that need one register the test-local store explicitly through ConfigureTestServices. With no Postgres connection string and outside the Testing environment, the host fails fast at startup (durable persistence is mandatory in live runtime).
• 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.

Token issuer

• Tokens are signed with an RSA private key (algorithm RS256 / SecurityAlgorithms.RsaSha256) loaded from RegistryTokenService:Signing:KeyPath. The loader (SigningKeyLoader) picks PFX when the path extension is .pfx (optional KeyPassword; requires an RSA private key) and PEM otherwise (RSA.ImportFromPem).
• iss is Signing:Issuer. aud defaults to the requested registry service value unless Signing:Audience is set.
• kid resolution: an explicit Signing:KeyId always wins; otherwise the PFX path defaults kid to the certificate thumbprint, while the PEM path emits no kid.
• Token lifetime (Signing:Lifetime) must be greater than zero and at most 1h (default 5m); values outside this range fail validation at startup.

Observability

• OpenTelemetry metrics (meter StellaOps.Registry.TokenService):
  • registry_token_issued_total{plan=...}
  • registry_token_rejected_total{reason=...}
• OpenTelemetry tracing for ASP.NET Core and outbound HTTP, plus runtime instrumentation.
• Structured logs via Serilog request logging.
• Unified audit events emitted to the Timeline service.

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. The scope query may repeat or be space-delimited (OAuth2 style); each scope is repository:<name>:<comma-separated-actions>.
4. Service validates:
   • service is present (and is allow-listed if Registry:AllowedServices is configured)
   • requested scopes parse correctly (type must be repository; at most 3 colon-separated segments; missing actions default to pull)
   • at least one scope is requested
   • 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, no scopes requested).
• 403 for authorization failures — the requested service not allow-listed, or IssueTokenAsync denial with reason license_revoked, plan_unknown, plan_disabled, or scope_not_permitted.
• Note: PlanRegistry.AuthorizeAsync also defines a no_scopes_requested reason, but the /token endpoint short-circuits empty scope lists with a 400 before the issuer runs, so that reason is unreachable over HTTP (it can surface only via direct library use of IssueTokenAsync/AuthorizeAsync).

Token shape (Docker registry compatible)

The JWT header carries alg = RS256 and, when a key id is resolved (see Token issuer), a kid.

The issued JWT payload includes registered claims iss, aud, nbf, iat, exp, plus:

• sub: subject derived from nameidentifier/client_id/sub claims (falls back to anonymous)
• jti: per-token unique identifier
• service: the requested registry service
• access: array of { type, name, actions[] } entries (type is repository)
• Optional: stellaops:license passthrough claim (for downstream correlation), present only when the caller carries it

The GET /token HTTP response is a JSON envelope:

{
  "token": "<jwt>",
  "expires_in": 300,
  "issued_at": "<ISO-8601 UTC>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Configuration

Configuration is loaded from:

• etc/registry-token.yaml (optional; resolved relative to the content root as ../etc/registry-token.yaml)
• environment variables prefixed with REGISTRY_TOKEN_

Key sections are defined by RegistryTokenServiceOptions (root section RegistryTokenService):

• Authority (Issuer, optional MetadataAddress, RequireHttpsMetadata, Audiences, RequiredScopes)
• Signing (Issuer, optional Audience, KeyPath, optional KeyPassword, optional KeyId, Lifetime)
• Registry (Realm, allow-listed AllowedServices)
• Plans, DefaultPlan, RevokedLicenses

Durable plan-rule persistence is configured separately under RegistryTokenService:Postgres (at minimum ConnectionString; optional SchemaName, defaulting to registry_token). 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. Without a connection string, the host requires at least one statically configured plan and refuses to start in non-test environments.

Roadmap / not-yet-implemented

• RateLimitDto (maxRequests, windowSeconds) is part of the admin plan model and persisted in plan_rules, but it is not yet enforced at the GET /token issuance path. Treat it as advisory metadata until enforcement lands.
• Plan Allowlist (explicit client identifiers) is stored and validated but is not consulted during /token authorization, which keys on the stellaops:plan/stellaops:license claims.

References

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