freeq

IRC server and client with AT Protocol (Bluesky) identity authentication, end-to-end encrypted channels, iroh QUIC transport, peer-to-peer DMs, and federated server-to-server clustering.

Users authenticate with their Bluesky identity via a custom SASL mechanism (ATPROTO-CHALLENGE). Standard IRC clients connect as guests. Authenticated users get their DID bound to their connection — visible via WHOIS, enforced for nick ownership, and usable for DID-based bans, invites, and persistent ops.

Try it now: irc.freeq.at

For agents

freeq is meant to be used by software as well as people, so every surface an agent looks for exists and cross-links the others:

• llms.txt — the documentation index, linking raw markdown (llms-full.txt for one fetch).
• OpenAPI 3.1 — the full HTTP contract (spec/openapi.yaml; a drift test fails the build if the router and the spec disagree).
• MCP — freeq-mcp/ (@freeq/mcp) gives any MCP client tools to read, search, verify and take part in conversations. Not on npm yet: build it (cd freeq-mcp && npm install && npm run build) and point your client at node <repo>/freeq-mcp/dist/index.js.
• Skills — skills/: freeq (talking to other people's agents), freeq-api (REST), freeq-bots (building one).
• Agent Assistance Interface — ask the server why a join failed or a message went missing; it answers with a conclusion plus evidence, not raw state.

Attribution is the point: every message carries a ULID msgid and a signature, and GET /api/v1/verify/{msgid} distinguishes a message signed by its author's key from one merely relayed by the server.

Web Client

The web client at irc.freeq.at provides:

• AT Protocol OAuth login — sign in with your Bluesky identity
• Channel policy gates — channels can require credential verification to join
• GitHub verification — prove repo collaborator or org membership status
• Bluesky social graph gates — prove you follow someone (no OAuth needed)
• Moderator appointments — ops issue signed credentials for halfop (+h)
• Automatic role escalation — credentials auto-grant IRC modes (op, halfop, voice)
• Shareable invite links — https://irc.freeq.at/join/#channel
• Message editing, deletion, reactions, threads — changing a message requires the sender's signature; current clients sign automatically
• End-to-end encrypted channels

Demo Channels

Architecture

freeq-server/       IRC server with SASL, WebSocket, iroh, S2S federation
freeq-app/          React web client (Vite + Tailwind)
freeq-auth-broker/  AT Protocol OAuth broker (persistent sessions)
freeq-sdk/          Reusable client SDK (connect, auth, events, E2EE, P2P)
freeq-tui/          Terminal UI client built on the SDK
freeq-site/         Marketing site (freeq.at)

The SDK exposes a (ClientHandle, Receiver<Event>) pattern — any UI or bot can consume events and send commands.

Transport Stack

┌──────────────────────────────────────────┐
│            IRC Wire Protocol             │
├──────────┬──────────┬──────────┬─────────┤
│   TCP    │   TLS    │WebSocket │  iroh   │
│  :6667   │  :6697   │  :8080   │  QUIC   │
└──────────┴──────────┴──────────┴─────────┘

All transports feed into the same handle_generic() handler — the IRC protocol is transport-agnostic. Each transport is zero-cost when not enabled.

Quick Start

Build

cargo build --release

Run the Server

# Minimal: plain TCP only, in-memory
cargo run --release --bin freeq-server

# With persistence
cargo run --release --bin freeq-server -- --db-path data/irc.db

# With TLS
cargo run --release --bin freeq-server -- \
  --tls-cert certs/cert.pem --tls-key certs/key.pem

# With WebSocket + REST API
cargo run --release --bin freeq-server -- --web-addr 0.0.0.0:8080

# With iroh transport (QUIC, NAT-traversing)
cargo run --release --bin freeq-server -- --iroh

# Full production setup
cargo run --release --bin freeq-server -- \
  --listen-addr 0.0.0.0:6667 \
  --tls-listen-addr 0.0.0.0:6697 \
  --tls-cert /etc/letsencrypt/live/example.com/fullchain.pem \
  --tls-key /etc/letsencrypt/live/example.com/privkey.pem \
  --db-path ./irc.db \
  --web-addr 0.0.0.0:8080 \
  --iroh

Generate a self-signed cert for local development:

mkdir -p certs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

Connect with the TUI Client

# Guest (no auth)
cargo run --release --bin freeq-tui -- 127.0.0.1:6667 mynick

# Bluesky OAuth (opens browser)
cargo run --release --bin freeq-tui -- 127.0.0.1:6697 mynick \
  --handle alice.bsky.social

# App password fallback
cargo run --release --bin freeq-tui -- 127.0.0.1:6667 mynick \
  --handle alice.bsky.social --app-password xxxx-xxxx-xxxx-xxxx

# Auto-join channels
cargo run --release --bin freeq-tui -- 127.0.0.1:6667 mynick \
  -c '#general,#random'

# Explicit iroh transport
cargo run --release --bin freeq-tui -- 127.0.0.1:6667 mynick \
  --iroh-addr <endpoint-id>

# Vi keybindings
cargo run --release --bin freeq-tui -- 127.0.0.1:6667 mynick --vi

Iroh auto-discovery: When connecting to a server that has --iroh enabled, the TUI probes CAP LS for the iroh=<endpoint-id> capability and auto-upgrades to iroh QUIC transport. No manual endpoint ID needed.

OAuth sessions are cached to ~/.config/freeq-tui/<handle>.session.json so you don't need to re-authenticate on every launch.

Connect with a Standard IRC Client

Any IRC client works as a guest — irssi, WeeChat, HexChat, LimeChat, etc. Connect to 127.0.0.1:6667 (plain) or 127.0.0.1:6697 (TLS). No special configuration needed.

Connect via WebSocket

When --web-addr is set, the server accepts WebSocket connections at ws://<addr>/irc. A test HTML client is included at freeq-server/test-client.html.

Authentication

SASL ATPROTO-CHALLENGE

The server implements a custom SASL mechanism for AT Protocol identity:

1. Client requests CAP sasl, then AUTHENTICATE ATPROTO-CHALLENGE
2. Server sends a challenge: base64url(json { session_id, nonce, timestamp })
3. Client responds with one of:
   • Crypto signature (method: "crypto"): Signs challenge bytes with a private key listed in the DID document
   • PDS session (method: "pds-session"): Sends an app-password JWT; server verifies against the PDS
   • PDS OAuth (method: "pds-oauth"): Sends a DPoP-bound access token with proof; server verifies against the PDS
4. Server verifies, emits 903 (success) or 904 (failure)
5. Client sends CAP END, registration completes

Security Properties

• Each challenge contains a cryptographically random nonce
• Challenges are invalidated after use (no replay)
• Challenge validity window: configurable, default 60 seconds
• Private keys never leave the client
• PDS URL is verified against the DID document before accepting session tokens
• Supported key types: secp256k1 (MUST), ed25519 (SHOULD)

What Authentication Gets You

• Nick is bound to your DID — no one else can use it
• WHOIS shows your DID and Bluesky handle
• You can be banned or invited by DID (survives reconnect/nick changes)
• Persistent channel ops tied to your DID (survive reconnects and work across federated servers)
• Your identity is cryptographically verifiable

Transports

TCP / TLS (Standard)

Standard IRC on port 6667 (plain) and 6697 (TLS). TLS auto-detected by port in the client. Always available.

WebSocket

Enabled with --web-addr. Accepts WebSocket IRC at /irc. Uses the same IRC wire protocol — WebSocket is a transport, not a new protocol. Includes a read-only REST API at /api/v1/ (channels, members, topics, messages).

iroh (QUIC)

Enabled with --iroh. Provides NAT-traversing encrypted QUIC connections via iroh. The server generates a persistent secret key (iroh-key.secret) on first run — endpoint ID is stable across restarts.

The server advertises its iroh endpoint ID in CAP LS:

CAP * LS :sasl message-tags iroh=44f1415c9db30989...

Clients auto-discover and upgrade to iroh when available.

End-to-End Encryption (E2EE)

Client-side channel encryption using AES-256-GCM with HKDF-SHA256 key derivation from a shared passphrase. The server relays ciphertext unchanged.

/encrypt <passphrase>    Enable E2EE for current channel
/decrypt                 Disable E2EE for current channel

Wire format: ENC1:<nonce-b64>:<ciphertext-b64> — version-tagged, uses the message body for robustness. All channel members must use the same passphrase.

Peer-to-Peer Encrypted DMs

Direct encrypted messaging between clients via iroh QUIC, bypassing the server entirely.

/p2p start               Start your P2P endpoint
/p2p id                  Show your P2P endpoint ID
/p2p connect <id>        Connect to a peer
/p2p msg <id> <message>  Send a direct message