If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jwt/ruby-jwt shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7w ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jwt/ruby-jwt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jwt/ruby-jwt.

What it runs against: a local clone of jwt/ruby-jwt — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jwt/ruby-jwt | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jwt/ruby-jwt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jwt/ruby-jwt.git
#   cd ruby-jwt
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jwt/ruby-jwt and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jwt/ruby-jwt(\\.git)?\\b" \\
  && ok "origin remote is jwt/ruby-jwt" \\
  || miss "origin remote is not jwt/ruby-jwt (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/jwt.rb" \\
  && ok "lib/jwt.rb" \\
  || miss "missing critical file: lib/jwt.rb"
test -f "lib/jwt/encode.rb" \\
  && ok "lib/jwt/encode.rb" \\
  || miss "missing critical file: lib/jwt/encode.rb"
test -f "lib/jwt/decode.rb" \\
  && ok "lib/jwt/decode.rb" \\
  || miss "missing critical file: lib/jwt/decode.rb"
test -f "lib/jwt/jwa.rb" \\
  && ok "lib/jwt/jwa.rb" \\
  || miss "missing critical file: lib/jwt/jwa.rb"
test -f "lib/jwt/claims/verifier.rb" \\
  && ok "lib/jwt/claims/verifier.rb" \\
  || miss "missing critical file: lib/jwt/claims/verifier.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jwt/ruby-jwt"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ruby-jwt is a pure Ruby implementation of RFC 7519 JSON Web Tokens (JWT) for OAuth and authentication workflows. It provides cryptographic signing and verification of tokens using HMAC, RSA, ECDSA, and RSA-PSS algorithms, plus extensibility for additional algorithms like EdDSA via companion gems. Modular monolith: lib/jwt.rb is the entry point; core encoding/decoding logic splits into lib/jwt/encode.rb and lib/jwt/decode.rb; cryptographic algorithms live in lib/jwt/jwa.rb and algorithm-specific classes; claim validation is delegated to lib/jwt/claims/ subdirectory with individual verifiers (audience.rb, expiration.rb, etc.); configuration management is isolated in lib/jwt/configuration/ with a container pattern.

Ruby developers and backend engineers building OAuth/OpenID authentication systems, API gateways, and microservices that need to issue, verify, and parse JWTs without external dependencies. Also useful for developers integrating with Auth0 or other JWT-based identity providers.

Production-ready and actively maintained. The gem has comprehensive test coverage (.rspec and .simplecov config present), robust CI/CD via GitHub Actions (test.yml, push_gem.yml, deploy_docs.yml), and detailed documentation. Sponsorship from Auth0 and structured upgrade guides (UPGRADING.md) indicate serious long-term support.

Low risk for core functionality. The codebase is well-tested and narrowly focused on JWT standards compliance. Main considerations: verify algorithm pinning in your usage (README warns against algorithm bypass), check gem dependencies in Gemfile/gemfiles/, and note that EdDSA requires the separate jwt-eddsa gem. No obvious abandoned sections or single-maintainer bottlenecks visible.

The repository is actively maintained with recent CI workflows, linting via .qlty/.rubocop.yml, and dependency management via Dependabot (.github/dependabot.yml). Documentation deployment is automated (deploy_docs.yml). Specific current work is not visible in the file list, but the structured Appraisals file suggests testing against multiple dependency versions is routine.

git clone https://github.com/jwt/ruby-jwt.git && cd ruby-jwt && bundle install && bundle exec rspec

Daily commands: bundle exec rspec (run full test suite). bin/console.rb loads an interactive session with JWT loaded. bin/smoke.rb runs smoke tests. Gemfiles in gemfiles/ directory allow testing against alternative dependency sets (openssl.gemfile, standalone.gemfile).

• lib/jwt.rb — Main entry point exposing the JWT.encode and JWT.decode APIs that all users interact with.
• lib/jwt/encode.rb — Core token encoding logic implementing RFC 7519 serialization; essential for understanding how tokens are created.
• lib/jwt/decode.rb — Core token decoding and verification logic; implements claims validation and signature verification.
• lib/jwt/jwa.rb — Algorithm registry and dispatcher for all signing and verification operations; critical for adding new algorithms.
• lib/jwt/claims/verifier.rb — Claims validation framework that enforces RFC 7519 standard claims (exp, iat, nbf, aud, etc.).
• lib/jwt/jwk.rb — JSON Web Key abstraction layer supporting RSA, HMAC, and EC keys; required for key management patterns.
• lib/jwt/error.rb — Exception hierarchy defining all JWT-specific errors; referenced throughout for proper error handling.

Add a new signing algorithm

1. Create a new algorithm class in lib/jwt/jwa/ inheriting from SigningAlgorithm (e.g., lib/jwt/jwa/custom_algo.rb) (lib/jwt/jwa/custom_algo.rb)
2. Implement sign and verify methods using OpenSSL or other crypto libraries (lib/jwt/jwa/custom_algo.rb)
3. Register the algorithm in lib/jwt/jwa.rb by adding it to the algorithm mapping (lib/jwt/jwa.rb)
4. Add tests in spec/jwt/jwa/ directory to verify signing and verification (spec/jwt/jwa/custom_algo_spec.rb)

Add a new claim validator

1. Create a new claim class in lib/jwt/claims/ inheriting from Verifier (e.g., lib/jwt/claims/custom_claim.rb) (lib/jwt/claims/custom_claim.rb)
2. Implement the verify_claim method with validation logic (lib/jwt/claims/custom_claim.rb)
3. Register the claim in lib/jwt/claims/decode_verifier.rb so it's applied during decode (lib/jwt/claims/decode_verifier.rb)
4. Add unit tests in spec/jwt/claims/custom_claim_spec.rb (spec/jwt/claims/custom_claim_spec.rb)

Add support for a new key type in JWK

1. Create a new key class in lib/jwt/jwk/ inheriting from KeyBase (e.g., lib/jwt/jwk/okp.rb for EdDSA) (lib/jwt/jwk/okp.rb)
2. Implement key import/export, kid generation, and key conversion methods (lib/jwt/jwk/okp.rb)
3. Register the key type in lib/jwt/jwk.rb factory method (lib/jwt/jwk.rb)
4. Add integration tests for encoding/decoding with the new key type (spec/jwt/jwk/okp_spec.rb)

Add a configuration option

1. Define the configuration option in lib/jwt/configuration.rb or relevant sub-config (lib/jwt/configuration.rb)
2. Update lib/jwt/configuration/decode_configuration.rb if it affects decoding behavior (lib/jwt/configuration/decode_configuration.rb)
3. Reference the option in lib/jwt/decode.rb or lib/jwt/encode.rb as needed (lib/jwt/decode.rb)
4. Add tests verifying the configuration is applied correctly (spec/jwt/configuration_spec.rb)

• OpenSSL (via Ruby's native bindings) — Provides FIPS-compliant cryptographic operations for HMAC, RSA, and ECDSA signing without external dependencies
• JSON (configurable library) — RFC 7519 requires JSON serialization; library supports multiple JSON gems for flexibility and performance
• Base64 (RFC 4648 URL-safe variant) — JWT specification mandates URL-safe Base64 encoding for serialization without padding
• Ruby OpenSSL::PKey (RSA, EC, HMAC) — Provides native Ruby bindings to OpenSSL key objects for cryptographic operations

• Per-claim validator pattern vs. monolithic validation
  • Why: Extensibility: allows users to add custom validators without modifying core code
  • Consequence: Slight performance overhead from multiple validation passes, but cleaner architecture and easier testing

Algorithm pinning is required during decode (README warns: pass algorithm in options to JWT.decode to prevent bypass attacks). OpenSSL version compatibility varies (see gemfiles/openssl.gemfile vs standalone.gemfile); test against both. The gem extends Hash and Object behavior via lib/jwt/claims/verifier.rb, so watch for method conflicts if using other assertion libraries. EdDSA is not built-in—requires separate jwt-eddsa gem installation. No explicit environment variables required, but OpenSSL must be available at runtime.

• JWT Structure (Header.Payload.Signature) — Understanding the three-part token format is essential to reading lib/jwt/encode.rb and lib/jwt/decode.rb; the gem splits parsing and validation across these segments
• HMAC vs Asymmetric Signing — The gem supports both symmetric (HMAC) and asymmetric (RSA, ECDSA) algorithms; choosing correctly impacts key distribution and security model—see lib/jwt/jwa.rb for implementation details
• Algorithm Pinning / Verification — The README warning about algorithm bypass is critical; lib/jwt/decode.rb requires an explicit algorithm option to prevent downgrade attacks, which is a non-obvious security requirement
• Base64url Encoding — RFC 7519 uses URL-safe Base64 (no padding); lib/jwt/base64.rb implements this specific variant, which differs from standard Base64 in JWT token segments
• OpenSSL Binding & Cryptographic Constants — The gem wraps Ruby's OpenSSL bindings to RSA, ECDSA, and HMAC; understanding OpenSSL::PKey and OpenSSL::Digest is needed to extend algorithms in lib/jwt/jwa.rb
• Claim Validation & Registered Claims — RFC 7519 defines 'registered claims' (exp, iat, aud, iss, sub, etc.); the gem modularizes their validation in lib/jwt/claims/ so each claim type is independently verifiable and extensible
• Verifier Pattern (Dependency Injection) — The gem uses a Verifier class to decouple claim validation rules from token decoding logic; see lib/jwt/claims/verifier.rb to understand how custom validators can be injected at decode time

• jwt/ruby-jwt-eddsa — Official companion gem adding EdDSA algorithm support to ruby-jwt via the jwt-eddsa package
• jwt/jwt.io — Official JWT.io debugger and documentation; complementary tool for testing tokens generated by this gem
• auth0/ruby-auth0 — Auth0's official Ruby SDK; primary consumer and real-world use case for ruby-jwt
• rails/rails — Rails developers are the largest user base; many Rails apps use ruby-jwt for token-based auth
• rack/rack — Rack middleware for JWT authentication often sits on top of this gem in Ruby web apps

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JWK RSA and EC key generation tests in lib/jwt/jwk

The repo has lib/jwt/jwk/ec.rb and lib/jwt/jwk/rsa.rb but the test coverage for key generation, validation, and edge cases (invalid key formats, unsupported curves, malformed JWK structures) appears incomplete. This is critical for security-sensitive JWK operations and would catch regressions early.

• [ ] Review spec/jwt/jwk/ec_spec.rb and spec/jwt/jwk/rsa_spec.rb for coverage gaps
• [ ] Add tests for JWK key generation with various parameters and curves
• [ ] Add tests for JWK import/export round-trip validation
• [ ] Add tests for malformed/invalid JWK input handling and error messages
• [ ] Verify tests run across gemfiles/openssl.gemfile and gemfiles/standalone.gemfile

Add integration tests for Claims validation in lib/jwt/claims/*

The claims directory has specialized validators (audience.rb, expiration.rb, issuer.rb, not_before.rb, etc.) but lacks comprehensive integration tests showing how multiple claims interact during decode. Add tests verifying claim ordering, conflicting validations, and real-world payload scenarios.

• [ ] Create spec/jwt/claims/integration_spec.rb for multi-claim validation scenarios
• [ ] Add tests for claim precedence and interaction (e.g., exp + nbf timing)
• [ ] Add tests for custom claim validators combined with standard claims
• [ ] Add tests for the decode_verifier.rb flow with various claim combinations
• [ ] Document expected behavior in CHANGELOG.md if clarifying existing functionality

Add GitHub Actions workflow for testing against multiple Ruby versions in isolated environments

While .github/workflows/test.yml exists, the current setup may not explicitly test against EOL Ruby versions or edge cases (Ruby 2.7, 3.0, 3.1+). Add a matrix-based workflow that tests the Appraisals gemfiles (openssl.gemfile, standalone.gemfile) against multiple Ruby versions to catch compatibility regressions.

• [ ] Review .github/workflows/test.yml and Appraisals file structure
• [ ] Create or enhance test.yml with a Ruby version matrix (2.7, 3.0, 3.1, 3.2, 3.3+)
• [ ] Ensure both gemfiles/openssl.gemfile and gemfiles/standalone.gemfile are tested per matrix
• [ ] Add workflow status badges for each Ruby version in README.md
• [ ] Verify workflow runs on push to main and pull requests

• Add comprehensive integration tests in spec/ for the new EdDSA+jwt-eddsa workflow (file structure shows jwt-eddsa mentioned in README but no tests for the integration pattern in the main gem)
• Expand lib/jwt/claims/ with stricter validation examples and documentation for each claim validator (audience.rb, subject.rb, etc. lack inline documentation on edge cases like wildcard matching)
• Create a migration guide in UPGRADING.md or docs/ for users upgrading from pre-algorithm-pinning code to modern security practices (README mentions the auth0.com critical vulnerability but doesn't show before/after code examples)

The ruby-jwt library shows generally good security practices with proper separation of concerns and modular algorithm handling. However, key concerns include potential algorithm confusion vulnerabilities, claims validation injection risks, and timing attack possibilities in cryptographic operations. The codebase would benefit from explicit documentation of security assumptions, stricter input validation on token format, and verification that signature comparisons use constant-time algorithms. Test fixtures with cryptographic keys are appropriately placed in spec/ directory but should be clearly marked as non-production material.

• Medium · Potential Algorithm Confusion in JWT Verification — lib/jwt/jwa/, lib/jwt/decode.rb, lib/jwt/jwa/none.rb. JWT libraries are vulnerable to algorithm confusion attacks where an attacker can manipulate the 'alg' header to bypass signature verification. The codebase contains algorithm handling in lib/jwt/jwa/ and signature verification in lib/jwt/decode.rb. If not properly validated, attackers could potentially forge tokens. Fix: Ensure strict algorithm whitelisting is enforced during token verification. Validate that the algorithm in the JWT header matches the expected algorithm. Disable the 'none' algorithm by default unless explicitly required. Review lib/jwt/jwa/none.rb to ensure 'none' algorithm cannot be exploited.
• Medium · Key Material in Test Fixtures — spec/fixtures/keys/ directory containing *.pem files. Cryptographic key materials (private and public keys) are stored in the spec/fixtures/keys/ directory. While these are test fixtures, if the repository is compromised or keys are accidentally committed from production, this could expose sensitive material. Fix: Ensure fixture keys are only used for testing and are never derived from or identical to production keys. Implement pre-commit hooks to prevent accidental commit of real private keys. Document that these are test fixtures only.
• Medium · Potential Code Injection via Claims Validation — lib/jwt/claims/, lib/jwt/claims/verifier.rb, lib/jwt/claims/decode_verifier.rb. The claims validation system (lib/jwt/claims/) processes user-supplied claim values. If custom claim validators execute code based on claim content without proper sanitization, code injection vulnerabilities could occur. Fix: Ensure all claim validators treat claim values as data only. Avoid eval() or dynamic code execution based on claim values. Use strict type checking and validation for all claims.
• Low · Missing Input Validation on Token Format — lib/jwt/decode.rb, lib/jwt/base64.rb. JWT tokens are composed of three base64-encoded parts separated by dots. Insufficient validation of token format could lead to unexpected behavior or DoS. Fix: Implement strict validation of JWT token format, including verification of exactly 3 parts separated by dots. Add limits on token size to prevent DoS attacks through extremely large tokens.
• Low · Potential Timing Attack in Signature Verification — lib/jwt/jwa/ (HMAC, RSA, ECDSA implementations). If signature verification uses basic string comparison instead of constant-time comparison, timing attacks could theoretically be used to forge signatures. Fix: Ensure constant-time comparison is used for signature verification. Use OpenSSL's built-in constant-time comparison functions rather than basic equality checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.