docs: FoF-gating spec skeleton (hand-off to Opus)

Drafts the Friend-of-Friend post-gating spec with crypto specifics
marked TBD — OPUS for Opus to fill in. Six-layer implementation plan;
each layer independently shippable.

Includes README overview + six layer files:
- Layer 1: V_me vouch primitive (keys, keyring, VouchGrant wire format)
- Layer 2: Mode 2 — public post + FoF-gated comments
- Layer 3: Mode 1 — FoFClosed (encrypted body via wrap_slots + prefilter)
- Layer 4: per-post keypair rotation
- Layer 5: unlock cache + prefilter optimization (perf-critical)
- Layer 6: revocation (stub; likely deferred post-v1)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Scott Reimers 2026-04-23 23:20:56 -04:00
parent d118daee28
commit 1fdf9a94cc
8 changed files with 867 additions and 0 deletions

View file

@ -6,6 +6,32 @@ See `CONTRIBUTING.md` for the protocol. See `AGENTS.md` for the Claude-specific
---
## 2026-04-23 — primary Claude (Lead) — `docs/fof-spec-skeleton`
**Started**: late April 23 UTC
**Instance**: Scott's primary Claude (Lead role)
**Issue**: none (spec-drafting work; hand-off to Opus for crypto fill-in)
**Branch**: `docs/fof-spec-skeleton`
**Scope**: Skeleton spec for Friend-of-Friend (FoF) post gating. Lays out the per-person vouch-key (`V_me`) primitive, four visibility levels (Public / Friends-only / FoF / Custom), Mode 1 (`FOF_CLOSED`) and Mode 2 (public post + FoF comments), and a six-layer implementation plan. Crypto byte layouts and algorithm specifics are marked `TBD — OPUS` for Opus to fill in.
**Completed in this session**:
- `docs/fof-spec/README.md` — top-level overview, user-facing model, design properties, layering plan, out-of-scope, glossary, integration with existing primitives.
- `docs/fof-spec/layer-1-vouch-primitive.md``V_x` keys, per-persona keyring, `VouchGrant` wire format (DM-wrapped).
- `docs/fof-spec/layer-2-mode2-fof-comments.md``CommentPolicy::FriendsOfFriends`, `pub_post` / `priv_post` / wrap-slot primitives, `group_sig` + `vouch_mac` on comments.
- `docs/fof-spec/layer-3-mode1-fof-closed.md``PostVisibility::FoFClosed`, wrap-slot byte layout, anonymous 2B prefilter, power-of-2 slot padding.
- `docs/fof-spec/layer-4-keypair-rotation.md``PostKeyRotation` record, explicit `pub_post_index` on comments, per-post re-gating.
- `docs/fof-spec/layer-5-prefilter-and-cache.md``vouch_unlock_cache`, `vouch_unreadable_posts`, author-direct fast path, keyring-change retry sweep.
- `docs/fof-spec/layer-6-revocation.md` — stub; candidate designs AD; Lead leaning is coarse-rotation with UX polish (Candidate D); revisit after 30 days of production data.
**Pending after this PR merges**:
- Opus review pass: fill in `TBD — OPUS` markers (AEAD specifier, key sizes, WrapSlot byte layout, prefilter tag algorithm confirmation, epoch granularity, etc.).
- Lead re-review after Opus fills in crypto.
- Per-layer branch schedule for implementation (Layer 1 ships first, independently exercised).
**Stopping point**: session ending after Lead self-merges `docs/fof-spec-skeleton` to master. Branch to be deleted locally + remote.
---
## 2026-04-23 — primary Claude (Lead) — `chore/workflow-adoption`
**Started**: late April 23 UTC