feat(auth): verifiers on one axis, and a reusable authenticator constructor

[ben-fornefeld]

Makes packages/auth usable by a service that authenticates a route before the caller is a user — signup. Today no verifier fits that, so the closest one silently skips OIDC discovery, the issuer cross-check and the iss claim.

Verifiers, now one axis

	keys from	establishes
JWKSVerifier	issuer's JWKS path	claims
OIDCVerifier	OIDC discovery	what the token asserts
LinkedOIDCVerifier	OIDC discovery	+ the internal user

Each adds to the one before. Picking a lower rung is a choice about what you need, never a weaker check — discovery and issuer validation are identical across both OIDC levels.

LinkedOIDCVerifier embeds OIDCVerifier, so linking is additive: the unlinked type has no Verify to call, rather than one that fails at runtime.

Also

• NewAuthenticator(AuthenticatorConfig[T]) — build an authenticator for a scheme this package doesn't name. Every existing constructor is already a thin literal over commonAuthenticator, but they fix the scheme name and context key, and the type is internal. Named constructors unchanged.
• iss/sub extraction moved into VerifyIdentity; the resolving path is built on it, so those claims are read in one place.

Breaking

before	after
ProviderVerifier	LinkedOIDCVerifier
OIDCVerifier (single-issuer)	OIDCIssuerVerifier
AdminVerifier	JWKSVerifier

Aliases removed rather than deprecated — only belt used them, and it pins by commit. The OIDCVerifier reuse can't break silently: the new one takes a ProviderConfig where the old took a JWTConfig, so callers get a compile error.

NewAdminJWTAuthenticator keeps its name — AdminJWTAuth is a real security scheme.

Verification

Behaviour unchanged for every current caller; dashboard-api verifies exactly as before. New tests cover the identity verifier (reports claims without a lookup, rejects a missing subject, rejects a discovery issuer mismatch), the authenticator constructor (scheme, prefix stripping, 401 on missing header, optional context setter), and that nil verifiers deny rather than panic — the last one panics without its guard, since promotion through an embedded value dereferences before the inner nil check.

No docs/ARCHITECTURE.md change: no service, port, protocol, data store, flow or topology affected.

[cursor]

PR Summary

Medium Risk
Auth verification APIs were renamed and split (LinkedOIDCVerifier, OIDCVerifier, JWKSVerifier), so any caller still using ProviderVerifier/AdminVerifier must migrate; runtime behavior for linked OIDC and admin JWT paths is intended to stay equivalent.

Overview
This PR adds a middle tier of OIDC verification that runs full discovery and issuer checks but stops at iss/sub via VerifyIdentity and NewOIDCVerifier, so signup-style flows do not need a fake identity lookup or JWKS-only admin verification. ProviderVerifier becomes LinkedOIDCVerifier; per-issuer NewIdentityVerifier backs the unlinked path while Verify on an identity-only verifier fails if no lookup was configured.

AdminVerifier is removed in favor of JWKSVerifier (same JWKS-path behavior); dashboard-api now calls NewJWKSVerifier. Exported NewAuthenticator/AuthenticatorConfig reuse the shared header extraction, prefix stripping, optional context, and 401 stamping used by the named middleware constructors.

^{Reviewed by Cursor Bugbot for commit 12b0229. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[claude]

LGTM — a clean, backward-compatible refactor with no functional behavior change.

Extended reasoning...

Overview

This PR adds a generic NewAuthenticator(AuthenticatorConfig[T]) constructor to packages/auth for external services that define their own security scheme, and renames AdminVerifier/NewAdminVerifier to IssuerVerifier/NewIssuerVerifier (better reflecting that the verifier resolves no identity). Both changes are additive/aliasing: AdminVerifier, NewAdminVerifier remain as type aliases and deprecated wrapper functions, so no existing caller breaks. dashboard-api/main.go is updated to use the new name; I confirmed via grep that no other file in the repo references the old names outside packages/auth internals, so the rename is safe.

Security risks

None identified. The underlying commonAuthenticator logic (header extraction, prefix handling, 401 stamping, telemetry) is untouched — NewAuthenticator just exposes the existing struct literal fields through a public config struct. The verifier rename is a pure type alias (type IssuerVerifier = token.AdminVerifier), so token.AdminVerifier's JWT/issuer verification behavior is unchanged.

Level of scrutiny

Light-to-moderate is appropriate: this touches the shared auth package, but the change is a mechanical constructor extraction plus a rename via type alias, not new authentication/authorization logic. I built and ran the full test suite for packages/auth locally (all passing) and confirmed no other callers of the old AdminVerifier/NewAdminVerifier names exist that could be affected by the rename.

Other factors

Four new unit tests cover the new constructor's behavior (scheme name/context setter application, prefix stripping, 401 stamping on missing header, optional SetContext). The PR author states go vet/golangci-lint pass and that they compiled an external caller's bootstrap shape against the new export. No architecture doc update was needed since no service responsibility, protocol, or topology changed.