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 mechanism via anonymous per-recipient wrappers in the issuer's bio post. 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}.
• Vouches are distributed via anonymous wrappers appended to the voucher's bio post, not via DM. No recipient IDs are visible on the wire.
• Clients auto-scan new/updated bio posts of people they follow; successfully unwrapped V_x keys are silently added to the receiving persona's keyring.
• Users can view who has vouched for them (from keyring) and who they've vouched for (from their own bio-post state).
• No post encryption or comment gating depends on Layer 1 yet — that arrives in Layer 2/3.

---

Lead decisions

• V_me is symmetric. 32B CSPRNG-generated. 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 includes an anonymous wrapper containing V_alice addressed to Bob's persona pubkey in her bio post. No handshake, no acknowledgment.
• Distribution channel is the bio post, not DM. Bio posts already propagate via the CDN to followers. Recipient anonymity is preserved by HPKE key privacy (see below). No new control-message type is needed. Scan-on-fetch replaces push-notification.
• Per-wrapper scheme is HPKE (RFC 9180). Per-recipient ciphertext is HPKE-sealed under the recipient's X25519 persona key. One ephemeral pubkey per bio-post batch, shared across all wrappers in that batch. Each wrapper is 48B on the wire (32B sealed V_me + 16B AEAD tag).
• HKDF info MUST be recipient-free. info = "itsgoin/vouch-grant/v1/" || bio_post_id. Including any recipient identifier in info breaks key privacy and is forbidden.
• No prefilter tag on Layer 1 wrappers. Unlike FoF post wrap slots (Layers 2–3, which use HMAC prefilter over V_x), vouch grants have no prior shared secret. Readers pay a full X25519 scalar-mult per wrapper per persona. Cost is acceptable at realistic vouch-set sizes (<40ms for 600 trials).
• Scan is follow-gated by default. Clients auto-scan bio posts of followed personas. For non-followed personas, scanning is a manual "check this person's bio for a vouch" gesture. Rationale: vouches that would be relevant to a reader overwhelmingly come from people the reader follows.
• Wrapper count padded to fixed buckets (64 / 128 / 256 / 512). Dummy wrappers are random bytes shaped identically to real wrappers. Prevents observers from reading vouch-set size off the bio post.
• Wrapper order shuffled on every publish. Prevents positional inference of which vouchee slot changed between bio-post revisions.
• Epoch tag is part of the key. Each V_x has associated (owner_id, epoch) so receivers can distinguish fresh from stale when the voucher rotates.
• Keyring is per-persona, not per-device. Multi-persona users have independent keyrings. Layer 3 reader logic iterates personas when trial-decrypting.
• Rotation is coarse. Revocation = rotate V_me, republish bio post with wrappers for the remaining vouchees. See Layer 6 for design discussion.

---

Data model

vouch_keys_own table

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

vouch_keys_own(
    persona_id     BLOB,
    epoch          INTEGER,
    key_material   BLOB(32),
    created_at_ms  INTEGER,
    is_current     INTEGER,     -- 1 for active, 0 for retained past
    PRIMARY KEY (persona_id, epoch)
)

vouch_keys_received table

Per-persona keyring — vouch keys successfully unwrapped from others' bio posts.

vouch_keys_received(
    holder_persona_id  BLOB,         -- whose keyring this entry belongs to
    owner_id           BLOB,         -- the persona who issued V_x
    epoch              INTEGER,
    key_material       BLOB(32),
    received_at_ms     INTEGER,
    source_bio_post_id BLOB,         -- provenance (which bio post we unwrapped from)
    PRIMARY KEY (holder_persona_id, owner_id, epoch)
)

vouch_bio_scan_cache table

Skips re-scanning bio posts that haven't changed since last attempt.

vouch_bio_scan_cache(
    scanner_persona_id  BLOB,
    bio_author_id       BLOB,
    bio_epoch           INTEGER,        -- bio-post revision counter
    result              INTEGER,        -- 0 = no wrapper unlocked; 1 = unlocked
    unlocked_v_x_epoch  INTEGER,        -- NULL if result=0
    scanned_at_ms       INTEGER,
    PRIMARY KEY (scanner_persona_id, bio_author_id, bio_epoch)
)

On an unchanged bio, clients short-circuit via this cache. On a bio-post update, clients trial only the new wrappers in the diff (not the full batch), bounded by bio_epoch increment.

Outbound vouches

No separate vouches_issued table. The bio post itself IS the authoritative record of whom the persona has vouched for. UI "people I've vouched for" is derived from local author-side state (the recipient pubkey list used at bio-post assembly time), stored in a simple own_vouch_targets table:

own_vouch_targets(
    voucher_persona_id  BLOB,
    target_persona_id   BLOB,
    target_x25519_pub   BLOB(32),
    granted_at_ms       INTEGER,
    current             INTEGER,       -- 1 = in latest bio-post batch, 0 = removed
    PRIMARY KEY (voucher_persona_id, target_persona_id)
)

This is local-only; never transmitted. The wire carries only anonymous wrappers.

---

Wrapper format

Bio post carries a VouchGrantBatch:

VouchGrantBatch {
    batch_eph_pub:  [u8; 32],         // shared ephemeral X25519 pubkey for this batch
    v_x_epoch:      u32,              // epoch of V_me being distributed in this batch
    wrappers:       Vec<Wrapper>,     // padded to next bucket in {64, 128, 256, 512}
}

Wrapper {
    ciphertext:  [u8; 32],            // HPKE-sealed V_me (32B key)
    tag:         [u8; 16],            // AEAD auth tag
}

Per-recipient wrapper construction (RFC 9180 HPKE sealing, single-shot mode):

shared_secret  = X25519(batch_eph_priv, recipient_x25519_pub)
key, nonce     = HKDF-Expand(
                    HKDF-Extract(salt="", ikm=shared_secret),
                    info = "itsgoin/vouch-grant/v1/" || bio_post_id,
                    L     = key_len + nonce_len
                 )
(ciphertext, tag) = AEAD-Seal(key, nonce, aad="", plaintext=V_me)

All recipients share the same batch_eph_pub; each gets a distinct wrapper derived from ECDH between that ephemeral and the recipient's persona X25519 pubkey.

Dummy wrappers: 32B random bytes + 16B random bytes. Shape-identical to real wrappers. Indistinguishable to any party lacking the voucher's target list.

TBD — OPUS (confirm): AEAD choice for HPKE. Default RFC 9180 suite DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20Poly1305 matches existing ItsGoin crypto usage; confirm no reason to prefer AES-GCM.

---

Bio-post integration

ItsGoin already has bio posts (control post with VisibilityIntent::Profile). Layer 1 adds an optional vouch_grant_batch section to the profile-post payload:

struct ProfilePostPayload {
    // ... existing fields (display_name, bio, avatar_cid, etc.) ...

    #[serde(default, skip_serializing_if = "Option::is_none")]
    vouch_grants: Option<VouchGrantBatch>,

    bio_epoch: u32,     // monotonic per-persona; incremented on every bio-post revision
}

Adding/removing a vouchee is a bio-post update: new batch, new batch_eph_pub, wrappers re-shuffled, bio_epoch incremented, republish. Propagates via the standard bio-post CDN path.

Incremental grants via bio-post comments (deferred): Scott's variant of appending additional wrappers as author-only comments on the bio post (to avoid full republish on every small change) is a future optimization. v1 ships with full republish per change; simpler mental model and keeps the wire contract symmetric. Revisit if bio-post bandwidth becomes a concern.

---

Reader / scanner behavior

On follow (new)

1. Fetch the followed persona's latest bio post.
2. If vouch_grants.is_some() AND (scanner_persona, bio_author, bio_epoch) not in scan cache:
   • For each persona P in the reader's persona set:
     • For each wrapper in the batch:
       • Derive shared_secret = X25519(P.x25519_priv, batch_eph_pub).
       • Derive key, nonce = HKDF(shared_secret, info="itsgoin/vouch-grant/v1/" || bio_post_id, ...).
       • Attempt AEAD-Open(wrapper.ciphertext, wrapper.tag, key, nonce).
       • On success: extract V_me, insert into vouch_keys_received as (holder=P, owner=bio_author, epoch=v_x_epoch). Record scan-cache hit.
3. If no wrapper unlocked across any persona: record scan-cache miss. Done.

On bio-post update (existing follow)

Same as above, but trial only the wrappers that are new relative to the prior bio_epoch. Since wrappers are shuffled on every publish, "new wrappers" = all wrappers on every update. TBD: whether to persist the exact wrapper-ciphertext set per bio_epoch so deltas can be computed, or just rescan the full batch (pay the cost, skip the bookkeeping). Lead leaning: rescan full batch; the cost (~40ms × number of followed personas publishing updates) is tolerable and the bookkeeping adds state-sync complexity.

On manual "check bio" gesture

Treat as new-follow scan. User-invoked. Useful when a non-followed persona has vouched for the user.

Multi-persona trial order

Personas iterated in stable sorted order (by persona_id). First unlock wins; stop scanning wrappers once any persona succeeds on any wrapper (the wrapper was addressed to that persona specifically — other wrappers in the batch are for other recipients).

TBD — OPUS: confirm early-exit is correct. One caveat: the voucher may grant to MULTIPLE of the reader's personas (e.g., "I vouch for your work-persona AND your private-persona"). In that case we want to unlock all matching wrappers, not just the first. Lead leaning: do not early-exit on persona; continue scanning with remaining personas so all applicable grants are received.

---

Cost analysis

Per wrapper per persona: 1 X25519 scalar mult + 1 HKDF + 1 AEAD-Open attempt. ~60µs on ARM mobile; faster on desktop.

Typical bio update: 200 wrappers × 3 personas = 600 trials ≈ 36ms. Invisible to user.

Padded bucket at 512 × 3 personas = 1536 trials ≈ 90ms. Still acceptable for a one-time ingest per bio update.

Scan-cache prevents re-pay on unchanged bios.

---

UI / UX

Minimum viable surface for Layer 1 ship:

• Persona screen: "Vouch for someone" action. Picker of contacts. Adds their persona to own_vouch_targets; republishes bio post with new batch on save.
• Persona screen: "Who has vouched for me" list (reads vouch_keys_received grouped by owner_id).
• Persona screen: "People I've vouched for" list (reads own_vouch_targets where current = 1).
• Settings: "Rotate my vouch key" → generates new V_me epoch, republishes bio post with wrappers under the new key for every current target.
• Post detail: manual "Check this person's bio for a vouch for me" button (non-followed author case).

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

---

Privacy properties (Layer 1 scope)

• Recipient anonymity. HPKE key privacy: wrapper ciphertext reveals nothing about the recipient's pubkey. Only trial decryption identifies recipients.
• No identifiers on the wire. No recipient NodeIds, no persona IDs, no derived recipient tags in the bio post.
• Set-size opacity. Bucket padding hides actual vouch-set size to within 2× granularity.
• Rotation unobservability. Shuffled wrapper order per publish prevents positional inference of which slot changed.

Timing leak is acknowledged: a bio-post update with a changed vouch set leaks "someone new was vouched for today" to observers who see the update. Batching (daily cadence instead of immediate) would blur this; out of scope for v1.

---

Open questions

• Batching cadence. Immediate (republish on every vouch-add) vs daily-batched (aggregate changes). Lead leaning: immediate in v1; observe whether timing leak is a concern in practice.
• Dummy-wrapper count strategy. Always pad to next bucket, or pad to a fixed persona-local target size (e.g., "always 128")? Fixed target hides growth trajectory but wastes bandwidth early on. Lead leaning: next-bucket padding.
• V_me in identity export. Losing V_me means every FoF post gated under it becomes permanently unreadable for every vouchee. Lead leaning: include vouch_keys_own (current + retained epochs) AND vouch_keys_received in persona export bundles.
• Rescan triggering. Scan on fetch of the bio post is natural. Should we also opportunistically rescan on keyring-change events (when the persona acquires a new X25519 keypair — unlikely but possible during import)? Lead leaning: yes, rescan-on-keyring-change, cheap.
• Bio post size. 512 wrappers × 48B = 24KB of vouch-grant payload. Plus ephemeral pubkey, epoch, headers. Negligible relative to profile-post overhead including avatars. No concern.
• Does the scanner need to verify the voucher's identity sig over the batch? Bio posts are already signed by the author's identity key, so the VouchGrantBatch inherits that signature. Forgery requires identity-key compromise (out of FoF scope).

---

Ship criteria for Layer 1

• All personas auto-generate V_me at creation.
• Bio-post publish path can embed a VouchGrantBatch.
• own_vouch_targets table tracks who the persona has vouched for locally.
• vouch_keys_received populated via auto-scan on bio-post fetch; gated to followed personas + manual gesture.
• vouch_bio_scan_cache prevents re-scanning unchanged bios.
• UI: vouch someone, list given vouches, list received vouches, rotate V_me.
• No change to post visibility / comment behavior.
• HPKE wrapper construction matches RFC 9180 with recipient-free info.
• Bucket-padding + per-publish wrapper shuffle implemented.
• Integration test: two personas on two devices. A vouches for B. B auto-scans A's bio post after follow. B's vouch_keys_received contains V_alice at the correct epoch. B un-follows A then manually scans: same result. A rotates V_me, republishes. B auto-rescans, gets new epoch.