Quick Start

Build

Requirements: Maven 3.9.9+, Java 26+.

mvn clean install

mvn install is required at least once because the demos depend on each other through the local ~/.m2 repository (demo-vaadin-rest-client depends on demo-rest for tests, and demo-rest-shared is consumed by both REST-side modules).

Pick the right demo

Both Vaadin demos ship with a role + user admin UI (/admin/roles, including a new-user dialog with ConfirmDialog-protected deletes), a red lockout notification on repeated failed logins, and an audit-log grid (/audit) backed by RingBufferAuditSink.

demo-vaadin — Standalone Vaadin demo

cd demo-vaadin && mvn jetty:run
# Browser: http://localhost:8080/

First run shows the bootstrap setup (the demo prints a token to the console). After setup, log in as the chosen admin. Demo users user/user and demo/demo are pre-populated; admin is created via the bootstrap flow. Visit /admin/roles (admin only) for the role + user administration UI, /audit for the audit log.

demo-rest — REST server + CLI

# Terminal 1 — JDK-only HTTP server on http://localhost:8080
mvn -pl :demo-rest exec:java
# Prints a bootstrap token to the console (TRANSIENT_CONSOLE mode).

# Terminal 2 — interactive CLI
mvn -pl :demo-rest exec:java \
    -Dexec.mainClass=com.svenruppert.vaadin.security.demo.rest.cli.DemoRestCli
# Use `init-admin` to create the first admin via the bootstrap token.
# Then `login admin <new-password>` and play with `operations` / `call …`.

Demo users: editor/editor, viewer/viewer. admin is created via the bootstrap flow; with -Dsecurity.bootstrap.mode=DISABLED the default admin/admin is pre-populated instead.

REST endpoints relevant to the new subsystems:

• GET /api/audit — read recent audit events (admin only)
• GET /api/admin/users — list users (admin only)
• POST /api/admin/users — create user (admin only, UserCreated audit)
• PUT /api/admin/users/{username} — set role (admin only)
• DELETE/api/admin/users/{username} — delete user (admin only, UserDeleted audit)

Repeated failed logins are throttled by LoginAttemptPolicy. The server responds with 429 Too Many Requests + Retry-After once the configured limit is reached.

demo-vaadin-rest-client — Vaadin UI + REST backend

# Terminal 1 — backend (same as the REST demo above)
mvn -pl :demo-rest exec:java
# Prints a bootstrap token to the console.

# Terminal 2 — Vaadin UI
mvn -pl :demo-vaadin-rest-client jetty:run
# Browser: http://localhost:9090/

Browser opens /setup (because the backend has no admin yet). Paste the token from the backend console, choose a username and password, submit — the Vaadin UI calls POST /api/bootstrap/admin against the backend, no in-JVM auth. Then log in. The UI never speaks HTTP directly: only the encapsulated DemoBackendClient does. The /admin/roles UI is backend-driven through GET/POST/PUT/DELETE /api/admin/users.

demo-standalone — Library CLI (Core Java)

mvn -pl :demo-standalone exec:java \
    -Dexec.mainClass=com.svenruppert.vaadin.security.demo.standalone.DemoApp

Plain interactive shell — no Vaadin, no REST — against an in-memory book library. Seeded users admin/admin, librarian/librarian, alice/alice. Same @RequiresPermission / @RequiresRole annotations, enforced by a dynamic-proxy via Secured.wrap(LibraryService.class, new InMemoryLibraryService()). Brute-force throttling and audit events work identically — same SPI services. See Standalone Integration for the API.

Tests

# Whole reactor — ~570 tests across all modules
mvn test

# Single module
mvn -pl :security-core -am test
mvn -pl :security-standalone -am test
mvn -pl :demo-rest -am test
mvn -pl :demo-vaadin-rest-client -am test

# Mutation testing (Pitest) — library modules carry 79–98% mutation,
# 91–98% test strength. See Architecture → Quality.
mvn -P mutation verify -pl :security-core -am

Add the dependency

Current release: 00.60.00.

For a Vaadin application:

<dependency>
  <groupId>com.svenruppert</groupId>
  <artifactId>security-vaadin</artifactId>
  <version>00.60.00</version>
</dependency>

For a REST handler / servlet application:

<dependency>
  <groupId>com.svenruppert</groupId>
  <artifactId>security-rest</artifactId>
  <version>00.60.00</version>
</dependency>

For a plain Core-Java application (CLI, desktop, batch):

<dependency>
  <groupId>com.svenruppert</groupId>
  <artifactId>security-standalone</artifactId>
  <version>00.60.00</version>
</dependency>

security-core is pulled in transitively by any of the three adapters.