ttychat

ttychat is a privacy-focused terminal messenger for direct peer-to-peer communication over Tor hidden services. It combines authenticated end-to-end encryption with local encrypted storage and an operator-friendly CLI.

Overview

ttychat is built for users who want secure messaging primitives without centralized identity providers or phone-number-based onboarding.

Challenge	ttychat approach
Centralized service dependency	Direct peer-to-peer transport over Tor hidden services
Metadata leakage from IP addresses	Onion routing for endpoint network privacy
Key trust and identity spoofing risk	Fingerprints, verification flow, TOFU pinning, key-change detection
Delivery on intermittent connectivity	Local encrypted queue with retry backoff and jitter

Core Capabilities

• End-to-end encryption: X25519 key exchange plus AES-GCM message protection
• Message authentication: Ed25519 signatures with verification enforcement
• Transport privacy: Tor hidden-service communication
• Encrypted persistence: SQLCipher-backed local storage
• Trust lifecycle: contact verification, fingerprint display, key rotation
• Reliability controls: delivery receipts, retry scheduling, manual retry-now
• Attachment support: encrypted file transfer plus integrity hashing
• Auditability: security event log and audit export/rotation tools
• Terminal workflows: CLI-first operations and minimal Bubble Tea inbox view

Requirements

• Go 1.24+
• Tor binary available in PATH for runtime transport checks and daemon operations
• C toolchain and CGO enabled for SQLCipher/sqlite driver usage

Build

git clone https://github.com/voidsgnl/ttychat.git
cd ttychat
go mod tidy
go build -o ttychat.exe .

Quick Start

ttychat start

# Optional: share and import invite codes directly
ttychat identity show-code
ttychat contact add-code <invite_code>

# Open inbox directly on later runs
ttychat inbox

Manual setup (advanced):

ttychat init
ttychat daemon start

ttychat contact add \
  --name alice \
  --onion aliceexample123.onion \
  --enc-pubkey <alice_x25519_public_key> \
  --sign-pubkey <alice_ed25519_public_key>

ttychat contact verify alice
ttychat send alice "hello"
ttychat read

Command Surface

Area	Commands
Onboarding	ttychat start
Initialization (advanced)	ttychat init
Daemon and health	ttychat daemon start, ttychat daemon stop, ttychat daemon status, ttychat daemon health
Identity	ttychat identity show-code, ttychat identity regen-code, ttychat identity rotate-invite, ttychat identity migrate, ttychat identity backup-delete
Contacts	ttychat contact add, ttychat contact add-code, ttychat contact list, ttychat contact show, ttychat contact verify, ttychat contact rotate-keys, ttychat contact export, ttychat contact import
Messaging	ttychat send, ttychat read, ttychat convo, ttychat message list, ttychat message search, ttychat message retry-now, ttychat message delete, ttychat message expunge-contact, ttychat message expunge-all
Attachments	ttychat file send, ttychat file save
Voice	ttychat voice send, ttychat voice save, ttychat voice list
Inbox TUI	ttychat inbox
Security audit	ttychat audit tail, ttychat audit export, ttychat audit clear

Security Notes

• Designed to mitigate passive network observation and centralized metadata collection
• Not a defense against compromised endpoints or global traffic-correlation adversaries
• Contacts should be verified out-of-band before trusted messaging
• Forward secrecy ratcheting beyond per-message ephemeral exchange is planned as future work

Ratchet Compatibility Mode

During mixed-version rollouts, you can temporarily enable ratchet compatibility mode to accept legacy envelopes:

export TTYCHAT_RATCHET_COMPAT_MODE=1

Recommended usage:

• Enable only during a short transition window where peers may still emit older ratchet envelopes.
• Disable after all peers are upgraded so strict envelope validation remains enforced.
• Keep it disabled by default in normal operation.

Configuration and Data

• User config: ~/.config/ttychat/config.yaml
• Identity material: ~/.config/ttychat/identity.json
• Message store: path configured in storage.path (default under ~/.local/share/ttychat/)
• Security audit log: ~/.config/ttychat/security-audit.log

Project Documentation

For architecture, threat model details, storage notes, and roadmap tracking, see ROADMAP.md.

Rust Prototype

• Initial Rust scaffold is available at rust/ttychat-rs.
• Current prototype commands: init, status.
• This is a bootstrap stage and does not yet provide feature parity with the Go implementation.

License

AGPL-3.0.

Disclaimer

This project is provided for lawful use. Operators are responsible for compliance with local regulations regarding encryption and anonymity tooling.