Source of truth as of: 30 July 2026

The Library Management System uses session-based authentication with Spring Security 6.5, BCrypt password hashing, CSRF protection via a SPA-aware token handler, and URL-pattern-based role authorization. The frontend and API share the same origin (Spring Boot serves both), so no CORS configuration is needed.

See ARCHITECTURE.md for system context and API.md for endpoint reference.

sequenceDiagram
    participant Browser
    participant AuthController
    participant AuthService
    participant AuthManager
    participant Session

    Browser->>AuthController: POST /api/auth/login {username, password}
    AuthController->>AuthService: login(credentials)
    AuthService->>AuthManager: authenticate(UsernamePasswordAuthenticationToken)
    AuthManager-->>AuthService: Authentication
    AuthService->>Session: SecurityContextHolder → HTTP session
    AuthService-->>Browser: AuthenticatedUserResponse (accountId, username, role, displayName)
    Note right of Browser: JSESSIONID cookie set

1. POST /api/auth/logout with X-XSRF-TOKEN header.
2. AuthService.logout() invalidates the HTTP session and clears SecurityContextHolder.
3. Frontend nulls currentUser and redirects to login.

The system defines three roles via the Role enum:

Authorization is enforced at the URL-pattern level in SecurityConfig.security(). Rules are evaluated in declaration order:

// Public endpoints
.requestMatchers("/login.html", "/styles.css",
    "/css/**", "/js/**", "/components/**", "/assets/**",
    "/api/auth/login", "/api/auth/csrf", "/login.html", "/register.html").permitAll()

// Authenticated endpoints
.requestMatchers("/api/auth/logout", "/api/auth/me", "/api/profile").authenticated()

// Student dashboard — STUDENT, ADMIN, LIBRARIAN
.requestMatchers("/api/student/**").hasAnyRole("ADMIN", "LIBRARIAN", "STUDENT")

// Books, magazines, newspapers GET — any authenticated user (including STUDENT)
.requestMatchers(HttpMethod.GET, "/api/books/**", "/api/magazines/**", "/api/newspapers/**").authenticated()

// Librarians — ADMIN only
.requestMatchers("/api/librarians/**").hasRole("ADMIN")

// Analytics, audit, reports — ADMIN and LIBRARIAN
.requestMatchers("/api/analytics/**", "/api/audit/**", "/api/reports/**").hasAnyRole("ADMIN", "LIBRARIAN")

// Books mutate, students, borrow records mutate, dashboard — ADMIN and LIBRARIAN
.requestMatchers("/api/books/**", "/api/students/**", "/api/borrow-records/**", "/api/dashboard").hasAnyRole("ADMIN", "LIBRARIAN")

// Librarian dashboard — ADMIN and LIBRARIAN
.requestMatchers("/api/librarian/dashboard").hasAnyRole("ADMIN", "LIBRARIAN")

// Everything else (including Swagger UI) — authenticated
.anyRequest().authenticated()

Rule ordering note: The rule requestMatchers(HttpMethod.GET, "/api/books/**").authenticated() appears before requestMatchers("/api/books/**").hasAnyRole("ADMIN","LIBRARIAN"). This means GET requests from any authenticated user (including STUDENT) are permitted, while POST/PUT/DELETE require ADMIN or LIBRARIAN.

No @PreAuthorize, @Secured, or @RolesAllowed annotations are used anywhere in the codebase. Authorization is purely URL-pattern-based.

sequenceDiagram
    participant Browser
    participant CSRFEndpoint as GET /api/auth/csrf
    participant API as POST /api/auth/login

    Browser->>CSRFEndpoint: GET /api/auth/csrf
    CSRFEndpoint-->>Browser: XSRF-TOKEN cookie (readable by JS)
    Browser->>API: POST /api/auth/login + X-XSRF-TOKEN header
    API->>API: SpaCsrfTokenRequestHandler validates raw token
    API-->>Browser: 200 OK + session cookie

Session cookies are automatically included by the browser on same-origin requests. Without CSRF protection, a malicious site could submit state-changing requests (borrow, delete, create) on behalf of an authenticated user. The SpaCsrfTokenRequestHandler provides SPA-compatible CSRF protection without disabling it.

Both return the standard ApiErrorResponse JSON shape — no HTML error pages, no stack traces.

• Passwords are processed using BCryptPasswordEncoder.
• A new password is encoded before the account is saved.
• Login uses BCrypt's verification method.
• The database stores the resulting hash only.
• server.error.include-message=never prevents Spring Boot from leaking error details.

A CommandLineRunner in AdminSeeder creates an admin account with ROLE_ADMIN if no admin username exists. Reads lms.admin.username and lms.admin.password from configuration. Throws IllegalStateException if the password is null or blank.

Warning: The default password is a development seed. Change it before any non-local deployment.

# Prevent Spring Boot from leaking error details
server.error.include-message=never

# Null fields omitted from JSON responses
spring.jackson.default-property-inclusion=non_null