itsgoin/docs/fof-spec/layer-1-vouch-primitive.md

# Layer 1 — Vouch Primitive

**Scope**: Introduce `V_x` vouch keys, per-persona keyring storage, and a distribution/exchange mechanism. No post-gating yet — this layer ships first so the primitive is in place and UI-exercised before any post encryption depends on it.

---

## Goal

After Layer 1 ships:

- Each persona owns a current `V_me` symmetric key. New personas auto-generate one at creation.
- Each persona has a keyring of received vouch keys: `{V_x : x has vouched for me}`.
- Users can view who they've vouched for, who has vouched for them, and revoke/rotate `V_me`.
- Wire protocol can transfer `V_me` from voucher to vouchee inside an existing encrypted channel.
- No post encryption or comment gating depends on Layer 1 yet — that arrives in Layer 2/3.

---

## Lead decisions

- **`V_me` is symmetric, not asymmetric.** Every vouchee holds the same `V_me`. This is the property that makes FoF reach emergent (wrap under `V_x`, anyone `x` vouched for decrypts).
- **Distribution is unilateral.** Alice vouching for Bob = Alice gives Bob a copy of `V_alice`. No request/accept handshake. Bob can immediately read FoF posts that include `V_alice` as a wrap slot.
- **Revocation = rotate `V_me`.** There is no per-vouchee revocation. To un-vouch someone, the persona generates a new `V_me'` and re-distributes to every remaining vouchee. Layer 6 stub.
- **Epoch tag is part of the key.** Every `V_x` has an associated `(owner_id, epoch)` so receivers can tell fresh from stale when multiple copies arrive (e.g., if voucher rotated).
- **Keyring is per-persona, not per-device.** Multi-persona users have independent keyrings. Layer 3 reader logic iterates personas when trial-decrypting.

---

## Data model

### `vouch_keys_own` table

Per-persona, stores the persona's own `V_me` history (current + recent-past for graceful rotation).

TBD — OPUS: exact column types, key size in bytes, how many past epochs to retain.

```
vouch_keys_own(
    persona_id         BLOB,
    epoch              INTEGER,
    key_material       BLOB,      -- TBD — OPUS: symmetric key bytes (32B for a 256-bit key?)
    created_at_ms      INTEGER,
    is_current         INTEGER,   -- 1 for the active V_me, 0 for retained past epochs
    PRIMARY KEY (persona_id, epoch)
)
```

### `vouch_keys_received` table

Per-persona, stores vouch keys received from other personas (one row per `(owner_id, epoch)` currently held).

```
vouch_keys_received(
    holder_persona_id  BLOB,      -- whose keyring this entry belongs to
    owner_id           BLOB,      -- the persona who owns (issued) this V_x
    epoch              INTEGER,
    key_material       BLOB,
    received_at_ms     INTEGER,
    PRIMARY KEY (holder_persona_id, owner_id, epoch)
)
```

Readers compute their keyring as `SELECT key_material FROM vouch_keys_received WHERE holder_persona_id = ? UNION SELECT key_material FROM vouch_keys_own WHERE persona_id = ? AND is_current = 1`.

---

## Key generation

TBD — OPUS: specify the primitive. Candidates:

- Random 32B from CSPRNG (simplest; `V_me` is pure symmetric secret)
- HKDF-derived from persona identity key + epoch counter (allows deterministic re-derivation; couples key rotation to identity key exposure)

Lead leaning: **random 32B CSPRNG, stored encrypted at rest alongside identity key material**. Identity-key coupling offers no defensive benefit given the keyring is already indexed per-persona in the same DB.

---

## Wire format for vouch distribution

A `VouchGrant` message carries a copy of the voucher's current `V_me` from voucher to vouchee.

TBD — OPUS: exact byte layout. Target shape:

```
VouchGrant {
    voucher_persona_id:  NodeId,        -- sender's persona
    epoch:               u32,
    key_material:        [u8; 32],      -- V_voucher at this epoch
    issued_at_ms:        u64,
    sig:                 [u8; 64],      -- voucher's identity-key signature over the above
}
```

Delivery: wrap `VouchGrant` inside the existing `Direct` (encrypted-to-one-recipient) post primitive. Do not introduce a new top-level control message. Content-type byte distinguishes vouch grants from regular DMs. Recipient's receive-path decodes, verifies signature, inserts into `vouch_keys_received`.

TBD — OPUS: decide whether vouch grants should use a reserved visibility intent (`VisibilityIntent::VouchGrant`) for filtering out of the Messages tab, or whether they ride under `Direct` and are suppressed client-side by content-type.

---

## UI / UX

Minimum viable surface for Layer 1 ship:

- **Persona screen**: "Vouch for someone" button. Picker of contacts. Hands them a `V_me`.
- **Persona screen**: "Who has vouched for me" list (reads `vouch_keys_received` grouped by `owner_id`).
- **Persona screen**: "People I've vouched for" list (local-only; TBD — OPUS on whether to track this explicitly or derive from DM-sent history — see open question below).
- **Settings**: "Rotate my vouch key" button → generates new epoch, queues re-distribution to tracked vouchees.

Layer 1 ships without any post/comment behavior change. Vouches are visible in UI but don't gate content yet.

---

## Open questions

- **Do we track outbound vouches explicitly?** Option A: local `vouches_issued(recipient_persona_id, epoch_at_grant)` table. Option B: derive from DM-sent history searching for `VouchGrant` payloads. A is simpler + survives DM history loss; B avoids a redundant record. Lead leaning: A.
- **Re-distribution on rotation.** When persona rotates `V_me`, do we auto-queue `VouchGrant` DMs to every tracked vouchee, or require user-initiated re-vouch? Lead leaning: auto-queue with a confirmation summary ("rotate will re-send vouch to N people").
- **Key size.** 256-bit symmetric key is standard and matches our ChaCha20-Poly1305 usage. Confirm with Opus there's no reason to prefer 192 or 128 bits.
- **Epoch granularity.** Monotonic counter per persona, or wall-clock-based? Counter is simpler; wall-clock aids debugging. Lead leaning: counter.
- **Should `V_me` ever be exported in the persona backup bundle?** Losing `V_me` means every FoF post gated under it becomes permanently unreadable for every vouchee. Lead leaning: yes, include in identity export.

---

## Ship criteria for Layer 1

- All personas auto-generate `V_me` at creation.
- Users can vouch and receive vouches end-to-end via DM-wrapped `VouchGrant`.
- UI shows received and issued vouches per persona.
- `V_me` rotation works; re-distribution to tracked vouchees is demonstrated.
- No change to post visibility / comment behavior.
- Integration test: two personas on two devices, Alice vouches for Bob, Bob's `vouch_keys_received` contains `V_alice` with correct signature.