Architecture

Module Structure

The reactor has 44 modules as of 00.79.41 — the 13 from 00.70, the two opt-in credential modules from 00.71 (jSentinel-crypto-bc, jSentinel-credentials-hibp), seven developer-experience modules from 00.72 (the jSentinel-dx-* facades, jSentinel-autoservice-*, and jSentinel-vaadin-starter — see Developer Experience), three token-propagation modules from 00.74 (jSentinel-propagation, jSentinel-propagation-processor, jSentinel-propagation-oidc — see 00.74.00 release notes), and four Security-Event-Bus modules from 00.75 (jSentinel-events, jSentinel-events-rest, jSentinel-events-testkit, jSentinel-events-persistence-eclipsestore — see 00.75.00 release notes), and the opt-in jSentinel-jwt JWT-validation module from 00.76 (Nimbus JOSE+JWT — see 00.76.00 release notes), three OAuth2 Relying-Party modules from 00.77 (jSentinel-oauth2, jSentinel-oauth2-vaadin, jSentinel-oauth2-rest — see 00.77.00 release notes), three OIDC Relying-Party modules from 00.78 (jSentinel-identity-oidc + the Vaadin / REST adapters — see 00.78.00 release notes), the six IdP vendor-profile modules plus a jSentinel-test-oidc harness from 00.79 (see 00.79.00 release notes), and the jSentinel-dpop sender-constrained-token module from 00.79.10 (DPoP / RFC 9449 — see 00.79.10 release notes). The table below lists the ten core/library modules; the opt-in credential and DX modules are covered on their own pages.

Dependency Rules

jSentinel-core                       -> (no project deps; no third-party runtime deps)
jSentinel-vaadin                     -> jSentinel-core
jSentinel-rest                       -> jSentinel-core
jSentinel-standalone                 -> jSentinel-core
jSentinel-test                       -> jSentinel-core (test fixtures)
jSentinel-processor                  -> proxybuilder (compile-time only)
jSentinel-persistence-testkit        -> jSentinel-core (test scope)
jSentinel-persistence-eclipsestore   -> jSentinel-core, org.eclipse.store:storage-embedded
demo-*                              -> their adapter + jSentinel-core

jSentinel-core has no Vaadin, Servlet, REST-framework, or storage dependencies. None of the adapters depend on each other. Only jSentinel-persistence-eclipsestore carries a third-party storage dependency — the persistence SPIs themselves live dependency-free in the core. See Persistence.

Package layout

jSentinel-core packages are organised by concern, not by adapter:

com.svenruppert.jsentinel
├── action/         — ActionAuthorizationService, ActionPermission
├── audit/          — JSentinelAuditService + 27 sealed AuditEvent types + sinks
├── authentication/ — AuthenticationService, PasswordHasher, Pbkdf2PasswordHasher
├── authorization/  — annotations, evaluators, scanner, AuthorizationDecision
├── bootstrap/      — first-run admin setup
├── bruteforce/     — LoginAttemptPolicy + InMemory default
├── logout/         — LogoutService, SubjectSessionRegistry, LogoutListener
└── session/        — SessionPolicy + TimeoutSessionPolicy + SessionDecision

Each adapter adds one small wiring package on top:

com.svenruppert.jsentinel.standalone   — Secured, StandaloneLoginFlow,
                                                ThreadLocalSubjectStore   (3 classes)
com.svenruppert.jsentinel.logout.vaadin — VaadinLogoutService + Gateway
com.svenruppert.jsentinel.session.vaadin— SessionLifetimeListener
com.svenruppert.jsentinel.rest          — RestRequest/Response, filters,
                                                BearerTokenExtractor, …

Core rule

Library modules do not define project-specific permissions. Concrete roles, permissions, and business operations belong to consuming applications or demo modules.

Decision Model

The library uses two decision types:

Adapters map these to framework-specific behavior:

• jSentinel-vaadin → navigation: continue, reroute to login, or reroute to error.
• jSentinel-rest → HTTP status: 200/handler, 401, or 403.

In addition, several sealed decision hierarchies cover the production-hardening SPIs:

• LoginAttemptDecision = Allowed | LockedOut(Duration, int) — see Brute-Force Protection
• SessionDecision = Continue | RequireLogin | Invalidate(String reason, String loginRoute) — see Session Policy
• SessionPolicyDecision = Active | IdleTimeout | AbsoluteLifetimeExceeded — pure-query result of SessionPolicy.evaluate(SessionMetadata)
• PolicyDecision = Allowed | Denied | StepUpRequired — see Policy API
• JSentinelVersionStatus = Current(at) | Drifted(snapshot, current) and EnforcementOutcome = Continue | SessionStale(status) — see Multi-Tenancy
• RateLimitDecision = Allowed | Throttled(eventsInWindow, limit, window, retryAfter)

JSentinelServiceResolver — one resolver for all SPIs

JSentinelAuditService audit    = JSentinelServiceResolver.auditService();
LogoutService        logout   = JSentinelServiceResolver.logoutService();
LoginAttemptPolicy   bruteFor = JSentinelServiceResolver.loginAttemptPolicy();
SessionPolicy<MyUser> session = JSentinelServiceResolver.sessionPolicy();
ActionAuthorizationService<MyUser> action = JSentinelServiceResolver.actionService();
PasswordHasher       hasher   = JSentinelServiceResolver.passwordHasher();

Covers all eight SPIs (Authentication / Authorization / Audit / Action / LoginAttempt / Session / PasswordHasher / Logout). Strict accessors throw IllegalStateException for missing services; find…() returns Optional; set…(…) is a programmatic test seam.

Annotation-Driven Protection

JSentinelAnnotationScanner scans classes, methods, or any AnnotatedElement for restriction annotations meta-annotated with @JSentinelAnnotation. Both adapters use the same scanner.

Generic annotations (in jSentinel-core):

• @RequiresRole({"ROLE_ADMIN"}) → RequiresRoleEvaluator
• @RequiresPermission("document:delete") → RequiresPermissionEvaluator
• @ProtectedBy(...) → ProtectedByEvaluator

Project-specific annotations are encouraged for Vaadin views (e.g. @VisibleFor).

Three Authorization Patterns

The library distinguishes three intent-explicit call shapes:

// Pattern A — UX hint. Hide the button if the user can't use it.
if (PermissionGuard.hasPermission(user, "document:delete")) {
  layout.add(deleteButton);
}

// Pattern B — Server-side guard. Throws AccessDeniedException.
public void handleDelete() {
  PermissionGuard.requirePermission(user, "document:delete");
  documentService.delete(...);
}

// Pattern C — Audited action check. ActionAuthorizationService SPI.
public void handleDelete() {
  actionService.requireAllowed(user, ActionPermission.of("document:delete"));
  // ActionDenied audit event is emitted automatically on denial
  documentService.delete(...);
}

Hiding a button is never the security boundary — it’s a usability hint. The real check happens at the route, the handler, or the service call. The three patterns make the intent explicit at the call site so reviewers can tell the difference at a glance.

The two-tier setup in demo-vaadin-rest-client takes this further: PermissionGuard runs locally against the cached RemoteUser purely for UX, while the REST backend is the authoritative decision point. Clients never make local authorization decisions that the server hasn’t sanctioned.

Two-tier reference architecture

demo-vaadin-rest-client shows how to wire demo-rest as the authoritative backend behind a Vaadin UI:

• Vaadin code sees no REST calls. All views/ and security/ code is free of java.net.http.*, URI, HttpClient, JSON, or endpoint paths. The contract is DemoBackendClient; HttpDemoBackendClient is the only class with transport knowledge.
• REST server is authoritative. Mutating clicks call the server. 200 / 401 / 403 decides. Local PermissionGuard checks against the cached subject are UX hints only.
• Bootstrap goes over REST. The Vaadin /setup view calls POST /api/bootstrap/admin — no in-JVM admin logic.

demo-rest-shared provides the transport-level constants (DemoEndpoints) and a tiny JSON helper, shared between the REST server and any client. It has no project-specific code.

Reusable security building blocks

Quality — Mutation Coverage

The eight core/adapter and opt-in credential/DX modules below were last re-measured reactor-wide in 00.75.20 (a touched-module PIT pass — no module regressed against its prior baseline). The Report column links to each module’s full site-native breakdown; those reports were rendered from an earlier snapshot (pre-00.73 security-* module ids), so the headline number here is the current one while the per-mutator / survivor detail behind the link predates the rebrand.

Credential and developer-experience modules, same 00.75.20 pass:

The identity-federation stack (00.75–00.79), each at its own most recent measurement — see the linked release notes for full mutator context:

¹ jSentinel-vaadin dipped at 00.70 because the Phase-4c enforcer listener and the Phase-8 secured components (SecuredButton, SecuredRouterLink, SecuredMenuItem, SessionManagementView) landed. The gap was dominated by VoidMethodCallMutator survivors on component-construction setters with no testable side effect; absolute kill count rose from ~91 (00.60) to 242 (00.70) and has kept climbing since (249 as of 00.75.20).

² jSentinel-processor keeps a high line-coverage figure even where the mutation kill rate trails; the module has grown across releases as diagnostics/wrapper-index code landed. The report lists the historical survivors (mostly BooleanFalseReturnValsMutator guard-return flips) from its earlier snapshot.

jSentinel-test and jSentinel-persistence-testkit are test-support modules (fixtures / contracts); jSentinel-test reached 90 % (82 / 91) at its first PIT pass in 00.75.20 despite being fixture-heavy. jSentinel-autoservice-annotations is annotation-only (nothing to mutate). Demo modules are not PIT targets.

Reports are generated with Pitest via ./mvnw -P mutation verify.

Stable vs. Experimental API

Stable: role-based access, REST adapter contracts, JSentinelSubject, AccessContext, AuthorizationDecision, scanner, LogoutService, LoginAttemptPolicy, SessionPolicy, JSentinelAuditService, ActionAuthorizationService, PasswordHasher, JSentinelServiceResolver.

Experimental (marked with @ExperimentalSecurityApi): permission-based access types — PermissionBasedAccessEvaluator, PermissionName, HasPermissions, PermissionAuthorizationService. May change in incompatible ways in future releases.

Project-specific permissions live in applications

Library modules contain no concrete business permissions. Examples like document:read belong in demo-rest. Real applications define their own catalog (e.g. shortlink:create, audit:read) inside the consuming project.