@eddacraft/anvil-adapters 0.1.0

package/src/__tests__/fixtures/speckit-official/auth-feature/plan.md

@@ -0,0 +1,272 @@
+# Implementation Plan: User Authentication System
+
+**Branch**: `feature/001-auth-system` **Date**: 2025-01-15 **Spec**:
+[spec.md](./spec.md)
+
+## Summary
+
+Implement a secure JWT-based authentication system with user registration,
+login, password reset, and token refresh capabilities. The system will use
+Node.js/TypeScript with Express.js, PostgreSQL for data storage, and Redis for
+session management.
+
+## Technical Context
+
+- **Language/Version**: TypeScript 5.3, Node.js 20 LTS
+- **Dependencies**:
+  - express ^4.18.0
+  - jsonwebtoken ^9.0.2
+  - bcrypt ^5.1.1
+  - @types/node ^20.0.0
+  - zod ^3.22.0 (validation)
+  - pg ^8.11.0 (PostgreSQL client)
+  - redis ^4.6.0 (session management)
+  - nodemailer ^6.9.0 (email sending)
+- **Storage**: PostgreSQL 15+ for user data, Redis 7+ for session/rate limiting
+- **Testing**: Vitest for unit tests, Supertest for API tests
+- **Target**: REST API server, containerized with Docker
+- **Type**: Backend service
+- **Performance Goals**:
+  - Authentication endpoint response time < 200ms (p95)
+  - Support 100 concurrent requests
+- **Constraints**:
+  - Must comply with OWASP authentication guidelines
+  - Must support horizontal scaling
+- **Scale**: Expected initial load: 1000 daily active users, 10,000 total users
+
+## Constitution Check
+
+✅ **Modularity**: Authentication logic separated into controller, service, and
+repository layers ✅ **Testability**: Each component has clear interfaces for
+mocking ✅ **Security**: Follows OWASP Top 10 guidelines, password hashing, JWT
+validation ✅ **Performance**: Redis caching for rate limiting, indexed database
+queries ✅ **Maintainability**: TypeScript for type safety, clear error handling
+✅ **Documentation**: OpenAPI/Swagger docs for all endpoints
+
+## Project Structure
+
+### Documentation
+
+```
+specs/
+└── 001-auth-system/
+    ├── spec.md (this file's sibling)
+    ├── plan.md (this file)
+    └── tasks.md (to be generated)
+```
+
+### Source Code Structure
+
+#### Option 1: Modular Backend Service (Selected)
+
+```
+src/
+├── modules/
+│   └── auth/
+│       ├── auth.controller.ts      # HTTP endpoints
+│       ├── auth.service.ts         # Business logic
+│       ├── auth.repository.ts      # Data access
+│       ├── auth.validation.ts      # Zod schemas
+│       ├── auth.middleware.ts      # JWT verification
+│       └── __tests__/
+│           ├── auth.controller.test.ts
+│           ├── auth.service.test.ts
+│           └── auth.integration.test.ts
+├── entities/
+│   ├── user.entity.ts
+│   ├── auth-token.entity.ts
+│   ├── audit-log.entity.ts
+│   └── password-reset.entity.ts
+├── database/
+│   ├── migrations/
+│   │   ├── 001_create_users_table.sql
+│   │   ├── 002_create_auth_tokens_table.sql
+│   │   ├── 003_create_audit_logs_table.sql
+│   │   └── 004_create_password_resets_table.sql
+│   └── connection.ts
+├── utils/
+│   ├── jwt.util.ts
+│   ├── hash.util.ts
+│   ├── email.util.ts
+│   └── rate-limit.util.ts
+├── config/
+│   ├── env.ts
+│   └── constants.ts
+└── app.ts
+```
+
+## Implementation Details
+
+### API Endpoints
+
+**POST /api/auth/register**
+
+- Request: `{ email: string, password: string }`
+- Response: `{ user: { id, email }, token: string }`
+- Errors: 400 (validation), 409 (email exists)
+
+**POST /api/auth/login**
+
+- Request: `{ email: string, password: string }`
+- Response: `{ user: { id, email }, token: string, refreshToken: string }`
+- Errors: 401 (invalid credentials), 423 (account locked)
+
+**POST /api/auth/logout**
+
+- Request: Headers with JWT
+- Response: 204 No Content
+- Errors: 401 (unauthorized)
+
+**POST /api/auth/refresh**
+
+- Request: `{ refreshToken: string }`
+- Response: `{ token: string, refreshToken: string }`
+- Errors: 401 (invalid/expired token)
+
+**POST /api/auth/password-reset/request**
+
+- Request: `{ email: string }`
+- Response: 200 OK (always, for security)
+- Errors: 429 (rate limit)
+
+**POST /api/auth/password-reset/confirm**
+
+- Request: `{ token: string, newPassword: string }`
+- Response: 200 OK
+- Errors: 400 (invalid token), 410 (expired token)
+
+### Database Schema
+
+**users table**
+
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  hashed_password VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  last_login TIMESTAMP,
+  account_locked BOOLEAN DEFAULT FALSE,
+  failed_login_count INTEGER DEFAULT 0
+);
+CREATE INDEX idx_users_email ON users(email);
+```
+
+**auth_tokens table**
+
+```sql
+CREATE TABLE auth_tokens (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  refresh_token VARCHAR(255) UNIQUE NOT NULL,
+  expires_at TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+CREATE INDEX idx_auth_tokens_user_id ON auth_tokens(user_id);
+CREATE INDEX idx_auth_tokens_refresh_token ON auth_tokens(refresh_token);
+```
+
+**audit_logs table**
+
+```sql
+CREATE TABLE audit_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+  event_type VARCHAR(50) NOT NULL,
+  ip_address VARCHAR(45),
+  user_agent TEXT,
+  success BOOLEAN NOT NULL,
+  error_message TEXT,
+  timestamp TIMESTAMP DEFAULT NOW()
+);
+CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id);
+CREATE INDEX idx_audit_logs_timestamp ON audit_logs(timestamp);
+```
+
+**password_resets table**
+
+```sql
+CREATE TABLE password_resets (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  token VARCHAR(255) UNIQUE NOT NULL,
+  expires_at TIMESTAMP NOT NULL,
+  used BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+CREATE INDEX idx_password_resets_token ON password_resets(token);
+```
+
+### Configuration
+
+**Environment Variables**
+
+```
+# Database
+DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
+REDIS_URL=redis://localhost:6379
+
+# JWT
+JWT_SECRET=<generate-secure-secret>
+JWT_EXPIRES_IN=15m
+REFRESH_TOKEN_EXPIRES_IN=7d
+
+# Email
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=auth@example.com
+SMTP_PASS=<smtp-password>
+
+# Security
+BCRYPT_ROUNDS=10
+MAX_LOGIN_ATTEMPTS=5
+RATE_LIMIT_WINDOW=60000
+RATE_LIMIT_MAX_REQUESTS=10
+PASSWORD_RESET_EXPIRY=24h
+```
+
+### Security Measures
+
+1. **Password Security**
+   - Bcrypt hashing with cost factor 10
+   - Minimum 8 characters, complexity requirements enforced
+   - Old passwords not stored (for comparison)
+
+2. **JWT Security**
+   - Signed with HS256 algorithm
+   - Short expiration (15 minutes)
+   - Refresh tokens stored in database, long-lived (7 days)
+   - Token blacklisting on logout via Redis
+
+3. **Rate Limiting**
+   - 10 requests per minute per IP on auth endpoints
+   - Implemented with Redis sliding window
+   - Account lockout after 5 failed login attempts
+
+4. **Audit Logging**
+   - All authentication events logged
+   - IP address and user agent captured
+   - 90-day retention policy
+
+## Complexity Tracking
+
+### Complex Design Decision: Token Refresh Strategy
+
+**Problem**: Need to balance security (short-lived tokens) with UX (not forcing
+frequent re-logins)
+
+**Solution**: Dual-token approach
+
+- Short-lived JWT (15 min) for API access
+- Long-lived refresh token (7 days) stored in database
+- Automatic token refresh before expiration
+- Refresh token rotation on each use
+
+**Justification**:
+
+- JWT is stateless and fast to validate
+- Refresh tokens are revocable (database-backed)
+- Compromise of JWT has limited window
+- UX stays smooth with automatic refresh
+- Meets security best practices (OWASP)

package/src/__tests__/fixtures/speckit-official/auth-feature/spec.md

@@ -0,0 +1,149 @@
+# Feature: User Authentication System
+
+**Branch**: `feature/001-auth-system` **Date**: 2025-01-15 **Status**: Draft
+
+## User Scenarios & Testing
+
+### P1: User Registration
+
+**As a** new user **I want to** create an account with email and password **So
+that** I can access the application securely
+
+**Acceptance Scenarios:**
+
+- User submits valid email and strong password
+- System validates email format and password strength
+- System creates user account and sends confirmation email
+- User receives success message
+
+**Edge Cases:**
+
+- Email already registered → Show error message
+- Weak password → Show password requirements
+- Invalid email format → Show format error
+- Network failure during registration → Show retry option
+
+### P1: User Login
+
+**As a** registered user **I want to** log in with my credentials **So that** I
+can access my personalized content
+
+**Acceptance Scenarios:**
+
+- User enters valid email and password
+- System validates credentials
+- System generates JWT token
+- User is redirected to dashboard
+
+**Edge Cases:**
+
+- Invalid credentials → Show error, increment failure count
+- Account locked (5 failed attempts) → Show account locked message
+- Expired session → Redirect to login with message
+- [NEEDS CLARIFICATION: Should we support "remember me" functionality?]
+
+### P2: Password Reset
+
+**As a** user who forgot their password **I want to** reset my password via
+email **So that** I can regain access to my account
+
+**Acceptance Scenarios:**
+
+- User requests password reset
+- System sends reset link to registered email
+- User clicks link and sets new password
+- User can log in with new password
+
+**Edge Cases:**
+
+- Email not found → Show generic message for security
+- Reset link expired (24 hours) → Show error, offer to resend
+- Weak new password → Show requirements
+- [NEEDS CLARIFICATION: Should old passwords be prevented from reuse?]
+
+### P3: Token Refresh
+
+**As a** logged-in user **I want** my session to be extended automatically **So
+that** I don't lose my work due to session expiration
+
+**Acceptance Scenarios:**
+
+- User's token expires during active session
+- System automatically requests refresh token
+- New JWT token is issued
+- User continues working without interruption
+
+**Edge Cases:**
+
+- Refresh token expired → Force re-login
+- Network failure during refresh → Queue and retry
+- [NEEDS CLARIFICATION: What is the token expiration policy?]
+
+## Requirements
+
+### Functional Requirements
+
+**FR-001**: System MUST validate email addresses using RFC 5322 standard
+**FR-002**: System MUST enforce password requirements: minimum 8 characters, one
+uppercase, one lowercase, one number, one special character **FR-003**: System
+MUST hash passwords using bcrypt with minimum cost factor of 10 **FR-004**:
+System MUST generate JWT tokens with configurable expiration time **FR-005**:
+System MUST lock accounts after 5 consecutive failed login attempts **FR-006**:
+System MUST send password reset emails with time-limited tokens (24 hours)
+**FR-007**: System MUST retain user authentication audit logs for 90 days
+**FR-008**: [NEEDS CLARIFICATION: Token expiration time - 15 minutes or 1 hour?]
+**FR-009**: [NEEDS CLARIFICATION: Should we support OAuth providers (Google,
+GitHub)?] **FR-010**: System MUST rate-limit authentication endpoints to prevent
+brute force attacks
+
+### Key Entities
+
+**User**
+
+- Represents: A person with access to the application
+- Key Attributes: id, email, hashed_password, created_at, last_login,
+  account_locked, failed_login_count
+- Relationships: Has many AuthTokens, has many AuditLogs
+
+**AuthToken**
+
+- Represents: A JWT token for authentication
+- Key Attributes: id, user_id, token, expires_at, refresh_token, created_at
+- Relationships: Belongs to User
+
+**AuditLog**
+
+- Represents: Record of authentication events
+- Key Attributes: id, user_id, event_type, ip_address, user_agent, success,
+  timestamp
+- Relationships: Belongs to User
+
+**PasswordReset**
+
+- Represents: Password reset request
+- Key Attributes: id, user_id, token, expires_at, used, created_at
+- Relationships: Belongs to User
+
+## Success Criteria
+
+### Quantitative Metrics
+
+- Authentication endpoint response time < 200ms (p95)
+- Successfully handle 100 concurrent login requests
+- Zero plain-text password storage
+- Account lockout triggers within 100ms of 5th failed attempt
+- Password reset emails delivered within 30 seconds
+
+### Qualitative Metrics
+
+- Users can complete registration in under 2 minutes
+- Login flow requires no more than 2 steps
+- Error messages are clear and actionable
+- Password reset process is intuitive and requires no support intervention
+
+### Security Metrics
+
+- All passwords stored with bcrypt cost factor >= 10
+- JWT tokens properly signed and validated
+- Rate limiting prevents more than 10 login attempts per minute per IP
+- Audit logs capture all authentication events

package/src/__tests__/fixtures/speckit-official/auth-feature/tasks.md

@@ -0,0 +1,169 @@
+# Tasks: User Authentication System
+
+**Branch**: `feature/001-auth-system` **Date**: 2025-01-15 **Spec**:
+[spec.md](./spec.md) | **Plan**: [plan.md](./plan.md)
+
+## Phase 1: Setup
+
+- [001] Create project structure and configuration files
+- [002] Set up database connection and migration system
+- [003] Configure TypeScript, ESLint, and testing environment
+- [004] Set up Redis connection for rate limiting and caching
+- [005] Configure environment variables and validation
+
+**Checkpoint**: Project builds successfully, database and Redis connections
+established
+
+## Phase 2: Foundational Infrastructure
+
+- [006] Create database migrations for all tables (users, auth_tokens,
+  audit_logs, password_resets)
+- [007] Implement User entity with TypeScript types
+- [008] Implement AuthToken entity with TypeScript types
+- [009] Implement AuditLog entity with TypeScript types
+- [010] Implement PasswordReset entity with TypeScript types
+- [011] Create utility functions for JWT generation and validation
+- [012] Create utility functions for password hashing and verification
+- [013] Create utility function for email sending
+- [014] Create rate limiting middleware using Redis
+- [015] Write tests for all utility functions
+
+**Checkpoint**: All foundational utilities tested and working
+
+## Phase 3: User Story - P1: User Registration
+
+- [016] Write failing tests for registration validation (email format, password
+  strength)
+- [017] Implement Zod schemas for registration request validation
+- [018] Write failing tests for AuthRepository.createUser()
+- [019] Implement AuthRepository.createUser() method
+- [020] Write failing tests for AuthService.register()
+- [021] Implement AuthService.register() with email uniqueness check
+- [022] Implement password hashing in registration flow
+- [023] Write failing tests for POST /api/auth/register endpoint
+- [024] Implement AuthController.register() endpoint
+- [025] Add audit logging for registration events
+- [026] Add email confirmation sending (placeholder for now)
+- [027] Run all registration tests and verify they pass
+
+**Checkpoint**: Users can successfully register with valid credentials, invalid
+attempts are rejected
+
+## Phase 4: User Story - P1: User Login
+
+- [028] Write failing tests for login validation
+- [029] Implement Zod schemas for login request validation
+- [030] Write failing tests for AuthRepository.findByEmail()
+- [031] Implement AuthRepository.findByEmail() method
+- [032] Write failing tests for AuthService.login() with credential validation
+- [033] Implement AuthService.login() with bcrypt password verification
+- [034] Implement JWT and refresh token generation on successful login
+- [035] Write failing tests for AuthRepository.saveRefreshToken()
+- [036] Implement AuthRepository.saveRefreshToken() method
+- [037] Implement failed login attempt tracking
+- [038] Implement account lockout after 5 failed attempts
+- [039] Write failing tests for POST /api/auth/login endpoint
+- [040] Implement AuthController.login() endpoint
+- [041] Add audit logging for login attempts (success and failure)
+- [042] Add rate limiting to login endpoint
+- [043] Run all login tests and verify they pass
+
+**Checkpoint**: Users can log in with valid credentials, receive JWT + refresh
+tokens, accounts lock after failures
+
+## Phase 5: User Story - P2: Password Reset
+
+- [044] [P] Write failing tests for password reset request validation
+- [045] [P] Implement Zod schema for password reset request
+- [046] [P] Write failing tests for AuthRepository.createPasswordReset()
+- [047] [P] Implement AuthRepository.createPasswordReset() method
+- [048] [P] Write failing tests for AuthService.requestPasswordReset()
+- [049] [P] Implement AuthService.requestPasswordReset() with token generation
+- [050] [P] Implement email sending for password reset link
+- [051] [P] Write failing tests for POST /api/auth/password-reset/request
+  endpoint
+- [052] [P] Implement AuthController.requestPasswordReset() endpoint
+- [053] [P] Add rate limiting to password reset request endpoint
+- [054] Write failing tests for password reset confirmation validation
+- [055] Implement Zod schema for password reset confirmation
+- [056] Write failing tests for AuthRepository.validateResetToken()
+- [057] Implement AuthRepository.validateResetToken() method
+- [058] Write failing tests for AuthService.confirmPasswordReset()
+- [059] Implement AuthService.confirmPasswordReset() with password update
+- [060] Mark reset token as used after successful reset
+- [061] Write failing tests for POST /api/auth/password-reset/confirm endpoint
+- [062] Implement AuthController.confirmPasswordReset() endpoint
+- [063] Add audit logging for password reset events
+- [064] Run all password reset tests and verify they pass
+
+**Checkpoint**: Users can request and complete password reset, expired/invalid
+tokens are rejected
+
+## Phase 6: User Story - P3: Token Refresh
+
+- [065] [P] Write failing tests for token refresh validation
+- [066] [P] Implement Zod schema for refresh token request
+- [067] [P] Write failing tests for AuthRepository.validateRefreshToken()
+- [068] [P] Implement AuthRepository.validateRefreshToken() method
+- [069] [P] Write failing tests for AuthService.refreshToken()
+- [070] [P] Implement AuthService.refreshToken() with token rotation
+- [071] [P] Implement refresh token expiration check
+- [072] [P] Write failing tests for POST /api/auth/refresh endpoint
+- [073] [P] Implement AuthController.refresh() endpoint
+- [074] [P] Run all token refresh tests and verify they pass
+
+**Checkpoint**: Tokens can be refreshed successfully, expired tokens are
+rejected
+
+## Phase 7: Polish and Security
+
+- [075] Implement JWT verification middleware for protected routes
+- [076] Write tests for JWT middleware
+- [077] Implement logout functionality (token blacklisting)
+- [078] Write tests for logout endpoint
+- [079] Add OpenAPI/Swagger documentation for all endpoints
+- [080] Run security audit (password storage, JWT validation, rate limiting)
+- [081] Run performance tests (concurrent logins, response times)
+- [082] Add integration tests for complete user journeys
+- [083] Review and update error messages for clarity
+- [084] Set up audit log cleanup job (90-day retention)
+- [085] Final code review and cleanup
+
+**Checkpoint**: All tests passing, security measures verified, documentation
+complete
+
+## Dependencies & Execution Order
+
+### Required Sequential Order
+
+- Setup (001-005) must complete before Foundational (006-015)
+- Foundational (006-015) must complete before any user story implementation
+- Registration (016-027) should complete before Login (028-043)
+- Login (028-043) should complete before Password Reset and Token Refresh
+
+### Parallel Work Opportunities
+
+- Password Reset (044-064) can be developed in parallel with Token Refresh
+  (065-074) after Login is complete
+- Within each user story, test writing and implementation can be done by
+  different team members
+- Documentation (079) can be written in parallel with final polish tasks
+
+## Implementation Strategies
+
+### Strategy 1: MVP (Minimum Viable Product)
+
+Deliver P1 features first (Registration + Login), deploy to get user feedback,
+then add P2/P3 features.
+
+### Strategy 2: Incremental by Priority
+
+Complete P1 stories → P2 stories → P3 stories in sequence. Deploy after each
+priority level.
+
+### Strategy 3: Parallel Development
+
+Assign user stories to different developers, integrate at the end. Requires
+strong coordination.
+
+**Recommended**: Strategy 2 (Incremental by Priority) for this feature size.