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>
2026-06-06 10:40:19 -04:00
parent 297cb797d6
commit dffd05d303
20 changed files with 640 additions and 13 deletions
@@ -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
@@ -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)."""
@@ -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
@@ -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
@@ -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
@@ -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)