httpauth-firebase/docs/adr/ADR-001-provider-specific-naming.md

ADR-001: Provider-Specific Module Naming (httpauth-firebase)

Status: Accepted Date: 2026-03-18

Context

An auth middleware module originally named httpauth was designed to be provider-agnostic: it defined a TokenVerifier interface and duck-typed firebase.Client so the module never imported Firebase directly. The intent was that any JWT provider could be supported by implementing TokenVerifier.

Under global ADR-001, framework modules import their named dependencies directly rather than duck-typing them away. An auth module for Firebase should import firebase.google.com/go/v4/auth directly, since that is its explicit purpose. This raises the naming question: if the module imports Firebase, should it still be called httpauth?

Decision

The module is named httpauth-firebase:

• Go module path: code.nochebuena.dev/go/httpauth-firebase
• Directory: micro-lib/httpauth-firebase/
• Package name: httpauth (short import alias; the module path carries the provider name)

A different auth provider would live in httpauth-auth0, httpauth-jwks, etc. All httpauth-* modules converge on the same output contract: rbac.Identity stored in context via rbac.SetInContext.

The TokenVerifier interface is retained solely for unit-test mockability — not for provider abstraction. In production, *auth.Client from firebase.google.com/go/v4/auth satisfies TokenVerifier directly without any adapter.

Consequences

• The module name is honest: scanning the module list, a developer immediately knows this is Firebase-specific and not a generic auth abstraction.
• Other auth providers are accommodated by creating sibling modules (httpauth-auth0, etc.) with identical output contracts, not by implementing an interface in this module.
• The TokenVerifier interface remains exported so test code outside the package can implement it (mockVerifier in compliance_test.go). Its presence does not imply that swapping providers at runtime is a supported pattern.
• Applications that switch from Firebase to another provider replace the module import; the rest of the auth stack (EnrichmentMiddleware, AuthzMiddleware) and all business logic remain unchanged because they depend on rbac.Identity, not on Firebase types.