83 lines
2.3 KiB
Markdown
83 lines
2.3 KiB
Markdown
|
# httpauth-firebase
|
||
|
|
|
||
|
|
Firebase-backed HTTP middleware for authentication, identity enrichment, and RBAC authorization.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
Three composable `func(http.Handler) http.Handler` middleware functions:
|
||
|
|
|
||
|
|
| Middleware | Responsibility |
|
||
|
|
|---|---|
|
||
|
|
| `AuthMiddleware` | Verifies Firebase Bearer token; injects uid + claims into context |
|
||
|
|
| `EnrichmentMiddleware` | Calls app-provided `IdentityEnricher`; stores `rbac.Identity` in context |
|
||
|
|
| `AuthzMiddleware` | Resolves permission mask; gates request |
|
||
|
|
|
||
|
|
All functions accept interfaces — testable without a live Firebase connection.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```
|
||
|
|
require code.nochebuena.dev/go/httpauth-firebase v0.1.0
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```go
|
||
|
|
r.Use(httpauth.AuthMiddleware(firebaseAuthClient, []string{"/health", "/public/*"}))
|
||
|
|
r.Use(httpauth.EnrichmentMiddleware(myUserEnricher, httpauth.WithTenantHeader("X-Tenant-ID")))
|
||
|
|
r.Use(httpauth.AuthzMiddleware(myPermProvider, "orders", rbac.Read))
|
||
|
|
```
|
||
|
|
|
||
|
|
## Interfaces
|
||
|
|
|
||
|
|
### TokenVerifier
|
||
|
|
|
||
|
|
```go
|
||
|
|
type TokenVerifier interface {
|
||
|
|
VerifyIDTokenAndCheckRevoked(ctx context.Context, idToken string) (*auth.Token, error)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
`*firebase/auth.Client` satisfies this directly. Swap in a mock for tests.
|
||
|
|
|
||
|
|
### IdentityEnricher
|
||
|
|
|
||
|
|
```go
|
||
|
|
type IdentityEnricher interface {
|
||
|
|
Enrich(ctx context.Context, uid string, claims map[string]any) (rbac.Identity, error)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Implement this in your application to load user data from your store and return an `rbac.Identity`.
|
||
|
|
|
||
|
|
### PermissionProvider
|
||
|
|
|
||
|
|
```go
|
||
|
|
type PermissionProvider interface {
|
||
|
|
ResolveMask(ctx context.Context, uid, resource string) (rbac.PermissionMask, error)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Returns the permission bitmask for the user on a given resource.
|
||
|
|
|
||
|
|
## Options
|
||
|
|
|
||
|
|
| Option | Description |
|
||
|
|
|---|---|
|
||
|
|
| `WithTenantHeader(header)` | Reads `TenantID` from the named request header. If absent, `TenantID` remains `""`. |
|
||
|
|
|
||
|
|
## Public paths
|
||
|
|
|
||
|
|
`AuthMiddleware` skips token verification for requests matching any pattern in `publicPaths`. Patterns use `path.Match` semantics (e.g. `"/public/*"`).
|
||
|
|
|
||
|
|
## HTTP status codes
|
||
|
|
|
||
|
|
| Condition | Status |
|
||
|
|
|---|---|
|
||
|
|
| Missing or malformed `Authorization` header | 401 |
|
||
|
|
| Token verification failure | 401 |
|
||
|
|
| No `rbac.Identity` in context (AuthzMiddleware) | 401 |
|
||
|
|
| Missing uid in context (EnrichmentMiddleware) | 401 |
|
||
|
|
| Enricher error | 500 |
|
||
|
|
| Permission denied or provider error | 403 |
|