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/auth0/java-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 the board

• Last commit 1w ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 71% 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 auth0/java-jwt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/auth0/java-jwt.

What it runs against: a local clone of auth0/java-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 auth0/java-jwt | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of auth0/java-jwt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/auth0/java-jwt.git
#   cd java-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 auth0/java-jwt and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "auth0/java-jwt(\\.git)?\\b" \\
  && ok "origin remote is auth0/java-jwt" \\
  || miss "origin remote is not auth0/java-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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
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/auth0/java-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).

A Java library implementing the JWT (JSON Web Token) standard (RFC 7519) for server-side JVM applications, providing both signing and verification of tokens using symmetric (HMAC256/384/512) and asymmetric (RSA256/384/512, ECDSA256/384/512) algorithms. It abstracts cryptographic complexity into a fluent API so developers can securely issue and validate authentication tokens without wrestling with the underlying Java crypto APIs. Gradle-based monorepo with a core library under lib/ (lib/build.gradle, lib/src) containing the JWT implementation, benchmarks in lib/src/jmh, and Maven publishing configuration in gradle/maven-publish.gradle. Build metadata and versioning are centralized in gradle/versioning.gradle and gradle.properties, with CI/CD automation in .github/workflows and custom GitHub Actions in .github/actions/.

Backend Java developers building authentication and authorization systems who need to create or validate JWTs—typical users are building microservices, REST APIs, or applications integrating with Auth0. Contributors are Auth0 maintainers and the Java security community ensuring crypto best practices.

Production-ready and actively maintained. The repository has formal CI/CD pipelines (.github/workflows including build-and-test.yml, java-release.yml, security scanning with semgrep and snyk), Maven Central distribution, and follows semantic versioning with a CHANGELOG.md. Recent investment in key rotation and signing key updates indicates active security stewardship, though specific commit recency cannot be determined from the file list alone.

Standard open source risks apply.

Active security and reliability work: the repo recently rotated signing keys (noted in README note box), added security scanning workflows (rl-secure.yml, semgrep.yml, snyk.yml), implemented dependency validation (gradle-wrapper-validation.yml), and maintains stale issue management (stale.yml). Release automation via release.yml and java-release.yml workflows indicates regular versioning cadence.

Clone the repository, then build with Gradle: ```bash git clone https://github.com/auth0/java-jwt.git cd java-jwt ./gradlew build

The gradlew script (committed) handles Gradle version management, so no separate Gradle installation is needed.

**Daily commands:**
Run tests: ```bash
./gradlew build

Run benchmarks: ```bash ./gradlew lib:jmh

Publish locally (requires MAVEN_USERNAME/MAVEN_PASSWORD env vars): ```bash
./gradlew publish

• lib/build.gradle: Defines the core library's dependencies, compilation targets (Java 8+), and test configurations; critical for understanding build requirements
• lib/src: Root directory for main JWT implementation code (signing, verification, claim handling) and all unit tests
• .github/workflows/java-release.yml: Automates Maven Central publishing; shows how artifacts reach production and what environment variables are required
• gradle/versioning.gradle: Centralizes semantic versioning logic and release version computation; changes here affect all releases
• config/checkstyle/checkstyle.xml: Enforces code style and quality rules (checked in CI); understanding this prevents build failures from style violations
• EXAMPLES.md: Runnable code examples demonstrating JWT signing and verification for different algorithms; best learning resource after the codebase
• MIGRATION_GUIDE.md: Documents breaking changes between major versions; essential reading before upgrading or contributing compatibility fixes

Start in lib/src for the core JWT implementation. To add a new algorithm: update the algorithm enum (likely in lib/src/main) and implement the signing/verification logic. To add tests: mirror the structure in lib/src/test. To update release mechanics: edit .github/workflows/java-release.yml or .github/workflows/release.yml. Configuration and linting rules are in config/checkstyle/checkstyle.xml.

The library targets only Java LTS versions (8, 11, 17, 21); testing on non-LTS versions may fail or be unsupported. Maven Central publishing requires MAVEN_USERNAME and MAVEN_PASSWORD environment variables set in CI/CD—missing these blocks releases silently. The .version file must be kept in sync with gradle.properties and CHANGELOG.md during releases; version mismatches can cause publishing failures. ECDSA with secp256k1 is deliberately dropped due to Java 15+ disabling it—don't try to add it back. Checkstyle validation (config/checkstyle/checkstyle.xml) is strict and blocks builds; run ./gradlew checkstyleMain locally before pushing.

• JSON Web Token (JWT) Structure — Understanding the three-part structure (header.payload.signature) and base64url encoding is essential to using and debugging this library correctly
• HMAC (Hash-based Message Authentication Code) — Half of the supported algorithms use HMAC for symmetric signing; knowing its properties (shared secret, no non-repudiation) guides correct key management in java-jwt applications
• RSA (Rivest–Shamir–Adleman) Cryptography — RSA256/384/512 algorithms enable asymmetric signing; understanding public/private key separation is critical for issuing vs. verifying tokens in distributed systems
• ECDSA (Elliptic Curve Digital Signature Algorithm) — ES256/384/512 algorithms provide asymmetric signing with smaller key sizes than RSA; the library deliberately excludes secp256k1 due to Java 15+ restrictions—knowing this prevents wasted implementation effort
• Fluent Builder Pattern — The library's API uses fluent builders for token creation and verification; understanding this pattern helps when extending or modifying the API surface
• JWS (JSON Web Signature) — RFC 7515 defines how tokens are signed; the algorithm table in the README maps JWS algorithm names to java-jwt's support, critical for interoperability
• X.509 Certificates and Public Key Infrastructure (PKI) — RSA and ECDSA verification requires loading public keys from certificates or PEM files; understanding PKI formats helps debug key loading issues in production

• auth0/jwks-rsa-java — Companion library for fetching and caching JSON Web Key Sets from Auth0; commonly used alongside java-jwt for token verification in Auth0 flows
• auth0/JWTDecode.Android — Auth0's JWT library for Android; this repo explicitly recommends it for Android apps instead of java-jwt, showing the ecosystem split
• eclipse-ee4j/jsonp — Reference implementation of JSON Processing (JSR 374); java-jwt uses JSON for token structure, and understanding JSON-P helps with custom claim handling
• jpadilla/pyjwt — Python JWT library by the original author; useful for understanding JWT semantics and cross-language compatibility testing
• auth0/node-jsonwebtoken — Auth0's Node.js JWT library; developers often need to verify tokens issued by java-jwt in different language ecosystems

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 test coverage for Algorithm implementations and edge cases

The file structure shows lib/src/main/java/com/auth0/jwt/algorithms/Algorithm.java but no corresponding test files are visible in the partial listing. JWT algorithm implementations (RSA, HMAC, ECDSA, EdDSA) are security-critical and need extensive edge case testing including invalid signatures, key size validation, null handling, and algorithm-specific boundary conditions. This would improve security posture and catch potential vulnerabilities early.

• [ ] Create lib/src/test/java/com/auth0/jwt/algorithms/AlgorithmTest.java with tests for all algorithm types
• [ ] Add tests for invalid signature detection across RSA, HMAC, ECDSA variants
• [ ] Add tests for key validation edge cases (wrong key size, null keys, expired certificates)
• [ ] Add tests for algorithm mismatch scenarios and algorithm confusion attacks
• [ ] Ensure >90% code coverage for the algorithms/ package reported in codecov

Expand JWTVerifier test suite with real-world verification scenarios

JWTVerifier.java is a core security component but the test coverage is likely incomplete based on the repo structure. Real-world verification includes claim validation (exp, nbf, iat, iss, sub, aud), leeway handling, timezone edge cases, and custom claim validators. This ensures production deployments don't face surprising verification failures.

• [ ] Create lib/src/test/java/com/auth0/jwt/JWTVerifierTest.java with comprehensive claim validation tests
• [ ] Add tests for timestamp validation with various timezones and leeway configurations
• [ ] Add tests for custom claim validators and multiple claim validation chains
• [ ] Add tests for audience and issuer validation with multiple values
• [ ] Add tests for verification failure scenarios and meaningful error messages

Add performance benchmarking documentation and CI validation

The repo already has lib/src/jmh/java/com/auth0/jwt/benchmark/JWTDecoderBenchmark.java (JMH benchmarks present), but there's no GitHub Actions workflow to run, track, or report on performance regressions. Adding a CI workflow would prevent performance degradation in future releases and provide metrics to contributors.

• [ ] Create .github/workflows/jmh-benchmark.yml to run JMH benchmarks on PRs targeting main branches
• [ ] Configure the workflow to compare benchmark results against baseline (master/main)
• [ ] Add benchmark result reporting as PR comments to help reviewers spot performance regressions
• [ ] Add performance thresholds (e.g., fail if encoding/decoding slows >5%) and document in CONTRIBUTING.md
• [ ] Reference the benchmark workflow in README.md under a 'Performance' or 'Contributing' section

• Add comprehensive unit tests for edge cases in ECDSA256/384/512 verification with malformed signatures in lib/src/test; current coverage gaps could hide validation bugs
• Write a code example in EXAMPLES.md demonstrating how to rotate signing keys without breaking token validation for tokens issued before the rotation—this is now a documented concern in the README
• Create integration tests that verify java-jwt works correctly with all supported Java LTS versions (8, 11, 17, 21) by adding a new test matrix to .github/workflows/build-and-test.yml

The java-jwt library demonstrates a reasonable security posture with multiple scanning tools integrated (Semgrep, Snyk, ReleaseLocker, SCA). However, there are concerns regarding potential support for the 'none' algorithm in JWT verification, which is a critical vulnerability. Credential management relies on environment variables without documented rotation practices. The library should implement stricter algorithm validation to prevent substitution attacks and provide clearer documentation

• High · Credentials Stored in Environment Variables Without Rotation Policy — build.gradle (nexusPublishing configuration). Maven credentials (MAVEN_USERNAME and MAVEN_PASSWORD) are stored in environment variables for the Sonatype repository. While this is better than hardcoding, there's no visible rotation policy or secret management strategy documented. Fix: Implement automated secret rotation, use GitHub Secrets with expiration policies, and consider using workload identity federation instead of static credentials. Document the credential rotation process.
• High · JWT Library with None Algorithm Support — lib/src/main/java/com/auth0/jwt/algorithms/NoneAlgorithm.java. The presence of 'NoneAlgorithm.java' in the codebase suggests the library may support the 'none' algorithm, which is a critical vulnerability in JWT implementations. This allows token verification to be bypassed entirely. Fix: Verify that NoneAlgorithm is disabled by default and cannot be used in production. Add warnings in documentation. Consider removing it entirely or ensuring it requires explicit opt-in with security warnings.
• Medium · Potential Algorithm Mismatch Vulnerability — lib/src/main/java/com/auth0/jwt/algorithms/Algorithm.java and lib/src/main/java/com/auth0/jwt/exceptions/AlgorithmMismatchException.java. The existence of 'AlgorithmMismatchException.java' indicates the library handles algorithm mismatches, but the file structure suggests algorithm selection may be flexible. This could lead to algorithm substitution attacks if not properly validated. Fix: Ensure that algorithm validation is strict and that users must explicitly specify expected algorithms during verification. Add documentation warning about algorithm substitution attacks.
• Medium · Missing Dependency Version Pinning — build.gradle, lib/build.gradle. The build.gradle file shows dependency management but the provided snippet doesn't show explicit version pinning for transitive dependencies. This could lead to unexpected security patches or vulnerabilities from transitive dependencies. Fix: Implement explicit version pinning for all dependencies. Use Gradle's dependency locking feature or a Bill of Materials (BoM) to ensure reproducible builds.
• Medium · Signing Key Rotation Notice Without Implementation Details — README.md. The README mentions signing key rotation but doesn't provide technical details on how validation is performed. Users may not understand the security implications or implementation details. Fix: Document the signing key rotation process, provide migration guidance, and ensure backward compatibility is explicitly tested and documented.
• Low · Public Gradle Wrapper JAR — gradle/wrapper/gradle-wrapper.jar. The gradle-wrapper.jar file is included in version control. While this is a common practice, it increases the attack surface if the repository is compromised. Fix: Consider using Gradle's wrapper validation in CI/CD (appears to be done in gradle-wrapper-validation.yml). Ensure the wrapper SHA is verified in the build pipeline.
• Low · Missing OWASP Dependency Check Integration — .github/workflows/. While the project includes Semgrep and Snyk scanning workflows, there's no visible OWASP Dependency-Check integration for comprehensive vulnerability scanning. Fix: Add OWASP Dependency-Check to the CI/CD pipeline for additional vulnerability detection coverage alongside existing Snyk and Semgrep scans.
• Low · Benchmark Code in Main Source Tree — lib/src/jmh/java/com/auth0/jwt/benchmark/JWTDecoderBenchmark.java. JMH benchmark code is included in the main source tree alongside production code, which could potentially be included in the compiled artifact. Fix: Ensure JMH benchmark classes are excluded from the final JAR artifact. Verify the Gradle build configuration properly isolates benchmark code.

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.