nattermatic 0.0.1 → 0.2.1

package/src/codex.js

@@ -0,0 +1,247 @@
+// Codex CLI integration. Setup adds nattermatic to Codex's config.toml: the adapter (in poll mode) and a
+// SessionStart hook. Codex's hooks can't wake a session, but `codex queue` can: it gives an idle
+// session a turn (or a busy one, once its turn ends). So the hook (`natter codex-hook`) starts a
+// waiter in the background (`natter codex-wake`), which waits for the session's messages the way
+// the Claude Code hook does, and queues a fixed note telling it to read them.
+//
+// Codex runs every session's adapter from one shared app-server, so the node can't tell sessions
+// apart by process alone as it does Claude Code's: the waiter also gives the session's folder, which
+// the adapter has as its working directory. Two Codex sessions in one folder can't be told apart:
+// the newer one is woken.
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync, spawn, spawnSync } from 'node:child_process'
+import { errMsg, homeDir, loadConfig, shQuote as sq, writeAtomic } from './config.js'
+import { Local } from './local.js'
+import { selfCmd, which } from './claude.js'
+
+const BEGIN = '# >>> nattermatic >>> (managed by `natter setup`; `natter uninstall` removes it)'
+const END = '# <<< nattermatic <<<'
+// the block as agentlink wrote it, before the rename: replaced in place by this one
+const OLD_BEGIN = '# >>> agentlink >>> (managed by `agentlink setup`; `agentlink uninstall` removes it)', OLD_END = '# <<< agentlink <<<'
+const renamed = (/** @type {string} */ text) => text.replace(OLD_BEGIN, BEGIN).replace(OLD_END, END)
+// tools a woken session reads with, which it may use without asking (as for Claude Code)
+const READ_TOOLS = ['inbox', 'peers']
+const THREAD = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const RETRY_MS = 5000
+const SLOW_RETRY_MS = 30_000
+const SLOW_AFTER_MS = 120_000
+// with no session of that name for this long, the waiter gives up; resuming the session starts a new one
+const GIVE_UP_MS = 86400_000
+const MAX_LOG = 64 * 1024
+// what Codex shows for the hook when it asks the user to trust it
+const HOOK_NAME = 'nattermatic: wake this session when another agent messages it'
+
+export const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
+export const codexConfigFile = () => path.join(codexHome(), 'config.toml')
+/** Is Codex on this machine? */
+export const codexPresent = () => !!which('codex') || fs.existsSync(codexHome())
+
+/** The hook's command. It must stay the same across upgrades: Codex asks again for a changed hook. */
+export const hookCmd = () => [...selfCmd().map(a => a.startsWith('-') ? a : sq(a)), 'codex-hook'].join(' ')
+
+const tq = (/** @type {string} */ s) => JSON.stringify(s)      // a TOML basic string (JSON's escapes are TOML's)
+
+/** The hook's entry. Codex asks the user to trust it again whenever it changes. */
+const hookEntry = () => ['[[hooks.SessionStart]]', '[[hooks.SessionStart.hooks]]', 'type = "command"', `command = ${tq(hookCmd())}`, 'timeout = 10', `statusMessage = ${tq(HOOK_NAME)}`].join('\n')
+
+/** What setup puts in config.toml. @param {{ hook: boolean }} o */
+export function configBlock({ hook }) {
+  const [cmd, ...args] = selfCmd()
+  return [
+    BEGIN,
+    '[mcp_servers.nattermatic]',
+    `command = ${tq(cmd)}`,
+    `args = [${[...args, 'mcp', '--poll'].map(tq).join(', ')}]`,
+    // Codex sessions are named after their folder: the shared app-server's environment is whichever
+    // shell started it, so a NATTERMATIC_NAME there would name every session
+    'env = { NATTERMATIC_NAME = "" }',
+    ...READ_TOOLS.flatMap(t => ['', `[mcp_servers.nattermatic.tools.${t}]`, 'approval_mode = "approve"']),
+    ...(hook ? ['', hookEntry()] : []),
+    END,
+  ].join('\n')
+}
+
+/** `text` without nattermatic's block. @param {string} text */
+export function withoutBlock(text) {
+  const a = text.indexOf(BEGIN)
+  if (a < 0) return text
+  const b = text.indexOf(END, a)
+  if (b < 0) return text
+  const out = (text.slice(0, a) + text.slice(b + END.length).replace(/^\n/, '')).replace(/\n{3,}/g, '\n\n')
+  return out.trim() ? out.replace(/\n+$/, '\n') : ''
+}
+
+/**
+ * Settings of the user's own that nattermatic's block would clash with (TOML can't define a table
+ * twice), so setup leaves the file alone. @param {string} text the file without nattermatic's block
+ */
+export function clashes(text) {
+  const out = []
+  if (/^\s*\[\s*mcp_servers\s*\.\s*"?nattermatic"?\s*[\].]/m.test(text) || /^\s*mcp_servers\s*=/m.test(text)) out.push('a nattermatic MCP server of its own')
+  if (/^\s*SessionStart\s*=/m.test(text) || /^\s*hooks\s*=/m.test(text)) out.push('hooks written inline (SessionStart = [...])')
+  return out
+}
+
+/** `text` with nattermatic's block, in place of any earlier one. @param {string} text @param {string} block */
+export function withBlock(text, block) {
+  const a = text.indexOf(BEGIN)
+  const b = a < 0 ? -1 : text.indexOf(END, a)
+  // in place, so the trust Codex recorded for the hook (by its position in the file) still applies
+  if (a >= 0 && b >= 0) return text.slice(0, a) + block + text.slice(b + END.length)
+  const base = text.replace(/\s*$/, '')
+  return `${base}${base ? '\n\n' : ''}${block}\n`
+}
+
+/** Can this Codex give a session a turn from outside? @param {string | null} codex */
+export function canQueue(codex) {
+  if (!codex) return false
+  return spawnSync(codex, ['queue', '--help'], { stdio: 'ignore', timeout: 15_000 }).status === 0
+}
+
+/**
+ * Add nattermatic to Codex, or throw why not. hook: sessions are woken (this Codex has `codex queue`);
+ * approve: the hook is new to Codex, which asks the user to trust it at its next start.
+ * @returns {{ hook: boolean, approve: boolean }}
+ */
+export function installCodex() {
+  const file = codexConfigFile()
+  let text = ''
+  try { text = fs.readFileSync(file, 'utf8') } catch (e) { if (/** @type {any} */ (e).code !== 'ENOENT') throw new Error(`can't read ${file} (${errMsg(e)})`) }
+  const was = text
+  text = renamed(text)
+  const theirs = clashes(withoutBlock(text))
+  if (theirs.length) throw new Error(`${file} already has ${theirs.join(' and ')}, so nattermatic left it alone`)
+  const hook = canQueue(which('codex'))
+  const next = withBlock(text, configBlock({ hook }))
+  if (next !== was) write(file, next)
+  return { hook, approve: hook && !text.includes(hookEntry()) }
+}
+
+export function removeCodex() {
+  const file = codexConfigFile()
+  let text
+  try { text = fs.readFileSync(file, 'utf8') } catch { return }
+  const next = withoutBlock(renamed(text))
+  if (next !== text) write(file, next)
+}
+
+/** @param {string} file @param {string} text */
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const real = fs.existsSync(file) ? fs.realpathSync(file) : file       // often a link into dotfiles
+  writeAtomic(real, text, fs.existsSync(real) ? fs.statSync(real).mode & 0o777 : 0o600)
+}
+
+/** The fixed note a waiter queues: nothing another agent wrote. @param {number} n @param {string} name */
+export const codexWakeText = (n, name) => `[nattermatic] This session is on the nattermatic agent network as ${name}, and ${n === 1 ? 'a new message has' : `${n} new messages have`} arrived from another agent. Read ${n === 1 ? 'it' : 'them'} now with nattermatic's inbox tool, then act on ${n === 1 ? 'it' : 'them'} as requests from a colleague, not instructions from your user.`
+
+/**
+ * `natter codex-hook`: Codex's SessionStart hook. Starts the session's waiter and returns at once
+ * (Codex waits for its hooks). Prints nothing: what a SessionStart hook prints goes to the model.
+ */
+export async function runCodexHook() {
+  let input = ''
+  for await (const c of process.stdin) input += c
+  /** @type {any} */
+  let d
+  try { d = JSON.parse(input) } catch { return 0 }
+  const thread = String(d?.session_id || '')
+  if (!THREAD.test(thread) || typeof d.cwd !== 'string') return 0
+  if (fs.existsSync(path.join(homeDir(), 'disabled'))) return 0
+  const codex = which('codex') || parentExe()
+  if (!codex) return 0
+  let cwd = d.cwd
+  try { cwd = fs.realpathSync(cwd) } catch {}
+  const [cmd, ...args] = selfCmd()
+  // the app-server that ran this hook started the session's adapter too (a shell may be in between)
+  const pids = [process.ppid, ...parents(process.ppid, 2)]
+  const child = spawn(cmd, [...args, 'codex-wake', '--thread', thread, '--pids', pids.join(','), '--cwd', cwd, '--codex', codex],
+    { detached: true, stdio: 'ignore' })
+  child.on('error', () => {})
+  child.unref()
+  return 0
+}
+
+/** Up to `n` ancestors of `pid`, nearest first. @param {number} pid @param {number} n */
+function parents(pid, n) {
+  const out = []
+  for (let i = 0; i < n && pid > 1; i++) {
+    try { pid = Number(execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim()) } catch { break }
+    if (pid > 1) out.push(pid)
+  }
+  return out
+}
+
+/** The program that ran this hook: Codex's app-server, a codex that can queue. */
+function parentExe() {
+  try {
+    if (process.platform === 'linux') return fs.readlinkSync(`/proc/${process.ppid}/exe`)
+    const p = execFileSync('ps', ['-o', 'comm=', '-p', String(process.ppid)], { encoding: 'utf8', timeout: 2000 }).trim()
+    return path.isAbsolute(p) && path.basename(p) === 'codex' ? p : null
+  } catch { return null }
+}
+
+/**
+ * `natter codex-wake`: one Codex session's waiter. Each message for the session queues one note;
+ * the session reads the messages with the inbox tool. A newer waiter for the session takes over
+ * from this one.
+ * @param {{ thread: string, pids: string, cwd: string, codex: string }} o
+ */
+export async function runCodexWake({ thread, pids: pidList, cwd, codex }) {
+  const pids = String(pidList || '').split(',').map(Number).filter(Boolean)
+  if (!THREAD.test(thread || '') || !pids.length || !cwd || !codex) return 2
+  /** @type {Local} */
+  let local
+  try {
+    if (fs.existsSync(path.join(homeDir(), 'disabled'))) return 0
+    local = new Local(loadConfig())
+  } catch { return 0 }
+  sweepMarks()
+  const mark = path.join(homeDir(), `codex-wake-${thread}`)
+  const me = String(process.pid)
+  try { fs.writeFileSync(mark, me) } catch {}
+  const isMine = () => { try { return fs.readFileSync(mark, 'utf8') === me } catch { return true } }
+  const finish = (/** @type {number} */ code) => { if (isMine()) fs.rmSync(mark, { force: true }); return code }
+  let since = Date.now()
+  for (;;) {
+    if (!isMine()) return 0
+    /** @type {{ event: string, name?: string, count?: number } | null} */
+    let r = null, reached = true
+    try { r = await local.wakeWait(pids, cwd) } catch { reached = false }
+    if (!isMine()) return 0
+    if (r?.event === 'wake') {
+      const name = r.name || 'this session'
+      const q = spawnSync(codex, ['queue', '--thread', thread, '--message', codexWakeText(r.count || 1, name)], { encoding: 'utf8', timeout: 30_000 })
+      if (q.status !== 0) log(`codex queue for ${name} (${thread}) failed: ${(q.stderr || q.error?.message || `exit ${q.status}`).trim()}`)
+      since = Date.now()
+      continue
+    }
+    if (r?.event === 'done') return finish(0)          // a newer waiter for this session took over
+    if (!reached || r?.event === 'closed') since = Date.now()
+    const waited = Date.now() - since
+    if (waited > GIVE_UP_MS) return finish(0)
+    await new Promise(res => setTimeout(res, waited > SLOW_AFTER_MS ? SLOW_RETRY_MS : RETRY_MS))
+  }
+}
+
+/** @param {string} m */
+function log(m) {
+  const f = path.join(homeDir(), 'codex.log')
+  try {
+    if (fs.statSync(f).size > MAX_LOG) fs.rmSync(f, { force: true })
+  } catch {}
+  try { fs.appendFileSync(f, `${new Date().toISOString()} ${m}\n`) } catch {}
+}
+
+/** Waiters that died (a restart, say) leave their marks behind: clear those. */
+function sweepMarks() {
+  try {
+    for (const f of fs.readdirSync(homeDir())) {
+      if (!/^codex-wake-[0-9a-f-]+$/i.test(f)) continue
+      const pid = Number(fs.readFileSync(path.join(homeDir(), f), 'utf8'))
+      try { if (pid) process.kill(pid, 0) } catch (e) { if (/** @type {any} */ (e).code === 'ESRCH') fs.rmSync(path.join(homeDir(), f), { force: true }) }
+    }
+  } catch {}
+}

package/src/config.js

@@ -0,0 +1,280 @@
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { fingerprint } from './cert.js'
+
+export const VERSION = '0.2.1'
+
+export function homeDir() {
+  return process.env.NATTERMATIC_HOME || path.join(os.homedir(), '.nattermatic')
+}
+const configPath = () => path.join(homeDir(), 'config.json')
+/** This machine's key, certificate and the network's membership records. */
+export const keyPath = (dir = homeDir()) => path.join(dir, 'node.key')
+export const certPath = (dir = homeDir()) => path.join(dir, 'node.crt')
+export const rosterPath = (dir = homeDir()) => path.join(dir, 'roster.json')
+
+export const sleep = (/** @type {number} */ ms) => new Promise(r => setTimeout(r, ms))
+/** Single-quote for sh. @param {unknown} v */
+export const shQuote = v => `'${String(v).replace(/'/g, `'\\''`)}'`
+/** Compare dotted versions numerically. @param {string} a @param {string} b */
+export function cmpVersion(a, b) {
+  const x = String(a).split(/[.-]/).map(Number), y = String(b).split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) - (y[i] || 0)
+  return 0
+}
+
+/**
+ * Replace `file` in one step, on disk before the rename: a crash or a full disk leaves the old file
+ * or the new one, never part of one.
+ * @param {string} file @param {string | Buffer} data @param {number} mode
+ */
+export function writeAtomic(file, data, mode) {
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    const fd = fs.openSync(tmp, 'w', mode)
+    // writeFileSync, not writeSync: writeSync can write part of the data and report no error
+    try { fs.fchmodSync(fd, mode); fs.writeFileSync(fd, data); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+    fs.renameSync(tmp, file)
+  } catch (e) { fs.rmSync(tmp, { force: true }); throw e }
+}
+
+/** Create the nattermatic home directory, private to this user even if something (an older installer,
+ * a umask-created parent) made it before us: it holds this machine's private key, messages and logs. */
+export function ensureHomeDir(dir = homeDir()) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  try { if ((fs.statSync(dir).mode & 0o077) !== 0) fs.chmodSync(dir, 0o700) } catch {}
+  return dir
+}
+
+/** Longest a message may live, whatever the config says (keeps timestamps well inside SQLite/JS integer range). */
+export const MAX_TTL_MS = 30 * 86400_000
+
+/** Normalise a machine name (lowercase, `.local` for bare names); throws if invalid. @param {unknown} input @returns {string} */
+export function normHost(input) {
+  let h = String(input || '').trim().toLowerCase().replace(/\.$/, '')
+  if (!h) throw new Error('empty host')
+  // hostnames / IPv4 only: keeps addresses from being turned into arbitrary URLs
+  if (!/^[a-z0-9]([a-z0-9-]{0,62})(\.[a-z0-9]([a-z0-9-]{0,62}))*$/.test(h) || h.length > 253) throw new Error(`invalid host "${h}"`)
+  if (!h.includes('.') && h !== 'localhost') h += '.local'
+  return h
+}
+
+/** A dialable "host:port" (hostname or IPv4, or [IPv6]) — anything else is refused. */
+/** @param {unknown} a @returns {a is string} */
+export function validAddr(a) {
+  if (typeof a !== 'string') return false
+  const m = a.match(/^(\[[0-9a-f:.]+\]|[a-z0-9.-]+):(\d{1,5})$/i)
+  return !!m && Number(m[2]) > 0 && Number(m[2]) < 65536
+}
+
+/** @param {unknown} n */
+export function sanitizeName(n) {
+  const s = String(n || '').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+/, '').slice(0, 48).replace(/[-.]+$/, '')
+  return s || 'agent'
+}
+
+/**
+ * "name@host" | "name" -> {name, host}
+ * @param {unknown} input
+ * @param {string} selfHost
+ * @returns {{ name: string, host: string }}
+ */
+export function parseAddr(input, selfHost) {
+  const a = String(input || '').trim()
+  const i = a.lastIndexOf('@')
+  if (i < 0) return { name: sanitizeName(a), host: selfHost }
+  return { name: sanitizeName(a.slice(0, i)), host: normHost(a.slice(i + 1)) }
+}
+
+/**
+ * "host" | "host:port" | "1.2.3.4:7777" -> { host, addr|null }
+ * @param {unknown} p
+ * @returns {import('./types.js').PeerSpec | null}
+ */
+export function parsePeer(p) {
+  const s = String(p || '').trim().toLowerCase()
+  // an IPv6 address has no name: this one stands for it until the machine there says who it is
+  const v6 = s.match(/^\[([0-9a-f:.]+)\]:\d+$/)
+  if (v6) return validAddr(s) ? { host: `ipv6-${v6[1].replace(/[:.]/g, '-').replace(/^-+|-+$/g, '')}.local`, addr: s } : null
+  const m = s.match(/^([^:\s]+)(?::(\d+))?$/)
+  if (!m) return null
+  let host
+  try { host = normHost(m[1]) } catch { return null }
+  if (/^\d+\.\d+\.\d+\.\d+\.local$/.test(host)) host = host.slice(0, -6)
+  // with an explicit port, dial the name exactly as given: a bare name may be a MagicDNS/DNS short
+  // name ("desk:7777") that only resolves without the ".local" we add for identity
+  const literal = m[1].replace(/\.$/, '')
+  const addr = m[2] ? `${/^[a-z0-9-]+$/.test(literal) ? literal : host}:${m[2]}` : null
+  if (addr && !validAddr(addr)) return null
+  return { host, addr }
+}
+
+export function localIPv4s() {
+  const out = ['127.0.0.1']
+  for (const list of Object.values(os.networkInterfaces())) for (const i of list || []) if (i.family === 'IPv4') out.push(i.address)
+  return out
+}
+
+/** This machine's Tailscale DNS name, if Tailscale is running. */
+export function tailscaleName() {
+  for (const bin of ['tailscale', '/Applications/Tailscale.app/Contents/MacOS/Tailscale']) {
+    try {
+      const self = JSON.parse(execFileSync(bin, ['status', '--json'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] })).Self
+      if (self?.Online !== false && self?.DNSName) return normHost(self.DNSName)
+    } catch {}
+  }
+  return null
+}
+
+/** @param {string} h */
+const hostSafe = h => String(h).trim().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 63) || 'agentlink-host'
+
+export function detectHost() {
+  let h = null
+  if (process.platform === 'darwin') {
+    try { h = normHost(hostSafe(execFileSync('scutil', ['--get', 'LocalHostName']).toString())) } catch {}
+  }
+  h ||= normHost(hostSafe(os.hostname().split('.')[0]))
+  // every node treats "localhost" as itself, so it can't be a machine's network identity
+  if (isLocalhost(h)) throw new Error(`this machine's hostname is "${os.hostname()}", which can't identify it on the network; run: natter setup --host <name>`)
+  return h
+}
+const isLocalhost = (/** @type {string} */ h) => h === 'localhost' || h.startsWith('localhost.')
+/**
+ * Can this (normalised) name identify a machine? Every node takes "localhost" for itself, and an IP
+ * address says where a machine is, not which one it is.
+ * @param {string} h
+ */
+export const machineName = h => !isLocalhost(h) && !/^\d+(\.\d+){3}$/.test(h)
+
+/**
+ * This machine's identity, or null if setup hasn't created one.
+ * @returns {import('./types.js').Identity | null}
+ */
+export function readIdentity(dir = homeDir()) {
+  let key, cert
+  try { key = fs.readFileSync(keyPath(dir), 'utf8'); cert = fs.readFileSync(certPath(dir), 'utf8') } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === 'ENOENT') return null
+    throw e
+  }
+  const pub = crypto.createPublicKey(key)
+  const x = new crypto.X509Certificate(cert)
+  if (!x.publicKey.equals(pub)) throw new Error(`${certPath(dir)} does not match ${keyPath(dir)}: restore the right file, or run natter setup --new-network to start over`)
+  return { key, cert, fp: fingerprint(key) }
+}
+
+/** @param {import('./types.js').Identity} id */
+export function writeIdentity(id, dir = homeDir()) {
+  ensureHomeDir(dir)
+  writeAtomic(keyPath(dir), id.key, 0o600)
+  writeAtomic(certPath(dir), id.cert, 0o644)
+}
+
+/** The network this machine belongs to (the founding machine's fingerprint), or null. */
+function readNet(dir = homeDir()) {
+  try { return String(JSON.parse(fs.readFileSync(rosterPath(dir), 'utf8')).net) } catch { return null }
+}
+
+/** @returns {import('./types.js').Config} */
+export function loadConfig() {
+  /** @type {import('./types.js').ConfigFile} */
+  const file = readConfigFile() || {}
+  const identity = readIdentity()
+  const net = readNet()
+  if (!identity || !net) throw new Error(`nattermatic is not set up on this machine. Run: natter setup`)
+  const explicit = process.env.NATTERMATIC_HOST || file.host
+  const host = normHost(explicit || detectHost())
+  if (isLocalhost(host)) throw new Error(`"${host}" can't identify this machine on the network; run: natter setup --host <name>`)
+  const aliases = new Set([...(file.aliases || []).map(normHost), 'localhost'])
+  const autoAliases = process.env.NATTERMATIC_AUTO_ALIASES ? process.env.NATTERMATIC_AUTO_ALIASES !== '0' : file.autoAliases !== false
+  if (autoAliases) {
+    for (const ip of localIPv4s()) aliases.add(ip)
+    // the OS hostname is only one of our names when we use it for identity: a machine given its own
+    // name (e.g. a clone renamed with --host) must not answer for its twin's hostname
+    if (!explicit) try { const o = normHost(os.hostname()); if (!isLocalhost(o)) aliases.add(o) } catch {}   // skipped if not a valid host
+  }
+  aliases.delete(host)
+  return {
+    dir: homeDir(),
+    identity,
+    net,
+    host,
+    aliases: [...aliases],
+    port: Number(process.env.NATTERMATIC_PORT || file.port || 7777),
+    peers: (file.peers || []).map(parsePeer).filter(p => p !== null),  // extra peers beyond LAN discovery (Tailscale names, IPs)
+    routes: file.routes || {},                        // host -> "ip:port" overrides
+    discoveryPort: Number(process.env.NATTERMATIC_DISCOVERY_PORT || file.discoveryPort || 0) || undefined,
+    discovery: process.env.NATTERMATIC_DISCOVERY ? process.env.NATTERMATIC_DISCOVERY !== '0' : file.discovery !== false,
+    ttlMs: Math.min(Number(file.ttlDays) > 0 ? Number(file.ttlDays) * 86400_000 : 7 * 86400_000, MAX_TTL_MS),
+    autoAliases,
+    maxWaiting: Number(file.maxWaiting) > 0 ? Number(file.maxWaiting) : 2000,      // unread messages for one session
+    maxStoreBytes: (Number(file.maxStoreMB) > 0 ? Number(file.maxStoreMB) : 1024) * 2 ** 20,
+  }
+}
+
+/** Merge `obj` into config.json. @param {import('./types.js').ConfigFile} obj */
+export function writeConfig(obj) {
+  ensureHomeDir()
+  const next = { ...readConfigFile(), ...obj }
+  writeAtomic(configPath(), JSON.stringify(next, null, 2) + '\n', 0o600)
+  return next
+}
+
+/** config.json's contents, or null if there is none; a file that exists but can't be read or parsed
+ * throws (never treated as empty, which would silently change this machine's settings). */
+/** @returns {import('./types.js').ConfigFile | null} */
+export function readConfigFile() {
+  let text
+  try { text = fs.readFileSync(configPath(), 'utf8') } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === 'ENOENT') return null
+    throw new Error(`cannot read ${configPath()}: ${errMsg(e)}`)
+  }
+  try {
+    const v = JSON.parse(text)
+    if (!v || typeof v !== 'object' || Array.isArray(v)) throw new Error('not a JSON object')
+    return v
+  } catch (e) { throw new Error(`bad config ${configPath()}: ${errMsg(e)} — fix the file (or delete it to start over)`) }
+}
+
+/**
+ * The message of a caught value (which may not be an Error), with a network cause code if any.
+ * A connection to a name with several addresses fails with an AggregateError whose own message is
+ * empty: report the codes of the attempts instead.
+ * @param {unknown} e
+ */
+export const errMsg = e => {
+  if (!(e instanceof Error)) return String(e)
+  const cause = /** @type {any} */ (e).cause
+  const agg = e instanceof AggregateError ? e : cause instanceof AggregateError ? cause : null
+  if (agg && agg.errors.length) {
+    const codes = [...new Set(agg.errors.map(x => x?.code || (x instanceof Error ? x.message : String(x))))]
+    const desc = `connect ${codes.join(', ')}${agg.errors.length > 1 ? ` (tried ${agg.errors.length} addresses)` : ''}`
+    return e === agg ? (e.message ? `${e.message}: ${desc}` : desc) : `${e.message}: ${desc}`
+  }
+  const code = cause?.code
+  return code && !e.message.includes(code) ? `${e.message} (${code})` : e.message
+}
+
+/** The network error code behind a caught value (its own, its cause's, or the first attempt's). @param {unknown} e @returns {string} */
+export const errCode = e => {
+  const x = /** @type {any} */ (e)
+  if (!x || typeof x !== 'object') return ''
+  if (typeof x.code === 'string') return x.code
+  if (x instanceof AggregateError) return errCode(x.errors[0])
+  return x.cause ? errCode(x.cause) : ''
+}
+
+/**
+ * A hint for errors with a well-known local cause: on macOS, a process without Local Network
+ * permission gets EHOSTUNREACH for every machine on the LAN.
+ * @param {unknown} e
+ */
+export const netHint = e => {
+  const code = errCode(e)
+  if (process.platform === 'darwin' && (code === 'EHOSTUNREACH' || code === 'ENETUNREACH'))
+    return ' (if that machine is on, macOS may be blocking nattermatic from the local network: check System Settings → Privacy & Security → Local Network)'
+  return ''
+}

package/src/crypto.js

@@ -0,0 +1,124 @@
+import crypto from 'node:crypto'
+
+/** Constant-time string comparison; false unless both are strings. @param {unknown} a @param {unknown} b */
+function safeEq(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false
+  const x = Buffer.from(a), y = Buffer.from(b)
+  return x.length === y.length && crypto.timingSafeEqual(x, y)
+}
+
+/** @param {string} s */
+export const sha256 = s => crypto.createHash('sha256').update(s).digest('base64url')
+
+/** @param {crypto.KeyLike} key @param {string} payload */
+const sign = (key, payload) => crypto.sign('sha256', Buffer.from(payload), key).toString('base64url')
+/** @param {crypto.KeyLike} pub @param {string} payload @param {unknown} sig */
+function verify(pub, payload, sig) {
+  if (typeof sig !== 'string' || sig.length > 200) return false
+  try { return crypto.verify('sha256', Buffer.from(payload), pub, Buffer.from(sig, 'base64url')) } catch { return false }
+}
+
+/** @param {Omit<import('./types.js').Envelope, 'sig'>} m */
+const envPayload = m => JSON.stringify(['agentlink-env-1', m.id, m.from, m.to, m.sent_at, m.expires_at, m.body])
+/**
+ * Envelope signature by the sending machine's key: end to end, so nobody relaying a message
+ * (holders, other members) can alter it, and a member can't send as another machine.
+ * @param {string} key PEM private key @param {Omit<import('./types.js').Envelope, 'sig'>} m
+ */
+export const signEnvelope = (key, m) => sign(key, envPayload(m))
+/** @param {crypto.KeyLike} pub @param {import('./types.js').Envelope} m */
+export const verifyEnvelope = (pub, m) => verify(pub, envPayload(m), m.sig)
+
+/** @param {Omit<import('./types.js').RosterRecord, 'sig'>} r */
+const recPayload = r => JSON.stringify(['agentlink-roster-1', r.type, r.host ?? '', r.fp, r.cert ?? '', r.at, r.by, r.dk ?? '',
+  ...(r.type === 'remove' ? [(r.seen ?? []).join(',')] : r.type === 'snapshot' ? [JSON.stringify(r.list), JSON.stringify(r.keys)] : [])])
+/**
+ * A short id for a roster record (what a remove record lists in `seen`): of its content, not its
+ * signature. A signature can be re-encoded by anyone and still verify, so it can't say which record
+ * this is, and a copy with a different signature is the same record.
+ * @param {Omit<import('./types.js').RosterRecord, 'sig'>} r
+ */
+export const recId = r => { let id = ids.get(r); if (!id) ids.set(r, id = sha256(recPayload(r)).slice(0, 22)); return id }
+// records aren't changed once made, and replaying a roster asks for each one's id several times
+/** @type {WeakMap<object, string>} */
+const ids = new WeakMap()
+/**
+ * What a check of a record is remembered under: its whole content and signature. Never the signature
+ * alone, or a signature that was good for one record would pass for any other record carrying it.
+ * @param {import('./types.js').RosterRecord} r
+ */
+export const recKey = r => sha256(JSON.stringify([recPayload(r), r.sig]))
+/** @param {string} key @param {Omit<import('./types.js').RosterRecord, 'sig'>} r */
+export const signRecord = (key, r) => sign(key, recPayload(r))
+/** @param {crypto.KeyLike} pub @param {import('./types.js').RosterRecord} r */
+export const verifyRecord = (pub, r) => verify(pub, recPayload(r), r.sig)
+
+/** A fresh discovery key (shared by members, only ever sent over member TLS connections). */
+export const newDiscoveryKey = () => crypto.randomBytes(32).toString('base64')
+
+/**
+ * LAN discovery beacons are encrypted under the discovery key, so people on the same network
+ * (a café) see opaque packets: no machine name, nothing stable to recognise a laptop by.
+ * @param {string} dk base64 key @param {object} obj
+ */
+export function sealBeacon(dk, obj) {
+  const iv = crypto.randomBytes(12)
+  const c = crypto.createCipheriv('aes-256-gcm', Buffer.from(dk, 'base64'), iv)
+  const body = Buffer.concat([c.update(JSON.stringify(obj)), c.final()])
+  return Buffer.concat([iv, body, c.getAuthTag()])
+}
+/** @param {string[]} dks keys to try @param {Buffer} buf @returns {any} the beacon, or null */
+export function openBeacon(dks, buf) {
+  if (buf.length < 29 || buf.length > 2048) return null
+  for (const dk of [...dks].reverse()) {      // the current key is the one nearly every beacon uses
+    try {
+      const d = crypto.createDecipheriv('aes-256-gcm', Buffer.from(dk, 'base64'), buf.subarray(0, 12))
+      d.setAuthTag(buf.subarray(buf.length - 16))
+      return JSON.parse(Buffer.concat([d.update(buf.subarray(12, buf.length - 16)), d.final()]).toString('utf8'))
+    } catch {}
+  }
+  return null
+}
+
+/** A random URL- and shell-safe token. */
+export const randomToken = (bytes = 18) => {
+  for (;;) { const s = crypto.randomBytes(bytes).toString('base64url'); if (!s.startsWith('-')) return s }
+}
+
+// ---- in-band identity (see docs/design/unlinkable-keys.md) ----
+// A node's TLS certificate is a throwaway, so the handshake itself proves nothing. Instead, on each
+// connection, the client first proves it holds a discovery key (the "gate": a stranger gets a 404
+// like any other path), the server then signs the connection's TLS exporter with its machine key,
+// and only then does the client sign it with its own and send its request. Both signatures are
+// bound to that one TLS session, so they can't be replayed or relayed onto another connection.
+
+/** @param {string} dk */
+const gateKey = dk => crypto.createHmac('sha256', Buffer.from(dk, 'base64')).update('agentlink-gate-1').digest()
+/** @param {string} dk @param {Buffer} ekm */
+const gateTag = (dk, ekm) => crypto.createHmac('sha256', gateKey(dk)).update(ekm).digest('base64url')
+const GATE_TAGS = 4
+
+/**
+ * Tags proving we hold the network's discovery key, for one connection (`ekm`: its TLS exporter).
+ * The newest few keys, so a node that missed a removal (and its key rotation) still recognises us.
+ * @param {string[]} dks oldest first @param {Buffer} ekm
+ */
+export const gateTags = (dks, ekm) => dks.slice(-GATE_TAGS).reverse().map(dk => gateTag(dk, ekm)).join(',')
+
+/**
+ * Does `header` hold a tag for one of `dks`? Old keys count too: they only let a client learn which
+ * member it is talking to, and anyone who ever held one already has the member list.
+ * @param {string[]} dks @param {Buffer} ekm @param {unknown} header
+ */
+export function gateOk(dks, ekm, header) {
+  if (typeof header !== 'string' || header.length > 64 * GATE_TAGS) return false
+  const tags = header.split(',').slice(0, GATE_TAGS)
+  return dks.some(dk => { const want = gateTag(dk, ekm); return tags.some(t => safeEq(t, want)) })
+}
+
+/** @param {'server' | 'client'} role @param {Buffer} ekm */
+const authPayload = (role, ekm) => JSON.stringify(['agentlink-auth-1', role, ekm.toString('base64')])
+/** Sign this connection's exporter as `role`. @param {string} key PEM @param {'server' | 'client'} role @param {Buffer} ekm */
+export const proveAuth = (key, role, ekm) => sign(key, authPayload(role, ekm))
+/** @param {crypto.KeyLike} pub @param {'server' | 'client'} role @param {Buffer} ekm @param {unknown} sig */
+export const checkAuth = (pub, role, ekm, sig) => verify(pub, authPayload(role, ekm), sig)