Add Cloudflare Tunnel connector (profile-gated) to the deploy stack

A cloudflared service (opt-in via the 'tunnel' compose profile, token from CLOUDFLARE_TUNNEL_TOKEN) connects the lab to Cloudflare. One public hostname -> http://caddy:80 is sufficient because Caddy does the internal path routing. Mirrors the drawbar tunnel setup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

.gitea/workflows/build-backend.yml

@@ -0,0 +1,105 @@
+name: build-backend
+
+# Builds + pushes the backend image to justin/provenance-backend's package area
+# on Gitea on every merge to main. Servers pull from git.jpaul.io.
+#
+# Push goes to the LAN registry endpoint 192.168.0.2:1234 (plain HTTP) to bypass
+# Cloudflare's request-body limit; pulls use the public git.jpaul.io FQDN. Same
+# Gitea registry either way. Mirrors the drawbar setup.
+#
+# Tag scheme: test-main | test-sha-<long> | <semver from pyproject> | latest (v* tags)
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    tags: ['v*']
+    paths:
+      - 'backend/**'
+      - '.gitea/workflows/build-backend.yml'
+
+concurrency:
+  group: build-backend-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from pyproject.toml
+        id: ver
+        run: |
+          v=$(grep -oP '^version = "\K[^"]+' backend/pyproject.toml | head -1)
+          if [ -z "$v" ]; then echo "could not parse version from backend/pyproject.toml"; exit 1; fi
+          echo "semver=$v" >> "$GITHUB_OUTPUT"
+          echo "backend semver: $v"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          # LAN registry serves plain HTTP on :1234 (git.jpaul.io is the only TLS
+          # endpoint, via Cloudflare). Treat the LAN endpoint as insecure so
+          # buildkit doesn't try to upgrade the push to HTTPS.
+          config-inline: |
+            [registry."192.168.0.2:1234"]
+              http = true
+              insecure = true
+
+      - name: Configure registry credentials for buildx
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          REGISTRY_USER: ${{ github.actor }}
+        run: |
+          mkdir -p ~/.docker
+          AUTH=$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_TOKEN" | base64 -w0)
+          cat > ~/.docker/config.json <<EOF
+          {
+            "auths": {
+              "192.168.0.2:1234": {
+                "auth": "$AUTH"
+              }
+            }
+          }
+          EOF
+
+      - name: Compute tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: 192.168.0.2:1234/justin/provenance-backend
+          tags: |
+            type=ref,event=branch,prefix=test-
+            type=sha,prefix=test-sha-,format=long
+            type=raw,value=${{ steps.ver.outputs.semver }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+          labels: |
+            org.opencontainers.image.source=https://git.jpaul.io/justin/provenance
+            org.opencontainers.image.version=${{ steps.ver.outputs.semver }}
+
+      - name: Build and push (amd64)
+        uses: docker/build-push-action@v6
+        with:
+          context: ./backend
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Link package to the provenance repo
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          code=$(curl -s -o /tmp/link.out -w "%{http_code}" -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            "https://git.jpaul.io/api/v1/packages/justin/container/provenance-backend/-/link/provenance")
+          echo "link -> provenance: HTTP $code"
+          case "$code" in
+            201) echo "OK — newly linked" ;;
+            400|409) echo "OK — already linked" ;;
+            *) cat /tmp/link.out; exit 1 ;;
+          esac

.gitea/workflows/build-frontend.yml

@@ -0,0 +1,102 @@
+name: build-frontend
+
+# Builds + pushes the Next.js image to justin/provenance-frontend's package area
+# on Gitea on every merge to main. Servers pull from git.jpaul.io.
+#
+# Push -> LAN registry 192.168.0.2:1234 (plain HTTP); pull -> git.jpaul.io.
+# Mirrors the drawbar setup; see build-backend.yml for the rationale.
+#
+# Tag scheme: test-main | test-sha-<long> | <version from package.json> | latest (v* tags)
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    tags: ['v*']
+    paths:
+      - 'frontend/**'
+      - '.gitea/workflows/build-frontend.yml'
+
+concurrency:
+  group: build-frontend-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from package.json
+        id: ver
+        run: |
+          v=$(grep -oP '"version"\s*:\s*"\K[^"]+' frontend/package.json | head -1)
+          if [ -z "$v" ]; then echo "could not parse version from frontend/package.json"; exit 1; fi
+          echo "semver=$v" >> "$GITHUB_OUTPUT"
+          echo "frontend version: $v"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          # See build-backend.yml for why these flags are needed.
+          config-inline: |
+            [registry."192.168.0.2:1234"]
+              http = true
+              insecure = true
+
+      - name: Configure registry credentials for buildx
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          REGISTRY_USER: ${{ github.actor }}
+        run: |
+          mkdir -p ~/.docker
+          AUTH=$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_TOKEN" | base64 -w0)
+          cat > ~/.docker/config.json <<EOF
+          {
+            "auths": {
+              "192.168.0.2:1234": {
+                "auth": "$AUTH"
+              }
+            }
+          }
+          EOF
+
+      - name: Compute tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: 192.168.0.2:1234/justin/provenance-frontend
+          tags: |
+            type=ref,event=branch,prefix=test-
+            type=sha,prefix=test-sha-,format=long
+            type=raw,value=${{ steps.ver.outputs.semver }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+          labels: |
+            org.opencontainers.image.source=https://git.jpaul.io/justin/provenance
+            org.opencontainers.image.version=${{ steps.ver.outputs.semver }}
+
+      - name: Build and push (amd64)
+        uses: docker/build-push-action@v6
+        with:
+          context: ./frontend
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Link package to the provenance repo
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          code=$(curl -s -o /tmp/link.out -w "%{http_code}" -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            "https://git.jpaul.io/api/v1/packages/justin/container/provenance-frontend/-/link/provenance")
+          echo "link -> provenance: HTTP $code"
+          case "$code" in
+            201) echo "OK — newly linked" ;;
+            400|409) echo "OK — already linked" ;;
+            *) cat /tmp/link.out; exit 1 ;;
+          esac

.gitea/workflows/build.yml

@@ -1,40 +0,0 @@
-name: build-images
-
-# Gitea Actions build container images and push to the Gitea registry on
-# git.jpaul.io. Servers pull to deploy — no build on the host.
-#
-# Requires repo/org secrets: REGISTRY_USERNAME, REGISTRY_PASSWORD (a token with
-# package:write). Adjust the runner label to one your Gitea runner advertises.
-
-on:
-  push:
-    branches: [main]
-    tags: ["v*"]
-
-env:
-  REGISTRY: git.jpaul.io
-  IMAGE_BASE: git.jpaul.io/${{ github.repository }}
-
-jobs:
-  backend:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: docker/setup-buildx-action@v3
-
-      - name: Log in to the Gitea registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ secrets.REGISTRY_USERNAME }}
-          password: ${{ secrets.REGISTRY_PASSWORD }}
-
-      - name: Build and push backend image
-        uses: docker/build-push-action@v6
-        with:
-          context: ./backend
-          push: true
-          tags: |
-            ${{ env.IMAGE_BASE }}/backend:latest
-            ${{ env.IMAGE_BASE }}/backend:${{ github.sha }}

CLAUDE.md

@@ -29,7 +29,7 @@ These are product invariants, not preferences. Do not violate them, and flag any
 - **Object storage:** S3-compatible (MinIO for self-host).
 - **Edge:** Caddy reverse proxy; optional Cloudflare Tunnel (preferred ingress, never required).
 - **Email:** operator-configured SMTP.
-- **CI/CD:** Gitea Actions on `git.jpaul.io` build container images to the Gitea registry; servers pull to deploy.
+- **CI/CD:** Gitea Actions build per-component images. **Push** to the LAN registry `192.168.0.2:1234` (plain HTTP, bypasses Cloudflare's body limit); **pull** via the public `git.jpaul.io` FQDN. Servers pull to deploy — no host build. Mirrors the drawbar setup; see [[gitea-lan-push-fqdn-pull]].
 
 Pick libraries consistent with this stack. If you introduce a significant dependency or a new service, note it in ARCHITECTURE.md in the same change.
 
@@ -38,17 +38,17 @@ Pick libraries consistent with this stack. If you introduce a significant depend
 ```
 /                  # docs and project meta (this file, README, LICENSE, COC, CONTRIBUTING)
 /docs              # PRD.md, ARCHITECTURE.md
-/backend           # FastAPI service (uv-managed). app/ = api / core (config, db); more layers land with the data model
+/backend           # FastAPI service (uv-managed). app/{api/v1, services (+ privacy engine), repositories, models, schemas, integrations (auth/mailer), core}; migrations/ = Alembic
 /deploy            # docker-compose.yml, Caddyfile, .env.example — the self-host stack
 /.gitea/workflows  # Gitea Actions CI (build images → Gitea registry)
-/frontend          # Next.js app — not yet scaffolded (Phase 0, after the deploy story)
+/frontend          # Next.js (App Router, TS, Tailwind, shadcn-style UI). app/ pages, lib/api generated OpenAPI client, components/ui
 ```
 
-Phase 0 is landing **deploy-first**: the compose stack (Postgres + MinIO + Caddy + a minimal FastAPI backend exposing `/health` and `/health/ready`) and CI come before the real data model and the frontend. Backend dependencies are managed with **uv**; migrations will use **Alembic**. Keep this section current as the tree grows.
+Phase 0 is landing **deploy-first**: the compose stack (Postgres + MinIO + Caddy + a minimal FastAPI backend exposing `/health` and `/health/ready`) and CI come before the real data model and the frontend. Backend dependencies are managed with **uv**; migrations use **Alembic**. The core data model (ARCHITECTURE §5), **local auth** (Argon2 passwords, backend-issued sessions, email verify/reset behind the `AuthProvider` interface; API auth via Bearer header or HttpOnly cookie), and the **Next.js frontend scaffold** (Tailwind + shadcn-style UI, generated OpenAPI client, auth + tree/person views) have all landed — **Phase 0 is complete and running on the live deployment.** Phase 1 (core tree features — media, soft-delete recovery, richer CRUD) is next; OIDC/social auth is Phase 5. Keep this section current as the tree grows.
 
 ## Where to start
 
-The roadmap is phased in PRD §8. Build in dependency order. **Phase 0 — Foundation** is the current target:
+The roadmap is phased in PRD §8. Build in dependency order. **Phase 0 — Foundation is complete** and running on the live deployment; **Phase 1 (core tree features) is the current target.** For reference, Phase 0 covered:
 
 1. Backend skeleton (FastAPI, async, layered) + Postgres + migrations
 2. Core data model from ARCHITECTURE §5 — start with User, Tree, TreeMembership, Person, Name, Relationship, Event, Place, Source, Citation, AuditEntry, soft-delete support

backend/app/api/deps.py

@@ -0,0 +1,48 @@
+"""Shared API dependencies: DB session, the authenticated user, and the mailer."""
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import get_settings
+from app.core.db import get_session
+from app.integrations.mailer.base import Mailer
+from app.integrations.mailer.console import ConsoleMailer
+from app.integrations.mailer.smtp import SMTPMailer
+from app.models.user import User
+from app.services import auth_service
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+
+def extract_session_token(request: Request) -> str | None:
+    """Bearer header (API clients) takes precedence over the session cookie
+    (browser)."""
+    authorization = request.headers.get("authorization")
+    if authorization and authorization.lower().startswith("bearer "):
+        return authorization[7:].strip()
+    return request.cookies.get(get_settings().cookie_name)
+
+
+async def get_current_user(request: Request, session: SessionDep) -> User:
+    raw_token = extract_session_token(request)
+    if raw_token is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "authentication required")
+    user = await auth_service.resolve_session_user(session, raw_token=raw_token)
+    if user is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid or expired session")
+    return user
+
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+
+def get_mailer() -> Mailer:
+    settings = get_settings()
+    if settings.mailer == "smtp" and settings.smtp_host:
+        return SMTPMailer(settings)
+    return ConsoleMailer()
+
+
+MailerDep = Annotated[Mailer, Depends(get_mailer)]

backend/app/api/v1/__init__.py

@@ -0,0 +1,11 @@
+"""Versioned API surface. Mounts under /api/v1."""
+
+from fastapi import APIRouter
+
+from app.api.v1 import auth, persons, trees, users
+
+api_router = APIRouter(prefix="/api/v1")
+api_router.include_router(auth.router)
+api_router.include_router(users.router)
+api_router.include_router(trees.router)
+api_router.include_router(persons.router)

backend/app/api/v1/auth.py

@@ -0,0 +1,81 @@
+from fastapi import APIRouter, HTTPException, Request, Response, status
+
+from app.api.deps import MailerDep, SessionDep, extract_session_token
+from app.core.config import get_settings
+from app.schemas.auth import (
+    LoginRequest,
+    PasswordResetConfirm,
+    PasswordResetRequest,
+    RegisterRequest,
+    SessionRead,
+    TokenRequest,
+)
+from app.schemas.user import UserRead
+from app.services import auth_service
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+def _set_session_cookie(response: Response, token: str) -> None:
+    settings = get_settings()
+    response.set_cookie(
+        settings.cookie_name,
+        token,
+        max_age=settings.session_ttl_days * 86400,
+        httponly=True,
+        secure=settings.cookie_secure,
+        samesite="lax",
+    )
+
+
+@router.post("/register", response_model=SessionRead, status_code=status.HTTP_201_CREATED)
+async def register(
+    data: RegisterRequest, session: SessionDep, mailer: MailerDep, response: Response
+) -> SessionRead:
+    user, token, expires_at = await auth_service.register(
+        session,
+        mailer,
+        email=data.email,
+        password=data.password,
+        display_name=data.display_name,
+    )
+    _set_session_cookie(response, token)
+    return SessionRead(user=UserRead.model_validate(user), token=token, expires_at=expires_at)
+
+
+@router.post("/login", response_model=SessionRead)
+async def login(data: LoginRequest, session: SessionDep, response: Response) -> SessionRead:
+    result = await auth_service.login(session, email=data.email, password=data.password)
+    if result is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid credentials")
+    user, token, expires_at = result
+    _set_session_cookie(response, token)
+    return SessionRead(user=UserRead.model_validate(user), token=token, expires_at=expires_at)
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
+async def logout(request: Request, session: SessionDep, response: Response) -> None:
+    raw_token = extract_session_token(request)
+    if raw_token:
+        await auth_service.logout(session, raw_token=raw_token)
+    response.delete_cookie(get_settings().cookie_name)
+
+
+@router.post("/verify-email", status_code=status.HTTP_204_NO_CONTENT)
+async def verify_email(data: TokenRequest, session: SessionDep) -> None:
+    await auth_service.verify_email(session, raw_token=data.token)
+
+
+@router.post("/request-password-reset", status_code=status.HTTP_202_ACCEPTED)
+async def request_password_reset(
+    data: PasswordResetRequest, session: SessionDep, mailer: MailerDep
+) -> dict:
+    await auth_service.request_password_reset(session, mailer, email=data.email)
+    return {"status": "accepted"}
+
+
+@router.post("/reset-password", status_code=status.HTTP_204_NO_CONTENT)
+async def reset_password(data: PasswordResetConfirm, session: SessionDep) -> None:
+    await auth_service.reset_password(
+        session, raw_token=data.token, new_password=data.new_password
+    )

backend/app/api/v1/persons.py

@@ -0,0 +1,43 @@
+import uuid
+
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.person import PersonCreate, PersonRead
+from app.services import person_service, tree_service
+
+# Persons are nested under their tree (the tenant boundary).
+router = APIRouter(prefix="/trees", tags=["persons"])
+
+
+@router.post(
+    "/{tree_id}/persons",
+    response_model=PersonRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_person(
+    tree_id: uuid.UUID, data: PersonCreate, session: SessionDep, current: CurrentUser
+) -> PersonRead:
+    # get_tree enforces existence + view access; create_person enforces edit rights.
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    person = await person_service.create_person(
+        session,
+        actor=current,
+        tree=tree,
+        given=data.given,
+        surname=data.surname,
+        gender=data.gender,
+        is_living=data.is_living,
+        privacy_setting=data.privacy,
+        notes=data.notes,
+    )
+    return PersonRead.model_validate(person)
+
+
+@router.get("/{tree_id}/persons", response_model=list[PersonRead])
+async def list_persons(
+    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[PersonRead]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    persons = await person_service.list_persons(session, viewer_id=current.id, tree=tree)
+    return [PersonRead.model_validate(p) for p in persons]

backend/app/api/v1/trees.py

@@ -0,0 +1,33 @@
+import uuid
+
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.tree import TreeCreate, TreeRead
+from app.services import tree_service
+
+router = APIRouter(prefix="/trees", tags=["trees"])
+
+
+@router.post("", response_model=TreeRead, status_code=status.HTTP_201_CREATED)
+async def create_tree(data: TreeCreate, session: SessionDep, current: CurrentUser) -> TreeRead:
+    tree = await tree_service.create_tree(
+        session,
+        owner=current,
+        name=data.name,
+        description=data.description,
+        visibility=data.visibility,
+    )
+    return TreeRead.model_validate(tree)
+
+
+@router.get("", response_model=list[TreeRead])
+async def list_my_trees(session: SessionDep, current: CurrentUser) -> list[TreeRead]:
+    trees = await tree_service.list_trees_for_user(session, user=current)
+    return [TreeRead.model_validate(t) for t in trees]
+
+
+@router.get("/{tree_id}", response_model=TreeRead)
+async def get_tree(tree_id: uuid.UUID, session: SessionDep, current: CurrentUser) -> TreeRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    return TreeRead.model_validate(tree)

backend/app/api/v1/users.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from app.api.deps import CurrentUser
+from app.schemas.user import UserRead
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.get("/me", response_model=UserRead)
+async def read_me(current: CurrentUser) -> UserRead:
+    return UserRead.model_validate(current)

backend/app/core/config.py

@@ -27,6 +27,22 @@ class Settings(BaseSettings):
         default="postgresql+asyncpg://provenance:provenance@localhost:5432/provenance",
     )
 
+    # --- Auth / sessions ---
+    session_ttl_days: int = 30
+    token_ttl_hours: int = 24  # email-verify / password-reset token lifetime
+    cookie_name: str = "provenance_session"
+    cookie_secure: bool = True  # set false for local http; true behind TLS
+    # Base URL used to build links in outbound email.
+    app_base_url: str = "http://localhost"
+
+    # --- Email (SMTP) ---
+    mailer: str = Field(default="console", description="console | smtp")
+    smtp_host: str | None = None
+    smtp_port: int = 587
+    smtp_username: str | None = None
+    smtp_password: str | None = None
+    smtp_from: str = "Provenance <no-reply@provenance.local>"
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/core/db.py

@@ -1,22 +1,43 @@
-"""Async database engine.
+"""Async database engine, session factory, and the FastAPI session dependency.
 
-A single lazily-created async engine for the process. The repository layer
-(coming with the data model) will build sessions on top of this; for now it
-backs the readiness probe.
+The repository layer builds on ``get_session``; ``get_engine`` also backs the
+readiness probe. Everything is lazy so importing the app never opens a
+connection (important for tests and for ``--help``-style invocations).
 """
 
-from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from collections.abc import AsyncIterator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
 
 from app.core.config import get_settings
 
 _engine: AsyncEngine | None = None
+_sessionmaker: async_sessionmaker[AsyncSession] | None = None
 
 
 def get_engine() -> AsyncEngine:
     global _engine
     if _engine is None:
-        _engine = create_async_engine(
-            get_settings().database_url,
-            pool_pre_ping=True,
-        )
+        _engine = create_async_engine(get_settings().database_url, pool_pre_ping=True)
     return _engine
+
+
+def get_sessionmaker() -> async_sessionmaker[AsyncSession]:
+    global _sessionmaker
+    if _sessionmaker is None:
+        _sessionmaker = async_sessionmaker(
+            get_engine(), expire_on_commit=False, class_=AsyncSession
+        )
+    return _sessionmaker
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+    """FastAPI dependency. One session per request; commits are explicit in the
+    service layer."""
+    async with get_sessionmaker()() as session:
+        yield session

backend/app/core/security.py

@@ -0,0 +1,35 @@
+"""Password hashing and token primitives.
+
+Passwords use Argon2id (argon2-cffi). Session and email tokens are random
+high-entropy strings; only their SHA-256 hash is stored, so a database leak
+never exposes a usable credential.
+"""
+
+import hashlib
+import secrets
+
+from argon2 import PasswordHasher
+from argon2.exceptions import Argon2Error
+
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    return _hasher.hash(password)
+
+
+def verify_password(password_hash: str, password: str) -> bool:
+    try:
+        return _hasher.verify(password_hash, password)
+    except (Argon2Error, ValueError):
+        return False
+
+
+def generate_token() -> str:
+    """A URL-safe, high-entropy token (the raw secret handed to the client)."""
+    return secrets.token_urlsafe(32)
+
+
+def hash_token(token: str) -> str:
+    """SHA-256 of a token — what we store and look up by."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()

backend/app/integrations/auth/base.py

@@ -0,0 +1,24 @@
+"""AuthProvider interface.
+
+Operators enable any subset of providers (local, OIDC, social). A provider's
+job is narrow: verify a credential and return the matching User (or None).
+Session issuance, tokens, and registration live in the auth service and are
+provider-agnostic, so adding OIDC/social later (Phase 5) is additive.
+"""
+
+from abc import ABC, abstractmethod
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+
+
+class AuthProvider(ABC):
+    name: str
+
+    @abstractmethod
+    async def authenticate(
+        self, session: AsyncSession, *, identifier: str, secret: str
+    ) -> User | None:
+        """Return the User if the credential is valid, else None."""
+        raise NotImplementedError

backend/app/integrations/auth/local.py

@@ -0,0 +1,27 @@
+"""Local (email + password) auth provider."""
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.security import verify_password
+from app.integrations.auth.base import AuthProvider
+from app.models.user import User
+
+
+class LocalAuthProvider(AuthProvider):
+    name = "local"
+
+    async def authenticate(
+        self, session: AsyncSession, *, identifier: str, secret: str
+    ) -> User | None:
+        email = identifier.strip().lower()
+        user = (
+            await session.execute(
+                select(User).where(User.email == email, User.deleted_at.is_(None))
+            )
+        ).scalar_one_or_none()
+        if user is None or user.hashed_password is None:
+            return None
+        if not verify_password(user.hashed_password, secret):
+            return None
+        return user

backend/app/integrations/mailer/base.py

@@ -0,0 +1,16 @@
+"""Mailer interface for transactional email.
+
+Implementations: ConsoleMailer (dev default — logs the link) and SMTPMailer
+(operator-configured). Selected by config; resolved via app.api.deps.get_mailer.
+Real deployments will move sending to the worker; for now it is inline.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class Mailer(ABC):
+    @abstractmethod
+    async def send_email_verification(self, *, to: str, link: str) -> None: ...
+
+    @abstractmethod
+    async def send_password_reset(self, *, to: str, link: str) -> None: ...

backend/app/integrations/mailer/console.py

@@ -0,0 +1,16 @@
+"""Development mailer: logs the would-be email (including the action link) to
+stdout instead of sending. Never use in production."""
+
+import logging
+
+from app.integrations.mailer.base import Mailer
+
+logger = logging.getLogger("provenance.mailer")
+
+
+class ConsoleMailer(Mailer):
+    async def send_email_verification(self, *, to: str, link: str) -> None:
+        logger.info("[email] verify address for %s -> %s", to, link)
+
+    async def send_password_reset(self, *, to: str, link: str) -> None:
+        logger.info("[email] password reset for %s -> %s", to, link)

backend/app/integrations/mailer/smtp.py

@@ -0,0 +1,43 @@
+"""SMTP mailer using the standard library, run off the event loop. Configured
+entirely from settings (host/port/credentials/from)."""
+
+import asyncio
+import smtplib
+from email.message import EmailMessage
+
+from app.core.config import Settings
+from app.integrations.mailer.base import Mailer
+
+
+class SMTPMailer(Mailer):
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    def _send(self, *, to: str, subject: str, body: str) -> None:
+        msg = EmailMessage()
+        msg["From"] = self.settings.smtp_from
+        msg["To"] = to
+        msg["Subject"] = subject
+        msg.set_content(body)
+        with smtplib.SMTP(self.settings.smtp_host, self.settings.smtp_port) as smtp:
+            smtp.starttls()
+            if self.settings.smtp_username and self.settings.smtp_password:
+                smtp.login(self.settings.smtp_username, self.settings.smtp_password)
+            smtp.send_message(msg)
+
+    async def _send_async(self, *, to: str, subject: str, body: str) -> None:
+        await asyncio.to_thread(self._send, to=to, subject=subject, body=body)
+
+    async def send_email_verification(self, *, to: str, link: str) -> None:
+        await self._send_async(
+            to=to,
+            subject="Verify your Provenance email",
+            body=f"Confirm your email address:\n\n{link}\n",
+        )
+
+    async def send_password_reset(self, *, to: str, link: str) -> None:
+        await self._send_async(
+            to=to,
+            subject="Reset your Provenance password",
+            body=f"Reset your password:\n\n{link}\n",
+        )

backend/app/main.py

@@ -1,17 +1,51 @@
 """FastAPI application entrypoint.
 
-Thin by design: wire settings and routers, expose the OpenAPI contract. All
-domain logic lives in the service layer (added with the data model). The
-versioned API will mount under ``/api/v1``; health probes stay at the root.
+Thin by design: wire settings, routers, and error handling, and expose the
+OpenAPI contract. All domain logic lives in the service layer; the privacy
+engine is the single enforcement point for reads.
 """
 
-from fastapi import FastAPI
+import logging
+import sys
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
 
 from app.api.health import router as health_router
+from app.api.v1 import api_router
 from app.core.config import get_settings
+from app.services.exceptions import Conflict, Forbidden, NotFound
+
+
+def _configure_logging() -> None:
+    """Emit the app's own ``provenance.*`` logs at INFO to stdout (uvicorn only
+    configures its own loggers). The ConsoleMailer relies on this so self-hosters
+    can read verification/reset links from the logs."""
+    app_logger = logging.getLogger("provenance")
+    app_logger.setLevel(logging.INFO)
+    if not app_logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(logging.Formatter("%(levelname)s [%(name)s] %(message)s"))
+        app_logger.addHandler(handler)
+    app_logger.propagate = False
+
+
+def _register_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(NotFound)
+    async def _not_found(request: Request, exc: NotFound) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": str(exc) or "not found"})
+
+    @app.exception_handler(Forbidden)
+    async def _forbidden(request: Request, exc: Forbidden) -> JSONResponse:
+        return JSONResponse(status_code=403, content={"detail": str(exc) or "forbidden"})
+
+    @app.exception_handler(Conflict)
+    async def _conflict(request: Request, exc: Conflict) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc) or "conflict"})
 
 
 def create_app() -> FastAPI:
+    _configure_logging()
     settings = get_settings()
     app = FastAPI(
         title=settings.app_name,
@@ -19,6 +53,8 @@ def create_app() -> FastAPI:
         description="Provenance API — family and land provenance.",
     )
     app.include_router(health_router)
+    app.include_router(api_router)
+    _register_error_handlers(app)
     return app
 
 

backend/app/models/__init__.py

@@ -2,6 +2,7 @@
 and for ``create_all`` in tests."""
 
 from app.models.audit import AuditEntry
+from app.models.auth import Session, UserToken
 from app.models.base import Base
 from app.models.event import Event
 from app.models.person import Name, Person
@@ -25,4 +26,6 @@ __all__ = [
     "Source",
     "Citation",
     "AuditEntry",
+    "Session",
+    "UserToken",
 ]

backend/app/models/auth.py

@@ -0,0 +1,43 @@
+"""Authentication state: opaque backend-issued sessions and single-use email
+tokens. Only token *hashes* are stored (see app.core.security).
+"""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, func
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+from app.models.enums import TokenPurpose
+from app.models.mixins import UUIDPrimaryKey
+
+
+class Session(Base, UUIDPrimaryKey):
+    __tablename__ = "sessions"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), index=True
+    )
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class UserToken(Base, UUIDPrimaryKey):
+    __tablename__ = "user_tokens"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), index=True
+    )
+    purpose: Mapped[TokenPurpose] = mapped_column(SAEnum(TokenPurpose, name="token_purpose"))
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

backend/app/models/enums.py

@@ -55,3 +55,8 @@ class CitationConfidence(enum.StrEnum):
 class AuditActorType(enum.StrEnum):
     user = "user"
     assistant = "assistant"
+
+
+class TokenPurpose(enum.StrEnum):
+    email_verify = "email_verify"
+    password_reset = "password_reset"

backend/app/repositories/base.py

@@ -0,0 +1,40 @@
+"""Thin data-access layer over SQLAlchemy. No business rules live here — the
+service layer owns those (and the privacy engine). The repository only knows how
+to fetch and stage rows, transparently excluding soft-deleted ones.
+"""
+
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class BaseRepository:
+    def __init__(self, session: AsyncSession, model: type) -> None:
+        self.session = session
+        self.model = model
+
+    def _exclude_deleted(self, stmt):
+        if hasattr(self.model, "deleted_at"):
+            stmt = stmt.where(self.model.deleted_at.is_(None))
+        return stmt
+
+    async def get(self, id_: Any, *, include_deleted: bool = False):
+        stmt = select(self.model).where(self.model.id == id_)
+        if not include_deleted:
+            stmt = self._exclude_deleted(stmt)
+        return (await self.session.execute(stmt)).scalar_one_or_none()
+
+    async def list(self, *conditions, include_deleted: bool = False, order_by=None):
+        stmt = select(self.model)
+        for condition in conditions:
+            stmt = stmt.where(condition)
+        if not include_deleted:
+            stmt = self._exclude_deleted(stmt)
+        if order_by is not None:
+            stmt = stmt.order_by(order_by)
+        return list((await self.session.execute(stmt)).scalars().all())
+
+    def add(self, obj):
+        self.session.add(obj)
+        return obj

backend/app/schemas/auth.py

@@ -0,0 +1,35 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from app.schemas.user import UserRead
+
+
+class RegisterRequest(BaseModel):
+    email: str
+    password: str = Field(min_length=8)
+    display_name: str | None = None
+
+
+class LoginRequest(BaseModel):
+    email: str
+    password: str
+
+
+class TokenRequest(BaseModel):
+    token: str
+
+
+class PasswordResetRequest(BaseModel):
+    email: str
+
+
+class PasswordResetConfirm(BaseModel):
+    token: str
+    new_password: str = Field(min_length=8)
+
+
+class SessionRead(BaseModel):
+    user: UserRead
+    token: str
+    expires_at: datetime

backend/app/schemas/person.py

@@ -0,0 +1,27 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from app.models.enums import PersonPrivacy
+
+
+class PersonCreate(BaseModel):
+    given: str | None = None
+    surname: str | None = None
+    gender: str | None = None
+    is_living: bool | None = None
+    privacy: PersonPrivacy = PersonPrivacy.inherit
+    notes: str | None = None
+
+
+class PersonRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    tree_id: uuid.UUID
+    primary_name: str | None = None
+    gender: str | None
+    is_living: bool | None
+    privacy: PersonPrivacy
+    created_at: datetime

backend/app/schemas/tree.py

@@ -0,0 +1,23 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from app.models.enums import TreeVisibility
+
+
+class TreeCreate(BaseModel):
+    name: str
+    description: str | None = None
+    visibility: TreeVisibility = TreeVisibility.private
+
+
+class TreeRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    description: str | None
+    visibility: TreeVisibility
+    owner_id: uuid.UUID
+    created_at: datetime

backend/app/schemas/user.py

@@ -0,0 +1,22 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+# Note: email is a plain str for now (no email-validator dependency yet); the
+# auth slice can tighten this to EmailStr.
+
+
+class UserCreate(BaseModel):
+    email: str
+    display_name: str | None = None
+
+
+class UserRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    email: str
+    display_name: str | None
+    email_verified_at: datetime | None
+    created_at: datetime

backend/app/services/audit.py

@@ -0,0 +1,37 @@
+"""Audit logging. Every mutation records an append-only AuditEntry attributing
+the change to a User (or the assistant principal acting for a User). Staged on
+the session; the caller commits as part of its unit of work.
+"""
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.audit import AuditEntry
+from app.models.enums import AuditActorType
+
+
+def record_audit(
+    session: AsyncSession,
+    *,
+    action: str,
+    entity_type: str,
+    entity_id: uuid.UUID | None = None,
+    tree_id: uuid.UUID | None = None,
+    actor_user_id: uuid.UUID | None = None,
+    actor_type: AuditActorType = AuditActorType.user,
+    before: dict | None = None,
+    after: dict | None = None,
+) -> AuditEntry:
+    entry = AuditEntry(
+        action=action,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        tree_id=tree_id,
+        actor_user_id=actor_user_id,
+        actor_type=actor_type,
+        before=before,
+        after=after,
+    )
+    session.add(entry)
+    return entry

backend/app/services/auth_service.py

@@ -0,0 +1,201 @@
+"""Authentication service: registration, login, sessions, email verification,
+and password reset. Provider-agnostic — credential checking is delegated to an
+AuthProvider; this module owns session/token issuance and the audit trail.
+"""
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import get_settings
+from app.core.security import generate_token, hash_password, hash_token
+from app.integrations.auth.local import LocalAuthProvider
+from app.integrations.mailer.base import Mailer
+from app.models.auth import Session as SessionModel
+from app.models.auth import UserToken
+from app.models.enums import TokenPurpose
+from app.models.user import User
+from app.services.audit import record_audit
+from app.services.exceptions import Conflict, NotFound
+
+_local_provider = LocalAuthProvider()
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _link(path: str, raw: str) -> str:
+    return f"{get_settings().app_base_url}{path}?token={raw}"
+
+
+def _issue_session(session: AsyncSession, user: User) -> tuple[str, SessionModel]:
+    raw = generate_token()
+    record = SessionModel(
+        user_id=user.id,
+        token_hash=hash_token(raw),
+        expires_at=_now() + timedelta(days=get_settings().session_ttl_days),
+    )
+    session.add(record)
+    return raw, record
+
+
+def _create_email_token(session: AsyncSession, user: User, purpose: TokenPurpose) -> str:
+    raw = generate_token()
+    session.add(
+        UserToken(
+            user_id=user.id,
+            purpose=purpose,
+            token_hash=hash_token(raw),
+            expires_at=_now() + timedelta(hours=get_settings().token_ttl_hours),
+        )
+    )
+    return raw
+
+
+async def _consume_token(
+    session: AsyncSession, raw_token: str, purpose: TokenPurpose
+) -> UserToken:
+    token = (
+        await session.execute(
+            select(UserToken).where(
+                UserToken.token_hash == hash_token(raw_token),
+                UserToken.purpose == purpose,
+            )
+        )
+    ).scalar_one_or_none()
+    if token is None or token.used_at is not None or token.expires_at <= _now():
+        raise NotFound("invalid or expired token")
+    token.used_at = _now()
+    return token
+
+
+async def register(
+    session: AsyncSession,
+    mailer: Mailer,
+    *,
+    email: str,
+    password: str,
+    display_name: str | None = None,
+) -> tuple[User, str, datetime]:
+    email = email.strip().lower()
+    existing = (
+        await session.execute(select(User).where(User.email == email))
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise Conflict("email already registered")
+
+    user = User(email=email, display_name=display_name, hashed_password=hash_password(password))
+    session.add(user)
+    await session.flush()
+
+    verify_raw = _create_email_token(session, user, TokenPurpose.email_verify)
+    raw_token, record = _issue_session(session, user)
+    record_audit(
+        session,
+        action="register",
+        entity_type="User",
+        entity_id=user.id,
+        actor_user_id=user.id,
+        after={"email": email},
+    )
+    await session.commit()
+    await session.refresh(user)
+
+    await mailer.send_email_verification(to=email, link=_link("/auth/verify-email", verify_raw))
+    return user, raw_token, record.expires_at
+
+
+async def login(
+    session: AsyncSession, *, email: str, password: str
+) -> tuple[User, str, datetime] | None:
+    user = await _local_provider.authenticate(session, identifier=email, secret=password)
+    if user is None:
+        return None
+    raw_token, record = _issue_session(session, user)
+    record_audit(
+        session, action="login", entity_type="User", entity_id=user.id, actor_user_id=user.id
+    )
+    await session.commit()
+    return user, raw_token, record.expires_at
+
+
+async def logout(session: AsyncSession, *, raw_token: str) -> None:
+    await session.execute(
+        update(SessionModel)
+        .where(
+            SessionModel.token_hash == hash_token(raw_token),
+            SessionModel.revoked_at.is_(None),
+        )
+        .values(revoked_at=_now())
+    )
+    await session.commit()
+
+
+async def resolve_session_user(session: AsyncSession, *, raw_token: str) -> User | None:
+    record = (
+        await session.execute(
+            select(SessionModel).where(SessionModel.token_hash == hash_token(raw_token))
+        )
+    ).scalar_one_or_none()
+    if record is None or record.revoked_at is not None or record.expires_at <= _now():
+        return None
+    return (
+        await session.execute(
+            select(User).where(User.id == record.user_id, User.deleted_at.is_(None))
+        )
+    ).scalar_one_or_none()
+
+
+async def verify_email(session: AsyncSession, *, raw_token: str) -> None:
+    token = await _consume_token(session, raw_token, TokenPurpose.email_verify)
+    await session.execute(
+        update(User).where(User.id == token.user_id).values(email_verified_at=_now())
+    )
+    record_audit(
+        session,
+        action="verify_email",
+        entity_type="User",
+        entity_id=token.user_id,
+        actor_user_id=token.user_id,
+    )
+    await session.commit()
+
+
+async def request_password_reset(session: AsyncSession, mailer: Mailer, *, email: str) -> None:
+    email = email.strip().lower()
+    user = (
+        await session.execute(
+            select(User).where(User.email == email, User.deleted_at.is_(None))
+        )
+    ).scalar_one_or_none()
+    # Always succeed to avoid leaking which emails are registered.
+    if user is None:
+        return
+    raw = _create_email_token(session, user, TokenPurpose.password_reset)
+    await session.commit()
+    await mailer.send_password_reset(to=email, link=_link("/auth/reset-password", raw))
+
+
+async def reset_password(session: AsyncSession, *, raw_token: str, new_password: str) -> None:
+    token = await _consume_token(session, raw_token, TokenPurpose.password_reset)
+    await session.execute(
+        update(User)
+        .where(User.id == token.user_id)
+        .values(hashed_password=hash_password(new_password))
+    )
+    # Revoke all existing sessions — a reset invalidates prior logins.
+    await session.execute(
+        update(SessionModel)
+        .where(SessionModel.user_id == token.user_id, SessionModel.revoked_at.is_(None))
+        .values(revoked_at=_now())
+    )
+    record_audit(
+        session,
+        action="reset_password",
+        entity_type="User",
+        entity_id=token.user_id,
+        actor_user_id=token.user_id,
+    )
+    await session.commit()

backend/app/services/exceptions.py

@@ -0,0 +1,18 @@
+"""Domain errors. The API layer maps these to HTTP status codes so services
+stay transport-agnostic."""
+
+
+class DomainError(Exception):
+    """Base for domain-level errors."""
+
+
+class NotFound(DomainError):
+    """Requested entity does not exist (or is soft-deleted / not visible)."""
+
+
+class Forbidden(DomainError):
+    """Caller lacks the required role for this action."""
+
+
+class Conflict(DomainError):
+    """Operation conflicts with current state (e.g. duplicate email)."""

backend/app/services/person_service.py

@@ -0,0 +1,113 @@
+"""Person service. Writes require editor rights on the tree; reads run every
+person through the privacy engine. Each returned Person gets a transient
+``primary_name`` for display (not persisted).
+"""
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import PersonPrivacy
+from app.models.person import Name, Person
+from app.models.tree import Tree
+from app.models.user import User
+from app.services import privacy
+from app.services.audit import record_audit
+from app.services.exceptions import Forbidden
+from app.services.privacy import Visibility
+
+
+def _format_name(name: Name) -> str | None:
+    parts = [name.given, name.surname]
+    joined = " ".join(p for p in parts if p)
+    return joined or name.display_name
+
+
+async def _attach_primary_name(session: AsyncSession, person: Person) -> None:
+    stmt = (
+        select(Name)
+        .where(Name.person_id == person.id, Name.deleted_at.is_(None))
+        .order_by(Name.is_primary.desc(), Name.sort_order)
+    )
+    name = (await session.execute(stmt)).scalars().first()
+    # Transient display attribute consumed by the PersonRead schema.
+    person.primary_name = _format_name(name) if name is not None else None
+
+
+async def create_person(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    given: str | None = None,
+    surname: str | None = None,
+    gender: str | None = None,
+    is_living: bool | None = None,
+    privacy_setting: PersonPrivacy = PersonPrivacy.inherit,
+    notes: str | None = None,
+) -> Person:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+
+    person = Person(
+        tree_id=tree.id,
+        gender=gender,
+        is_living=is_living,
+        privacy=privacy_setting,
+        notes=notes,
+    )
+    session.add(person)
+    await session.flush()  # assign person.id
+
+    if given or surname:
+        session.add(
+            Name(
+                tree_id=tree.id,
+                person_id=person.id,
+                name_type="birth",
+                given=given,
+                surname=surname,
+                is_primary=True,
+            )
+        )
+    record_audit(
+        session,
+        action="create",
+        entity_type="Person",
+        entity_id=person.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"given": given, "surname": surname},
+    )
+    await session.commit()
+    await session.refresh(person)
+    await _attach_primary_name(session, person)
+    return person
+
+
+async def list_persons(
+    session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree
+) -> list[Person]:
+    if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
+        raise Forbidden("not permitted to view this tree")
+
+    stmt = (
+        select(Person)
+        .where(Person.tree_id == tree.id, Person.deleted_at.is_(None))
+        .order_by(Person.created_at)
+    )
+    persons = list((await session.execute(stmt)).scalars().all())
+
+    visible: list[Person] = []
+    for person in persons:
+        if (
+            await privacy.person_visibility(
+                session, user_id=viewer_id, tree=tree, person=person
+            )
+            == Visibility.hidden
+        ):
+            continue
+        await _attach_primary_name(session, person)
+        visible.append(person)
+    return visible

backend/app/services/privacy.py

@@ -0,0 +1,62 @@
+"""The privacy engine — the single enforcement point for visibility.
+
+INVARIANT (CLAUDE.md #2): every read path resolves visibility here. Do not add a
+query path that returns rows to a caller without first passing through this
+module. Effective visibility is a function of the viewer's role on the tree, the
+tree's visibility, the per-person override, and (Phase 2) living-person status.
+"""
+
+import enum
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import MembershipRole, PersonPrivacy, TreeVisibility
+from app.models.person import Person
+from app.models.tree import Tree, TreeMembership
+
+
+class Visibility(enum.StrEnum):
+    full = "full"
+    redacted = "redacted"
+    hidden = "hidden"
+
+
+async def get_membership_role(
+    session: AsyncSession, user_id: uuid.UUID | None, tree_id: uuid.UUID
+) -> MembershipRole | None:
+    if user_id is None:
+        return None
+    stmt = select(TreeMembership.role).where(
+        TreeMembership.tree_id == tree_id,
+        TreeMembership.user_id == user_id,
+    )
+    return (await session.execute(stmt)).scalar_one_or_none()
+
+
+async def can_view_tree(session: AsyncSession, *, user_id: uuid.UUID | None, tree: Tree) -> bool:
+    if tree.deleted_at is not None:
+        return False
+    if await get_membership_role(session, user_id, tree.id) is not None:
+        return True
+    return tree.visibility in (TreeVisibility.public, TreeVisibility.unlisted)
+
+
+async def can_edit_tree(session: AsyncSession, *, user_id: uuid.UUID | None, tree: Tree) -> bool:
+    role = await get_membership_role(session, user_id, tree.id)
+    return role in (MembershipRole.owner, MembershipRole.editor)
+
+
+async def person_visibility(
+    session: AsyncSession, *, user_id: uuid.UUID | None, tree: Tree, person: Person
+) -> Visibility:
+    if not await can_view_tree(session, user_id=user_id, tree=tree):
+        return Visibility.hidden
+    if await get_membership_role(session, user_id, tree.id) is not None:
+        return Visibility.full
+    # Non-member viewing a public/unlisted tree:
+    if person.privacy == PersonPrivacy.private:
+        return Visibility.hidden
+    # TODO(Phase 2): redact living people for non-members (ARCHITECTURE §6).
+    return Visibility.full

backend/app/services/tree_service.py

@@ -0,0 +1,61 @@
+"""Tree service. Creating a tree also creates the owner's TreeMembership (the
+authorization basis) and an audit entry. Reads go through the privacy engine.
+"""
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import MembershipRole, TreeVisibility
+from app.models.tree import Tree, TreeMembership
+from app.models.user import User
+from app.repositories.base import BaseRepository
+from app.services import privacy
+from app.services.audit import record_audit
+from app.services.exceptions import Forbidden, NotFound
+
+
+async def create_tree(
+    session: AsyncSession,
+    *,
+    owner: User,
+    name: str,
+    description: str | None = None,
+    visibility: TreeVisibility = TreeVisibility.private,
+) -> Tree:
+    tree = Tree(owner_id=owner.id, name=name, description=description, visibility=visibility)
+    session.add(tree)
+    await session.flush()  # assign tree.id
+    session.add(TreeMembership(tree_id=tree.id, user_id=owner.id, role=MembershipRole.owner))
+    record_audit(
+        session,
+        action="create",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=owner.id,
+        after={"name": name, "visibility": visibility.value},
+    )
+    await session.commit()
+    await session.refresh(tree)
+    return tree
+
+
+async def list_trees_for_user(session: AsyncSession, *, user: User) -> list[Tree]:
+    stmt = (
+        select(Tree)
+        .join(TreeMembership, TreeMembership.tree_id == Tree.id)
+        .where(TreeMembership.user_id == user.id, Tree.deleted_at.is_(None))
+        .order_by(Tree.created_at)
+    )
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def get_tree(session: AsyncSession, *, viewer_id: uuid.UUID, tree_id: uuid.UUID) -> Tree:
+    tree = await BaseRepository(session, Tree).get(tree_id)
+    if tree is None:
+        raise NotFound("tree not found")
+    if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
+        raise Forbidden("not permitted to view this tree")
+    return tree

backend/app/services/user_service.py

@@ -0,0 +1,44 @@
+"""User service. Account creation here is a temporary, open dev bootstrap so we
+can create tree owners before the auth slice exists; the auth slice replaces it
+with the AuthProvider (password/OIDC/social) and proper verification.
+"""
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+from app.repositories.base import BaseRepository
+from app.services.audit import record_audit
+from app.services.exceptions import Conflict
+
+
+async def create_user(
+    session: AsyncSession, *, email: str, display_name: str | None = None
+) -> User:
+    email = email.strip().lower()
+    existing = (
+        await session.execute(select(User).where(User.email == email))
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise Conflict("email already registered")
+
+    user = User(email=email, display_name=display_name)
+    session.add(user)
+    await session.flush()  # assign user.id
+    record_audit(
+        session,
+        action="create",
+        entity_type="User",
+        entity_id=user.id,
+        actor_user_id=user.id,
+        after={"email": email},
+    )
+    await session.commit()
+    await session.refresh(user)
+    return user
+
+
+async def get_user(session: AsyncSession, user_id: uuid.UUID) -> User | None:
+    return await BaseRepository(session, User).get(user_id)

backend/migrations/versions/1f6e54f6406a_auth_sessions_and_tokens.py

@@ -0,0 +1,62 @@
+"""auth sessions and tokens
+
+Revision ID: 1f6e54f6406a
+Revises: ec43c338e155
+Create Date: 2026-06-06 10:47:06.454748
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '1f6e54f6406a'
+down_revision: str | None = 'ec43c338e155'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('sessions',
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('token_hash', sa.String(length=64), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_sessions_user_id_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_sessions'))
+    )
+    op.create_index(op.f('ix_sessions_token_hash'), 'sessions', ['token_hash'], unique=True)
+    op.create_index(op.f('ix_sessions_user_id'), 'sessions', ['user_id'], unique=False)
+    op.create_table('user_tokens',
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('purpose', sa.Enum('email_verify', 'password_reset', name='token_purpose'), nullable=False),
+    sa.Column('token_hash', sa.String(length=64), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('used_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_user_tokens_user_id_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_user_tokens'))
+    )
+    op.create_index(op.f('ix_user_tokens_token_hash'), 'user_tokens', ['token_hash'], unique=True)
+    op.create_index(op.f('ix_user_tokens_user_id'), 'user_tokens', ['user_id'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_user_tokens_user_id'), table_name='user_tokens')
+    op.drop_index(op.f('ix_user_tokens_token_hash'), table_name='user_tokens')
+    op.drop_table('user_tokens')
+    op.drop_index(op.f('ix_sessions_user_id'), table_name='sessions')
+    op.drop_index(op.f('ix_sessions_token_hash'), table_name='sessions')
+    op.drop_table('sessions')
+    # ### end Alembic commands ###
+
+    # Enum type created implicitly by create_table(); drop it for reversibility.
+    op.execute("DROP TYPE IF EXISTS token_purpose")

backend/pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "sqlalchemy[asyncio]>=2.0",
     "asyncpg>=0.30",
     "alembic>=1.14",
+    "argon2-cffi>=23.1",
 ]
 
 [dependency-groups]

backend/tests/conftest.py

@@ -0,0 +1,89 @@
+"""Test fixtures.
+
+DB-backed tests require ``TEST_DATABASE_URL`` (an async URL to a *disposable*
+Postgres); without it they skip, so the no-DB unit suite still runs anywhere.
+The schema is built from the models via ``create_all`` and dropped per test for
+isolation. A capturing mailer replaces the real one so email flows are testable.
+"""
+
+import os
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+import app.models  # noqa: F401 — register all models on Base.metadata
+from app.api.deps import get_mailer
+from app.core.db import get_session
+from app.integrations.mailer.base import Mailer
+from app.main import app
+from app.models import Base
+
+TEST_DATABASE_URL = os.getenv("TEST_DATABASE_URL")
+
+
+class CapturingMailer(Mailer):
+    def __init__(self) -> None:
+        self.verifications: list[tuple[str, str]] = []
+        self.resets: list[tuple[str, str]] = []
+
+    async def send_email_verification(self, *, to: str, link: str) -> None:
+        self.verifications.append((to, link))
+
+    async def send_password_reset(self, *, to: str, link: str) -> None:
+        self.resets.append((to, link))
+
+
+_mailer = CapturingMailer()
+
+
+@pytest.fixture
+def mailer() -> CapturingMailer:
+    return _mailer
+
+
+@pytest_asyncio.fixture
+async def client():
+    if not TEST_DATABASE_URL:
+        pytest.skip("TEST_DATABASE_URL not set")
+
+    engine = create_async_engine(TEST_DATABASE_URL)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+        await conn.run_sync(Base.metadata.create_all)
+
+    sessionmaker = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+
+    async def _override_session():
+        async with sessionmaker() as session:
+            yield session
+
+    _mailer.verifications.clear()
+    _mailer.resets.clear()
+    app.dependency_overrides[get_session] = _override_session
+    app.dependency_overrides[get_mailer] = lambda: _mailer
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as http_client:
+        yield http_client
+
+    app.dependency_overrides.clear()
+    await engine.dispose()
+
+
+def token_from_link(link: str) -> str:
+    return link.split("token=", 1)[1]
+
+
+async def register(client, email: str, password: str = "password123") -> str:
+    """Register a user and return their bearer session token."""
+    resp = await client.post(
+        "/api/v1/auth/register", json={"email": email, "password": password}
+    )
+    assert resp.status_code == 201, resp.text
+    return resp.json()["token"]
+
+
+def auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}

backend/tests/test_auth.py

@@ -0,0 +1,106 @@
+"""Auth flows: registration, login, email verification, password reset, logout."""
+
+from tests.conftest import auth, register, token_from_link
+
+
+async def test_register_issues_session_and_verification_email(client, mailer):
+    resp = await client.post(
+        "/api/v1/auth/register",
+        json={"email": "new@example.com", "password": "password123", "display_name": "New"},
+    )
+    assert resp.status_code == 201, resp.text
+    body = resp.json()
+    assert body["token"]
+    assert body["user"]["email"] == "new@example.com"
+    assert body["user"]["email_verified_at"] is None
+    # A verification email was "sent".
+    assert len(mailer.verifications) == 1
+    assert mailer.verifications[0][0] == "new@example.com"
+
+
+async def test_duplicate_email_conflicts(client):
+    await register(client, "dupe@example.com")
+    resp = await client.post(
+        "/api/v1/auth/register", json={"email": "dupe@example.com", "password": "password123"}
+    )
+    assert resp.status_code == 409
+
+
+async def test_login_wrong_password_rejected(client):
+    await register(client, "user@example.com", password="password123")
+    resp = await client.post(
+        "/api/v1/auth/login", json={"email": "user@example.com", "password": "wrong-password"}
+    )
+    assert resp.status_code == 401
+
+
+async def test_login_succeeds_and_me_returns_user(client):
+    await register(client, "user2@example.com", password="password123")
+    resp = await client.post(
+        "/api/v1/auth/login", json={"email": "user2@example.com", "password": "password123"}
+    )
+    assert resp.status_code == 200
+    token = resp.json()["token"]
+    resp = await client.get("/api/v1/users/me", headers=auth(token))
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "user2@example.com"
+
+
+async def test_email_verification(client, mailer):
+    await register(client, "verify@example.com")
+    token = token_from_link(mailer.verifications[0][1])
+    resp = await client.post("/api/v1/auth/verify-email", json={"token": token})
+    assert resp.status_code == 204
+
+    # Logging in and checking /me shows the address is now verified.
+    login = await client.post(
+        "/api/v1/auth/login", json={"email": "verify@example.com", "password": "password123"}
+    )
+    me = await client.get("/api/v1/users/me", headers=auth(login.json()["token"]))
+    assert me.json()["email_verified_at"] is not None
+
+
+async def test_password_reset_flow_revokes_old_sessions(client, mailer):
+    old_token = await register(client, "reset@example.com", password="password123")
+
+    resp = await client.post(
+        "/api/v1/auth/request-password-reset", json={"email": "reset@example.com"}
+    )
+    assert resp.status_code == 202
+    reset_token = token_from_link(mailer.resets[0][1])
+
+    resp = await client.post(
+        "/api/v1/auth/reset-password",
+        json={"token": reset_token, "new_password": "new-password456"},
+    )
+    assert resp.status_code == 204
+
+    # Old session is revoked.
+    assert (await client.get("/api/v1/users/me", headers=auth(old_token))).status_code == 401
+    # Old password no longer works; new one does.
+    assert (
+        await client.post(
+            "/api/v1/auth/login", json={"email": "reset@example.com", "password": "password123"}
+        )
+    ).status_code == 401
+    assert (
+        await client.post(
+            "/api/v1/auth/login",
+            json={"email": "reset@example.com", "password": "new-password456"},
+        )
+    ).status_code == 200
+
+
+async def test_request_password_reset_unknown_email_still_accepted(client, mailer):
+    resp = await client.post(
+        "/api/v1/auth/request-password-reset", json={"email": "nobody@example.com"}
+    )
+    assert resp.status_code == 202
+    assert len(mailer.resets) == 0  # no email sent, but no enumeration either
+
+
+async def test_logout_revokes_session(client):
+    token = await register(client, "logout@example.com")
+    assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 200
+    assert (await client.post("/api/v1/auth/logout", headers=auth(token))).status_code == 204
+    assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 401

backend/tests/test_core_api.py

@@ -0,0 +1,73 @@
+"""End-to-end coverage of the core data model through the API: tenancy, the
+privacy seam, and real session auth."""
+
+from tests.conftest import auth, register
+
+
+async def test_tree_and_person_flow(client):
+    token = await register(client, "keeper@example.com")
+
+    resp = await client.post(
+        "/api/v1/trees",
+        json={"name": "Smith Family", "visibility": "private"},
+        headers=auth(token),
+    )
+    assert resp.status_code == 201, resp.text
+    tree = resp.json()
+    assert tree["visibility"] == "private"
+    tree_id = tree["id"]
+
+    resp = await client.get("/api/v1/trees", headers=auth(token))
+    assert resp.status_code == 200
+    assert len(resp.json()) == 1
+
+    resp = await client.post(
+        f"/api/v1/trees/{tree_id}/persons",
+        json={"given": "John", "surname": "Smith"},
+        headers=auth(token),
+    )
+    assert resp.status_code == 201, resp.text
+    person = resp.json()
+    assert person["primary_name"] == "John Smith"
+    assert person["tree_id"] == tree_id
+
+    resp = await client.get(f"/api/v1/trees/{tree_id}/persons", headers=auth(token))
+    assert resp.status_code == 200
+    assert len(resp.json()) == 1
+
+
+async def test_private_tree_isolated_from_other_users(client):
+    owner = await register(client, "owner@example.com")
+    other = await register(client, "stranger@example.com")
+
+    resp = await client.post(
+        "/api/v1/trees", json={"name": "Private", "visibility": "private"}, headers=auth(owner)
+    )
+    tree_id = resp.json()["id"]
+
+    resp = await client.get(f"/api/v1/trees/{tree_id}", headers=auth(other))
+    assert resp.status_code == 403
+    resp = await client.get(f"/api/v1/trees/{tree_id}/persons", headers=auth(other))
+    assert resp.status_code == 403
+
+
+async def test_public_tree_viewable_but_not_editable_by_non_member(client):
+    owner = await register(client, "owner2@example.com")
+    viewer = await register(client, "viewer2@example.com")
+
+    resp = await client.post(
+        "/api/v1/trees", json={"name": "Public", "visibility": "public"}, headers=auth(owner)
+    )
+    tree_id = resp.json()["id"]
+
+    resp = await client.get(f"/api/v1/trees/{tree_id}", headers=auth(viewer))
+    assert resp.status_code == 200
+    resp = await client.post(
+        f"/api/v1/trees/{tree_id}/persons", json={"given": "Nope"}, headers=auth(viewer)
+    )
+    assert resp.status_code == 403
+
+
+async def test_auth_required_without_token(client):
+    resp = await client.get("/api/v1/trees")
+    assert resp.status_code == 401

backend/uv.lock

@@ -1,6 +1,10 @@
 version = 1
 revision = 3
 requires-python = ">=3.13"
+resolution-markers = [
+    "python_full_version >= '3.14'",
+    "python_full_version < '3.14'",
+]
 
 [[package]]
 name = "alembic"
@@ -46,6 +50,49 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" },
 ]
 
+[[package]]
+name = "argon2-cffi"
+version = "25.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "argon2-cffi-bindings" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0e/89/ce5af8a7d472a67cc819d5d998aa8c82c5d860608c4db9f46f1162d7dab9/argon2_cffi-25.1.0.tar.gz", hash = "sha256:694ae5cc8a42f4c4e2bf2ca0e64e51e23a040c6a517a85074683d3959e1346c1", size = 45706, upload-time = "2025-06-03T06:55:32.073Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4f/d3/a8b22fa575b297cd6e3e3b0155c7e25db170edf1c74783d6a31a2490b8d9/argon2_cffi-25.1.0-py3-none-any.whl", hash = "sha256:fdc8b074db390fccb6eb4a3604ae7231f219aa669a2652e0f20e16ba513d5741", size = 14657, upload-time = "2025-06-03T06:55:30.804Z" },
+]
+
+[[package]]
+name = "argon2-cffi-bindings"
+version = "25.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5c/2d/db8af0df73c1cf454f71b2bbe5e356b8c1f8041c979f505b3d3186e520a9/argon2_cffi_bindings-25.1.0.tar.gz", hash = "sha256:b957f3e6ea4d55d820e40ff76f450952807013d361a65d7f28acc0acbf29229d", size = 1783441, upload-time = "2025-07-30T10:02:05.147Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/97/3c0a35f46e52108d4707c44b95cfe2afcafc50800b5450c197454569b776/argon2_cffi_bindings-25.1.0-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:3d3f05610594151994ca9ccb3c771115bdb4daef161976a266f0dd8aa9996b8f", size = 54393, upload-time = "2025-07-30T10:01:40.97Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/f4/98bbd6ee89febd4f212696f13c03ca302b8552e7dbf9c8efa11ea4a388c3/argon2_cffi_bindings-25.1.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:8b8efee945193e667a396cbc7b4fb7d357297d6234d30a489905d96caabde56b", size = 29328, upload-time = "2025-07-30T10:01:41.916Z" },
+    { url = "https://files.pythonhosted.org/packages/43/24/90a01c0ef12ac91a6be05969f29944643bc1e5e461155ae6559befa8f00b/argon2_cffi_bindings-25.1.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:3c6702abc36bf3ccba3f802b799505def420a1b7039862014a65db3205967f5a", size = 31269, upload-time = "2025-07-30T10:01:42.716Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/d3/942aa10782b2697eee7af5e12eeff5ebb325ccfb86dd8abda54174e377e4/argon2_cffi_bindings-25.1.0-cp314-cp314t-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a1c70058c6ab1e352304ac7e3b52554daadacd8d453c1752e547c76e9c99ac44", size = 86558, upload-time = "2025-07-30T10:01:43.943Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/82/b484f702fec5536e71836fc2dbc8c5267b3f6e78d2d539b4eaa6f0db8bf8/argon2_cffi_bindings-25.1.0-cp314-cp314t-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e2fd3bfbff3c5d74fef31a722f729bf93500910db650c925c2d6ef879a7e51cb", size = 92364, upload-time = "2025-07-30T10:01:44.887Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/c1/a606ff83b3f1735f3759ad0f2cd9e038a0ad11a3de3b6c673aa41c24bb7b/argon2_cffi_bindings-25.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c4f9665de60b1b0e99bcd6be4f17d90339698ce954cfd8d9cf4f91c995165a92", size = 85637, upload-time = "2025-07-30T10:01:46.225Z" },
+    { url = "https://files.pythonhosted.org/packages/44/b4/678503f12aceb0262f84fa201f6027ed77d71c5019ae03b399b97caa2f19/argon2_cffi_bindings-25.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ba92837e4a9aa6a508c8d2d7883ed5a8f6c308c89a4790e1e447a220deb79a85", size = 91934, upload-time = "2025-07-30T10:01:47.203Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/c7/f36bd08ef9bd9f0a9cff9428406651f5937ce27b6c5b07b92d41f91ae541/argon2_cffi_bindings-25.1.0-cp314-cp314t-win32.whl", hash = "sha256:84a461d4d84ae1295871329b346a97f68eade8c53b6ed9a7ca2d7467f3c8ff6f", size = 28158, upload-time = "2025-07-30T10:01:48.341Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/80/0106a7448abb24a2c467bf7d527fe5413b7fdfa4ad6d6a96a43a62ef3988/argon2_cffi_bindings-25.1.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b55aec3565b65f56455eebc9b9f34130440404f27fe21c3b375bf1ea4d8fbae6", size = 32597, upload-time = "2025-07-30T10:01:49.112Z" },
+    { url = "https://files.pythonhosted.org/packages/05/b8/d663c9caea07e9180b2cb662772865230715cbd573ba3b5e81793d580316/argon2_cffi_bindings-25.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:87c33a52407e4c41f3b70a9c2d3f6056d88b10dad7695be708c5021673f55623", size = 28231, upload-time = "2025-07-30T10:01:49.92Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/57/96b8b9f93166147826da5f90376e784a10582dd39a393c99bb62cfcf52f0/argon2_cffi_bindings-25.1.0-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:aecba1723ae35330a008418a91ea6cfcedf6d31e5fbaa056a166462ff066d500", size = 54121, upload-time = "2025-07-30T10:01:50.815Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/08/a9bebdb2e0e602dde230bdde8021b29f71f7841bd54801bcfd514acb5dcf/argon2_cffi_bindings-25.1.0-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:2630b6240b495dfab90aebe159ff784d08ea999aa4b0d17efa734055a07d2f44", size = 29177, upload-time = "2025-07-30T10:01:51.681Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/02/d297943bcacf05e4f2a94ab6f462831dc20158614e5d067c35d4e63b9acb/argon2_cffi_bindings-25.1.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:7aef0c91e2c0fbca6fc68e7555aa60ef7008a739cbe045541e438373bc54d2b0", size = 31090, upload-time = "2025-07-30T10:01:53.184Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/93/44365f3d75053e53893ec6d733e4a5e3147502663554b4d864587c7828a7/argon2_cffi_bindings-25.1.0-cp39-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1e021e87faa76ae0d413b619fe2b65ab9a037f24c60a1e6cc43457ae20de6dc6", size = 81246, upload-time = "2025-07-30T10:01:54.145Z" },
+    { url = "https://files.pythonhosted.org/packages/09/52/94108adfdd6e2ddf58be64f959a0b9c7d4ef2fa71086c38356d22dc501ea/argon2_cffi_bindings-25.1.0-cp39-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d3e924cfc503018a714f94a49a149fdc0b644eaead5d1f089330399134fa028a", size = 87126, upload-time = "2025-07-30T10:01:55.074Z" },
+    { url = "https://files.pythonhosted.org/packages/72/70/7a2993a12b0ffa2a9271259b79cc616e2389ed1a4d93842fac5a1f923ffd/argon2_cffi_bindings-25.1.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:c87b72589133f0346a1cb8d5ecca4b933e3c9b64656c9d175270a000e73b288d", size = 80343, upload-time = "2025-07-30T10:01:56.007Z" },
+    { url = "https://files.pythonhosted.org/packages/78/9a/4e5157d893ffc712b74dbd868c7f62365618266982b64accab26bab01edc/argon2_cffi_bindings-25.1.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:1db89609c06afa1a214a69a462ea741cf735b29a57530478c06eb81dd403de99", size = 86777, upload-time = "2025-07-30T10:01:56.943Z" },
+    { url = "https://files.pythonhosted.org/packages/74/cd/15777dfde1c29d96de7f18edf4cc94c385646852e7c7b0320aa91ccca583/argon2_cffi_bindings-25.1.0-cp39-abi3-win32.whl", hash = "sha256:473bcb5f82924b1becbb637b63303ec8d10e84c8d241119419897a26116515d2", size = 27180, upload-time = "2025-07-30T10:01:57.759Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/c6/a759ece8f1829d1f162261226fbfd2c6832b3ff7657384045286d2afa384/argon2_cffi_bindings-25.1.0-cp39-abi3-win_amd64.whl", hash = "sha256:a98cd7d17e9f7ce244c0803cad3c23a7d379c301ba618a5fa76a67d116618b98", size = 31715, upload-time = "2025-07-30T10:01:58.56Z" },
+    { url = "https://files.pythonhosted.org/packages/42/b9/f8d6fa329ab25128b7e98fd83a3cb34d9db5b059a9847eddb840a0af45dd/argon2_cffi_bindings-25.1.0-cp39-abi3-win_arm64.whl", hash = "sha256:b0fdbcf513833809c882823f98dc2f931cf659d9a1429616ac3adebb49f5db94", size = 27149, upload-time = "2025-07-30T10:01:59.329Z" },
+]
+
 [[package]]
 name = "asyncpg"
 version = "0.31.0"
@@ -87,6 +134,51 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/59/8c/57e832b7af6d7c5abe66eb3fbe3a3a32f4d11ea23a1aa7131371035be991/certifi-2026.5.20-py3-none-any.whl", hash = "sha256:3c52e209ba0a4ad7aebe60436a4ab349c39e1e602e8c134221e546902ad25897", size = 134134, upload-time = "2026-05-20T11:46:48.578Z" },
 ]
 
+[[package]]
+name = "cffi"
+version = "2.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pycparser", marker = "implementation_name != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" },
+    { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" },
+    { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" },
+    { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" },
+    { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" },
+    { url = "https://files.pythonhosted.org/packages/92/c4/3ce07396253a83250ee98564f8d7e9789fab8e58858f35d07a9a2c78de9f/cffi-2.0.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:fc33c5141b55ed366cfaad382df24fe7dcbc686de5be719b207bb248e3053dc5", size = 185320, upload-time = "2025-09-08T23:23:18.087Z" },
+    { url = "https://files.pythonhosted.org/packages/59/dd/27e9fa567a23931c838c6b02d0764611c62290062a6d4e8ff7863daf9730/cffi-2.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c654de545946e0db659b3400168c9ad31b5d29593291482c43e3564effbcee13", size = 181487, upload-time = "2025-09-08T23:23:19.622Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/43/0e822876f87ea8a4ef95442c3d766a06a51fc5298823f884ef87aaad168c/cffi-2.0.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:24b6f81f1983e6df8db3adc38562c83f7d4a0c36162885ec7f7b77c7dcbec97b", size = 220049, upload-time = "2025-09-08T23:23:20.853Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/89/76799151d9c2d2d1ead63c2429da9ea9d7aac304603de0c6e8764e6e8e70/cffi-2.0.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:12873ca6cb9b0f0d3a0da705d6086fe911591737a59f28b7936bdfed27c0d47c", size = 207793, upload-time = "2025-09-08T23:23:22.08Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/dd/3465b14bb9e24ee24cb88c9e3730f6de63111fffe513492bf8c808a3547e/cffi-2.0.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:d9b97165e8aed9272a6bb17c01e3cc5871a594a446ebedc996e2397a1c1ea8ef", size = 206300, upload-time = "2025-09-08T23:23:23.314Z" },
+    { url = "https://files.pythonhosted.org/packages/47/d9/d83e293854571c877a92da46fdec39158f8d7e68da75bf73581225d28e90/cffi-2.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:afb8db5439b81cf9c9d0c80404b60c3cc9c3add93e114dcae767f1477cb53775", size = 219244, upload-time = "2025-09-08T23:23:24.541Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/0f/1f177e3683aead2bb00f7679a16451d302c436b5cbf2505f0ea8146ef59e/cffi-2.0.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:737fe7d37e1a1bffe70bd5754ea763a62a066dc5913ca57e957824b72a85e205", size = 222828, upload-time = "2025-09-08T23:23:26.143Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/0f/cafacebd4b040e3119dcb32fed8bdef8dfe94da653155f9d0b9dc660166e/cffi-2.0.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:38100abb9d1b1435bc4cc340bb4489635dc2f0da7456590877030c9b3d40b0c1", size = 220926, upload-time = "2025-09-08T23:23:27.873Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/aa/df335faa45b395396fcbc03de2dfcab242cd61a9900e914fe682a59170b1/cffi-2.0.0-cp314-cp314-win32.whl", hash = "sha256:087067fa8953339c723661eda6b54bc98c5625757ea62e95eb4898ad5e776e9f", size = 175328, upload-time = "2025-09-08T23:23:44.61Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/92/882c2d30831744296ce713f0feb4c1cd30f346ef747b530b5318715cc367/cffi-2.0.0-cp314-cp314-win_amd64.whl", hash = "sha256:203a48d1fb583fc7d78a4c6655692963b860a417c0528492a6bc21f1aaefab25", size = 185650, upload-time = "2025-09-08T23:23:45.848Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/2c/98ece204b9d35a7366b5b2c6539c350313ca13932143e79dc133ba757104/cffi-2.0.0-cp314-cp314-win_arm64.whl", hash = "sha256:dbd5c7a25a7cb98f5ca55d258b103a2054f859a46ae11aaf23134f9cc0d356ad", size = 180687, upload-time = "2025-09-08T23:23:47.105Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/61/c768e4d548bfa607abcda77423448df8c471f25dbe64fb2ef6d555eae006/cffi-2.0.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:9a67fc9e8eb39039280526379fb3a70023d77caec1852002b4da7e8b270c4dd9", size = 188773, upload-time = "2025-09-08T23:23:29.347Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/ea/5f76bce7cf6fcd0ab1a1058b5af899bfbef198bea4d5686da88471ea0336/cffi-2.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7a66c7204d8869299919db4d5069a82f1561581af12b11b3c9f48c584eb8743d", size = 185013, upload-time = "2025-09-08T23:23:30.63Z" },
+    { url = "https://files.pythonhosted.org/packages/be/b4/c56878d0d1755cf9caa54ba71e5d049479c52f9e4afc230f06822162ab2f/cffi-2.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7cc09976e8b56f8cebd752f7113ad07752461f48a58cbba644139015ac24954c", size = 221593, upload-time = "2025-09-08T23:23:31.91Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/0d/eb704606dfe8033e7128df5e90fee946bbcb64a04fcdaa97321309004000/cffi-2.0.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:92b68146a71df78564e4ef48af17551a5ddd142e5190cdf2c5624d0c3ff5b2e8", size = 209354, upload-time = "2025-09-08T23:23:33.214Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/19/3c435d727b368ca475fb8742ab97c9cb13a0de600ce86f62eab7fa3eea60/cffi-2.0.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:b1e74d11748e7e98e2f426ab176d4ed720a64412b6a15054378afdb71e0f37dc", size = 208480, upload-time = "2025-09-08T23:23:34.495Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/44/681604464ed9541673e486521497406fadcc15b5217c3e326b061696899a/cffi-2.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:28a3a209b96630bca57cce802da70c266eb08c6e97e5afd61a75611ee6c64592", size = 221584, upload-time = "2025-09-08T23:23:36.096Z" },
+    { url = "https://files.pythonhosted.org/packages/25/8e/342a504ff018a2825d395d44d63a767dd8ebc927ebda557fecdaca3ac33a/cffi-2.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7553fb2090d71822f02c629afe6042c299edf91ba1bf94951165613553984512", size = 224443, upload-time = "2025-09-08T23:23:37.328Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/5e/b666bacbbc60fbf415ba9988324a132c9a7a0448a9a8f125074671c0f2c3/cffi-2.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c6c373cfc5c83a975506110d17457138c8c63016b563cc9ed6e056a82f13ce4", size = 223437, upload-time = "2025-09-08T23:23:38.945Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/1d/ec1a60bd1a10daa292d3cd6bb0b359a81607154fb8165f3ec95fe003b85c/cffi-2.0.0-cp314-cp314t-win32.whl", hash = "sha256:1fc9ea04857caf665289b7a75923f2c6ed559b8298a1b8c49e59f7dd95c8481e", size = 180487, upload-time = "2025-09-08T23:23:40.423Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/41/4c1168c74fac325c0c8156f04b6749c8b6a8f405bbf91413ba088359f60d/cffi-2.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d68b6cef7827e8641e8ef16f4494edda8b36104d79773a334beaa1e3521430f6", size = 191726, upload-time = "2025-09-08T23:23:41.742Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
+]
+
 [[package]]
 name = "click"
 version = "8.4.1"
@@ -353,6 +445,7 @@ version = "0.0.0"
 source = { virtual = "." }
 dependencies = [
     { name = "alembic" },
+    { name = "argon2-cffi" },
     { name = "asyncpg" },
     { name = "fastapi" },
     { name = "pydantic" },
@@ -372,6 +465,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "alembic", specifier = ">=1.14" },
+    { name = "argon2-cffi", specifier = ">=23.1" },
     { name = "asyncpg", specifier = ">=0.30" },
     { name = "fastapi", specifier = ">=0.115" },
     { name = "pydantic", specifier = ">=2.9" },
@@ -388,6 +482,15 @@ dev = [
     { name = "ruff", specifier = ">=0.8" },
 ]
 
+[[package]]
+name = "pycparser"
+version = "3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" },
+]
+
 [[package]]
 name = "pydantic"
 version = "2.13.4"

deploy/.env.example

@@ -4,6 +4,10 @@
 # --- Core ---
 APP_ENV=development
 
+# --- Images (pulled from git.jpaul.io; CI pushes to the LAN registry) ---
+# test-main = current main build; or pin a semver / test-sha-<sha> for rollback.
+IMAGE_TAG=test-main
+
 # --- Database (Postgres) ---
 POSTGRES_USER=provenance
 POSTGRES_PASSWORD=change-me
@@ -22,8 +26,26 @@ S3_REGION=us-east-1
 
 # --- Edge (Caddy) ---
 # Local: ':80' (http://localhost). Production: 'provenance.example.com' for auto-HTTPS.
+# Behind a Cloudflare Tunnel, keep ':80' — Cloudflare terminates TLS and the
+# tunnel forwards plain HTTP to caddy:80.
 PROVENANCE_SITE_ADDRESS=:80
 
+# --- Cloudflare Tunnel (optional) ---
+# Enable by setting COMPOSE_PROFILES=tunnel and supplying the connector token
+# from the Cloudflare dashboard. Public hostname -> http://caddy:80.
+CLOUDFLARE_TUNNEL_TOKEN=
+COMPOSE_PROFILES=
+
+# --- Auth / sessions ---
+SESSION_TTL_DAYS=30
+TOKEN_TTL_HOURS=24
+# Set false for local http; true (default) behind TLS.
+COOKIE_SECURE=false
+# Base URL used to build links in outbound email.
+APP_BASE_URL=http://localhost
+# Mailer: 'console' logs links to stdout (dev); 'smtp' uses the SMTP settings below.
+MAILER=console
+
 # --- Email (SMTP) — wired in a later phase ---
 SMTP_HOST=
 SMTP_PORT=587

deploy/Caddyfile

@@ -15,11 +15,8 @@
 		reverse_proxy backend:8000
 	}
 
-	# Frontend (Next.js) — not yet deployed in Phase 0. Uncomment when it lands.
-	# handle {
-	#	reverse_proxy frontend:3000
-	# }
+	# Everything else -> the Next.js frontend.
 	handle {
-		respond "Provenance — Phase 0. Backend health at /health; frontend not yet deployed." 200
+		reverse_proxy frontend:3000
 	}
 }

deploy/docker-compose.dev.yml

@@ -0,0 +1,18 @@
+name: provenance
+
+# Dev override: build the backend/frontend images locally instead of pulling
+# them from the registry. Layer it on top of the base compose:
+#   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
+#
+# Use this before CI has published images, or to test local changes.
+
+services:
+  backend:
+    build:
+      context: ../backend
+      dockerfile: Dockerfile
+
+  frontend:
+    build:
+      context: ../frontend
+      dockerfile: Dockerfile

deploy/docker-compose.yml

@@ -2,6 +2,11 @@ name: provenance
 
 # One stack stands up the whole system. Configuration is entirely env-driven
 # (see .env.example). Run from this directory: `docker compose up -d`.
+#
+# backend/frontend are PULLED from the public registry (git.jpaul.io); CI pushes
+# them to the LAN endpoint (192.168.0.2:1234). For local building instead of
+# pulling, layer the dev override:
+#   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
 
 services:
   postgres:
@@ -36,9 +41,7 @@ services:
     restart: unless-stopped
 
   backend:
-    build:
-      context: ../backend
-      dockerfile: Dockerfile
+    image: git.jpaul.io/justin/provenance-backend:${IMAGE_TAG:-test-main}
     environment:
       APP_ENV: ${APP_ENV:-development}
       DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://provenance:provenance@postgres:5432/provenance}
@@ -57,6 +60,14 @@ services:
       start_period: 20s
     restart: unless-stopped
 
+  frontend:
+    image: git.jpaul.io/justin/provenance-frontend:${IMAGE_TAG:-test-main}
+    environment:
+      NODE_ENV: production
+    depends_on:
+      - backend
+    restart: unless-stopped
+
   caddy:
     image: caddy:2
     ports:
@@ -72,8 +83,27 @@ services:
       - caddyconfig:/config
     depends_on:
       - backend
+      - frontend
     restart: unless-stopped
 
+  # Cloudflare Tunnel connector. The tunnel/ingress is configured in the
+  # Cloudflare dashboard; this container just connects. One public hostname
+  # (e.g. provenance.paul.farm) -> http://caddy:80 is enough, because Caddy
+  # does the internal path routing (/ -> frontend, /api + /health -> backend).
+  #
+  # Opt-in via the "tunnel" profile so local dev doesn't start it. On the lab
+  # host set COMPOSE_PROFILES=tunnel so `docker compose up -d` includes it.
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    restart: unless-stopped
+    command: tunnel --no-autoupdate run
+    environment:
+      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN:-}
+    depends_on:
+      - caddy
+    profiles:
+      - tunnel
+
 volumes:
   pgdata:
   miniodata:

docs/ARCHITECTURE.md

@@ -79,6 +79,7 @@ Async throughout (FastAPI + async SQLAlchemy). Anything that can be slow or can
 - **Authoring UI** is client-side, talking to the REST API. A generated TypeScript client keeps it in sync with the OpenAPI contract.
 - **Mobile-first.** Layouts are responsive and touch-first; no separate mobile codebase. Feature parity with desktop is a requirement, not a nice-to-have.
 - **Design system:** Tailwind + shadcn/ui for a consistent, accessible (WCAG 2.2 AA target) component layer.
+- *Status:* the scaffold has landed — Next.js (App Router) + Tailwind + shadcn-style primitives, a typed client generated from the backend OpenAPI spec (`openapi-typescript` + `openapi-fetch`), and auth + tree/person views. Auth rides the same-origin HttpOnly session cookie (Caddy proxies `/api/*` to the backend). Built as a standalone container; Caddy routes `/` to it.
 
 ## 5. Data model
 
@@ -93,7 +94,7 @@ Core entities and the important relationships. (Illustrative, not final DDL.)
 - **Person** — belongs to a Tree. Has many **Name** records (with parts: given, surname, prefix/suffix, and a type such as birth/married/alias) to support variants and changes over time. Carries living/deceased status.
 - **Relationship** — typed edge between two Persons within a Tree: parent–child (with a qualifier: biological, adoptive, step, foster, donor, guardian), partnership/marriage (with its own events), sibling (often derived). Modeling parentage as qualified edges — rather than assuming a two-biological-parent nuclear family — is what makes adoption, donor conception, and blended families first-class rather than awkward.
 - **Event** — typed (birth, death, marriage, residence, immigration, etc.), with a date (supporting ranges, approximations, and non-Gregorian calendars), an optional Place, and attachable to a Person or a partnership.
-- **Place** — a tenant-shared gazetteer entity: hierarchical (place within place), with **historical name variants and date ranges** so a record entered as "Königsberg, 1900" sorts and displays correctly against "Kaliningrad." Optional coordinates.
+- **Place** — a tenant-shared gazetteer entity: hierarchical (place within place), with **historical name variants and date ranges** so a record entered as "Königsberg, 1900" sorts and displays correctly against "Kaliningrad." Optional coordinates. *(Phase 0 scopes Place to a Tree via `tree_id` for absolute tenant isolation; a deployment-wide shared gazetteer is a deliberate later refinement. Variants live in a `PlaceName` child table.)*
 
 ### Sources (first-class)
 - **Source** — a reusable record of an origin: title, repository, type, optional URL, free citation text, optional quality grade. One Source backs many facts.
@@ -147,6 +148,7 @@ Three parts, deliberately separated:
 - `AuthProvider` interface with implementations for **local** (password + email verification/reset), **OIDC** (validated against Authentik; expected to work with Keycloak, Auth0, etc.), and **social** (Google, Apple, Facebook).
 - Operators enable any subset via config. This deployment will use Authentik (`auth.jpaul.io`) plus selected social providers; a bare self-hoster can run local-only.
 - Sessions are backend-issued; the assistant principal is minted per-session and scoped to the acting user.
+- *Status:* **local auth has landed** — Argon2id password hashing, opaque backend-issued sessions (only the token hash is stored; presented as a Bearer token or HttpOnly cookie), and email verification + password reset via the `Mailer` interface (console in dev, SMTP for operators). OIDC and social providers are Phase 5. Every write records an attributable actor in the audit log.
 
 ## 10. Search
 
@@ -168,8 +170,10 @@ Jobs are idempotent and retryable; an external failure degrades gracefully rathe
 
 ## 12. Deployment & CI/CD
 
-- **Images** are built by **Gitea Actions** on `git.jpaul.io` and pushed to the **Gitea container registry**.
-- Servers **pull** new images to deploy — no build on the host.
+- **Images** are built by **Gitea Actions** (`runs-on: docker`) and pushed to the **Gitea container registry**, one package per component (`provenance-backend`, `provenance-frontend`) linked to the repo.
+- **Split push/pull endpoints** (mirrors the drawbar setup): CI **pushes** to the LAN registry endpoint `192.168.0.2:1234` over plain HTTP (buildx configured `insecure`/`http`) to bypass the Cloudflare request-body limit; servers **pull** from the public `git.jpaul.io` FQDN (TLS via Cloudflare). Same Gitea registry, two front doors. Auth uses the `REGISTRY_TOKEN` Actions secret.
+- Tag scheme: `test-main` (current main), `test-sha-<long>` (rollback pins), the component version, and `latest` on `v*` tags.
+- Servers **pull** new images to deploy — no build on the host. The deploy compose references `git.jpaul.io/justin/provenance-{backend,frontend}:${IMAGE_TAG:-test-main}`; `docker-compose.dev.yml` is a local-build override.
 - **Caddy** terminates TLS and reverse-proxies frontend + backend. **Cloudflare Tunnel** is the preferred ingress (no open inbound ports) but is never required; a plain Caddy-on-a-public-host deployment is equally supported.
 - **Configuration** is entirely environment-driven (twelve-factor). One `.env` plus the compose file is enough to stand up a deployment.
 - **Migrations** run on backend start (or via an explicit job) so an image pull + restart is a complete upgrade.
@@ -178,10 +182,10 @@ Jobs are idempotent and retryable; an external failure degrades gracefully rathe
 **Repository layout (as scaffolded):**
 
 ```
-/backend           # FastAPI service, uv-managed (app/ = api, core; service/repository/domain land with the data model)
+/backend           # FastAPI, uv-managed. app/{api/v1, services (+privacy), repositories, models, schemas, integrations (auth/mailer), core}; migrations/ = Alembic
 /deploy            # docker-compose.yml, Caddyfile, .env.example
 /.gitea/workflows  # Gitea Actions: build images → Gitea registry
-/frontend          # Next.js (pending)
+/frontend          # Next.js (App Router, TS, Tailwind). app/ pages, lib/api (openapi-typescript client), components/ui, Dockerfile (standalone)
 ```
 
 The compose stack runs `postgres` (pgvector image — includes `pgvector`; `pg_trgm` ships in contrib), `minio`, `backend`, and `caddy`. The **worker** container (same image as backend, worker mode) joins once queue-driven jobs exist. Phase 0 ships a minimal backend with `/health` (liveness) and `/health/ready` (Postgres reachability) to validate the deploy wiring before the data model lands.

frontend/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+.next
+out
+build
+npm-debug.log*
+.env*.local
+README.md

frontend/.gitignore

@@ -0,0 +1,6 @@
+/node_modules
+/.next
+/out
+/build
+next-env.d.ts
+.env*.local

frontend/Dockerfile

@@ -0,0 +1,24 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-bookworm-slim AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+FROM node:22-bookworm-slim AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:22-bookworm-slim AS runner
+WORKDIR /app
+ENV NODE_ENV=production \
+    PORT=3000 \
+    HOSTNAME=0.0.0.0
+# Next standalone output: a minimal server with only the traced dependencies.
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+COPY --from=build /app/public ./public
+EXPOSE 3000
+CMD ["node", "server.js"]

frontend/app/globals.css

@@ -0,0 +1,19 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}

frontend/app/layout.tsx

@@ -0,0 +1,34 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Provenance",
+  description: "Where it came from matters — family and land, every fact sourced.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <header className="border-b border-neutral-200">
+          <div className="mx-auto flex max-w-3xl items-center justify-between px-4 py-3">
+            <Link href="/" className="font-semibold">
+              Provenance
+            </Link>
+            <nav className="flex gap-4 text-sm">
+              <Link href="/trees" className="hover:underline">
+                Trees
+              </Link>
+              <Link href="/login" className="hover:underline">
+                Sign in
+              </Link>
+            </nav>
+          </div>
+        </header>
+        <main className="mx-auto max-w-3xl px-4 py-8">{children}</main>
+      </body>
+    </html>
+  );
+}

frontend/app/login/page.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export default function LoginPage() {
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+    const { error } = await api.POST("/api/v1/auth/login", { body: { email, password } });
+    setLoading(false);
+    if (error) {
+      setError("Invalid email or password.");
+      return;
+    }
+    router.push("/trees");
+  }
+
+  return (
+    <Card className="mx-auto max-w-md">
+      <CardHeader>
+        <CardTitle>Sign in</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={onSubmit} className="space-y-4">
+          <div className="space-y-1">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              required
+            />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              required
+            />
+          </div>
+          {error && <p className="text-sm text-red-600">{error}</p>}
+          <Button type="submit" disabled={loading} className="w-full">
+            {loading ? "Signing in…" : "Sign in"}
+          </Button>
+        </form>
+        <p className="mt-4 text-sm text-neutral-600">
+          No account?{" "}
+          <Link href="/register" className="underline">
+            Create one
+          </Link>
+        </p>
+      </CardContent>
+    </Card>
+  );
+}

frontend/app/page.tsx

@@ -0,0 +1,25 @@
+import Link from "next/link";
+
+import { Button } from "@/components/ui/button";
+
+export default function Home() {
+  return (
+    <div className="space-y-6">
+      <div className="space-y-2">
+        <h1 className="text-3xl font-bold">Provenance</h1>
+        <p className="text-neutral-600">
+          Trace where you come from — your family and your land — with every fact linked to a
+          source, on infrastructure you control.
+        </p>
+      </div>
+      <div className="flex gap-3">
+        <Link href="/register">
+          <Button>Create an account</Button>
+        </Link>
+        <Link href="/login">
+          <Button variant="outline">Sign in</Button>
+        </Link>
+      </div>
+    </div>
+  );
+}

frontend/app/register/page.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export default function RegisterPage() {
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+    const { error } = await api.POST("/api/v1/auth/register", {
+      body: { email, password, display_name: displayName || null },
+    });
+    setLoading(false);
+    if (error) {
+      setError("Could not register. The email may already be in use, or the password is too short (min 8).");
+      return;
+    }
+    router.push("/trees");
+  }
+
+  return (
+    <Card className="mx-auto max-w-md">
+      <CardHeader>
+        <CardTitle>Create your account</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={onSubmit} className="space-y-4">
+          <div className="space-y-1">
+            <Label htmlFor="name">Name</Label>
+            <Input id="name" value={displayName} onChange={(e) => setDisplayName(e.target.value)} />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              required
+            />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              minLength={8}
+              required
+            />
+          </div>
+          {error && <p className="text-sm text-red-600">{error}</p>}
+          <Button type="submit" disabled={loading} className="w-full">
+            {loading ? "Creating…" : "Create account"}
+          </Button>
+        </form>
+        <p className="mt-4 text-sm text-neutral-600">
+          Already have an account?{" "}
+          <Link href="/login" className="underline">
+            Sign in
+          </Link>
+        </p>
+      </CardContent>
+    </Card>
+  );
+}

frontend/app/trees/[id]/page.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import Link from "next/link";
+import { useParams, useRouter } from "next/navigation";
+import { useCallback, useEffect, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import type { components } from "@/lib/api/schema";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+
+type Person = components["schemas"]["PersonRead"];
+
+export default function TreeDetailPage() {
+  const router = useRouter();
+  const params = useParams<{ id: string }>();
+  const treeId = params.id;
+
+  const [persons, setPersons] = useState<Person[]>([]);
+  const [given, setGiven] = useState("");
+  const [surname, setSurname] = useState("");
+  const [ready, setReady] = useState(false);
+
+  const load = useCallback(async () => {
+    const { data, response } = await api.GET("/api/v1/trees/{tree_id}/persons", {
+      params: { path: { tree_id: treeId } },
+    });
+    if (response.status === 401) {
+      router.push("/login");
+      return;
+    }
+    setPersons(data ?? []);
+    setReady(true);
+  }, [router, treeId]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  async function addPerson(e: React.FormEvent) {
+    e.preventDefault();
+    if (!given.trim() && !surname.trim()) return;
+    const { error } = await api.POST("/api/v1/trees/{tree_id}/persons", {
+      params: { path: { tree_id: treeId } },
+      body: { given: given || null, surname: surname || null },
+    });
+    if (!error) {
+      setGiven("");
+      setSurname("");
+      load();
+    }
+  }
+
+  if (!ready) return <p className="text-neutral-500">Loading…</p>;
+
+  return (
+    <div className="space-y-6">
+      <Link href="/trees" className="text-sm text-neutral-500 hover:underline">
+        ← All trees
+      </Link>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Add a person</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <form onSubmit={addPerson} className="flex gap-2">
+            <Input placeholder="Given name" value={given} onChange={(e) => setGiven(e.target.value)} />
+            <Input placeholder="Surname" value={surname} onChange={(e) => setSurname(e.target.value)} />
+            <Button type="submit">Add</Button>
+          </form>
+        </CardContent>
+      </Card>
+
+      <div>
+        <h2 className="mb-2 text-lg font-semibold">People</h2>
+        {persons.length === 0 ? (
+          <p className="text-neutral-500">No people yet.</p>
+        ) : (
+          <ul className="space-y-2">
+            {persons.map((person) => (
+              <li key={person.id}>
+                <Card>
+                  <CardContent className="p-4">
+                    {person.primary_name ?? <span className="text-neutral-400">Unnamed</span>}
+                  </CardContent>
+                </Card>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/app/trees/page.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useCallback, useEffect, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import type { components } from "@/lib/api/schema";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+
+type Tree = components["schemas"]["TreeRead"];
+
+export default function TreesPage() {
+  const router = useRouter();
+  const [trees, setTrees] = useState<Tree[]>([]);
+  const [name, setName] = useState("");
+  const [ready, setReady] = useState(false);
+
+  const load = useCallback(async () => {
+    const { data, response } = await api.GET("/api/v1/trees");
+    if (response.status === 401) {
+      router.push("/login");
+      return;
+    }
+    setTrees(data ?? []);
+    setReady(true);
+  }, [router]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  async function createTree(e: React.FormEvent) {
+    e.preventDefault();
+    if (!name.trim()) return;
+    const { error } = await api.POST("/api/v1/trees", { body: { name } });
+    if (!error) {
+      setName("");
+      load();
+    }
+  }
+
+  async function logout() {
+    await api.POST("/api/v1/auth/logout");
+    router.push("/login");
+  }
+
+  if (!ready) return <p className="text-neutral-500">Loading…</p>;
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-bold">Your trees</h1>
+        <Button variant="ghost" size="sm" onClick={logout}>
+          Sign out
+        </Button>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">New tree</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <form onSubmit={createTree} className="flex gap-2">
+            <Input
+              placeholder="Family name"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+            />
+            <Button type="submit">Create</Button>
+          </form>
+        </CardContent>
+      </Card>
+
+      {trees.length === 0 ? (
+        <p className="text-neutral-500">No trees yet — create your first one above.</p>
+      ) : (
+        <ul className="space-y-2">
+          {trees.map((tree) => (
+            <li key={tree.id}>
+              <Link href={`/trees/${tree.id}`}>
+                <Card className="transition-colors hover:bg-neutral-50">
+                  <CardContent className="flex items-center justify-between p-4">
+                    <span className="font-medium">{tree.name}</span>
+                    <span className="text-xs uppercase tracking-wide text-neutral-400">
+                      {tree.visibility}
+                    </span>
+                  </CardContent>
+                </Card>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

frontend/components/ui/button.tsx

@@ -0,0 +1,33 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-neutral-400 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-neutral-900 text-white hover:bg-neutral-700",
+        outline: "border border-neutral-300 bg-transparent hover:bg-neutral-100",
+        ghost: "hover:bg-neutral-100",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 px-3",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, ...props }, ref) => (
+    <button ref={ref} className={cn(buttonVariants({ variant, size, className }))} {...props} />
+  ),
+);
+Button.displayName = "Button";

frontend/components/ui/card.tsx

@@ -0,0 +1,24 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+export function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("rounded-lg border border-neutral-200 bg-white/50 shadow-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-1 p-6", className)} {...props} />;
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className={cn("text-lg font-semibold", className)} {...props} />;
+}
+
+export function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("p-6 pt-0", className)} {...props} />;
+}

frontend/components/ui/input.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+export const Input = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
+  ({ className, ...props }, ref) => (
+    <input
+      ref={ref}
+      className={cn(
+        "flex h-10 w-full rounded-md border border-neutral-300 bg-transparent px-3 py-2 text-sm placeholder:text-neutral-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-neutral-400 disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Input.displayName = "Input";

frontend/components/ui/label.tsx

@@ -0,0 +1,11 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+export const Label = React.forwardRef<
+  HTMLLabelElement,
+  React.LabelHTMLAttributes<HTMLLabelElement>
+>(({ className, ...props }, ref) => (
+  <label ref={ref} className={cn("text-sm font-medium", className)} {...props} />
+));
+Label.displayName = "Label";

frontend/lib/api/client.ts

@@ -0,0 +1,10 @@
+import createClient from "openapi-fetch";
+
+import type { paths } from "./schema";
+
+// Same-origin in production (Caddy proxies /api/* to the backend). Override with
+// NEXT_PUBLIC_API_BASE_URL for split local dev. credentials:"include" sends the
+// HttpOnly session cookie the backend issues on login.
+const baseUrl = process.env.NEXT_PUBLIC_API_BASE_URL ?? "";
+
+export const api = createClient<paths>({ baseUrl, credentials: "include" });

frontend/lib/api/schema.d.ts

@@ -0,0 +1,785 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Health */
+        get: operations["health_health_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/health/ready": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Ready */
+        get: operations["ready_health_ready_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/register": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Register */
+        post: operations["register_api_v1_auth_register_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/login": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Login */
+        post: operations["login_api_v1_auth_login_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/logout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Logout */
+        post: operations["logout_api_v1_auth_logout_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/verify-email": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Verify Email */
+        post: operations["verify_email_api_v1_auth_verify_email_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/request-password-reset": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Request Password Reset */
+        post: operations["request_password_reset_api_v1_auth_request_password_reset_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/auth/reset-password": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reset Password */
+        post: operations["reset_password_api_v1_auth_reset_password_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/users/me": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read Me */
+        get: operations["read_me_api_v1_users_me_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/trees": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List My Trees */
+        get: operations["list_my_trees_api_v1_trees_get"];
+        put?: never;
+        /** Create Tree */
+        post: operations["create_tree_api_v1_trees_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/trees/{tree_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Tree */
+        get: operations["get_tree_api_v1_trees__tree_id__get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/trees/{tree_id}/persons": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List Persons */
+        get: operations["list_persons_api_v1_trees__tree_id__persons_get"];
+        put?: never;
+        /** Create Person */
+        post: operations["create_person_api_v1_trees__tree_id__persons_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /** HTTPValidationError */
+        HTTPValidationError: {
+            /** Detail */
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        /** LoginRequest */
+        LoginRequest: {
+            /** Email */
+            email: string;
+            /** Password */
+            password: string;
+        };
+        /** PasswordResetConfirm */
+        PasswordResetConfirm: {
+            /** Token */
+            token: string;
+            /** New Password */
+            new_password: string;
+        };
+        /** PasswordResetRequest */
+        PasswordResetRequest: {
+            /** Email */
+            email: string;
+        };
+        /** PersonCreate */
+        PersonCreate: {
+            /** Given */
+            given?: string | null;
+            /** Surname */
+            surname?: string | null;
+            /** Gender */
+            gender?: string | null;
+            /** Is Living */
+            is_living?: boolean | null;
+            /** @default inherit */
+            privacy?: components["schemas"]["PersonPrivacy"];
+            /** Notes */
+            notes?: string | null;
+        };
+        /**
+         * PersonPrivacy
+         * @description Per-person override of the tree's visibility (PRD US-041).
+         * @enum {string}
+         */
+        PersonPrivacy: "inherit" | "private" | "public";
+        /** PersonRead */
+        PersonRead: {
+            /**
+             * Id
+             * Format: uuid
+             */
+            id: string;
+            /**
+             * Tree Id
+             * Format: uuid
+             */
+            tree_id: string;
+            /** Primary Name */
+            primary_name?: string | null;
+            /** Gender */
+            gender: string | null;
+            /** Is Living */
+            is_living: boolean | null;
+            privacy: components["schemas"]["PersonPrivacy"];
+            /**
+             * Created At
+             * Format: date-time
+             */
+            created_at: string;
+        };
+        /** RegisterRequest */
+        RegisterRequest: {
+            /** Email */
+            email: string;
+            /** Password */
+            password: string;
+            /** Display Name */
+            display_name?: string | null;
+        };
+        /** SessionRead */
+        SessionRead: {
+            user: components["schemas"]["UserRead"];
+            /** Token */
+            token: string;
+            /**
+             * Expires At
+             * Format: date-time
+             */
+            expires_at: string;
+        };
+        /** TokenRequest */
+        TokenRequest: {
+            /** Token */
+            token: string;
+        };
+        /** TreeCreate */
+        TreeCreate: {
+            /** Name */
+            name: string;
+            /** Description */
+            description?: string | null;
+            /** @default private */
+            visibility?: components["schemas"]["TreeVisibility"];
+        };
+        /** TreeRead */
+        TreeRead: {
+            /**
+             * Id
+             * Format: uuid
+             */
+            id: string;
+            /** Name */
+            name: string;
+            /** Description */
+            description: string | null;
+            visibility: components["schemas"]["TreeVisibility"];
+            /**
+             * Owner Id
+             * Format: uuid
+             */
+            owner_id: string;
+            /**
+             * Created At
+             * Format: date-time
+             */
+            created_at: string;
+        };
+        /**
+         * TreeVisibility
+         * @enum {string}
+         */
+        TreeVisibility: "public" | "unlisted" | "private";
+        /** UserRead */
+        UserRead: {
+            /**
+             * Id
+             * Format: uuid
+             */
+            id: string;
+            /** Email */
+            email: string;
+            /** Display Name */
+            display_name: string | null;
+            /** Email Verified At */
+            email_verified_at: string | null;
+            /**
+             * Created At
+             * Format: date-time
+             */
+            created_at: string;
+        };
+        /** ValidationError */
+        ValidationError: {
+            /** Location */
+            loc: (string | number)[];
+            /** Message */
+            msg: string;
+            /** Error Type */
+            type: string;
+            /** Input */
+            input?: unknown;
+            /** Context */
+            ctx?: Record<string, never>;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    health_health_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
+    ready_health_ready_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
+    register_api_v1_auth_register_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RegisterRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionRead"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    login_api_v1_auth_login_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LoginRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionRead"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    logout_api_v1_auth_logout_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    verify_email_api_v1_auth_verify_email_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TokenRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    request_password_reset_api_v1_auth_request_password_reset_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PasswordResetRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    reset_password_api_v1_auth_reset_password_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PasswordResetConfirm"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    read_me_api_v1_users_me_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserRead"];
+                };
+            };
+        };
+    };
+    list_my_trees_api_v1_trees_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TreeRead"][];
+                };
+            };
+        };
+    };
+    create_tree_api_v1_trees_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TreeCreate"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TreeRead"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    get_tree_api_v1_trees__tree_id__get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tree_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TreeRead"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    list_persons_api_v1_trees__tree_id__persons_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tree_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PersonRead"][];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    create_person_api_v1_trees__tree_id__persons_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tree_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PersonCreate"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PersonRead"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+}

frontend/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

frontend/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Standalone output keeps the production container small.
+  output: "standalone",
+};
+
+export default nextConfig;

frontend/openapi.json

@@ -0,0 +1,936 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Provenance",
+    "description": "Provenance API \u2014 family and land provenance.",
+    "version": "0.0.0"
+  },
+  "paths": {
+    "/health": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "summary": "Health",
+        "operationId": "health_health_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Health Health Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/health/ready": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "summary": "Ready",
+        "operationId": "ready_health_ready_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Ready Health Ready Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/auth/register": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Register",
+        "operationId": "register_api_v1_auth_register_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RegisterRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionRead"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/auth/login": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Login",
+        "operationId": "login_api_v1_auth_login_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/LoginRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionRead"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/auth/logout": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Logout",
+        "operationId": "logout_api_v1_auth_logout_post",
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          }
+        }
+      }
+    },
+    "/api/v1/auth/verify-email": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Verify Email",
+        "operationId": "verify_email_api_v1_auth_verify_email_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/auth/request-password-reset": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Request Password Reset",
+        "operationId": "request_password_reset_api_v1_auth_request_password_reset_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PasswordResetRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Request Password Reset Api V1 Auth Request Password Reset Post"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/auth/reset-password": {
+      "post": {
+        "tags": [
+          "auth"
+        ],
+        "summary": "Reset Password",
+        "operationId": "reset_password_api_v1_auth_reset_password_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PasswordResetConfirm"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/users/me": {
+      "get": {
+        "tags": [
+          "users"
+        ],
+        "summary": "Read Me",
+        "operationId": "read_me_api_v1_users_me_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserRead"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/trees": {
+      "get": {
+        "tags": [
+          "trees"
+        ],
+        "summary": "List My Trees",
+        "operationId": "list_my_trees_api_v1_trees_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "$ref": "#/components/schemas/TreeRead"
+                  },
+                  "type": "array",
+                  "title": "Response List My Trees Api V1 Trees Get"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "trees"
+        ],
+        "summary": "Create Tree",
+        "operationId": "create_tree_api_v1_trees_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TreeCreate"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreeRead"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/trees/{tree_id}": {
+      "get": {
+        "tags": [
+          "trees"
+        ],
+        "summary": "Get Tree",
+        "operationId": "get_tree_api_v1_trees__tree_id__get",
+        "parameters": [
+          {
+            "name": "tree_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "title": "Tree Id"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreeRead"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/trees/{tree_id}/persons": {
+      "post": {
+        "tags": [
+          "persons"
+        ],
+        "summary": "Create Person",
+        "operationId": "create_person_api_v1_trees__tree_id__persons_post",
+        "parameters": [
+          {
+            "name": "tree_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "title": "Tree Id"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PersonCreate"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PersonRead"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "persons"
+        ],
+        "summary": "List Persons",
+        "operationId": "list_persons_api_v1_trees__tree_id__persons_get",
+        "parameters": [
+          {
+            "name": "tree_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "title": "Tree Id"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/PersonRead"
+                  },
+                  "title": "Response List Persons Api V1 Trees  Tree Id  Persons Get"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "HTTPValidationError": {
+        "properties": {
+          "detail": {
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            },
+            "type": "array",
+            "title": "Detail"
+          }
+        },
+        "type": "object",
+        "title": "HTTPValidationError"
+      },
+      "LoginRequest": {
+        "properties": {
+          "email": {
+            "type": "string",
+            "title": "Email"
+          },
+          "password": {
+            "type": "string",
+            "title": "Password"
+          }
+        },
+        "type": "object",
+        "required": [
+          "email",
+          "password"
+        ],
+        "title": "LoginRequest"
+      },
+      "PasswordResetConfirm": {
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "Token"
+          },
+          "new_password": {
+            "type": "string",
+            "minLength": 8,
+            "title": "New Password"
+          }
+        },
+        "type": "object",
+        "required": [
+          "token",
+          "new_password"
+        ],
+        "title": "PasswordResetConfirm"
+      },
+      "PasswordResetRequest": {
+        "properties": {
+          "email": {
+            "type": "string",
+            "title": "Email"
+          }
+        },
+        "type": "object",
+        "required": [
+          "email"
+        ],
+        "title": "PasswordResetRequest"
+      },
+      "PersonCreate": {
+        "properties": {
+          "given": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Given"
+          },
+          "surname": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Surname"
+          },
+          "gender": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Gender"
+          },
+          "is_living": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Is Living"
+          },
+          "privacy": {
+            "$ref": "#/components/schemas/PersonPrivacy",
+            "default": "inherit"
+          },
+          "notes": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Notes"
+          }
+        },
+        "type": "object",
+        "title": "PersonCreate"
+      },
+      "PersonPrivacy": {
+        "type": "string",
+        "enum": [
+          "inherit",
+          "private",
+          "public"
+        ],
+        "title": "PersonPrivacy",
+        "description": "Per-person override of the tree's visibility (PRD US-041)."
+      },
+      "PersonRead": {
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Id"
+          },
+          "tree_id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Tree Id"
+          },
+          "primary_name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Primary Name"
+          },
+          "gender": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Gender"
+          },
+          "is_living": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Is Living"
+          },
+          "privacy": {
+            "$ref": "#/components/schemas/PersonPrivacy"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          }
+        },
+        "type": "object",
+        "required": [
+          "id",
+          "tree_id",
+          "gender",
+          "is_living",
+          "privacy",
+          "created_at"
+        ],
+        "title": "PersonRead"
+      },
+      "RegisterRequest": {
+        "properties": {
+          "email": {
+            "type": "string",
+            "title": "Email"
+          },
+          "password": {
+            "type": "string",
+            "minLength": 8,
+            "title": "Password"
+          },
+          "display_name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Display Name"
+          }
+        },
+        "type": "object",
+        "required": [
+          "email",
+          "password"
+        ],
+        "title": "RegisterRequest"
+      },
+      "SessionRead": {
+        "properties": {
+          "user": {
+            "$ref": "#/components/schemas/UserRead"
+          },
+          "token": {
+            "type": "string",
+            "title": "Token"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Expires At"
+          }
+        },
+        "type": "object",
+        "required": [
+          "user",
+          "token",
+          "expires_at"
+        ],
+        "title": "SessionRead"
+      },
+      "TokenRequest": {
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "Token"
+          }
+        },
+        "type": "object",
+        "required": [
+          "token"
+        ],
+        "title": "TokenRequest"
+      },
+      "TreeCreate": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "title": "Name"
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Description"
+          },
+          "visibility": {
+            "$ref": "#/components/schemas/TreeVisibility",
+            "default": "private"
+          }
+        },
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "title": "TreeCreate"
+      },
+      "TreeRead": {
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Id"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name"
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Description"
+          },
+          "visibility": {
+            "$ref": "#/components/schemas/TreeVisibility"
+          },
+          "owner_id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Owner Id"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          }
+        },
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "description",
+          "visibility",
+          "owner_id",
+          "created_at"
+        ],
+        "title": "TreeRead"
+      },
+      "TreeVisibility": {
+        "type": "string",
+        "enum": [
+          "public",
+          "unlisted",
+          "private"
+        ],
+        "title": "TreeVisibility"
+      },
+      "UserRead": {
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Id"
+          },
+          "email": {
+            "type": "string",
+            "title": "Email"
+          },
+          "display_name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Display Name"
+          },
+          "email_verified_at": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Email Verified At"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          }
+        },
+        "type": "object",
+        "required": [
+          "id",
+          "email",
+          "display_name",
+          "email_verified_at",
+          "created_at"
+        ],
+        "title": "UserRead"
+      },
+      "ValidationError": {
+        "properties": {
+          "loc": {
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                }
+              ]
+            },
+            "type": "array",
+            "title": "Location"
+          },
+          "msg": {
+            "type": "string",
+            "title": "Message"
+          },
+          "type": {
+            "type": "string",
+            "title": "Error Type"
+          },
+          "input": {
+            "title": "Input"
+          },
+          "ctx": {
+            "type": "object",
+            "title": "Context"
+          }
+        },
+        "type": "object",
+        "required": [
+          "loc",
+          "msg",
+          "type"
+        ],
+        "title": "ValidationError"
+      }
+    }
+  }
+}

frontend/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "provenance-frontend",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "gen:api": "openapi-typescript ./openapi.json -o ./lib/api/schema.d.ts --default-non-nullable false"
+  },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "openapi-fetch": "^0.13.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0",
+    "lucide-react": "^0.469.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.49",
+    "openapi-typescript": "^7.5.0"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

frontend/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}