nordisk/holger

Auth & RBAC — design note (for review)

Status: IMPLEMENTED (W1 + W2 v1), awaiting Rickard's evaluation. Grounded in server/lib/src/auth.rs + server/lib/src/grpc.rs. Folds the §O.holger-fixes W1/W2 items. The model below is the agent's professional call (delegated: "do it pro, I eval later"); change it freely.

Where authorization config lives — RON, not redb

Authorization policy is declarative config, not runtime state. Who is reader/writer/admin, and (later) which repo allows what, lives in the RON config graph alongside repos/endpoints/storage:

• git-tracked, code-reviewed, diffable — a policy change shows up in a PR.
• immutable in the static/drift flavor — the sealed binary's policy can't be silently mutated; it's exactly the bytes you reviewed.
• no IdP-claim-format coupling — airgap-friendly.

redb is for mutable operational state, not policy. Its natural homes here:

Putting auth policy in a mutable KV store would defeat audit/review and the airgap immutability model. So: policy → RON; runtime/audit/lineage → redb.

W1 — OIDC validation is fast (DONE)

auth.rs::validate_oidc_token previously built a fresh reqwest::Client and hit /userinfo on every write. Now:

• One shared pooled client (OnceLock<reqwest::Client>, idle-pool + 10s timeout) — connection + TLS-session reuse instead of a handshake per write.
• TTL token cache keyed by (issuer, blake3(token)) → (subject, instant). A repeat write with the same token returns from cache with zero network calls. TTL = 120s default (NORNIR_OIDC_USERINFO_CACHE_TTL_SECS override; the legacy HOLGER_OIDC_CACHE_TTL_SECS is honoured with a deprecation warning) — short enough that a revoked token stops working quickly. The raw token is never stored (only its blake3 digest), and the digest key can't collide into an auth bypass. Expired entries are purged opportunistically on insert (bounded map).

Tests (auth.rs mod tests, real local /userinfo mock counting hits): oidc_validation_caches_and_skips_repeat_userinfo_call (2nd validate → 1 hit), oidc_distinct_token_is_not_a_cache_hit (2 tokens → 2 hits).

mTLS stays the fast path (chain verified once at handshake; per-request only a leaf-CN parse) — unchanged.

W1-airgap — offline OIDC (net-new, for the static/airgap profile)

The /userinfo round-trip above is the online path → dynamic-only (it makes an outbound call, so it cannot exist in an airgap binary). The airgap path validates the OIDC token offline, like a PKI signature: verify the JWT's signature + standard claims (exp/iss/aud) against a JWKS provisioned offline — carried in the RON config or the sealed .znippy, never fetched. Pure crypto, no reqwest. So OIDC works in airgap without egress; the profile/BackendProvider selects online-vs-offline. See static-dynamic-profile-design.md (auth-by-egress table).

DONE. auth.rs::validate_oidc_bearer is offline-first: a JWT is verified OFFLINE by verify_jwt_offline (jsonwebtoken, key selected by header kid) against a JWKS cache keyed by issuer; claims exp/iss/aud are checked. The JWKS is resolved in order — fresh in-memory cache → inline jwks in the RON config → a pre-provisioned jwks_path file → an online fetch from jwks_uri (write-through-persisted to jwks_path). The first three touch no network — the fully-airgapped path. An opaque (non-JWT) token still falls back to the online /userinfo. The sub claim feeds the same RBAC role_for path. New AuthMethodConfig::Oidc fields (audience, jwks, jwks_path, jwks_uri) are all #[serde(default)], so existing issuer_url-only configs parse unchanged. Tests (auth.rs offline_oidc_tests): valid-verifies-offline, expired / bad-sig / wrong-iss / wrong-aud rejected, fully-offline via a pre-provisioned file, and JWKS fetched-once-then-cached.

W2 — authorization / RBAC (v1 global gate + v2 per-repo ACL — both DONE)

Model. Role = Reader | Writer | Admin (ordered, least→most). AuthConfig gains:

auth: Some((
    methods: [ Oidc(( issuer_url: "https://idp/realm" )), Mtls(( ca_cert: "..." )) ],
    // identity (OIDC `sub` or mTLS CN) → role
    roles: {
        "alice@corp":   Admin,
        "CN=build-bot": Writer,
    },
    // role for an authenticated-but-unmapped identity (omit ⇒ Reader, least-priv)
    default_role: Some(Reader),
))

Backward-compatible. roles/default_role are #[serde(default)], and RBAC is off until either is set (rbac_enabled()), so every existing config keeps its current authN-only behaviour (any valid identity may write). Old RON parses unchanged.

v1 enforcement (global gate, implemented). grpc.rs::authorize_write resolves the writer's role (role_for: explicit map → default_role → Reader) and, when RBAC is on, requires role.can_write() (Writer|Admin) — else permission_denied. Fail-closed: policy configured but no identity ⇒ denied. Reads stay open (R3 is a separate, deliberate decision — see holger-fixes).

Tests: role_privilege_ordering_and_capabilities, rbac_is_off_until_policy_is_configured, role_resolution_explicit_then_default_then_least_privilege.

v2 (per-repo ACL — implemented). AuthConfig carries repo_roles: HashMap<String, HashMap<String, Role>> (server/lib/src/auth.rs:AuthConfig) — outer key = repository name, inner map = identity → role FOR THAT REPO. A repo-scoped mapping WINS over the global roles/default_role, so a build-bot can be a Writer on team-a-dev yet only a Reader everywhere else — the airgap "who may push to which shelf" control:

// on AuthConfig, alongside `roles` / `default_role`
repo_roles: {
    "team-a-dev": { "alice@corp": Writer, "bob@corp": Reader },
},

Configuring any per-repo ACL turns RBAC on by itself — rbac_enabled() (server/lib/src/auth.rs:AuthConfig::rbac_enabled) is true when any role policy is set, even with an empty global roles map. The write path resolves the scoped role via AuthConfig::role_for_repo(repo, subject) (server/lib/src/auth.rs:AuthConfig::role_for_repo): per-repo explicit → global explicit → default_role → least-privilege Reader. The enforcing gate is HolgerGrpc::authorize_write (server/lib/src/grpc.rs:HolgerGrpc::authorize_write), which calls role_for_repo once the target repo name is known — threaded in from put_artifact (server/lib/src/grpc/services.rs); authorize_admin mirrors it requiring Admin. Fail-closed as before: policy configured but no identity ⇒ denied. The v1→v2 change is how the role is resolved (repo-scoped vs global); the gate, RON compat (#[serde(default)]), and fail-closed posture are unchanged.

Tests: per_repo_acl_overrides_global_role (a repo-scoped map both promotes and demotes on its shelf, global elsewhere) and rbac_is_off_until_policy_is_configured (a per-repo ACL alone flips RBAC on) — both in server/lib/src/auth.rs.

R3 — authenticated READS (SHIPPED 2026-07-22, opt-in)

The question first: gap, or deliberate?

Holger's reads — download, list, archive stat/browse, search, the whole HTTP door GET surface — were never authenticated. Only writes and admin actions were. Was that a decision or an omission?

Both, and the split matters. Open reads are the RIGHT DEFAULT for what holger mostly is: a mirror on the secure side of an airgap, where the network boundary IS the perimeter and every client inside it may pull. pip / cargo / docker pointed at holger with no credentials is the whole "it thinks it's talking to PyPI" promise; the read path is deliberately as frictionless as a public mirror. integration_oci_tls.rs::writes_blocked_without_auth_reads_open has asserted that posture on purpose since the beginning.

What was a gap is that there was no way to turn it OFF. Role::Reader has existed in the docs, in CLAUDE.md's permission table and in the code since day one with nothing enforcing it — a role that granted "download, list" while download and list asked for nobody. A holger that fronts an internal registry on a routed corporate network, or one whose repo set is itself sensitive (the catalog alone leaks project names), had no switch. This item was already logged here as R3; it is now closed.

The design: one opt-in flag, the existing role ladder

auth: Some((
    methods: [ Oidc(issuer_url: "https://idp.corp/realms/holger") ],
    require_auth_for_reads: true,             // ← the whole switch
    default_role: Some(Reader),               // any authenticated identity may pull
    repo_roles: {
        "customer-secrets": { "contractor@corp": Denied },   // …except here
    },
)),

• AuthConfig::require_auth_for_reads: bool, #[serde(default)] ⇒ false. A config that does not mention it behaves byte-for-byte as before. Nothing breaks on upgrade; that is the point of making it opt-in rather than deriving it from rbac_enabled() (turning RBAC on for writes must not silently close reads — asserted by read_gate_is_off_by_default_and_reads_stay_open).
• Role::Denied — a new variant, declared FIRST so the derived Ord keeps Denied < Reader < Writer < Admin. Nothing produces it implicitly and no existing RON names it, so it is purely additive. It is what makes the gate expressive instead of a boolean: a per-repo Denied carves one private repo out of an otherwise readable server. Role::can_read() is !Denied.
• AuthConfig::authorize_read(identity, repo) — the ONE predicate every read door consults (L5). Gate off ⇒ Ok(()). Gate on: no identity ⇒ 401, a role that cannot read ⇒ 403. Repo-scoped, so repo_roles governs reads exactly as it governs writes.
• Fail-closed, loudly. Gate on with no methods configured = nothing can authenticate = every read refused. That is fail-closed working as designed (asserted, so it can never be "fixed" into falling open), and warn_unauthenticatable_read_gate() shouts at boot so it is not a mystery.

Where it is enforced

Health stays open on purpose: gating it would break every load balancer and readiness probe the moment an operator opts in (read_gate_leaves_health_open).

The bonus that falls out

A gated read audits the real subject. Every read used to record anonymous because there was no identity to record; with the gate on, AuditEvent::ident carries the OIDC sub / token principal / mTLS CN. Knowing who took a build artifact is most of why one authenticates a download at all.

Cost when off

Zero. authorize_read returns on a bool before touching metadata, headers or certificates — no credential parsing happens on the default read path.

Tests

auth.rs + exposed/http.rs unit cover the predicate (default-off, 401/403, Denied globally and per-repo, the no-methods refusal). grpc.rs drives the real service impls: read_gate_off_serves_anonymous_reads_even_with_rbac_on (the default is untouched even with auth + roles configured), read_gate_on_refuses_anonymous_serves_reader_denies_denied (401 / 200 / 403, and the audit line names pull-bot), read_gate_covers_every_read_door_not_just_fetch (RED-when-broken for a door that forgets the gate — StreamArtifact bypassed the quarantine predicate exactly that way once), read_gate_leaves_health_open.

Open follow-ups

• W8 — audit log in redb (the RBAC companion).