StellaOps Registry

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section.

Service wiring (image, database and role, compose profile, bundle presence) is generated in the service inventory; this dossier does not restate it.

Audience: operators running the Stella Registry and its token service, and integrators that pull from or publish to it through Docker/OCI clients.

src/Registry/ is the Stella Registry, the product’s own OCI registry. It is one service family with two deployables that share the family database stellaops_registry but no source edge; the contract between them is a signed registry token verified against a certificate.

Both deployables ship in the release bundle (devops/release/bundle/docker-compose.yml). The generated OpenAPI reference for the token service lives in registry-token/. Every registry-shaped surface in an estate and its single role is listed in the registry topology; the direction is recorded in ADR-041.

Responsibilities

• registry-web serves the OCI distribution-spec surface, validates registry bearer tokens (issuer, service audience, access claim) against the token service’s public X.509 certificate, stores metadata in schema registry and content in its own object-store bucket, and reclaims expired upload sessions.
• registry-token validates the caller’s Authority token and required scope (host floor registry.token.issue; configurable through Authority:RequiredScopes), resolves the caller’s plan, and mints an RS256 registry JWT whose access claim carries only the permitted repository actions.
• An Authority-issued stellaops:plan claim is authoritative. Only an absent or blank claim falls back to DefaultPlan; an unknown claimed plan is refused with plan_unknown and never downgraded.
• Issuance is refused for revoked licences (stellaops:license claim matched against RevokedLicenses) and for disabled or unknown plans.
• Anonymous issuance is off by default. It is available only when AnonymousPlan names a plan, and an anonymous token can carry only pull.

Key endpoints

registry-token

• GET /token - Docker registry token exchange (endpoint is AllowAnonymous; the registry.token.issue policy is evaluated by hand for callers that send an Authorization header). Requires a service query parameter and one or more scope parameters of the form repository:<name>:<actions> (space-delimited or repeated; actions comma-separated; a scope without actions requests pull). Returns JSON { token, expires_in, issued_at, issued_token_type }. Problem responses: 400 for a missing service, an invalid scope or no scopes; 401 for invalid credentials, or for an anonymous caller that cannot be served; 403 when the service is not in Registry:AllowedServices or plan/licence authorization fails; 503 when the host is not provisioned for issuance.
• /api/admin/plans - plan-rule administration (policy registry.admin): list, get by id, create, update (optimistic concurrency on version), delete, POST /validate (dry run with optional testScopes) and GET /audit (paginated history).
• GET /healthz, GET /openapi/v1.json (anonymous), and the build-info endpoint (module name registry-token).

registry-web

• /v2/ distribution-spec read and write routes (GET/HEAD blobs and manifests, uploads, manifest PUT, tag listing, referrers). DELETE answers 405 UNSUPPORTED: deletion is GC policy.
• Repository names under registries/<slug>/ (for example /v2/registries/<slug>/<repo>/manifests/<digest>) are the read-only pull-through facade over a tenant’s integrated registry, off unless Registry:Facade:* is configured.
• GET /healthz, GET /readyz, the build-info endpoint (module name registry-web), and GET /doctor/registry-web/checks (Authority scope ops.health).

Both registry.admin and registry.token.issue are defined in the Authority scope catalogue (StellaOpsScopes.RegistryAdmin, StellaOpsScopes.RegistryTokenIssue).

Configuration (registry-token)

• Plan catalogue file: etc/registry-token.yaml, resolved to an absolute path next to the content root (../etc/registry-token.yaml), optional, no reload-on-change. The unprefixed environment provider is re-applied after the file, so deployment RegistryTokenService__* variables override it. REGISTRY_TOKEN_-prefixed variables are also read.
• Configuration section RegistryTokenService (RegistryTokenServiceOptions):
  • Authority - Issuer (absolute URI; HTTPS unless loopback or RequireHttpsMetadata=false), MetadataAddress, RequireHttpsMetadata (default true), Audiences, RequiredScopes (default empty; the host then applies registry.token.issue).
  • Signing - Issuer, optional Audience (defaults to the requested service), KeyPath (operator-supplied PEM or PFX; no inline key, fails closed when missing), KeyPassword, optional KeyId, Lifetime (default 00:05:00, between 1 second and 1 hour).
  • Registry - Realm (absolute URI, required), AllowedServices (empty permits any service).
  • Plans - static catalogue: Name and Repositories (Pattern with * wildcard, Actions). Actions have no default: a repository rule without actions fails validation.
  • DefaultPlan, AnonymousPlan (pull-only; unset by default), RevokedLicenses.
  • Postgres - ConnectionString (required outside the Testing environment), optional SchemaName (default registry_token).
• Deployments map STELLAOPS_POSTGRES_REGISTRY_CONNECTION into RegistryTokenService__Postgres__ConnectionString.

registry-web configuration (Registry:Bearer:*, Registry:Storage:*, Registry:Push:*, Registry:Facade:*) is described in architecture.md.

Persistence

• Database stellaops_registry, owned by the family and resolved from STELLAOPS_POSTGRES_REGISTRY_CONNECTION (no shared-connection fallback).
• registry-token owns schema registry_token (plan_rules, plan_audit), migrated on startup through AddStartupMigrations (module Registry.TokenService) from the SQL embedded in StellaOps.Registry.Token.Persistence. The physical plan_rules.allowlist column is reserved and never consulted for authorization.
• registry-web owns schema registry (repositories, tags, manifests, blobs, manifest references, upload sessions, GC audit), migrated on startup from StellaOps.Registry.Persistence.
• On an empty durable store, the first-boot catalogue importer copies the shipped plan catalogue once and records a marker. Later file edits never overwrite operator-managed rows, and token authorization never falls back from PostgreSQL to YAML.

Observability

• Meter StellaOps.Registry.TokenService: registry_token_issued_total (tag plan) and registry_token_rejected_total (tag reason, for example license_revoked, plan_unknown, plan_disabled, scope_not_permitted, anonymous_disabled).
• Token service audit events go to Timeline through AddAuditEmission; plan changes are recorded in plan_audit. There is no per-token issuance audit table.
• registry-web Doctor check doctor.registry.retention.upload-session-backlog and the owned-state measurement described in content-storage-measurement.

Not implemented

• rateLimit (maxRequests, windowSeconds) is stored with plan rules but not enforced at GET /token.

Related docs

• Architecture - both roles, token exchange, plan evaluation, data plane, facade, GC, and the Evidence table.
• Operations: token service - plan catalogue, key management, enablement and verification.
• Registry topology - every registry-shaped surface and its role.
• Content storage measurement.