frankbria
diff --git a/‎CLAUDE.md‎
Lines changed: 6 additions & 4 deletions b/‎CLAUDE.md‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 72 additions & 8 deletions b/‎CONTRIBUTING.md‎
Lines changed: 72 additions & 8 deletions
diff --git a/‎README.md‎
Lines changed: 9 additions & 0 deletions b/‎README.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎SECURITY.md‎
Lines changed: 45 additions & 0 deletions b/‎SECURITY.md‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎codeframe/core/project.py‎
Lines changed: 4 additions & 1 deletion b/‎codeframe/core/project.py‎
Lines changed: 4 additions & 1 deletion
@@ -38,12 +38,14 @@ Quick reference:
 └── docs/             # Additional documentation
 ```
 
+NOTE: This is a pre-production application, so there is no need for database migration scripting or backward compatibility. Keep the schema flat as much as possible.
+
 ## Commands
 ```bash
-pytest                 # Run all tests
-pytest tests/test_*worker_agent.py  # Worker agent tests (async)
-ruff check .           # Lint code
-cd web-ui && npm test  # Frontend tests
+uv run pytest                              # Run all tests
+uv run pytest tests/test_*worker_agent.py  # Worker agent tests (async)
+uv run ruff check .                        # Lint code
+cd web-ui && npm test                      # Frontend tests
 ```
 
 ## Context Management for AI Conversations
 
@@ -9,19 +9,31 @@ Thank you for your interest in contributing to CodeFRAME!
 git clone https://github.com/frankbria/codeframe.git
 cd codeframe
 
+# Install uv package manager
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
 # Create virtual environment
-python -m venv venv
-source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+uv venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
 
 # Install development dependencies
-pip install -e ".[dev]"
+uv sync
+
+# Set up environment variables
+export ANTHROPIC_API_KEY="your-api-key-here"
+export AUTH_REQUIRED=false  # Optional, for local development
+
+# Set up frontend (if working on UI)
+cd web-ui
+npm install
+cd ..
 
 # Run tests
-pytest
+uv run pytest
 
 # Format code
-black codeframe tests
-ruff check codeframe tests
+uv run ruff format codeframe tests
+uv run ruff check codeframe tests
 ```
 
 ## Code Style
@@ -40,11 +52,63 @@ Before contributing, review relevant architecture documentation in [`docs/archit
 
 Add new architecture documentation when introducing cross-cutting patterns or data model changes.
 
+## Authentication & Security
+
+CodeFRAME uses Better Auth for authentication and implements comprehensive authorization checks.
+
+### Working with Authentication
+
+**Development Mode** (AUTH_REQUIRED=false):
+- Authentication is optional
+- Requests without tokens receive default admin user (id=1)
+- Useful for local development and testing
+
+**Production Mode** (AUTH_REQUIRED=true):
+- Authentication is required for all endpoints
+- Requests without valid tokens receive 401 Unauthorized
+
+### Adding Protected Endpoints
+
+When creating new API endpoints that access project resources:
+
+```python
+from fastapi import HTTPException, Depends
+from codeframe.persistence.database import Database
+from codeframe.ui.dependencies import get_db, get_current_user, User
+
+@router.get("/api/projects/{project_id}/resource")
+async def get_resource(
+    project_id: int,
+    db: Database = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    # 1. Verify project exists
+    project = db.get_project(project_id)
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    # 2. Authorization check
+    if not db.user_has_project_access(current_user.id, project_id):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    # 3. Proceed with operation
+    return {"resource": "data"}
+```
+
+**Key Requirements**:
+- Add `current_user: User = Depends(get_current_user)` parameter
+- Check project existence before authorization check
+- Use `db.user_has_project_access()` for authorization
+- Return 403 Forbidden (not 404) for unauthorized access
+
+**See Also**: [docs/authentication.md](docs/authentication.md) for complete guide.
+
 ## Testing
 
 - Write unit tests for new features
-- Maintain >80% code coverage
-- Run `pytest` before submitting PRs
+- Maintain >85% code coverage
+- Run `uv run pytest` before submitting PRs
+- Include authentication/authorization tests for protected endpoints
 
 ## Pull Request Process
 
 
@@ -122,6 +122,7 @@ Unlike traditional AI coding assistants that wait for your prompts, CodeFRAME ag
 - Python 3.11+
 - Node.js 18+ (for frontend)
 - Anthropic API key
+- SQLite 3 (included with Python)
 
 ### Installation
 
@@ -141,6 +142,9 @@ uv sync
 # Set up environment
 export ANTHROPIC_API_KEY="your-api-key-here"
 
+# Optional: Enable authentication (default: false for development)
+export AUTH_REQUIRED=false  # Set to 'true' for production
+
 # Set up frontend
 cd web-ui
 npm install
@@ -236,11 +240,15 @@ curl -X POST http://localhost:8080/api/projects/1/checkpoints/5/restore
 # Required
 ANTHROPIC_API_KEY=sk-ant-...           # Anthropic API key
 
+# Optional - Authentication
+AUTH_REQUIRED=false                    # Enable authentication (default: false for development)
+
 # Optional - Database
 DATABASE_PATH=./codeframe.db           # SQLite database path (default: in-memory)
 
 # Optional - Quality Enforcement
 MIN_COVERAGE_PERCENT=85                # Minimum test coverage required
+CODEFRAME_ENABLE_SKIP_DETECTION=true   # Enable skip detection gate (default: true)
 
 # Optional - Git Integration
 AUTO_COMMIT_ENABLED=true               # Enable automatic commits after test passes
@@ -352,6 +360,7 @@ For detailed documentation, see:
 
 - **Product Requirements**: [PRD.md](PRD.md)
 - **System Architecture**: [CODEFRAME_SPEC.md](CODEFRAME_SPEC.md)
+- **Authentication & Authorization**: [docs/authentication.md](docs/authentication.md) - Complete guide to security features
 - **Architecture Decisions**: [`docs/architecture/`](docs/architecture/) - Technical design decisions and data model semantics
 - **Sprint Planning**: [SPRINTS.md](SPRINTS.md)
 - **Feature Specs**: `specs/{feature}/spec.md`
 
@@ -6,6 +6,42 @@ If you discover a security vulnerability in CodeFRAME, please report it by email
 
 ## Security Best Practices
 
+### Authentication & Authorization (Issue #132)
+
+CodeFRAME implements comprehensive authentication and authorization to address OWASP A01 - Broken Access Control vulnerability.
+
+#### Authentication
+- **Email/Password**: Secure authentication with bcrypt password hashing (salt rounds=12)
+- **Session Management**: 7-day sessions with automatic expiry and cleanup
+- **Token Validation**: All API requests validate Bearer tokens against sessions table
+- **Better Auth**: Frontend authentication using Better Auth v1.4.7
+
+#### Authorization
+- **Project Ownership**: All projects have an owner (user_id in projects table)
+- **Role-Based Access**: Owner, collaborator, and viewer roles via project_users table
+- **Access Checks**: All API endpoints verify `user_has_project_access()` before operations
+- **403 vs 404**: Returns 403 Forbidden (not 404) for unauthorized access to prevent information leakage
+
+#### Audit Logging
+- **Comprehensive Logging**: All authentication, authorization, and lifecycle events logged
+- **Database Persistence**: audit_logs table with indexes for performance
+- **Event Types**: AUTH_LOGIN_SUCCESS, AUTH_LOGIN_FAILED, AUTHZ_ACCESS_GRANTED, AUTHZ_ACCESS_DENIED, PROJECT_CREATED, etc.
+- **Metadata**: Structured JSON metadata for each event (user_id, ip_address, resource details)
+
+#### Security Configuration
+
+**Development** (authentication optional):
+```bash
+export AUTH_REQUIRED=false
+```
+
+**Production** (authentication required):
+```bash
+export AUTH_REQUIRED=true
+```
+
+**See Also**: [docs/authentication.md](docs/authentication.md) for complete authentication guide.
+
 ### Command Injection Prevention
 
 CodeFRAME's `AdaptiveTestRunner` executes test commands detected from project configuration files. To prevent command injection vulnerabilities:
@@ -96,6 +132,15 @@ subprocess.run(command, shell=True, cwd=project_path)
 
 ## Security Changelog
 
+### Issue #132 (2025-12-21)
+- **Added**: Comprehensive authentication and authorization infrastructure
+  - Email/password authentication with Better Auth v1.4.7
+  - Session management with 7-day expiry
+  - Project ownership model with role-based access control
+  - Authorization checks on all API endpoints
+  - Comprehensive audit logging (auth, authz, lifecycle events)
+  - Addresses OWASP A01 - Broken Access Control vulnerability
+
 ### Sprint 8 (2025-11-15)
 - **Fixed**: Command injection vulnerability in `AdaptiveTestRunner`
   - Added `SAFE_COMMANDS` allowlist
 
@@ -119,7 +119,10 @@ def create(cls, project_name: str, project_dir: Optional[Path] = None) -> "Proje
         project.db.initialize()
 
         # Create initial project record
-        project.db.create_project(project_name, ProjectStatus.INIT)
+        project.db.create_project(
+            name=project_name,
+            description=""
+        )
 
         return project