From 4be87440d5d024521a2951ec64f8313c39ae4863 Mon Sep 17 00:00:00 2001 From: Anthony Ettinger Date: Sun, 14 Jun 2026 10:54:21 +0000 Subject: [PATCH 1/3] tor: premium tor-url / tor-irc / tor routes over Tor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three premium-gated SSH routes: ssh tor-url@host one-shot HTTP(S) GET over Tor (host-side, curl via SOCKS, 30s/2MB caps, http/https only) ssh -t tor-irc@host interactive IRC over Tor in the member's pod ssh -t tor@host run any command over Tor (torsocks) in the pod tor-url runs host-side and constrained; tor/tor-irc run inside the member's isolated pod (new pods.Exec) so arbitrary/interactive commands are sandboxed, never on the host. internal/tor wraps curl/torsocks/irssi. All gated by ensurePremium; names reserved. setup.sh installs + enables tor (SOCKS 127.0.0.1:9050) and torsocks. Note: tor-url is host-side and self-contained. tor/tor-irc still need the pod image to carry torsocks+irssi and reach the Tor SOCKS — follow-up. Co-Authored-By: Claude Opus 4.8 --- cmd/agentbbs/main.go | 137 ++++++++++++++++++++++++++++++++++++++++++ internal/auth/auth.go | 22 ++++++- internal/pods/pods.go | 41 +++++++++++++ internal/tor/tor.go | 80 ++++++++++++++++++++++++ setup.sh | 6 ++ 5 files changed, 285 insertions(+), 1 deletion(-) create mode 100644 internal/tor/tor.go diff --git a/cmd/agentbbs/main.go b/cmd/agentbbs/main.go index ee86427..ecd776a 100644 --- a/cmd/agentbbs/main.go +++ b/cmd/agentbbs/main.go @@ -60,6 +60,7 @@ import ( "github.com/profullstack/agentbbs/internal/sandbox" "github.com/profullstack/agentbbs/internal/sites" "github.com/profullstack/agentbbs/internal/store" + "github.com/profullstack/agentbbs/internal/tor" "github.com/profullstack/agentbbs/plugins/about" "github.com/profullstack/agentbbs/plugins/agentgames" "github.com/profullstack/agentbbs/plugins/arcade" @@ -246,6 +247,12 @@ func (a *app) router() wish.Middleware { a.handleGame(s) case auth.IsPodName(user): a.handlePod(s) + case auth.IsTorURLName(user): + a.handleTorURL(s) + case auth.IsTorIRCName(user): + a.handleTorIRC(s) + case auth.IsTorName(user): + a.handleTorCmd(s) case isVideo: a.handleVideo(s, code) case user == "agent": @@ -805,6 +812,136 @@ func (a *app) handlePod(s ssh.Session) { } } +// torMember resolves the caller's key to a premium member for the tor routes, +// printing a reason and returning ok=false otherwise. It records the session. +func (a *app) torMember(s ssh.Session, route string) (store.User, bool) { + fp := auth.Fingerprint(s.PublicKey()) + if fp == "" { + wish.Println(s, route+"@ needs your registered SSH key. New here? ssh join@"+a.host) + _ = s.Exit(1) + return store.User{}, false + } + u, found, err := a.st.UserByFingerprint(fp) + if err != nil || !found { + wish.Println(s, "key not registered — run: ssh join@"+a.host) + _ = s.Exit(1) + return store.User{}, false + } + if u.Banned { + wish.Println(s, "this account is suspended.") + _ = s.Exit(1) + return store.User{}, false + } + if !a.ensurePremium(&u) { + wish.Println(s, " "+route+" is a Premium feature ($10 lifetime). Upgrade: ssh join@"+a.host) + _ = s.Exit(1) + return store.User{}, false + } + _, _ = a.st.RecordSession(u.ID, s.User(), remoteIP(s), route) + return u, true +} + +// handleTorURL fetches a single URL over Tor and writes the body back. One-shot, +// host-side, and constrained (timeout + size cap, http/https only). Premium. +func (a *app) handleTorURL(s ssh.Session) { + u, ok := a.torMember(s, "tor-url") + if !ok { + return + } + args := s.Command() + if len(args) == 0 { + wish.Println(s, "usage: ssh tor-url@"+a.host+" (e.g. an .onion address)") + _ = s.Exit(1) + return + } + url := args[0] + log.Info("tor-url fetch", "user", u.Name, "url", url) + body, err := tor.FetchURL(s.Context(), url) + if err != nil { + wish.Println(s, " "+err.Error()) + _ = s.Exit(1) + return + } + _, _ = s.Write(body) + _ = s.Exit(0) +} + +// handleTorIRC opens an interactive IRC-over-Tor session inside the member's +// pod (sandboxed). Premium; requires a PTY. +func (a *app) handleTorIRC(s ssh.Session) { + u, ok := a.torMember(s, "tor-irc") + if !ok { + return + } + args := s.Command() + if len(args) == 0 || !validIRCServer(args[0]) { + wish.Println(s, "usage: ssh -t tor-irc@"+a.host+" (e.g. an .onion IRC server)") + _ = s.Exit(1) + return + } + if a.pods == nil { + wish.Println(s, "pods are temporarily unavailable on this host.") + _ = s.Exit(1) + return + } + log.Info("tor-irc connect", "user", u.Name, "server", args[0]) + if err := a.pods.Exec(s, u.Name, tor.IRCArgv(args[0])); err != nil { + wish.Println(s, "tor-irc error: "+err.Error()) + _ = s.Exit(1) + } +} + +// handleTorCmd runs an arbitrary command through Tor (torsocks) inside the +// member's pod, never on the host. Premium; requires a PTY. +func (a *app) handleTorCmd(s ssh.Session) { + u, ok := a.torMember(s, "tor") + if !ok { + return + } + args := s.Command() + if len(args) == 0 { + wish.Println(s, "usage: ssh -t tor@"+a.host+" (runs in your pod, over Tor)") + _ = s.Exit(1) + return + } + if a.pods == nil { + wish.Println(s, "pods are temporarily unavailable on this host.") + _ = s.Exit(1) + return + } + log.Info("tor cmd", "user", u.Name, "argv", strings.Join(args, " ")) + if err := a.pods.Exec(s, u.Name, tor.Torsocks(args)); err != nil { + wish.Println(s, "tor error: "+err.Error()) + _ = s.Exit(1) + } +} + +// validIRCServer accepts host or host:port with a sane charset (no shell/space). +func validIRCServer(s string) bool { + host := s + if i := strings.LastIndex(s, ":"); i > 0 { + port := s[i+1:] + host = s[:i] + if port == "" || len(port) > 5 { + return false + } + for _, r := range port { + if r < '0' || r > '9' { + return false + } + } + } + if host == "" || len(host) > 255 { + return false + } + for _, r := range host { + if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || r == '.' || r == '-') { + return false + } + } + return true +} + // handleVideo joins a PairUX call rendered as ASCII (docs/video.md). // `video@` prompts for a code; `video-@` joins directly. Codes are // minted by PairUX — starting a call requires already having one. diff --git a/internal/auth/auth.go b/internal/auth/auth.go index edaa680..b8276d5 100644 --- a/internal/auth/auth.go +++ b/internal/auth/auth.go @@ -46,6 +46,16 @@ var DomainNames = map[string]bool{"domain": true, "domains": true} // (see IsAdmin); the name itself confers nothing. var AdminNames = map[string]bool{"admin": true, "sysop": true} +// TorURLNames route to the one-shot "fetch a URL over Tor" command (premium). +var TorURLNames = map[string]bool{"tor-url": true} + +// TorIRCNames route to an interactive IRC-over-Tor client in the member's pod. +var TorIRCNames = map[string]bool{"tor-irc": true} + +// TorNames route to the generic "run a command over Tor" passthrough in the +// member's pod (premium). Checked after the more specific tor-* routes. +var TorNames = map[string]bool{"tor": true} + // GameNames are usernames that route to AgentGames: the line-delimited-JSON // agent-vs-agent match protocol (PRD §5.2). `play@` stays a guest hub alias. var GameNames = map[string]bool{"game": true, "games": true} @@ -65,6 +75,15 @@ func IsDomainName(u string) bool { return DomainNames[strings.ToLower(u)] } // IsAdminName reports whether the SSH username requests the admin console. func IsAdminName(u string) bool { return AdminNames[strings.ToLower(u)] } +// IsTorURLName reports whether the SSH username requests the tor-url fetch. +func IsTorURLName(u string) bool { return TorURLNames[strings.ToLower(u)] } + +// IsTorIRCName reports whether the SSH username requests the tor-irc client. +func IsTorIRCName(u string) bool { return TorIRCNames[strings.ToLower(u)] } + +// IsTorName reports whether the SSH username requests the generic tor passthrough. +func IsTorName(u string) bool { return TorNames[strings.ToLower(u)] } + // systemReserved are names that don't drive an SSH route but would still // collide with a per-user subdomain (.), the agent route, or common // infra hostnames — so members may not claim them as account names. @@ -80,7 +99,8 @@ var systemReserved = map[string]bool{ // therefore cannot be used as a member's account name. func IsReservedName(name string) bool { n := strings.ToLower(name) - if GuestNames[n] || PodNames[n] || JoinNames[n] || DomainNames[n] || AdminNames[n] || systemReserved[n] { + if GuestNames[n] || PodNames[n] || JoinNames[n] || DomainNames[n] || AdminNames[n] || + TorURLNames[n] || TorIRCNames[n] || TorNames[n] || systemReserved[n] { return true } return strings.HasPrefix(n, "video-") // video- call routes diff --git a/internal/pods/pods.go b/internal/pods/pods.go index 3a5746b..ea638c8 100644 --- a/internal/pods/pods.go +++ b/internal/pods/pods.go @@ -144,6 +144,47 @@ func (m *Manager) Attach(s ssh.Session, user string) error { return nil } +// Exec provisions the user's pod and runs argv inside it wired to the SSH +// session (PTY required). Used for tor@/tor-irc@ so arbitrary or interactive +// commands run sandboxed in the member's container, never on the host. Blocks +// until the command exits or the session closes. +func (m *Manager) Exec(s ssh.Session, user string, argv []string) error { + if len(argv) == 0 { + return fmt.Errorf("pods: no command given") + } + ptyReq, winCh, hasPty := s.Pty() + if !hasPty { + return fmt.Errorf("pods: a PTY is required (ssh -t)") + } + name, err := m.ensure(user) + if err != nil { + return err + } + + args := append([]string{"exec", "-it", "-e", "TERM=" + ptyReq.Term, name}, argv...) + cmd := exec.Command(m.engine, args...) + f, err := pty.Start(cmd) + if err != nil { + return fmt.Errorf("pods: exec failed: %w", err) + } + defer f.Close() + + m.ref(name, +1) + defer m.deref(name) + + _ = pty.Setsize(f, &pty.Winsize{Rows: uint16(ptyReq.Window.Height), Cols: uint16(ptyReq.Window.Width)}) + go func() { + for w := range winCh { + _ = pty.Setsize(f, &pty.Winsize{Rows: uint16(w.Height), Cols: uint16(w.Width)}) + } + }() + + go func() { _, _ = io.Copy(f, s) }() // ssh -> pod + _, _ = io.Copy(s, f) // pod -> ssh + _ = cmd.Wait() + return nil +} + func (m *Manager) ref(name string, d int) { m.mu.Lock() defer m.mu.Unlock() diff --git a/internal/tor/tor.go b/internal/tor/tor.go new file mode 100644 index 0000000..bfcd4b3 --- /dev/null +++ b/internal/tor/tor.go @@ -0,0 +1,80 @@ +// Package tor fetches URLs and wraps commands so they egress through the host's +// Tor SOCKS proxy. tor-url fetches run on the host (constrained); generic and +// IRC commands run inside the member's pod via torsocks (see cmd/agentbbs). +package tor + +import ( + "context" + "fmt" + "net/url" + "os" + "os/exec" + "strings" + "time" +) + +// SocksAddr is the host-local Tor SOCKS5 endpoint that setup.sh's tor service +// listens on. Overridable so a dev host can point elsewhere. +var SocksAddr = envOr("AGENTBBS_TOR_SOCKS", "127.0.0.1:9050") + +// Fetch limits so a single member can't tie up the host. +const ( + fetchTimeout = 30 * time.Second + maxBytes = 2_000_000 // 2 MB +) + +// FetchURL retrieves rawURL over Tor and returns the body (capped at maxBytes). +// Only http/https are allowed and the call is bounded by a timeout, so the URL +// (passed to curl as a single argv element — never a shell) can't be abused to +// reach the local network or run unboundedly. +func FetchURL(ctx context.Context, rawURL string) ([]byte, error) { + u, err := url.Parse(strings.TrimSpace(rawURL)) + if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" { + return nil, fmt.Errorf("give an http(s) URL, e.g. http://example.onion") + } + ctx, cancel := context.WithTimeout(ctx, fetchTimeout) + defer cancel() + cmd := exec.CommandContext(ctx, "curl", + "-sS", "-L", "--max-redirs", "3", + "--max-time", fmt.Sprint(int(fetchTimeout.Seconds())), + "--max-filesize", fmt.Sprint(maxBytes), + "--proto", "=http,https", + "--socks5-hostname", SocksAddr, // resolve the hostname through Tor too + u.String(), + ) + out, err := cmd.Output() + if err != nil { + if ctx.Err() == context.DeadlineExceeded { + return nil, fmt.Errorf("timed out after %s", fetchTimeout) + } + return nil, fmt.Errorf("fetch failed (is the host reachable over Tor?): %v", err) + } + if len(out) > maxBytes { + out = out[:maxBytes] + } + return out, nil +} + +// Torsocks prefixes argv with torsocks so the command's network traffic is +// routed through Tor when run inside a pod that has torsocks configured. +func Torsocks(argv []string) []string { + return append([]string{"torsocks"}, argv...) +} + +// IRCArgv builds the argv for an interactive IRC-over-Tor session to server +// (host[:port]); it runs irssi through torsocks. server is validated by the +// caller. Defaults to the standard IRC port when none is given. +func IRCArgv(server string) []string { + host, port := server, "6667" + if i := strings.LastIndex(server, ":"); i > 0 { + host, port = server[:i], server[i+1:] + } + return Torsocks([]string{"irssi", "--connect=" + host, "--port=" + port}) +} + +func envOr(k, def string) string { + if v := strings.TrimSpace(os.Getenv(k)); v != "" { + return v + } + return def +} diff --git a/setup.sh b/setup.sh index 26d1d8a..25cde42 100755 --- a/setup.sh +++ b/setup.sh @@ -87,8 +87,14 @@ apt-get update -qq apt-get install -y -qq \ git ca-certificates curl ufw ffmpeg unzip \ podman uidmap slirp4netns fuse-overlayfs \ + tor torsocks \ debian-keyring debian-archive-keyring apt-transport-https >/dev/null +# Tor SOCKS proxy for the tor-url@/tor@/tor-irc@ routes. Ships listening on +# 127.0.0.1:9050 by default; keep it loopback-only (never expose it). +log "enabling tor (SOCKS 127.0.0.1:9050)" +systemctl enable --now tor >/dev/null 2>&1 || warn "tor service not enabled — tor-url@ will be unavailable" + # yt-dlp from pip is fresher than apt; fall back to apt if pip is unavailable. if ! command -v yt-dlp >/dev/null; then log "installing yt-dlp" From 8adafaf515f65e3dc94956bd7c969c77dca1059f Mon Sep 17 00:00:00 2001 From: Anthony Ettinger Date: Sun, 14 Jun 2026 11:21:39 +0000 Subject: [PATCH 2/3] feat(irc): members-only Ergo IRC network co-located on the BBS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Provision a self-hosted Ergo IRC network (irc.${DOMAIN}) in setup.sh §9b: single Go binary on its own ports/user, reusing Caddy's Let's Encrypt cert for 6697 TLS (refreshed by a timer; self-signed fallback on first boot), loopback 6667 + a loopback WebSocket fronted by Caddy at wss://${DOMAIN}/irc. Access is MEMBERS-ONLY: every client must authenticate with SASL, self-service registration is off, and an auth-script (deploy/ergo/auth-script.sh, installed as /usr/local/bin/ergo-auth-member) approves a login only if the account name maps to an existing AgentBBS member home dir under /users/. Passphrase is ignored — membership (the filesystem dir) is the credential. require-sasl has no IP exemption so WebSocket clients (which reach Ergo via Caddy from 127.0.0.1) can't bypass the gate; accounts are auto-created on first successful auth. Public attack surface is TLS-only (ufw opens 6697; 6667 is loopback). Toggle with IRC=0. See docs/irc.md. Co-Authored-By: Claude Opus 4.8 --- README.md | 19 + deploy/ergo/auth-script.sh | 48 ++ deploy/ergo/ircd.yaml | 1189 ++++++++++++++++++++++++++++++++++ deploy/ergo/refresh-certs.sh | 42 ++ docs/irc.md | 126 ++++ setup.sh | 148 ++++- 6 files changed, 1570 insertions(+), 2 deletions(-) create mode 100644 deploy/ergo/auth-script.sh create mode 100644 deploy/ergo/ircd.yaml create mode 100755 deploy/ergo/refresh-certs.sh create mode 100644 docs/irc.md diff --git a/README.md b/README.md index 48e58ec..e21bd39 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ plugins around one shared account system; the full product plan is in | `agent@` chat (configurable agent backend) + finger | ✅ | | M2 — admin console (`admin@`: users, sessions, moderation, plugins) | ✅ | | M3 — AgentGames (`game@` + WebSocket; TTT/C4, ELO ladder, replays) | ✅ | +| IRC (`irc.bbs.profullstack.com` — Ergo network for humans + agents) | ✅ | | M4 — Files (cl1.tech SFTP workspaces) | ⬜ | | M5 — AgentAd marketplace (built on the AgentAd standard in logicsrc) | ⬜ | @@ -99,6 +100,24 @@ The production host (`bbs.profullstack.com`) is provisioned by the idempotent Full details, required secrets, and ops commands: [`docs/deploy.md`](docs/deploy.md). +### IRC network + +`setup.sh` also stands up a co-located [Ergo](https://ergo.chat) IRC server (its +own `ergo.service`, ports 6697/TLS + a Caddy-fronted WebSocket) so humans and +agents can meet on a real IRC network. It is **members-only**: every client must +authenticate with SASL, and an auth-script approves a login only if the account +name is an existing AgentBBS member (registration is off — your BBS account *is* +your IRC identity): + +```bash +# native client — SASL account = your BBS member name +/connect irc.bbs.profullstack.com 6697 +# browser / agent over WebSocket +wss://bbs.profullstack.com/irc +``` + +Set `IRC=0` to skip it. Full details: [`docs/irc.md`](docs/irc.md). + ## Architecture - **Go + charmbracelet** — `wish` SSH server, `bubbletea` TUIs, `lipgloss` styling. diff --git a/deploy/ergo/auth-script.sh b/deploy/ergo/auth-script.sh new file mode 100644 index 0000000..77f4332 --- /dev/null +++ b/deploy/ergo/auth-script.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# +# auth-script.sh — Ergo auth-script that gates the IRC network on AgentBBS +# membership. setup.sh installs this to /usr/local/bin/ergo-auth-member and +# wires it into /etc/ergo/ircd.yaml (accounts.auth-script). +# +# "Member" == a user with a home dir under the AgentBBS users dir (created when +# someone registers via `ssh join@`). IRC is members-only, so a login is +# approved iff the requested account name maps to such a dir. The passphrase is +# intentionally IGNORED — membership (a filesystem dir) IS the credential, by +# design (see docs/irc.md). Anyone who knows a member's name can connect as +# them; that tradeoff was chosen deliberately for this private, TLS-only network. +# +# Protocol (Ergo): one JSON object on stdin per attempt, one JSON line on stdout +# then exit. Input keys: accountName, passphrase, certfp, ip. Output: +# {"success":bool,"accountName":str,"error":str}. +# +# args: [""] # defaults to /var/lib/agentbbs/users +set -uo pipefail + +USERS_DIR="${1:-/var/lib/agentbbs/users}" + +# Always emit valid JSON and exit 0 — Ergo reads the JSON, not the exit code; +# a non-zero exit / no output is treated as a script error, not a clean deny. +deny() { printf '{"success":false,"error":"%s"}\n' "${1:-not a member}"; exit 0; } + +# Don't gate on read's exit code: a final line without a trailing newline still +# carries data (read returns non-zero at EOF but populates $line). +line="" +read -r line || true +[ -n "$line" ] || deny "no input" + +acct="$(printf '%s' "$line" | jq -r '.accountName // ""' 2>/dev/null || true)" + +# certfp-only attempts carry no account name; we don't support cert auth here. +[ -n "$acct" ] || deny "membership requires an account name" + +# Defense in depth against path traversal. IRC account names are a restricted +# charset anyway, but never let one escape USERS_DIR. +case "$acct" in + *[!A-Za-z0-9._-]* | "." | ".." | *..* | */* ) deny "invalid account name" ;; +esac + +if [ -d "$USERS_DIR/$acct" ]; then + printf '{"success":true,"accountName":"%s"}\n' "$acct" +else + deny "not a member" +fi diff --git a/deploy/ergo/ircd.yaml b/deploy/ergo/ircd.yaml new file mode 100644 index 0000000..9d68282 --- /dev/null +++ b/deploy/ergo/ircd.yaml @@ -0,0 +1,1189 @@ +# AgentBBS IRC network — Ergo (https://ergo.chat) config TEMPLATE. +# +# This is a TEMPLATE: setup.sh renders it to /etc/ergo/ircd.yaml on deploy, +# substituting the __TOKENS__ below. Do not point Ergo at this file directly — +# the __TOKENS__ are not valid YAML values until rendered. +# +# __NETWORK__ network name shown to clients (e.g. ProfullstackBBS) +# __DOMAIN__ the BBS domain (e.g. bbs.profullstack.com) +# __DATA__ Ergo state dir (ircd.db lives here) +# __TLS_DIR__ dir holding fullchain.pem / privkey.pem for 6697 +# __LANG_DIR__ Ergo's bundled languages/ dir (from the release) +# __OPER_PASSWORD_HASH__ bcrypt hash for /OPER admin (ergo genpasswd) +# __USERS_DIR__ AgentBBS member home dirs (the IRC membership gate) +# +# It is based on Ergo's upstream default.yaml (v2.18.0) with the AgentBBS +# listeners (public 6697 TLS, loopback 6667, loopback 8097 WebSocket fronted +# by Caddy at wss://__DOMAIN__/irc) and the network identity wired in. Tuned +# for a mixed humans + agents network: it is MEMBERS-ONLY — every client must +# authenticate with SASL, self-service registration is OFF, and an auth-script +# (deploy/ergo/auth-script.sh, installed as /usr/local/bin/ergo-auth-member) +# approves a login only if the account name maps to an existing AgentBBS member +# home dir under __USERS_DIR__. Message history (CHATHISTORY) is enabled so +# reconnecting agents and web clients can replay. See docs/irc.md. +# +# Most settings keep Ergo's recommended defaults — read the inline comments +# before changing one. A few worth knowing about: +# 1. network.name / server.name — the network identity (rendered from tokens). +# 2. server.listeners — the 6697 cert/key are refreshed from Caddy's Let's +# Encrypt cert for __DOMAIN__ by setup.sh (self-signed fallback on first run). +# 3. opers — the /OPER admin password hash (rendered from a token). +# 4. history — in-memory, messages expire after ~7 days. Switch to MySQL-backed +# persistent history (datastore.mysql) if you need durability across restarts. + +# network configuration +network: + # name of the network + name: __NETWORK__ + +# server configuration +server: + # server name + name: irc.__DOMAIN__ + + # addresses to listen on + listeners: + # Public TLS (6697) — the front door for native IRC clients (humans) and + # SASL-authenticating agents. Cert/key are refreshed from Caddy's + # Let's Encrypt cert for __DOMAIN__ by setup.sh (falls back to self-signed). + ":6697": + tls: + cert: __TLS_DIR__/fullchain.pem + key: __TLS_DIR__/privkey.pem + min-tls-version: 1.2 + + # Loopback plaintext (6667) — never exposed (firewall blocks it). Used by + # the in-BBS bridge and local tooling on the agentbbs box only. + "127.0.0.1:6667": + "[::1]:6667": + + # WebSocket (loopback) — Caddy terminates TLS and reverse-proxies + # wss://__DOMAIN__/irc to here, giving humans a browser client and agents + # a WebSocket transport without opening another public port. + "127.0.0.1:8097": + websocket: true + unix-bind-mode: 0777 + + # configure the behavior of Tor listeners (ignored if you didn't enable any): + tor-listeners: + # if this is true, connections from Tor must authenticate with SASL + require-sasl: false + + # what hostname should be displayed for Tor connections? + vhost: "tor-network.onion" + + # allow at most this many connections at once (0 for no limit): + max-connections: 64 + + # connection throttling (limit how many connection attempts are allowed at once): + throttle-duration: 10m + # set to 0 to disable throttling: + max-connections-per-duration: 64 + + # strict transport security, to get clients to automagically use TLS + # (irrelevant in the recommended configuration, with no public plaintext listener) + sts: + # whether to advertise STS + # + # to stop advertising STS, leave this enabled and set 'duration' below to "0". this will + # advertise to connecting users that the STS policy they have saved is no longer valid + enabled: false + + # how long clients should be forced to use TLS for. + # setting this to a too-long time will mean bad things if you later remove your TLS. + # the default duration below is 1 month, 2 days and 5 minutes. + duration: 1mo2d5m + + # tls port - you should be listening on this port above + port: 6697 + + # should clients include this STS policy when they ship their inbuilt preload lists? + preload: false + + websockets: + # Restrict the origin of WebSocket connections by matching the "Origin" HTTP + # header. This setting causes ergo to reject websocket connections unless + # they originate from a page on one of the whitelisted websites in this list. + # This prevents malicious websites from making their visitors connect to your + # ergo instance without their knowledge. An empty list means there are no + # restrictions. + allowed-origins: + - "https://__DOMAIN__" + # - "https://ergo.chat" + # - "https://*.ergo.chat" + + # casemapping controls what kinds of strings are permitted as identifiers (nicknames, + # channel names, account names, etc.), and how they are normalized for case. + # the recommended default is 'ascii' (traditional ASCII-only identifiers). + # the other options are 'precis', which allows UTF8 identifiers that are "sane" + # (according to UFC 8265), with additional mitigations for homoglyph attacks, + # 'permissive', which allows identifiers containing unusual characters like + # emoji, at the cost of increased vulnerability to homoglyph attacks and potential + # client compatibility problems, and the legacy mappings 'rfc1459' and + # 'rfc1459-strict'. we recommend leaving this value at its default; + # however, note that changing it once the network is already up and running is + # problematic. + casemapping: "ascii" + + # enforce-utf8 controls whether the server will preemptively discard non-UTF8 + # messages (since they cannot be relayed to websocket clients), or will allow + # them and relay them to non-websocket clients (as in traditional IRC). + enforce-utf8: true + + # whether to look up user hostnames with reverse DNS. there are 3 possibilities: + # 1. lookup-hostnames enabled, IP cloaking disabled; users will see each other's hostnames + # 2. lookup-hostnames disabled, IP cloaking disabled; users will see each other's numeric IPs + # 3. [the default] IP cloaking enabled; users will see cloaked hostnames + lookup-hostnames: false + # whether to confirm hostname lookups using "forward-confirmed reverse DNS", i.e., for + # any hostname returned from reverse DNS, resolve it back to an IP address and reject it + # unless it matches the connecting IP + forward-confirm-hostnames: true + + # use ident protocol to get usernames + check-ident: false + + # ignore the supplied user/ident string from the USER command, always setting user/ident + # to the following literal value; this can potentially reduce confusion and simplify bans. + # the value must begin with a '~' character. comment out / omit to disable: + coerce-ident: '~u' + + # 'password' allows you to require a global, shared password (the IRC `PASS` command) + # to connect to the server. for operator passwords, see the `opers` section of the + # config. for a more secure way to create a private server, see the `require-sasl` + # section. you must hash the password with `ergo genpasswd`, then enter the hash here: + #password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234" + + # motd filename + # if you change the motd, you should move it to ircd.motd + motd: ergo.motd + + # motd formatting codes + # if this is true, the motd is escaped using formatting codes like $c, $b, and $i + motd-formatting: true + + # send a configurable notice to clients immediately after they connect, + # as a way of detecting open proxies + #initial-notice: "*** Welcome to the Ergo IRC server" + + # idle timeouts for inactive clients + idle-timeouts: + # give the client this long to complete connection registration (i.e. the initial + # IRC handshake, including capability negotiation and SASL) + registration: 60s + # if the client hasn't sent anything for this long, send them a PING + ping: 1m30s + # if the client hasn't sent anything for this long (including the PONG to the + # above PING), disconnect them + disconnect: 2m30s + + # relaying using the RELAYMSG command + relaymsg: + # is relaymsg enabled at all? + enabled: true + + # which character(s) are reserved for relayed nicks? + separators: "/" + + # can channel operators use RELAYMSG in their channels? + # our implementation of RELAYMSG makes it safe for chanops to use without the + # possibility of real users being silently spoofed + available-to-chanops: true + + # IPs/CIDRs the PROXY command can be used from + # This should be restricted to localhost (127.0.0.1/8, ::1/128, and unix sockets). + # Unless you have a good reason. you should also add these addresses to the + # connection limits and throttling exemption lists. + proxy-allowed-from: + - localhost + # - "192.168.1.1" + # - "192.168.10.1/24" + + # controls the use of the WEBIRC command (by IRC<->web interfaces, bouncers and similar) + webirc: + # one webirc block -- should correspond to one set of gateways + - + # SHA-256 fingerprint of the TLS certificate the gateway must use to connect + # (comment this out to use passwords only) + certfp: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789" + + # password the gateway uses to connect, made with `ergo genpasswd` + password: "$2a$04$abcdef0123456789abcdef0123456789abcdef0123456789abcde" + + # IPs/CIDRs that can use this webirc command + # you should also add these addresses to the connection limits and throttling exemption lists + hosts: + - localhost + # - "192.168.1.1" + # - "192.168.10.1/24" + + # whether to accept the hostname parameter on the WEBIRC line as the IRC hostname + # (the default/recommended Ergo configuration will use cloaks instead) + accept-hostname: false + + # maximum length of clients' sendQ in bytes + # this should be big enough to hold bursts of channel/direct messages + max-sendq: 96k + + # compatibility with legacy clients + compatibility: + # many clients require that the final parameter of certain messages be an + # RFC1459 trailing parameter, i.e., prefixed with :, whether or not this is + # actually required. this forces Ergo to send those parameters + # as trailings. this is recommended unless you're testing clients for conformance; + # defaults to true when unset for that reason. + force-trailing: true + + # some clients (ZNC 1.6.x and lower, Pidgin 2.12 and lower) do not + # respond correctly to SASL messages with the server name as a prefix: + # https://github.com/znc/znc/issues/1212 + # this works around that bug, allowing them to use SASL. + send-unprefixed-sasl: true + + # traditionally, IRC servers will truncate and send messages that are + # too long to be relayed intact. this behavior can be disabled by setting + # allow-truncation to false, in which case Ergo will reject the message + # and return an error to the client. (note that this option defaults to true + # when unset.) + allow-truncation: false + + # IP-based DoS protection + ip-limits: + # whether to limit the total number of concurrent connections per IP/CIDR + count: true + # maximum concurrent connections per IP/CIDR + max-concurrent-connections: 16 + + # whether to restrict the rate of new connections per IP/CIDR + throttle: true + # how long to keep track of connections for + window: 10m + # maximum number of new connections per IP/CIDR within the given duration + max-connections-per-window: 32 + + # how wide the CIDR should be for IPv4 (a /32 is a fully specified IPv4 address) + cidr-len-ipv4: 32 + # how wide the CIDR should be for IPv6 (a /64 is the typical prefix assigned + # by an ISP to an individual customer for their LAN) + cidr-len-ipv6: 64 + + # IPs/networks which are exempted from connection limits + exempted: + - "localhost" + # - "192.168.1.1" + # - "2001:0db8::/32" + + # custom connection limits for certain IPs/networks. + custom-limits: + #"irccloud": + # nets: + # - "192.184.9.108" # highgate.irccloud.com + # - "192.184.9.110" # ealing.irccloud.com + # - "192.184.9.112" # charlton.irccloud.com + # - "192.184.10.118" # brockwell.irccloud.com + # - "192.184.10.9" # tooting.irccloud.com + # - "192.184.8.73" # hathersage.irccloud.com + # - "192.184.8.103" # stonehaven.irccloud.com + # - "5.254.36.57" # tinside.irccloud.com + # - "5.254.36.56/29" # additional ipv4 net + # - "2001:67c:2f08::/48" + # - "2a03:5180:f::/64" + # max-concurrent-connections: 2048 + # max-connections-per-window: 2048 + + # pluggable IP ban mechanism, via subprocess invocation + # this can be used to check new connections against a DNSBL, for example + # see the manual for details on how to write an IP ban checking script + ip-check-script: + enabled: false + command: "/usr/local/bin/check-ip-ban" + # constant list of args to pass to the command; the actual query + # and result are transmitted over stdin/stdout: + args: [] + # timeout for process execution, after which we send a SIGTERM: + timeout: 9s + # how long after the SIGTERM before we follow up with a SIGKILL: + kill-timeout: 1s + # how many scripts are allowed to run at once? 0 for no limit: + max-concurrency: 64 + # if true, only check anonymous connections (not logged into an account) + # at the very end of the handshake: + exempt-sasl: false + + # IP cloaking hides users' IP addresses from other users and from channel admins + # (but not from server admins), while still allowing channel admins to ban + # offending IP addresses or networks. In place of hostnames derived from reverse + # DNS, users see fake domain names like pwbs2ui4377257x8.irc. These names are + # generated deterministically from the underlying IP address, but if the underlying + # IP is not already known, it is infeasible to recover it from the cloaked name. + # If you disable this, you should probably enable lookup-hostnames in its place. + ip-cloaking: + # whether to enable IP cloaking + enabled: true + + # whether to use these cloak settings (specifically, `netname` and `num-bits`) + # to produce unique hostnames for always-on clients. you can enable this even if + # you disabled IP cloaking for normal clients above. if this is disabled, + # always-on clients will all have an identical hostname (the server name). + enabled-for-always-on: true + + # fake TLD at the end of the hostname, e.g., pwbs2ui4377257x8.irc + # you may want to use your network name here + netname: "irc" + + # the cloaked hostname is derived only from the CIDR (most significant bits + # of the IP address), up to a configurable number of bits. this is the + # granularity at which bans will take effect for IPv4. Note that changing + # this value will invalidate any stored bans. + cidr-len-ipv4: 32 + + # analogous granularity for IPv6 + cidr-len-ipv6: 64 + + # number of bits of hash output to include in the cloaked hostname. + # more bits means less likelihood of distinct IPs colliding, + # at the cost of a longer cloaked hostname. if this value is set to 0, + # all users will receive simply `netname` as their cloaked hostname. + num-bits: 64 + + # secure-nets identifies IPs and CIDRs which are secure at layer 3, + # for example, because they are on a trusted internal LAN or a VPN. + # plaintext connections from these IPs and CIDRs will be considered + # secure (clients will receive the +Z mode and be allowed to resume + # or reattach to secure connections). note that loopback IPs are always + # considered secure: + secure-nets: + # - "10.0.0.0/8" + + # allow attempts to OPER with a password at most this often. defaults to + # 10 seconds when unset. + oper-throttle: 10s + + # Ergo will write files to disk under certain circumstances, e.g., + # CPU profiling or data export. by default, these files will be written + # to the working directory. set this to customize: + #output-path: "/home/ergo/out" + + # the hostname used by "services", e.g., NickServ, defaults to "localhost", + # e.g., `NickServ!NickServ@localhost`. uncomment this to override: + #override-services-hostname: "example.network" + + # in a "closed-loop" system where you control the server and all the clients, + # you may want to increase the maximum (non-tag) length of an IRC line from + # the default value of 512. DO NOT change this on a public server: + #max-line-len: 512 + + # send all 0's as the LUSERS (user counts) output to non-operators; potentially useful + # if you don't want to publicize how popular the server is + suppress-lusers: false + + # publish additional key-value pairs in ISUPPORT (the 005 numeric). + # keys that collide with a key published by Ergo will be silently ignored. + additional-isupport: + #"draft/FILEHOST": "https://example.com/filehost" + #"draft/bazbat": "" # empty string means no value + + # optionally map command alias names to existing ergo commands. most deployments + # should ignore this. + #command-aliases: + #"UMGEBUNG": "AMBIANCE" + +# account options +accounts: + # is account authentication enabled, i.e., can users log into existing accounts? + authentication-enabled: true + + # account registration + registration: + # MEMBERS-ONLY: self-service registration is OFF. The only way to get an + # account is the auth-script (autocreate) below, gated on AgentBBS + # membership. Operators with `accreg` can still /NICKSERV SAREGISTER. + # (require-sasl below mandates this be false.) + enabled: false + + # can users use the REGISTER command to register before fully connecting? + allow-before-connect: true + + # global throttle on new account creation + throttling: + enabled: true + # window + duration: 10m + # number of attempts allowed within the window + max-attempts: 30 + + # this is the bcrypt cost we'll use for account passwords + # (note that 4 is the lowest value allowed by the bcrypt library) + bcrypt-cost: 4 + + # length of time a user has to verify their account before it can be re-registered + verify-timeout: "32h" + + # options for email verification of account registrations + email-verification: + enabled: false + sender: "admin@my.network" + require-tls: true + helo-domain: "my.network" # defaults to server name if unset + # set to `tcp4` to force sending over IPv4, `tcp6` to force IPv6: + # protocol: "tcp4" + # set to force a specific source/local IPv4 or IPv6 address: + # local-address: "1.2.3.4" + # options to enable DKIM signing of outgoing emails (recommended, but + # requires creating a DNS entry for the public key): + # dkim: + # domain: "my.network" + # selector: "20200229" + # key-file: "dkim.pem" + # to use an MTA/smarthost instead of sending email directly: + # mta: + # server: localhost + # port: 25 + # username: "admin" + # password: "hunter2" + # implicit-tls: false # TLS from the first byte, typically on port 465 + # addresses that are not accepted for registration: + address-blacklist: + # - "*@mailinator.com" + address-blacklist-syntax: "glob" # change to "regex" for regular expressions + # file of newline-delimited address blacklist entries (no enclosing quotes) + # in the above syntax (i.e. either globs or regexes). supersedes + # address-blacklist if set: + # address-blacklist-file: "/path/to/address-blacklist-file" + timeout: 60s + # email-based password reset: + password-reset: + enabled: false + # time before we allow resending the email + cooldown: 1h + # time for which a password reset code is valid + timeout: 1d + + # throttle account login attempts (to prevent either password guessing, or DoS + # attacks on the server aimed at forcing repeated expensive bcrypt computations) + login-throttling: + enabled: true + + # window + duration: 1m + + # number of attempts allowed within the window + max-attempts: 3 + + # some clients (notably Pidgin and Hexchat) offer only a single password field, + # which makes it impossible to specify a separate server password (for the PASS + # command) and SASL password. if this option is set to true, a client that + # successfully authenticates with SASL will not be required to send + # PASS as well, so it can be configured to authenticate with SASL only. + skip-server-password: false + + # enable login to accounts via the PASS command, e.g., PASS account:password + # this is useful for compatibility with old clients that don't support SASL + login-via-pass-command: true + + # advertise the SCRAM-SHA-256 authentication method. set to false in case of + # compatibility issues with certain clients: + advertise-scram: true + + # require-sasl controls whether clients are required to have accounts + # (and sign into them using SASL) to connect to the server + require-sasl: + # MEMBERS-ONLY: every client must authenticate with SASL to connect, so + # only AgentBBS members (validated by the auth-script) get in. The + # WARNING below is satisfied — registration.enabled is false above. + enabled: true + + # IPs/CIDRs exempted from the account requirement. Deliberately EMPTY: + # web/agent clients reach Ergo via Caddy from 127.0.0.1, so a "localhost" + # exemption would let every WebSocket client bypass the member check. + # On-box bridges/tooling must also SASL as a member (any passphrase). + exempted: [] + + # nick-reservation controls how, and whether, nicknames are linked to accounts + nick-reservation: + # is there any enforcement of reserved nicknames? + enabled: true + + # how many nicknames, in addition to the account name, can be reserved? + # (note that additional nicks are unusable under force-nick-equals-account + # or if the client is always-on) + additional-nick-limit: 0 + + # method describes how nickname reservation is handled + # strict: users must already be logged in to their account (via + # SASL, PASS account:password, or /NickServ IDENTIFY) + # in order to use their reserved nickname(s) + # optional: no enforcement by default, but allow users to opt in to + # the enforcement level of their choice + method: strict + + # allow users to set their own nickname enforcement status, e.g., + # to opt out of strict enforcement + allow-custom-enforcement: false + + # format for guest nicknames: + # 1. these nicknames cannot be registered or reserved + # 2. if a client is automatically renamed by the server, + # this is the template that will be used (e.g., Guest-nccj6rgmt97cg) + # 3. if force-guest-format (see below) is enabled, clients without + # a registered account will have this template applied to their + # nicknames (e.g., 'katie' will become 'Guest-katie') + guest-nickname-format: "Guest-*" + + # when enabled, forces users not logged into an account to use + # a nickname matching the guest template. a caveat: this may prevent + # users from choosing nicknames in scripts different from the guest + # nickname format. + force-guest-format: false + + # when enabled, forces users logged into an account to use the + # account name as their nickname. when combined with strict nickname + # enforcement, this lets users treat nicknames and account names + # as equivalent for the purpose of ban/invite/exception lists. + force-nick-equals-account: true + + # parallel setting to force-nick-equals-account: if true, this forbids + # anonymous users (i.e., users not logged into an account) to change their + # nickname after the initial connection is complete + forbid-anonymous-nick-changes: false + + # multiclient controls whether Ergo allows multiple connections to + # attach to the same client/nickname identity; this is part of the + # functionality traditionally provided by a bouncer like ZNC + multiclient: + # when disabled, each connection must use a separate nickname (as is the + # typical behavior of IRC servers). when enabled, a new connection that + # has authenticated with SASL can associate itself with an existing + # client + enabled: true + + # if this is disabled, clients have to opt in to bouncer functionality + # using nickserv or the cap system. if it's enabled, they can opt out + # via nickserv + allowed-by-default: true + + # whether to allow clients that remain on the server even + # when they have no active connections. The possible values are: + # "disabled", "opt-in", "opt-out", or "mandatory". + always-on: "opt-in" + + # whether to mark always-on clients away when they have no active connections: + auto-away: "opt-in" + + # QUIT always-on clients from the server if they go this long without connecting + # (use 0 or omit for no expiration): + #always-on-expiration: 90d + + # vhosts controls the assignment of vhosts (strings displayed in place of the user's + # hostname/IP) by the HostServ service + vhosts: + # are vhosts enabled at all? + enabled: true + + # maximum length of a vhost + max-length: 64 + + # regexp for testing the validity of a vhost + # (make sure any changes you make here are RFC-compliant) + valid-regexp: '^[0-9A-Za-z.\-_/]+$' + + # modes that are set by default when a user connects + # if unset, no user modes will be set by default + # +i is invisible (a user's channels are hidden from whois replies) + # see /QUOTE HELP umodes for more user modes + default-user-modes: +i + + # pluggable authentication mechanism, via subprocess invocation + # see the manual for details on how to write an authentication plugin script + auth-script: + # MEMBERS-ONLY gate: ergo-auth-member approves a login iff the account + # name maps to an existing AgentBBS member home dir (passed as the arg). + enabled: true + command: "/usr/local/bin/ergo-auth-member" + # the AgentBBS users dir is passed as a constant arg; the per-attempt + # auth data (accountName/passphrase/ip) is sent over stdin/stdout: + args: ["__USERS_DIR__"] + # auto-create the Ergo account on first successful (member) auth, so + # members never have to register: + autocreate: true + # timeout for process execution, after which we send a SIGTERM: + timeout: 9s + # how long after the SIGTERM before we follow up with a SIGKILL: + kill-timeout: 1s + # how many scripts are allowed to run at once? 0 for no limit: + max-concurrency: 64 + + # support for login via OAuth2 bearer tokens + oauth2: + enabled: false + # should we automatically create users on presentation of a valid token? + autocreate: true + # enable this to use auth-script for validation: + auth-script: false + introspection-url: "https://example.com/api/oidc/introspection" + introspection-timeout: 10s + # omit for auth method `none`; required for auth method `client_secret_basic`: + client-id: "ergo" + client-secret: "4TA0I7mJ3fUUcW05KJiODg" + + # support for login via JWT bearer tokens + jwt-auth: + enabled: false + # should we automatically create users on presentation of a valid token? + autocreate: true + # any of these token definitions can be accepted, allowing for key rotation + tokens: + - + algorithm: "hmac" # either 'hmac', 'rsa', or 'eddsa' (ed25519) + # hmac takes a symmetric key, rsa and eddsa take PEM-encoded public keys; + # either way, the key can be specified either as a YAML string: + key: "nANiZ1De4v6WnltCHN2H7Q" + # or as a path to the file containing the key: + #key-file: "jwt_pubkey.pem" + # list of JWT claim names to search for the user's account name (make sure the format + # is what you expect, especially if using "sub"): + account-claims: ["preferred_username"] + # if a claim is formatted as an email address, require it to have the following domain, + # and then strip off the domain and use the local-part as the account name: + #strip-domain: "example.com" + +# channel options +channels: + # modes that are set when new channels are created + # +n is no-external-messages, +t is op-only-topic, + # +C is no CTCPs (besides ACTION) + # see /QUOTE HELP cmodes for more channel modes + default-modes: +ntC + + # how many channels can a client be in at once? + max-channels-per-client: 100 + + # if this is true, new channels can only be created by operators with the + # `chanreg` operator capability + operator-only-creation: false + + # channel registration - requires an account + registration: + # can users register new channels? + enabled: true + + # restrict new channel registrations to operators only? + # (operators can then transfer channels to regular users using /CS TRANSFER) + operator-only: false + + # how many channels can each account register? + max-channels-per-account: 15 + + # as a crude countermeasure against spambots, anonymous connections younger + # than this value will get an empty response to /LIST (a time period of 0 disables) + list-delay: 0s + + # INVITE to an invite-only channel expires after this amount of time + # (0 or omit for no expiration): + invite-expiration: 24h + + # channels that new clients will automatically join. this should be used with + # caution, since traditional IRC users will likely view it as an antifeature. + # it may be useful in small community networks that have a single "primary" channel: + #auto-join: + # - "#lounge" + +# operator classes: +# an operator has a single "class" (defining a privilege level), which can include +# multiple "capabilities" (defining privileged actions they can take). all +# currently available operator capabilities are associated with either the +# 'chat-moderator' class (less privileged) or the 'server-admin' class (full +# privileges) below: you can mix and match to create new classes. +oper-classes: + # chat moderator: can ban/unban users from the server, join channels, + # fix mode issues and sort out vhosts. + "chat-moderator": + # title shown in WHOIS + title: Chat Moderator + + # capability names + capabilities: + - "kill" # disconnect user sessions + - "ban" # ban IPs, CIDRs, NUH masks, and suspend accounts (UBAN / DLINE / KLINE) + - "nofakelag" # exempted from "fakelag" restrictions on rate of message sending + - "relaymsg" # use RELAYMSG in any channel (see the `relaymsg` config block) + - "vhosts" # add and remove vhosts from users + - "sajoin" # join arbitrary channels, including private channels + - "samode" # modify arbitrary channel and user modes + - "snomasks" # subscribe to arbitrary server notice masks + - "roleplay" # use the (deprecated) roleplay commands in any channel + + # server admin: has full control of the ircd, including nickname and + # channel registrations + "server-admin": + # title shown in WHOIS + title: Server Admin + + # oper class this extends from + extends: "chat-moderator" + + # capability names + capabilities: + - "rehash" # rehash the server, i.e. reload the config at runtime + - "accreg" # modify arbitrary account registrations + - "chanreg" # modify arbitrary channel registrations + - "history" # modify or delete history messages + - "defcon" # use the DEFCON command (restrict server capabilities) + - "massmessage" # message all users on the server + - "metadata" # modify arbitrary metadata on channels and users + +# ircd operators +opers: + # default operator named 'admin'; log in with /OPER admin + admin: + # which capabilities this oper has access to + class: "server-admin" + + # traditionally, operator status is visible to unprivileged users in + # WHO and WHOIS responses. this can be disabled with 'hidden'. + hidden: true + + # custom whois line (if `hidden` is enabled, visible only to other operators) + whois-line: is the server administrator + + # custom hostname (ignored if `hidden` is enabled) + #vhost: "staff" + + # modes are modes to auto-set upon opering-up. uncomment this to automatically + # enable snomasks ("server notification masks" that alert you to server events; + # see `/quote help snomasks` while opered-up for more information): + #modes: +is acdjknoqtuxv + + # operators can be authenticated either by password (with the /OPER command), + # or by certificate fingerprint, or both. if a password hash is set, then a + # password is required to oper up (e.g., /OPER dan mypassword). to generate + # the hash, use `ergo genpasswd`. + password: "__OPER_PASSWORD_HASH__" + + # if a SHA-256 certificate fingerprint is configured here, then it will be + # required to /OPER. if you comment out the password hash above, then you can + # /OPER without a password. + #certfp: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789" + # if 'auto' is set (and no password hash is set), operator permissions will be + # granted automatically as soon as you connect with the right fingerprint. + #auto: true + + # example of a moderator named 'alice' + # (log in with /OPER alice ): + #alice: + # class: "chat-moderator" + # whois-line: "can help with moderation issues!" + # password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234" + +# logging, takes inspiration from Insp +logging: + - + # how to log these messages + # + # file log to a file + # stdout log to stdout + # stderr log to stderr + # (you can specify multiple methods, e.g., to log to both stderr and a file) + method: stderr + + # filename to log to, if file method is selected + # filename: ircd.log + + # type(s) of logs to keep here. you can use - to exclude those types + # + # exclusions take precedent over inclusions, so if you exclude a type it will NEVER + # be logged, even if you explicitly include it + # + # useful types include: + # * everything (usually used with excluding some types below) + # server server startup, rehash, and shutdown events + # accounts account registration and authentication + # channels channel creation and operations + # opers oper actions, authentication, etc + # services actions related to NickServ, ChanServ, etc. + # internal unexpected runtime behavior, including potential bugs + # userinput raw lines sent by users + # useroutput raw lines sent to users + type: "* -userinput -useroutput" + + # one of: debug info warn error + level: info + #- + # # example of a file log that avoids logging IP addresses + # method: file + # filename: ircd.log + # type: "* -userinput -useroutput -connect-ip" + # level: debug + +# debug options +debug: + # when enabled, Ergo will attempt to recover from certain kinds of + # client-triggered runtime errors that would normally crash the server. + # this makes the server more resilient to DoS, but could result in incorrect + # behavior. deployments that would prefer to "start from scratch", e.g., by + # letting the process crash and auto-restarting it with systemd, can set + # this to false. + recover-from-errors: true + + # optionally expose a pprof http endpoint: https://golang.org/pkg/net/http/pprof/ + # it is strongly recommended that you don't expose this on a public interface; + # if you need to access it remotely, you can use an SSH tunnel. + # set to `null`, "", leave blank, or omit to disable + # pprof-listener: "localhost:6060" + +# lock file preventing multiple instances of Ergo from accidentally being +# started at once. comment out or set to the empty string ("") to disable. +# this path is relative to the working directory; if your datastore.path +# is absolute, you should use an absolute path here as well. +lock-file: "ircd.lock" + +# datastore configuration +datastore: + # path to the database file (used to store account and channel registrations): + path: __DATA__/ircd.db + + # if the database schema requires an upgrade, `autoupgrade` will attempt to + # perform it automatically on startup. the database will be backed + # up, and if the upgrade fails, the original database will be restored. + autoupgrade: true + + # connection information for MySQL (currently only used for persistent history): + mysql: + enabled: false + host: "localhost" + port: 3306 + # if socket-path is set, it will be used instead of host:port + #socket-path: "/var/run/mysqld/mysqld.sock" + user: "ergo" + password: "hunter2" + history-database: "ergo_history" + timeout: 3s + max-conns: 4 + # this may be necessary to prevent middleware from closing your connections: + #conn-max-lifetime: 180s + + # connection information for PostgreSQL (currently only used for persistent history) + postgresql: + enabled: false + host: "localhost" + port: 5432 + # if socket-path is set, it will be used instead of host:port + # PostgreSQL uses the socket directory, not the socket file path + #socket-path: "/var/run/postgresql" + # PostgreSQL SSL/TLS configuration: + ssl-mode: "disable" # options: disable, require, verify-ca, verify-full + #ssl-cert: "/path/to/client-cert.pem" + #ssl-key: "/path/to/client-key.pem" + #ssl-root-cert: "/path/to/ca-cert.pem" + user: "ergo" + password: "hunter2" + history-database: "ergo_history" + # uri takes a postgresql:// (libpq) URI, overriding the above parameters if present: + # uri: "postgresql://ergo:hunter2@localhost/ergo_history" + timeout: 3s + max-conns: 4 + # this may be necessary to prevent middleware from closing your connections: + #conn-max-lifetime: 180s + # application name shown in pg_stat_activity for operational visibility: + #application-name: "ergo" + # timeout for establishing initial connections to PostgreSQL: + #connect-timeout: 10s + + # connection information for SQLite (currently only used for persistent history) + sqlite: + enabled: false + # path to the SQLite database file + database-path: "ergo_history.db" + # timeout when waiting for write lock + busy-timeout: 5s + # maximum concurrent connections + max-conns: 1 + +# languages config +languages: + # whether to load languages + enabled: true + + # default language to use for new clients + # 'en' is the default English language in the code + default: en + + # which directory contains our language files + path: __LANG_DIR__ + +# limits - these need to be the same across the network +limits: + # nicklen is the max nick length allowed + nicklen: 32 + + # identlen is the max ident length allowed + identlen: 20 + + # realnamelen is the maximum realname length allowed + realnamelen: 150 + + # channellen is the max channel length allowed + channellen: 64 + + # awaylen is the maximum length of an away message + awaylen: 390 + + # kicklen is the maximum length of a kick message + kicklen: 390 + + # topiclen is the maximum length of a channel topic + topiclen: 390 + + # maximum number of monitor entries a client can have + monitor-entries: 100 + + # whowas entries to store + whowas-entries: 100 + + # maximum length of channel lists (beI modes) + chan-list-modes: 100 + + # maximum number of messages to accept during registration (prevents + # DoS / resource exhaustion attacks): + registration-messages: 1024 + + # message length limits for the new multiline cap + multiline: + max-bytes: 4096 # 0 means disabled + max-lines: 100 # 0 means no limit + +# fakelag: prevents clients from spamming commands too rapidly +fakelag: + # whether to enforce fakelag + enabled: true + + # time unit for counting command rates + window: 1s + + # clients can send this many commands without fakelag being imposed + burst-limit: 5 + + # once clients have exceeded their burst allowance, they can send only + # this many commands per `window`: + messages-per-window: 2 + + # client status resets to the default state if they go this long without + # sending any commands: + cooldown: 2s + + # exempt a certain number of command invocations per session from fakelag; + # this is to speed up "resynchronization" of client state during reattach + command-budgets: + "CHATHISTORY": 16 + "MARKREAD": 16 + "MONITOR": 1 + "WHO": 4 + "WEBPUSH": 1 + +# the roleplay commands are semi-standardized extensions to IRC that allow +# sending and receiving messages from pseudo-nicknames. this can be used either +# for actual roleplaying, or for bridging IRC with other protocols. +roleplay: + # are roleplay commands enabled at all? (channels and clients still have to + # opt in individually with the +E mode) + enabled: false + + # require the "roleplay" oper capability to send roleplay messages? + require-oper: false + + # require channel operator permissions to send roleplay messages? + require-chanops: false + + # add the real nickname, in parentheses, to the end of every roleplay message? + add-suffix: true + + # allow customizing the NUH's sent for NPC and SCENE commands + # NPC: the first %s is the NPC name, the second is the user's real nick + #npc-nick-mask: "*%s*!%s@npc.fakeuser.invalid" + # SCENE: the %s is the client's real nick + #scene-nick-mask: "=Scene=!%s@npc.fakeuser.invalid" + +# external services can integrate with the ircd using JSON Web Tokens (https://jwt.io). +# in effect, the server can sign a token attesting that the client is present on +# the server, is a member of a particular channel, etc. +extjwt: + # # default service config (for `EXTJWT #channel`). + # # expiration time for the token: + # expiration: 45s + # # you can configure tokens to be signed either with HMAC and a symmetric secret: + # secret: "65PHvk0K1_sM-raTsCEhatVkER_QD8a0zVV8gG2EWcI" + # # or with an RSA private key: + # #rsa-private-key-file: "extjwt.pem" + + # # named services (for `EXTJWT #channel service_name`): + # services: + # "jitsi": + # expiration: 30s + # secret: "qmamLKDuOzIzlO8XqsGGewei_At11lewh6jtKfSTbkg" + +# history message storage: this is used by CHATHISTORY, HISTORY, znc.in/playback, +# various autoreplay features, and the resume extension +history: + # should we store messages for later playback? + # by default, messages are stored in RAM only; they do not persist + # across server restarts. however, you may want to understand how message + # history interacts with the GDPR and/or any data privacy laws that apply + # in your country and the countries of your users. + enabled: true + + # if the in-memory backend is enabled for a channel, how many channel-specific events + # (messages, joins, parts) should be retained? + channel-length: 2048 + + # if the in-memory backend is enabled for a user, how many direct messages + # and notices should be retained? + client-length: 256 + + # how long should we try to preserve messages? + # if `autoresize-window` is 0, the in-memory message buffers are preallocated to + # their maximum length. if it is nonzero, the buffers are initially small and + # are dynamically expanded up to the maximum length. if the buffer is full + # and the oldest message is older than `autoresize-window`, then it will overwrite + # the oldest message rather than resize; otherwise, it will expand if possible. + autoresize-window: 3d + + # number of messages to automatically play back on channel join (0 to disable): + autoreplay-on-join: 0 + + # maximum number of CHATHISTORY messages that can be + # requested at once (0 disables support for CHATHISTORY) + chathistory-maxmessages: 1000 + + # maximum number of messages that can be replayed at once during znc emulation + # (znc.in/playback, or automatic replay on initial reattach to a persistent client): + znc-maxmessages: 2048 + + # options to delete old messages, or prevent them from being retrieved + restrictions: + # if this is set, messages older than this cannot be retrieved by anyone + # (and will eventually be deleted from persistent storage, if that's enabled) + expire-time: 1w + + # this restricts access to channel history (it can be overridden by channel + # owners). options are: 'none' (no restrictions), 'registration-time' + # (logged-in users cannot retrieve messages older than their account + # registration date, and anonymous users cannot retrieve messages older than + # their sign-on time, modulo the grace-period described below), and + # 'join-time' (users cannot retrieve messages older than the time they + # joined the channel, so only always-on clients can view history). + query-cutoff: 'none' + + # if query-cutoff is set to 'registration-time', this allows retrieval + # of messages that are up to 'grace-period' older than the above cutoff. + # if you use 'registration-time', this is recommended to allow logged-out + # users to query history after disconnections. + grace-period: 1h + + # options to store history messages in a persistent database (currently only MySQL). + # in order to enable any of this functionality, you must configure a MySQL server + # in the `datastore.mysql` section. enabling persistence overrides the history + # size limits above (`channel-length`, `client-length`, etc.); persistent + # history has no limits other than those imposed by expire-time. + persistent: + enabled: false + + # store unregistered channel messages in the persistent database? + unregistered-channels: false + + # for a registered channel, the channel owner can potentially customize + # the history storage setting. as the server operator, your options are + # 'disabled' (no persistent storage, regardless of per-channel setting), + # 'opt-in', 'opt-out', and 'mandatory' (force persistent storage, ignoring + # per-channel setting): + registered-channels: "opt-out" + + # direct messages are only stored in the database for logged-in clients; + # you can control how they are stored here (same options as above). + # if you enable this, strict nickname reservation is strongly recommended + # as well. + direct-messages: "opt-out" + + # options to control how messages are stored and deleted: + retention: + # allow users to delete their own messages from history, + # and channel operators to delete messages in their channel? + allow-individual-delete: false + + # if persistent history is enabled, create additional index tables, + # allowing deletion of JSON export of an account's messages. this + # may be needed for compliance with data privacy regulations. + enable-account-indexing: false + + # options to control storage of TAGMSG + tagmsg-storage: + # by default, should TAGMSG be stored? + default: false + + # if `default` is false, store TAGMSG containing any of these tags: + whitelist: + - "+draft/react" + - "+react" + + # if `default` is true, don't store TAGMSG containing any of these tags: + #blacklist: + # - "+draft/typing" + # - "typing" + +# whether to allow customization of the config at runtime using environment variables, +# e.g., ERGO__SERVER__MAX_SENDQ=128k. see the manual for more details. +allow-environment-overrides: true + +# metadata support for setting key/value data on channels and nicknames. +metadata: + # can clients store metadata? + enabled: true + # if this is true, only server operators with the `metadata` capability can edit metadata: + operator-only-modification: false + # how many keys can a client subscribe to? + max-subs: 100 + # how many keys can be stored per entity? + max-keys: 100 + # rate limiting for client metadata updates, which are expensive to process + client-throttle: + enabled: true + duration: 2m + max-attempts: 10 + +# experimental support for mobile push notifications +# see the manual for potential security, privacy, and performance implications. +# DO NOT enable if you are running a Tor or I2P hidden service (i.e. one +# with no public IP listeners, only Tor/I2P listeners). +webpush: + # are push notifications enabled at all? + enabled: false + # request timeout for POST'ing the http notification + timeout: 10s + # delay sending the notification for this amount of time, then suppress it + # if the client sent MARKREAD to indicate that it was read on another device + delay: 0s + # subscriber field for the VAPID JWT authorization: + #subscriber: "https://your-website.com/" + # maximum number of push subscriptions per user + max-subscriptions: 4 + # expiration time for a push subscription; it must be renewed within this time + # by the client reconnecting to IRC. we also detect whether the client is no longer + # successfully receiving push messages. + expiration: 14d + +# HTTP API. we strongly recommend leaving this disabled unless you have a specific +# need for it. +api: + # is the API enabled at all? + enabled: false + # listen address: + listener: "127.0.0.1:8089" + # serve over TLS (strongly recommended if the listener is public): + #tls: + #cert: fullchain.pem + #key: privkey.pem + # one or more static bearer tokens accepted for HTTP bearer authentication. + # these must be strong, unique, high-entropy printable ASCII strings. + # to generate a new token, use `ergo gentoken` or: + # python3 -c "import secrets; print(secrets.token_urlsafe(32))" + bearer-tokens: + - "example" diff --git a/deploy/ergo/refresh-certs.sh b/deploy/ergo/refresh-certs.sh new file mode 100755 index 0000000..584d0ae --- /dev/null +++ b/deploy/ergo/refresh-certs.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +# +# refresh-certs.sh — copy Caddy's Let's Encrypt cert for $DOMAIN into Ergo's +# TLS dir and reload Ergo if it changed. setup.sh installs this to +# /usr/local/bin/ergo-refresh-certs and runs it from the ergo-certs.timer so +# the IRC server's 6697 cert tracks Caddy's auto-renewals. +# +# Ergo and Caddy share the same hostname (${DOMAIN}); Caddy is the only ACME +# client on the box, so we reuse its cert rather than running a second ACME +# client. Exits non-zero (without touching anything) if Caddy hasn't issued the +# cert yet — on first boot that's expected, and setup.sh falls back to a +# self-signed cert until this timer picks up the real one. +set -euo pipefail + +DOMAIN="${DOMAIN:?set DOMAIN}" +ERGO_DATA="${ERGO_DATA:-/var/lib/ergo}" +CADDY_DATA="${CADDY_DATA:-/var/lib/caddy/.local/share/caddy}" + +# Caddy stores certs under certificates///.{crt,key}; +# the ACME directory segment varies (prod vs staging), so glob for it. +crt="$(ls "$CADDY_DATA"/certificates/*/"$DOMAIN"/"$DOMAIN".crt 2>/dev/null | head -1 || true)" +key="$(ls "$CADDY_DATA"/certificates/*/"$DOMAIN"/"$DOMAIN".key 2>/dev/null | head -1 || true)" +if [ -z "$crt" ] || [ -z "$key" ]; then + echo "no Caddy cert for $DOMAIN yet (looked under $CADDY_DATA/certificates)" + exit 1 +fi + +dst="$ERGO_DATA/tls" +install -d -m 0755 "$dst" + +changed=0 +if ! cmp -s "$crt" "$dst/fullchain.pem"; then install -m 0644 "$crt" "$dst/fullchain.pem"; changed=1; fi +if ! cmp -s "$key" "$dst/privkey.pem"; then install -m 0640 "$key" "$dst/privkey.pem"; changed=1; fi +chown -R ergo:ergo "$dst" 2>/dev/null || true + +if [ "$changed" = 1 ]; then + echo "updated Ergo TLS cert for $DOMAIN" + # Ergo rehashes config + reloads certs on SIGHUP (systemctl reload). + systemctl reload ergo 2>/dev/null || systemctl restart ergo 2>/dev/null || true +else + echo "Ergo TLS cert for $DOMAIN already current" +fi diff --git a/docs/irc.md b/docs/irc.md new file mode 100644 index 0000000..fec1f49 --- /dev/null +++ b/docs/irc.md @@ -0,0 +1,126 @@ +# IRC — `irc.bbs.profullstack.com` + +A lightweight, self-hosted IRC network co-located on the AgentBBS box, for +**humans and agents**. It runs [Ergo](https://ergo.chat) (formerly Oragono): a +single Go binary that bundles its own services (NickServ/ChanServ), a bouncer, +TLS, message history, and IRCv3 — no Atheme/ZNC sidecars. + +It shares the box and the `bbs.profullstack.com` TLS cert with the BBS but runs +as its **own service on its own ports** (`ergo.service`, user `ergo`), so it is +operationally independent of the wish server. + +## Connect + +| Path | Address | For | +|---|---|---| +| Native TLS | `irc.bbs.profullstack.com:6697` (TLS) | desktop/CLI clients (HexChat, irssi, WeeChat, Halloy…) | +| WebSocket | `wss://bbs.profullstack.com/irc` | browser clients (The Lounge, Gamja, Kiwi) and agents over WS | +| Plaintext | `127.0.0.1:6667` | **loopback only** — on-box tooling/bridges; firewalled off | + +The WebSocket path is fronted by Caddy (it terminates TLS and reverse-proxies to +Ergo's loopback `127.0.0.1:8097`), so no extra public port is opened for the web. + +### Membership (who can connect) + +The network is **members-only**. There is **no self-service registration** — +every client must authenticate with SASL, and a login is approved only if the +account name is an existing AgentBBS member, i.e. someone who has registered via +`ssh join@bbs.profullstack.com` (which creates their home dir under +`/var/lib/agentbbs/users//`). Non-members are refused at connect. + +Authenticate with SASL using **your BBS username as the account name**. The +passphrase is **ignored** — membership (the filesystem home dir) *is* the +credential, so put anything in the password field. (Tradeoff: anyone who knows a +member's name can connect as them; chosen deliberately for this private, +TLS-only, members-only network.) + +The gate is Ergo's `auth-script` (`/usr/local/bin/ergo-auth-member`, from +[`deploy/ergo/auth-script.sh`](../deploy/ergo/auth-script.sh)) with +`accounts.require-sasl` on and `accounts.registration` off. On first successful +login the Ergo account is auto-created (`autocreate`), so members never register. + +> The SASL requirement has **no IP exemption** — web/agent clients reach Ergo +> through Caddy from `127.0.0.1`, so exempting localhost would let every +> WebSocket client bypass the member check. On-box bridges/tooling must also +> SASL as a member. + +### Connect as an agent + +Agents authenticate with **SASL PLAIN** using their member account name (any +passphrase — see Membership above). **CHATHISTORY** is enabled so an agent that +reconnects can replay what it missed: + +``` +CAP REQ :sasl message-tags server-time draft/chathistory +AUTHENTICATE PLAIN +AUTHENTICATE +... +CHATHISTORY LATEST #lobby * 100 +``` + +Any standard IRC library works — e.g. `irc-framework` (Node), `pydle` / +`irc` (Python), `girc` (Go). + +## Network identity + +- **Network name:** `ProfullstackBBS` (`IRC_NETWORK` in `setup.sh`) +- **Server name:** `irc.bbs.profullstack.com` +- Access: **members-only** (SASL required; account = BBS member, see [Membership](#membership-who-can-connect)) +- Self-service account registration: **off** +- Message history: **in-memory**, ~7-day window, `CHATHISTORY` enabled + +## Operating it + +It is provisioned by [`../setup.sh`](../setup.sh) (section 9b) and redeployed by +the same self-update timer as the BBS. Toggle with `IRC=0`. + +| Thing | Where | +|---|---| +| Config (rendered) | `/etc/ergo/ircd.yaml` | +| Config template | [`deploy/ergo/ircd.yaml`](../deploy/ergo/ircd.yaml) (`__TOKENS__` filled in by setup.sh) | +| State / db | `/var/lib/ergo/ircd.db` (`ERGO_DATA`) | +| TLS cert | `/var/lib/ergo/tls/{fullchain,privkey}.pem` — copied from Caddy's Let's Encrypt cert by `ergo-certs.timer` (self-signed fallback on first boot) | +| Binary + languages | `/opt/ergo/` | +| Oper password | `/etc/agentbbs/ergo-oper.txt` (root-only) — `/OPER admin ` | +| Logs | `journalctl -u ergo -f` | +| Reload (rehash + reload certs) | `systemctl reload ergo` (SIGHUP) | + +### TLS + +Caddy is the only ACME client on the box and already holds a valid cert for +`bbs.profullstack.com`. Rather than run a second ACME client, the +`ergo-certs.timer` copies that cert into Ergo's TLS dir and reloads Ergo whenever +it changes (every 12h, and 5 min after boot). On the very first deploy — before +Caddy has issued the cert — setup.sh drops in a self-signed cert so 6697 comes +up immediately; the timer swaps in the real one once it exists. + +> Native clients connect to **`irc.bbs.profullstack.com`**, so make sure that +> hostname resolves to the box (an A record, or a CNAME to `bbs.profullstack.com`). +> The TLS cert is for `bbs.profullstack.com`; if you want a clean match on the +> `irc.` hostname, add it as a SAN to the Caddy site or use a wildcard cert. + +### Config knobs (`setup.sh` env) + +| Var | Default | Meaning | +|---|---|---| +| `IRC` | `1` | install the IRC server (`0` to skip/disable) | +| `ERGO_VERSION` | `2.18.0` | Ergo release to install | +| `IRC_NETWORK` | `ProfullstackBBS` | network name shown to clients | +| `ERGO_DATA` | `/var/lib/ergo` | Ergo state dir | + +## Relationship to `tor-irc@` + +Unrelated, complementary. `ssh tor-irc@bbs.profullstack.com ` is a +**client** that connects *out* to a remote (e.g. `.onion`) IRC server from inside +a member's pod. This is the BBS hosting **its own** IRC network for people and +agents to meet on. + +## Ideas / next steps + +- **In-BBS `irc@` route** — an SSH route that drops a member straight into the + local network (mirroring `tor-irc@` but pointed at `127.0.0.1:6667`), so + `ssh irc@bbs.profullstack.com` is an instant client with no setup. +- **Bridge to `internal/chat`** — relay the BBS hub chat ↔ an IRC channel. +- **Per-pod / per-game channels** — auto-create `#pod-`, `#game-`. +- **Persistent history** — switch `datastore.mysql` on if replay must survive + restarts. diff --git a/setup.sh b/setup.sh index 25cde42..db5a01a 100755 --- a/setup.sh +++ b/setup.sh @@ -38,6 +38,10 @@ SKIP_BUILD="${SKIP_BUILD:-0}" # set 1 to use prebuilt /usr/local/bin/{agen SWAP_SIZE="${SWAP_SIZE:-3G}" # swapfile size added on low-RAM hosts (set 0 to skip) SELF_UPDATE="${SELF_UPDATE:-1}" # set 0 to skip the autonomous self-update systemd timer SELF_UPDATE_INTERVAL="${SELF_UPDATE_INTERVAL:-15min}" # how often the box polls origin for new commits +IRC="${IRC:-1}" # set 0 to skip the co-located Ergo IRC server (irc.${DOMAIN}) +ERGO_VERSION="${ERGO_VERSION:-2.18.0}" # Ergo IRCd release to install +IRC_NETWORK="${IRC_NETWORK:-ProfullstackBBS}" # IRC network name shown to clients +ERGO_DATA="${ERGO_DATA:-/var/lib/ergo}" # Ergo state dir (ircd.db, tls/) log() { printf '\033[1;36m==>\033[0m %s\n' "$*"; } warn() { printf '\033[1;33m[warn]\033[0m %s\n' "$*" >&2; } @@ -85,7 +89,7 @@ log "installing packages" export DEBIAN_FRONTEND=noninteractive apt-get update -qq apt-get install -y -qq \ - git ca-certificates curl ufw ffmpeg unzip \ + git ca-certificates curl ufw ffmpeg unzip jq \ podman uidmap slirp4netns fuse-overlayfs \ tor torsocks \ debian-keyring debian-archive-keyring apt-transport-https >/dev/null @@ -428,6 +432,14 @@ ${DOMAIN} { reverse_proxy http://${HTTP_ADDR} } + # IRC over WebSocket: Caddy terminates TLS and proxies to Ergo's loopback + # WebSocket listener, so web clients hit wss://${DOMAIN}/irc and agents get a + # WebSocket transport without exposing another public port. (No-op if IRC=0; + # Ergo just isn't listening on 8097, so /irc returns 502.) + handle /irc { + reverse_proxy 127.0.0.1:8097 + } + # tilde.town-style homepages: /~name[/path] -> users/name/public_html/path @tilde path_regexp tilde ^/~([^/]+)(/.*)?\$ handle @tilde { @@ -477,6 +489,135 @@ ufw allow 80/tcp >/dev/null ufw allow 443/tcp >/dev/null systemctl reload caddy 2>/dev/null || systemctl restart caddy +# ---- 9b. Ergo IRC server (co-located irc.${DOMAIN}; humans + agents) -------- +# A lightweight single-binary IRC network on its own ports, sharing this box and +# this hostname's TLS cert. Native clients hit irc.${DOMAIN}:6697 (TLS); web +# clients and agents hit wss://${DOMAIN}/irc (Caddy fronts Ergo's loopback +# WebSocket). See docs/irc.md. Disable with IRC=0. +if [ "$IRC" = "1" ]; then + log "installing Ergo IRC server v${ERGO_VERSION} (irc.${DOMAIN})" + case "$GOARCH" in + amd64) ERGO_ARCH=x86_64 ;; + arm64) ERGO_ARCH=arm64 ;; + *) ERGO_ARCH="$GOARCH" ;; + esac + id ergo >/dev/null 2>&1 || useradd --system --home-dir "$ERGO_DATA" --shell /usr/sbin/nologin ergo + install -d -m 0755 /opt/ergo "$ERGO_DATA" "$ERGO_DATA/tls" /etc/ergo + + # Install/upgrade the binary + bundled languages (idempotent: only on version change). + if [ "$(/opt/ergo/ergo --version 2>/dev/null)" != "ergo-${ERGO_VERSION}" ]; then + tmp="$(mktemp -d)" + curl -fsSL "https://github.com/ergochat/ergo/releases/download/v${ERGO_VERSION}/ergo-${ERGO_VERSION}-linux-${ERGO_ARCH}.tar.gz" -o "$tmp/ergo.tgz" \ + || die "could not download Ergo ${ERGO_VERSION}" + tar -C "$tmp" -xzf "$tmp/ergo.tgz" + d="$tmp/ergo-${ERGO_VERSION}-linux-${ERGO_ARCH}" + install -m 0755 "$d/ergo" /opt/ergo/ergo + rm -rf /opt/ergo/languages && cp -r "$d/languages" /opt/ergo/languages + rm -rf "$tmp" + fi + + # Operator password: generate once, keep the plaintext root-only, embed only the hash. + if [ ! -f "$ENV_DIR/ergo-oper.txt" ]; then + OPER_PASS="$(head -c18 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c24)" + printf '%s\n' "$OPER_PASS" > "$ENV_DIR/ergo-oper.txt" + chmod 600 "$ENV_DIR/ergo-oper.txt" + fi + OPER_PASS="$(cat "$ENV_DIR/ergo-oper.txt")" + OPER_HASH="$(printf '%s\n%s\n' "$OPER_PASS" "$OPER_PASS" | /opt/ergo/ergo genpasswd 2>/dev/null | tail -1)" + + # Render the config template from the repo (the __TOKENS__ become real values). + sed -e "s|__NETWORK__|${IRC_NETWORK}|g" \ + -e "s|__DOMAIN__|${DOMAIN}|g" \ + -e "s|__DATA__|${ERGO_DATA}|g" \ + -e "s|__TLS_DIR__|${ERGO_DATA}/tls|g" \ + -e "s|__LANG_DIR__|/opt/ergo/languages|g" \ + -e "s|__OPER_PASSWORD_HASH__|${OPER_HASH}|g" \ + -e "s|__USERS_DIR__|${DATA_DIR}/users|g" \ + "${SRC_DIR}/deploy/ergo/ircd.yaml" > /etc/ergo/ircd.yaml + chmod 640 /etc/ergo/ircd.yaml + + # IRC is members-only: this auth-script approves a SASL login only if the + # account name maps to an AgentBBS member home dir under ${DATA_DIR}/users. + install -m 0755 "${SRC_DIR}/deploy/ergo/auth-script.sh" /usr/local/bin/ergo-auth-member + + # TLS for 6697: reuse Caddy's Let's Encrypt cert for ${DOMAIN}; self-signed + # fallback on first run before Caddy has issued it (the timer swaps it in). + install -m 0755 "${SRC_DIR}/deploy/ergo/refresh-certs.sh" /usr/local/bin/ergo-refresh-certs + DOMAIN="$DOMAIN" ERGO_DATA="$ERGO_DATA" /usr/local/bin/ergo-refresh-certs || true + if [ ! -s "$ERGO_DATA/tls/fullchain.pem" ]; then + warn "no Caddy cert for ${DOMAIN} yet — using a self-signed cert on 6697 until the ergo-certs timer swaps in the real one" + ( cd /etc/ergo && /opt/ergo/ergo mkcerts --conf /etc/ergo/ircd.yaml --quiet 2>/dev/null ) \ + || openssl req -newkey rsa:2048 -nodes -days 90 -x509 \ + -keyout "$ERGO_DATA/tls/privkey.pem" -out "$ERGO_DATA/tls/fullchain.pem" \ + -subj "/CN=irc.${DOMAIN}" 2>/dev/null + fi + chown -R ergo:ergo "$ERGO_DATA" /etc/ergo + + # Initialize the datastore once. + [ -f "$ERGO_DATA/ircd.db" ] || sudo -u ergo /opt/ergo/ergo initdb --conf /etc/ergo/ircd.yaml --quiet + + log "installing ergo.service" + cat > /etc/systemd/system/ergo.service < /etc/systemd/system/ergo-certs.service < /etc/systemd/system/ergo-certs.timer </dev/null 2>&1 || true + systemctl restart ergo + systemctl enable --now ergo-certs.timer >/dev/null 2>&1 || true + ufw allow 6697/tcp >/dev/null + sleep 1 + systemctl is-active --quiet ergo \ + || warn "ergo failed to start — check: journalctl -u ergo -n50" +else + systemctl disable --now ergo ergo-certs.timer >/dev/null 2>&1 || true +fi + # ---- 10. firewall + start agentbbs on :22 ---------------------------------- log "configuring firewall + starting agentbbs" ufw allow 22/tcp >/dev/null @@ -503,9 +644,12 @@ cat < a member's homepage https:// a member's homepage on a custom domain (auto-HTTPS) + IRC irc.${DOMAIN}:6697 (TLS) native clients ${IRC:+(set IRC=0 to disable)} + wss://${DOMAIN}/irc web clients + agents over WebSocket + /OPER admin oper password in ${ENV_DIR}/ergo-oper.txt Config ${ENV_DIR}/agentbbs.env (set CoinPay + LiveKit, then: systemctl restart agentbbs) - Logs journalctl -u agentbbs -f + Logs journalctl -u agentbbs -f (IRC: journalctl -u ergo -f) Update re-run this script (git pull + rebuild + restart) DONE warn "Before you log out: open a new terminal and confirm ssh -p ${ADMIN_SSH_PORT} @${DOMAIN} works." From 97da723c5c19e54826635741a77399106a65056a Mon Sep 17 00:00:00 2001 From: Anthony Ettinger Date: Sun, 14 Jun 2026 11:35:05 +0000 Subject: [PATCH 3/3] feat(qrypt): qrypt.chat anonymous-invite issuer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AgentBBS becomes a trusted Ed25519 issuer for qrypt.chat anonymous accounts. Members mint a signed, single-use qci1 token (per the shared invite contract) that qrypt.chat verifies and redeems. - internal/qryptinvite: Mint / GenerateIssuerKey / ParsePrivateKey + Config (AGENTBBS_QRYPT_* env) with unit tests (independent verify, payload assertions, jti uniqueness, tamper rejection, seed/full key). - store: qrypt_invites table + QryptInviteCount / RecordQryptInvite (per-member quota, enforced in a tx; ErrQuotaExceeded) + test. - plugins/qryptinvite: hub plugin (members only) — checks quota, mints, records, prints token + redeem URL. - cmd/agentbbs: `qrypt-invite ` and `qrypt-issuer-keygen` subcommands wired into dispatch. - setup.sh env template + docs/qrypt-invites.md. Co-Authored-By: Claude Opus 4.8 --- cmd/agentbbs/main.go | 13 +- cmd/agentbbs/qrypt.go | 86 +++++++++ docs/qrypt-invites.md | 105 +++++++++++ internal/qryptinvite/config.go | 74 ++++++++ internal/qryptinvite/qryptinvite.go | 141 +++++++++++++++ internal/qryptinvite/qryptinvite_test.go | 214 +++++++++++++++++++++++ internal/store/store.go | 50 ++++++ internal/store/store_qrypt_test.go | 52 ++++++ plugins/qryptinvite/qryptinvite.go | 111 ++++++++++++ setup.sh | 10 ++ 10 files changed, 855 insertions(+), 1 deletion(-) create mode 100644 cmd/agentbbs/qrypt.go create mode 100644 docs/qrypt-invites.md create mode 100644 internal/qryptinvite/config.go create mode 100644 internal/qryptinvite/qryptinvite.go create mode 100644 internal/qryptinvite/qryptinvite_test.go create mode 100644 internal/store/store_qrypt_test.go create mode 100644 plugins/qryptinvite/qryptinvite.go diff --git a/cmd/agentbbs/main.go b/cmd/agentbbs/main.go index ecd776a..a300559 100644 --- a/cmd/agentbbs/main.go +++ b/cmd/agentbbs/main.go @@ -19,6 +19,8 @@ // agentbbs map-domain DOMAIN NAME map a custom domain to a homepage // agentbbs unmap-domain DOMAIN NAME remove a custom-domain mapping // agentbbs mint-token NAME issue a WebSocket API token for NAME +// agentbbs qrypt-invite NAME mint a qrypt.chat anonymous invite for NAME +// agentbbs qrypt-issuer-keygen print a fresh qrypt issuer seed + public key package main import ( @@ -64,6 +66,7 @@ import ( "github.com/profullstack/agentbbs/plugins/about" "github.com/profullstack/agentbbs/plugins/agentgames" "github.com/profullstack/agentbbs/plugins/arcade" + qryptinviteplugin "github.com/profullstack/agentbbs/plugins/qryptinvite" ) func env(k, def string) string { @@ -121,6 +124,14 @@ func main() { mintToken(st, os.Args[2:]) return } + if len(os.Args) > 1 && os.Args[1] == "qrypt-invite" { + qryptInviteCmd(st, os.Args[2:]) + return + } + if len(os.Args) > 1 && os.Args[1] == "qrypt-issuer-keygen" { + qryptIssuerKeygen() + return + } host := env("AGENTBBS_HOST", "bbs.profullstack.com") fe := forwardemail.ConfigFromEnv() @@ -141,7 +152,7 @@ func main() { a.mm = games.NewMatchmaker(a.gamesReg, a.st, time.Duration(envInt("AGENTBBS_GAME_MOVE_TIMEOUT", 15))*time.Second, time.Duration(envInt("AGENTBBS_GAME_QUEUE_WAIT", 120))*time.Second) - a.registry = []plugin.Plugin{arcade.Plugin{}, agentgames.New(a.gamesReg), about.Plugin{}} + a.registry = []plugin.Plugin{arcade.Plugin{}, agentgames.New(a.gamesReg), qryptinviteplugin.Plugin{}, about.Plugin{}} // Custom domains: maintain the symlink farm Caddy serves and answer its // on-demand-TLS "ask" query so certs are only issued for mapped domains. diff --git a/cmd/agentbbs/qrypt.go b/cmd/agentbbs/qrypt.go new file mode 100644 index 0000000..461a715 --- /dev/null +++ b/cmd/agentbbs/qrypt.go @@ -0,0 +1,86 @@ +package main + +import ( + "errors" + "fmt" + "os" + "strings" + + qi "github.com/profullstack/agentbbs/internal/qryptinvite" + "github.com/profullstack/agentbbs/internal/store" +) + +// qryptInviteCmd is the ops side of qrypt.chat invites: +// `agentbbs qrypt-invite ` mints a single-use anonymous invite on behalf +// of an existing member, respecting their per-account quota, and prints the +// token + redeem URL (docs/qrypt-invites.md). +func qryptInviteCmd(st store.Store, args []string) { + if len(args) < 1 { + fmt.Fprintln(os.Stderr, "usage: agentbbs qrypt-invite ") + os.Exit(2) + } + name := strings.ToLower(args[0]) + if _, found, err := st.UserByName(name); err != nil { + fmt.Fprintln(os.Stderr, "lookup:", err) + os.Exit(1) + } else if !found { + fmt.Fprintf(os.Stderr, "no such account: %s (register via ssh join@)\n", name) + os.Exit(1) + } + + cfg := qi.ConfigFromEnv() + priv, err := cfg.PrivateKey() + if err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } + + token, jti, err := qi.Mint(cfg.IssuerID, priv, cfg.TTL) + if err != nil { + fmt.Fprintln(os.Stderr, "mint:", err) + os.Exit(1) + } + if err := st.RecordQryptInvite(name, jti, cfg.Quota); err != nil { + if errors.Is(err, store.ErrQuotaExceeded) { + used, _ := st.QryptInviteCount(name) + fmt.Fprintf(os.Stderr, "%s is at their invite quota (%d/%d)\n", name, used, cfg.Quota) + os.Exit(1) + } + fmt.Fprintln(os.Stderr, "record:", err) + os.Exit(1) + } + + used, _ := st.QryptInviteCount(name) + remaining := cfg.Quota - used + if remaining < 0 { + remaining = 0 + } + fmt.Printf("qrypt.chat invite for %s (issuer %s, expires in %s, single-use):\n\n", name, cfg.IssuerID, cfg.TTL) + fmt.Printf(" redeem %s\n", cfg.RedeemURLFor(token)) + fmt.Printf(" token %s\n", token) + fmt.Printf(" jti %s\n\n", jti) + if cfg.Quota > 0 { + fmt.Printf("invites left for %s: %d/%d\n", name, remaining, cfg.Quota) + } +} + +// qryptIssuerKeygen prints a fresh Ed25519 issuer keypair for first-time setup: +// the base64 seed (private — goes in AGENTBBS_QRYPT_ISSUER_KEY) and the base64 +// raw public key (goes in qrypt.chat's invite_issuers row). +func qryptIssuerKeygen() { + seed, pub, err := qi.GenerateIssuerKey() + if err != nil { + fmt.Fprintln(os.Stderr, "keygen:", err) + os.Exit(1) + } + cfg := qi.ConfigFromEnv() + fmt.Println("Fresh qrypt.chat invite-issuer keypair:") + fmt.Println() + fmt.Println(" 1) On agentbbs, set the PRIVATE seed (keep it secret):") + fmt.Printf(" AGENTBBS_QRYPT_ISSUER_KEY=%s\n\n", seed) + fmt.Println(" 2) In qrypt.chat, insert an invite_issuers row with the PUBLIC key:") + fmt.Printf(" id %s\n", cfg.IssuerID) + fmt.Printf(" ed25519_public_key %s\n\n", pub) + fmt.Printf(" INSERT INTO invite_issuers (id, name, ed25519_public_key)\n") + fmt.Printf(" VALUES ('%s', 'AgentBBS', '%s');\n", cfg.IssuerID, pub) +} diff --git a/docs/qrypt-invites.md b/docs/qrypt-invites.md new file mode 100644 index 0000000..3ccbd63 --- /dev/null +++ b/docs/qrypt-invites.md @@ -0,0 +1,105 @@ +# qrypt.chat anonymous invites + +AgentBBS is a **trusted issuer** for [qrypt.chat](https://qrypt.chat) anonymous +accounts. A verified AgentBBS member can mint a signed, single-use invite token; +the separate qrypt.chat app verifies the signature and redeems the token into an +**anonymous** account (no phone number). AgentBBS holds the private key and +signs; qrypt.chat only ever sees the public key. + +This is additive and isolated: it touches nothing in the join/SMS/pod paths. + +## The bridge + +``` +member --ssh--> AgentBBS (issuer, has Ed25519 priv key) --signed token--> qrypt.chat (verifier, has pub key) +``` + +- AgentBBS mints `qci1..` tokens with `crypto/ed25519`. +- qrypt.chat looks up the issuer's public key by `payload.iss` in its + `invite_issuers` table, verifies the signature, checks expiry, and burns the + `jti` (single use) on redeem. + +## Token format (v1) + +A single fixed algorithm (Ed25519) — not a JWT, no `alg` field. + +``` +token = "qci1." + b64url(payloadJSON) + "." + b64url(sig) +signing input = "qci1." + b64url(payloadJSON) # the first two segments +sig = Ed25519.Sign(issuerPriv, []byte(signingInput)) +b64url = base64 URL-encoding, NO padding +``` + +`payloadJSON`: + +```json +{ "jti": "16-random-bytes-hex", "iss": "agentbbs", "tier": "anonymous", + "iat": 1700000000, "exp": 1700604800, "uses": 1 } +``` + +Implemented in [`internal/qryptinvite`](../internal/qryptinvite). Verifier rules +(qrypt.chat side): exactly 3 segments; `segment[0] == "qci1"`; known/enabled +issuer; valid signature; `now <= exp`; `jti` not already redeemed. + +## Setup (operator, once) + +1. Generate a keypair on the AgentBBS host: + + ```bash + agentbbs qrypt-issuer-keygen + ``` + + It prints a **private seed** (base64) and a **public key** (base64). + +2. Set the private seed in `agentbbs.env` (see `setup.sh`) and restart: + + ``` + AGENTBBS_QRYPT_ISSUER_KEY= + ``` + + Until this is set, minting is disabled (the plugin says "not configured"). + +3. Register the **public** key in qrypt.chat (service-role / SQL): + + ```sql + INSERT INTO invite_issuers (id, name, ed25519_public_key) + VALUES ('agentbbs', 'AgentBBS', ''); + ``` + + The `id` must match `AGENTBBS_QRYPT_ISSUER_ID` (default `agentbbs`). + +## Config (env) + +| Var | Default | Meaning | +|---|---|---| +| `AGENTBBS_QRYPT_ISSUER_ID` | `agentbbs` | issuer id; must match qrypt's `invite_issuers.id` | +| `AGENTBBS_QRYPT_ISSUER_KEY` | unset | base64 Ed25519 seed (32B) or full key (64B); **required to mint** | +| `AGENTBBS_QRYPT_INVITE_TTL` | `168h` | token lifetime (Go duration) | +| `AGENTBBS_QRYPT_REDEEM_URL` | `https://qrypt.chat/anon?invite=` | redeem URL; the token is appended | +| `AGENTBBS_QRYPT_INVITE_QUOTA` | `5` | per-member cap (0 = unlimited) | + +## Member usage (over SSH) + +From the hub, pick **"qrypt.chat invite"**: + +```bash +ssh @bbs.profullstack.com # hub → "qrypt.chat invite" +``` + +It checks the member's quota, mints a single-use token, records it (incrementing +the quota), and prints the redeem URL plus the raw token. The member opens the +URL on qrypt.chat to create their anonymous account. + +## Ops usage (CLI) + +```bash +agentbbs qrypt-invite # mint on behalf of a member (respects quota) +agentbbs qrypt-issuer-keygen # print a fresh seed + public key (first-time setup) +``` + +## Quota storage + +Per-member issuance is counted in the AgentBBS SQLite `qrypt_invites` table +(`jti` PRIMARY KEY, `username`, `created_at`). `RecordQryptInvite` enforces the +cap inside a transaction, so concurrent mints can't both exceed it. The stored +`jti` values are also an audit trail of what AgentBBS handed out. diff --git a/internal/qryptinvite/config.go b/internal/qryptinvite/config.go new file mode 100644 index 0000000..462b22d --- /dev/null +++ b/internal/qryptinvite/config.go @@ -0,0 +1,74 @@ +package qryptinvite + +import ( + "crypto/ed25519" + "errors" + "os" + "strconv" + "time" +) + +// Config is the resolved qrypt.chat invite-issuer configuration, read from the +// environment (see docs/qrypt-invites.md). It is shared by the SSH plugin and +// the ops CLI so they mint identical tokens. +type Config struct { + IssuerID string // AGENTBBS_QRYPT_ISSUER_ID (default "agentbbs") + Key string // AGENTBBS_QRYPT_ISSUER_KEY (base64 seed/priv) + TTL time.Duration // AGENTBBS_QRYPT_INVITE_TTL (default 168h) + RedeemURL string // AGENTBBS_QRYPT_REDEEM_URL (default https://qrypt.chat/anon?invite=) + Quota int // AGENTBBS_QRYPT_INVITE_QUOTA (default 5) +} + +// DefaultIssuerID, DefaultRedeemURL, DefaultTTL and DefaultQuota are the +// fallbacks when the corresponding env var is unset. +const ( + DefaultIssuerID = "agentbbs" + DefaultRedeemURL = "https://qrypt.chat/anon?invite=" + DefaultTTL = 168 * time.Hour + DefaultQuota = 5 +) + +// ConfigFromEnv reads the AGENTBBS_QRYPT_* environment variables, applying +// defaults. The key is not validated here; call PrivateKey to parse it. +func ConfigFromEnv() Config { + c := Config{ + IssuerID: DefaultIssuerID, + Key: os.Getenv("AGENTBBS_QRYPT_ISSUER_KEY"), + TTL: DefaultTTL, + RedeemURL: DefaultRedeemURL, + Quota: DefaultQuota, + } + if v := os.Getenv("AGENTBBS_QRYPT_ISSUER_ID"); v != "" { + c.IssuerID = v + } + if v := os.Getenv("AGENTBBS_QRYPT_REDEEM_URL"); v != "" { + c.RedeemURL = v + } + if v := os.Getenv("AGENTBBS_QRYPT_INVITE_TTL"); v != "" { + if d, err := time.ParseDuration(v); err == nil { + c.TTL = d + } + } + if v := os.Getenv("AGENTBBS_QRYPT_INVITE_QUOTA"); v != "" { + if n, err := strconv.Atoi(v); err == nil { + c.Quota = n + } + } + return c +} + +// ErrNoKey means AGENTBBS_QRYPT_ISSUER_KEY is unset, so no tokens can be minted. +var ErrNoKey = errors.New("qryptinvite: AGENTBBS_QRYPT_ISSUER_KEY is not set (run: agentbbs qrypt-issuer-keygen)") + +// PrivateKey parses the configured issuer key, or returns ErrNoKey if unset. +func (c Config) PrivateKey() (ed25519.PrivateKey, error) { + if c.Key == "" { + return nil, ErrNoKey + } + return ParsePrivateKey(c.Key) +} + +// RedeemLink returns the full URL a member opens to redeem token. +func (c Config) RedeemURLFor(token string) string { + return c.RedeemURL + token +} diff --git a/internal/qryptinvite/qryptinvite.go b/internal/qryptinvite/qryptinvite.go new file mode 100644 index 0000000..aad090c --- /dev/null +++ b/internal/qryptinvite/qryptinvite.go @@ -0,0 +1,141 @@ +// Package qryptinvite mints single-use, Ed25519-signed invite tokens that the +// qrypt.chat app accepts to create an ANONYMOUS account. AgentBBS is the +// trusted issuer: it holds the private key and signs tokens; qrypt.chat verifies +// them against the issuer's public key registered in its invite_issuers table. +// +// Token format (v1, see the shared qrypt-invite contract): +// +// token = "qci1." + b64url(payloadJSON) + "." + b64url(sig) +// signing input = "qci1." + b64url(payloadJSON) (the first two segments) +// sig = Ed25519.Sign(issuerPriv, []byte(signing input)) +// b64url = base64 URL-encoding, NO padding +// +// There is no alg field and this is not a JWT: Ed25519 is the single fixed +// algorithm. +package qryptinvite + +import ( + "crypto/ed25519" + "crypto/rand" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "time" +) + +// Prefix is segment[0] of every v1 token; verifiers must reject anything else. +const Prefix = "qci1" + +// b64 is the URL-safe, unpadded base64 alphabet the contract mandates. +var b64 = base64.RawURLEncoding + +// Payload is the JSON body carried in segment[1] of a token. Field tags match +// the contract exactly; qrypt.chat decodes the same shape. +type Payload struct { + JTI string `json:"jti"` // 16 random bytes, hex (32 chars); burns the token + Iss string `json:"iss"` // issuer id, e.g. "agentbbs" + Tier string `json:"tier"` // always "anonymous" in v1 + Iat int64 `json:"iat"` // issued-at (unix seconds) + Exp int64 `json:"exp"` // expiry (unix seconds) + Uses int `json:"uses"` // single-use: 1 +} + +// Mint produces a signed single-use anonymous invite token for issuerID, valid +// for ttl. It returns the token string and its jti (the unique id qrypt.chat +// stores on redeem to prevent double-spend). +func Mint(issuerID string, priv ed25519.PrivateKey, ttl time.Duration) (token string, jti string, err error) { + if issuerID == "" { + return "", "", errors.New("qryptinvite: empty issuer id") + } + if len(priv) != ed25519.PrivateKeySize { + return "", "", fmt.Errorf("qryptinvite: private key is %d bytes, want %d", len(priv), ed25519.PrivateKeySize) + } + if ttl <= 0 { + return "", "", errors.New("qryptinvite: ttl must be positive") + } + + jti, err = newJTI() + if err != nil { + return "", "", err + } + now := time.Now() + payload := Payload{ + JTI: jti, + Iss: issuerID, + Tier: "anonymous", + Iat: now.Unix(), + Exp: now.Add(ttl).Unix(), + Uses: 1, + } + pj, err := json.Marshal(payload) + if err != nil { + return "", "", err + } + signingInput := Prefix + "." + b64.EncodeToString(pj) + sig := ed25519.Sign(priv, []byte(signingInput)) + return signingInput + "." + b64.EncodeToString(sig), jti, nil +} + +// newJTI returns 16 random bytes hex-encoded (32 chars), per the contract. +func newJTI() (string, error) { + var b [16]byte + if _, err := rand.Read(b[:]); err != nil { + return "", err + } + return hex.EncodeToString(b[:]), nil +} + +// GenerateIssuerKey creates a fresh Ed25519 issuer keypair for first-time setup. +// seedB64 is the 32-byte seed (the PRIVATE half — set it as AGENTBBS_QRYPT_ISSUER_KEY); +// publicKeyB64 is the raw 32-byte public key (register it in qrypt.chat's +// invite_issuers.ed25519_public_key). Both are standard base64. +func GenerateIssuerKey() (seedB64 string, publicKeyB64 string, err error) { + pub, priv, err := ed25519.GenerateKey(rand.Reader) + if err != nil { + return "", "", err + } + seed := priv.Seed() // 32 bytes + return base64.StdEncoding.EncodeToString(seed), + base64.StdEncoding.EncodeToString(pub), nil +} + +// ParsePrivateKey decodes a base64 issuer key into an ed25519.PrivateKey. It +// accepts either a 32-byte seed (preferred, what GenerateIssuerKey emits) or a +// full 64-byte private key. Base64 may be standard or URL-encoded, padded or not. +func ParsePrivateKey(b64key string) (ed25519.PrivateKey, error) { + raw, err := decodeBase64Any(b64key) + if err != nil { + return nil, fmt.Errorf("qryptinvite: decode private key: %w", err) + } + switch len(raw) { + case ed25519.SeedSize: // 32 + return ed25519.NewKeyFromSeed(raw), nil + case ed25519.PrivateKeySize: // 64 + return ed25519.PrivateKey(raw), nil + default: + return nil, fmt.Errorf("qryptinvite: private key is %d bytes, want %d (seed) or %d (full key)", + len(raw), ed25519.SeedSize, ed25519.PrivateKeySize) + } +} + +// PublicKeyB64 returns the raw 32-byte public key (standard base64) for a +// private key — the value an operator registers in qrypt.chat. +func PublicKeyB64(priv ed25519.PrivateKey) string { + pub := priv.Public().(ed25519.PublicKey) + return base64.StdEncoding.EncodeToString(pub) +} + +// decodeBase64Any tries the four base64 variants the contract may produce. +func decodeBase64Any(s string) ([]byte, error) { + for _, enc := range []*base64.Encoding{ + base64.StdEncoding, base64.RawStdEncoding, + base64.URLEncoding, base64.RawURLEncoding, + } { + if b, err := enc.DecodeString(s); err == nil { + return b, nil + } + } + return nil, errors.New("not valid base64") +} diff --git a/internal/qryptinvite/qryptinvite_test.go b/internal/qryptinvite/qryptinvite_test.go new file mode 100644 index 0000000..9348549 --- /dev/null +++ b/internal/qryptinvite/qryptinvite_test.go @@ -0,0 +1,214 @@ +package qryptinvite + +import ( + "crypto/ed25519" + "encoding/base64" + "encoding/json" + "strings" + "testing" + "time" +) + +// verifyAsQrypt independently checks a token the way the qrypt.chat backend +// would: split into 3 segments, require segment[0] == "qci1", verify the +// Ed25519 signature over "qci1."+payloadSeg with the issuer's public key, and +// decode the payload. It deliberately does NOT reuse Mint's internals. +func verifyAsQrypt(t *testing.T, token string, pub ed25519.PublicKey) Payload { + t.Helper() + parts := strings.Split(token, ".") + if len(parts) != 3 { + t.Fatalf("token has %d segments, want 3", len(parts)) + } + if parts[0] != "qci1" { + t.Fatalf("segment[0] = %q, want qci1", parts[0]) + } + signingInput := parts[0] + "." + parts[1] + sig, err := base64.RawURLEncoding.DecodeString(parts[2]) + if err != nil { + t.Fatalf("decode sig: %v", err) + } + if !ed25519.Verify(pub, []byte(signingInput), sig) { + t.Fatal("signature did not verify") + } + pj, err := base64.RawURLEncoding.DecodeString(parts[1]) + if err != nil { + t.Fatalf("decode payload: %v", err) + } + var p Payload + if err := json.Unmarshal(pj, &p); err != nil { + t.Fatalf("unmarshal payload: %v", err) + } + return p +} + +func TestMintAndVerify(t *testing.T) { + seedB64, pubB64, err := GenerateIssuerKey() + if err != nil { + t.Fatal(err) + } + priv, err := ParsePrivateKey(seedB64) + if err != nil { + t.Fatalf("ParsePrivateKey(seed): %v", err) + } + pubRaw, err := base64.StdEncoding.DecodeString(pubB64) + if err != nil { + t.Fatal(err) + } + pub := ed25519.PublicKey(pubRaw) + + before := time.Now() + token, jti, err := Mint("agentbbs", priv, 168*time.Hour) + if err != nil { + t.Fatalf("Mint: %v", err) + } + + p := verifyAsQrypt(t, token, pub) + + if p.Iss != "agentbbs" { + t.Errorf("iss = %q, want agentbbs", p.Iss) + } + if p.Tier != "anonymous" { + t.Errorf("tier = %q, want anonymous", p.Tier) + } + if p.Uses != 1 { + t.Errorf("uses = %d, want 1", p.Uses) + } + if p.JTI != jti { + t.Errorf("payload jti %q != returned jti %q", p.JTI, jti) + } + if len(p.JTI) != 32 { + t.Errorf("jti len = %d, want 32 hex chars", len(p.JTI)) + } + if p.Exp <= time.Now().Unix() { + t.Errorf("exp %d is not in the future", p.Exp) + } + if p.Iat < before.Unix()-1 || p.Iat > time.Now().Unix()+1 { + t.Errorf("iat %d outside the mint window", p.Iat) + } + // exp == iat + ttl + if got, want := p.Exp-p.Iat, int64((168 * time.Hour).Seconds()); got != want { + t.Errorf("exp-iat = %d, want %d", got, want) + } +} + +func TestJTIUnique(t *testing.T) { + seedB64, _, err := GenerateIssuerKey() + if err != nil { + t.Fatal(err) + } + priv, err := ParsePrivateKey(seedB64) + if err != nil { + t.Fatal(err) + } + seen := map[string]bool{} + for i := 0; i < 100; i++ { + _, jti, err := Mint("agentbbs", priv, time.Hour) + if err != nil { + t.Fatal(err) + } + if seen[jti] { + t.Fatalf("duplicate jti %q on iteration %d", jti, i) + } + seen[jti] = true + } +} + +func TestTamperedTokenFails(t *testing.T) { + seedB64, pubB64, err := GenerateIssuerKey() + if err != nil { + t.Fatal(err) + } + priv, _ := ParsePrivateKey(seedB64) + pubRaw, _ := base64.StdEncoding.DecodeString(pubB64) + pub := ed25519.PublicKey(pubRaw) + + token, _, err := Mint("agentbbs", priv, time.Hour) + if err != nil { + t.Fatal(err) + } + parts := strings.Split(token, ".") + + // Tamper with the payload: flip the tier to "verified" and re-encode. The + // signature was made over the original payload, so verification must fail. + pj, _ := base64.RawURLEncoding.DecodeString(parts[1]) + var p Payload + if err := json.Unmarshal(pj, &p); err != nil { + t.Fatal(err) + } + p.Tier = "verified" + p.Uses = 9999 + tj, _ := json.Marshal(p) + tampered := parts[0] + "." + base64.RawURLEncoding.EncodeToString(tj) + "." + parts[2] + + if got := verifySig(tampered, pub); got { + t.Fatal("tampered token verified but should have failed") + } + // The untouched token still verifies, proving the key is right. + if !verifySig(token, pub) { + t.Fatal("original token failed to verify") + } + + // Tampering with the signature segment must also fail. + badSig := parts[0] + "." + parts[1] + "." + flipLastChar(parts[2]) + if verifySig(badSig, pub) { + t.Fatal("token with corrupted signature verified but should have failed") + } +} + +// verifySig is a minimal boolean form of the qrypt verify path. +func verifySig(token string, pub ed25519.PublicKey) bool { + parts := strings.Split(token, ".") + if len(parts) != 3 || parts[0] != "qci1" { + return false + } + sig, err := base64.RawURLEncoding.DecodeString(parts[2]) + if err != nil { + return false + } + return ed25519.Verify(pub, []byte(parts[0]+"."+parts[1]), sig) +} + +func flipLastChar(s string) string { + if s == "" { + return s + } + b := []byte(s) + last := b[len(b)-1] + if last == 'A' { + b[len(b)-1] = 'B' + } else { + b[len(b)-1] = 'A' + } + return string(b) +} + +func TestParsePrivateKeyAcceptsSeedAndFull(t *testing.T) { + _, priv, err := ed25519.GenerateKey(nil) + if err != nil { + t.Fatal(err) + } + seedB64 := base64.StdEncoding.EncodeToString(priv.Seed()) + fullB64 := base64.StdEncoding.EncodeToString(priv) + + fromSeed, err := ParsePrivateKey(seedB64) + if err != nil { + t.Fatalf("seed: %v", err) + } + fromFull, err := ParsePrivateKey(fullB64) + if err != nil { + t.Fatalf("full: %v", err) + } + if !fromSeed.Equal(fromFull) { + t.Fatal("seed and full-key parses produced different keys") + } + if !fromSeed.Equal(priv) { + t.Fatal("parsed key differs from original") + } + + if _, err := ParsePrivateKey("not-base64-@@@"); err == nil { + t.Error("expected error on garbage input") + } + if _, err := ParsePrivateKey(base64.StdEncoding.EncodeToString([]byte("short"))); err == nil { + t.Error("expected error on wrong-length key") + } +} diff --git a/internal/store/store.go b/internal/store/store.go index b11b776..0e168ef 100644 --- a/internal/store/store.go +++ b/internal/store/store.go @@ -152,6 +152,15 @@ type Store interface { // UserByToken resolves an API token to its account name. UserByToken(token string) (string, bool, error) + // qrypt.chat anonymous-invite issuance (docs/qrypt-invites.md). + + // QryptInviteCount reports how many qrypt.chat invites username has issued. + QryptInviteCount(username string) (int, error) + // RecordQryptInvite records one issued invite (its jti, for audit and as + // the per-member quota counter) against username. It returns + // ErrQuotaExceeded if the member is already at or above quota. + RecordQryptInvite(username, jti string, quota int) error + Close() error } @@ -226,6 +235,9 @@ var ErrKeyMismatch = errors.New("username registered with a different key") // ErrDomainTaken means a domain is already mapped to a different member. var ErrDomainTaken = errors.New("domain already mapped to another account") +// ErrQuotaExceeded means a member has hit their qrypt.chat invite quota. +var ErrQuotaExceeded = errors.New("qrypt invite quota exceeded") + type sqliteStore struct{ db *sql.DB } // Open opens (and migrates) the SQLite store at path. @@ -381,6 +393,12 @@ CREATE TABLE IF NOT EXISTS api_tokens ( created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')) ); CREATE INDEX IF NOT EXISTS idx_api_tokens_user ON api_tokens(username); +CREATE TABLE IF NOT EXISTS qrypt_invites ( + jti TEXT PRIMARY KEY, + username TEXT NOT NULL, + created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')) +); +CREATE INDEX IF NOT EXISTS idx_qrypt_invites_user ON qrypt_invites(username); ` func (s *sqliteStore) EnsureUser(name, kind, fp string) (User, error) { @@ -807,4 +825,36 @@ func (s *sqliteStore) SetPluginDisabled(id string, disabled bool) error { return err } +func (s *sqliteStore) QryptInviteCount(username string) (int, error) { + var n int + err := s.db.QueryRow(`SELECT COUNT(*) FROM qrypt_invites WHERE username = ?`, username).Scan(&n) + if err != nil { + return 0, err + } + return n, nil +} + +// RecordQryptInvite atomically enforces the per-member quota and records the +// invite's jti. The count check and the insert run in one transaction so two +// concurrent issuances can't both slip past the cap. +func (s *sqliteStore) RecordQryptInvite(username, jti string, quota int) error { + tx, err := s.db.Begin() + if err != nil { + return err + } + defer func() { _ = tx.Rollback() }() + + var n int + if err := tx.QueryRow(`SELECT COUNT(*) FROM qrypt_invites WHERE username = ?`, username).Scan(&n); err != nil { + return err + } + if quota > 0 && n >= quota { + return ErrQuotaExceeded + } + if _, err := tx.Exec(`INSERT INTO qrypt_invites (jti, username) VALUES (?,?)`, jti, username); err != nil { + return err + } + return tx.Commit() +} + func (s *sqliteStore) Close() error { return s.db.Close() } diff --git a/internal/store/store_qrypt_test.go b/internal/store/store_qrypt_test.go new file mode 100644 index 0000000..31acca3 --- /dev/null +++ b/internal/store/store_qrypt_test.go @@ -0,0 +1,52 @@ +package store + +import ( + "errors" + "path/filepath" + "testing" +) + +func TestQryptInviteQuota(t *testing.T) { + st, err := Open(filepath.Join(t.TempDir(), "t.db")) + if err != nil { + t.Fatalf("open: %v", err) + } + defer st.Close() + + const quota = 3 + + if n, err := st.QryptInviteCount("alice"); err != nil || n != 0 { + t.Fatalf("initial count = %d, %v; want 0, nil", n, err) + } + + for i := 0; i < quota; i++ { + jti := "jti-alice-" + string(rune('a'+i)) + if err := st.RecordQryptInvite("alice", jti, quota); err != nil { + t.Fatalf("record %d: %v", i, err) + } + } + if n, err := st.QryptInviteCount("alice"); err != nil || n != quota { + t.Fatalf("count after fill = %d, %v; want %d", n, err, quota) + } + + // One over the cap must be rejected with ErrQuotaExceeded and not stored. + if err := st.RecordQryptInvite("alice", "jti-over", quota); !errors.Is(err, ErrQuotaExceeded) { + t.Fatalf("over-quota err = %v; want ErrQuotaExceeded", err) + } + if n, _ := st.QryptInviteCount("alice"); n != quota { + t.Fatalf("count after rejected insert = %d; want %d", n, quota) + } + + // Quotas are per-member: bob is unaffected. + if err := st.RecordQryptInvite("bob", "jti-bob", quota); err != nil { + t.Fatalf("bob record: %v", err) + } + if n, _ := st.QryptInviteCount("bob"); n != 1 { + t.Fatalf("bob count = %d; want 1", n) + } + + // quota <= 0 means unlimited. + if err := st.RecordQryptInvite("carol", "jti-carol-1", 0); err != nil { + t.Fatalf("unlimited record: %v", err) + } +} diff --git a/plugins/qryptinvite/qryptinvite.go b/plugins/qryptinvite/qryptinvite.go new file mode 100644 index 0000000..2b35680 --- /dev/null +++ b/plugins/qryptinvite/qryptinvite.go @@ -0,0 +1,111 @@ +// Package qryptinvite is the hub plugin that lets an authenticated member mint +// a single-use qrypt.chat anonymous invite. AgentBBS is the trusted issuer: the +// plugin signs a token with the operator's Ed25519 key, records it against the +// member's per-account quota, and prints the token + redeem URL. The separate +// qrypt.chat app verifies the signature and burns the jti on redeem. +// +// See internal/qryptinvite for the token format and docs/qrypt-invites.md. +package qryptinvite + +import ( + "errors" + "strconv" + + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/lipgloss" + + "github.com/profullstack/agentbbs/internal/auth" + "github.com/profullstack/agentbbs/internal/plugin" + qi "github.com/profullstack/agentbbs/internal/qryptinvite" + "github.com/profullstack/agentbbs/internal/store" +) + +// Plugin is the hub registration. It admits members only (guests have no +// account to quota against). +type Plugin struct{} + +func (Plugin) ID() string { return "qrypt-invite" } +func (Plugin) Title() string { return "qrypt.chat invite" } +func (Plugin) Description() string { return "Mint an anonymous qrypt.chat signup invite" } +func (Plugin) RequiresAuth() bool { return true } + +func (Plugin) New(user auth.User, ctx plugin.Context) tea.Model { + cfg := qi.ConfigFromEnv() + m := model{user: user, store: ctx.Store, cfg: cfg} + m.issue() // do the work once up front; the view just reports the result + return m +} + +type model struct { + user auth.User + store store.Store + cfg qi.Config + body string // rendered result, ready to display +} + +// issue runs the full flow: check quota, mint, record, build the output. +func (m *model) issue() { + if m.user.Kind == auth.Guest || m.user.Name == "" { + m.body = errStyle.Render("Sign in with your SSH key to mint an invite.") + return + } + priv, err := m.cfg.PrivateKey() + if err != nil { + m.body = errStyle.Render("Invites are not configured on this host yet.\n") + + dStyle.Render(" ("+err.Error()+")") + return + } + used, err := m.store.QryptInviteCount(m.user.Name) + if err != nil { + m.body = errStyle.Render("Couldn't read your invite count: " + err.Error()) + return + } + if m.cfg.Quota > 0 && used >= m.cfg.Quota { + m.body = errStyle.Render("You've used all your invites ") + + dStyle.Render("("+strconv.Itoa(used)+"/"+strconv.Itoa(m.cfg.Quota)+"). Ask an operator for more.") + return + } + + token, jti, err := qi.Mint(m.cfg.IssuerID, priv, m.cfg.TTL) + if err != nil { + m.body = errStyle.Render("Mint failed: " + err.Error()) + return + } + if err := m.store.RecordQryptInvite(m.user.Name, jti, m.cfg.Quota); err != nil { + if errors.Is(err, store.ErrQuotaExceeded) { + m.body = errStyle.Render("You've used all your invites. Ask an operator for more.") + return + } + m.body = errStyle.Render("Couldn't record the invite: " + err.Error()) + return + } + + remaining := m.cfg.Quota - (used + 1) + m.body = hStyle.Render("Your qrypt.chat anonymous invite") + "\n\n" + + " Redeem at:\n" + + urlStyle.Render(" "+m.cfg.RedeemURLFor(token)) + "\n\n" + + dStyle.Render(" Token (same thing, if you'd rather paste it):") + "\n" + + " " + token + "\n\n" + + dStyle.Render(" Single-use · expires in "+m.cfg.TTL.String()+" · invites left: "+strconv.Itoa(max(remaining, 0))) +} + +func (m model) Init() tea.Cmd { return nil } + +func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { + if _, ok := msg.(tea.KeyMsg); ok { + return m, plugin.Exit + } + return m, nil +} + +func (m model) View() string { + return lipgloss.NewStyle().Padding(1, 2).Render( + m.body + "\n\n" + dStyle.Render("press any key to return")) +} + +var ( + hStyle = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#4ade80")) + dStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("241")) + errStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("203")) + urlStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("#60a5fa")) +) diff --git a/setup.sh b/setup.sh index db5a01a..ec43b0e 100755 --- a/setup.sh +++ b/setup.sh @@ -264,6 +264,16 @@ AGENTBBS_HTTP_ADDR=${HTTP_ADDR} # Agent chat backend (agent@), stdin->stdout, e.g. "claude -p": # AGENTBBS_AGENT_CMD= + +# qrypt.chat anonymous-invite issuer (docs/qrypt-invites.md). Members mint a +# signed single-use token here that qrypt.chat redeems into an anon account. +# Run \`agentbbs qrypt-issuer-keygen\` once: paste the seed below, register the +# public key in qrypt.chat's invite_issuers row. Without the key, minting is off. +# AGENTBBS_QRYPT_ISSUER_KEY= +# AGENTBBS_QRYPT_ISSUER_ID=agentbbs +# AGENTBBS_QRYPT_INVITE_TTL=168h +# AGENTBBS_QRYPT_REDEEM_URL=https://qrypt.chat/anon?invite= +# AGENTBBS_QRYPT_INVITE_QUOTA=5 ENV chmod 0640 "$ENV_DIR/agentbbs.env" fi