# Type Safety

> Display and validation contracts for JSP/Servlet frontend work.

---

## Overview

The frontend is JSP/CSS, not TypeScript. Type safety comes from Java entities,
Servlet parameter parsing, service contracts, DAO results, and careful JSP
rendering.

---

## JSP Data Contracts

- Servlets should set clearly named request attributes before forwarding to
  JSPs, such as `books`, `reader`, `borrowRecords`, `errors`, and `message`.
- JSP pages should render JavaBean/entity properties through JSP EL or JSTL
  rather than embedding business Java code.
- Keep attribute names stable between Servlet controllers and JSP pages; update
  both sides together when a contract changes.

---

## Scenario: Login JSP And Servlet Contract

### 1. Scope / Trigger

- Trigger: the initial login scaffold introduced a cross-layer JSP/Servlet
  contract for authentication screens and protected role pages.

### 2. Signatures

- Login form: `POST /login`.
- Request fields consumed by `LoginServlet`: `username`, `password`, and
  optional `redirect`.
- Presentation-only login controls may submit auxiliary fields such as
  `loginRole` and `rememberUsername`; these must not participate in
  authentication or authorization unless the Servlet/service contract is
  deliberately changed.
- Login JSP request attributes: `errorMessage`, `username`, and `redirect`.
- Dashboard/role JSP session attributes: `authenticatedUser`, `userRole`, and
  `userPermissions`.
- Role page request attributes: `areaName` and `areaSummary`.

### 3. Contracts

- `username` is trimmed in the Servlet before service authentication and may be
  echoed back only through JSP escaping.
- `password` is submitted to the Servlet and must never be written to a request
  attribute or session attribute.
- `redirect` must be a same-application path beginning with one `/`; invalid
  values are ignored.
- `loginRole` is only a login-intent hint in the JSP. The authenticated role is
  determined by the `users.role_code` row returned through `AuthService`, not by
  a client-side radio selection.
- Remember-me behavior may persist only the username in browser storage. It must
  never persist passwords, password hashes, redirects, permission state, or
  extend the server session.
- JSPs render data with JSP EL/JSTL, not scriptlet Java.
- JSPs may read safe session snapshots, but they must not call DAOs or inspect
  password hashes.

### 4. Validation & Error Matrix

- Missing `username` or `password` -> `errorMessage` displays
  `Username and password are required.`
- Invalid credentials -> `errorMessage` displays
  `Invalid username or password.`
- Login service unavailable -> `errorMessage` displays a generic unavailable
  message; details stay in server logs.
- Missing authenticated session on protected pages -> redirect to `/login` with
  a safe `redirect` value.
- Insufficient role permission -> render `/unauthorized`.

### 5. Good/Base/Bad Cases

- Good: failed login keeps the escaped username and never redisplays the
  password.
- Good: selecting a role radio option or checking remember-me does not change
  the server-side authentication decision.
- Base: dashboard reads `sessionScope.authenticatedUser.displayName` and
  `sessionScope.userRole` only for display/navigation.
- Bad: JSP, JavaScript, or Servlet code trusts `loginRole` to grant a role or
  stores the password in browser storage.

### 6. Tests Required

- Scan JSPs to confirm there are no scriptlets beyond directives.
- Scan JSP/static assets to confirm no SQL/JDBC access exists in presentation
  files.
- Run service-level auth checks for required fields, invalid credentials,
  success, DAO fallback, and permission checks.
- When login page scripts change, scan them to confirm only usernames can be
  stored client-side and `password` is never persisted.
- When Maven/Tomcat is available, run a Servlet/JSP compile or package check.

### 7. Wrong vs Correct

#### Wrong

```jsp
<%-- JSP checks request.getParameter("password") or runs SQL directly. --%>
<%-- JavaScript stores the password or LoginServlet trusts loginRole. --%>
```

#### Correct

```text
login.jsp displays attributes set by LoginServlet; AuthService and UserDao own
authentication and database access.
```

---

## Validation

- Parse and validate IDs, dates, enum/status values, and required strings in
  Servlet controllers before calling services.
- Services should re-check business rules such as borrowing eligibility,
  inventory availability, overdue status, and permission access.
- JSP pages should display validation messages but should not be the only place
  validation occurs.

---

## Forbidden Patterns

- Do not claim TypeScript, generated API types, React prop types, or Vue type
  conventions exist unless the stack changes.
- Do not use JSP scriptlets for business logic.
- Do not let JSP pages infer database schema details directly.
