SuperChat V3 Specification

Overview

V3 adds advanced channel features and privacy features. All V3 features maintain backward compatibility with V1/V2 clients.

V3 Status: Complete ✅

V3 Feature List

1. Subchannels ✅

Status: Complete Priority: High

Implementation Summary:

  • Two-level channel hierarchy using parent_id on Channel table (subchannels are channels with a parent)
  • Permission check: only channel owner or server admin can create subchannels
  • Terminal client: expandable tree UI in channel sidebar
  • Desktop client: needs update (uses same protocol)

Protocol Messages Implemented:

  • Client → Server: CREATE_SUBCHANNEL (0x08), GET_SUBCHANNELS (0x15)
  • Server → Client: SUBCHANNEL_CREATED (0x88), SUBCHANNEL_LIST (0x96)
  • CHANNEL_LIST updated with HasSubchannels and SubchannelCount fields

Database Migration:

-- 010_add_subchannels.sql
ALTER TABLE Channel ADD COLUMN parent_id INTEGER REFERENCES Channel(id) ON DELETE CASCADE;
CREATE INDEX IF NOT EXISTS idx_channel_parent ON Channel(parent_id) WHERE parent_id IS NOT NULL;

Files Modified:

Server:

  • pkg/database/migrations/010_add_subchannels.sql - Add parent_id to Channel
  • pkg/database/database.go - CreateSubchannel, GetSubchannels, GetSubchannelCount, updated ListChannels/GetChannel
  • pkg/database/memdb.go - Same operations with in-memory caching
  • pkg/server/handlers.go - handleCreateSubchannel, handleGetSubchannels, broadcastSubchannelCreated
  • pkg/server/server.go - Message dispatch for new types

Protocol:

  • pkg/protocol/messages.go - Message types (0x08, 0x15, 0x96), structs, encode/decode
  • pkg/protocol/messages_test.go - Tests for new message types

Terminal Client:

  • pkg/client/ui/model.go - expandedChannelID, subchannels state, ChannelListItem helper
  • pkg/client/ui/view.go - Expandable tree rendering with ▸/▾ indicators
  • pkg/client/ui/update.go - Cursor navigation, expand/collapse, subchannel handlers
  • pkg/client/ui/modal/create_subchannel.go - Create subchannel modal
  • pkg/client/ui/modal/types.go - ModalCreateSubchannel type

Terminal Client UX:

#general              <- regular channel, Enter → threads
#dev ▸           [3]  <- has 3 subchannels, Enter → expand
#dev ▾                <- expanded:
  #frontend           <- subchannel, Enter → threads
  #backend
  #devops
#random

Keys: Enter=expand/collapse/navigate, s=create subchannel, Esc=collapse

2. Direct Messages (DMs) ✅

Status: Complete Priority: Medium

Implementation Summary:

  • Private DM channels between users (not in public channel list)
  • Encryption status tracking (not possible / required / optional)
  • Support for both registered and anonymous users
  • DM request/accept flow with encryption negotiation

Protocol Messages Implemented:

  • Client → Server: START_DM (0x19), ACCEPT_DM (0x1A), REJECT_DM (0x1B), PROVIDE_PUBLIC_KEY (0x18)
  • Server → Client: DM_READY (0xA2), DM_PENDING (0xA3), DM_REQUEST (0xA4)

Database Changes:

  • is_dm flag on Channel table
  • ChannelAccess table for DM participant tracking
  • encryption_public_key on User table for X25519 keys
  • Migration: 011_add_direct_messages.sql

Files Modified:

  • pkg/database/database.go - CreateDMChannel, GetDMChannels, ChannelAccess operations
  • pkg/server/handlers.go - handleStartDM, handleAcceptDM, handleRejectDM
  • pkg/protocol/messages.go - DM message types and structs
  • pkg/client/ui/ - DM UI, request modal, encryption status display

3. End-to-End Encryption ✅

Status: Complete (integrated with DMs) Priority: Medium

Implementation Summary:

  • X25519 key exchange for DM encryption negotiation
  • Encryption status per DM (not possible / required / optional)
  • Session-only keys for anonymous users
  • Public keys stored on User table for registered users

Security Features:

  • Keys generated using Go's crypto package
  • Encryption public keys tracked per user/session
  • DM encryption status communicated during request flow

4. Message Compression ✅

Status: Complete Priority: Low

Implementation Summary:

  • Protocol version bumped to v2 (v1 = no compression, v2 = LZ4 compression)
  • LZ4 compression for payloads ≥ 512 bytes (CompressionThreshold)
  • Version-aware: EncodeFrame(w, f, peerVersion) only compresses for v2+ peers
  • Wire format: [Uncompressed Size (4 bytes)][LZ4 Compressed Data]
  • Falls back to uncompressed if compression doesn't reduce size

Backward Compatibility:

  • v2 clients can connect to v1 servers (no compression used)
  • v2 servers track each client's version and only send compressed frames to v2 clients
  • Broadcasts encode twice (v1 and v2 versions) and send appropriate version to each client
  • Server-to-server communication respects peer version

Forward Compatibility:

  • Best effort communication with unknown future versions
  • Compression used for v2 up to current ProtocolVersion (so bumping version doesn't break compression)
  • No compression for versions > ProtocolVersion (unknown, conservative)
  • Core protocol operations (handshake, verification) work with any version

Protocol Impact:

  • No new protocol messages needed
  • Uses existing flags byte (bit 0 = compression)
  • EncodeFrame takes optional peerVersion parameter

Files Modified:

  • pkg/protocol/frame.go - Added compression functions, version-aware EncodeFrame()
  • pkg/server/session.go - Added ProtocolVersion field to track client version
  • pkg/server/handlers.go - Version-aware broadcasts with encodeFrameVersionAware()
  • pkg/server/server.go - Server-to-server version tracking
  • pkg/client/connection.go - Store server version, pass to EncodeFrame

Usage:

// EncodeFrame with peer version (compression only for v2+ peers)
err := EncodeFrame(writer, frame, peerVersion)

// DecodeFrame automatically decompresses
frame, err := DecodeFrame(reader)
// frame.Payload is decompressed, FlagCompressed is cleared

5. Web Client ✅

Status: Complete Priority: Medium Implemented: Desktop app with Wails (superchat-desktop/)

The web/desktop client was implemented using Wails with a React/TypeScript frontend, providing a native desktop experience while leveraging web technologies.

Implementation Priority

All V3 features complete:

  1. Subchannels ✅ Complete
  2. Direct Messages + Encryption ✅ Complete
  3. Message Compression ✅ Complete
  4. Web/Desktop Client ✅ Complete

Database Schema Changes (V3)

Migrations

  • 010_add_subchannels.sql ✅ - Add parent_id to Channel table
  • 011_add_direct_messages.sql ✅ - ChannelAccess table, Channel.is_dm flag, User.encryption_public_key
  • Message compression requires no schema changes (protocol-level only)

Testing Requirements

All V3 features must meet coverage requirements:

  • Protocol package: 90%+ coverage (enforced)
  • Server package: 80-90% coverage
  • Encryption: 95%+ coverage (security-critical)
  • Database migrations: Path tests validating data integrity

Migration tests must include:

  • Schema validation (tables, indexes, constraints)
  • Data integrity validation (existing data preserved)
  • Upgrade path testing (v2→v3)
  • Encryption key migration if applicable

Security Considerations

V3 introduces encryption and private messaging:

  1. Encryption:

    • Validate all string inputs for length and content
    • Use established crypto libraries (Go's crypto package)
    • Proper random number generation for keys/nonces
    • Secure key storage (encrypted at rest)
    • Never log encrypted message content or keys

  2. Direct Messages:

    • Access control (only participants can read DMs)
    • Prevent DM spam (rate limiting on DM creation)
    • Key verification (prevent MITM attacks)

  3. Key Management:

    • Support key rotation
    • Handle compromised keys gracefully
    • Allow users to revoke keys
    • Multiple keys per user for device management

Client UI Updates Needed (V3)

Subchannels: ✅ Complete (terminal client)

  • Channel sidebar: expandable tree with ▸/▾ indicators
  • Subchannel creation modal (channel owner/admin only)
  • Desktop client needs update to match

Direct Messages:

  • DM list view (separate from channels)
  • DM creation: user search/selection
  • Encryption setup flow:
    • Key generation/import UI
    • Encryption preference (always/once/never)
    • Key verification UI
  • Lock icon for encrypted DMs

Message Compression:

  • No UI changes needed (transparent to user)
  • Optional: show compression indicator in debug mode

V3 → V4 Boundary

V4 features (future, not planned yet):

  • Multi-party DMs (3+ participants)
  • Read receipts (opt-in)
  • Typing indicators
  • Message reactions
  • Server-to-server federation
  • Voice/video chat (out of scope - see CLAUDE.md)

References

  • Protocol: See docs/PROTOCOL.md for complete message specifications
  • V1 Spec: See docs/versions/V1.md for V1 implementation
  • V2 Spec: See docs/versions/V2.md for V2 implementation
  • Data Model: See docs/DATA_MODEL.md for full database schema
  • Migrations: See docs/MIGRATIONS.md for migration system guide

Note: V3 is complete. All features implemented: Subchannels, Direct Messages with Encryption, Message Compression, Web/Desktop Client.