Tasks: Simple HTTP Auth

Feature: Simple HTTP Auth Branch: 005-simple-http-auth Date: October 13, 2025

Phase 1: Setup Tasks (Project Initialization)

T001: Create backend/.env file for passphrase configuration.
T002: Update docker-compose.yaml to include AUTH_PASSPHRASE environment variable for the backend service.

Phase 2: Foundational Tasks (Blocking Prerequisites for all User Stories)

T003: Implement a logging utility in the backend to write authentication attempts to a text file. (FR-008)
T004: Implement a service in the backend to read AUTH_PASSPHRASE from .env and handle its absence/invalidity (default to no authentication). (FR-006, Edge Case)
T005: Implement a session management mechanism in the backend to preserve user access during a browser session. (FR-005, SC-003)

Phase 3: User Story 1 - Accessing the SPA (Priority: P1)

Goal: A user attempts to access the Single Page Application (SPA). They are prompted to enter a passphrase. Upon entering the correct passphrase, they gain access to the SPA. This access is maintained throughout their session. Independent Test: Can be fully tested by navigating to the SPA, entering a valid passphrase, and verifying access to content.

T006 [US1]: Implement the /api/auth/passphrase POST endpoint in backend/src/api/ to validate the entered passphrase. (FR-001, FR-002, FR-003, FR-007, contracts/openapi.yaml)
T007 [US1]: Integrate the session management mechanism with the /api/auth/passphrase endpoint to issue a session token upon successful authentication. (FR-005)
T008 [US1]: Implement a middleware or guard in the backend to protect SPA routes, redirecting unauthenticated users to the passphrase entry page.
T009 [US1][P]: Create a passphrase input component in frontend/src/components/ to capture user input. (FR-001)
T010 [US1][P]: Implement a service in frontend/src/services/ to send the passphrase to the backend and handle the session token.
T011 [US1][P]: Create a login page in frontend/src/pages/ that uses the passphrase input component and handles authentication flow. (FR-001)
T012 [US1][P]: Implement routing in the frontend to redirect to the login page if unauthenticated and to the SPA content upon successful authentication.
T013 [US1]: Write unit/integration tests for the /api/auth/passphrase endpoint (success case). (SC-001)
T014 [US1]: Write end-to-end tests for successful SPA access after passphrase entry.

Phase 4: User Story 2 - Invalid Passphrase (Priority: P2)

Goal: A user attempts to access the SPA but enters an incorrect passphrase. They should be denied access and prompted to try again. Independent Test: Can be tested by entering an incorrect passphrase and verifying that access is denied.

T015 [US2]: Enhance the /api/auth/passphrase POST endpoint to return a 401 status for invalid passphrases. (FR-004, contracts/openapi.yaml)
T016 [US2][P]: Update the frontend login page to display an error message for invalid passphrase attempts. (FR-004)
T017 [US2]: Write unit/integration tests for the /api/auth/passphrase endpoint (failure case). (SC-002)
T018 [US2]: Write end-to-end tests for denied SPA access after incorrect passphrase entry.

Final Phase: Polish & Cross-Cutting Concerns

T019: Review and refine logging messages for clarity and completeness.
T020: Ensure .env file handling is robust and secure (e.g., not committed to VCS).
T021: Update README.md with setup and usage instructions for the authentication feature.
T022: Verify that the passphrase can be updated in the .env file and takes effect upon application restart. (SC-004)

Dependencies

Phase 2 depends on Phase 1.
Phase 3 depends on Phase 2.
Phase 4 depends on Phase 3.
Final Phase depends on Phase 4.

Parallel Execution Examples

Within Phase 3 (US1), T009, T010, T011, T012 can be developed in parallel with T006, T007, T008.
Within Phase 4 (US2), T015 and T016 can be developed in parallel.

Implementation Strategy

This feature will be implemented incrementally, delivering User Story 1 as a Minimum Viable Product (MVP) first, followed by User Story 2. Each user story is designed to be independently testable and deployable.

4.2 KiB Raw Blame History