go/httpauth-jwt
2
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity

feat(httpauth-jwt): initial release — self-issued JWT auth middleware v1.0.0

Browse Source 
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.
This commit is contained in:
Rene Nochebuena
2026-05-07 22:18:04 -06:00
commit d8773b0f9f
15 changed files with 1187 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
CHANGELOG.md Normal file
View File

@@ -0,0 +1,56 @@
# Changelog
All notable changes to `code.nochebuena.dev/go/httpauth-jwt` are documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [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.