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/justauth/JustAuth 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 3w ago
• 14 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 justauth/JustAuth repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/justauth/JustAuth.

What it runs against: a local clone of justauth/JustAuth — 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 justauth/JustAuth | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "justauth/JustAuth(\\.git)?\\b" \\
  && ok "origin remote is justauth/JustAuth" \\
  || miss "origin remote is not justauth/JustAuth (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"

# 4. Critical files exist
test -f "src/main/java/me/zhyd/oauth/AuthRequestBuilder.java" \\
  && ok "src/main/java/me/zhyd/oauth/AuthRequestBuilder.java" \\
  || miss "missing critical file: src/main/java/me/zhyd/oauth/AuthRequestBuilder.java"
test -f "src/main/java/me/zhyd/oauth/config/AuthDefaultSource.java" \\
  && ok "src/main/java/me/zhyd/oauth/config/AuthDefaultSource.java" \\
  || miss "missing critical file: src/main/java/me/zhyd/oauth/config/AuthDefaultSource.java"
test -f "src/main/java/me/zhyd/oauth/config/AuthConfig.java" \\
  && ok "src/main/java/me/zhyd/oauth/config/AuthConfig.java" \\
  || miss "missing critical file: src/main/java/me/zhyd/oauth/config/AuthConfig.java"
test -f "src/main/java/me/zhyd/oauth/model/AuthResponse.java" \\
  && ok "src/main/java/me/zhyd/oauth/model/AuthResponse.java" \\
  || miss "missing critical file: src/main/java/me/zhyd/oauth/model/AuthResponse.java"
test -f "src/main/java/me/zhyd/oauth/cache/AuthDefaultStateCache.java" \\
  && ok "src/main/java/me/zhyd/oauth/cache/AuthDefaultStateCache.java" \\
  || miss "missing critical file: src/main/java/me/zhyd/oauth/cache/AuthDefaultStateCache.java"

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

JustAuth is a Java library that abstracts OAuth 2.0 authentication across 40+ third-party platforms (GitHub, Gitee, WeChat, Alipay, Google, Facebook, Twitter, LinkedIn, etc.) into a unified, simple API. It eliminates the need to integrate each platform's SDK individually by providing a single AuthRequestBuilder and standardized request/response handling across all providers. Monolithic single-module Maven project (src/main/java/me/zhyd/oauth/) organized by concern: core authorization logic in AuthRequestBuilder.java, pluggable caching in cache/ (AuthCache, AuthDefaultCache, AuthCacheScheduler), and individual provider implementations (not shown but implied by 40+ platforms listed). Build artifacts deployed to Maven Central and Sonatype snapshots.

Java backend developers building web applications who need to add social login/OAuth authentication without dealing with the complexity of multiple third-party SDKs. Target users range from startups to enterprises, particularly in China (given strong Gitee/WeChat/Alipay support) and globally.

Production-ready and actively maintained. The project shows 1.16.7+ releases, has 40+ OAuth providers integrated, uses CI/CD (GitHub Actions in .github/workflows/), maintains comprehensive documentation at justauth.cn, and demonstrates active Gitee/GitHub community presence. The codebase is stable with clear semver versioning and organized issue templates.

Relatively low risk for a mature OAuth library, but with caveats: (1) primary maintainer appears to be Yadong.Zhang (single-point-of-failure), though 2 co-developers are listed; (2) Java 1.8 baseline is aging (released 2014); (3) no explicit lock-in risk since it's a thin adapter layer, but OAuth spec changes could require provider-specific updates; (4) dependency footprint not fully visible in pom.xml snippet, but the library explicitly avoids forcing HTTP client dependencies (design choice).

Active maintenance with snapshot deployments (.github/workflows/deploy-snapshot.yml), pull request testing (test-pr.yml), and version management scripts in bin/ (updVersion.sh, repVersion.sh). Recent work appears focused on platform additions and stability given no breaking changes visible in CHANGELOGS.md snippet shown.

git clone https://gitee.com/yadong.zhang/JustAuth.git
cd JustAuth
mvn clean install
mvn test

No external services required for basic compilation; review pom.xml for dependency tree and check bin/version.txt for current release version.

Daily commands: This is a library, not an application. To use it in your project: (1) Add Maven dependency: me.zhyd.oauth:JustAuth:1.16.7, (2) Instantiate via AuthRequestBuilder.authGithub(AuthConfig).build() or similar for your target platform, (3) Redirect users to the authorization URL, (4) Handle callback and exchange code for user info. See example.md for concrete usage patterns.

• src/main/java/me/zhyd/oauth/AuthRequestBuilder.java — Main entry point and factory builder for creating OAuth request instances across 40+ providers — all authentication flows start here.
• src/main/java/me/zhyd/oauth/config/AuthDefaultSource.java — Central registry mapping all 40+ OAuth provider configurations (GitHub, Gitee, WeChat, etc.) — defines the source-of-truth for endpoint URLs and default scopes.
• src/main/java/me/zhyd/oauth/config/AuthConfig.java — Abstract configuration base class for OAuth credentials and endpoints — every provider implementation extends this to customize their auth flow.
• src/main/java/me/zhyd/oauth/model/AuthResponse.java — Unified response wrapper for all OAuth operations — standardizes success/error handling across heterogeneous third-party APIs.
• src/main/java/me/zhyd/oauth/cache/AuthDefaultStateCache.java — Default state parameter cache implementation preventing CSRF attacks — critical for OAuth 2.0 security in multi-request flows.
• src/main/java/me/zhyd/oauth/model/AuthUser.java — Unified user profile data model normalizing attributes across 40+ OAuth providers with different response schemas.
• pom.xml — Maven build configuration defining all transitive dependencies (HTTP client, JSON parsers) and deployment targets.

Add support for a new OAuth provider (e.g., NewPlatform)

1. Create scope enum in src/main/java/me/zhyd/oauth/enums/scope/AuthNewPlatformScope.java implementing AuthScope interface with platform-specific permissions (src/main/java/me/zhyd/oauth/enums/scope/AuthNewPlatformScope.java)
2. Add provider entry to AuthDefaultSource enum with authorize/token/userinfo URLs and default scope (src/main/java/me/zhyd/oauth/config/AuthDefaultSource.java)
3. Create AuthNewPlatformConfig extending AuthConfig to hold clientId, clientSecret, redirectUri for NewPlatform (src/main/java/me/zhyd/oauth/config/AuthNewPlatformConfig.java)
4. Create AuthNewPlatformRequest implementing OAuth 2.0 flow: authorize → callback(code+state) → exchange for token → fetch user profile, parsing NewPlatform's JSON schema into AuthUser (src/main/java/me/zhyd/oauth/request/AuthNewPlatformRequest.java)
5. Register new request class in AuthRequestBuilder.getRequest() factory method switch statement (src/main/java/me/zhyd/oauth/AuthRequestBuilder.java)

Customize OAuth scopes for an existing provider

1. Extend the provider's scope enum (e.g., AuthGithubScope) with additional scope constants if not already present (src/main/java/me/zhyd/oauth/enums/scope/AuthGithubScope.java)
2. When building AuthRequest via AuthRequestBuilder, pass custom scopes in the config's scopes() method (src/main/java/me/zhyd/oauth/config/AuthConfig.java)
3. AuthRequest implementation will include custom scopes in the authorization URL via getAuthorizationUrl() (src/main/java/me/zhyd/oauth/request/AuthGithubRequest.java)

Implement custom state caching (e.g., Redis instead of in-memory)

1. Create CustomRedisStateCache implementing AuthStateCache interface with save(state, expiryTime) and get(state) methods (src/main/java/me/zhyd/oauth/cache/AuthRedisStateCache.java)
2. Pass custom cache to AuthRequestBuilder via .setStateCache(new AuthRedisStateCache()) when building requests (src/main/java/me/zhyd/oauth/AuthRequestBuilder.java)
3. Cache implementation is consumed by AuthRequest.validate() during callback validation to verify CSRF state parameter (src/main/java/me/zhyd/oauth/request/AuthRequest.java)

Add provider-specific error code handling

1. Create provider error enum (e.g., AuthNewPlatformErrorCode) to map provider-specific error codes to standardized messages (src/main/java/me/zhyd/oauth/enums/AuthNewPlatformErrorCode.java)
2. In AuthNewPlatformRequest.getAccessToken() or parseUserInfo(), check error codes from provider response and throw AuthException with mapped message (src/main/java/me/zhyd/oauth/request/AuthNewPlatformRequest.java)

• Java 1.8+ — Mature, strongly-typed language enabling provider-specific implementations with minimal boilerplate via generics and interfaces
• Maven — Standard Java dependency management and build tool; enables reproducible builds and automated deployment to Maven Central
• HTTPClient (likely Apache or similar) — Standardizes HTTP/HTTPS communication across 40+ OAuth providers with connection pooling and request signing
• JSON parsing (likely FastJSON based on pom.xml) — Fast deserialization of heterogeneous provider API responses into normalized AuthUser/Auth

(1) OAuth State parameter caching requires careful configuration in distributed systems—default AuthDefaultCache uses JVM memory and won't sync across multiple instances; must implement custom AuthCache for Redis/Memcached. (2) Each OAuth provider has different scope requirements and permission models; blindly using default scopes may fail authorization with some providers. (3) Callback URL must be registered identically on the OAuth provider's platform (including protocol, domain, path, port)—mismatches cause silent failures. (4) Refresh token support varies by provider; not all 40+ platforms support token refresh, requiring re-authorization. (5) Java 1.8 baseline means no use of newer Java features; upgrading Java version in your app doesn't enable language features in this library.

• OAuth 2.0 Authorization Code Grant Flow — The core flow this library implements: user redirects to provider, authenticates, grants permission, and your app exchanges an authorization code for access tokens and user profile data
• State Parameter and CSRF Prevention — JustAuth's caching layer manages State parameters to prevent cross-site request forgery attacks during OAuth callbacks; misconfiguring this in distributed systems is a common security trap
• Scope-based Permission Model — Each OAuth provider defines different scopes (read profile, email, repositories, etc.); JustAuth allows custom scope configuration per provider, critical for requesting minimal necessary permissions
• Token Refresh and Expiration Handling — Access tokens expire and some providers issue refresh tokens; understanding this lifecycle matters for building production-grade login systems that don't require re-authentication
• Adapter Pattern for Provider Abstraction — JustAuth uses this pattern to unify 40+ different OAuth provider APIs into one AuthRequest interface, reducing complexity and boilerplate when adding new providers
• Pluggable Cache Strategy — The AuthCache interface allows swapping between in-memory, Redis, Memcached, or custom implementations without changing core logic; essential pattern for scaling to distributed deployments
• Dependency Inversion for HTTP Client Selection — Rather than hardcoding a specific HTTP library (HttpClient, OkHttp, etc.), JustAuth lets developers choose their own, reducing dependency conflicts in large projects

• pac4j/pac4j — Broader Java security framework that also abstracts OAuth and SAML, but heavier-weight than JustAuth with more features like authorization and session management
• spring-projects/spring-security-oauth — Spring's native OAuth support; JustAuth is simpler and framework-agnostic, while Spring Security OAuth integrates deeper with Spring's authentication ecosystem
• AuthJavaEE/AuthJavaEE — Lighter alternative OAuth library for Java, but with fewer providers (8-10) compared to JustAuth's 40+; good comparison for minimalist use cases
• azerothyang/Autumn — Chinese-focused alternative OAuth library; fewer providers but tightly integrated with domestic platforms like WeChat and Alipay
• yadong.zhang/JustAuth-demo — Official companion repository with runnable Spring Boot examples using JustAuth; essential reference for implementation patterns

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 unit tests for AuthRequestBuilder and scope enums

The repo has 40+ OAuth provider implementations with corresponding scope enums (AuthAmazonScope, AuthAppleScope, AuthBaiduScope, AuthCodingScope, AuthDingTalkScope, etc.) but no visible test directory structure. AuthRequestBuilder is a critical entry point for all OAuth flows and lacks test coverage. Adding unit tests would ensure scope validation, builder pattern correctness, and prevent regressions as new providers are added.

• [ ] Create src/test/java/me/zhyd/oauth directory structure mirroring src/main/java
• [ ] Add AuthRequestBuilderTest.java to test builder instantiation, configuration validation, and error handling for all 40+ supported providers
• [ ] Add AuthScopeSuite.java with parameterized tests for each scope enum (AuthAmazonScope, AuthAppleScope, etc.) to verify scope values are correctly defined
• [ ] Add AuthDefaultCacheTest.java and AuthDefaultStateCacheTest.java to test cache behavior under concurrent access

Add GitHub Actions workflow for multi-JDK compatibility testing

The project targets JDK 1.8+ (per badge and pom.xml), but .github/workflows only contains deploy-snapshot.yml and test-pr.yml. There's no explicit matrix testing across JDK 8, 11, 17, and 21 to catch compatibility regressions early, especially important for a widely-used OAuth library that may be used in legacy (Java 8) and modern (Java 21+) environments.

• [ ] Create .github/workflows/test-jdk-matrix.yml with matrix strategy testing against JDK [8, 11, 17, 21]
• [ ] Configure the workflow to run 'mvn clean test' for each JDK version on push to main/master and PRs
• [ ] Add job failure conditions to block PRs if any JDK version fails, ensuring backward and forward compatibility

Create INTEGRATION_TESTING.md with provider-specific test credentials setup guide

JustAuth supports 40+ OAuth providers, but there's no documented guide for contributors wanting to add or modify provider implementations. New contributors need to understand how to obtain test credentials for each provider (GitHub, Weibo, DingTalk, WeChat, etc.), configure them safely, and run integration tests. This guide would dramatically reduce friction for onboarding contributors to the provider implementation layer.

• [ ] Create docs/INTEGRATION_TESTING.md documenting how to obtain test OAuth credentials for major providers (GitHub, Google, Facebook, WeChat, Weibo, DingTalk, Gitee, LinkedIn, Microsoft)
• [ ] Document environment variable configuration patterns (e.g., JUSTAUTH_GITHUB_CLIENT_ID, JUSTAUTH_GITHUB_CLIENT_SECRET) for safe local testing without committing secrets
• [ ] Add a matrix table showing required scopes/permissions for each provider to test successfully, referencing the corresponding AuthXxxScope enum classes
• [ ] Include troubleshooting section for common OAuth redirect URI mismatch errors and provider-specific configuration gotchas

• Add caching layer tests for distributed scenarios: Currently AuthCacheScheduler.java lacks integration tests for concurrent cache expiration in multi-threaded environments. Add JUnit tests using ExecutorService to verify thread-safety of cache cleanup.
• Document OAuth State parameter validation in examples: No validation example shown in visible files for the State parameter returned from callback. Add concrete code example in example.md showing how to validate State and prevent CSRF attacks.
• Create a custom HttpClient provider example: Library claims 'choose your own HTTP client' but no example shown for integrating Apache HttpClient or OkHttp. Add sample implementation guide in docs showing how to extend for custom HTTP configuration (proxies, timeouts, SSL).

• High · Incomplete POM.xml Configuration — pom.xml. The pom.xml file appears truncated in the provided content. The dependency management section is incomplete, making it impossible to perform a comprehensive analysis of all third-party dependencies for known vulnerabilities. This could hide critical security issues in transitive dependencies. Fix: Provide the complete pom.xml file. Additionally, implement a Maven dependency check plugin (e.g., OWASP Dependency-Check) in the CI/CD pipeline to automatically scan for known vulnerabilities in dependencies.
• Medium · Missing Security Configuration in CI/CD — .github/workflows/. While GitHub Actions workflows are present (.github/workflows/deploy-snapshot.yml, test-pr.yml), the actual workflow configurations are not provided. Deployment workflows often handle sensitive credentials and should enforce strict security practices. Without visibility, potential risks include: exposed secrets in logs, insufficient authentication checks, or unsafe artifact handling. Fix: Review and validate all GitHub Actions workflows. Implement: 1) Secret management via GitHub Secrets only, 2) OIDC token-based authentication instead of personal access tokens, 3) Branch protection rules, 4) Signed commits requirement, 5) Code review requirements before deployment.
• Medium · Third-Party OAuth Integration Security — src/main/java/me/zhyd/oauth/. As an OAuth library integrating with 40+ third-party platforms (GitHub, Google, Facebook, WeChat, Alipay, etc.), the codebase likely handles authentication tokens and sensitive user data. Without reviewing the actual implementation, potential risks include: insecure token storage, insufficient validation of OAuth responses, CSRF token mishandling, or improper redirect URI validation. Fix: 1) Implement strict OAuth 2.0 security guidelines (RFC 6749, RFC 8252). 2) Use secure random generation for state parameters. 3) Validate all redirect URIs against allowlists. 4) Implement PKCE (Proof Key for Code Exchange) for mobile flows. 5) Conduct security code review and penetration testing for OAuth flows. 6) Add HSTS headers and other security headers.
• Medium · Cache Implementation Security — src/main/java/me/zhyd/oauth/cache/. The cache module (AuthCache, AuthDefaultCache, AuthDefaultStateCache) is present but implementation details are not visible. Caching authentication tokens or state values improperly could lead to: token replay attacks, session fixation, or unauthorized access if cache is not properly isolated. Fix: 1) Implement cache invalidation based on token expiration times. 2) Use secure, isolated cache stores (not in-memory shared across users). 3) Implement cache size limits and TTL to prevent memory exhaustion. 4) For distributed deployments, use Redis with encryption (TLS) and authentication. 5) Never cache sensitive data (passwords, refresh tokens) in plaintext.
• Low · Outdated Java Version Target — pom.xml (properties section). The project targets Java 1.8 (maven.compiler.target=1.8), which reached End-of-Life in December 2030 (commercially) but has been superseded. While Java 8 is still widely used, newer LTS versions (17, 21) provide better security features and performance. Fix: Consider upgrading to Java 11 LTS minimum (as Java 8 is aging) or Java 17/21 LTS for modern security features and long-term support. Ensure backward compatibility testing before upgrade.
• Low · Missing Security Policy and Vulnerability Disclosure — Repository root. While the repository has CODE_OF_CONDUCT.md, there is no visible SECURITY.md file for responsible vulnerability disclosure. This makes it difficult for security researchers to report vulnerabilities privately. Fix: Create a SECURITY.md file following GitHub's recommended format. Include: 1) Clear instructions for reporting security vulnerabilities, 2) A responsible disclosure timeline, 3) Contact information for the security team, 4) Commitment to timely patching and updates.
• Low · License Verification — pom.xml (license section). The project is licensed under MIT, which is permissive. However, dependency licenses should be verified to ensure compatibility and that no GPL or restrictive licenses create compliance issues. Fix: Implement Maven license-maven-plugin to automatically verify all dependency licenses during build. Ensure no LGPL

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.