auth

Auth — Gantry Server

Pluggable role-based auth. Two roles only: admin (full access) and viewer (read-only). Full adapter config reference: docs/auth.md. This skill covers adapter internals, route classification, and the frontend gating that the reference doc doesn't.

Adapter factory: server/src/web/auth/index.ts::createAuthAdapter(authConfig)

Built from gantry.json's auth key ({ adapter: string, config?: object }). Resolution:

• No auth key, or adapter: "loopback" → LoopbackAdapter (the documented default — admin only from 127.0.0.1/::1).
• adapter string matches a built-in name (switch statement) → that adapter.
• Anything else → must start with ./ (custom adapter, dynamic import() of a local JS/TS module exporting a default AuthAdapter). Throws if it doesn't start with ./ — this is deliberate, to block arbitrary package imports from gantry.json.

Built-in adapter names in code — more than the docs list. docs/auth.md and server/AGENTS.md document five: none, token, cloudflare-access, local-network, layered (plus the loopback default). The switch statement in index.ts also has two more, undocumented in docs/auth.md:

• deny (adapters/deny.ts) — authenticate() always returns null (always viewer, never admin, no anonymous admin possible even on MCP/localhost bypass paths that don't apply here). Used internally as a fail-closed fallback concept (see isExternallyAccessible() commentary in index.ts), but is directly selectable via "adapter": "deny" too.
• domain (adapters/domain.ts) — grants admin by matching the Host header against adminDomains, but only if a cf-access-jwt-assertion header is also present (it doesn't validate the JWT itself, just requires evidence the request passed through Cloudflare's edge). The adapter's own doc comment says it "MUST NOT be used as a standalone auth mechanism" — it's designed to be composed inside another adapter after a real CF JWT check, not selected directly. Doc mismatch: docs/auth.md's layered section describes adminDomains as "an optional hint that annotates which Cloudflare tunnel the admin came through" — but layered.ts's own LayeredConfig comment says adminDomains is "accepted but unused — domain auth requires a standalone domain adapter." The layered adapter's authenticate() never reads adminDomains at all; only localNetworkRanges and Cloudflare fields matter. If you need domain-based gating, wire the domain adapter explicitly (or write a custom one) — layered alone will not do it despite what adminDomains in its config suggests.