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
This commit is contained in:
98
README.md
Normal file
98
README.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# einherjar/auth-jwt
|
||||
|
||||
[](https://code.nochebuena.dev/einherjar/auth-jwt)
|
||||
[](LICENSE)
|
||||
[](https://go.dev)
|
||||
|
||||
> A warrior's seal is recognized anywhere — but only if it cannot be forged.
|
||||
|
||||
JWT authentication middleware and token lifecycle management for the Einherjar framework.
|
||||
Supports HMAC-SHA256 (HS256), RSA-SHA256 (RS256), and ECDSA (ES256/ES384/ES512).
|
||||
|
||||
## API
|
||||
|
||||
| Symbol | Kind | Description |
|
||||
|---|---|---|
|
||||
| `Verifier` | interface | Validates JWT strings |
|
||||
| `Signer` | interface | Extends `Verifier`; also signs tokens |
|
||||
| `NewHMACSigner(secret)` | func | HS256 signer |
|
||||
| `NewRSASigner(key)` | func | RS256 signer |
|
||||
| `NewRSASignerFromPEM(pem)` | func | RS256 signer from PKCS#8/PKCS#1 PEM |
|
||||
| `NewRSAPublicKeyVerifier(key)` | func | RS256 verifier (verify-only) |
|
||||
| `NewRSAPublicKeyVerifierFromPEM(pem)` | func | RS256 verifier from PKIX/PKCS#1 PEM |
|
||||
| `NewECSigner(key)` | func | ES256/384/512 signer (curve auto-detected) |
|
||||
| `NewECSignerFromPEM(pem)` | func | EC signer from PKCS#8 PEM |
|
||||
| `NewECPublicKeyVerifier(key)` | func | EC verifier (verify-only) |
|
||||
| `NewECPublicKeyVerifierFromPEM(pem)` | func | EC verifier from PKIX PEM |
|
||||
| `TokenConfig` | struct | AccessTTL, RefreshTTL, Issuer |
|
||||
| `TokenPair` | struct | AccessToken, RefreshToken, ExpiresIn |
|
||||
| `IssueTokenPair(signer, uid, claims, cfg)` | func | Sign access + refresh pair |
|
||||
| `Blacklist` | interface | JTI revocation store (duck-typed by cache-valkey) |
|
||||
| `ErrTokenRevoked` | var | Sentinel for replay-attack detection |
|
||||
| `RefreshTokenPair(ctx, signer, token, bl, cfg, claims)` | func | Rotate tokens with blacklist check |
|
||||
| `AuthMiddleware(logger, verifier, publicPaths)` | func | HTTP middleware — verifies Bearer token, calls `authmw.SetTokenData` |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```
|
||||
contracts/logging ──► auth-jwt
|
||||
contracts/security ──► auth-jwt (via auth/authmw)
|
||||
core/xerrors ──► auth-jwt
|
||||
web/httputil ──► auth-jwt
|
||||
auth/authmw ──► auth-jwt
|
||||
jwt/v5 ──► auth-jwt (only external dependency)
|
||||
```
|
||||
|
||||
## Wiring example — HMAC, full stack
|
||||
|
||||
```go
|
||||
import (
|
||||
"code.nochebuena.dev/einherjar/auth-jwt"
|
||||
"code.nochebuena.dev/einherjar/auth/authmw"
|
||||
"code.nochebuena.dev/einherjar/auth/rbac"
|
||||
)
|
||||
|
||||
signer := authjwt.NewHMACSigner([]byte(os.Getenv("JWT_SECRET")))
|
||||
cfg := authjwt.TokenConfig{
|
||||
AccessTTL: 15 * time.Minute,
|
||||
RefreshTTL: 7 * 24 * time.Hour,
|
||||
Issuer: "myapp",
|
||||
}
|
||||
|
||||
// JWT verification runs first (global).
|
||||
srv.Use(authjwt.AuthMiddleware(logger, signer, []string{"/health", "/auth/*"}))
|
||||
|
||||
// Enrichment and authz follow.
|
||||
srv.Use(authmw.EnrichmentMiddleware(logger, userEnricher))
|
||||
|
||||
const ReadOrders = security.Permission(0)
|
||||
srv.With(authmw.AuthzMiddleware(logger, permissions, "orders", ReadOrders)).
|
||||
Get("/orders", ordersHandler)
|
||||
|
||||
// Login handler issues tokens:
|
||||
pair, err := authjwt.IssueTokenPair(signer, uid, customClaims, cfg)
|
||||
|
||||
// Refresh handler rotates tokens:
|
||||
newPair, err := authjwt.RefreshTokenPair(ctx, signer, body.RefreshToken, blacklist, cfg, freshClaims)
|
||||
if errors.Is(err, authjwt.ErrTokenRevoked) {
|
||||
// replay attack — return 401 and require re-login
|
||||
}
|
||||
```
|
||||
|
||||
## Verifier-only microservice (RSA)
|
||||
|
||||
```go
|
||||
// Service that verifies tokens but never issues them.
|
||||
verifier, err := authjwt.NewRSAPublicKeyVerifierFromPEM([]byte(os.Getenv("RSA_PUBLIC_KEY_PEM")))
|
||||
srv.Use(authjwt.AuthMiddleware(logger, verifier, publicPaths))
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
None. All configuration is passed in code.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
go get code.nochebuena.dev/einherjar/auth-jwt@v1.0.0
|
||||
```
|
||||
Reference in New Issue
Block a user