Registry — Architecture

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.

Audience: operators deploying the Stella Registry and integrators wiring Docker/OCI clients or the plan-administration API. Source: src/Registry/. Related: token-service operations runbook, registry topology.

Overview

src/Registry/ is a two-role service family:

• registry-token (src/Registry/StellaOps.Registry.TokenService) issues the registry bearer tokens and hosts the plan-administration API. It is described in the first half of this file.
• registry-web (src/Registry/StellaOps.Registry.WebService) is the Stella Registry data plane, described under The data plane (registry-web).

The two roles share database stellaops_registry (separate schemas and migration chains) and deliberately share no source edge. The contract between them is a signed token verified against a certificate, which is also what lets them deploy and restart independently. Both are services in the release bundle; registry-web answers on registry.stella-ops.local and stella-registry.stella-ops.local, and the shipped compose files set its bearer service to stella-registry.stella-ops.local (Registry__Bearer__Service).

The token service issues short-lived Docker registry bearer tokens after enforcing plan and licence constraints, and exposes an authenticated Plan Administration API (CRUD, dry-run validation, audit history) for the plan-rule catalogue that drives those decisions.

The token service surface:

• Token exchange: GET /token (AllowAnonymous; the registry.token.issue policy is evaluated for callers that present credentials).
• 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 token claims and (b) plan rules read from the durable PostgreSQL store (or, in test hosts, an explicitly registered in-memory store).

Migration resource ownership

The token role loads its startup SQL from StellaOps.Registry.Token.Persistence (Migrations/001_initial_schema.sql, 002_reserve_plan_allowlist.sql, 003_registry_token_retention_classes.sql) under module name Registry.TokenService. The data-plane StellaOps.Registry.Persistence chain (module schema registry) is separate.

Primary responsibilities

• Validate caller identity using Authority-issued access tokens (AddStellaOpsResourceServerAuthentication).
• Authorize requested registry scopes against the configured/persisted plan catalogue.
• Deny issuance for revoked licences and for disabled or unknown plans.
• Optionally mint pull-only tokens for callers presenting no credentials, when AnonymousPlan is set (off by default).
• 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.
• Both scopes are defined in StellaOps.Auth.Abstractions/StellaOpsScopes.cs: StellaOpsScopes.RegistryTokenIssue and StellaOpsScopes.RegistryAdmin.

Plan registry (token authorization rules)

• Authority assigns a client plan through the optional client property and emits it as stellaops:plan on client-credentials tokens. The configured DefaultPlan applies only when that claim is absent or blank.
• A non-blank claimed plan is authoritative: if the named enabled plan cannot be resolved, authorization returns plan_unknown and never retries through DefaultPlan. This pins assignment/enforcement drift as a loud refusal.
• 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.
• Statically configured repository rules have no default actions: a rule without Actions fails validation at startup, so a grant never widens implicitly.
• Anonymous issuance (AnonymousPlan, unset by default): a caller with no Authorization header receives a token carrying only the anonymous plan’s grants, narrowed to pull (RegistryTokenServiceOptions.AnonymousActions). Requests outside the plan are dropped from the access claim rather than refused. Startup fails if a static anonymous plan grants any action other than pull; narrowing is applied again at mint time for durable plans. A caller that presents an invalid Authorization header is not treated as anonymous and receives 401.

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, *), and positive rate-limit values; 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. allowlist is a reserved, unused physical compatibility column: create/import converge it to [], update does not write it, response models expose it read-only, and authorization never reads it. 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. Embedded migrations 001_initial_schema.sql, 002_reserve_plan_allowlist.sql and 003_registry_token_retention_classes.sql converge both fresh and upgraded databases; 002 records the reserved-column contract without rewriting the applied baseline, and 003 (comment-only, unqualified like the rest of the chain) classes both tables source-of-truth.
• 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. (Without an Authorization header the request takes the anonymous branch, which answers 401 unless AnonymousPlan is configured.)
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).
• 401 for presented-but-invalid credentials, and for an anonymous caller that cannot be served.
• 503 when the issuance policy or the issuer is not provisioned on the host.
• 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
• Optional: stellaops:anonymous: true on anonymously issued tokens (subject anonymous)

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 to an absolute path from the content root as ../etc/registry-token.yaml, no reload-on-change)
• environment variables: the unprefixed provider is re-added after the YAML file, so deployment RegistryTokenService__* values win over the shipped catalogue (RegistryTokenConfigurationSources); REGISTRY_TOKEN_-prefixed variables are also read

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, AnonymousPlan, 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.

The data plane (registry-web)

Source: src/Registry/StellaOps.Registry.WebService. Family database stellaops_registry (its own schema registry and migration chain, fail-closed on STELLAOPS_POSTGRES_REGISTRY_CONNECTION), own object-store bucket. It validates the bearer tokens registry-token mints — issuer, service audience, access claim, token lifetime — against the token service’s public X.509 certificate, and never references that project in source. The certificate’s own validity period is enforced: a lapsed signing certificate stops token acceptance. Health endpoints are GET /healthz and GET /readyz (readiness round-trips the registry schema).

Configuration (section Registry, RegistryWebServiceOptions; each value is validated at startup):

The operational GET /doctor/registry-web/checks surface uses Authority ops.health authorization (policy registry.ops.health) and reports Registry’s own database and configured content-bucket size. It does not change the distribution token contract. See the content measurement procedure for configuration, verification status and measurement limits.

Distribution-spec surface, named by the spec’s own endpoint identifiers (which is also how the official conformance suite groups its cases):

Load-bearing behaviours an integrator should not have to discover:

• Reachability is per repository, not per digest. registry.blobs / registry.manifests record which digests a given repository may serve, and registry.tags carries a composite foreign key on (repository, manifest_digest). One content-addressed bucket backs several trust domains, so a digest-only lookup would let a token scoped to one namespace read another’s bytes.
• Cross-repo mount requires pull on the SOURCE, not only push on the target — otherwise end-11 is a cross-namespace read primitive. A mount the caller is not entitled to falls back to an ordinary upload session (the spec’s own fallback) rather than answering 403, so the response is not an existence oracle for the source repository.
• GET on an upload session is authorized as a push. An in-flight upload is unpublished content.
• Upload sessions live in the database (registry.blob_uploads, registry.blob_upload_chunks), so they survive across replicas; the out-of-order rule is a conditional UPDATE on the cursor. Staged chunks are verified against their own recorded sha256 before assembly. Idle sessions expire per Registry:Push:SessionTimeout (default 24 h) and then answer BLOB_UPLOAD_UNKNOWN.
• Expired upload sessions are reclaimed by RegistryUploadSessionSweeper (a hosted service): every Registry:Push:SessionSweepInterval (default 1 h) it deletes the sessions whose LAST ACTIVITY is older than SessionTimeout, their chunk manifests, and then their staged bytes, in batches of Registry:Push:SessionSweepBatchSize (default 500). SessionSweepEnabled=false turns it off. A session still receiving chunks is never reclaimed, however long ago it started. Both tables are operational-state (P13, 005_registry_upload_session_retention.sql); the Doctor check doctor.registry.retention.upload-session-backlog reports sessions idle longer than the timeout plus one sweep interval. The repository, manifest, tag, blob and manifest-reference tables are source-of-truth: only the policy GC removes manifest and blob rows, and nothing schedules GC.
• Plan enforcement plugs in at IRegistryPushAdmission(Security/IRegistryPushAdmission.cs). The token-grant rule is the first registered admission; registration order is evaluation order and the first refusal wins. The pipeline refuses when the admission list is empty and when an admission throws (503) — losing the registrations yields a registry that accepts nothing.
• Registry:Push:MaxBlobBytes(default 1 GiB) is the enforced blob ceiling; Kestrel’s own body cap is lifted so this is the limit clients actually meet, returned as 413 with SIZE_INVALID.

Conformance suite. The OCI distribution-spec conformance suite is vendored at pinned v1.1.1 under tools/conformance/oci-distribution-spec/ (dev/test only — never distributed; the non-release guard is VendoredConformanceSuiteIsolationConformanceTests). The Pull, Push and Referrers categories are the target; Content Management is disabled rather than failing, because end-9/end-10 answer the spec’s 405 UNSUPPORTED (deletion is GC policy, below, not a client-callable route). Re-run the suite for a current result; a recorded pass count is not maintained here.

Referrers (end-12a / end-12b)

• Native, not fallback-tag emulation. A registry may emulate referrers by publishing an ordinary tag named sha256-<hex>; this one never creates that tag, and a test asserts it stays 404. That 404 is how a client tells a native implementation from an emulated one.
• Always 200, never 404 — the most consequential detail in the endpoint. The response is an image index that may be empty. A registry that 404s an unknown subject makes every client read “nothing refers to this” as “this registry has no referrers API at all”, after which clients fall back to tag emulation or give up. The suite pins it from three directions: a subject never pushed, a subject whose manifest is missing, and a plain unknown digest.
• The subject is a digest, not a stored object. Nothing is looked up. A client may attach a signature to content this repository has never held, and may keep reading referrers after the subject is deleted; both are legal and both are tested.
• OCI-Filters-Applied is emitted only when a filter was actually applied. Its ABSENCE tells the suite “this registry does not filter”, after which the suite expects the UNFILTERED list — so emitting the header without filtering, or filtering without emitting it, fails in opposite directions.
• A malformed digest is the one non-empty-index case: 400 DIGEST_INVALID, because the client asked a question the API cannot parse. An unknown but well-formed digest is a legitimate empty answer.

Deletion is GC policy, not a route

end-9/end-10 answer 405 permanently. Reclamation runs as a sweep (Gc/RegistryGarbageCollector.cs), and the shape is deliberate:

• Dry-run by default (RegistryGcOptions.DryRun = true), and a dry run writes the SAME audit rows a real one would — so the audit trail is reviewable before anything is erased.
• Every candidate is audited with a reason, not only the collected ones. registry.gc_audit is append-only.
• Reachability is ref-counted over registry.manifest_references edges: retained → tagged → referenced → collectable, in that order. A manifest with referrers is KEPT by default (CollectSubjectsWithReferrers = false), because collecting a subject silently orphans its signatures.
• Bytes are erased only when NO repository anywhere still references the digest. One bucket backs several repositories, so a per-repository decision would delete another repository’s layer.
• An image manifest with unaccounted edges stops the sweep rather than proceeding on a partial view of what is reachable.
• Retention pins (registry.manifests.retained_until) survive a re-push: PutManifestAsync’s upsert deliberately does not touch the column.

The meta-masking facade (registries/<slug>/…)

Deployment status. The facade is implemented and conformance-tested. It is off unless Registry:Facade:IntegrationsBaseAddress and Registry:Facade:Tenant are set; the base release bundle and the dev compose estate set neither, and only the optional bundle overlay devops/release/bundle/docker-compose.demo-registry.yml enables it. An unconfigured host answers registries/<slug> with the “meta-masking facade is not configured” refusal.

ADR-041 D3 gives registries/<slug>/<repo> to a pull-through of a tenant’s own registry, with Stella’s metadata overlaid on top. Two rules make it more than a naming convention:

• Writes are refused permanently (403 DENIED), not pending anything. “Stella metadata overlays customer images without being pushed into customer registries” cuts both ways — customer content is not pushed into Stella’s either, and the standing 4b DENY refuses customer artifact hosting on the product registry outright.
• Reads never fall through to the own store. Content pushed under a facade name before the namespace was reserved is not served; the answer is 404 NAME_UNKNOWN. Both refusals run AFTER the grant check, so neither is an existence oracle for an unauthorized caller.

It relays; it does not cache. The upstream leg is OciDistributionClient, the read half of StellaOps.Oci.Core — deliberately NOT OciPullThrough, which is a store primitive right for the agent’s loopback cache and wrong here: caching would write customer bytes into Stella’s own bucket under the very namespace reserved to prevent that, arriving through the server instead of a client PUT. A caching tier, if ever wanted, is an explicit custody decision.

Three behaviours worth stating explicitly, because each has a plausible-looking wrong alternative:

• Refusal is never anonymity. Any credential that cannot be resolved stops the fetch entirely. Falling back to an anonymous fetch fails silently in exactly the case that matters — an anonymous read of a PUBLIC upstream succeeds, so a broken credential configuration looks like a working facade until the day it points at a private registry.
• A builtin:// credential reference is UNRESOLVABLE ACROSS SERVICES, and is refused by name. A builtin secret is a row in the OWNING service’s own database (ADR-039 §8.2), so one minted by Integrations would be looked up in stellaops_registry and reported as a missing secret — true, and it sends the operator to entirely the wrong place. Facade upstream credentials must live in an external backend (vault/openbao).
• An empty referrers index and an unknown answer are different facts. Empty asserts “nothing is attached to this image”. Rendering a Scanner outage as empty would report an unscanned, unsigned image as merely an image with no metadata — silently, on the exact surface used to decide whether it was ever checked. Every transport failure answers 503, including an upstream 404, which on Scanner’s referrers plane means the route was missing rather than the subject.

Trap for whoever next touches Scanner’s referrers producer. Scanner accepts ?artifactType= and filters silently — it emits no OCI-Filters-Applied. The facade therefore fetches UNFILTERED and filters locally, because a filtered body without that header is wrong in the one way the conformance suite checks. If the producer ever starts emitting the header, revisit RegistryFacadePullThrough.ServeReferrersAsync rather than assuming pass-through became safe.

Configuration (all off by default; the facade and the meta overlay are separate opt-ins):

Known precision limit. Scanner’s referrers row is keyed on (tenant, registry_host, repo_path, subject_digest) but its HTTP contract exposes only repo path and digest, so two integrated registries in one tenant sharing a repository path and a subject digest see the same metadata. That is defensible — the metadata is about content, and an identical digest is the identical image — but it is a precision limit, not a designed guarantee. Making it exact needs a registryHost filter on the producer route.

Not yet implemented

• RateLimitDto (maxRequests, windowSeconds) is part of the admin plan model and persisted in plan_rules, but it is not enforced at the GET /token issuance path. Treat it as advisory metadata.

References

• Operations/runbook: operations/token-service.md
• Registry topology: registry-topology.md
• Content measurement: operations/content-storage-measurement.md

Evidence