nattermatic 0.0.1 → 0.2.1

package/src/discovery.js

@@ -0,0 +1,60 @@
+// LAN discovery by encrypted UDP broadcast beacons. Deliberately does NOT use mDNS/Bonjour, so it
+// can never interfere with the OS's own hostname announcements.
+import dgram from 'node:dgram'
+import os from 'node:os'
+import { sealBeacon, openBeacon } from './crypto.js'
+
+const EVERY = 30_000
+const MAX_SKEW = 5 * 60_000
+const MAX_KEYS_TRIED = 64              // anyone can send a packet; a machine on an older key is found other ways
+
+function broadcastAddrs() {
+  const out = new Set(['255.255.255.255'])
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const i of list || []) {
+      if (i.family !== 'IPv4' || i.internal || !i.netmask) continue
+      const ip = i.address.split('.').map(Number), mask = i.netmask.split('.').map(Number)
+      out.add(ip.map((o, k) => (o | (~mask[k] & 255)) >>> 0).join('.'))
+    }
+  }
+  return [...out]
+}
+
+/**
+ * onPeer({host, fp, addr}) is called for each beacon from another member. Beacons are encrypted
+ * under the network's discovery key, so outsiders can neither read nor forge them; but a captured
+ * beacon can be replayed and a member could lie, so callers treat addr as a hint and only route to
+ * it once a TLS handshake there presents that member's key.
+ * @param {import('./types.js').Config} cfg
+ * @param {() => string[]} keys discovery keys to accept, current (used for sending) last
+ * @param {(peer: { host: string, fp: string, addr: string }) => void} onPeer
+ * @param {(...a: any[]) => void} log
+ */
+export function startDiscovery(cfg, keys, onPeer, log) {
+  const port = cfg.discoveryPort || cfg.port
+  const sock = dgram.createSocket({ type: 'udp4', reuseAddr: true })
+  /** @param {boolean} reply */
+  const beacon = reply => {
+    const dk = keys().at(-1)
+    return dk ? sealBeacon(dk, { host: cfg.host, fp: cfg.identity.fp, port: cfg.port, ts: Date.now(), reply }) : null
+  }
+  const announce = () => {
+    const msg = beacon(false)
+    if (msg) for (const a of broadcastAddrs()) sock.send(msg, port, a, () => {})
+  }
+  sock.on('message', (buf, rinfo) => {
+    const b = openBeacon(keys().slice(-MAX_KEYS_TRIED), buf)
+    if (!b || typeof b.host !== 'string' || typeof b.fp !== 'string' || b.fp === cfg.identity.fp) return
+    if (!Number.isFinite(b.ts) || Math.abs(Date.now() - b.ts) > MAX_SKEW) return
+    if (!Number.isInteger(b.port) || b.port <= 0 || b.port >= 65536) return
+    if (!b.reply) { const r = beacon(true); if (r) sock.send(r, port, rinfo.address, () => {}) }   // answer so discovery is instant both ways
+    onPeer({ host: b.host, fp: b.fp, addr: `${rinfo.address}:${b.port}` })
+  })
+  sock.on('error', e => log('discovery socket error:', e.message))
+  sock.bind(port, () => {
+    sock.setBroadcast(true)
+    announce()
+  })
+  const t = setInterval(announce, EVERY)
+  return { announce, stop() { clearInterval(t); try { sock.close() } catch {} } }
+}

package/src/legacy-env.js

@@ -0,0 +1,4 @@
+// Imported first by the entry point, before anything reads the environment: AGENTLINK_* settings,
+// from before the rename, still count.
+import { legacyEnv } from './legacy.js'
+legacyEnv()

package/src/legacy.js

@@ -0,0 +1,130 @@
+// nattermatic was called agentlink until 0.2.0. This moves a machine set up under the old name
+// onto the new one, keeping its key, network and messages, and keeps the old names working for
+// whatever still uses them: the user's scripts and settings, and sessions started before the upgrade.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+export const OLD = 'agentlink'
+/** agentlink's home, where a machine set up before the rename keeps its key and messages. */
+export const oldHome = () => path.join(os.homedir(), '.agentlink')
+
+/**
+ * AGENTLINK_* settings still count, under their new names, unless the new name is set too.
+ * Run before anything reads the environment.
+ */
+export function legacyEnv() {
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!k.startsWith('AGENTLINK_')) continue
+    const n = `NATTERMATIC_${k.slice('AGENTLINK_'.length)}`
+    if (!(n in process.env)) process.env[n] = v
+  }
+}
+
+const uid = () => process.getuid?.() ?? 0
+
+/** Stop and remove agentlink's background service, so it can't restart the old node. */
+export function removeOldService() {
+  if (process.platform === 'darwin') {
+    const plist = path.join(os.homedir(), 'Library', 'LaunchAgents', 'com.agentlink.node.plist')
+    if (!fs.existsSync(plist)) return false
+    spawnSync('launchctl', ['bootout', `gui/${uid()}/com.agentlink.node`], { stdio: 'ignore' })
+    fs.rmSync(plist, { force: true })
+    return true
+  }
+  if (process.platform === 'linux') {
+    const unit = path.join(os.homedir(), '.config', 'systemd', 'user', 'agentlink.service')
+    if (!fs.existsSync(unit)) return false
+    spawnSync('systemctl', ['--user', 'disable', '--now', 'agentlink'], { stdio: 'ignore' })
+    fs.rmSync(unit, { force: true })
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' })
+    return true
+  }
+  return false
+}
+
+/**
+ * Move ~/.agentlink to `home` and leave a link in its place, for sessions and shell lines that
+ * still use the old path. Only for the usual home, and only if `home` doesn't exist yet or holds
+ * nothing but what the installer has just put there (bin, pkg, node): entries already in `home`
+ * win, and what's left of the old home is the old program, which the new one replaces.
+ * If ~/.agentlink is itself a link (to a folder on another disk, say), the data stays where it is:
+ * the installer's entries go into that folder and `home` becomes a link to it too.
+ * Returns what happened, or null if there was nothing to move.
+ * @param {string} home @returns {string | null}
+ */
+export function moveOldHome(home) {
+  const old = oldHome()
+  let st
+  try { st = fs.lstatSync(old) } catch { return null }
+  /** @type {string | null} */
+  let target = null          // where a linked ~/.agentlink really is
+  if (st.isSymbolicLink()) {
+    try { target = fs.realpathSync(old) } catch { return `${old} was left alone: it is a link to a folder that isn't there` }
+    if (!fs.statSync(target).isDirectory()) return null
+    let real = null
+    try { real = fs.realpathSync(home) } catch {}
+    if (real === target) return null                 // moved already: both names lead to the same folder
+  } else if (!st.isDirectory()) return null
+  if (path.resolve(home) === old) return null
+  const installed = new Set(['bin', 'pkg', 'node'])
+  /** @type {string[]} */
+  let have = []
+  try { have = fs.readdirSync(home) } catch {}
+  if (have.some(e => !installed.has(e))) return `${old} was left alone: ${home} is already in use`
+  removeOldService()
+  if (target) {
+    // the new program replaces the old one in that folder; then home leads there
+    for (const e of have) {
+      fs.rmSync(path.join(target, e), { recursive: true, force: true })
+      moveEntry(path.join(home, e), path.join(target, e))
+    }
+    fs.rmSync(home, { recursive: true, force: true })
+    fs.symlinkSync(target, home)
+    return `linked ${home} to ${target}, where ${old} leads`
+  }
+  if (!have.length) {
+    fs.rmSync(home, { recursive: true, force: true })
+    fs.renameSync(old, home)
+  } else {
+    for (const e of fs.readdirSync(old)) if (!have.includes(e)) fs.renameSync(path.join(old, e), path.join(home, e))
+    fs.rmSync(old, { recursive: true, force: true })
+  }
+  fs.symlinkSync(home, old)
+  return `moved ${old} to ${home}`
+}
+
+/** rename, or copy and remove when the two are on different disks. @param {string} from @param {string} to */
+function moveEntry(from, to) {
+  try { fs.renameSync(from, to) } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code !== 'EXDEV') throw e
+    fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true })
+    fs.rmSync(from, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The database's old file name, renamed once nothing has it open: called by the node after it has
+ * the port, so no other node of this machine is running.
+ * @param {string} dir
+ */
+export function renameOldDb(dir) {
+  const from = path.join(dir, 'agentlink.db'), to = path.join(dir, 'nattermatic.db')
+  if (!fs.existsSync(from) || fs.existsSync(to)) return
+  for (const ext of ['-wal', '-shm', '']) {
+    try { fs.renameSync(from + ext, to + ext) } catch (e) { if (/** @type {any} */ (e).code !== 'ENOENT') throw e }
+  }
+}
+
+/** A permission rule naming agentlink's tools, under its new name. @param {any} rule @returns {any} */
+export const renamedRule = rule => typeof rule === 'string' ? rule.replace(/^mcp__agentlink(?=__|$|\()/, 'mcp__nattermatic') : rule
+
+/** agentlink.app, beside the app this runs from: replaced by nattermatic.app. @param {string | null} bundle */
+export function removeOldApp(bundle) {
+  if (!bundle) return false
+  const old = path.join(path.dirname(bundle), 'agentlink.app')
+  if (old === bundle || !fs.existsSync(path.join(old, 'Contents', 'Info.plist'))) return false
+  fs.rmSync(old, { recursive: true, force: true })
+  return true
+}

package/src/local.js

@@ -0,0 +1,219 @@
+// Client for the local node's loopback API, plus auto-start of the node.
+//
+// The local API runs over TLS on 127.0.0.1 with the same in-band identity check as connections
+// between machines (see tls.js): the node must prove it holds this machine's key, and so must the
+// client. Only a process that can read this machine's private key (this user) gets in, and a
+// process squatting on the port is refused before it is sent anything.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import crypto from 'node:crypto'
+import { authedRequest, authedRaw, PinError, PROTO } from './tls.js'
+import { cmpVersion, ensureHomeDir, errMsg, readIdentity, rosterPath, sleep, VERSION } from './config.js'
+import { Roster } from './roster.js'
+import { selfCmd } from './claude.js'
+
+const MAX_LOCAL_REPLY = 64 << 20   // the most an inbox read can come to: 100 messages of 64 KB, escaped
+
+/**
+ * The running node is a newer nattermatic than this process: this process (a session's adapter
+ * started before an upgrade, say) is the one that is out of date, and must not replace the node.
+ */
+export class StaleError extends Error {}
+
+/** Is the node behind `h` a different version from this process, and is it newer? @param {import('./types.js').Health} h */
+export function versionOf(h) {
+  const proto = h.proto ?? 0     // nodes from before the protocol number count as older
+  const differs = proto !== PROTO || h.version !== VERSION
+  const newer = proto !== PROTO ? proto > PROTO : cmpVersion(h.version, VERSION) > 0
+  return { differs, newer: differs && newer }
+}
+
+/** @type {{ stamp: string, dks: string[] } | null} */
+let dkCache = null
+/**
+ * The discovery keys that open this machine's node, read fresh (a removal elsewhere rotates them
+ * while long-lived clients, like MCP adapters, keep running) but through the roster's own rules, so
+ * only keys that count are used. Replaying the roster is only needed when the file has changed.
+ * @param {string} [dir] @returns {string[]}
+ */
+function readDks(dir) {
+  try {
+    const file = rosterPath(dir)
+    const st = fs.statSync(file)
+    const stamp = `${file} ${st.mtimeMs} ${st.size}`
+    if (dkCache?.stamp !== stamp) dkCache = { stamp, dks: Roster.load(file).gateDks() }
+    return dkCache.dks
+  } catch { return [] }
+}
+
+export class Local {
+  /** @param {Pick<import('./types.js').Config, 'identity' | 'port' | 'dir'>} cfg */
+  constructor(cfg) {
+    this.cfg = cfg
+    this.addr = `127.0.0.1:${cfg.port}`
+    this.accept = new Map([[cfg.identity.fp, crypto.createPublicKey(cfg.identity.key)]])
+  }
+
+  /**
+   * This machine's key as it is on disk now: `natter setup --new-network` (or joining another
+   * network) replaces it while long-lived clients, like MCP adapters, keep running, and the node
+   * they reach then proves the new key. Returns whether it changed.
+   */
+  reloadIdentity() {
+    let id = null
+    try { id = readIdentity(this.cfg.dir) } catch {}
+    if (!id || id.fp === this.cfg.identity.fp) return false
+    this.cfg.identity = id
+    this.accept = new Map([[id.fp, crypto.createPublicKey(id.key)]])
+    return true
+  }
+
+  /** @param {{ path: string, method?: 'GET' | 'POST', body?: string, timeout?: number, signal?: AbortSignal }} o */
+  // anyProto: after an upgrade the running node may be the previous version; setup must still reach it to stop it
+  opts(o) { return { addr: this.addr, identity: this.cfg.identity, accept: this.accept, dks: readDks(this.cfg.dir), anyProto: true, ...o } }
+
+  /** @param {unknown} e */
+  wrap(e) {
+    if (e instanceof PinError || /** @type {any} */ (e)?.code === 'EPROTO') return new Error(`port ${this.cfg.port} is not answered by this machine's nattermatic node`)
+    return new Error(`cannot reach the nattermatic node on port ${this.cfg.port}: ${errMsg(e)}`)
+  }
+
+  /**
+   * Request to the local node's API; throws with the node's error message on failure.
+   * @param {'GET'|'POST'} method
+   * @param {string} p
+   * @param {object} [obj]
+   * @returns {Promise<any>}
+   */
+  async req(method, p, obj, query = '', timeout = 15_000) {
+    let r
+    const send = () => authedRequest(this.opts({ method, path: p + query, body: obj === undefined ? '' : JSON.stringify(obj), timeout }), MAX_LOCAL_REPLY)
+    try {
+      r = await send()
+    } catch (e) {
+      // refused before anything was sent: if this machine's key was replaced meanwhile, try again with the new one
+      if (!(e instanceof PinError) || !this.reloadIdentity()) throw this.wrap(e)
+      try { r = await send() } catch (e2) { throw this.wrap(e2) }
+    }
+    /** @type {any} */
+    let data = {}
+    try { data = r.text ? JSON.parse(r.text) : {} } catch {}
+    if (r.status < 200 || r.status >= 300) throw new Error(data.error || `HTTP ${r.status}`)
+    return data
+  }
+
+  /**
+   * Is a node running on the port? null: nothing is listening. { foreign: true }: something that
+   * isn't this machine's node (another network's node, another user's, or not nattermatic at all).
+   * @returns {Promise<import('./types.js').Health | { foreign: true } | null>}
+   */
+  async health() {
+    const h = await this.health1()
+    // the node may be this machine's under a key replaced since this process started
+    return h && 'foreign' in h && this.reloadIdentity() ? this.health1() : h
+  }
+
+  /** @returns {Promise<import('./types.js').Health | { foreign: true } | null>} */
+  async health1() {
+    try {
+      const r = await authedRequest(this.opts({ path: '/health', timeout: 1000 }))
+      return r.status === 200 ? JSON.parse(r.text) : { foreign: true }
+    } catch (e) {
+      return e instanceof PinError || /** @type {any} */ (e)?.code === 'EPROTO' ? { foreign: true } : null
+    }
+  }
+
+  /** Make sure a node is running on this machine (start one in the background if not). */
+  async ensureNode() {
+    let h = await this.health()
+    if (h && 'foreign' in h) throw new Error(`port ${this.cfg.port} is used by something that is not this machine's nattermatic node`)
+    if (h && versionOf(h).newer) {
+      // nattermatic was upgraded while this process was running: replacing the node would downgrade it
+      throw new StaleError(`nattermatic on this machine was upgraded (to ${h.version}, protocol ${h.proto}) while this program (${VERSION}, protocol ${PROTO}) was running, so it can't use the node any more`)
+    }
+    // nattermatic was upgraded under a running node: replace it with this version
+    if (h && versionOf(h).differs) {
+      try { await this.req('POST', '/local/shutdown') } catch {}
+      for (let i = 0; i < 30 && (h = await this.health()) && !('foreign' in h) && versionOf(h).differs; i++) await sleep(100)
+    }
+    if (h && !('foreign' in h) && !versionOf(h).differs) return h
+    if (fs.existsSync(path.join(this.cfg.dir, 'disabled'))) throw new Error('nattermatic is uninstalled on this machine (run `natter setup` to re-enable)')
+    ensureHomeDir(this.cfg.dir)
+    const out = fs.openSync(path.join(this.cfg.dir, 'node.log'), 'a', 0o600)
+    let exited = false, spawnErr = ''
+    try {
+      // --on-demand: if another node wins the race for the port, this one exits instead of standing by.
+      // selfCmd(): a Node path that survives upgrades (the versioned execPath may be removed by brew)
+      const [cmd, ...args] = selfCmd()
+      const child = spawn(cmd, [...args, 'node', '--on-demand'], { detached: true, stdio: ['ignore', out, out], env: process.env })
+      child.on('error', e => { exited = true; spawnErr = errMsg(e) })   // e.g. ENOENT: must not crash the caller
+      child.on('exit', () => { exited = true })
+      child.unref()
+    } finally { fs.closeSync(out) }
+    for (let i = 0; i < 60; i++) {
+      await sleep(100)
+      const h2 = await this.health()
+      if (h2 && !('foreign' in h2)) return h2
+      if (exited && i > 5) break   // it died (lost the race to a node still starting, or failed): one last look below
+    }
+    const h3 = await this.health()
+    if (h3 && !('foreign' in h3)) return h3
+    throw new Error(`could not start the nattermatic node${spawnErr ? ` (${spawnErr})` : ''} (see ${path.join(this.cfg.dir, 'node.log')})`)
+  }
+
+  /**
+   * Wait for news for the session owned by one of `pids` (and, given `cwd`, working in that folder).
+   * null: there's no such session (yet).
+   * @param {number[]} pids @param {string} [cwd]
+   * @returns {Promise<{ event: string, name?: string, count?: number } | null>}
+   */
+  async wakeWait(pids, cwd) {
+    const { res } = await authedRaw(this.opts({ timeout: 0, path: `/local/wake?pids=${pids.join(',')}${cwd ? `&cwd=${encodeURIComponent(cwd)}` : ''}` }))
+    if (res.statusCode !== 200) { res.destroy(); return null }
+    for await (const { event, data } of sseEvents(res)) { res.destroy(); return { event, ...data } }
+    return { event: 'closed' }
+  }
+
+  /**
+   * Long-lived stream of messages for session `name`; `token` lets a reconnect reclaim the same name.
+   * Resolves when the stream ends.
+   * @param {string} name
+   * @param {string} token
+   * @param {(event: string, data: any) => Promise<void> | void} onEvent
+   * @param {{ signal?: AbortSignal, poll?: boolean }} [opts] poll: messages are read with the inbox tool, not pushed
+   */
+  async stream(name, token, onEvent, { signal, poll = false } = {}) {
+    let res
+    try {
+      ({ res } = await authedRaw(this.opts({
+        timeout: 0, signal,
+        // owner and cwd: the session that started this adapter, so its hook can find it: Claude Code's
+        // process (see wake.js), or Codex's shared app-server and the session's folder (see codex.js)
+        path: `/local/stream?name=${encodeURIComponent(name)}&token=${encodeURIComponent(token)}&owner=${process.ppid}&cwd=${encodeURIComponent(process.cwd())}${poll ? '&mode=poll' : ''}`,
+      })))
+    } catch (e) { throw /** @type {any} */ (e)?.name === 'AbortError' ? e : this.wrap(e) }
+    if (res.statusCode !== 200) { res.destroy(); throw new Error(`stream HTTP ${res.statusCode}`) }
+    for await (const { event, data } of sseEvents(res)) await onEvent(event, data)
+  }
+}
+
+/** The events of a server-sent stream, as they arrive. @param {import('node:http').IncomingMessage} res */
+async function* sseEvents(res) {
+  const dec = new TextDecoder()
+  let buf = ''
+  for await (const chunk of res) {
+    buf += dec.decode(chunk, { stream: true })
+    let i
+    while ((i = buf.indexOf('\n\n')) >= 0) {
+      const raw = buf.slice(0, i)
+      buf = buf.slice(i + 2)
+      let event = 'message', data = ''
+      for (const line of raw.split('\n')) {
+        if (line.startsWith('event: ')) event = line.slice(7)
+        else if (line.startsWith('data: ')) data += line.slice(6)
+      }
+      if (data) yield { event, data: JSON.parse(data) }
+    }
+  }
+}