provenance/docs/design/tree-visibility.md

# Design note: tree visibility & the public viewing surface

Status: **Shipped (#41-#51)**. Owner: Justin. Created 2026-06-09.

This is a privacy-critical change (it created the first anonymous read surface in
Provenance). Per CLAUDE.md, it was designed before code and shipped in small,
individually-reviewable PRs, with tests on the privacy engine and the public read
path landing before any anonymous endpoint was exposed.

## 1. The model

Visibility flattens **two axes** — *who may read* and *how discoverable* — into one
ordered enum for the UI:

| Level | Anonymous (no login) | Any logged-in user | Tree members | In-app directory | Search-indexed |
|---|---|---|---|---|---|
| `public` — anyone on the web | ✅ view¹ | ✅ view¹ | ✅ full | ✅ listed to everyone | ✅ sitemap + indexable |
| `site_members` — Public, Site Members | ❌ | ✅ view¹ | ✅ full | ✅ listed to logged-in users | ❌ (`noindex`) |
| `unlisted` — anyone with the link | ✅ via direct link¹ | ✅ via link¹ | ✅ full | ❌ never listed | ❌ (`noindex`) |
| `private` | ❌ | ❌ | ✅ full | ❌ | ❌ |

¹ **Every non-member view passes through the privacy engine.** Living people are
redacted, and per-person `private` hides / `public` reveals, exactly as
`person_visibility()` already does (`backend/app/services/privacy.py:100-110`).
This is the single enforcement point — no public code path may issue a raw query.

Decisions captured (2026-06-09):
- **Unlisted** = anyone with the link, no account required. The link must be
  **unguessable** (the tree UUID is already non-enumerable; do not add a public
  integer id). Unlisted trees are excluded from the directory and sitemap and
  served `noindex`.
- **Public** discovery for v1 includes **an in-app public browse/search**, not
  just search-engine indexing.
- **Public – Site Members** = *any* registered account on this instance (not an
  invite list — that is already tree membership / `private`).

## 2. Data model

`TreeVisibility` enum (`backend/app/models/enums.py`) gains a value:

```
public        # anyone on the web
site_members  # any authenticated user of this instance   <-- NEW
unlisted      # anyone with the link
private        # members only (default)
```

- Alembic migration to `ALTER TYPE tree_visibility ADD VALUE 'site_members'`
  (Postgres enum add-value cannot run inside a transaction with other DDL — use
  `op.execute` with autocommit, separate migration).
- Default stays `private`. Existing rows unchanged.
- `TreeRead`/`TreeUpdate`/`TreeCreate` schemas already carry the enum; they pick
  up the new value automatically. The OpenAPI client regen (`gen:api`) exposes it
  to the frontend.

## 3. Privacy engine

`can_view_tree()` today treats `public` and `unlisted` identically and ignores
whether the viewer is anonymous vs authenticated (`privacy.py:44-49`). Replace the
final line with explicit branching on viewer auth state:

```
if membership: return True              # members always
match tree.visibility:
  public, unlisted: return True         # anonymous OK (unlisted gated only by knowing the link)
  site_members:     return user_id is not None   # any logged-in account
  private:          return False
```

`person_visibility()` is unchanged — it already redacts living/private people for
non-members. Add focused unit tests: anonymous + each visibility; living person
redacted on public/unlisted; `site_members` denies anonymous but allows a
logged-in non-member; `private` denies both.

## 4. The anonymous read path (the careful part)

**Shipped: a dedicated read-only public API namespace**, not optional-auth on the
existing endpoints. Rationale: it is far easier to audit a small, purpose-built
surface that *always* funnels through `person_visibility` than to weaken the
membership checks on the authenticated endpoints and hope every branch is covered.

- Router `app/api/v1/public.py`, mounted at `/api/v1/public`, with an
  **optional-auth** dependency `CurrentUserOrNone` (returns `User | None`; never
  401s). Contrast with `CurrentUser` (`deps.py:30-36`) which hard-401s.
- Endpoints (read-only; no create/update/delete):
  - `GET /public/trees` — directory: lists `public` to everyone; additionally
    lists `site_members` when the caller is authenticated. Paginated, search via
    existing `pg_trgm`. Never lists `unlisted`/`private`.
  - `GET /public/trees/{id}` — tree metadata if `can_view_tree(user_or_none)`.
  - `GET /public/trees/{id}/persons`, `/persons/{pid}`, `/persons/{pid}/names`,
    `/relationships`, `/events` — each filtered through `person_visibility`.
    (Media is not exposed on the public surface yet — deferred.)
- **Redaction happens in the service, before serialization** — this is the safety
  guarantee. It did **not** ship as a separate `PublicPersonRead` schema (that
  recommendation was not adopted): the public router **reuses the member read
  schemas** (`PersonRead`, `RelationshipRead`, `EventRead`, `NameRead`), and only
  the tree projection (`PublicTreeRead`) is distinct. Safety comes from
  `public_view_service` resolving `person_visibility` and then **dropping hidden
  rows and redacting possibly-living people** (`person_service._redact` rewrites
  the name to "Living person", etc.) *before* a row is ever validated into a
  schema. No route hands a raw row to the serializer.
- **Rate limiting** on the public namespace (per-IP) is **deferred** — it is not
  implemented in the app and may be handled at the Caddy edge if needed.
- **Audit**: count public reads; do not log PII.

## 5. Frontend public pages

- New **server-rendered** routes outside the authed app shell, e.g.
  `/p/[treeId]` (tree), `/p/[treeId]/[personId]` (person), `/explore` (directory).
  Server components fetch the `/api/v1/public/*` endpoints; no login redirect.
- `robots`: ships a coarse `allow: ["/", "/p/"]` rule (`frontend/app/robots.ts`)
  that keeps the authed app out of the index. Per-tree `noindex, nofollow` meta
  for `unlisted`/`site_members` and a `public`-only **sitemap** did **not** ship —
  both are **deferred** follow-ups (per-tree noindex needs server rendering;
  meanwhile `unlisted`/`site_members` trees aren't linked or listed, so they
  aren't crawl-discoverable).
- The directory `/explore` is anonymous for `public`; shows `site_members` trees
  only to logged-in users.
- Reuse the tree/person view components where possible, fed by the redacted
  schema.

## 6. UI control

Update the visibility dropdown (`frontend/app/trees/page.tsx`, shipped in PR #41)
from 3 to 4 options with helper text:

```
Private          — only you and people you invite
Public – Members — any signed-in user on this site
Unlisted         — anyone with the link (not listed or indexed)
Public           — anyone on the web; listed and search-indexable
```

A short confirmation when switching *to* `public` ("This makes <tree> visible to
anyone on the web. Living people stay hidden.") is worthwhile given the stakes.

## 7. Guardrails / invariants

- One enforcement point: every public response is built from `person_visibility`
  output. No raw repository reads in the public router.
- Living-person protection holds regardless of tree visibility.
- Unlisted relies on UUID unguessability; never expose a sequential public id.
- Per-tree `noindex` (everything except `public`) and a `public`-only sitemap are
  **deferred** (see §5); today `robots.ts` keeps the authed app out of the index
  and `unlisted`/`site_members` trees aren't linked or listed.
- Tests gate the merge: privacy-engine matrix + an integration test that hits the
  public endpoints anonymously and asserts no living-person PII leaks.

## 8. Suggested phasing (small PRs)

1. Enum value + migration + regen client (+ dropdown → 4 options). No behavior
   change yet for non-members.
2. Privacy-engine branching + unit tests.
3. Public read API namespace (optional-auth, redacted schema, rate limit) + tests.
4. Public frontend pages (`/p/...`) + robots/sitemap.
5. In-app `/explore` directory + search.

Steps 2–3 are the privacy-critical core and should be reviewed hardest.

## 9. Open questions

- Caching: public pages are cacheable for SEO, but cache keys must not blur the
  redacted-vs-member rendering. Likely: cache only the anonymous projection at the
  edge; never cache member responses.
- Do `site_members` trees appear in the sitemap for logged-in crawling? (Default:
  no — `noindex`.)
- Per-tree opt-out of the directory even when `public`? (Probably unnecessary;
  `unlisted` already covers "reachable but not listed.")