root/golib
1
0
Fork 0
mirror of https://github.com/therootcompany/golib.git synced 2026-03-13 12:27:59 +00:00
Code Issues Projects Releases Wiki Activity

feat(auth/bestjwt): add hybrid JWT/JWS/JWK package

Browse Source 
Combines the best ergonomics from genericjwt and embeddedjwt:

- Decode(&claims) pattern (embedded structs, no generics at call sites,
  no type assertion to access custom fields)
- StandardClaims.Validate promoted to any embedding struct via value
  receiver; override Validate on the outer struct for custom checks
- Sign(crypto.Signer): algorithm inferred from key.Public() type switch,
  supports HSM/cloud KMS transparently
- Full ECDSA curve support: ES256 (P-256), ES384 (P-384), ES512 (P-521)
  all inferred automatically from key curve via algForECKey
- Curve/alg consistency check in UnsafeVerify: P-256 key rejected for
  ES384 token and vice versa (prevents cross-algorithm downgrade)
- digestFor: fixed-size stack arrays for SHA-256/384/512 digests
- ecdsaDERToRaw + FillBytes: correct zero-padded r||s conversion from
  ASN.1 DER output of crypto.Signer
- Generic PublicJWK[K Key] + TypedKeys[K]: type-safe JWKS key management,
  filter mixed []PublicJWK[Key] to concrete type without assertions
- JWKS fetch/parse: FetchPublicJWKs, ReadPublicJWKs, UnmarshalPublicJWKs,
  DecodePublicJWKs for RSA and EC (P-256/384/521)
- RS256 (PKCS#1 v1.5 + SHA-256) support via crypto.Signer
- 13 tests covering all algorithms, negative cases, and JWKS integration
This commit is contained in:
AJ ONeal 2026-03-12 17:40:24 -06:00
parent 55a7b9b2f4
commit fac58cf1ad
No known key found for this signature in database
4 changed files with 1416 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
auth/bestjwt/go.mod Normal file
View File

@ -0,0 +1,3 @@
module github.com/therootcompany/golib/auth/bestjwt
go 1.24.0

706
auth/bestjwt/jwt.go Normal file
View File

@ -0,0 +1,706 @@
// Copyright 2025 AJ ONeal <aj@therootcompany.com> (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 bestjwt is a lightweight JWT/JWS/JWK library that combines the
// best ergonomics from the genericjwt and embeddedjwt packages:
//
// - Claims via embedded structs: Decode(token, &myClaims) — no generics at
// call sites, no type assertions to access custom fields.
// - crypto.Signer for all signing: works with in-process keys AND
// hardware-backed keys (HSM, cloud KMS, PKCS#11) without modification.
// - Full ECDSA curve support: ES256 (P-256), ES384 (P-384), ES512 (P-521).
// The algorithm is inferred from the key's curve, not hardcoded.
// - Curve/algorithm consistency enforcement: UnsafeVerify rejects a P-256
// key presented for an ES384 token and vice versa.
// - Generic PublicJWK[K Key]: type-safe JWKS key management with TypedKeys
// to filter a mixed []PublicJWK[Key] to a concrete key type.
package bestjwt
import (
"crypto"
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/rsa"
"crypto/sha256"
"crypto/sha512"
"encoding/asn1"
"encoding/base64"
"encoding/json"
"fmt"
"math/big"
"slices"
"strings"
"time"
)
// Claims is the interface that custom claims types must satisfy.
//
// Because [StandardClaims] implements Claims with a value receiver, any struct
// that embeds StandardClaims satisfies Claims automatically via method
// promotion — no boilerplate required:
//
// type AppClaims struct {
// bestjwt.StandardClaims
// Email string `json:"email"`
// }
// // AppClaims now satisfies Claims for free.
//
// Override Validate on the outer struct to add application-specific checks.
// Call [ValidateStandardClaims] inside your override to preserve all standard
// OIDC/JWT validation.
type Claims interface {
Validate(params ValidateParams) ([]string, error)
}
// JWS is a decoded JSON Web Signature / JWT.
//
// Claims is stored as the [Claims] interface so that any embedded-struct type
// can be used without generics. The most ergonomic access pattern is via the
// pointer you passed to [Decode]:
//
// var claims AppClaims
// jws, err := bestjwt.Decode(tokenString, &claims)
// jws.UnsafeVerify(pubKey)
// errs, err := jws.Validate(params)
// // Access claims.Email, claims.Roles, etc. directly — no type assertion.
type JWS struct {
Protected string `json:"-"` // base64url-encoded header
Header StandardHeader `json:"header"`
Payload string `json:"-"` // base64url-encoded claims
Claims Claims `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.
//
// Embed StandardClaims in your own struct to satisfy [Claims] automatically:
//
// type AppClaims struct {
// bestjwt.StandardClaims
// Email string `json:"email"`
// }
// // AppClaims now satisfies Claims via promoted Validate.
// // Override Validate on AppClaims to add custom checks.
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"`
}
// Validate implements [Claims] by checking all standard OIDC/JWT claim fields.
//
// This method is promoted to any struct that embeds [StandardClaims], so
// embedding structs satisfy Claims without writing any additional code.
// params.Now must be non-zero; [JWS.Validate] ensures this before delegating.
func (c StandardClaims) Validate(params ValidateParams) ([]string, error) {
return ValidateStandardClaims(c, params)
}
// Decode parses a compact JWT string (header.payload.signature) into a JWS.
//
// claims must be a pointer to the caller's pre-allocated claims struct
// (e.g. &AppClaims{}). The JSON payload is unmarshaled directly into it,
// and the same pointer is stored in jws.Claims. Callers can access custom
// fields through their own variable without a type assertion:
//
// var claims AppClaims
// jws, err := bestjwt.Decode(token, &claims)
// // claims.Email is already set; no type assertion needed.
//
// The signature is not verified by Decode. Call [JWS.UnsafeVerify] first,
// then [JWS.Validate].
func Decode(tokenStr string, claims Claims) (*JWS, error) {
parts := strings.Split(tokenStr, ".")
if len(parts) != 3 {
return nil, fmt.Errorf("invalid JWT format")
}
var jws JWS
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 nil, fmt.Errorf("invalid header encoding: %v", err)
}
if err := json.Unmarshal(header, &jws.Header); err != nil {
return nil, fmt.Errorf("invalid header JSON: %v", err)
}
payload, err := base64.RawURLEncoding.DecodeString(jws.Payload)
if err != nil {
return nil, fmt.Errorf("invalid claims encoding: %v", err)
}
// Unmarshal into the concrete type behind the Claims interface.
// json.Unmarshal reaches the concrete pointer via reflection.
if err := json.Unmarshal(payload, claims); err != nil {
return nil, fmt.Errorf("invalid claims JSON: %v", err)
}
if err := jws.Signature.UnmarshalJSON([]byte(sigEnc)); err != nil {
return nil, fmt.Errorf("invalid signature encoding: %v", err)
}
jws.Claims = claims
return &jws, nil
}
// NewJWSFromClaims creates an unsigned JWS from the provided claims.
//
// kid identifies the signing key. The "alg" header field is set automatically
// when [JWS.Sign] is called, since only the key type determines the algorithm.
// Call [JWS.Encode] to produce a compact JWT string after signing.
func NewJWSFromClaims(claims Claims, kid string) (*JWS, error) {
var jws JWS
jws.Header = StandardHeader{
// Alg is intentionally omitted here; Sign sets it from 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].
//
// The algorithm is determined from the signer's public key type and, for EC
// keys, from the curve. The "alg" header field is set and the protected header
// is re-encoded before computing the signing input, so the signed bytes are
// always consistent with the token header.
//
// Supported algorithms (inferred automatically):
// - *ecdsa.PublicKey P-256 → ES256 (ECDSA + SHA-256, raw r||s)
// - *ecdsa.PublicKey P-384 → ES384 (ECDSA + SHA-384, raw r||s)
// - *ecdsa.PublicKey P-521 → ES512 (ECDSA + SHA-512, 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 signers (HSM, OS keychain, cloud KMS) work transparently.
func (jws *JWS) Sign(key crypto.Signer) ([]byte, error) {
switch pub := key.Public().(type) {
case *ecdsa.PublicKey:
alg, h, err := algForECKey(pub)
if err != nil {
return nil, err
}
jws.Header.Alg = alg
headerJSON, _ := json.Marshal(jws.Header)
jws.Protected = base64.RawURLEncoding.EncodeToString(headerJSON)
digest := digestFor(h, 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, digest, h)
if err != nil {
return nil, fmt.Errorf("Sign %s: %w", alg, 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)
digest := digestFor(crypto.SHA256, 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, digest, 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) 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 (expiry, issuer, audience, etc.).
//
// pub must be of the concrete type matching the header alg (e.g.
// *ecdsa.PublicKey for ES256/ES384/ES512). Callers can pass PublicJWK.Key
// directly without a type assertion.
//
// For ECDSA tokens, the key's curve is checked against the claimed algorithm
// (e.g. P-384 key is rejected for an ES256 token) to prevent cross-algorithm
// downgrade attacks.
//
// Currently supported: ES256, ES384, ES512, RS256.
func (jws *JWS) UnsafeVerify(pub Key) bool {
signingInput := jws.Protected + "." + jws.Payload
switch jws.Header.Alg {
case "ES256", "ES384", "ES512":
k, ok := pub.(*ecdsa.PublicKey)
if !ok || k == nil {
jws.Verified = false
return false
}
// Require the key's curve to match the token's claimed algorithm.
// A P-256 key must not verify an ES384 token and vice versa.
expectedAlg, h, err := algForECKey(k)
if err != nil || expectedAlg != jws.Header.Alg {
jws.Verified = false
return false
}
byteLen := (k.Curve.Params().BitSize + 7) / 8
if len(jws.Signature) != 2*byteLen {
jws.Verified = false
return false
}
digest := digestFor(h, signingInput)
r := new(big.Int).SetBytes(jws.Signature[:byteLen])
s := new(big.Int).SetBytes(jws.Signature[byteLen:])
jws.Verified = ecdsa.Verify(k, digest, r, s)
case "RS256":
k, ok := pub.(*rsa.PublicKey)
if !ok || k == nil {
jws.Verified = false
return false
}
digest := digestFor(crypto.SHA256, signingInput)
jws.Verified = rsa.VerifyPKCS1v15(k, crypto.SHA256, digest, 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) 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.
//
// Called by [StandardClaims.Validate] and exported so that custom claims types
// can call it from an overriding Validate method:
//
// func (c AppClaims) Validate(params bestjwt.ValidateParams) ([]string, error) {
// errs, _ := bestjwt.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
// }
//
// 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
}
// --- Signing helpers ---
// SignES256 computes an ES256 signature over header.payload using a P-256 key.
// The signature is a fixed-width 64-byte raw r||s value (not ASN.1 DER).
// Each component is zero-padded to 32 bytes via [big.Int.FillBytes].
func SignES256(header, payload string, key *ecdsa.PrivateKey) ([]byte, error) {
return signEC(header, payload, key, crypto.SHA256)
}
// SignES384 computes an ES384 signature over header.payload using a P-384 key.
// The signature is a fixed-width 96-byte raw r||s value.
func SignES384(header, payload string, key *ecdsa.PrivateKey) ([]byte, error) {
return signEC(header, payload, key, crypto.SHA384)
}
// SignES512 computes an ES512 signature over header.payload using a P-521 key.
// The signature is a fixed-width 132-byte raw r||s value.
func SignES512(header, payload string, key *ecdsa.PrivateKey) ([]byte, error) {
return signEC(header, payload, key, crypto.SHA512)
}
// SignRS256 computes an RS256 (PKCS#1 v1.5 + SHA-256) signature over header.payload.
func SignRS256(header, payload string, key *rsa.PrivateKey) ([]byte, error) {
digest := digestFor(crypto.SHA256, header+"."+payload)
sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, digest)
if err != nil {
return nil, fmt.Errorf("SignRS256: %w", err)
}
return sig, nil
}
// EncodeToJWT appends a base64url-encoded signature to a signing input string.
func EncodeToJWT(signingInput string, signature []byte) string {
return signingInput + "." + base64.RawURLEncoding.EncodeToString(signature)
}
// --- EC private key JWK utilities ---
// 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
}
// --- Internal helpers ---
// algForECKey returns the JWA algorithm name and hash function for an EC public
// key, inferred from its curve. Returns an error for unsupported curves.
func algForECKey(pub *ecdsa.PublicKey) (alg string, h crypto.Hash, err error) {
switch pub.Curve {
case elliptic.P256():
return "ES256", crypto.SHA256, nil
case elliptic.P384():
return "ES384", crypto.SHA384, nil
case elliptic.P521():
return "ES512", crypto.SHA512, nil
default:
return "", 0, fmt.Errorf("unsupported EC curve: %s", pub.Curve.Params().Name)
}
}
// digestFor hashes data with h and returns the digest.
// Uses fixed-size stack arrays for the three supported hashes to avoid
// unnecessary heap allocation on the hot signing/verification path.
func digestFor(h crypto.Hash, data string) []byte {
switch h {
case crypto.SHA256:
d := sha256.Sum256([]byte(data))
return d[:]
case crypto.SHA384:
d := sha512.Sum384([]byte(data))
return d[:]
case crypto.SHA512:
d := sha512.Sum512([]byte(data))
return d[:]
default:
panic(fmt.Sprintf("bestjwt: unsupported hash %v", h))
}
}
// signEC is the shared implementation for SignES256/384/512.
func signEC(header, payload string, key *ecdsa.PrivateKey, h crypto.Hash) ([]byte, error) {
digest := digestFor(h, header+"."+payload)
r, s, err := ecdsa.Sign(rand.Reader, key, digest)
if err != nil {
return nil, fmt.Errorf("signEC: %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
}
// ecdsaDERToRaw converts an ASN.1 DER-encoded ECDSA signature (as returned by
// [crypto.Signer]) to the fixed-width raw r||s format required by JWS.
// r and s are zero-padded to the curve's byte length via [big.Int.FillBytes].
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
}
// 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, " ")
}

478
auth/bestjwt/jwt_test.go Normal file
View File

@ -0,0 +1,478 @@
// Copyright 2025 AJ ONeal <aj@therootcompany.com> (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 bestjwt_test
import (
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/rsa"
"fmt"
"testing"
"time"
"github.com/therootcompany/golib/auth/bestjwt"
)
// AppClaims is an example custom claims type.
// Embedding StandardClaims promotes Validate — no boilerplate needed.
type AppClaims struct {
bestjwt.StandardClaims
Email string `json:"email"`
Roles []string `json:"roles"`
}
// StrictAppClaims overrides Validate to also require a non-empty Email.
// This demonstrates how to add application-specific validation on top of
// the standard OIDC checks.
type StrictAppClaims struct {
bestjwt.StandardClaims
Email string `json:"email"`
}
func (c StrictAppClaims) Validate(params bestjwt.ValidateParams) ([]string, error) {
errs, _ := bestjwt.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
}
// goodClaims returns a valid AppClaims with all standard fields populated.
func goodClaims() AppClaims {
now := time.Now()
return AppClaims{
StandardClaims: bestjwt.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"},
}
}
// goodParams returns ValidateParams matching the claims from goodClaims.
func goodParams() bestjwt.ValidateParams {
return bestjwt.ValidateParams{
Iss: "https://example.com",
Sub: "user123",
Aud: "myapp",
Jti: "abc123",
Nonce: "nonce1",
Azp: "myapp",
RequiredAmrs: []string{"pwd"},
}
}
// --- Round-trip tests (sign → encode → decode → verify → validate) ---
// TestRoundTripES256 exercises the most common path: ECDSA P-256 / ES256.
// Demonstrates the Decode(&claims) ergonomic — no generics at the call site,
// no type assertion needed to access Email after decoding.
func TestRoundTripES256(t *testing.T) {
privKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
if err != nil {
t.Fatal(err)
}
claims := goodClaims()
jws, err := bestjwt.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)
}
if len(jws.Signature) != 64 { // P-256: 32 bytes each for r and s
t.Fatalf("expected 64-byte signature, got %d", len(jws.Signature))
}
token := jws.Encode()
var decoded AppClaims
jws2, err := bestjwt.Decode(token, &decoded)
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 via the local variable — no type assertion.
if decoded.Email != claims.Email {
t.Errorf("email: got %s, want %s", decoded.Email, claims.Email)
}
}
// TestRoundTripES384 exercises ECDSA P-384 / ES384, verifying that the
// algorithm is inferred from the key's curve and that the 96-byte r||s
// signature format is produced and verified correctly.
func TestRoundTripES384(t *testing.T) {
privKey, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
if err != nil {
t.Fatal(err)
}
claims := goodClaims()
jws, err := bestjwt.NewJWSFromClaims(&claims, "key-1")
if err != nil {
t.Fatal(err)
}
if _, err = jws.Sign(privKey); err != nil {
t.Fatal(err)
}
if jws.Header.Alg != "ES384" {
t.Fatalf("expected ES384, got %s", jws.Header.Alg)
}
if len(jws.Signature) != 96 { // P-384: 48 bytes each for r and s
t.Fatalf("expected 96-byte signature, got %d", len(jws.Signature))
}
token := jws.Encode()
var decoded AppClaims
jws2, err := bestjwt.Decode(token, &decoded)
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)
}
}
// TestRoundTripES512 exercises ECDSA P-521 / ES512 and the 132-byte signature.
func TestRoundTripES512(t *testing.T) {
privKey, err := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
if err != nil {
t.Fatal(err)
}
claims := goodClaims()
jws, err := bestjwt.NewJWSFromClaims(&claims, "key-1")
if err != nil {
t.Fatal(err)
}
if _, err = jws.Sign(privKey); err != nil {
t.Fatal(err)
}
if jws.Header.Alg != "ES512" {
t.Fatalf("expected ES512, got %s", jws.Header.Alg)
}
if len(jws.Signature) != 132 { // P-521: 66 bytes each for r and s
t.Fatalf("expected 132-byte signature, got %d", len(jws.Signature))
}
token := jws.Encode()
var decoded AppClaims
jws2, err := bestjwt.Decode(token, &decoded)
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)
}
}
// 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 := bestjwt.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()
var decoded AppClaims
jws2, err := bestjwt.Decode(token, &decoded)
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)
}
}
// --- Security / negative tests ---
// TestVerifyWrongKeyType verifies that an RSA public key is rejected when
// verifying a token signed with ECDSA (alg = ES256).
func TestVerifyWrongKeyType(t *testing.T) {
ecKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
rsaKey, _ := rsa.GenerateKey(rand.Reader, 2048)
claims := goodClaims()
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(ecKey) // alg = "ES256"
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
if jws2.UnsafeVerify(&rsaKey.PublicKey) {
t.Fatal("expected verification to fail: RSA key for ES256 token")
}
}
// TestVerifyAlgCurveMismatch verifies that a P-256 key is rejected when
// verifying a token whose header claims ES384 (signed with P-384).
// Without the curve/alg consistency check this would silently return false
// from ecdsa.Verify, but the explicit check makes the rejection reason clear.
func TestVerifyAlgCurveMismatch(t *testing.T) {
p384Key, _ := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
p256Key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
claims := goodClaims()
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(p384Key) // alg = "ES384"
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
// P-256 key must be rejected for an ES384 token.
if jws2.UnsafeVerify(&p256Key.PublicKey) {
t.Fatal("expected verification to fail: P-256 key for ES384 token")
}
}
// TestVerifyUnknownAlg verifies that a tampered alg header is rejected.
func TestVerifyUnknownAlg(t *testing.T) {
privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
claims := goodClaims()
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(privKey)
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
// Tamper: overwrite alg in the decoded header.
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, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(privKey)
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
// 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)
}
}
// --- Embedded vs overridden Validate ---
// TestPromotedValidate confirms that AppClaims (which only embeds
// StandardClaims) gets the standard OIDC validation for free via promotion,
// without writing any Validate method.
func TestPromotedValidate(t *testing.T) {
privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
claims := goodClaims()
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(privKey)
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
jws2.UnsafeVerify(&privKey.PublicKey)
if errs, err := jws2.Validate(goodParams()); err != nil {
t.Fatalf("promoted Validate failed unexpectedly: %v", errs)
}
}
// TestOverriddenValidate confirms that a StrictAppClaims with an empty Email
// fails validation via its overridden Validate method.
func TestOverriddenValidate(t *testing.T) {
privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
now := time.Now()
claims := StrictAppClaims{
StandardClaims: bestjwt.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: "", // intentionally empty to trigger the override
}
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k")
_, _ = jws.Sign(privKey)
token := jws.Encode()
var decoded StrictAppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
jws2.UnsafeVerify(&privKey.PublicKey)
errs, err := jws2.Validate(goodParams())
if err == nil {
t.Fatal("expected validation to fail: email is empty")
}
found := false
for _, e := range errs {
if e == "missing email claim" {
found = true
}
}
if !found {
t.Fatalf("expected 'missing email claim' in errors: %v", errs)
}
}
// --- JWKS / key management ---
// TestTypedKeys verifies that TypedKeys correctly filters a mixed
// []PublicJWK[Key] into typed slices without type assertions at use sites.
func TestTypedKeys(t *testing.T) {
ecKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
rsaKey, _ := rsa.GenerateKey(rand.Reader, 2048)
allKeys := []bestjwt.PublicJWK[bestjwt.Key]{
{Key: &ecKey.PublicKey, KID: "ec-1", Use: "sig"},
{Key: &rsaKey.PublicKey, KID: "rsa-1", Use: "sig"},
}
ecKeys := bestjwt.TypedKeys[*ecdsa.PublicKey](allKeys)
if len(ecKeys) != 1 || ecKeys[0].KID != "ec-1" {
t.Errorf("unexpected EC keys: %+v", ecKeys)
}
// Typed access — no assertion needed.
_ = ecKeys[0].Key.Curve
rsaKeys := bestjwt.TypedKeys[*rsa.PublicKey](allKeys)
if len(rsaKeys) != 1 || rsaKeys[0].KID != "rsa-1" {
t.Errorf("unexpected RSA keys: %+v", rsaKeys)
}
}
// TestVerifyWithJWKSKey verifies that PublicJWK.Key can be passed directly to
// UnsafeVerify without a type assertion when using a typed PublicJWK[Key].
func TestVerifyWithJWKSKey(t *testing.T) {
privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
jwksKey := bestjwt.PublicJWK[bestjwt.Key]{Key: &privKey.PublicKey, KID: "k1"}
claims := goodClaims()
jws, _ := bestjwt.NewJWSFromClaims(&claims, "k1")
_, _ = jws.Sign(privKey)
token := jws.Encode()
var decoded AppClaims
jws2, _ := bestjwt.Decode(token, &decoded)
// Pass PublicJWK.Key directly — Key interface satisfies the Key constraint.
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 := bestjwt.UnmarshalPublicJWKs(jwksJSON)
if err != nil {
t.Fatal(err)
}
if len(keys) != 2 {
t.Fatalf("expected 2 keys, got %d", len(keys))
}
ecKeys := bestjwt.TypedKeys[*ecdsa.PublicKey](keys)
if len(ecKeys) != 1 || ecKeys[0].KID != "ec-256" {
t.Errorf("EC key mismatch: %+v", ecKeys)
}
rsaKeys := bestjwt.TypedKeys[*rsa.PublicKey](keys)
if len(rsaKeys) != 1 || rsaKeys[0].KID != "rsa-2048" {
t.Errorf("RSA key mismatch: %+v", rsaKeys)
}
}

229
auth/bestjwt/pub.go Normal file
View File

@ -0,0 +1,229 @@
// Copyright 2025 AJ ONeal <aj@therootcompany.com> (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 bestjwt
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 := bestjwt.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, _ := bestjwt.FetchPublicJWKs(jwksURL)
// ecKeys := bestjwt.TypedKeys[*ecdsa.PublicKey](all)
// rsaKeys := bestjwt.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
}