provenance/docs/design/tree-visibility.md

Design note: tree visibility & the public viewing surface

Status: proposed (design only — no code yet). Owner: Justin. Created 2026-06-09.

This is a privacy-critical change (it creates the first anonymous read surface in Provenance). Per CLAUDE.md, design before code. Implementation should land in small, individually-reviewable PRs, with tests on the privacy engine and the public read path before any anonymous endpoint is 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)

Recommendation: 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.

• New 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}, /relationships, /events, /media, … — each filtered through person_visibility, returning redacted projections (a PublicPersonRead that omits PII for redacted people: no exact dates, no living-person names beyond "Living", etc.).
• A redacted response schema, distinct from the member PersonRead, so the serializer physically cannot emit fields a non-member shouldn't see. Redaction happens in the service, not the route.
• Rate limiting on the public namespace (per-IP) to blunt scraping/enumeration.
• 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: allow + sitemap for public; noindex, nofollow meta for unlisted and site_members. Sitemap lists only public trees/persons.
• 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 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.
• noindex everything except public; sitemap is public-only.
• 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.")