Phase 2 complete

Author: Shashankpgit

README.md

@@ -1 +1,127 @@
-# development
+# Personal Vault
+
+A multi-user private storage application for notes and passwords.
+Built progressively across 13 phases as a full-stack learning project.
+
+---
+
+## Project structure
+
+```
+development/
+├── vault/                  ← application code
+├── docs/                   ← planning docs, KT docs, API reference
+├── claude-instructions/    ← phase-by-phase implementation playbooks
+└── README.md               ← this file
+```
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- Docker (for PostgreSQL)
+
+---
+
+## First-time setup
+
+```bash
+# 1. Clone and enter the repo
+cd development/vault
+
+# 2. Create and activate the virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+
+# 4. Copy the environment file and fill in your values
+cp .env.example .env
+# edit .env with your credentials
+
+# 5. Start the PostgreSQL container
+docker run --name vault-db \
+  -e POSTGRES_USER=vault_user \
+  -e POSTGRES_PASSWORD=vault_pass \
+  -e POSTGRES_DB=vault \
+  -p 5432:5432 \
+  -d postgres:16
+```
+
+---
+
+## Daily workflow
+
+Every time you start working on the project:
+
+```bash
+# 1. Start the database (if not already running)
+docker start vault-db
+
+# 2. Activate the virtual environment
+cd vault
+source .venv/bin/activate
+
+# 3. Start the server
+uvicorn app.main:app --reload
+```
+
+---
+
+## Stopping everything
+
+```bash
+# Stop the server
+Ctrl+C
+
+# Stop the database container (data is preserved)
+docker stop vault-db
+```
+
+---
+
+## Useful URLs (while server is running)
+
+| URL | What it is |
+|---|---|
+| `http://localhost:8000/health` | Health check — confirms server + DB are up |
+| `http://localhost:8000/docs` | Swagger UI — interactive API explorer |
+| `http://localhost:8000/redoc` | ReDoc — alternative API documentation |
+
+---
+
+## Useful commands
+
+```bash
+# Check if the database container is running
+docker ps --filter name=vault-db
+
+# View database container logs
+docker logs vault-db
+
+# Connect directly to PostgreSQL (inspect data)
+docker exec -it vault-db psql -U vault_user -d vault
+
+# Inside psql — list tables
+\dt
+
+# Inside psql — exit
+\q
+
+# Check installed Python packages
+pip list
+
+# Install new dependencies after pulling changes
+pip install -r requirements.txt
+```
+
+---
+
+## Current phase
+
+**Phase 1 complete** — project setup, first API endpoint, PostgreSQL connection.
+
+See `docs/` for planning documents and KT notes.
+See `docs/api/` for API reference.

docs/004-user-model-plan.md

@@ -0,0 +1,89 @@
+# 004 — User Model
+
+---
+
+## Part 1: What we are doing
+
+**Goal:** Create the `User` database table and the API endpoints to create and fetch users. No authentication yet — passwords stored as plaintext with a clear TODO marker.
+
+### Files being created / modified
+```
+vault/app/models/user.py        ← new: SQLAlchemy User model (the table)
+vault/app/schemas/user.py       ← new: Pydantic schemas (request/response shapes)
+vault/app/routers/users.py      ← new: POST /users, GET /users/{id}
+vault/app/models/__init__.py    ← modified: import User so create_all finds it
+vault/app/main.py               ← modified: register users router
+docs/api/users.md               ← updated: full endpoint documentation
+```
+
+### The table being created
+```
+users
+├── id             INTEGER, primary key, auto-increment
+├── username       VARCHAR(50), unique, not null
+├── hashed_password TEXT, not null
+└── created_at     TIMESTAMP, default = now
+```
+
+### Steps
+1. Create `app/models/user.py`
+2. Import User in `app/models/__init__.py`
+3. Create `app/schemas/user.py`
+4. Create `app/routers/users.py`
+5. Register router in `app/main.py`
+6. Start server → verify table is created in PostgreSQL
+7. Test via Swagger, curl, and Postman
+
+### What is NOT done in this step
+- No password hashing (plaintext for now, TODO comment added — fixed in Phase 4)
+- No login
+- No authentication
+- No relationship to notes or passwords yet
+
+---
+
+## Part 2: Concepts / KT
+
+### SQLAlchemy model
+A Python class that maps directly to a database table. You define columns as class attributes using SQLAlchemy's `Column` type. When `create_all()` runs at startup, SQLAlchemy reads these class definitions and generates the `CREATE TABLE` SQL automatically.
+
+```python
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    username = Column(String(50), unique=True, nullable=False)
+```
+
+SQLAlchemy generates:
+```sql
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    username VARCHAR(50) UNIQUE NOT NULL
+);
+```
+
+You write Python. SQLAlchemy writes SQL.
+
+### Pydantic schema vs SQLAlchemy model
+Two different things that look similar but serve different purposes:
+
+| | SQLAlchemy Model | Pydantic Schema |
+|---|---|---|
+| Purpose | Defines the database table | Defines the API input/output shape |
+| Used by | SQLAlchemy (DB operations) | FastAPI (request validation + response serialisation) |
+| Location | `app/models/` | `app/schemas/` |
+
+Why keep them separate? The `User` model has a `hashed_password` column. You never want to return that in an API response. So `UserResponse` schema simply doesn't include it. Two shapes for two different contexts.
+
+### `model_config = ConfigDict(from_attributes=True)`
+Pydantic v2 needs this on response schemas to read data from SQLAlchemy model objects. Without it, Pydantic wouldn't know how to convert a SQLAlchemy `User` object into a JSON-serialisable dict.
+
+### `nullable=False` vs `unique=True`
+- `nullable=False` → the column must always have a value. Inserting a row without this column fails.
+- `unique=True` → no two rows can have the same value in this column. Trying to create two users with the same username fails with an `IntegrityError`.
+
+### `server_default=func.now()`
+Instead of setting `created_at` in Python, we tell the database to set it automatically at insert time using the database's own clock. More reliable than Python time (no timezone confusion between app server and DB server).
+
+### Why plaintext passwords now
+Hashing is a Phase 4 concern — it belongs with JWT and authentication. Introducing it now would mix two concepts at once. A `TODO` comment marks it clearly. This is how real teams work — ship the minimum, mark the gap, fix it in the right phase.

docs/005-crud-notes-plan.md

@@ -0,0 +1,87 @@
+# 005 — Notes CRUD
+
+---
+
+## Part 1: What we are doing
+
+**Goal:** Build full CRUD for text notes. A note belongs to a user via a foreign key. No authentication yet — user_id is passed in the request body for now.
+
+### Files being created / modified
+```
+vault/app/models/note.py        ← new: Note SQLAlchemy model
+vault/app/schemas/note.py       ← new: NoteCreate, NoteUpdate, NoteResponse
+vault/app/routers/notes.py      ← new: 5 endpoints
+vault/app/models/__init__.py    ← modified: import Note
+vault/app/main.py               ← modified: register notes router
+docs/api/notes.md               ← updated: full endpoint documentation
+```
+
+### The table being created
+```
+notes
+├── id          INTEGER, primary key, auto-increment
+├── user_id     INTEGER, foreign key → users.id
+├── title       VARCHAR(200), not null
+├── body        TEXT, nullable
+├── created_at  TIMESTAMP, default = now
+└── updated_at  TIMESTAMP, default = now, updates on every change
+```
+
+### Endpoints
+| Method | Path | Action |
+|---|---|---|
+| `POST` | `/notes` | Create a note |
+| `GET` | `/notes?user_id=1` | List notes for a user |
+| `GET` | `/notes/{id}` | Get a single note |
+| `PUT` | `/notes/{id}` | Update a note |
+| `DELETE` | `/notes/{id}` | Delete a note |
+
+### What is NOT done in this step
+- No auth guard — any user_id can be passed freely (fixed in Phase 4)
+- No tags or search
+- No frontend
+
+---
+
+## Part 2: Concepts / KT
+
+### Foreign key
+A column that points to the primary key of another table. `notes.user_id` points to `users.id`. This is how relational databases connect data.
+
+```
+users table          notes table
+id | username        id | user_id | title
+1  | bob      ◄───  1  |    1    | "My first note"
+2  | alice           2  |    1    | "Second note"
+                     3  |    2    | "Alice's note"
+```
+
+If you try to create a note with `user_id=99` and no user with `id=99` exists, the database rejects it with a `ForeignKeyViolation` error. The database itself enforces the relationship — your code doesn't have to check manually.
+
+### `onupdate=func.now()`
+`updated_at` should automatically change every time the row is modified. SQLAlchemy's `onupdate` parameter does exactly this — whenever you `UPDATE` that row, SQLAlchemy sets the column to the current timestamp automatically.
+
+### Query parameters vs path parameters
+Two different ways to pass values in a URL:
+
+```
+GET /notes/5          ← path parameter: identifies WHICH note
+GET /notes?user_id=1  ← query parameter: FILTERS the list
+```
+
+Path parameter = the identity of a specific resource. Always required.
+Query parameter = optional filter or option. Appears after `?`.
+
+### `NoteUpdate` with Optional fields
+An update request shouldn't require all fields — you might only want to change the title without touching the body. Pydantic's `Optional` handles this:
+
+```python
+class NoteUpdate(BaseModel):
+    title: Optional[str] = None
+    body: Optional[str] = None
+```
+
+Only fields sent in the request get updated. Fields not sent stay as they are.
+
+### `response_model` on routes
+Every route that returns data should declare `response_model=NoteResponse`. This tells FastAPI exactly what shape to return and strips out anything not in the schema. This is also where the deliberate mistake in this step comes from — see what happens when `model_config = ConfigDict(from_attributes=True)` is missing from the schema.

docs/006-crud-passwords-plan.md

@@ -0,0 +1,88 @@
+# 006 — Passwords CRUD
+
+---
+
+## Part 1: What we are doing
+
+**Goal:** Build CRUD for stored password entries. Passwords are encrypted before being saved to the database and decrypted on retrieval. The encryption key lives in `.env`.
+
+### Files being created / modified
+```
+vault/app/utils/__init__.py         ← new: makes utils a package
+vault/app/utils/crypto.py           ← new: encrypt / decrypt helpers
+vault/app/models/password_entry.py  ← new: PasswordEntry SQLAlchemy model
+vault/app/schemas/password_entry.py ← new: request/response schemas
+vault/app/routers/passwords.py      ← new: 5 endpoints
+vault/app/models/__init__.py        ← modified: import PasswordEntry
+vault/app/main.py                   ← modified: register passwords router
+vault/requirements.txt              ← modified: add cryptography
+vault/.env.example                  ← modified: add VAULT_ENCRYPTION_KEY
+docs/api/passwords.md               ← updated: full endpoint documentation
+```
+
+### The table being created
+```
+password_entries
+├── id               INTEGER, primary key, auto-increment
+├── user_id          INTEGER, foreign key → users.id
+├── label            VARCHAR(100), not null  (e.g. "Gmail", "GitHub")
+├── username         VARCHAR(100), not null  (the username for that service)
+├── encrypted_value  TEXT, not null          (the password, encrypted)
+├── created_at       TIMESTAMP, default = now
+└── updated_at       TIMESTAMP, default = now, updates on change
+```
+
+### Endpoints
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/passwords` | Store a new password (encrypted) |
+| `GET` | `/passwords?user_id=1` | List entries — value NOT included |
+| `GET` | `/passwords/{id}` | Get single entry WITH decrypted value |
+| `PUT` | `/passwords/{id}` | Update (re-encrypts if value changes) |
+| `DELETE` | `/passwords/{id}` | Delete |
+
+### What is NOT done in this step
+- No auth guard (Phase 4)
+- No key rotation
+- No tags
+
+---
+
+## Part 2: Concepts / KT
+
+### Hashing vs Encryption — the critical distinction
+
+This is the most important concept in this step.
+
+| | Hashing | Encryption |
+|---|---|---|
+| Direction | One-way — cannot be reversed | Two-way — can be decrypted |
+| Algorithm | bcrypt, SHA256 | AES, Fernet |
+| Use case | Login passwords | Secrets you need to read back |
+| Example | Your Vault login password | Your Gmail password stored in Vault |
+
+Your Vault login password is **hashed** — the server never needs to know the original, it just checks if what you typed matches the hash.
+
+Your Gmail password stored inside the Vault is **encrypted** — you need to read it back in full when you open your vault. Hashing it would make it permanently unreadable.
+
+Same word "password", completely different treatment.
+
+### Fernet symmetric encryption
+Fernet is a symmetric encryption scheme from the `cryptography` library. One key encrypts and decrypts. The key must be:
+- Exactly 32 bytes
+- URL-safe base64 encoded
+- Generated using `Fernet.generate_key()` — not made up by hand
+
+Generate one for your `.env`:
+```bash
+python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+### Why the key must live in `.env`
+The deliberate mistake in this step shows exactly what happens when it doesn't — a new random key is generated every server restart. Any previously encrypted values become permanently unreadable. In production, losing the key = losing all stored passwords.
+
+### Two response schemas for passwords
+- `PasswordListResponse` — used in `GET /passwords?user_id=1`. No `value` field. You don't return the password on every list call — only when specifically requested.
+- `PasswordDetailResponse` — used in `GET /passwords/{id}`. Includes the decrypted `value`.
+
+This is a real-world API design principle: return the minimum data needed for each context.