Add simple auth

specs/003-basic-login/spec.md

@@ -0,0 +1,103 @@
+# Feature Specification: Basic Login Protection
+
+**Feature Branch**: `003-basic-login`  
+**Created**: 2026-04-06  
+**Status**: Draft  
+**Input**: User description: "Add simple and basic login (username and password) to protect the app."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Authenticate to Access the App (Priority: P1)
+
+A user opens the application and is presented with a login screen. They enter their username and password and, upon successful authentication, gain access to the full application. Without logging in, no part of the application is accessible.
+
+**Why this priority**: This is the core feature — all other functionality depends on this gate being in place.
+
+**Independent Test**: Can be fully tested by navigating to any page without credentials (should redirect to login), then logging in with valid credentials (should grant access) — this alone delivers the full MVP value.
+
+**Acceptance Scenarios**:
+
+1. **Given** an unauthenticated user, **When** they navigate to any page of the app, **Then** they are redirected to the login screen
+2. **Given** the login screen, **When** the user enters valid credentials and submits, **Then** they are redirected to the application home/dashboard
+3. **Given** the login screen, **When** the user enters invalid credentials and submits, **Then** an error message is displayed and they remain on the login screen
+4. **Given** an authenticated user, **When** they navigate directly to a protected page, **Then** they can access it without re-authenticating
+
+---
+
+### User Story 2 - Log Out of the App (Priority: P2)
+
+An authenticated user can explicitly log out of the application, terminating their session. After logging out, they are redirected to the login screen and must re-authenticate to access the app.
+
+**Why this priority**: Logout is essential for security — especially on shared machines — but the app is still protected even without explicit logout (session expires).
+
+**Independent Test**: Can be fully tested by logging in, clicking logout, and confirming that the protected pages are no longer accessible.
+
+**Acceptance Scenarios**:
+
+1. **Given** an authenticated user, **When** they click the logout button, **Then** their session is terminated and they are redirected to the login screen
+2. **Given** a user who has logged out, **When** they navigate to a protected page, **Then** they are redirected to the login screen
+
+---
+
+### User Story 3 - Session Persistence Across Browser Refresh (Priority: P3)
+
+An authenticated user refreshes the page or reopens the browser tab and remains logged in without having to re-enter credentials, as long as their session has not expired.
+
+**Why this priority**: Improves usability — users should not be forced to log in after every page refresh during normal use.
+
+**Independent Test**: Can be tested by logging in, refreshing the page, and confirming the user is still authenticated.
+
+**Acceptance Scenarios**:
+
+1. **Given** an authenticated user, **When** they refresh the browser, **Then** they remain logged in and on the same page
+2. **Given** a session that has expired, **When** the user tries to access a protected page, **Then** they are redirected to the login screen
+
+---
+
+### Edge Cases
+
+- What happens when the login form is submitted with empty username or password fields?
+- How does the system handle a user whose credentials are removed/disabled while they have an active session?
+- What happens if the user attempts to access the login page while already authenticated?
+- How does the system behave if the session store becomes unavailable?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST display a login screen (username + password fields and submit button) to unauthenticated users
+- **FR-002**: System MUST redirect unauthenticated users attempting to access any protected page to the login screen
+- **FR-003**: System MUST validate submitted credentials against configured or stored credentials
+- **FR-004**: System MUST create an authenticated session upon successful login
+- **FR-005**: System MUST display a clear, user-friendly error message when credentials are incorrect (without revealing which field is wrong)
+- **FR-006**: System MUST provide a logout action that terminates the active session
+- **FR-007**: System MUST redirect users to the login screen after logout
+- **FR-008**: System MUST prevent login form submission when username or password is empty
+- **FR-009**: System MUST automatically expire sessions after a reasonable inactivity period
+- **FR-010**: System MUST redirect users to the login page if their session has expired
+- **FR-011**: Credentials MUST be stored securely (passwords hashed, not stored in plaintext)
+- **FR-012**: System MUST allow at least one user account to be configured via environment variables or a configuration file; credential changes take effect on restart
+
+### Key Entities
+
+- **User Account**: Represents a person who can authenticate; has a username (unique identifier) and a hashed password
+- **Session**: Represents an active authenticated context; linked to a user account, has an expiry time
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Unauthenticated users cannot access any protected page — 100% of protected routes redirect to login
+- **SC-002**: Users can complete the login flow (enter credentials, submit, land on the app) in under 30 seconds under normal conditions
+- **SC-003**: Invalid login attempts display an error within 3 seconds and do not reveal which field was wrong
+- **SC-004**: Authenticated sessions persist across page refreshes for the configured session duration without requiring re-authentication
+- **SC-005**: Logout terminates the session immediately — any subsequent request to a protected page results in a redirect to login
+
+## Assumptions
+
+- The target users are a small, known group — there is no public self-registration for new accounts
+- A single set of credentials (or a small number of pre-configured accounts) is sufficient for this initial version
+- Mobile/responsive design for the login form is expected but full mobile optimization is not the focus of this feature
+- The app currently has no authentication layer, so this will be added globally
+- Session duration defaults to a reasonable inactivity timeout (e.g., 30 minutes of inactivity), configurable if needed
+- A "remember me" / persistent login cookie is out of scope for this initial implementation