feat: update specs and add auth service test

.trellis/spec/backend/database-guidelines.md

@@ -7,28 +7,34 @@
 ## Overview
 
 MySQL is the project data layer. DAO classes perform CRUD and query operations
-against MySQL. Application source and schema files are not present yet, so table
-and class names here are illustrative conventions for future implementation.
+against MySQL. The initial scaffold schema exists at
+`src/main/resources/db/schema.sql`; future module tables should follow the same
+DDL style and DAO boundaries.
 
 ---
 
 ## Core Tables
 
 Use primary keys for every table and foreign keys for cross-entity integrity.
-Illustrative table names:
+
+Implemented scaffold tables:
+
+- `roles`: administrator, librarian, reader, and future role definitions.
+- `permissions`: permission definitions for protected actions.
+- `role_permissions`: role-to-permission mapping.
+- `users`: login accounts for administrator, librarian, and reader roles.
+- `system_logs`: key operation logs, backup events, and exception traces.
+
+Planned module tables:
 
 - `books`: book information, inventory count/status, category reference.
 - `book_categories`: category names and descriptions.
 - `readers`: reader profiles, borrowing eligibility, contact information.
 - `borrow_records`: book-reader borrowing, return, renew, and overdue data.
-- `administrators`: administrator/librarian login and profile data.
-- `roles`: administrator, librarian, reader, and future role definitions.
-- `permissions`: permission definitions for protected actions.
-- `role_permissions`: role-to-permission mapping.
 - `system_logs`: key operation logs, backup events, and exception traces.
 
-When schema files are introduced, record the actual path, DDL style, and exact
-table names here.
+Record new schema changes in `src/main/resources/db/schema.sql` and update this
+spec with exact table names, key columns, and DAO/service contracts.
 
 ---
 
@@ -42,8 +48,9 @@ table names here.
   inventory status.
 - Return entities or small query result objects to services, not HTML or
   servlet response objects.
-- Keep MySQL connection details in a shared configuration/helper once one
-  exists, for example `JdbcUtil` plus `db.properties`.
+- Keep MySQL connection details in `src/main/resources/db.properties` loaded by
+  `JdbcUtil`. The required keys are `db.driver`, `db.url`, `db.username`, and
+  `db.password`.
 
 ---
 
@@ -66,6 +73,9 @@ table names here.
 - `borrow_records.reader_id` should reference `readers`.
 - Administrator-role and role-permission mapping tables should use foreign keys
   to preserve authorization integrity.
+- `users.role_code` must reference `roles.code`.
+- `role_permissions.role_code` must reference `roles.code`.
+- `role_permissions.permission_code` must reference `permissions.code`.
 - Prefer explicit status columns/enums for inventory and borrowing states, then
   document the chosen values once code exists.
 
@@ -83,6 +93,12 @@ table names here.
 - DAO signature: `UserDao.findActiveByUsername(String username)`.
 - Service signature: `AuthService.authenticate(String username, String password)`.
 - Permission signature: `AuthService.hasPermission(AuthenticatedUser user, Permission permission)`.
+- Servlet route: `POST /login` with `username`, `password`, and optional
+  same-application `redirect`.
+- Protected routes: `/dashboard`, `/admin/home`, `/librarian/home`, and
+  `/reader/home`.
+- Session keys: `authenticatedUser`, `userRole`, and `userPermissions`.
+- DB config keys: `db.driver`, `db.url`, `db.username`, and `db.password`.
 - Login tables: `roles`, `permissions`, `role_permissions`, `users`, and
   `system_logs`.
 
@@ -93,9 +109,16 @@ table names here.
   `pbkdf2_sha256$iterations$saltBase64$hashBase64` format.
 - `users.role_code`: foreign key to `roles.code`; supported scaffold values
   are `administrator`, `librarian`, and `reader`.
+- `users.active`: only rows with `active = 1` can authenticate.
+- `roles.code`, `permissions.code`, and `role_permissions` must match the Java
+  `Role` and `Permission` enum codes exactly.
+- `db.properties` must be local configuration. Commit
+  `db.properties.example`, but do not commit real credentials.
 - Session state stores an `AuthenticatedUser` snapshot, role code, and
   permission-code set. It must not store raw passwords or DAO result objects
   with password hashes.
+- Login redirects must stay inside the current application context. Reject
+  values that do not start with a single `/` or that contain CR/LF characters.
 
 ### 4. Validation & Error Matrix
 
@@ -103,6 +126,7 @@ table names here.
   `Username and password are required.`
 - Unknown user, inactive user, or hash mismatch -> request returns to login JSP
   with `Invalid username or password.`
+- Unsafe or blank redirect -> ignore and route to `/dashboard` after success.
 - Missing `db.properties`, JDBC failure, or unsupported role code -> request
   returns a generic service-unavailable message and logs server-side details.
 - Authenticated user missing a required permission -> HTTP 403 and
@@ -123,6 +147,8 @@ table names here.
   unavailable.
 - Run `PermissionPolicyCheck` or equivalent assertions for administrator,
   librarian, and reader permissions.
+- Run `AuthServiceCheck` or equivalent assertions for required-field failures,
+  invalid credentials, success, permission checks, and DAO failure fallback.
 - When Maven/Tomcat dependencies are installed, run `mvn test` or
   `mvn clean package` to compile Servlet and JSP integration.
 
@@ -131,11 +157,12 @@ table names here.
 #### Wrong
 
 ```java
-// JSP or Servlet opens JDBC and checks passwords directly.
+// JSP, Servlet, or session code opens JDBC and stores password_hash.
 ```
 
 #### Correct
 
 ```text
 login.jsp -> LoginServlet -> AuthService -> UserDao -> users/roles tables
+session -> AuthenticatedUser snapshot + role/permission codes only
 ```