ag/unisono
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simple HTTP Auth designed

Browse Source
This commit is contained in:
aodulov
2025-10-13 17:21:28 +03:00
parent 3e2c3bf9f3
commit 6e587e8aa7
9 changed files with 414 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
specs/005-simple-http-auth/checklists/requirements.md Normal file
View File

@@ -0,0 +1,34 @@
# Specification Quality Checklist: Simple HTTP Auth
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: October 13, 2025
**Feature**: [Link to spec.md]
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

44
specs/005-simple-http-auth/contracts/openapi.yaml Normal file
View File

@@ -0,0 +1,44 @@
openapi: 3.0.0
info:
title: Simple HTTP Auth API
version: 1.0.0
paths:
/api/auth/passphrase:
post:
summary: Authenticate with a passphrase
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
passphrase:
type: string
description: The passphrase to authenticate with.
required:
- passphrase
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Authentication successful"
sessionToken:
type: string
description: A token to maintain the session.
'401':
description: Invalid passphrase
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Invalid passphrase"

15
specs/005-simple-http-auth/data-model.md Normal file
View File

@@ -0,0 +1,15 @@
# Data Model: Simple HTTP Auth
## Entities
### Passphrase
- **Description**: A secret string used for authentication.
- **Attributes**:
- `value`: string (The actual passphrase, stored securely in .env)
### Session
- **Description**: Represents a period of continuous interaction between the user and the SPA, during which access is maintained.
- **Attributes**:
- `id`: string (Unique identifier for the session)
- `isAuthenticated`: boolean (Indicates if the session is authenticated)
- `expiry`: datetime (Timestamp when the session expires, if applicable)

86
specs/005-simple-http-auth/plan.md Normal file
View File

@@ -0,0 +1,86 @@
# Implementation Plan: Simple HTTP Auth
**Branch**: `005-simple-http-auth` | **Date**: October 13, 2025 | **Spec**: D:/Coding/unisono/specs/005-simple-http-auth/spec.md
**Input**: Feature specification from `/specs/005-simple-http-auth/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
## Summary
The feature provides a simple HTTP authentication mechanism for the Single Page Application (SPA). Users will be prompted to enter a passphrase, configured via an `.env` file, to gain access. Access will be preserved for the duration of the browser session. Failed attempts will not be rate-limited, and if the passphrase is missing or invalid in the `.env` file, the application will default to no authentication. Authentication attempts (success/failure) will be logged to a text file. User management, password reset, and multi-factor authentication are explicitly out-of-scope.
## Technical Context
**Language/Version**: Node.js (LTS), TypeScript 5.x
**Primary Dependencies**: React, Material-UI / MUI, WebSocket library, Express.js
**Storage**: Ephemeral server-side storage (in-memory/session store) for encrypted session data, `.env` file for passphrase.
**Testing**: `npm test`
**Target Platform**: Web (SPA)
**Project Type**: Web application (frontend + backend)
**Performance Goals**: No specific target for passphrase validation.
**Constraints**: Access preserved during browser session.
**Scale/Scope**: Simple HTTP authentication for a single SPA.
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
The plan aligns with the project constitution:
- **I. Conventions**: The plan adheres to existing project conventions by using Node.js/TypeScript, React, Material-UI, Express.js, and the established `backend/` and `frontend/` structure.
- **II. Libraries/Frameworks**: The plan explicitly lists primary dependencies (React, Material-UI / MUI, WebSocket library, Express.js) which are established in `GEMINI.md`.
- **III. Style & Structure**: The plan follows the existing `backend/` and `frontend/` structure and uses TypeScript, aligning with the project's established patterns.
- **IV. Idiomatic Changes**: The plan proposes changes that integrate naturally within the existing web application structure.
- **V. Comments**: This is a code-level principle, not directly applicable to the plan document itself, but the plan doesn't suggest violating it.
**Quality Gates Alignment:**
- **I. Proactiveness**: The tasks include unit/integration and end-to-end tests for both user stories.
- **II. Verification (Tests)**: The plan specifies `npm test` for testing, consistent with `GEMINI.md`.
- **III. Verification (Standards)**: The plan implies adherence to these standards by using TypeScript and `npm test`.
**Status**: All principles and quality gates are aligned.
## Project Structure
### Documentation (this feature)
```
specs/005-simple-http-auth/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
```
backend/
├── src/
│ ├── models/
│ ├── services/
│ ├── api/
│ └── ws/
└── tests/
frontend/
├── src/
│ ├── components/
│ ├── pages/
│ └── services/
└── tests/
```
**Structure Decision**: The project uses a web application structure with separate `backend/` and `frontend/` directories. The authentication logic will primarily reside in the `backend/` for validation and session management, and the `frontend/` will handle the passphrase input and display.
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

60
specs/005-simple-http-auth/quickstart.md Normal file
View File

@@ -0,0 +1,60 @@
# Quickstart: Simple HTTP Auth
This document provides a quick guide to setting up and testing the Simple HTTP Auth feature.
## Prerequisites
- Node.js (LTS)
- npm (usually comes with Node.js)
- Docker and Docker Compose (for running the full application stack)
## Setup
1. **Clone the repository**:
```bash
git clone <repository_url>
cd unisono
```
2. **Create a `.env` file in the `backend/` directory**:
```
cd backend
touch .env
```
Add the following line to `backend/.env`, replacing `YOUR_PASSPHRASE_HERE` with your desired secret passphrase:
```
AUTH_PASSPHRASE=YOUR_PASSPHRASE_HERE
```
*Note: If `AUTH_PASSPHRASE` is missing or empty, the application will start without authentication.*
3. **Build and run the application using Docker Compose**:
```bash
cd ../.. # Go back to the project root if you are in backend/
docker-compose up --build
```
This will build the frontend and backend services and start them.
## Usage
1. **Access the application**:
Open your web browser and navigate to `http://localhost:80`.
2. **Enter the passphrase**:
You will be presented with a screen prompting you to enter the passphrase. Enter the passphrase you configured in `backend/.env`.
3. **Access the SPA**:
Upon successful authentication, you will gain access to the Single Page Application. Your access will be preserved for the duration of your browser session.
## Testing
To run the tests for the backend and frontend:
```bash
# For backend tests
cd backend
npm test
# For frontend tests
cd frontend
npm test
```

87
specs/005-simple-http-auth/spec.md Normal file
View File

@@ -0,0 +1,87 @@
# Feature Specification: Simple HTTP Auth
**Feature Branch**: `005-simple-http-auth`
**Created**: October 13, 2025
**Status**: Draft
**Input**: User description: "Simple HTTP Auth. I create a passphrase in the .env file, and users must enter the passphrase (without username) to get access to the SPA. The access must be preserved during session."
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Accessing the SPA (Priority: P1)
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.
**Why this priority**: This is the core functionality of the feature, enabling controlled access to the application.
**Independent Test**: Can be fully tested by navigating to the SPA, entering a valid passphrase, and verifying access to content.
**Acceptance Scenarios**:
1. **Given** a user navigates to the SPA, **When** they are presented with a passphrase input, **Then** they can enter the correct passphrase.
2. **Given** a user has entered the correct passphrase, **When** they are redirected to the SPA content, **Then** their access is preserved across page navigations within the SPA.
3. **Given** a user has entered the correct passphrase, **When** they close and reopen the browser (within a reasonable session timeout), **Then** they are still granted access without re-entering the passphrase.
---
### User Story 2 - Invalid Passphrase (Priority: P2)
A user attempts to access the SPA but enters an incorrect passphrase. They should be denied access and prompted to try again.
**Why this priority**: Essential for security and user experience, preventing unauthorized access.
**Independent Test**: Can be tested by entering an incorrect passphrase and verifying that access is denied.
**Acceptance Scenarios**:
1. **Given** a user navigates to the SPA, **When** they enter an incorrect passphrase, **Then** they are shown an error message and remain on the passphrase entry screen.
---
### Edge Cases
- What happens when the passphrase in the `.env` file is missing or invalid? (Answer: Default to No Authentication - the application starts without requiring a passphrase.)
- How does the system handle multiple failed passphrase attempts? (Answer: No Rate Limiting - unlimited attempts allowed.)
What defines “session” for preserving access? (Answer: Browser Session - Access is preserved only as long as the browser tab/window remains open. Closing the browser or tab will require re-entry of the passphrase.)
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: The system MUST prompt users to enter a passphrase before granting access to the SPA.
- **FR-002**: The system MUST validate the entered passphrase against a configured passphrase.
- **FR-003**: The system MUST grant access to the SPA upon successful passphrase validation.
- **FR-004**: The system MUST deny access and provide feedback upon unsuccessful passphrase validation.
- **FR-005**: The system MUST preserve user access to the SPA for the duration of their session.
- **FR-006**: The passphrase MUST be configurable via an environment variable (e.g., `.env` file).
- **FR-007**: The authentication mechanism MUST NOT require a username.
- **FR-008**: The system MUST log both successful and failed authentication attempts to a text file, without sensitive data.
### Key Entities *(include if feature involves data)*
- **Passphrase**: A secret string used for authentication.
- **Session**: A period of continuous interaction between the user and the SPA, during which access is maintained.
## Out of Scope
- User management (creation, deletion, modification of users)
- Password reset or recovery functionality
- Multi-factor authentication (MFA)
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: 100% of users who enter the correct passphrase gain immediate access to the SPA.
- **SC-002**: 0% of users who enter an incorrect passphrase gain access to the SPA.
- **SC-003**: User access to the SPA is maintained for the entire browser session (or defined session duration) without re-authentication.
- **SC-004**: The passphrase can be updated in the `.env` file and takes effect upon application restart.
## Clarifications
### Session 2025-10-13
- Q: What is the desired rate limiting behavior for multiple failed passphrase attempts? → A: No Rate Limiting
- Q: How should the system behave if the passphrase is missing or invalid in the `.env` file? → A: Default to No Authentication
- Q: Are there any specific performance targets (e.g., latency) for the passphrase validation process? → A: No target
- Q: What kind of logging or monitoring should be in place for authentication attempts (success/failure)? → A: Standard Logging (both successful and failed attempts, without sensitive data, to a text file)
- Q: Are there any explicit functionalities that are out-of-scope for this simple HTTP authentication (e.g., user management, password reset, multi-factor authentication)? → A: All of the above (User management, password reset, and MFA are all out-of-scope).

64
specs/005-simple-http-auth/tasks.md Normal file
View File

@@ -0,0 +1,64 @@
# 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.