feat(auth): password hashing, JWT, and signup (#3)

* feat(security): add bcrypt hashing and jwt helpers

* feat(schemas): add user create and response schemas with byte validation

* feat(auth): add signup endpoint and register auth router

* test(auth): cover signup, case-insensitivity, and password limits

* chore: add missing error tests and alembic boilerplate

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

app/main.py

@@ -4,6 +4,7 @@ from fastapi import FastAPI, Request
 from fastapi.exceptions import RequestValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from app.errors import AppError, error_response
+from app.routers import auth  # <-- IMPORT THE ROUTER
 
 logger = logging.getLogger("uvicorn.error")
 
@@ -15,7 +16,9 @@ def create_app() -> FastAPI:
         redoc_url=None,
     )
 
-    # 1. Catch-all middleware (must be inside Request-ID)
+    # Register the router
+    app.include_router(auth.router, prefix="/api/v1")
+
     @app.middleware("http")
     async def catch_unhandled(request: Request, call_next):
         try:
@@ -24,7 +27,6 @@ def create_app() -> FastAPI:
             logger.exception("unhandled error", extra={"request_id": getattr(request.state, "request_id", "unknown")})
             return error_response(request, 500, "INTERNAL_ERROR", "Unexpected server error.")
 
-    # 2. Request-ID middleware
     @app.middleware("http")
     async def add_request_id(request: Request, call_next):
         request.state.request_id = str(uuid.uuid4())
@@ -32,7 +34,6 @@ def create_app() -> FastAPI:
         response.headers["X-Request-ID"] = request.state.request_id
         return response
 
-    # 3. Exception Handlers
     @app.exception_handler(AppError)
     async def app_error_handler(request: Request, exc: AppError):
         return error_response(request, exc.status_code, exc.code, exc.message, exc.details, exc.headers)
@@ -41,23 +42,14 @@ def create_app() -> FastAPI:
     async def validation_error_handler(request: Request, exc: RequestValidationError):
         details = []
         for error in exc.errors():
-            # error["loc"] looks like ("body", "name")
             loc = error.get("loc", [])
             field = ".".join(str(x) for x in loc) if loc else "unknown"
-            
             details.append({
                 "field": field,
                 "reason": error.get("type", "invalid"),
                 "message": error.get("msg", "Invalid value")
             })
-            
-        return error_response(
-            request, 
-            422, 
-            "VALIDATION_ERROR", 
-            "Request validation failed.", 
-            details=details
-        )
+        return error_response(request, 422, "VALIDATION_ERROR", "Request validation failed.", details=details)
 
     @app.exception_handler(StarletteHTTPException)
     async def http_exception_handler(request: Request, exc: StarletteHTTPException):

app/models.py

@@ -0,0 +1,76 @@
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, String, Boolean, Integer, DateTime, ForeignKey, UniqueConstraint, LargeBinary
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from pgvector.sqlalchemy import Vector
+from app.db import Base
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email = Column(String(320), nullable=False)
+    password_hash = Column(String(255), nullable=False)
+    role = Column(String(20), nullable=False, default="owner")
+    is_active = Column(Boolean, nullable=False, default=True)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+
+class Hub(Base):
+    __tablename__ = "hubs"
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    name = Column(String(120), nullable=False)
+    description = Column(String(500), nullable=True)
+    ai_summary = Column(String, nullable=True)
+    suggested_questions = Column(JSONB, nullable=False, default=list)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+    
+    __table_args__ = (
+        UniqueConstraint("owner_id", "name", name="uq_hub_name_per_owner"),
+    )
+
+class Document(Base):
+    __tablename__ = "documents"
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    hub_id = Column(UUID(as_uuid=True), ForeignKey("hubs.id", ondelete="CASCADE"), nullable=False)
+    owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    origin = Column(String(20), nullable=False)
+    filename = Column(String(255), nullable=False)
+    mime_type = Column(String(100), nullable=False)
+    size_bytes = Column(Integer, nullable=False)
+    checksum_sha256 = Column(String(64), nullable=False)
+    status = Column(String(20), nullable=False, default="pending")
+    error_message = Column(String, nullable=True)
+    file_bytes = Column(LargeBinary, nullable=True)
+    process_claim = Column(UUID(as_uuid=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+
+    __table_args__ = (
+        UniqueConstraint("hub_id", "checksum_sha256", name="uq_doc_checksum_per_hub"),
+    )
+
+class Chunk(Base):
+    __tablename__ = "chunks"
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    document_id = Column(UUID(as_uuid=True), ForeignKey("documents.id", ondelete="CASCADE"), nullable=False)
+    hub_id = Column(UUID(as_uuid=True), ForeignKey("hubs.id", ondelete="CASCADE"), nullable=False)
+    owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    chunk_index = Column(Integer, nullable=False)
+    text = Column(String, nullable=False)
+    token_count = Column(Integer, nullable=False)
+    embedding = Column(Vector(768), nullable=False)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+
+class IdempotencyKey(Base):
+    __tablename__ = "idempotency_keys"
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), primary_key=True)
+    key = Column(UUID(as_uuid=True), primary_key=True)
+    request_method = Column(String(10), nullable=False)
+    request_path = Column(String(255), nullable=False)
+    request_hash = Column(String(64), nullable=False)
+    status = Column(String(20), nullable=False, default="in_progress")
+    response_status = Column(Integer, nullable=True)
+    response_body = Column(JSONB, nullable=True)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+    expires_at = Column(DateTime(timezone=True), nullable=False)

app/routers/auth.py

@@ -0,0 +1,42 @@
+from fastapi import APIRouter, Depends, status
+from sqlalchemy.orm import Session
+from sqlalchemy.exc import IntegrityError
+from app.db import get_db
+from app.models import User
+from app.schemas import UserCreate, UserResponse
+from app.security import hash_password
+from app.errors import AppError
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+@router.post("/signup", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+def signup(user_data: UserCreate, db: Session = Depends(get_db)):
+    # 1. Check if email exists (using lower() for case-insensitivity)
+    existing_user = db.query(User).filter(User.email.ilike(user_data.email)).first()
+    if existing_user:
+        raise AppError(
+            status_code=409,
+            code="EMAIL_ALREADY_REGISTERED",
+            message="An account with this email already exists.",
+        )
+
+    # 2. Hash password and create user
+    new_user = User(
+        email=user_data.email,
+        password_hash=hash_password(user_data.password)
+    )
+    
+    try:
+        db.add(new_user)
+        db.commit()
+        db.refresh(new_user)
+    except IntegrityError:
+        # Catch race conditions where two requests hit at the exact same time
+        db.rollback()
+        raise AppError(
+            status_code=409,
+            code="EMAIL_ALREADY_REGISTERED",
+            message="An account with this email already exists.",
+        )
+
+    return new_user

app/schemas.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+from uuid import UUID
+from pydantic import BaseModel, EmailStr, Field, ConfigDict, field_validator
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: EmailStr
+    password: str = Field(min_length=8, max_length=128)
+
+    @field_validator("password")
+    @classmethod
+    def password_strength(cls, v: str) -> str:
+        if not any(c.isdigit() for c in v) or not any(c.isalpha() for c in v):
+            raise ValueError("must contain at least one letter and one digit")
+        if len(v.encode("utf-8")) > 72:
+            raise ValueError("must be at most 72 bytes when encoded as UTF-8")
+        return v
+
+class UserResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: UUID
+    email: EmailStr
+    role: str
+    created_at: datetime

app/security.py

@@ -0,0 +1,26 @@
+import bcrypt
+import jwt
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+from app.config import settings
+
+# A dummy hash used to prevent timing attacks when an email doesn't exist
+_DUMMY_HASH = bcrypt.hashpw(b"not-a-real-password", bcrypt.gensalt()).decode()
+
+def hash_password(plain: str) -> str:
+    return bcrypt.hashpw(plain.encode(), bcrypt.gensalt()).decode()
+
+def verify_password(plain: str, stored_hash: str | None) -> bool:
+    # Always runs one bcrypt comparison, even if stored_hash is None
+    ok = bcrypt.checkpw(plain.encode(), (stored_hash or _DUMMY_HASH).encode())
+    return ok and stored_hash is not None
+
+def create_access_token(user_id: UUID, role: str) -> str:
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": str(user_id),
+        "role": role,
+        "iat": now,
+        "exp": now + timedelta(minutes=60),
+    }
+    return jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm="HS256")

tests/test_auth.py

@@ -0,0 +1,61 @@
+def test_signup_valid(client):
+    response = client.post("/api/v1/auth/signup", json={
+        "email": "test@example.com",
+        "password": "ValidPass123"
+    })
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert data["role"] == "owner"
+    assert "password_hash" not in data
+    assert "id" in data
+
+def test_signup_duplicate_email_case_insensitive(client):
+    # First signup
+    client.post("/api/v1/auth/signup", json={
+        "email": "Test@Example.com",
+        "password": "ValidPass123"
+    })
+    # Second signup with different casing
+    response = client.post("/api/v1/auth/signup", json={
+        "email": "test@example.com",
+        "password": "ValidPass123"
+    })
+    assert response.status_code == 409
+    assert response.json()["error"]["code"] == "EMAIL_ALREADY_REGISTERED"
+
+def test_signup_weak_password(client):
+    response = client.post("/api/v1/auth/signup", json={
+        "email": "weak@example.com",
+        "password": "abc"
+    })
+    assert response.status_code == 422
+    data = response.json()
+    assert data["error"]["code"] == "VALIDATION_ERROR"
+    # Check that the field is mapped correctly
+    fields = [d["field"] for d in data["error"]["details"]]
+    assert "body.password" in fields
+
+def test_signup_password_over_72_bytes(client):
+    # 40 emojis * 4 bytes = 160 bytes
+    emoji_password = "😀" * 40
+    response = client.post("/api/v1/auth/signup", json={
+        "email": "emoji@example.com",
+        "password": emoji_password
+    })
+    assert response.status_code == 422
+    data = response.json()
+    fields = [d["field"] for d in response.json()["error"]["details"]]
+    assert "body.password" in fields
+
+def test_signup_extra_field_forbidden(client):
+    response = client.post("/api/v1/auth/signup", json={
+        "email": "hacker@example.com",
+        "password": "ValidPass123",
+        "role": "admin"  # This should be forbidden!
+    })
+    assert response.status_code == 422
+    data = response.json()
+    assert data["error"]["code"] == "VALIDATION_ERROR"
+    fields = [d["field"] for d in data["error"]["details"]]
+    assert "body.role" in fields

tests/test_errors.py

@@ -0,0 +1,47 @@
+def test_404_returns_envelope(client):
+    response = client.get("/nope")
+    assert response.status_code == 404
+    
+    data = response.json()
+    assert "error" in data
+    assert data["error"]["code"] == "ROUTE_NOT_FOUND"
+    assert data["error"]["status"] == 404
+    assert "request_id" in data["error"]
+
+def test_422_returns_field_details(client):
+    # We will create a temporary endpoint just for this test to trigger a 422
+    from app.main import app
+    from pydantic import BaseModel
+    
+    class DummySchema(BaseModel):
+        email: str
+    
+    @app.post("/test-validation")
+    def test_route(data: DummySchema):
+        return {"ok": True}
+        
+    response = client.post("/test-validation", json={"wrong_field": "value"})
+    assert response.status_code == 422
+    
+    data = response.json()
+    assert data["error"]["code"] == "VALIDATION_ERROR"
+    assert data["error"]["details"][0]["field"] == "body.email"
+    assert data["error"]["details"][0]["reason"] == "missing"
+
+def test_request_id_header_present(client):
+    response = client.get("/healthz")
+    assert "X-Request-ID" in response.headers
+    
+def test_unhandled_exception_returns_500_envelope(client):
+    from app.main import app
+    @app.get("/test-crash")
+    def crash_route():
+        raise ValueError("Boom!")
+        
+    response = client.get("/test-crash")
+    assert response.status_code == 500
+    data = response.json()
+    assert data["error"]["code"] == "INTERNAL_ERROR"
+    # Ensure no traceback leaks
+    assert "Traceback" not in response.text
+    assert "ValueError" not in response.text