v1.0.0

code.nochebuena.dev/go/httpauth-firebase

Overview

httpauth-firebase v1.0.0 finalizes the module's scope: Firebase JWT verification
only. Identity enrichment, RBAC authorization, and permission providers have moved
to code.nochebuena.dev/go/httpauth — the provider-agnostic middleware layer shared
across httpauth-firebase, httpauth-jwt, and any future auth provider.

AuthMiddleware now calls httpauth.SetTokenData to inject uid and claims into
context, fulfilling the integration contract that all provider-specific auth modules
share. The rest of the stack (EnrichmentMiddleware, AuthzMiddleware, etc.) is
consumed directly from httpauth.

Breaking Changes

The following identifiers are no longer exported from this package. Import
code.nochebuena.dev/go/httpauth instead.

Removed from `httpauth-firebase`	Now in `httpauth`
`IdentityEnricher`	`httpauth.IdentityEnricher`
`PermissionProvider`	`rbac.PermissionProvider`
`EnrichmentMiddleware`	`httpauth.EnrichmentMiddleware`
`AuthzMiddleware`	`httpauth.AuthzMiddleware`
`WithTenantHeader`	`httpauth.WithTenantHeader`
`EnrichOpt`	`httpauth.EnrichOpt`

TokenVerifier and AuthMiddleware remain unchanged.

Migration Guide

Before (v0.9.0):

import httpauth "code.nochebuena.dev/go/httpauth-firebase"

r.Use(httpauth.AuthMiddleware(firebaseClient, publicPaths))
r.Use(httpauth.EnrichmentMiddleware(myEnricher))
r.With(httpauth.AuthzMiddleware(permProvider, "orders", rbac.Write)).Post("/orders", h)

After (v1.0.0):

import (
    httpauthfirebase "code.nochebuena.dev/go/httpauth-firebase"
    httpauthmw       "code.nochebuena.dev/go/httpauth"
)

r.Use(httpauthfirebase.AuthMiddleware(firebaseClient, publicPaths))
r.Use(httpauthmw.EnrichmentMiddleware(myEnricher))
r.With(httpauthmw.AuthzMiddleware(permProvider, "orders", rbac.Write)).Post("/orders", h)

The package identifier changes from httpauth to httpauthfirebase — update the
import alias (or remove it if you now import using the natural package name).
No behavior changes.

What's Included

AuthMiddleware(verifier TokenVerifier, publicPaths []string) func(http.Handler) http.Handler

Verifies the Authorization: Bearer <token> header via Firebase JWT verification
and injects uid + raw claims into the request context via httpauth.SetTokenData.
Requests matching any pattern in publicPaths are passed through without token
verification. Returns 401 on missing or invalid tokens.

TokenVerifier interface

Abstracts *auth.Client for unit-test mockability. Production code passes the
Firebase auth client directly.

Installation

go get code.nochebuena.dev/go/httpauth-firebase@v1.0.0
go get code.nochebuena.dev/go/httpauth@v1.0.0

Design Highlights

Single responsibility. This module verifies Firebase tokens. Everything else
lives in httpauth. The boundary is enforced by the module graph: httpauth-firebase
imports httpauth, never the reverse.

httpauth.SetTokenData as the integration contract. All provider-specific auth
modules (httpauth-firebase, httpauth-jwt, etc.) call httpauth.SetTokenData after
verifying their token. Generic middleware (EnrichmentMiddleware, AuthzMiddleware)
reads from those same context keys — no provider knowledge required.

No behavior changes. The token verification logic, public path bypass, and 401
response behavior are identical to v0.9.0.

Downloads

v0.9.0 d1de096c72

Compare
Release v0.9.0 Stable

Rene Nochebuena released this 2026-03-19 07:46:31 -06:00 | 3 commits to main since this release
v0.9.0

code.nochebuena.dev/go/httpauth-firebase

Overview

httpauth-firebase provides three composable net/http middleware functions that
implement the full Firebase authentication and authorization stack for HTTP services.
The output contract is always rbac.Identity — downstream handlers and business
logic are completely decoupled from Firebase types.

This release reflects an API designed through multiple architecture reviews and
validated end-to-end via the todo-api POC. It is versioned at v0.9.0 rather than
v1.0.0 because it has not yet been exercised in production workloads across all edge
cases, preserving the option for minor API refinements before committing to full
stability.

What's Included

AuthMiddleware(verifier TokenVerifier, publicPaths []string) func(http.Handler) http.Handler

Verifies the Authorization: Bearer <token> header via Firebase JWT verification
and injects the uid and raw claims into the request context. Requests matching any
pattern in publicPaths are passed through without token verification. Returns 401
on missing or invalid tokens.

EnrichmentMiddleware(enricher IdentityEnricher, opts ...EnrichOpt) func(http.Handler) http.Handler

Reads the uid and claims injected by AuthMiddleware, calls the application-provided
IdentityEnricher, and stores the resulting rbac.Identity in context via
rbac.SetInContext. Supports an optional tenant header via WithTenantHeader. Returns
401 if AuthMiddleware did not run upstream; returns 500 if the enricher fails.

AuthzMiddleware(provider PermissionProvider, resource string, required rbac.Permission) func(http.Handler) http.Handler

Reads rbac.Identity from context (set by EnrichmentMiddleware), resolves the
permission mask via the application-provided PermissionProvider, and gates the
request against the required permission bit. Returns 401 if no identity is in context;
returns 403 if the permission check fails or the provider errors.

Interfaces
- TokenVerifier — abstracts *auth.Client for unit-test mockability; production code passes the Firebase auth client directly
- IdentityEnricher — application-implemented; receives uid and raw claims, returns rbac.Identity
- PermissionProvider — application-implemented; receives uid and resource name, returns rbac.PermissionMask
Options
- WithTenantHeader(header string) EnrichOpt — reads a tenant ID from a named request header and attaches it to the identity
Installation
```
go get code.nochebuena.dev/go/httpauth-firebase@v0.9.0
```
Requires code.nochebuena.dev/go/rbac and firebase.google.com/go/v4.

Design Highlights

Provider-specific naming. The module is named httpauth-firebase because it
imports the Firebase SDK directly. Other auth providers (Auth0, JWKS, etc.) live in
sibling modules that all converge on the same rbac.Identity output contract. This
leaves the door open for httpauth-auth0 or httpauth-jwt without naming conflicts.

Three composable middleware, not one monolith. AuthMiddleware, EnrichmentMiddleware,
and AuthzMiddleware are separate functions. Each can be applied independently at the
router level or on individual route groups. A webhook endpoint might use only
AuthMiddleware; a protected CRUD resource uses all three.

rbac.Identity as the only output contract. Once EnrichmentMiddleware runs,
downstream code reads identity exclusively via rbac.FromContext. No Firebase type
leaks past the middleware boundary.

No logger dependency. Errors are returned as HTTP responses. The module does not
accept a logger parameter, keeping its dependency surface minimal.

Glob-based public path bypass. Public paths use path.Match patterns (* wildcard
supported), applied per request before any token parsing occurs.

Known Limitations & Edge Cases
- publicPaths matching uses path.Match (glob only). Regular expressions and
  prefix matching are not supported. A path like /api/v1/public/* requires an
  explicit * at the end; /api/v1/public does not match /api/v1/public/foo.
- No refresh token handling. Revoked tokens are detected via
  VerifyIDTokenAndCheckRevoked, but the middleware does not issue or refresh tokens.
- No claims caching. IdentityEnricher.Enrich is called on every request. Applications
  with expensive enrichment (e.g., database lookups) should implement their own caching
  inside the enricher.
- EnrichmentMiddleware returns a generic 500 if the enricher fails; the specific error
  is not surfaced to the client. Log the error inside your enricher implementation.
- AuthzMiddleware treats both provider errors and permission-check failures as 403.
  The two cases are intentionally indistinguishable to callers.
v0.9.0 → v1.0.0 Roadmap
- Evaluate whether publicPaths should support prefix matching in addition to glob patterns
- Add an optional error hook or logger interface so enricher/provider errors can be observed without coupling to a specific logger
- Consider claims caching support (e.g., an optional IdentityCache interface) for high-throughput services
- Validate behavior under token revocation race conditions
- Production hardening across multiple deployed services
Downloads
- Source Code (ZIP)
- Source Code (TAR.GZ)

2 Releases 3 Tags

Release v1.0.0 Stable

v1.0.0

Overview

Breaking Changes

Migration Guide

What's Included

Installation

Design Highlights

Release v0.9.0 Stable

v0.9.0

Overview

What's Included

Installation

Design Highlights

Known Limitations & Edge Cases

v0.9.0 → v1.0.0 Roadmap