feat: Enable private rooms with automatic secret distribution

[sanity]

Summary

River has a nearly-complete private room implementation that is currently disabled. The encryption infrastructure (AES-256-GCM symmetric + ECIES key distribution), data model (PrivacyMode, SealedBytes, RoomSecretsV1), contract validation, message encryption/decryption, and secret rotation are all fully implemented and tested. The UI checkbox is hardcoded to false with "Private rooms temporarily disabled".

Why it was disabled (commit 58ab2e7): "non-functional without owner online" — the room owner must be online to distribute the room secret to new/returning members. In a decentralized system where peers aren't always online, this makes private rooms unreliable.

Proposed Design

Core idea: any member can distribute secrets

Instead of requiring the owner to distribute room secrets, any member who has the secret can encrypt it for a new member. The chat delegate uses the existing V2 delegate-contract interaction host functions (get_contract_state, update_contract_state, subscribe_contract) to watch for new members and automatically distribute secrets.

Invitation flow

Invitations are posted as a special message type in the shared public room where both users are already present. The invitation contains the private room's contract key (which is not sensitive — knowing the key without the room secret is useless).

Why public invitations are a feature, not a limitation:

• Spam/auto-invite behavior is visible to room members and the owner, who can ban abusers
• Creates social accountability — you can see who's inviting whom
• Only metadata leaked is "Alice invited Bob to a private room" — not the room's content, name, or other members
• Dramatically simpler than a per-user inbox contract approach (which would require related contract validation)

UX

Two actions when clicking a username (in message header or member list):

1. "Private chat" — Creates a new 2-person private room, posts invitation in the shared room
2. "Invite to room" — Posts invitation for an existing private room the user owns/is a member of

Invitation renders as a clickable card in the shared room. Bob clicks to accept.

Delegate behavior

The chat delegate would:

1. Subscribe to each private room contract the user is a member of
2. On new member detected (via contract state change notification): if the new member lacks an encrypted secret entry and we have the room secret, encrypt it for them and update the contract
3. Persist room list in delegate context so it re-subscribes after restart

Concurrent secret distribution

Multiple members may independently encrypt the secret for the same new member. This is fine — ECIES produces different ciphertexts (randomized ephemeral keys) but they all decrypt to the same room secret. The contract merge deduplicates encrypted_secrets by (member_id, secret_version), keeping whichever entry arrives first.

Implementation Steps

1. New Invitation message type in the room contract — contains private room contract key, posted in shared rooms
2. UI rendering of invitation messages as clickable cards
3. Delegate contract subscription — subscribe to private room contracts, react to member changes
4. Automatic secret distribution in the delegate — encrypt room secret for new members using V2 host functions
5. Delegate context persistence — store list of private room contract keys for re-subscribe on restart
6. Re-enable UI toggle — remove hardcoded false in create_room_modal.rs, restore the reactive signal
7. Contract merge logic — deduplicate encrypted_secrets entries for concurrent distribution
8. CLI support — add --private flag to riverctl room create

What Already Exists

Component	Status
Encryption (AES-256-GCM + ECIES)	✅ Complete
Data model (PrivacyMode, SealedBytes, RoomSecretsV1)	✅ Complete
Contract validation (enforces encryption in private rooms)	✅ Complete
Message encryption/decryption in UI	✅ Complete
Secret rotation (versioning + UI button)	✅ Complete
Tests (660+ lines in private_room_test.rs + crypto tests)	✅ Complete
V2 delegate-contract host functions (freenet-core)	✅ Complete
UI creation toggle	⚠️ Disabled (hardcoded false)
CLI --private flag	❌ Missing
Delegate contract interaction (in River)	❌ Not yet used
Invitation message type	❌ Not yet implemented

Questions for Discussion

• Should invitation cards show the room name (decryptable only by invitee) or just "Alice invited you to a private room"?
• Should there be a confirmation step before accepting an invitation, or should the delegate auto-accept and just notify the user?
• Should room owners be able to configure whether any member can invite, or only the owner?
• Is the public invitation metadata leak acceptable for all use cases, or should we also support a private invitation path (per-user inbox contracts) for higher-security scenarios?

[AI-assisted - Claude]

[ple1n]

Per-user contract, I expect, would incur extra routing cost and offer less stability because a new contract is less cached, and both creating and accessing requires extra route-hopping. This hopping can be very annoying in bad networking conditions. There is a need to care for locality (and this shouldn't be automated, much like how you use memory).

I dont think there is a need to disclose secret key recipient. Only sender needs to be public.

For large rooms we use keys of 256bit random number (post quantum). For 1-to-1 rooms we can consider deriving keys directly from DH key exchange or equivalent protocols of post quantum cryptography, and `hmac(exchanged-key, session_random)

I think it needs,

• invite reason (public)
• room title (encrypted)

for the said locality optimization, it might be good to store 1-to-1 private DM rooms invites in a public room. public sender with private invitee would be good for current iteration.

[sanity]

Issue Priority Assessment

Generated: 2026-03-12T22:34:54.512362393+00:00
Issue hash: 172124f8

Value Assessment

Relevance: the “private rooms temporarily disabled” code is still in place—create_room_modal hardcodes private = false when producing the new room and renders a disabled checkbox with that exact warning (ui/src/components/room_list/create_room_modal.rs:25-36, :126-135). The CLI room create command only accepts --name and --nickname with no --private flag (cli/src/commands/room.rs:18-45), so there is no non-UI path to opt in either. On top of that, the code path that would have rotated or generated member secrets is still commented out inside sync_info::needs_to_send_update, and the comment explicitly references the infinite-loop bug and promises to “move this logic to a separate periodic task” (the disabled block at ui/src/components/app/sync_info.rs:187-209), meaning the automatic secret-distribution hook described in issue #140 is still missing.

User impact: because the UI and CLI both refuse to mark a room as private, end users cannot create private rooms even though the rest of the encryption stack exists. The modal’s disabled checkbox is the only surface ever exposed to the user, so everyone is funneled into public rooms while the backend secrets and rotation helpers sit unused. Since sync_info avoids calling RoomData::generate_missing_member_secrets, private room members can’t receive secrets automatically, making private rooms unreliable even if someone manually set privacy_mode elsewhere—this is the failure mode the issue is trying to fix.

Strategic alignment & blocking: River’s decentralized, privacy-first vision depends on fully encrypted rooms. The implementation described in #140—invitation messages, delegate subscriptions, and member-side secret distribution—would finally unlock that story. Today the chat delegate is still confined to signing and key-value storage requests and explicitly rejects contract notifications or subscribe responses (delegates/chat-delegate/src/lib.rs:33-106), so there is nowhere to implement the “any member can distribute secrets” flow the issue proposes. Without these pieces, the private room contract validation and secret-handling tests remain academic, and invitations cannot be handled inside the shared room as described.

Urgency: enabling private rooms is not a one-off cosmetic tweak; it is the only way to deliver the private-chat promise that River advertises. It doesn’t block every other feature but it does keep the most privacy-sensitive use cases on hold and leaves the work that depends on invitations or private invitations (UI cards, delegate reactions, CLI flags) incomplete. Prioritizing #140 would unblock those dependent pieces and let testing (playwright/e2e) stop failing on the “create private room” case, so its completion is worthwhile soon rather than indefinitely deferred.

Cost Assessment

Private rooms are still intentionally disabled even though the underlying mechanics are wired up: CreateRoomModal hard‑codes let private = false and greys out the checkbox because the UI never exposes the signal (ui/src/components/room_list/create_room_modal.rs:24‑136), and there’s no CLI flag to flip the switch (cli/src/commands/room.rs:10‑80, cli/src/api.rs:89‑197). That hardcoding is the only part of the issue that has drifted—Rooms::create_new_room_with_name already accepts an is_private boolean and generates a secret version/ciphertext, and RoomSecretsV1 plus PrivacyMode, SealedBytes, and the AES/ECIES helpers in common/src/room_state/privacy.rs and common/src/room_state/secret.rs already validate the encrypted blobs. So the issue is still actionable, but enabling private rooms now would expose the gaps the issue is trying to solve rather than being blocked by upstream refactors.

Delivering the rest of the design cuts across many layers. On the UI side we’d need a new invitation/content type (common/src/room_state/content.rs) plus rendering for that type in the conversation renderer (ui/src/components/conversation.rs), clickable cards/messages, and the “Private chat” / “Invite to room” actions in the member list so that both public rooms and members can post those invites (ui/src/components/members.rs). The delegate and contract stack also need work: the chat delegate currently only handles key‑value requests (delegates/chat-delegate/src/handlers.rs) and doesn’t subscribe to other contracts or persist a private‑room registry (the only persisted structure today is KeyIndex in delegates/chat-delegate/src/context.rs), so we’d have to teach it to watch private contracts, persist contract keys, detect missing encrypted secrets, encrypt via the ECIES helpers, and call the V2 host functions to update the contract. On the server/contract side RoomSecretsV1::apply_delta currently rejects duplicate (member_id, secret_version) entries; to tolerate concurrent distribution we have to dedupe there (and in the contract version of the same state, contracts/room-contract/src/lib.rs would have to mirror that behavior) while still enforcing signature verification of every encrypted secret (common/src/room_state/secret.rs:123‑220). Finally, the CLI needs a --private option wired through from RoomCommands::Create to ApiClient::create_room so scripts can create private rooms the same way as the UI.

The complexity is high because the delegate change introduces new async flows and new state that must keep UI, stored room data, and contract state in sync without the owner being online, and the contract/state rules are security critical (every secret/encrypted secret continues to be signed and validated and the has_complete_distribution helper will reject new messages unless the delegation succeeds). Mistakes here risk breaking private rooms entirely or relaxing the authorization invariants described in AGENTS.md, so this work needs expanded unit/integration coverage (common/tests/private_room_test.rs, contracts/room-contract/tests, delegate unit tests for host function behavior) plus the Playwright layout checks that are required before any Freenet publish. There are no new third‑party dependencies, but verifying the new flows still requires the usual freenet local tooling, Playwright runs, and delegate testing against a local node, so expect more end‑to‑end validation than usual.

---

Generated by issue-prioritizer