ADR-142: gyrum-go/pkg/auth audit + adoption shape

Status: Proposed Date: 2026-05-06

Context

gyrum-go/pkg/auth was authored as the fleet's intended shared auth library (Argon2id + JWT + httpOnly cookies + RBAC port shapes), but no repo currently uses it. Three repos ship bespoke auth implementations: warp

(api/internal/auth/{auth.go,bootstrap.go,magic_link.go,github_oauth.go},

~2,000 LoC), distill (internal/middleware/auth.go, 233 LoC), and ai-research (its own). Bug fixes in one do not propagate. The shared lib also has a load-bearing gap: there is no long-lived API key (Bearer) support — the whole shape is user-session-only. Agents using Authorization: Bearer wrp_… cannot resolve through it without an extension.

EPIC warp#1450 closes those gaps in five phases. Phase 0 — design — must land first because every subsequent phase cascades from these ADRs. This ADR (A0.1) is the audit + migration-shape commit. Sister ADRs A0.2 (warp#1452) and A0.3 (warp#1453) cover the Role × Permission matrix and the API-key primitive shape respectively; this ADR deliberately stays out of those slices.

The non-negotiable constraint is operator-tolerable but agent-intolerant breakage. Every active swarm session — including this one — routes through warp-claim / warp-complete with Authorization: Bearer wrp_…. Migration must be additive: agent flow keeps working through every phase. EPIC warp#1450's pitfalls list names this as the load-bearing risk.

Decision

We adopt gyrum-go/pkg/auth as warp's session backbone via an additive-then-cleanup migration: warp's auth middleware accepts EITHER its existing wrp_… Bearer token OR a new gyrum-go session JWT (cookie or Bearer); both resolve to a common Identity object that downstream handlers consume. Bespoke auth code stays running until each route is proven equivalent on the new substrate; only then is the old path deleted. warp is the first real consumer because it has the most rigorous test coverage (3-persona reviews, contract suite, smoke specs) and the most complex auth surface (4 scopes, 2 sign-in methods + bearer).

Surface audit — gyrum-go/pkg/auth as it exists today

Source files surveyed: auth.go (~480 LoC), routes.go (~280), rbac.go (~150), adapters.go (~80), platform.go (~60), plus doc.go. Verdict legend: as-is = warp adopts unchanged; extend = warp's needs require a deliberate, scoped extension; not needed = warp's bespoke flow is the right shape and the lib symbol stays for other consumers.

auth.go — JWT + Argon2id + cookie + middleware

routes.go — register / login / logout / me / refresh

This bundle is the bulk of the lib that does not apply to warp. The pkg keeps it; warp simply does not import it. Distill (Phase 5.1) adopts it.

rbac.go — Role + Permission + Policy + middleware

adapters.go — port-style wrappers (hex arch)

platform.go — gyrum.io platform (P078) JWT validator

Audit summary

• Adopted as-is by warp: Config, Auth, New, (*Auth).CreateTokens, (*Auth).ValidateToken, (*Auth).SetTokenCookies, (*Auth).ClearTokenCookies, UserID, Permission type, Policy + NewPolicy + Grant + Allows, RequireRole, RequirePermission.
• Adopted with extension by warp: Claims (add Permissions), (*Auth).RequireAuth (accept wrp_… Bearer via pluggable resolver), UserFromContext → IdentityFromContext rename, Role constants (warp set), (*Auth).CreateRoleTokens → permission-carrying variant.
• Stays in lib but not used by warp: the entire routes.go user-store bundle, the adapters.go UUID-flavoured port wrappers, the platform.go portal validator, the legal-app DefaultPolicy and its perms, RestrictClientToPortal. These continue to serve other consumers (legal-app blueprint, P078 portal, distill in Phase 5.1).
• Missing — must be added in Phase 1: APIKey type, APIKeyStore interface, mint / lookup / revoke ops, and the RequireAuth extension that resolves a wrp_… Bearer through the APIKeyStore to an Identity. The exact shape is A0.3 (warp#1453); this ADR only commits that the shape exists and that RequireAuth becomes its consumer.

Gap: API keys

gyrum-go/pkg/auth has zero support for long-lived bearer tokens. warp's wrp_… tokens are SHA-256-of-plaintext-stored, with a row per key in warp_api_keys carrying (key_hash, scope, label, expires_at, revoked_at). The shape needed in gyrum-go (locked here, detailed in A0.3):

// APIKey is a long-lived bearer credential.
type APIKey struct {
    ID         string      // opaque, e.g. uuid
    KeyHash    string      // sha256 hex of plaintext
    Label      string      // human display ("bootstrap-admin", "swarm-MMM")
    Role       Role        // warp role (admin/user/agent/readonly)
    ExpiresAt  *time.Time  // nil = no expiry
    RevokedAt  *time.Time  // nil = active
}

// APIKeyStore is the persistence port. warp's wrp_… keys table satisfies it.
type APIKeyStore interface {
    Mint(ctx context.Context, label string, role Role, ttl *time.Duration) (plaintext string, _ APIKey, _ error)
    Lookup(ctx context.Context, plaintext string) (APIKey, error) // hashes then SELECT
    Revoke(ctx context.Context, id string) error
    List(ctx context.Context) ([]APIKey, error) // for admin UI
}

The hash format must match warp's existing sha256_hex(plaintext) shape so existing wrp_… tokens migrate without re-mint (operator- experience promise per the EPIC's pitfalls). Token format (wrp_<32-hex>) is owned by the deploying app — gyrum-go provides the primitive, warp keeps its prefix + length.

Migration shape — additive-then-cleanup

Concrete code shape that A2.* implements:

// Identity is the resolved caller, regardless of which auth method
// produced it. Lives in gyrum-go/pkg/auth alongside Claims.
type Identity struct {
    UserID      string
    Email       string
    Role        Role
    Permissions []Permission
    KeySource   IdentitySource // "session_jwt" | "api_key" | "platform_jwt"
    KeyID       string         // populated for api_key; empty otherwise
    Label       string         // populated for api_key; empty otherwise
}

// IdentityResolver fans out across auth methods. RequireAuth tries
// each in order and stops at the first success.
type IdentityResolver interface {
    Resolve(r *http.Request) (Identity, bool, error) // (id, attempted, err)
}

// Concrete resolvers: SessionJWTResolver (existing), APIKeyResolver
// (new in A1.1, wraps APIKeyStore), PlatformJWTResolver (existing).
// warp wires all three; resolution order is fixed: session_jwt first
// (cheapest validation), then api_key, then platform_jwt.

RequireAuth becomes the composition point: it walks the configured resolver list, seeds Identity into context on first success, returns 401 if none match. Route guards (RequirePermission) read from the same context key regardless of which resolver populated it.

Crucially: no wrp_… token is invalidated, no agent restarts. warp's Middleware(lookup, allowed...) from auth.go keeps working in parallel until the route is migrated; the new RequireAuth + RequirePermission chain is opt-in per route. Bespoke deletion (Phase 4) only happens once all routes are migrated and proven equivalent.

What stays bespoke in warp (delegated to providers, not shared)

These remain warp-owned because they are warp-specific config or template content, not shared auth machinery:

• Magic-link email-template rendering (buildHTMLEmail, buildTextEmail in warp's magic_link.go). Warp's brand colours + copy live here. The flow itself (mint → email → redeem → mint session) routes its session-mint through gyrum-go/pkg/auth. CreateTokens once A2.4 lands. The MagicLink handler stays warp-resident; only the session-mint side is shared.
• GitHub OAuth allowed-orgs check (gateOrgs, allowedOrgsLowered in github_oauth.go). Warp's allowlist (gyrum-labs, gyrum-customers, …) is config-driven and warp-specific. The OAuth handler stays warp-resident; only the session-mint side routes through gyrum-go.
• BootstrapAdmin (bootstrap.go). First-boot key-file announcement is warp-deployment-specific (path, message, distroless UID note). It will use APIKeyStore.Mint once A1.1 lands but the bootstrap flow itself stays warp-resident.
• PGLookuper, PGStateStore, PGMagicLinkStore — Postgres adapters for warp's tables. Implement the gyrum-go interfaces (APIKeyStore etc.) but the schema and SQL are warp-owned.

Why warp first, not distill

• Test coverage rigour. warp ships the 3-persona review gate, the contract suite, and the smoke spec contract (warp#974). Bugs in the shared lib surface here first.
• Auth-surface complexity. warp has 4 scopes (admin/user/agent/ readonly), 3 sign-in methods (magic-link, GitHub OAuth, raw bearer for agents), and the bootstrap-admin flow (warp#1353). distill has one scope-pair (session vs API key) and one method. If the lib works for warp, distill is mechanical.
• Forcing function for API-key support. warp's agent flow is the reason APIKey must exist in gyrum-go. Migrating distill first would let us defer the gap; migrating warp first forces the design.

Risk register

Consequences

Easier:

• One canonical place to fix auth bugs once distill / ai-research catch up.
• New repos start with the shared lib; bespoke is structurally deprecated.
• RBAC becomes a fleet primitive — adding a new admin-only route in any repo is RequirePermission(perm) instead of bespoke scope-string parsing.
• Admin-from-browser (warp#1353) becomes a tractable A2.4 sub-ticket because RequireAuth now sees the same Identity whether the caller is a magic-link user or an agent — admin role gating works uniformly.
• Future repos can pick auth methods à la carte: bearer-only (agent gateway), session-only (read-only dashboard), or full multi-method (warp).

Harder:

• gyrum-go/pkg/auth becomes load-bearing: every repo that adopts it now depends on a single lib's release cadence. We mitigate via semver and the existing gyrum-go dependency-bump bot.
• The Permissions JWT extension and the Identity shape are now public API surface; bumping them needs an ADR and a migration window.
• Two paths run in parallel through Phases 2–3 (warp's bespoke + gyrum-go path). Phase 4 is mandatory, not optional — delaying deletion leaves dead code that confuses every future reviewer.

Signed up for:

• Maintaining the additive contract through every Phase 2 / Phase 3 sub-ticket.
• A1.* implementations (gyrum-go) ship their own regression suite; A2.* / A3.* (warp) ship contract-suite assertions that both paths agree.
• Phase 4's deletion ADR lives in warp, not here. This ADR commits to the shape; the deletion's audit lives where the deletion lands.
• Memory file feedback_fleet_auth_substrate.md filed once Phase 4 closes, codifying "use gyrum-go/pkg/auth; bespoke is deprecated".

Alternatives considered

• Wholesale replace, not additive. Cut warp over to gyrum-go in one PR; delete bespoke in the same PR. Lost because it breaks every running swarm session at the cutover instant; the EPIC names this as the load-bearing pitfall.
• Migrate distill first, warp second. distill has the simpler surface and would prove the lib faster. Lost because distill's surface is so simple it doesn't exercise the API-key path; we'd ship gyrum-go's APIKey support without a real consumer for it, deferring the design tension. The EPIC explicitly chooses warp-first for forcing-function reasons.
• Build a new shared lib; deprecate gyrum-go/pkg/auth. The lib has legal-app-flavoured constants (RoleAttorney, PermCaseCreate) that don't apply to warp. Lost because the constants are just Role/Permission values — they coexist trivially with warp's set. Replacing the whole lib is much higher cost than extending it.
• Keep bespoke per-repo; ship shared types only. Define Identity + Role + Permission in a shared types-only package; each repo keeps its handlers. Lost because the bug-propagation argument that motivated this work doesn't hold — handler bugs (cookie shape, JWT validation, RBAC enforcement) are exactly where the duplication hurts. Types-only sharing leaves the highest-bug-surface code per-repo.
• Bake permissions into JWT instead of resolving via Policy on each request. Faster guard checks (no map lookup). Lost because permission grants drift faster than JWT TTL; an admin demoted to user shouldn't keep mint_agent_token for 15 minutes until their access token expires. Resolving live trades a microsecond per request for correct authorisation. (A0.2 will revisit this if the perf regression is non-trivial; current stance: live resolution.)

Supersedes: none Superseded by: none yet

Cross-refs:

• EPIC: warp#1450 — fleet auth substrate
• A0.2: warp#1452 — fleet RBAC matrix (Role × Permission)
• A0.3: warp#1453 — agent API key shape
• Sister: warp#1442 — warp public identity (frontend home + login + account)
• Sister: warp#1353 — warp admin not reachable from browser

• ADR-140 (in flight, dark-factory PR #634) — warp public-identity architecture

• ADR-141 (in flight, dark-factory PR #635) — warp mobile-first auth UX