StellaOps Registry

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 one two-role service family. registry-web is the Stella-owned distribution data plane; registry-token is its bearer issuer and plan-admin role. They share the family database but no source edge: the contract crosses as a signed registry token. The Stella Registry runs on its own service name, while registry.stella-ops.local remains on the interim zot until SR-6 completes the alias cutover. The token service’s generated OpenAPI reference lives in registry-token/.

Direction (2026-08-03, ADR-041): the owner ruled that a Stella-owned product registry — the Stella Registry — is built in this family (registry-web data plane; this token service becomes its auth plane), and zot is demoted to demo-integration material. The stella-infra zot remains the interim plugin-publish target until the ADR-041 R6 cutover. See the registry topology truth doc for every registry-shaped surface and its single role, and docs/implplan/SPRINT_20260803_004_Registry_stella_registry_service_program.md for program state.

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. An Authority-issued stellaops:plan assignment is authoritative; only an absent claim falls back to configured DefaultPlan, while an unknown claimed plan returns plan_unknown without downgrade.
• 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: both registry.admin and registry.token.issue are defined in the canonical Authority scope catalogue (StellaOpsScopes.RegistryAdmin and StellaOpsScopes.RegistryTokenIssue).

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, 002_reserve_plan_allowlist.sql
• Metrics: src/Registry/StellaOps.Registry.TokenService/Observability/RegistryTokenMetrics.cs
• Tests: src/Registry/__Tests/StellaOps.Registry.TokenService.Tests

Configuration

• File: etc/registry-token.yaml (the relative location is resolved to an absolute path before loading; optional, no reload-on-change; deployment environment variables are re-applied afterwards and win).
• 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); migration SQL is embedded in the service assembly. Forward-only per ADR-004.
• Tables (baseline 001_initial_schema.sql, compatibility contract 002_reserve_plan_allowlist.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). The physical allowlist column is reserved and unused: create/import write [], update cannot write it, it remains read-only in responses, and authorization never consults it.
  • plan_audit (audit_seq bigserial, plan_id, action, actor, timestamp, summary, previous_version, new_version).
• On an empty durable store, the first-boot catalogue importer copies the shipped plan catalogue once and records a durable marker. Later file edits never overwrite operator-managed rows; token authorization also never falls back from PostgreSQL to YAML.
• 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.md before 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.