quicproquo/design/DM_CHANNELS.md

1:1 Channel Design (MVP)

Goals

• First-class 1:1 channels (DMs) atop NodeService.
• Authz on enqueue/fetch per channel, not just recipient key.
• Privacy: MLS-encrypted payloads; metadata limited to channel ID + participants.
• Retention: 7d message retention; keypackages expire after 24h (configurable later).
• Compatibility: additive schema change with version tagging; N-1 clients can interop if they ignore new fields.

Schema changes (Cap'n Proto)

• Add channelId :Data (UUID/16B) to enqueue/fetch/fetchWait requests.
• Add version :UInt16 to NodeService messages (reject unknown > current).
• Keep recipientKey for routing; server authz uses (channelId, caller identity).

AuthZ model

• Channel membership: exactly two identities (A,B). Server stores membership map {channelId -> {a_key, b_key}}.
• Enqueue allowed if caller identity ∈ channel members; fetch/fetchWait allowed only for caller identity.
• Rate limits applied per channel and per identity (50 r/s per IP/identity, 5 MB max payload).

Storage model

• New table/map: channels with channelId, member_keys[2], created_at.
• Deliveries keyed by (channelId, recipient_key); queues retain per recipient, per channel.
• Messages carry received_at timestamp; TTL eviction at fetch time and background sweep.

Flows

• Create channel: caller provides peer identity; server generates channelId, stores membership, returns channelId.
• Send: client includes channelId + recipientKey; server authz + size/TTL checks; enqueue.
• Receive: fetch/fetchWait drains messages for (channelId, caller_key); applies TTL, returns non-expired.

Backward compatibility

• Old clients without channelId: server treats channelId=nil as legacy mode (current behavior) for interim.
• Version field allows rejecting future schema changes cleanly.

Open items

• Persistence backend: extend FileBackedStore or move to proper DB for channels + TTL metadata.
• API surface: add createChannel(channelMembers) RPC or reuse auth service.
• Client UX: map peer identity → channelId discovery; cache channelId in state file.
• Auditing: log channel create, authz failures, send/recv events with redaction.