Security review findings: hardening opportunities

Start by reading the cited locations in lib/jwt/encoded_token.rb, lib/jwt/jwa/, lib/jwt/configuration/decode_configuration.rb, lib/jwt/jwk/key_base.rb, and lib/jwt/claims/. The findings cover distinct behaviors and include suggestions, but do not name tests; look for existing tests for each behavior before deciding scope. Done means the selected findings have clear dispositions and any agreed changes are covered by tests.

Security Review Findings

Internal security review of ruby-jwt v3.1.3 identified several hardening opportunities. None are assessed as CVE-eligible, but several are worth addressing.

---

Medium Severity

1. b64: false sets @claims_verified prematurely in EncodedToken

Location: lib/jwt/encoded_token.rb:192-194

When a token has b64: false, decode_payload internally calls verify_claims!(crit: ['b64']), which sets @claims_verified = true after only checking the crit header. If unverified_payload is accessed before payload without an explicit verify_claims! call, the payload accessor's claim verification guard is bypassed.

Conditions: Requires direct EncodedToken API usage + b64: false tokens + accessing unverified_payload before payload without calling verify_claims!. The JWT.decode path is not affected.

Suggestion: Use a private method for the internal crit check that does not set @claims_verified.

2. HMAC nil/empty key accepted silently

Location: lib/jwt/jwa/hmac.rb:24,37

Both sign and verify coerce nil keys to empty strings (signing_key ||= ''). Applications that accidentally pass nil as the HMAC key get tokens signed with zero-entropy keys without any warning.

Suggestion: Raise an error or deprecation warning when the HMAC key is nil or empty.

3. HMAC minimum key length enforcement off by default

Location: lib/jwt/configuration/decode_configuration.rb — enforce_hmac_key_length defaults to false

RFC 7518 Section 3.2 requires HMAC keys to be at least as long as the hash output (32/48/64 bytes for HS256/384/512). The check exists but is disabled by default.

Suggestion: Consider defaulting to true in the next major version.

---

Low Severity

4. RSA/PS verification lacks key type check

Location: lib/jwt/jwa/rsa.rb:21-25, lib/jwt/jwa/ps.rb:21-24

Unlike HMAC (is_a?(String)) and ECDSA (is_a?(OpenSSL::PKey::EC)), RSA/PS verify methods don't validate the key type. A String key produces NoMethodError instead of a clear VerificationError. Not exploitable (verification fails either way) but inconsistent.

5. No minimum RSA key size on verification

Location: lib/jwt/jwa/rsa.rb:21-25

The 2048-bit minimum is enforced on signing but not on verification. Low practical impact since the application controls verification keys.

6. JWK objects expose private keys via inspect

Location: lib/jwt/jwk/key_base.rb

No inspect override means debug logging of JWK objects could expose private key material from @parameters.

Suggestion: Override inspect to exclude private key components.

7. VerifierContext exception propagation with mixed key types

Location: lib/jwt/jwa/verifier_context.rb:14-18

When a key of the wrong type raises VerificationError inside .any?, the exception propagates without trying remaining keys. Only affects direct EncodedToken API users providing heterogeneous key arrays.

Suggestion: Rescue VerificationError within the .any? block and treat as false.

---

Informational

8. Issuer validation uses === semantics

Location: lib/jwt/claims/issuer.rb:21-24

The case/when *issuers pattern means Regexp or Proc objects passed as expected issuers silently enable flexible matching rather than strict string equality. Not a vulnerability (application controls the issuer list) but may surprise developers.

9. Claim error messages include expected values

Location: lib/jwt/claims/audience.rb:22, lib/jwt/claims/issuer.rb:25

Error messages include both expected and received claim values. If surfaced to clients or logs, internal service identifiers could be disclosed.

---

Strong Points

The library handles the major JWT attack vectors well:

• Algorithm confusion defense via key type checking on HMAC/ECDSA
• Constant-time HMAC comparison via OpenSSL.fixed_length_secure_compare
• none algorithm requires explicit opt-in and is blocked via JWK
• Strict base64 decoding since v3.0.0
• Algorithm whitelist model (non-empty allowed_algorithms required)
• No dangerous dynamic dispatch (eval, send, const_get, etc.)
• RSA 2048-bit minimum on signing
• JWK cryptographic parameter immutability after initialization