diff --git a/auth/genericjwt/go.mod b/auth/genericjwt/go.mod new file mode 100644 index 0000000..f839786 --- /dev/null +++ b/auth/genericjwt/go.mod @@ -0,0 +1,3 @@ +module github.com/therootcompany/golib/auth/genericjwt + +go 1.24.0 diff --git a/auth/genericjwt/jwt.go b/auth/genericjwt/jwt.go new file mode 100644 index 0000000..916c9d4 --- /dev/null +++ b/auth/genericjwt/jwt.go @@ -0,0 +1,556 @@ +// Copyright 2025 AJ ONeal (https://therootcompany.com) +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +// +// SPDX-License-Identifier: MPL-2.0 + +package genericjwt + +import ( + "crypto" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/rsa" + "crypto/sha256" + "encoding/asn1" + "encoding/base64" + "encoding/json" + "fmt" + "math/big" + "slices" + "strings" + "time" +) + +// Validatable is the constraint for the Claims type parameter C. +// +// Custom claims types must implement Validate so that [JWS.Validate] can +// delegate claim-specific logic to the claims type itself. Implementations +// should call [ValidateStandardClaims] for the embedded [StandardClaims] and +// append any application-specific checks. +// +// Note: params.Now is set to time.Now() by [JWS.Validate] before delegation, +// so implementations may rely on it being non-zero. +type Validatable interface { + Validate(params ValidateParams) ([]string, error) +} + +// JWS is a decoded JSON Web Signature / JWT, generic over the claims type C. +// +// Typical usage: +// +// jws, err := genericjwt.Decode[MyClaims](tokenString) +// jws.UnsafeVerify(pubKey) +// errs, err := jws.Validate(params) +type JWS[C Validatable] struct { + Protected string `json:"-"` // base64url-encoded header + Header StandardHeader `json:"header"` + Payload string `json:"-"` // base64url-encoded claims + Claims C `json:"claims"` + Signature URLBase64 `json:"signature"` + Verified bool `json:"-"` +} + +// StandardHeader holds the standard JOSE header fields. +type StandardHeader struct { + Alg string `json:"alg"` + Kid string `json:"kid"` + Typ string `json:"typ"` +} + +// StandardClaims holds the registered JWT claim names defined in RFC 7519 +// and extended by OpenID Connect Core. +type StandardClaims struct { + Iss string `json:"iss"` + Sub string `json:"sub"` + Aud string `json:"aud"` + Exp int64 `json:"exp"` + Iat int64 `json:"iat"` + AuthTime int64 `json:"auth_time"` + Nonce string `json:"nonce,omitempty"` + Amr []string `json:"amr"` + Azp string `json:"azp,omitempty"` + Jti string `json:"jti"` +} + +// Decode parses a compact JWT string (header.payload.signature) into a JWS[C]. +// +// It does not verify the signature. Call [JWS.UnsafeVerify] before [JWS.Validate]. +func Decode[C Validatable](tokenStr string) (JWS[C], error) { + parts := strings.Split(tokenStr, ".") + if len(parts) != 3 { + return JWS[C]{}, fmt.Errorf("invalid JWT format") + } + + var jws JWS[C] + var sigEnc string + jws.Protected, jws.Payload, sigEnc = parts[0], parts[1], parts[2] + + header, err := base64.RawURLEncoding.DecodeString(jws.Protected) + if err != nil { + return jws, fmt.Errorf("invalid header encoding: %v", err) + } + if err := json.Unmarshal(header, &jws.Header); err != nil { + return jws, fmt.Errorf("invalid header JSON: %v", err) + } + + payload, err := base64.RawURLEncoding.DecodeString(jws.Payload) + if err != nil { + return jws, fmt.Errorf("invalid claims encoding: %v", err) + } + if err := json.Unmarshal(payload, &jws.Claims); err != nil { + return jws, fmt.Errorf("invalid claims JSON: %v", err) + } + + if err := jws.Signature.UnmarshalJSON([]byte(sigEnc)); err != nil { + return jws, fmt.Errorf("invalid signature encoding: %v", err) + } + + return jws, nil +} + +// NewJWSFromClaims creates an unsigned JWS[C] from the provided claims. +// +// kid identifies the signing key (used to populate the header's "kid" field). +// The "alg" header field is set automatically when [JWS.Sign] is called. +// Call [JWS.Encode] to produce a compact JWT string after signing. +func NewJWSFromClaims[C Validatable](claims C, kid string) (JWS[C], error) { + var jws JWS[C] + + jws.Header = StandardHeader{ + // Alg is set by Sign based on the key type. + Kid: kid, + Typ: "JWT", + } + headerJSON, _ := json.Marshal(jws.Header) + jws.Protected = base64.RawURLEncoding.EncodeToString(headerJSON) + + claimsJSON, _ := json.Marshal(claims) + jws.Payload = base64.RawURLEncoding.EncodeToString(claimsJSON) + jws.Claims = claims + + return jws, nil +} + +// Sign signs the JWS in-place using the provided [crypto.Signer]. +// It determines the algorithm from the signer's public key type, sets the +// "alg" header field, re-encodes the protected header, then signs. +// +// Supported public key types: +// - *ecdsa.PublicKey → ES256 (ECDSA P-256, raw r||s) +// - *rsa.PublicKey → RS256 (PKCS#1 v1.5 + SHA-256) +// +// Because the parameter is [crypto.Signer] rather than a concrete key type, +// hardware-backed keys (HSM, OS keychain, etc.) work without modification. +func (jws *JWS[C]) Sign(key crypto.Signer) ([]byte, error) { + switch pub := key.Public().(type) { + case *ecdsa.PublicKey: + jws.Header.Alg = "ES256" + headerJSON, _ := json.Marshal(jws.Header) + jws.Protected = base64.RawURLEncoding.EncodeToString(headerJSON) + + hash := sha256.Sum256([]byte(jws.Protected + "." + jws.Payload)) + // crypto.Signer returns ASN.1 DER for ECDSA; convert to raw r||s for JWS. + derSig, err := key.Sign(rand.Reader, hash[:], crypto.SHA256) + if err != nil { + return nil, fmt.Errorf("Sign ES256: %w", err) + } + jws.Signature, err = ecdsaDERToRaw(derSig, pub.Curve) + return jws.Signature, err + + case *rsa.PublicKey: + jws.Header.Alg = "RS256" + headerJSON, _ := json.Marshal(jws.Header) + jws.Protected = base64.RawURLEncoding.EncodeToString(headerJSON) + + hash := sha256.Sum256([]byte(jws.Protected + "." + jws.Payload)) + // crypto.Signer returns raw PKCS#1 v1.5 bytes for RSA; use directly. + var err error + jws.Signature, err = key.Sign(rand.Reader, hash[:], crypto.SHA256) + return jws.Signature, err + + default: + return nil, fmt.Errorf("Sign: unsupported public key type %T (supported: *ecdsa.PublicKey, *rsa.PublicKey)", key.Public()) + } +} + +// Encode produces the compact JWT string (header.payload.signature). +func (jws JWS[C]) Encode() string { + sigEnc := base64.RawURLEncoding.EncodeToString(jws.Signature) + return jws.Protected + "." + jws.Payload + "." + sigEnc +} + +// UnsafeVerify checks the signature using the algorithm in the JWT header and +// sets jws.Verified on success. It only checks the signature — use +// [JWS.Validate] to check claim values. +// +// pub must be of the concrete type matching the header alg (e.g. +// *ecdsa.PublicKey for ES256). Callers can pass PublicJWK[K].Key directly +// without first narrowing to a concrete type. +// +// Currently supported: ES256, RS256. +func (jws *JWS[C]) UnsafeVerify(pub Key) bool { + signingInput := jws.Protected + "." + jws.Payload + + hash := sha256.Sum256([]byte(signingInput)) + + switch jws.Header.Alg { + case "ES256": + k, ok := pub.(*ecdsa.PublicKey) + if !ok || len(jws.Signature) != 64 { + jws.Verified = false + return false + } + r := new(big.Int).SetBytes(jws.Signature[:32]) + s := new(big.Int).SetBytes(jws.Signature[32:]) + jws.Verified = ecdsa.Verify(k, hash[:], r, s) + case "RS256": + k, ok := pub.(*rsa.PublicKey) + if !ok { + jws.Verified = false + return false + } + jws.Verified = rsa.VerifyPKCS1v15(k, crypto.SHA256, hash[:], jws.Signature) == nil + default: + jws.Verified = false + } + return jws.Verified +} + +// Validate sets params.Now if zero, then delegates to jws.Claims.Validate and +// additionally enforces that the signature was verified (unless params.IgnoreSig). +// +// Returns a list of human-readable errors and a non-nil sentinel if any exist. +func (jws *JWS[C]) Validate(params ValidateParams) ([]string, error) { + if params.Now.IsZero() { + params.Now = time.Now() + } + + errs, _ := jws.Claims.Validate(params) + + if !params.IgnoreSig && !jws.Verified { + errs = append(errs, "signature was not checked") + } + + if len(errs) > 0 { + timeInfo := fmt.Sprintf("info: server time is %s", params.Now.Format("2006-01-02 15:04:05 MST")) + if loc, err := time.LoadLocation("Local"); err == nil { + timeInfo += fmt.Sprintf(" %s", loc) + } + errs = append(errs, timeInfo) + return errs, fmt.Errorf("has errors") + } + return nil, nil +} + +// ValidateParams holds validation configuration. +// https://openid.net/specs/openid-connect-core-1_0.html#IDToken +type ValidateParams struct { + Now time.Time + IgnoreIss bool + Iss string + IgnoreSub bool + Sub string + IgnoreAud bool + Aud string + IgnoreExp bool + IgnoreJti bool + Jti string + IgnoreIat bool + IgnoreAuthTime bool + MaxAge time.Duration + IgnoreNonce bool + Nonce string + IgnoreAmr bool + RequiredAmrs []string + IgnoreAzp bool + Azp string + IgnoreSig bool +} + +// ValidateStandardClaims checks the registered JWT/OIDC claim fields. +// +// This is the shared implementation that custom claims types should call +// from their [Validatable.Validate] method. It does NOT check the signature +// or append the server-time info line (both are handled by [JWS.Validate]). +// +// params.Now must be non-zero; [JWS.Validate] ensures this before delegating. +func ValidateStandardClaims(claims StandardClaims, params ValidateParams) ([]string, error) { + var errs []string + + // Required to exist and match + if len(params.Iss) > 0 || !params.IgnoreIss { + if len(claims.Iss) == 0 { + errs = append(errs, "missing or malformed 'iss' (token issuer, identifier for public key)") + } else if claims.Iss != params.Iss { + errs = append(errs, fmt.Sprintf("'iss' (token issuer) mismatch: got %s, expected %s", claims.Iss, params.Iss)) + } + } + + // Required to exist, optional match + if len(claims.Sub) == 0 { + if !params.IgnoreSub { + errs = append(errs, "missing or malformed 'sub' (subject, typically pairwise user id)") + } + } else if len(params.Sub) > 0 { + if params.Sub != claims.Sub { + errs = append(errs, fmt.Sprintf("'sub' (subject) mismatch: got %s, expected %s", claims.Sub, params.Sub)) + } + } + + // Required to exist and match + if len(params.Aud) > 0 || !params.IgnoreAud { + if len(claims.Aud) == 0 { + errs = append(errs, "missing or malformed 'aud' (audience receiving token)") + } else if claims.Aud != params.Aud { + errs = append(errs, fmt.Sprintf("'aud' (audience) mismatch: got %s, expected %s", claims.Aud, params.Aud)) + } + } + + // Required to exist and not be in the past + if !params.IgnoreExp { + if claims.Exp <= 0 { + errs = append(errs, "missing or malformed 'exp' (expiration date in seconds)") + } else if claims.Exp < params.Now.Unix() { + duration := time.Since(time.Unix(claims.Exp, 0)) + expTime := time.Unix(claims.Exp, 0).Format("2006-01-02 15:04:05 MST") + errs = append(errs, fmt.Sprintf("token expired %s ago (%s)", formatDuration(duration), expTime)) + } + } + + // Required to exist and not be in the future + if !params.IgnoreIat { + if claims.Iat <= 0 { + errs = append(errs, "missing or malformed 'iat' (issued at, when token was signed)") + } else if claims.Iat > params.Now.Unix() { + duration := time.Unix(claims.Iat, 0).Sub(params.Now) + iatTime := time.Unix(claims.Iat, 0).Format("2006-01-02 15:04:05 MST") + errs = append(errs, fmt.Sprintf("'iat' (issued at) is %s in the future (%s)", formatDuration(duration), iatTime)) + } + } + + // Should exist, in the past, with optional max age + if params.MaxAge > 0 || !params.IgnoreAuthTime { + if claims.AuthTime == 0 { + errs = append(errs, "missing or malformed 'auth_time' (time of real-world user authentication, in seconds)") + } else { + authTime := time.Unix(claims.AuthTime, 0) + authTimeStr := authTime.Format("2006-01-02 15:04:05 MST") + age := params.Now.Sub(authTime) + diff := age - params.MaxAge + if claims.AuthTime > params.Now.Unix() { + fromNow := time.Unix(claims.AuthTime, 0).Sub(params.Now) + errs = append(errs, fmt.Sprintf( + "'auth_time' of %s is %s in the future (server time %s)", + authTimeStr, formatDuration(fromNow), params.Now.Format("2006-01-02 15:04:05 MST")), + ) + } else if params.MaxAge > 0 && age > params.MaxAge { + errs = append(errs, fmt.Sprintf( + "'auth_time' of %s is %s old, exceeding max age %s by %s", + authTimeStr, formatDuration(age), formatDuration(params.MaxAge), formatDuration(diff)), + ) + } + } + } + + // Optional exact match + if params.Jti != claims.Jti { + if len(params.Jti) > 0 { + errs = append(errs, fmt.Sprintf("'jti' (jwt id) mismatch: got %s, expected %s", claims.Jti, params.Jti)) + } else if !params.IgnoreJti { + errs = append(errs, fmt.Sprintf("unchecked 'jti' (jwt id): %s", claims.Jti)) + } + } + + // Optional exact match + if params.Nonce != claims.Nonce { + if len(params.Nonce) > 0 { + errs = append(errs, fmt.Sprintf("'nonce' mismatch: got %s, expected %s", claims.Nonce, params.Nonce)) + } else if !params.IgnoreNonce { + errs = append(errs, fmt.Sprintf("unchecked 'nonce': %s", claims.Nonce)) + } + } + + // Should exist, optional required-set check + if !params.IgnoreAmr { + if len(claims.Amr) == 0 { + errs = append(errs, "missing or malformed 'amr' (authorization methods, as json list)") + } else if len(params.RequiredAmrs) > 0 { + for _, required := range params.RequiredAmrs { + if !slices.Contains(claims.Amr, required) { + errs = append(errs, fmt.Sprintf("missing required '%s' from 'amr'", required)) + } + } + } + } + + // Optional, match if present + if params.Azp != claims.Azp { + if len(params.Azp) > 0 { + errs = append(errs, fmt.Sprintf("'azp' (authorized party) mismatch: got %s, expected %s", claims.Azp, params.Azp)) + } else if !params.IgnoreAzp { + errs = append(errs, fmt.Sprintf("unchecked 'azp' (authorized party): %s", claims.Azp)) + } + } + + if len(errs) > 0 { + return errs, fmt.Errorf("has errors") + } + return nil, nil +} + +// --- Private key / signing helpers --- + +// JWK represents a private key in JSON Web Key format (EC only). +type JWK struct { + Kty string `json:"kty"` + Crv string `json:"crv"` + D string `json:"d"` + X string `json:"x"` + Y string `json:"y"` +} + +// UnmarshalJWK parses an EC private key from a JWK struct. +func UnmarshalJWK(jwk JWK) (*ecdsa.PrivateKey, error) { + x, err := base64.RawURLEncoding.DecodeString(jwk.X) + if err != nil { + return nil, fmt.Errorf("invalid JWK X: %v", err) + } + y, err := base64.RawURLEncoding.DecodeString(jwk.Y) + if err != nil { + return nil, fmt.Errorf("invalid JWK Y: %v", err) + } + d, err := base64.RawURLEncoding.DecodeString(jwk.D) + if err != nil { + return nil, fmt.Errorf("invalid JWK D: %v", err) + } + + return &ecdsa.PrivateKey{ + PublicKey: ecdsa.PublicKey{ + Curve: elliptic.P256(), + X: new(big.Int).SetBytes(x), + Y: new(big.Int).SetBytes(y), + }, + D: new(big.Int).SetBytes(d), + }, nil +} + +// Thumbprint computes the RFC 7638 JWK Thumbprint for an EC public key. +func (jwk JWK) Thumbprint() (string, error) { + data := map[string]string{ + "crv": jwk.Crv, + "kty": jwk.Kty, + "x": jwk.X, + "y": jwk.Y, + } + jsonData, err := json.Marshal(data) + if err != nil { + return "", err + } + hash := sha256.Sum256(jsonData) + return base64.RawURLEncoding.EncodeToString(hash[:]), nil +} + +// SignES256 computes an ES256 signature over header.payload. +// The signature is a fixed-width raw r||s value (not ASN.1 DER). +// Each component is zero-padded to the curve's byte length. +func SignES256(header, payload string, key *ecdsa.PrivateKey) ([]byte, error) { + hash := sha256.Sum256([]byte(header + "." + payload)) + r, s, err := ecdsa.Sign(rand.Reader, key, hash[:]) + if err != nil { + return nil, fmt.Errorf("SignES256: %w", err) + } + byteLen := (key.Curve.Params().BitSize + 7) / 8 + out := make([]byte, 2*byteLen) + r.FillBytes(out[:byteLen]) + s.FillBytes(out[byteLen:]) + return out, nil +} + +// SignRS256 computes an RS256 (PKCS#1 v1.5 + SHA-256) signature over header.payload. +func SignRS256(header, payload string, key *rsa.PrivateKey) ([]byte, error) { + hash := sha256.Sum256([]byte(header + "." + payload)) + sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, hash[:]) + if err != nil { + return nil, fmt.Errorf("SignRS256: %w", err) + } + return sig, nil +} + +// ecdsaDERToRaw converts an ASN.1 DER ECDSA signature (as returned by +// [crypto.Signer]) to the fixed-width r||s format required by JWS. +func ecdsaDERToRaw(der []byte, curve elliptic.Curve) ([]byte, error) { + var sig struct{ R, S *big.Int } + if _, err := asn1.Unmarshal(der, &sig); err != nil { + return nil, fmt.Errorf("ecdsaDERToRaw: %w", err) + } + byteLen := (curve.Params().BitSize + 7) / 8 + out := make([]byte, 2*byteLen) + sig.R.FillBytes(out[:byteLen]) + sig.S.FillBytes(out[byteLen:]) + return out, nil +} + +// EncodeToJWT appends a base64url-encoded signature to a signing input. +func EncodeToJWT(signingInput string, signature []byte) string { + sigEnc := base64.RawURLEncoding.EncodeToString(signature) + return signingInput + "." + sigEnc +} + +// URLBase64 is a []byte that marshals to/from raw base64url in JSON. +type URLBase64 []byte + +func (s URLBase64) String() string { + return base64.RawURLEncoding.EncodeToString(s) +} + +func (s URLBase64) MarshalJSON() ([]byte, error) { + encoded := base64.RawURLEncoding.EncodeToString(s) + return json.Marshal(encoded) +} + +func (s *URLBase64) UnmarshalJSON(data []byte) error { + dst, err := base64.RawURLEncoding.AppendDecode([]byte{}, data) + if err != nil { + return fmt.Errorf("decode base64url signature: %w", err) + } + *s = dst + return nil +} + +func formatDuration(d time.Duration) string { + if d < 0 { + d = -d + } + days := int(d / (24 * time.Hour)) + d -= time.Duration(days) * 24 * time.Hour + hours := int(d / time.Hour) + d -= time.Duration(hours) * time.Hour + minutes := int(d / time.Minute) + d -= time.Duration(minutes) * time.Minute + seconds := int(d / time.Second) + + var parts []string + if days > 0 { + parts = append(parts, fmt.Sprintf("%dd", days)) + } + if hours > 0 { + parts = append(parts, fmt.Sprintf("%dh", hours)) + } + if minutes > 0 { + parts = append(parts, fmt.Sprintf("%dm", minutes)) + } + if seconds > 0 || len(parts) == 0 { + parts = append(parts, fmt.Sprintf("%ds", seconds)) + } + if seconds == 0 || len(parts) == 0 { + d -= time.Duration(seconds) * time.Second + millis := int(d / time.Millisecond) + parts = append(parts, fmt.Sprintf("%dms", millis)) + } + + return strings.Join(parts, " ") +} diff --git a/auth/genericjwt/jwt_test.go b/auth/genericjwt/jwt_test.go new file mode 100644 index 0000000..372b29d --- /dev/null +++ b/auth/genericjwt/jwt_test.go @@ -0,0 +1,294 @@ +// Copyright 2025 AJ ONeal (https://therootcompany.com) +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +// +// SPDX-License-Identifier: MPL-2.0 + +package genericjwt_test + +import ( + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/rsa" + "fmt" + "testing" + "time" + + "github.com/therootcompany/golib/auth/genericjwt" +) + +// AppClaims is an example custom claims type that satisfies [genericjwt.Validatable] +// by explicitly delegating to [genericjwt.ValidateStandardClaims]. +// +// Unlike embeddedjwt, there is no promoted Validate here — genericjwt's +// StandardClaims has no Validate method, so the application type always owns +// the implementation. This keeps the generics constraint explicit. +type AppClaims struct { + genericjwt.StandardClaims + Email string `json:"email"` + Roles []string `json:"roles"` +} + +func (c AppClaims) Validate(params genericjwt.ValidateParams) ([]string, error) { + return genericjwt.ValidateStandardClaims(c.StandardClaims, params) +} + +// StrictAppClaims adds an application-specific check (non-empty Email) on top +// of the standard OIDC validation. +type StrictAppClaims struct { + genericjwt.StandardClaims + Email string `json:"email"` +} + +func (c StrictAppClaims) Validate(params genericjwt.ValidateParams) ([]string, error) { + errs, _ := genericjwt.ValidateStandardClaims(c.StandardClaims, params) + if c.Email == "" { + errs = append(errs, "missing email claim") + } + if len(errs) > 0 { + return errs, fmt.Errorf("has errors") + } + return nil, nil +} + +func goodClaims() AppClaims { + now := time.Now() + return AppClaims{ + StandardClaims: genericjwt.StandardClaims{ + Iss: "https://example.com", + Sub: "user123", + Aud: "myapp", + Exp: now.Add(time.Hour).Unix(), + Iat: now.Unix(), + AuthTime: now.Unix(), + Amr: []string{"pwd"}, + Jti: "abc123", + Azp: "myapp", + Nonce: "nonce1", + }, + Email: "user@example.com", + Roles: []string{"admin"}, + } +} + +func goodParams() genericjwt.ValidateParams { + return genericjwt.ValidateParams{ + Iss: "https://example.com", + Sub: "user123", + Aud: "myapp", + Jti: "abc123", + Nonce: "nonce1", + Azp: "myapp", + RequiredAmrs: []string{"pwd"}, + } +} + +// TestRoundTrip is the primary happy path demonstrating the core genericjwt +// ergonomic: Decode[AppClaims] places the type parameter at the call site and +// returns a JWS[AppClaims] whose Claims field is directly typed — no interface, +// no type assertion ever needed. +func TestRoundTrip(t *testing.T) { + privKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + + claims := goodClaims() + jws, err := genericjwt.NewJWSFromClaims(claims, "key-1") + if err != nil { + t.Fatal(err) + } + + if _, err = jws.Sign(privKey); err != nil { + t.Fatal(err) + } + if jws.Header.Alg != "ES256" { + t.Fatalf("expected ES256, got %s", jws.Header.Alg) + } + + token := jws.Encode() + + // Type parameter at the call site — no pre-allocated claims pointer needed. + jws2, err := genericjwt.Decode[AppClaims](token) + if err != nil { + t.Fatal(err) + } + if !jws2.UnsafeVerify(&privKey.PublicKey) { + t.Fatal("signature verification failed") + } + if errs, err := jws2.Validate(goodParams()); err != nil { + t.Fatalf("validation failed: %v", errs) + } + // Direct field access on jws2.Claims — zero type assertions. + if jws2.Claims.Email != claims.Email { + t.Errorf("email: got %s, want %s", jws2.Claims.Email, claims.Email) + } +} + +// TestRoundTripRS256 exercises RSA PKCS#1 v1.5 / RS256. +func TestRoundTripRS256(t *testing.T) { + privKey, err := rsa.GenerateKey(rand.Reader, 2048) + if err != nil { + t.Fatal(err) + } + + claims := goodClaims() + jws, err := genericjwt.NewJWSFromClaims(claims, "key-1") + if err != nil { + t.Fatal(err) + } + + if _, err = jws.Sign(privKey); err != nil { + t.Fatal(err) + } + if jws.Header.Alg != "RS256" { + t.Fatalf("expected RS256, got %s", jws.Header.Alg) + } + + token := jws.Encode() + + jws2, err := genericjwt.Decode[AppClaims](token) + if err != nil { + t.Fatal(err) + } + if !jws2.UnsafeVerify(&privKey.PublicKey) { + t.Fatal("signature verification failed") + } + if errs, err := jws2.Validate(goodParams()); err != nil { + t.Fatalf("validation failed: %v", errs) + } +} + +// TestUnsafeVerifyWrongKey confirms that a different key's public key does +// not verify the signature. +func TestUnsafeVerifyWrongKey(t *testing.T) { + signingKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + wrongKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + + claims := goodClaims() + jws, _ := genericjwt.NewJWSFromClaims(claims, "k") + _, _ = jws.Sign(signingKey) + token := jws.Encode() + + jws2, _ := genericjwt.Decode[AppClaims](token) + + if jws2.UnsafeVerify(&wrongKey.PublicKey) { + t.Fatal("expected verification to fail with wrong key") + } +} + +// TestVerifyWrongKeyType confirms that an RSA key is rejected for an ES256 token. +func TestVerifyWrongKeyType(t *testing.T) { + ecKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + rsaKey, _ := rsa.GenerateKey(rand.Reader, 2048) + + claims := goodClaims() + jws, _ := genericjwt.NewJWSFromClaims(claims, "k") + _, _ = jws.Sign(ecKey) + token := jws.Encode() + + jws2, _ := genericjwt.Decode[AppClaims](token) + + if jws2.UnsafeVerify(&rsaKey.PublicKey) { + t.Fatal("expected verification to fail: RSA key for ES256 token") + } +} + +// TestVerifyUnknownAlg confirms that a tampered alg header is rejected. +func TestVerifyUnknownAlg(t *testing.T) { + privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + + claims := goodClaims() + jws, _ := genericjwt.NewJWSFromClaims(claims, "k") + _, _ = jws.Sign(privKey) + token := jws.Encode() + + jws2, _ := genericjwt.Decode[AppClaims](token) + jws2.Header.Alg = "none" + + if jws2.UnsafeVerify(&privKey.PublicKey) { + t.Fatal("expected verification to fail for unknown alg") + } +} + +// TestValidateMissingSignatureCheck verifies that Validate fails when +// UnsafeVerify was never called (Verified is false). +func TestValidateMissingSignatureCheck(t *testing.T) { + privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + + claims := goodClaims() + jws, _ := genericjwt.NewJWSFromClaims(claims, "k") + _, _ = jws.Sign(privKey) + token := jws.Encode() + + jws2, _ := genericjwt.Decode[AppClaims](token) + + // Deliberately skip UnsafeVerify. + errs, err := jws2.Validate(goodParams()) + if err == nil { + t.Fatal("expected validation to fail: signature was not checked") + } + found := false + for _, e := range errs { + if e == "signature was not checked" { + found = true + } + } + if !found { + t.Fatalf("expected 'signature was not checked' in errors: %v", errs) + } +} + +// TestVerifyWithJWKSKey verifies that PublicJWK[Key].Key can be passed +// directly to UnsafeVerify — the Key interface satisfies UnsafeVerify's +// parameter constraint without a type assertion. +func TestVerifyWithJWKSKey(t *testing.T) { + privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + jwksKey := genericjwt.PublicJWK[genericjwt.Key]{Key: &privKey.PublicKey, KID: "k1"} + + claims := goodClaims() + jws, _ := genericjwt.NewJWSFromClaims(claims, "k1") + _, _ = jws.Sign(privKey) + token := jws.Encode() + + jws2, _ := genericjwt.Decode[AppClaims](token) + + if !jws2.UnsafeVerify(jwksKey.Key) { + t.Fatal("verification via PublicJWK.Key failed") + } +} + +// TestDecodePublicJWKJSON verifies JWKS JSON parsing and TypedKeys filtering +// with real base64url-encoded key material from RFC 7517 / OIDC examples. +func TestDecodePublicJWKJSON(t *testing.T) { + jwksJSON := []byte(`{"keys":[ + {"kty":"EC","crv":"P-256", + "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", + "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", + "kid":"ec-256","use":"sig"}, + {"kty":"RSA", + "n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", + "e":"AQAB","kid":"rsa-2048","use":"sig"} + ]}`) + + keys, err := genericjwt.UnmarshalPublicJWKs(jwksJSON) + if err != nil { + t.Fatal(err) + } + if len(keys) != 2 { + t.Fatalf("expected 2 keys, got %d", len(keys)) + } + + ecKeys := genericjwt.TypedKeys[*ecdsa.PublicKey](keys) + if len(ecKeys) != 1 || ecKeys[0].KID != "ec-256" { + t.Errorf("EC key mismatch: %+v", ecKeys) + } + + rsaKeys := genericjwt.TypedKeys[*rsa.PublicKey](keys) + if len(rsaKeys) != 1 || rsaKeys[0].KID != "rsa-2048" { + t.Errorf("RSA key mismatch: %+v", rsaKeys) + } +} diff --git a/auth/genericjwt/pub.go b/auth/genericjwt/pub.go new file mode 100644 index 0000000..d6baba0 --- /dev/null +++ b/auth/genericjwt/pub.go @@ -0,0 +1,229 @@ +// Copyright 2025 AJ ONeal (https://therootcompany.com) +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +// +// SPDX-License-Identifier: MPL-2.0 + +package genericjwt + +import ( + "crypto" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rsa" + "encoding/base64" + "encoding/json" + "fmt" + "io" + "math/big" + "net/http" + "os" + "time" +) + +// Key is the constraint for the public key type parameter K used in PublicJWK. +// +// All standard-library asymmetric public key types satisfy this interface +// since Go 1.15: *ecdsa.PublicKey, *rsa.PublicKey, ed25519.PublicKey. +// +// Note: crypto.PublicKey is defined as interface{} and does NOT satisfy Key. +// Use Key itself as the type argument for heterogeneous collections +// (e.g. []PublicJWK[Key]), since Key declares Equal and therefore satisfies +// its own constraint. Use [TypedKeys] to narrow to a concrete type. +type Key interface { + Equal(x crypto.PublicKey) bool +} + +// PublicJWK wraps a parsed public key with its JWKS metadata. +// +// K is constrained to [Key], providing type-safe access to the underlying +// key without a type assertion at each use site. +// +// For a heterogeneous JWKS endpoint (mixed RSA/EC) use PublicJWK[Key]. +// For a homogeneous store use the concrete type directly (e.g. +// PublicJWK[*ecdsa.PublicKey]). Use [TypedKeys] to narrow a mixed slice. +// +// Example — sign with a known key type, no assertion needed: +// +// ecKeys := genericjwt.TypedKeys[*ecdsa.PublicKey](allKeys) +// jws.UnsafeVerify(ecKeys[0].Key) // Key is *ecdsa.PublicKey directly +type PublicJWK[K Key] struct { + Key K + KID string + Use string +} + +// PublicJWKJSON is the JSON representation of a single key in a JWKS document. +type PublicJWKJSON struct { + Kty string `json:"kty"` + KID string `json:"kid"` + N string `json:"n,omitempty"` // RSA modulus + E string `json:"e,omitempty"` // RSA exponent + Crv string `json:"crv,omitempty"` + X string `json:"x,omitempty"` + Y string `json:"y,omitempty"` + Use string `json:"use,omitempty"` +} + +// JWKsJSON is the JSON representation of a JWKS document. +type JWKsJSON struct { + Keys []PublicJWKJSON `json:"keys"` +} + +// TypedKeys filters a heterogeneous []PublicJWK[Key] slice to only those whose +// underlying key is of concrete type K, returning a typed []PublicJWK[K]. +// Keys of other types are silently skipped. +// +// Example — extract only ECDSA keys from a mixed JWKS result: +// +// all, _ := genericjwt.FetchPublicJWKs(jwksURL) +// ecKeys := genericjwt.TypedKeys[*ecdsa.PublicKey](all) +// rsaKeys := genericjwt.TypedKeys[*rsa.PublicKey](all) +func TypedKeys[K Key](keys []PublicJWK[Key]) []PublicJWK[K] { + var result []PublicJWK[K] + for _, k := range keys { + if typed, ok := k.Key.(K); ok { + result = append(result, PublicJWK[K]{Key: typed, KID: k.KID, Use: k.Use}) + } + } + return result +} + +// FetchPublicJWKs retrieves and parses a JWKS document from url. +// Keys are returned as []PublicJWK[Key] since a JWKS endpoint may contain a +// mix of key types. Use [TypedKeys] to narrow to a concrete type. +func FetchPublicJWKs(url string) ([]PublicJWK[Key], error) { + client := &http.Client{Timeout: 10 * time.Second} + resp, err := client.Get(url) + if err != nil { + return nil, fmt.Errorf("failed to fetch JWKS: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("unexpected status code: %d", resp.StatusCode) + } + return DecodePublicJWKs(resp.Body) +} + +// ReadPublicJWKs reads and parses a JWKS document from a file path. +func ReadPublicJWKs(filePath string) ([]PublicJWK[Key], error) { + file, err := os.Open(filePath) + if err != nil { + return nil, fmt.Errorf("failed to open JWKS file '%s': %w", filePath, err) + } + defer func() { _ = file.Close() }() + return DecodePublicJWKs(file) +} + +// UnmarshalPublicJWKs parses a JWKS document from raw JSON bytes. +func UnmarshalPublicJWKs(data []byte) ([]PublicJWK[Key], error) { + var jwks JWKsJSON + if err := json.Unmarshal(data, &jwks); err != nil { + return nil, fmt.Errorf("failed to parse JWKS JSON: %w", err) + } + return DecodePublicJWKsJSON(jwks) +} + +// DecodePublicJWKs parses a JWKS document from an [io.Reader]. +func DecodePublicJWKs(r io.Reader) ([]PublicJWK[Key], error) { + var jwks JWKsJSON + if err := json.NewDecoder(r).Decode(&jwks); err != nil { + return nil, fmt.Errorf("failed to parse JWKS JSON: %w", err) + } + return DecodePublicJWKsJSON(jwks) +} + +// DecodePublicJWKsJSON converts a parsed [JWKsJSON] into typed public keys. +func DecodePublicJWKsJSON(jwks JWKsJSON) ([]PublicJWK[Key], error) { + var keys []PublicJWK[Key] + for _, jwk := range jwks.Keys { + key, err := DecodePublicJWK(jwk) + if err != nil { + return nil, fmt.Errorf("failed to parse public jwk '%s': %w", jwk.KID, err) + } + keys = append(keys, *key) + } + if len(keys) == 0 { + return nil, fmt.Errorf("no valid RSA or ECDSA keys found") + } + return keys, nil +} + +// DecodePublicJWK parses a single [PublicJWKJSON] into a PublicJWK[Key]. +// Supports RSA (minimum 1024-bit) and EC (P-256, P-384, P-521) keys. +func DecodePublicJWK(jwk PublicJWKJSON) (*PublicJWK[Key], error) { + switch jwk.Kty { + case "RSA": + key, err := decodeRSAPublicJWK(jwk) + if err != nil { + return nil, fmt.Errorf("failed to parse RSA key '%s': %w", jwk.KID, err) + } + if key.Size() < 128 { // 1024 bits minimum + return nil, fmt.Errorf("RSA key '%s' too small: %d bytes", jwk.KID, key.Size()) + } + return &PublicJWK[Key]{Key: key, KID: jwk.KID, Use: jwk.Use}, nil + + case "EC": + key, err := decodeECDSAPublicJWK(jwk) + if err != nil { + return nil, fmt.Errorf("failed to parse EC key '%s': %w", jwk.KID, err) + } + return &PublicJWK[Key]{Key: key, KID: jwk.KID, Use: jwk.Use}, nil + + default: + return nil, fmt.Errorf("unsupported key type '%s' for kid '%s'", jwk.Kty, jwk.KID) + } +} + +func decodeRSAPublicJWK(jwk PublicJWKJSON) (*rsa.PublicKey, error) { + n, err := base64.RawURLEncoding.DecodeString(jwk.N) + if err != nil { + return nil, fmt.Errorf("invalid RSA modulus: %w", err) + } + e, err := base64.RawURLEncoding.DecodeString(jwk.E) + if err != nil { + return nil, fmt.Errorf("invalid RSA exponent: %w", err) + } + + eInt := new(big.Int).SetBytes(e).Int64() + if eInt > int64(^uint(0)>>1) || eInt < 0 { + return nil, fmt.Errorf("RSA exponent too large or negative") + } + + return &rsa.PublicKey{ + N: new(big.Int).SetBytes(n), + E: int(eInt), + }, nil +} + +func decodeECDSAPublicJWK(jwk PublicJWKJSON) (*ecdsa.PublicKey, error) { + x, err := base64.RawURLEncoding.DecodeString(jwk.X) + if err != nil { + return nil, fmt.Errorf("invalid ECDSA X: %w", err) + } + y, err := base64.RawURLEncoding.DecodeString(jwk.Y) + if err != nil { + return nil, fmt.Errorf("invalid ECDSA Y: %w", err) + } + + var curve elliptic.Curve + switch jwk.Crv { + case "P-256": + curve = elliptic.P256() + case "P-384": + curve = elliptic.P384() + case "P-521": + curve = elliptic.P521() + default: + return nil, fmt.Errorf("unsupported ECDSA curve: %s", jwk.Crv) + } + + return &ecdsa.PublicKey{ + Curve: curve, + X: new(big.Int).SetBytes(x), + Y: new(big.Int).SetBytes(y), + }, nil +}