Files

feat(auth-jwt): initial implementation — JWT lifecycle and AuthMiddleware (v1.0.0)

Introduces code.nochebuena.dev/einherjar/auth-jwt — JWT authentication middleware
and token lifecycle management for the Einherjar framework. Absorbs httpauth-jwt
from micro-lib with three changes: logger parameter on AuthMiddleware, httputil.Error
for consistent 401 responses, and added ECDSA support.

Signers and Verifiers (one file per implementation — CT-6 compliant):
- Verifier interface — Verify(tokenString string) (*jwt.Token, error)
- Signer interface — extends Verifier; adds Sign(claims jwt.Claims) (string, error)
- signer_hmac.go — NewHMACSigner(secret) → HS256; jwt.WithJSONNumber() on Verify
- signer_rsa.go — NewRSASigner(key) + NewRSASignerFromPEM(pem) → RS256
- verifier_rsa.go — NewRSAPublicKeyVerifier + NewRSAPublicKeyVerifierFromPEM → RS256 verify-only
- signer_ec.go — NewECSigner(key) + NewECSignerFromPEM(pem) → ES256/384/512; algorithm
  auto-detected from key curve (P-256→ES256, P-384→ES384, P-521→ES512)
- verifier_ec.go — NewECPublicKeyVerifier + NewECPublicKeyVerifierFromPEM → EC verify-only

Token lifecycle:
- TokenConfig struct — AccessTTL, RefreshTTL, Issuer
- TokenPair struct — AccessToken, RefreshToken, ExpiresIn
- IssueTokenPair — access + refresh pair; customClaims merged at top level; refresh
  carries only sub/iss/iat/exp/jti/fam; jwt.WithJSONNumber() preserves int64 bitmasks
- Blacklist interface — IsRevoked + Revoke; satisfied by cache-valkey via duck typing
- ErrTokenRevoked — errors.New sentinel; errors.Is pattern for replay-attack detection
- RefreshTokenPair — verifies token, checks blacklist, revokes old JTI, issues new pair

HTTP middleware:
- AuthMiddleware(logger, verifier, publicPaths) — verifies Bearer tokens; calls
  authmw.SetTokenData on success; 401 routed through httputil.Error (Warn level);
  publicPaths use path.Match wildcards; accepts Verifier (not Signer) to enforce
  narrowest-interface principle for verify-only services

Compliance test (package authjwt_test) enforces CT-6 (≤1 exported TypeSpec/file),
compile-time interface satisfaction, and behavioural coverage: HMAC/RSA/EC sign+verify,
algorithm mismatch rejection, IssueTokenPair claims/jti/fam, RefreshTokenPair success/
revoked/blacklist-error/custom-claims, MaxInt64 json.Number precision, AuthMiddleware
valid/invalid/expired/missing/public-path/wildcard/JSON-body/RSA-verifier/SetTokenData.

Depends on auth v1.0.0, contracts v1.0.0, core v1.0.0, web v1.0.0, jwt/v5 v5.2.1.

- identifiable.go: package-level Module variable (observability.Identifiable) for version
  identification — auth-jwt is a function library; not registered with the launcher

2026-05-29 16:13:01 +00:00

2.3 KiB

Raw Permalink Blame History

Changelog

v1.0.0

Initial release.

Signers and Verifiers

Verifier interface — Verify(tokenString string) (*jwt.Token, error)
Signer interface — extends Verifier; adds Sign(claims jwt.Claims) (string, error)
NewHMACSigner(secret []byte) Signer — HMAC-SHA256 (HS256)
NewRSASigner(privateKey *rsa.PrivateKey) Signer — RSA-SHA256 (RS256); public key derived from private
NewRSASignerFromPEM(pemKey []byte) (Signer, error) — parses PKCS#8 or PKCS#1 PEM
NewRSAPublicKeyVerifier(publicKey *rsa.PublicKey) Verifier — verify-only; use when the service never issues tokens
NewRSAPublicKeyVerifierFromPEM(pemKey []byte) (Verifier, error) — parses PKIX or PKCS#1 PEM
NewECSigner(privateKey *ecdsa.PrivateKey) Signer — ECDSA; algorithm auto-detected from curve (P-256→ES256, P-384→ES384, P-521→ES512)
NewECSignerFromPEM(pemKey []byte) (Signer, error) — parses PKCS#8 PEM
NewECPublicKeyVerifier(publicKey *ecdsa.PublicKey) Verifier — EC verify-only
NewECPublicKeyVerifierFromPEM(pemKey []byte) (Verifier, error) — parses PKIX PEM
All Verify implementations use jwt.WithJSONNumber() — preserves large int64 bitmasks through JSON round-trip

Token issuance

TokenConfig struct — AccessTTL time.Duration, RefreshTTL time.Duration, Issuer string
TokenPair struct — AccessToken string, RefreshToken string, ExpiresIn int64
IssueTokenPair(signer, uid, customClaims, cfg) (TokenPair, error) — signs access + refresh pair; customClaims merged at top level of access token; refresh token carries only sub/iss/iat/exp/jti/fam

Token refresh

Blacklist interface — IsRevoked(ctx, jti) (bool, error) + Revoke(ctx, jti, ttl) error; satisfied by cache-valkey via duck typing
ErrTokenRevoked — sentinel error; use errors.Is(err, authjwt.ErrTokenRevoked) to detect replay attacks
RefreshTokenPair(ctx, signer, refreshToken, bl, cfg, customClaims) (TokenPair, error) — validates token, checks blacklist, revokes old JTI, issues new pair; customClaims re-embedded in new access token

HTTP middleware

AuthMiddleware(logger, verifier, publicPaths) func(http.Handler) http.Handler — verifies Bearer tokens; calls authmw.SetTokenData on success; routes 401 through httputil.Error; publicPaths support path.Match wildcards

2.3 KiB Raw Permalink Blame History

Changelog

v1.0.0

Signers and Verifiers

Token issuance

Token refresh

HTTP middleware

2.3 KiB

Raw Permalink Blame History