claudemesh/.artifacts/specs/2026-04-15-per-peer-capabilities.md

Per-Peer Capabilities

Goal

Give mesh members fine-grained control over what peers can do to their session. Today: any mesh peer can send you any message; all messages get pushed as <channel> reminders. Users can't say "only @alice can send me messages," "read-only peers," or "@bob can broadcast but not DM."

Current state

• Mesh-level role: admin | member (only affects invite issuance)
• No per-peer filter — every peer message is delivered
• No per-peer read/write split (all peers have the same capabilities)

Target capability model

Capability	Meaning
read	Peer appears in your list_peers, can see your summary
dm	Peer can send you direct messages
broadcast	Peer's group broadcasts reach you
state-read	Peer can read shared state keys
state-write	Peer can set shared state keys
file-read	Peer can read files you've shared (already exists)

CLI surface

claudemesh grant @alice dm broadcast   # allow direct + broadcast
claudemesh grant @bob state-read       # read-only
claudemesh revoke @alice broadcast
claudemesh grants                       # list current grants per peer
claudemesh block @spammer               # shorthand for revoke-all

Broker schema

New column on mesh_member:

peer_grants jsonb DEFAULT '{}'::jsonb
  -- shape: { "<peer_pubkey_hex>": ["dm", "broadcast", ...] }

Alternative (cleaner): separate peer_grant table keyed on (member_id, target_pubkey).

Enforcement point

Broker's message router (apps/broker/src/index.ts — send flow). Before writing the encrypted message to the recipient's queue, check recipient.peer_grants[sender_pubkey] against message kind. Drop silently if disallowed (sender sees delivered, recipient sees nothing — matches Signal/iMessage block semantics).

Defaults

• Unknown peers: read + dm (matches current behavior — additive-safe rollout)
• Existing members: grandfathered into read + dm + broadcast + state-read via a migration
• claudemesh profile --default-grants read dm lets users change their own default

UI

• claudemesh peers renders a [grants: dm,broadcast] tag per peer
• claudemesh verify gains a --with-grants flag that shows the grant set alongside the safety number (helps the "did I accidentally block them?" check)

Crypto implications

Grants are server-enforced metadata. Not capability tokens. A malicious broker could forward messages regardless — this is about UX trust (spam / noise control), not protocol security. The spec is clear about this.

Migration plan

1. Ship broker schema change (jsonb column, nullable, default {}).
2. Ship grant/revoke/grants/block CLI commands against an unused column.
3. Enable enforcement in broker behind a per-mesh feature flag.
4. Flip on for all meshes.

Priority

Nice-to-have. The killer feature here is block — every mesh gets a bad actor eventually. Ship block first even if the full grant system is deferred.