go/httpauth
2
0
Fork 0
Code Issues Pull Requests Packages Releases 3 Activity

3 Releases 4 Tags

RSS Feed
  • v1.0.2 601e6a5144
    Compare

    Release v1.0.2 Stable

    Rene Nochebuena released this 2026-05-18 14:16:42 -06:00 | 0 commits to main since this release

    v1.0.2

    code.nochebuena.dev/go/httpauth

    Overview

    v1.0.2 closes three gaps discovered during integration testing of RBAC-guarded
    endpoints: wildcard resource support in ClaimsPermissionProvider, exact numeric
    precision for math.MaxInt64 permission masks, and JSON-formatted error responses
    across the full httpauth-* middleware stack.

    No breaking changes. All v1.0.x consumers can upgrade with go get.

    What Changed Since v1.0.1

    Wildcard resource fallback in ClaimsPermissionProvider

    ResolveMask now checks the requested resource key first, then falls back to "*" if
    the resource is absent from the JWT masks claim:

    // JWT masks claim: {"*": 9223372036854775807}
provider := httpauth.NewClaimsPermissionProvider("masks")
mask, _ := provider.ResolveMask(ctx, uid, "any_resource") // returns MaxInt64 — wildcard hit

    This enables the ADMIN system role to carry a single wildcard entry and pass every
    endpoint guard without enumerating resources. Per-resource entries take precedence over
    "*" when both are present.

    json.Number precision for high-bit masks

    ResolveMask now handles three numeric types from JWT claims:

    Type Source math.MaxInt64 safe?
    int64 Go construction ✓
    float64 Standard JWT parsing (no option) ✗ (rounds to 2^63)
    json.Number jwt.WithJSONNumber() ✓ (decimal string parse)

    httpauth-jwt v1.0.2 uses jwt.WithJSONNumber() in all Verify implementations,
    so the json.Number path is now active for all tokens in the standard stack.

    Unified JSON error bodies — WriteJSONError

    New exported function:

    func WriteJSONError(w http.ResponseWriter, status int, code, message string)

    Writes a structured JSON error body matching the httputil.Error format:
    Content-Type: application/json with body {"code":"...","message":"..."}.

    All three auth middlewares in the stack now use this function:

    Middleware Condition Status Code
    httpauth-jwt AuthMiddleware Missing/invalid/expired token 401 UNAUTHENTICATED
    EnrichmentMiddleware No uid in context 401 UNAUTHENTICATED
    EnrichmentMiddleware Enricher returns error 500 INTERNAL
    AuthzMiddleware No identity in context 401 UNAUTHENTICATED
    AuthzMiddleware Permission denied or provider error 403 PERMISSION_DENIED

    Previously all three used http.Error which writes text/plain. AuthzMiddleware
    also had the wrong code string UNAUTHORIZED instead of UNAUTHENTICATED.

    Dependency

    Added code.nochebuena.dev/go/xerrors v1.0.1 for the code constants.

    Migration

    No breaking changes.

    go get code.nochebuena.dev/go/httpauth@v1.0.2
    Downloads
  • v1.0.0 3c6636f905
    Compare

    Release v1.0.0 Stable

    Rene Nochebuena released this 2026-05-07 23:09:23 -06:00 | 2 commits to main since this release

    v1.0.0

    code.nochebuena.dev/go/httpauth

    Overview

    httpauth v1.0.0 commits the provider-agnostic middleware stack as stable and adds
    ChainPermissionProvider — the last roadmap item. The module now ships three
    rbac.PermissionProvider implementations covering every common resolution pattern:
    claims-embedded, TTL-cached, and chained (fast-path + fallback in the same request).

    Dependency bumped to rbac v1.0.0.

    What Changed Since v0.1.0

    New: NewChainPermissionProvider

    func NewChainPermissionProvider(providers ...rbac.PermissionProvider) rbac.PermissionProvider

    Tries each provider in order and returns the first non-zero mask. Errors propagate
    immediately — subsequent providers are not consulted.

    Primary use case — JWT fast-path with DB fallback:

    chain := httpauth.NewChainPermissionProvider(
    httpauth.NewClaimsPermissionProvider("permisos"),                        // JWT claims — no DB call
    httpauth.NewCachedPermissionProvider(dbProvider, valkeyCache, 5*time.Minute), // fallback
)
r.With(httpauth.AuthzMiddleware(chain, "usuarios", rbac.Permission(1))).Get("/usuarios", h)

    When the JWT embeds permission masks (customClaims from jwtauth.IssueTokenPair),
    the chain returns immediately from the first provider. When the JWT has no embedded
    masks (e.g. a token issued before permissions were cached in claims), the chain falls
    through to the DB-backed provider transparently.

    Dependency bump

    code.nochebuena.dev/go/rbac v0.9.0 → v1.0.0

    Full API (stable)

    SetTokenData(ctx, uid, claims) context.Context — integration contract called
    by provider-specific AuthMiddleware implementations.

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

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

    NewClaimsPermissionProvider(claimsKey string) rbac.PermissionProvider — reads
    bitmasks from JWT claims; handles float64 (JSON) and int64.

    NewCachedPermissionProvider(inner, cache, ttl) rbac.PermissionProvider — TTL
    cache with silent fallthrough on cache error. Cache key: rbac:{uid}:{resource}.

    NewChainPermissionProvider(providers...) rbac.PermissionProvider — first
    non-zero mask wins; errors propagate immediately. (New in v1.0.0)

    IdentityEnricher interface — Enrich(ctx, uid, claims) (rbac.Identity, error)

    Cache interface — Get(ctx, key) (int64, bool, error) and Set(ctx, key, value, ttl) error

    WithTenantHeader(header string) EnrichOpt

    Migration from v0.1.0

    No breaking changes. The only addition is NewChainPermissionProvider.

    go get code.nochebuena.dev/go/httpauth@v1.0.0
go get code.nochebuena.dev/go/rbac@v1.0.0
    Downloads
  • v0.1.0 18e5a16f7e
    Compare

    Release v0.1.0 Stable

    Rene Nochebuena released this 2026-05-07 21:44:08 -06:00 | 3 commits to main since this release

    v0.1.0

    code.nochebuena.dev/go/httpauth

    Overview

    httpauth provides provider-agnostic HTTP middleware for identity enrichment and
    RBAC authorization. It is the shared foundation for all httpauth-* provider modules
    (httpauth-firebase, httpauth-jwt, etc.) — they converge on rbac.Identity as
    the output contract and call SetTokenData to make EnrichmentMiddleware and
    AuthzMiddleware work without any further changes.

    The module ships two rbac.PermissionProvider implementations for the two common
    architectures: JWT-embedded permissions (no runtime DB call) and TTL-cached runtime
    resolution (for large or independently revocable permission sets).

    What's Included

    SetTokenData(ctx context.Context, uid string, claims map[string]any) context.Context

    Injects a verified uid and raw claims into the request context. Called by any
    upstream AuthMiddleware after token verification. EnrichmentMiddleware reads
    these values automatically. The context keys are unexported — callers interact
    exclusively through this function and the downstream middleware.

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

    Reads the uid and claims injected by any upstream AuthMiddleware via SetTokenData,
    calls the application-provided IdentityEnricher, and stores the resulting
    rbac.Identity in context via rbac.SetInContext. Supports optional tenant header
    extraction via WithTenantHeader. Returns 401 if no uid is present; returns 500 if
    the enricher fails.

    AuthzMiddleware(provider rbac.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 provided rbac.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. Uses rbac.PermissionProvider
    directly — no local redefinition.

    NewClaimsPermissionProvider(claimsKey string) rbac.PermissionProvider

    Reads pre-computed permission masks from JWT claims stored in context by SetTokenData.
    Expects claims[claimsKey] to be a map[string]any where each key is a resource name
    and the value is the bitmask as int64 or float64 (JSON decodes numbers as float64).
    Returns 0 without error if the claim is absent. No DB call, no network — suitable for
    simple applications that embed permissions at token issuance time.

    Cache interface + NewCachedPermissionProvider(inner rbac.PermissionProvider, cache Cache, ttl time.Duration) rbac.PermissionProvider

    Wraps any rbac.PermissionProvider with a TTL-based cache layer. Cache key format:
    rbac:{uid}:{resource}. On cache miss, falls through to inner and populates the
    cache. On cache error, falls through silently — never fails due to cache unavailability.
    TTL-based expiry only; for explicit invalidation, callers interact with the Cache
    directly using the known key format.

    Interfaces

    • IdentityEnricher — application-implemented; receives uid and raw claims, returns rbac.Identity
    • Cache — caching backend abstraction; implement with Valkey, Redis, or in-memory

    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@v0.1.0

    Requires code.nochebuena.dev/go/rbac only. No external provider dependencies.

    Design Highlights

    Provider-agnostic by design. EnrichmentMiddleware and AuthzMiddleware depend
    only on SetTokenData having been called upstream. Any AuthMiddleware — Firebase,
    self-issued JWT, API key, mTLS — is compatible without modifying the enrichment or
    authorization layer. Provider-specific modules are thin adapters that call SetTokenData
    and defer everything else to this module.

    rbac.PermissionProvider without redefinition. AuthzMiddleware accepts
    rbac.PermissionProvider directly. The rbac package is the single source of truth
    for this interface; local redefinition in httpauth-firebase has been removed.

    Two permission resolution strategies as first-class citizens. ClaimsPermissionProvider
    and CachedPermissionProvider address the two main architectures upfront. Applications
    choose based on token size constraints and revocation requirements — not an afterthought.

    Cache falls through, never fails. CachedPermissionProvider treats cache errors as
    misses. A Valkey outage degrades gracefully to the inner provider — the application
    continues to serve requests with slightly higher latency. No circuit-breaker or fallback
    logic required in application code.

    Minimal dependency surface. The only import is code.nochebuena.dev/go/rbac. No
    logger, no HTTP framework, no external service SDK. Errors surface as HTTP responses;
    the enricher and provider implementations log at their own layer.

    Known Limitations & Edge Cases

    • ClaimsPermissionProvider cannot distinguish between "claim absent" and "mask is
      genuinely 0". Both return (0, nil). Callers that need to distinguish should encode
      a sentinel value or check for claim presence in the enricher.
    • CachedPermissionProvider uses TTL-based expiry exclusively. After a role or
      permission update, affected users retain cached masks until TTL expires. Set TTL
      short enough to meet your consistency requirements (5 minutes is a typical default).
      For immediate invalidation, delete rbac:{uid}:{resource} directly via your Cache.
    • AuthzMiddleware treats provider errors and permission-check failures identically
      (both return 403). The two cases are intentionally indistinguishable to callers.
    • EnrichmentMiddleware returns a generic 500 if the enricher fails. Log the error
      inside your enricher implementation; it is not surfaced to the HTTP client.

    v0.1.0 → v1.0.0 Roadmap

    • Evaluate adding Del to the Cache interface to support explicit invalidation via CachedPermissionProvider
    • Consider an optional error observer hook for enricher and provider errors
    • Add ChainPermissionProvider for OR-ing multiple providers (e.g. claims fast-path + DB fallback in the same request)
    • Production hardening across multiple deployed services
    Downloads