Rene Nochebuena
d8773b0f9f
Provides AuthMiddleware (calls httpauth.SetTokenData, accepts Verifier or Signer), IssueTokenPair (access + refresh tokens as jwt.MapClaims, custom claims at top level for ClaimsPermissionProvider compatibility), RefreshTokenPair (blacklist check + rotation + re-issue), and Signer/Verifier implementations for HMAC-SHA256 and RSA-SHA256 including PEM loaders and a public-key-only Verifier for read-only microservices.
2.7 KiB
Changelog
All notable changes to code.nochebuena.dev/go/httpauth-jwt are documented here.
Format follows Keep a Changelog.
[1.0.0] — 2026-05-08
Added
Verifier interface — validates JWT strings. Narrowest interface; AuthMiddleware
accepts this so services that only verify (not issue) tokens pass a public-key verifier.
Signer interface — embeds Verifier and adds Sign(jwt.Claims). Used by
IssueTokenPair and RefreshTokenPair.
NewHMACSigner(secret []byte) Signer — HMAC-SHA256. For single-service or
monolith deployments where one process both issues and verifies tokens.
NewRSASigner(privateKey *rsa.PrivateKey) Signer — RSA-SHA256 signer + verifier
backed by the private key (public key derived automatically).
NewRSASignerFromPEM(pemKey []byte) (Signer, error) — loads a PKCS#8 or PKCS#1
PEM-encoded RSA private key. Suitable for loading from environment variables or files.
NewRSAPublicKeyVerifier(publicKey *rsa.PublicKey) Verifier — RSA-SHA256
verifier backed by a public key only. For microservices that receive tokens from a
central issuer but never sign them.
NewRSAPublicKeyVerifierFromPEM(pemKey []byte) (Verifier, error) — loads a PKIX
or PKCS#1 PEM-encoded RSA public key.
TokenConfig — AccessTTL, RefreshTTL, Issuer.
TokenPair — AccessToken, RefreshToken, ExpiresIn (seconds).
IssueTokenPair(signer, uid, customClaims, cfg) (TokenPair, error) — issues
access + refresh tokens. customClaims are merged at the top level of the access
token (compatible with httpauth.ClaimsPermissionProvider). Refresh token carries
only sub, iss, iat, exp, jti, and fam (token family for rotation).
Blacklist interface — IsRevoked(ctx, jti) and Revoke(ctx, jti, ttl).
Implementations are typically backed by Valkey or Redis.
ErrTokenRevoked — sentinel returned by RefreshTokenPair when the JTI is on
the blacklist. Callers should respond with 401 and prompt re-authentication.
RefreshTokenPair(ctx, signer, refreshToken, blacklist, cfg, customClaims) (TokenPair, error)
— validates the refresh token, checks the blacklist, revokes the old JTI with the
token's remaining TTL, and issues a new pair. customClaims in the new access token
allow callers to embed fresh permission masks reflecting any role changes since the
previous issue.
AuthMiddleware(verifier, publicPaths) func(http.Handler) http.Handler — verifies
the Bearer access token and calls httpauth.SetTokenData(ctx, uid, claims). Accepts
Verifier so services with only the public key can participate. Public paths bypass
token verification via path.Match glob patterns.