Add layered service/API for tenancy and people with the privacy seam

Wires the data model through repository -> service -> API/v1. The privacy engine (app/services/privacy.py) is the single enforcement point: every read resolves visibility there (tree role, tree visibility, per-person override; living-person redaction is a marked Phase 2 TODO). All writes record an attributable AuditEntry.

Endpoints: POST /users (open dev bootstrap until auth), GET /users/me, POST/GET /trees, GET /trees/{id}, and POST/GET /trees/{id}/persons. Authn is a temporary X-User-Id header shim; authz is membership-based (owner/editor/viewer). Domain errors map to 401/403/404/409. Verified on the deploy target: private tree -> 403 for non-members, missing actor -> 401, audit log populated.

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

backend/app/api/deps.py

@@ -0,0 +1,33 @@
+"""Shared API dependencies."""
+
+import uuid
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.db import get_session
+from app.models.user import User
+from app.services.user_service import get_user
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+
+async def get_current_user(
+    session: SessionDep,
+    x_user_id: Annotated[uuid.UUID | None, Header()] = None,
+) -> User:
+    """TEMPORARY pre-auth shim: identifies the caller via the ``X-User-Id``
+    header. Replaced by the AuthProvider (sessions/tokens) in the auth slice.
+    The assistant principal will also be minted here, scoped to its user."""
+    if x_user_id is None:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED, "X-User-Id header required (pre-auth)"
+        )
+    user = await get_user(session, x_user_id)
+    if user is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "unknown user")
+    return user
+
+
+CurrentUser = Annotated[User, Depends(get_current_user)]

backend/app/api/v1/__init__.py

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

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,21 @@
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.user import UserCreate, UserRead
+from app.services import user_service
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.post("", response_model=UserRead, status_code=status.HTTP_201_CREATED)
+async def create_user(data: UserCreate, session: SessionDep) -> UserRead:
+    # Open dev bootstrap until the auth slice; lets us create tree owners.
+    user = await user_service.create_user(
+        session, email=data.email, display_name=data.display_name
+    )
+    return UserRead.model_validate(user)
+
+
+@router.get("/me", response_model=UserRead)
+async def read_me(current: CurrentUser) -> UserRead:
+    return UserRead.model_validate(current)