Architecture

Module Structure

Dependency Rules

security-core              -> (no project deps)
security-vaadin            -> security-core
security-rest              -> security-core
security-standalone        -> security-core
demo-rest-shared           -> (no project deps; transport-only)
demo-vaadin                -> security-core, security-vaadin
demo-rest                  -> security-core, security-rest, demo-rest-shared
demo-vaadin-rest-client    -> security-core, security-vaadin, demo-rest-shared
                              (test scope only: demo-rest)
demo-standalone            -> security-core, security-standalone

security-core has no Vaadin, Servlet, or REST-framework dependencies. None of the three adapters (security-vaadin, security-rest, security-standalone) depend on each other — they all sit on top of security-core and can be used independently.

Package layout

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

com.svenruppert.vaadin.security
├── action/         — ActionAuthorizationService, ActionPermission
├── audit/          — SecurityAuditService + 16 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.vaadin.security.standalone   — Secured, StandaloneLoginFlow,
                                                ThreadLocalSubjectStore   (3 classes)
com.svenruppert.vaadin.security.logout.vaadin — VaadinLogoutService + Gateway
com.svenruppert.vaadin.security.session.vaadin— SessionLifetimeListener
com.svenruppert.vaadin.security.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:

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

In addition, two 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)

SecurityServiceResolver — one resolver for all SPIs

SecurityAuditService audit    = SecurityServiceResolver.auditService();
LogoutService        logout   = SecurityServiceResolver.logoutService();
LoginAttemptPolicy   bruteFor = SecurityServiceResolver.loginAttemptPolicy();
SessionPolicy<MyUser> session = SecurityServiceResolver.sessionPolicy();
ActionAuthorizationService<MyUser> action = SecurityServiceResolver.actionService();
PasswordHasher       hasher   = SecurityServiceResolver.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

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

Generic annotations (in security-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

Library modules carry the production guarantee:

¹ security-core was measured at 86 % in 00.51; the percentage dropped in 00.60 because the audit pipeline, LoginAttemptPolicy, SessionPolicy, ActionAuthorizationService and the refactored LogoutService are now inside the scope. The absolute killed-mutant count rose from 254 → 497.

Demo modules are exercised end-to-end through the library tests; their direct mutation numbers are reported for transparency:

Test strength = killed mutations / covered mutations. A 91% test strength means: of every 100 mutations the tests reached, 91 were detected. Line coverage tells you whether code runs; test strength tells you whether the assertions catch bugs.

Reports are generated with Pitest via mvn -P mutation verify.

Stable vs. Experimental API

Stable: role-based access, REST adapter contracts, SecuritySubject, AccessContext, AuthorizationDecision, scanner, LogoutService, LoginAttemptPolicy, SessionPolicy, SecurityAuditService, ActionAuthorizationService, PasswordHasher, SecurityServiceResolver.

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.