StellaOps Registry Token Service

Audience: operators configuring registry access for scans and deployments, and integrators that pull from private or mirrored registries through Stella Ops.

Scope note — src/Registry/ is the token service, not a registry. The stellaops-registry container in the compose stack is third-party software, not Stella Ops source: it is the zot OCI registry (ghcr.io/project-zot/zot-linux-amd64:v2.1.3, devops/compose/docker-compose.stella-infra.yml:126-128, config devops/compose/zot-config.json). This module only mints the bearer tokens that registry accepts; it never stores or serves images. The token-service container is stellaops-registry-token (its autogenerated OpenAPI reference lives in registry-token/).

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 and licence constraints, so registry credentials never need to be distributed to callers.

Responsibilities

• Validate Authority-issued caller identity and required scopes (default registry.token.issue; configurable via Authority.RequiredScopes).
• Authorize requested repository scopes against a plan catalogue (stellaops:plan claim, falling back to the configured DefaultPlan, evaluated against plan/repository rules).
• Block issuance for revoked licences (stellaops:license claim + configured deny list) and for disabled or unknown plans.
• Mint registry tokens with a bounded lifetime (default 5 minutes, capped at 1 hour) signed by a local RSA key loaded from PEM or PFX.

Key endpoints

• GET /token - Docker registry token exchange endpoint (authorization policy registry.token.issue). Requires a service query parameter and one or more scope parameters of the form repository:<name>:<actions> (space-delimited per OAuth2; actions comma-separated, defaulting to pull). On success returns JSON { token, expires_in, issued_at, issued_token_type } where issued_token_type is urn:ietf:params:oauth:token-type:access_token. Returns RFC7807 problem responses: 400 for a missing/invalid service, invalid scope, or no scopes; 403 when the service is not in Registry.AllowedServices or when plan/licence authorization fails.
• /api/admin/plans - plan-rule administration group (authorization policy registry.admin):
  • GET /api/admin/plans - list all plan rules ordered by name.
  • GET /api/admin/plans/{planId} - get a plan rule by ID (404 if absent).
  • POST /api/admin/plans - create a plan rule (201 with Location; 400 on validation failure; 409 on name conflict).
  • PUT /api/admin/plans/{planId} - update a plan rule; requires version for optimistic concurrency (200; 400/404; 409 on version or name conflict).
  • DELETE /api/admin/plans/{planId} - delete a plan rule (204; 404 if absent).
  • POST /api/admin/plans/validate - dry-run validation of a plan rule without saving; optionally evaluates supplied testScopes.
  • GET /api/admin/plans/audit - paginated plan-change audit history (optional planId, page, pageSize; pageSize clamped to 1-100, page floored to 1).
• GET /healthz - liveness probe (health check self).
• GET /openapi/v1.json - anonymous OpenAPI discovery document (mapped via MapOpenApi().AllowAnonymous() so the gateway aggregator can read it without a tenant header).
• Build-info endpoint - image/provenance metadata for the operator verify aggregator (mapped via MapBuildInfoEndpoint, module name registry-token).

Note: registry.admin is defined in the canonical Authority scope catalogue (StellaOpsScopes.RegistryAdmin). registry.token.issue is enforced as an authorization-policy scope string but is not (yet) declared as a constant in StellaOpsScopes; it is the hardcoded default for Authority.RequiredScopes.

Code locations

• Service host: src/Registry/StellaOps.Registry.TokenService/Program.cs
• Token issuer: src/Registry/StellaOps.Registry.TokenService/RegistryTokenIssuer.cs
• Plan evaluation: src/Registry/StellaOps.Registry.TokenService/PlanRegistry.cs
• Scope parsing: src/Registry/StellaOps.Registry.TokenService/RegistryScopeParser.cs
• Options: src/Registry/StellaOps.Registry.TokenService/RegistryTokenServiceOptions.cs
• Plan admin API: src/Registry/StellaOps.Registry.TokenService/Admin/PlanAdminEndpoints.cs, Admin/AdminModels.cs, Admin/PlanValidator.cs, Admin/IPlanRuleStore.cs
• Persistence: src/Registry/StellaOps.Registry.TokenService/Admin/Persistence/ (PostgresPlanRuleStore.cs, RegistryTokenPlanRuleDataSource.cs, RegistryTokenPersistenceExtensions.cs)
• Migrations: src/Registry/StellaOps.Registry.TokenService/Migrations/001_initial_schema.sql
• Metrics: src/Registry/StellaOps.Registry.TokenService/Observability/RegistryTokenMetrics.cs
• Tests: src/Registry/__Tests/StellaOps.Registry.TokenService.Tests

Configuration

• File: etc/registry-token.yaml (loaded from ../etc/registry-token.yaml relative to the content root, optional, reload-on-change).
• Configuration section: RegistryTokenService (YAML root key registryTokenService).
• Environment variable prefix: REGISTRY_TOKEN_.
• Key options (RegistryTokenServiceOptions):
  • Authority - Issuer, MetadataAddress, RequireHttpsMetadata (default true), Audiences, RequiredScopes (default ["registry.token.issue"]).
  • Signing - Issuer, optional Audience (defaults to the requested registry service), KeyPath (PEM/PFX), KeyPassword, optional KeyId (kid), Lifetime (default 00:05:00, must be between 1 second and 1 hour).
  • Registry - Realm (absolute URI), AllowedServices (empty list permits any service).
  • Plans - plan catalogue (Name + Repositories, each with Pattern supporting * wildcard and Actions defaulting to pull).
  • RevokedLicenses - deny list of revoked licence/customer IDs (normalized lowercase).
  • DefaultPlan - plan used when no stellaops:plan claim is present.
  • Postgres - durable plan-rule persistence (ConnectionString, SchemaName, etc.). When a connection string is supplied, plans are served from PostgreSQL and the in-config Plans list is not required; when absent (outside the Testing environment) startup fails unless static Plans are provided.

Persistence

• When RegistryTokenService:Postgres:ConnectionString is set, plan rules and audit history are stored in PostgreSQL (default schema registry_token).
• Auto-migration runs on startup via AddStartupMigrations (module Registry.TokenService); the migration SQL is embedded in the service assembly. Forward-only per ADR-004.
• Tables (Migrations/001_initial_schema.sql):
  • plan_rules (id, name, description, enabled, repositories jsonb, allowlist jsonb, rate_limit jsonb, created_at, modified_at, version), with a unique index on lower(name).
  • plan_audit (audit_seq bigserial, plan_id, action, actor, timestamp, summary, previous_version, new_version).
• Without a connection string, the service runs with the static in-config plan catalogue (the Testing environment supplies an IPlanRuleStore explicitly).

Observability

• Audit events are emitted to the Timeline service via unified audit emission (AddAuditEmission).
• OpenTelemetry metrics (meter StellaOps.Registry.TokenService):
  • registry_token_issued_total - counter of issued tokens, tagged by plan.
  • registry_token_rejected_total - counter of rejected requests, tagged by reason (e.g. license_revoked, plan_unknown, plan_disabled, scope_not_permitted, no_scopes_requested).
• ASP.NET Core and HttpClient tracing instrumentation plus runtime metrics are registered via AddStellaOpsTelemetry.

Implementation Status

Current Objectives

• Maintain deterministic behaviour and offline parity across releases
• Keep documentation, telemetry, and runbooks aligned with latest sprint outcomes

Epic Milestones

• Epic 10 – Export Center: signed registry token bundles for mirror/Offline Kit workflows (planned)
• Epic 14 – Identity & Tenancy: tenant-aware scope validation, revocation, audit trails (planned)

Core Capabilities

• Docker registry token exchange with Authority validation (resource-server JWT auth)
• Plan/repository scope enforcement via the stellaops:plan claim (or DefaultPlan) against configured or PostgreSQL-backed plan rules
• Short-lived JWT tokens (default 5 minutes) signed by a local RSA key; emitted access claim mirrors the requested repository scopes, and the stellaops:license claim is propagated when present
• Revocation support via the configured deny list matched against the stellaops:license claim
• Plan-rule admin API (CRUD, dry-run validate, audit history) backed by PostgreSQL with optimistic-concurrency versioning

Technical Decisions

• Token lifetime bounded to 5 minutes to minimize exposure window
• Local RSA key signing avoids external dependencies
• Plan catalogue enforcement ensures license compliance
• Integration with Authority for caller identity and scope validation

Coordination Approach

• Review AGENTS.mdbefore starting new work.
• Sync with cross-cutting teams via the sprint files under ../../implplan/SPRINT_*.md.
• Track follow-ups in src/Registry/TASKS.md.

Related docs

• Architecture — full design, token-exchange flow, and persistence detail.
• Operations: Token Service — deployment, key management, and runbooks.