httpauth-jwt/CHANGELOG.md

# 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.2] — 2026-05-18

### Changed

- All three `Verify` implementations (`hmacSigner`, `rsaSigner`, `rsaPublicVerifier`)
  now pass `jwt.WithJSONNumber()` to `jwt.Parse`. JWT numeric claims — including
  permission mask bitmasks — are decoded as `json.Number` instead of `float64`,
  preserving exact bit patterns for values up to and including `math.MaxInt64`.
- `AuthMiddleware` now returns JSON error bodies instead of plain-text `http.Error`
  for missing/invalid/expired Bearer tokens. Uses `httpauth.WriteJSONError` — the
  same helper as `EnrichmentMiddleware` and `AuthzMiddleware` — ensuring a consistent
  `{"code":"UNAUTHENTICATED","message":"unauthorized"}` response across the full
  middleware stack.
- Dependency `code.nochebuena.dev/go/httpauth` bumped to v1.0.2.

[1.0.2]: https://code.nochebuena.dev/go/httpauth-jwt/releases/tag/v1.0.2

## [1.0.0] — 2026-05-08

### Changed

- Package renamed from `jwtauth` to `httpauthjwt` — follows ecosystem convention
  (`repo name = package name`, hyphens removed); import path is unchanged
  (`code.nochebuena.dev/go/httpauth-jwt`); update all usages from `jwtauth.X` to
  `httpauthjwt.X`
- Dependency `code.nochebuena.dev/go/httpauth` bumped to v1.0.0
- Dependency `code.nochebuena.dev/go/rbac` bumped to v1.0.0 (indirect)

### 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.