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/hs-web/hsweb-framework 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 today
• 6 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% 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 hs-web/hsweb-framework repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hs-web/hsweb-framework.

What it runs against: a local clone of hs-web/hsweb-framework — 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 hs-web/hsweb-framework | 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 5.0.x exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/Authentication.java" \\
  && ok "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/Authentication.java" \\
  || miss "missing critical file: hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/Authentication.java"
test -f "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/AuthenticationManager.java" \\
  && ok "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/AuthenticationManager.java" \\
  || miss "missing critical file: hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/AuthenticationManager.java"
test -f "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ReactiveAuthenticationManager.java" \\
  && ok "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ReactiveAuthenticationManager.java" \\
  || miss "missing critical file: hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ReactiveAuthenticationManager.java"
test -f "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Authorize.java" \\
  && ok "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Authorize.java" \\
  || miss "missing critical file: hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Authorize.java"
test -f "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.java" \\
  && ok "hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.java" \\
  || miss "missing critical file: hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/hs-web/hsweb-framework"
  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).

hsweb-framework is a fully reactive enterprise backend management system built on Spring Boot 2.x and Spring WebFlux using Project Reactor. It provides the first complete reactive implementation of RBAC and data-level permission control, responsive CRUD operations via R2DBC (supporting H2, MySQL, SQL Server, PostgreSQL), and multi-dimensional authorization management—all without sacrificing performance through non-blocking I/O. Maven monorepo with modular structure: hsweb-authorization/ contains core auth APIs (Authentication, AuthenticationManager, Permission, Role, Dimension APIs); hsweb-core/ holds framework utilities; hsweb-datasource/, hsweb-concurrent/, hsweb-logging/ each encapsulate cross-cutting concerns; hsweb-starter/ bundles autoconfiguration; hsweb-system/ packages built-in business features (user management, permissions, dictionaries).

Java backend engineers building enterprise admin dashboards who need production-grade, fully asynchronous permission management and database access without blocking—particularly teams adopting reactive programming and needing to avoid servlet-based architectures.

Actively maintained with version 5.0.2-SNAPSHOT released, comprehensive CI/CD via GitHub Actions (maven-publish workflows for 4.x and 5.x branches, pull request validation), and modular architecture spanning 8 major subsystems (authorization, commons, concurrent, core, datasource, logging, starter, system). Production-ready for reactive Spring Boot deployments.

Primary risk is the reactive programming learning curve—requires deep understanding of Project Reactor and Spring WebFlux; team must be comfortable with backpressure, publishers, and async composition. Dependency on R2DBC (relatively newer than JDBC) means fewer community solutions for edge cases. Single-maintainer appearance and 5.0.2-SNAPSHOT version suggests ongoing but potentially slow release cycles.

Active development on version 5.0.x branch alongside 4.0.x maintenance track. GitHub workflows show regular Maven publishing and pull request validation. Documentation exists but is modular (each submodule has its own README). Authorization module documentation includes custom data access patterns and permission definitions.

Clone the repository: git clone https://github.com/hs-web/hsweb-framework.git && cd hsweb-framework. Use the included Maven wrapper: ./mvn clean install (or bash build.sh). Reference the Spring Boot starter modules in your pom.xml and follow per-module README docs in hsweb-authorization/, hsweb-core/, etc.

Daily commands: After Maven install, modules are published as dependencies. To run examples, clone https://github.com/zhou-hao/hsweb4-examples and follow its build steps. For local development: ./mvn clean compile in the hsweb-framework root validates all modules.

• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/Authentication.java — Core authentication interface defining the principal contract for all authentication operations in the framework.
• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/AuthenticationManager.java — Central manager for authentication lifecycle; all login/logout flows route through this interface.
• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ReactiveAuthenticationManager.java — Reactive variant of AuthenticationManager required for Project Reactor non-blocking authentication in this Spring WebFlux framework.
• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Authorize.java — Primary annotation for declaring authorization requirements on methods and classes; foundational for AOP-based permission enforcement.
• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.java — Pluggable handler interface for data-level access control; implements the framework's row-level security strategy.
• hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/define/AuthorizeDefinition.java — Metadata abstraction capturing authorization rules from annotations; drives the entire authorization definition and enforcement pipeline.

Add a Custom Authorization Annotation

1. Create a new annotation in hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/ following the pattern of @Authorize.java (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Authorize.java)
2. Define a corresponding AuthorizeDefinition subclass in the define package to capture annotation metadata (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/define/AuthorizeDefinition.java)
3. Register an AuthorizeDefinitionCustomizer to parse your annotation and populate the definition metadata (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/define/AuthorizeDefinitionCustomizer.java)

Implement Custom Data Access Control

1. Extend DataAccessConfig to define your custom data access rules and configuration model (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessConfig.java)
2. Implement DataAccessHandler to apply filtering logic based on your custom config (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.java)
3. Register the handler in DataAccessConfiguration to make it discoverable by the framework (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessConfiguration.java)

Add Custom Authentication Logic

1. Implement AuthenticationManager (or ReactiveAuthenticationManager for non-blocking) with your authentication strategy (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/AuthenticationManager.java)
2. Register your manager via AuthenticationManagerProvider so it's resolved at runtime (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ReactiveAuthenticationManagerProvider.java)
3. Optionally listen to AuthorizationBeforeEvent to intercept and customize the authentication flow (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/events/AuthorizationBeforeEvent.java)

Define New Permission Dimensions

1. Create a custom DimensionType by extending DefaultDimensionType for your business dimension (e.g., department, region) (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/DefaultDimensionType.java)
2. Implement DimensionProvider to supply dimension values from your data source (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/DimensionProvider.java)
3. Register the provider with DimensionManager to enable multi-dimensional permission queries (hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/dimension/DimensionManager.java)

Reactive programming requires context propagation awareness—ThreadLocal patterns fail; use ReactiveAuthenticationHolder and context-propagation library (io.micrometer:context-propagation) explicitly. R2DBC support varies by database dialect; verify your target DB is in the supported list (H2, MySQL 5.7+, SQL Server 2012+, PostgreSQL 10+). No built-in support for non-reactive JDBC or traditional MVC—this is intentional and enforced. Spring WebFlux runs on Netty by default; servlet containers (Tomcat, etc.) won't work. Multi-module Maven builds can be slow; use ./mvn clean install -DskipTests for quick iteration.

• Reactive Streams & Project Reactor (Mono/Flux) — hsweb is built entirely on Reactor—every auth check, DB query, and permission evaluation returns Mono or Flux; you must understand backpressure, subscription, and operator composition to extend this framework
• R2DBC (Reactive Relational Database Connectivity) — Core data layer abstraction replacing JDBC; hsweb-datasource and all CRUD operations depend on R2DBC drivers—you need familiarity with reactive connection pooling and statement execution without thread blocking
• RBAC (Role-Based Access Control) with Data-Level Filtering — hsweb implements both traditional role checks (via Role, Permission) and row-level access control (via DataAccessHandler); understanding the distinction is crucial for correct permission modeling in enterprise scenarios
• Multi-Dimensional Authorization — hsweb's Dimension and DimensionType APIs allow permission contexts beyond simple role hierarchies (e.g., org unit, project, location)—novel design pattern in the reactive auth space that enables flexible, context-aware access decisions
• Spring WebFlux & Netty Non-Blocking I/O — hsweb runs on Spring WebFlux (not Spring MVC); all request handling, routing, and middleware must be non-blocking—ThreadLocal and servlet APIs are incompatible
• Context Propagation in Reactive Pipelines — ThreadLocal storage (e.g., SecurityContext in servlet apps) breaks with reactive code; hsweb uses ReactiveAuthenticationHolder and Micrometer context-propagation to thread auth state through async chains without blocking
• DSL-Based Query & Update Builders — hsweb provides fluent, chainable APIs for building SQL without string concatenation (SQL injection protection); understanding the builder pattern here avoids accidental query bugs

• hs-web/hsweb-easy-orm — Underlying ORM abstraction layer for R2DBC that hsweb-framework depends on; essential for reactive CRUD operations
• zhou-hao/hsweb4-examples — Official example applications demonstrating hsweb-framework usage patterns (user management, permission setup, file upload)
• spring-projects/spring-security — Alternative for reactive auth but less integrated with data-level access control; hsweb-framework's authorization module complements or replaces it
• r2dbc/r2dbc-spi — Core reactive database abstraction that hsweb-datasource and hsweb-easy-orm build upon; understanding R2DBC is prerequisite knowledge
• projectreactor/reactor-core — Foundation reactive library providing Mono/Flux primitives used throughout hsweb for non-blocking composition

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 reactive authorization annotations processor

The hsweb-authorization-api module contains multiple authorization annotation classes (@Authorize, @DataAccess, @DimensionDataAccess, @FieldDataAccess, etc.) but there are no visible test files in the file structure. Given this is a reactive framework with complex permission handling, unit tests validating annotation processing, AOP interception, and reactive context propagation are critical for reliability. This is especially important for the @DataAccess and dimension-based access control features.

• [ ] Create src/test/java/org/hswebframework/web/authorization/annotation/AuthorizeAnnotationProcessorTest.java
• [ ] Create src/test/java/org/hswebframework/web/authorization/access/DataAccessHandlerTest.java testing all DefaultDataAccessType implementations
• [ ] Create src/test/java/org/hswebframework/web/authorization/ReactiveAuthenticationHolderTest.java validating reactive context handling
• [ ] Add tests for @DimensionDataAccess and @FieldDataAccess annotation combinations
• [ ] Ensure tests validate both success and failure paths for permission denials

Implement missing CI workflow for 5.x branch authorization module validation

The .github/workflows/ directory shows separate maven-publish and pull_request workflows for 4x and 5x branches, but there's no indication that authorization-api module is being validated with specific security-focused tests in CI. Authorization is the most critical security component, deserving dedicated workflow validation for reactive context propagation, permission edge cases, and concurrent access scenarios.

• [ ] Create .github/workflows/authorization-tests-5x.yml that runs Maven tests specifically for hsweb-authorization/ module
• [ ] Add separate test step for reactive context propagation tests to validate ThreadLocal and reactor context handling
• [ ] Add code coverage reporting step (using codecov badge already present) focused on authorization package
• [ ] Include integration test step validating permission enforcement against sample R2DBC operations
• [ ] Set workflow to trigger on pull requests modifying files in hsweb-authorization/ or hsweb-core/

Complete DataAccessHandler and custom implementation documentation with code examples

The hsweb-authorization-api/custom-data-access.md file exists but is incomplete (based on partial file structure). DataAccessHandler is a complex extension point for custom data access rules, yet there's no working example showing how to implement OwnCreatedDataAccessConfig or custom DataAccessType implementations. Contributors need concrete examples showing how to extend ScopeDataAccessConfig or create dimension-based filters.

• [ ] Expand hsweb-authorization/hsweb-authorization-api/custom-data-access.md with complete working example implementing a custom DataAccessHandler for department-based filtering
• [ ] Add example code showing how to extend DefaultDataAccessType with a custom type (e.g., LOCATION_BASED_ACCESS)
• [ ] Document the reactive flow: how DimensionProvider chains with DataAccessHandler in reactive contexts
• [ ] Include troubleshooting section for common issues (null context in reactive chains, dimension resolution order)
• [ ] Add reference example in hsweb-authorization/README.md linking to the custom implementation guide

• Add integration tests for DataAccessHandler implementations with PostgreSQL and SQL Server in hsweb-authorization-api/src/test/ (currently only H2 and MySQL examples visible). Follow existing R2DBC test patterns in the test suite.
• Extend DimensionProvider documentation with concrete examples of custom dimension types (current README only covers default types). Add a sample custom dimension class to hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/ showing org-unit-based filtering.
• Write reactive cache integration tests for ReactiveAuthenticationHolder with Spring Data Redis (optional dependency is present but no tests visible). Use @TestcontainersRedis or similar for Redis lifecycle management without requiring manual setup.

• High · Use of FastJSON library — hsweb-authorization/hsweb-authorization-api/pom.xml - fastjson dependency. The project uses Alibaba FastJSON (com.alibaba:fastjson) which has a history of critical deserialization vulnerabilities. FastJSON versions before 1.2.83 are vulnerable to remote code execution via malicious JSON payloads. Fix: Update to FastJSON 2.x (fastjson2) or replace with Jackson/Gson which have better security track records. If FastJSON must be used, ensure version is at least 1.2.83 and disable dangerous features like autotype parsing.
• High · Incomplete dependency declaration in pom.xml — hsweb-authorization/hsweb-authorization-api/pom.xml - line ending at 'optional>true<'. The pom.xml file appears truncated/incomplete with an unclosed dependency tag for 'io.micrometer:context-propagation'. This indicates potential build configuration issues and inability to verify all dependencies for vulnerabilities. Fix: Complete and validate the entire pom.xml file. Ensure all dependencies are properly declared and closed. Run 'mvn dependency:check' to identify outdated or vulnerable dependencies.
• Medium · Reactive Authentication Context Exposure — hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/context/. The presence of 'ReactiveAuthenticationHolder' and 'ThreadLocalReactiveAuthenticationSupplier' suggests potential issues with authentication context management in reactive code. ThreadLocal usage in reactive pipelines can lead to context leakage or incorrect authentication state across different reactive threads. Fix: Verify that reactive context propagation uses proper context-propagation libraries (io.micrometer:context-propagation) instead of ThreadLocal. Use Project Reactor's Context or similar mechanisms for reactive context management.
• Medium · Authorization Annotation Processing — hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/. Multiple authorization annotations (@Authorize, @DataAccess, @RequiresRoles, @TwoFactor) suggest AOP-based security. Without visible implementation details, there's a risk of annotation bypass, improper method interception, or order-of-execution issues in security checks. Fix: Review AOP interceptor implementation for: (1) Proper exception handling during authorization, (2) Correct advice order (@Order annotation), (3) Protection against proxy bypass techniques, (4) Comprehensive coverage of all protected methods.
• Medium · Data Access Control Complexity — hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/. The framework implements field-level and dimension-based data access control (FieldFilterDataAccessConfig, DimensionDataAccess). Complex authorization logic increases risk of logic flaws, privilege escalation, or data leakage through misconfiguration. Fix: Ensure comprehensive unit and integration tests for all data access configurations. Implement security review process for custom DataAccessHandler implementations. Add logging/auditing for data access decisions.
• Medium · Missing SecurityContext Initialization — hsweb-authorization/hsweb-authorization-api/. No visible evidence of Spring Security SecurityContext configuration in authorization module. This could lead to unprotected endpoints if integration is incomplete. Fix: Verify proper Spring Security integration. Ensure SecurityContextPersistenceFilter or equivalent is configured. Implement @EnableGlobalMethodSecurity or @EnableReactiveMethodSecurity as appropriate.
• Low · Optional Dependencies Without Version Management — hsweb-authorization/hsweb-authorization-api/pom.xml. Several dependencies marked as optional (spring-boot-starter, jakarta.servlet-api, spring-data-redis) without explicit version constraints in this module, relying on parent POM version management. Fix: Ensure parent POM (hsweb-authorization) maintains explicit version pins for all optional dependencies. Document version requirements clearly.
• Low · Test Scope Dependency — undefined. lettuce-core is included with test scope only, but spring-data-redis is optional runtime. This could cause runtime issues if Redis Fix: undefined

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.