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/dromara/Sa-Token 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2w ago
• 2 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ No CI workflows detected

_{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 dromara/Sa-Token repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dromara/Sa-Token.

What it runs against: a local clone of dromara/Sa-Token — 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 dromara/Sa-Token | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java" \\
  && ok "sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java" \\
  || miss "missing critical file: sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java"
test -f "sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java" \\
  && ok "sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java" \\
  || miss "missing critical file: sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java"
test -f "sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContext.java" \\
  && ok "sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContext.java" \\
  || miss "missing critical file: sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContext.java"
test -f "sa-token-core/src/main/java/cn/dev33/satoken/dao/SaTokenDao.java" \\
  && ok "sa-token-core/src/main/java/cn/dev33/satoken/dao/SaTokenDao.java" \\
  || miss "missing critical file: sa-token-core/src/main/java/cn/dev33/satoken/dao/SaTokenDao.java"
test -f "sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaAnnotationHandlerInterface.java" \\
  && ok "sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaAnnotationHandlerInterface.java" \\
  || miss "missing critical file: sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaAnnotationHandlerInterface.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 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
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/dromara/Sa-Token"
  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).

Sa-Token is a lightweight, one-stop Java authentication and authorization framework that handles login sessions, permission checks, distributed sessions, SSO, OAuth2.0, and API key/JWT validation. It eliminates boilerplate by providing simple static APIs (e.g., StpUtil.login(id), StpUtil.checkLogin()) and annotation-based guards (@SaCheckPermission, @SaCheckRole) for securing Java web applications across Spring Boot 2/3/4, Solon, and JFinal. Multi-module Maven monorepo: sa-token-core/ contains the engine (cn.dev33.satoken package with annotation processors, session managers, permission validators), sa-token-starter/ provides Spring Boot integration, sa-token-plugin/ extends with optional features (OAuth2, JWT, etc.), sa-token-dependencies/ and sa-token-bom/ manage version alignment. Entry point is SaManager.java; decorators like @SaCheckLogin intercept via Spring AOP.

Java backend developers building web applications who need production-grade authentication without implementing complex session management, permission models, or OAuth2 flows themselves. DevOps teams securing microservices and API gateways. Teams deploying SSO across multiple applications.

Highly mature and production-ready. Currently at v1.45.0 with active development visible in commit history and memo files tracking recent debugging sessions. Gitee badges show strong community adoption (stars across GitHub, Gitee, and AtomGit). Comprehensive documentation (sa-token.cc) indicates long-term commitment and stability since initial 2020 release.

Low risk for core functionality. Single-maintainer model (click33) evident from developer info, though community appears engaged. Large monorepo with many integration modules (starter/, plugin/) increases surface area for regressions. No visible test files in top 60 imports suggests test suite may be in separate locations; verify coverage before adopting. Maven-based dependency management is mature but requires monitoring for transitive vulnerabilities.

Recent work visible in .MEMO/ folder: debugging session notes (2026-3-1), dependency consolidation attempts, and version management improvements. Agent skills directory suggests automation for commit messages, changelog organization, and import cleanup. Active maintenance with memory artifacts indicating iterative refinement of dependency relationships.

git clone https://github.com/dromara/sa-token.git && cd sa-token && mvn clean install. For testing, run mvn test.bat (on Windows) or mvn clean test. Batch files in root (mvn clean.bat, mvn test.bat, preview-doc.bat) indicate common local workflows.

Daily commands: For development: mvn clean.bat (Windows) or mvn clean install (Unix). Preview documentation locally with preview-doc.bat. For test execution: mvn test.bat or mvn test. Add sa-token-spring-boot-starter v1.45.0 to your Spring Boot pom.xml; no configuration file required—works out of box.

• sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java — Core manager singleton that orchestrates all Sa-Token functionality—every contributor must understand the initialization and delegation patterns here.
• sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java — Central configuration class defining all customizable properties and defaults—required reading for understanding feature toggles and security settings.
• sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContext.java — Abstract context interface for request/response/storage isolation—critical for understanding how Sa-Token integrates with different frameworks.
• sa-token-core/src/main/java/cn/dev33/satoken/dao/SaTokenDao.java — Data access interface for session/token persistence—must understand this to implement custom storage backends.
• sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaAnnotationHandlerInterface.java — Handler chain interface for annotation-based security checks—defines the extensible plugin model for authorization decorators.
• pom.xml — Parent POM defining build configuration, version management, and module composition—essential for dependency resolution and release process.
• sa-token-core/src/main/java/cn/dev33/satoken/error/SaErrorCode.java — Centralized error code enumeration—required for understanding error handling contracts across all modules.

Add a Custom DAO Implementation (e.g., Redis Backend)

1. Create a new class implementing SaTokenDao interface (sa-token-core/src/main/java/cn/dev33/satoken/dao/SaTokenDao.java)
2. Implement required methods: get(), set(), delete(), getObject(), setObject() to delegate to Redis client ((new file) your-module/src/main/java/com/yourorg/SaTokenDaoRedisImpl.java)
3. Register your DAO in SaManager by setting SaTokenConfig.setDaoInterface(new SaTokenDaoRedisImpl()) (sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java)

Add a Custom Authorization Annotation Handler

1. Create a custom annotation in sa-token-core/src/main/java/cn/dev33/satoken/annotation/ (sa-token-core/src/main/java/cn/dev33/satoken/annotation/SaCheckLogin.java)
2. Implement SaAnnotationHandlerInterface to define check logic (sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaAnnotationHandlerInterface.java)
3. Create handler class extending appropriate base handler (sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaCheckLoginHandler.java)
4. Register handler in SaManager during initialization (sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java)

Implement Custom Request/Response Context for a New Framework

1. Create a class implementing SaTokenContext interface (sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContext.java)
2. Implement methods for accessing request headers, response headers, cookies, and session storage ((new file) sa-token-frameworks/sa-token-yourframework/src/main/java/cn/dev33/satoken/context/SaTokenContextYourFrameworkImpl.java)
3. Set your implementation in SaManager.setSaTokenContext() during framework initialization (sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java)

Add a New Authentication Scheme (e.g., Custom OAuth2 Flow)

1. Create annotation class for the new scheme (sa-token-core/src/main/java/cn/dev33/satoken/annotation/SaCheckHttpBasic.java)
2. Create handler implementation processing the annotation (sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaCheckHttpBasicHandler.java)
3. Register handler via SaManager and document in configuration (sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java)

• Maven multi-module build — Enables modular architecture where core auth logic is separated from framework adapters (Spring, Solon, Quarkus, etc.), allowing independent versioning and optional dependencies.
• ThreadLocal-based context (SaHolder) — Avoids passing context objects through every method signature; simplifies API surface while maintaining isolation in multi-threaded servlet environments.
• Annotation-driven security decorators — Leverages Spring/Jakarta framework annotation processors for declarative authorization, reducing boilerplate and improving code readability.
• Pluggable DAO abstraction (SaTokenDao) — Decouples token storage from business logic, enabling swappable backends (Redis, database, in-memory) without recompiling core.

• ThreadLocal-based context instead of explicit context objects
  • Why: Simpler API and less boilerplate for developers using Sa-Token.
  • Consequence: undefined

1. No configuration required out-of-box, but session persistence defaults to in-memory—production deployments must explicitly configure Redis or other backends via SaManager. 2. Java 1.8+ required (jdk.version=1.8 in pom.xml). 3. Annotation interception relies on Spring AOP—ensure @EnableAspectJAutoProxy is active if using non-Spring Boot frameworks. 4. Multi-module builds: mvn clean install must run from monorepo root; individual module builds may fail due to BOM dependencies. 5. .MEMO/ notes suggest recent dependency consolidation attempts may indicate transitive conflict resolution needed—check maven-shade-plugin config if embedding.

• Token-Based Session Management — Sa-Token's core is stateful session tracking via tokens (login(), checkLogin()); understanding session vs. stateless JWT tradeoffs is essential for choosing deployment mode
• Role-Based Access Control (RBAC) — Sa-Token's @SaCheckRole annotation enforces RBAC; this is the mental model for permission hierarchies the framework assumes (@SaCheckPermission extends it to fine-grained)
• Aspect-Oriented Programming (AOP) — Sa-Token annotations (@SaCheck*) are intercepted via Spring AOP; understanding joinpoints, advice, and aspectj syntax is required to debug permission failures or add custom checks
• OAuth2.0 Authorization Code Flow — Sa-Token offers OAuth2 module (mentioned in description); understanding grant types, scopes, and token refresh is essential if integrating third-party login or multi-tenant SSO
• JWT (JSON Web Tokens) Claims and Signing — Sa-Token integrates JWT; payload structure, signature verification, and expiration claims are critical for stateless session alternatives or mobile clients
• Pluggable Backend Pattern (Dependency Injection) — Sa-Token session storage is abstract (in-memory, Redis, custom)—SaManager injection of session handlers is a dependency injection pattern essential for scaling and testing
• Single Sign-On (SSO) and Authentication Delegation — Sa-Token explicitly supports SSO (listed as core module); understanding session replication, ticket validation, and cross-domain cookie handling is needed for enterprise deployments

• spring-projects/spring-security — Industry-standard Spring Security solves similar authentication/authorization but with significantly more boilerplate; Sa-Token's selling point is simpler API for common cases
• tymondesigns/jwt-auth — Laravel JWT library serving similar lightweight auth niche; helps understand Sa-Token's design philosophy of being one-stop without external JWT library dependency
• aerospike-community/aerospike-rest-client — Shows patterns for pluggable session backends (Sa-Token supports Redis, in-memory, custom stores); reference for session storage abstraction
• dromara/hutool — Companion utility library often used alongside Sa-Token in Dromara ecosystem projects; provides string, encryption, and collection helpers Sa-Token assumes
• alibaba/druid — Often paired with Sa-Token in Chinese enterprise Spring Boot stacks for connection pooling and SQL firewalling alongside session management

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 annotation handlers in sa-token-core

The sa-token-core module contains 9 annotation handler classes (SaCheckLoginHandler, SaCheckPermissionHandler, SaCheckRoleHandler, etc.) in sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/ but there is no visible test directory for these critical components. These handlers are the backbone of the framework's authentication/authorization system and need robust test coverage for different scenarios (valid tokens, expired tokens, missing permissions, etc.).

• [ ] Create sa-token-core/src/test/java/cn/dev33/satoken/annotation/handler/ directory structure
• [ ] Add unit tests for SaCheckLoginHandler covering: valid login, no login, different token types
• [ ] Add unit tests for SaCheckPermissionHandler covering: single permission, multiple permissions, wildcard matching, permission denial
• [ ] Add unit tests for SaCheckRoleHandler covering: role validation, role inheritance, invalid roles
• [ ] Add unit tests for SaCheckHttpBasicHandler and SaCheckHttpDigestHandler covering: valid credentials, invalid credentials, missing headers
• [ ] Add unit tests for SaCheckOrHandler covering: OR logic between multiple conditions
• [ ] Ensure tests mock SaManager and StpInterface appropriately

Create GitHub Actions CI workflow for multi-version Java and Spring compatibility testing

The project supports JDK 1.8+ and integrates with Spring ecosystem (evident from sa-token-starter module), but there is no visible GitHub Actions workflow in .github/workflows/. The .MEMO directory shows dependency relationship drafts, suggesting version compatibility is a concern. A CI workflow should test against multiple Java versions (8, 11, 17, 21) and Spring versions to catch regression issues early.

• [ ] Create .github/workflows/java-matrix-tests.yml with matrix strategy for Java versions [8, 11, 17, 21]
• [ ] Add matrix testing for Spring Boot versions [2.x, 3.x] to ensure sa-token-starter compatibility
• [ ] Configure workflow to run 'mvn clean test' across all modules (sa-token-core, sa-token-starter, sa-token-plugin)
• [ ] Add workflow triggers for: push to master, pull requests, and weekly schedule
• [ ] Include code coverage reporting (JaCoCo) with minimum threshold check
• [ ] Add verification for sa-token-bom (BOM) to ensure dependency consistency across versions

Add integration tests for distributed session management and SSO scenarios

The repository description explicitly mentions 'distributed Session sessions' and 'SSO single point login' as core features, but the file structure shows no visible test coverage for these complex distributed scenarios. The .agents/skills directory suggests the project uses assistant-driven development, indicating these areas may need systematic testing documentation. Integration tests should validate distributed session sync, SSO token exchange, and cross-service authentication.

• [ ] Create sa-token-core/src/test/java/cn/dev33/satoken/integration/distributed/ test directory
• [ ] Add integration tests for distributed session scenarios: session creation, sync across instances, timeout handling, invalidation broadcast
• [ ] Add integration tests for SSO: token generation, cross-domain validation, logout cascade, session linkage
• [ ] Add tests for OAuth2.0 flow coverage: authorization code flow, token refresh, scope validation
• [ ] Add tests for JWT integration: token creation, validation, refresh token logic, blacklist scenarios
• [ ] Document test setup instructions in sa-token-core/README or .agents/skills with Redis/distributed cache requirements

• Write unit tests for sa-token-core/src/main/java/cn/dev33/satoken/annotation/ package—visible from file structure that annotation classes exist but no test files appear in top 60 imports. Start with SaCheckLogin and SaCheckPermission happy-path and error scenarios.
• Add documentation examples to README for microservice gateway authentication scenario (currently mentions it as a core module but shows no code example). Cross-reference the OAuth2.0 and SSO sections which appear implemented but underdocumented in snippet.
• Implement missing HTTP Digest authentication test coverage—SaCheckHttpDigest.java exists but digest implementation is often subtly broken (replay attacks, nonce handling). Add integration tests against a real HTTP client.

Sa-Token is a mature authentication framework with a modular architecture, but static analysis reveals several areas of concern. The primary risks involve annotation-based security controls that require careful validation, ThreadLocal usage in concurrent environments, and missing security infrastructure (SECURITY.md, dependency scanning plugins). No hardcoded credentials or critical injection vulnerabilities are evident from the file structure, and the use of Apache 2.0 licensing is transparent. The framework appears to follow reasonable security patterns but would benefit from explicit security scanning in the build process, comprehensive security documentation, and additional validation around context storage mechanisms. Organizations using Sa-Token should implement additional security reviews of their specific implementations, particularly around annotation configuration and thread management.

• Medium · Incomplete POM Configuration - Missing Security Headers — pom.xml - developers section. The pom.xml file shows incomplete developer email configuration (truncated at '239358471'), which could indicate configuration management issues. More critically, there's no evidence of security plugin configurations like dependency-check, OWASP checks, or security scanning in the build process. Fix: Complete the developer configuration and add security scanning plugins: maven-dependency-check-plugin, org.owasp:dependency-check-maven, and spotbugs-maven-plugin.
• Medium · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file found in the repository root. This is important for a widely-used authentication framework to establish responsible disclosure practices. Fix: Create a SECURITY.md file documenting vulnerability reporting procedures and security best practices for users of Sa-Token.
• Medium · No Visible Dependency Version Pinning Strategy — pom.xml - modules section and dependency management. The pom.xml uses '${revision}' property management but there's no visible BOM (Bill of Materials) enforcement across modules. The sa-token-special-dependencies module suggests complex dependency management that could introduce version conflicts. Fix: Implement strict dependency version management using Maven enforcer plugin to prevent dependency conflicts. Ensure all transitive dependencies are explicitly declared with versions.
• Medium · Annotation-Based Security Controls - Potential Runtime Vulnerabilities — sa-token-core/src/main/java/cn/dev33/satoken/annotation/. The framework relies heavily on annotations (@SaCheckLogin, @SaCheckPermission, @SaCheckRole, etc.) for security enforcement. Annotations are runtime-based and can be bypassed if not properly validated at all entry points. Misconfiguration could lead to authorization bypass. Fix: Ensure all annotation handlers validate security checks consistently. Implement comprehensive integration tests for annotation-based security. Document potential bypass scenarios. Consider defense-in-depth with multiple validation layers.
• Medium · ThreadLocal Usage for Context Storage — sa-token-core/src/main/java/cn/dev33/satoken/context/SaTokenContextForThreadLocal*.java. The framework uses ThreadLocal for context storage (SaTokenContextForThreadLocal*). ThreadLocal can cause information leakage in thread pool environments (e.g., servlet containers, virtual threads in Java 21+) if not properly cleaned up. Fix: Implement proper ThreadLocal cleanup in finally blocks or use try-with-resources. Consider adding support for virtual threads in Java 21+. Add warnings in documentation about thread pool usage.
• Low · Mock Context Classes in Production Code — sa-token-core/src/main/java/cn/dev33/satoken/context/mock/. Mock classes (SaRequestForMock, SaResponseForMock, SaStorageForMock) are included in the main source tree rather than test directory, creating risk of accidental use in production. Fix: Move mock classes to src/test directory or clearly document that they're for testing only. Add warnings in Javadoc and consider using test-jar artifact if these are needed as utilities.
• Low · Incomplete Documentation in Repository — .MEMO/ directory, README.md. Several .MEMO and draft files suggest ongoing refactoring and potential documentation gaps. The README snippet is truncated and incomplete. Fix: Clean up repository of temporary files. Ensure comprehensive security documentation is available to users regarding proper configuration and usage.

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.