heyquilt 0.0.1 → 0.3.106

package/src/vault/server.js

@@ -0,0 +1,279 @@
+// quilt-vault (docs/superpowers/specs/2026-10-18-secrets.md): the only place a secret's value is
+// ever opened. Two jobs, nothing else:
+//
+// - POST /v1/write: a person's app or browser sends values here with a write ticket from
+//   quilt-api. The vault seals each under its scope's data key and stores the sealed blob
+//   through quilt-api's internal routes. It answers each name's digest, never a value.
+// - /g/<run token>/<NAME>/<path>: the gateway `quilt run` points a process at. quilt-api says
+//   whether the run may use NAME now; the vault opens the value, attaches it to the request in
+//   the secret's format, sends the request to the secret's one host, and streams the answer
+//   back with every copy of the value masked.
+//
+// No route answers a value. Values are never logged.
+import http from 'node:http'
+import https from 'node:https'
+import dns from 'node:dns'
+import net from 'node:net'
+import { Transform } from 'node:stream'
+import zlib from 'node:zlib'
+import { newDataKey, sealValue, openValue, digestOf } from './crypto.js'
+import { applyCredential, maskForms, shortDigest, cleanUpstream, MAX_VALUE_BYTES, STAND_IN } from '../ui/secret-rules.js'
+
+export const MASK = '[hidden by Quilt]'
+const MAX_WRITE_BODY = 2 * 1024 * 1024
+const UPSTREAM_TIMEOUT_MS = 120 * 1000
+// Headers that belong to one connection, never passed on (RFC 9110 §7.6.1), and ones the vault sets itself.
+const HOP = new Set(['connection', 'keep-alive', 'proxy-connection', 'proxy-authorization', 'proxy-authenticate', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length', 'accept-encoding', 'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'via'])
+const NAME = /^[A-Z_][A-Z0-9_]{0,63}$/
+const TOKEN = /^qrun_[A-Za-z0-9_-]{20,100}$/
+
+/** Whether an address is inside a private, local or reserved network (the vault never sends there). */
+export function privateAddress (address) {
+  const a = String(address).toLowerCase()
+  if (net.isIPv4(a)) {
+    const [x, y] = a.split('.').map(Number)
+    return x === 0 || x === 10 || x === 127 || (x === 100 && y >= 64 && y <= 127) || (x === 169 && y === 254) || (x === 172 && y >= 16 && y <= 31) || (x === 192 && y === 168) || (x === 192 && y === 0) || (x === 198 && (y === 18 || y === 19)) || x >= 224
+  }
+  if (net.isIPv6(a)) {
+    if (a === '::' || a === '::1') return true
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(a)
+    if (mapped) return privateAddress(mapped[1])
+    return /^(fc|fd|fe8|fe9|fea|feb|ff)/.test(a) || a.startsWith('64:ff9b:') || a.startsWith('2001:db8')
+  }
+  return true
+}
+
+/** A DNS lookup that refuses names pointing inside a network, checked as the connection is made. */
+export function publicLookup (hostname, options, callback) {
+  dns.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+    if (err) return callback(err)
+    const list = Array.isArray(addresses) ? addresses : [{ address: addresses, family: options.family || 4 }]
+    if (!list.length || list.some((x) => privateAddress(x.address))) return callback(Object.assign(new Error(`${hostname} points inside a private network`), { code: 'EPRIVATE' }))
+    if (options.all) return callback(null, list)
+    callback(null, list[0].address, list[0].family)
+  })
+}
+
+/** Replaces every form of a value in a stream, including one split across chunks. */
+export function masker (forms, replacement = MASK) {
+  const needles = forms.map((f) => Buffer.from(f)).filter((b) => b.length).sort((a, b) => b.length - a.length)
+  const keep = needles.length ? Math.max(...needles.map((n) => n.length)) - 1 : 0
+  const out = Buffer.from(replacement)
+  let carry = Buffer.alloc(0)
+  const run = (data, end, push) => {
+    const boundary = end ? data.length : Math.max(0, data.length - keep)
+    let pos = 0
+    while (needles.length) {
+      let best = -1; let len = 0
+      for (const n of needles) { const i = data.indexOf(n, pos); if (i !== -1 && (best === -1 || i < best)) { best = i; len = n.length } }
+      if (best === -1 || best >= boundary) break
+      if (best > pos) push(data.subarray(pos, best))
+      push(out)
+      pos = best + len
+    }
+    const cut = Math.max(pos, boundary)
+    if (cut > pos) push(data.subarray(pos, cut))
+    return data.subarray(cut)
+  }
+  return new Transform({
+    transform (chunk, enc, cb) { carry = run(Buffer.concat([carry, chunk]), false, (b) => this.push(b)); cb() },
+    flush (cb) { run(carry, true, (b) => this.push(b)); carry = Buffer.alloc(0); cb() }
+  })
+}
+
+const maskText = (s, forms) => forms.reduce((acc, f) => acc.split(f).join(MASK), String(s))
+
+/**
+ * Starts the vault. `apiUrl` and `vaultSecret` reach quilt-api's internal routes; `keys` is a
+ * key ring (crypto.js keyRing); `digestKey` (32 bytes) makes digests. `allowedOrigins` may write
+ * from a browser (the website). `upstreamProtocol` and `allowLocalUpstreams` are for tests only.
+ */
+export function startVault ({ port = 0, host = '127.0.0.1', apiUrl, vaultSecret, keys, digestKey, fetch: fetchImpl = globalThis.fetch, now = Date.now, log = () => {}, allowedOrigins = [], upstreamProtocol = 'https', allowLocalUpstreams = false, runLimit = 1200 }) {
+  if (!apiUrl || !vaultSecret || !keys || !digestKey) throw new Error('the vault needs QUILT_API_URL, QUILT_VAULT_SECRET, a root key and VAULT_DIGEST_KEY')
+  const api = String(apiUrl).replace(/\/+$/, '')
+  const origins = new Set(allowedOrigins.map((o) => String(o).replace(/\/+$/, '')))
+  const client = upstreamProtocol === 'http' ? http : https
+
+  /** quilt-api's internal routes: { status, body }. */
+  async function internal (path, body) {
+    let res
+    try {
+      res = await fetchImpl(`${api}${path}`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-quilt-vault-secret': vaultSecret }, body: JSON.stringify(body), signal: AbortSignal.timeout(15_000) })
+    } catch (err) { return { status: 502, body: { error: `Quilt did not answer (${err.message})` } } }
+    return { status: res.status, body: await res.json().catch(() => ({})) }
+  }
+
+  const hits = new Map()
+  const limited = (key) => {
+    const t = now()
+    const recent = (hits.get(key) || []).filter((x) => t - x < 60_000)
+    recent.push(t)
+    hits.set(key, recent)
+    if (hits.size > 50_000) hits.delete(hits.keys().next().value)
+    return recent.length > runLimit
+  }
+
+  const cors = (req) => {
+    const o = String(req.headers.origin || '')
+    return origins.has(o) ? { 'access-control-allow-origin': o, vary: 'origin' } : {}
+  }
+  const json = (req, res, status, data) => {
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...cors(req) })
+    res.end(JSON.stringify(data))
+  }
+
+  /** The scope's data key, opened: made (and stored) the first time the scope saves a secret. */
+  async function dataKeyFor (scope, given) {
+    let dk = given
+    if (!dk) {
+      const ctx = { scopeType: scope.type, scopeId: scope.id, version: 1 }
+      const fresh = newDataKey()
+      const sealedKey = await keys.wrap(fresh, ctx)
+      const r = await internal('/v1/vault/data-keys', { scopeType: scope.type, scopeId: scope.id, version: 1, sealedKey, provider: keys.primary })
+      if (r.status !== 200) throw Object.assign(new Error(r.body.error || 'could not store the data key'), { status: 502 })
+      dk = r.body.dataKey
+      // Another save made it first: theirs is the one stored, so it is the one used.
+      if (dk.sealedKey === sealedKey) return { version: 1, key: fresh }
+    }
+    return { version: dk.version, key: await keys.unwrap(dk.sealedKey, { scopeType: scope.type, scopeId: scope.id, version: dk.version }) }
+  }
+
+  async function write (req, res) {
+    let body
+    try { body = JSON.parse((await readBody(req, MAX_WRITE_BODY)).toString('utf8')) } catch (err) { return json(req, res, err.status || 400, { error: err.status ? err.message : 'bad json' }) }
+    const values = body && typeof body.values === 'object' && !Array.isArray(body.values) ? body.values : null
+    if (!values || !Object.keys(values).length) return json(req, res, 400, { error: 'send the values to save' })
+    for (const [name, v] of Object.entries(values)) {
+      if (typeof v !== 'string' || !v.length) return json(req, res, 400, { error: `${String(name).slice(0, 64)} has no value` })
+      if (Buffer.byteLength(v) > MAX_VALUE_BYTES) return json(req, res, 413, { error: `${String(name).slice(0, 64)} is longer than ${MAX_VALUE_BYTES / 1024} KB` })
+    }
+    const t = await internal('/v1/vault/tickets/redeem', { ticket: String(body.ticket || '') })
+    if (t.status !== 200) return json(req, res, t.status, { error: t.body.error || 'could not save' })
+    const wanted = new Set(t.body.entries.map((e) => e.name))
+    const names = Object.keys(values)
+    if (names.some((n) => !wanted.has(n)) || names.length !== wanted.size) return json(req, res, 400, { error: 'those are not the names this save was for' })
+    let dk
+    try { dk = await dataKeyFor(t.body.scope, t.body.dataKey) } catch (err) { log(`write: data key: ${err.message}`); return json(req, res, err.status || 500, { error: 'could not open this scope\'s key; try again' }) }
+    const scope = { scopeType: t.body.scope.type, scopeId: t.body.scope.id }
+    const items = names.map((name) => ({ name, sealedValue: sealValue(dk.key, scope, name, values[name]), keyVersion: dk.version, digest: digestOf(digestKey, values[name]) }))
+    const stored = await internal('/v1/vault/secrets', { ticketId: t.body.ticketId, items })
+    if (stored.status !== 200) return json(req, res, stored.status, { error: stored.body.error || 'could not save' })
+    log(`write: ${items.length} secret(s) saved in ${scope.scopeType} ${scope.scopeId}`)
+    return json(req, res, 200, { saved: items.map((i) => ({ name: i.name, digest: shortDigest(i.digest) })) })
+  }
+
+  async function gateway (req, res, token, name, rest) {
+    if (!TOKEN.test(token) || !NAME.test(name)) return json(req, res, 404, { error: 'not a Quilt gateway address' })
+    if (limited(token)) return json(req, res, 429, { error: 'too many requests for this run; slow down' })
+    const r = await internal('/v1/vault/resolve', { token, name })
+    if (r.status !== 200) {
+      req.resume()
+      return json(req, res, r.status, { error: r.body.error || 'not allowed' })
+    }
+    const { secret, dataKey } = r.body
+    let value
+    try {
+      const key = await keys.unwrap(dataKey.sealedKey, { scopeType: secret.scopeType, scopeId: secret.scopeId, version: dataKey.version })
+      value = openValue(key, { scopeType: secret.scopeType, scopeId: secret.scopeId }, secret.name, secret.sealedValue)
+    } catch (err) {
+      log(`gateway: could not open ${secret.name} (${err.message})`)
+      req.resume()
+      return json(req, res, 500, { error: 'the vault could not open this secret; replace it' })
+    }
+    let upstream
+    try { upstream = cleanUpstream(secret.upstream, { allowLocal: allowLocalUpstreams }) } catch { req.resume(); return json(req, res, 502, { error: 'this secret has no host the vault may reach' }) }
+    const cred = applyCredential(secret.format, value)
+    const forms = maskForms(secret.format, value)
+    const incoming = new URL(rest || '/', 'http://x')
+    let path = incoming.pathname
+    if (cred.path !== undefined) path = `/${cred.path.replace(/\/+$/, '')}${path === '/' ? '' : path}`
+    const query = new URLSearchParams(incoming.search)
+    if (cred.query) { query.delete(cred.query[0]); query.append(cred.query[0], cred.query[1]) }
+    const qs = query.toString()
+    const headers = {}
+    for (const [k, v] of Object.entries(req.headers)) {
+      const lower = k.toLowerCase()
+      if (HOP.has(lower) || lower.startsWith('fly-') || lower.startsWith('x-quilt-')) continue
+      // The process's stand-in credential (an SDK sends "Bearer quilt"): never passed on.
+      if (cred.header && lower === cred.header[0]) continue
+      if ((lower === 'authorization' || lower === 'x-api-key') && String(v).replace(/^(Bearer|Basic|Token)\s+/i, '') === STAND_IN) continue
+      headers[lower] = v
+    }
+    if (cred.header) headers[cred.header[0]] = cred.header[1]
+    headers['accept-encoding'] = 'identity' // the mask has to see the answer as text
+    const [hostname, port] = upstream.split(':')
+    const out = client.request({
+      protocol: `${upstreamProtocol}:`,
+      hostname,
+      port: port ? Number(port) : undefined,
+      method: req.method,
+      path: `${path}${qs ? `?${qs}` : ''}`,
+      headers: { ...headers, host: upstream },
+      servername: hostname,
+      lookup: allowLocalUpstreams ? undefined : publicLookup,
+      timeout: UPSTREAM_TIMEOUT_MS
+    })
+    let answered = false
+    out.on('timeout', () => out.destroy(Object.assign(new Error('the service took too long to answer'), { code: 'ETIMEDOUT' })))
+    out.on('error', (err) => {
+      if (answered) return res.destroy()
+      answered = true
+      log(`gateway: ${secret.name} to ${upstream}: ${err.code || err.message}`)
+      json(req, res, 502, { error: err.code === 'EPRIVATE' ? `${upstream} points inside a private network; the vault won't send secrets there` : `${upstream} did not answer (${err.code || 'error'})` })
+    })
+    out.on('response', (up) => {
+      answered = true
+      const h = {}
+      for (const [k, v] of Object.entries(up.headers)) {
+        if (HOP.has(k) || k === 'content-encoding') continue
+        h[k] = Array.isArray(v) ? v.map((x) => maskText(x, forms)) : maskText(v, forms)
+      }
+      res.writeHead(up.statusCode, up.statusMessage, h)
+      // A service that compresses anyway (it was asked not to): opened here, so the mask sees the text.
+      const enc = String(up.headers['content-encoding'] || '').trim().toLowerCase()
+      const open = enc === 'gzip' || enc === 'x-gzip' ? zlib.createGunzip() : enc === 'deflate' ? zlib.createInflate() : enc === 'br' ? zlib.createBrotliDecompress() : null
+      const body = open ? up.pipe(open) : up
+      if (open) open.on('error', () => res.destroy())
+      body.pipe(masker(forms)).pipe(res)
+      up.on('error', () => res.destroy())
+    })
+    req.pipe(out)
+    req.on('error', () => out.destroy())
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://x')
+      if (req.method === 'GET' && url.pathname === '/healthz') return json(req, res, 200, { ok: true })
+      if (url.pathname === '/v1/write') {
+        if (req.method === 'OPTIONS') {
+          res.writeHead(204, { ...cors(req), 'access-control-allow-methods': 'POST', 'access-control-allow-headers': 'content-type', 'access-control-max-age': '600' })
+          return res.end()
+        }
+        if (req.method === 'POST') return await write(req, res)
+      }
+      // /g/<token>/<NAME>[/<path>]: the raw path, so the service gets it exactly as sent.
+      const m = /^\/g\/([^/?#]+)\/([^/?#]+)(\/[^?#]*)?(\?[^#]*)?$/.exec(req.url)
+      if (m) return await gateway(req, res, m[1], m[2], `${m[3] || '/'}${m[4] || ''}`)
+      json(req, res, 404, { error: 'not found' })
+    } catch (err) {
+      log(`vault error: ${err.message}`)
+      if (!res.headersSent) json(req, res, 500, { error: 'internal error' })
+      else res.destroy()
+    }
+  })
+
+  return new Promise((resolve) => server.listen(port, host, () => {
+    const p = server.address().port
+    resolve({ port: p, url: `http://${host}:${p}`, close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(r) }) })
+  }))
+}
+
+function readBody (req, max) {
+  return new Promise((resolve, reject) => {
+    let size = 0; const chunks = []
+    req.on('data', (c) => { size += c.length; if (size > max) { req.destroy(); reject(Object.assign(new Error('too large'), { status: 413 })) } else chunks.push(c) })
+    req.on('end', () => resolve(Buffer.concat(chunks)))
+    req.on('error', reject)
+  })
+}

package/src/vault/sigv4.js

@@ -0,0 +1,38 @@
+// AWS Signature Version 4, for the vault's calls to AWS KMS (kms.js). Small and dependency
+// free: the vault keeps as little code as it can.
+import crypto from 'node:crypto'
+
+const sha256 = (data) => crypto.createHash('sha256').update(data).digest('hex')
+const hmac = (key, data) => crypto.createHmac('sha256', key).update(data).digest()
+// RFC 3986 encoding, as AWS wants it (encodeURIComponent leaves !'()* alone).
+const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+
+/** 20150830T123600Z and 20150830 for a time. */
+export function amzDates (at) {
+  const iso = new Date(at).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '')
+  return { amzDate: iso, dateStamp: iso.slice(0, 8) }
+}
+
+/**
+ * The headers that sign a request: { authorization, 'x-amz-date', 'x-amz-security-token'? }.
+ * `headers` are the ones to sign (host is taken from the URL when absent).
+ */
+export function signAws ({ method, url, headers = {}, body = '', region, service, credentials, now = Date.now }) {
+  const u = new URL(url)
+  const { amzDate, dateStamp } = amzDates(now())
+  const all = { host: u.host, ...Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), String(v)])), 'x-amz-date': amzDate }
+  if (credentials.sessionToken) all['x-amz-security-token'] = credentials.sessionToken
+  const names = Object.keys(all).sort()
+  const canonicalHeaders = names.map((n) => `${n}:${all[n].trim().replace(/\s+/g, ' ')}\n`).join('')
+  const signedHeaders = names.join(';')
+  const path = u.pathname.split('/').map((seg) => enc(decodeURIComponent(seg))).join('/') || '/'
+  const query = [...u.searchParams].map(([k, v]) => [enc(k), enc(v)]).sort(([a, x], [b, y]) => (a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0)).map(([k, v]) => `${k}=${v}`).join('&')
+  const canonical = [method.toUpperCase(), path, query, canonicalHeaders, signedHeaders, sha256(body)].join('\n')
+  const scope = `${dateStamp}/${region}/${service}/aws4_request`
+  const toSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256(canonical)].join('\n')
+  const key = hmac(hmac(hmac(hmac(`AWS4${credentials.secretAccessKey}`, dateStamp), region), service), 'aws4_request')
+  const signature = crypto.createHmac('sha256', key).update(toSign).digest('hex')
+  const out = { 'x-amz-date': amzDate, authorization: `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}` }
+  if (credentials.sessionToken) out['x-amz-security-token'] = credentials.sessionToken
+  return out
+}

package/src/webhooks.js

@@ -0,0 +1,235 @@
+// Webhooks: an agent asks to be told, by an HTTP POST to a URL of its own, when
+// it is mentioned in chat (@name), sent a direct message, or handed a task. The
+// agent sets the subscription itself (quilt_webhook_subscribe), so a cloud agent
+// with a routine behind a webhook trigger wakes up instead of polling quilt_inbox.
+//
+// One POST per event, JSON, signed with the subscription's secret so the agent can
+// check it came from Quilt (`x-quilt-signature: sha256=<hmac>` over `<ts>.<body>`).
+// A failed delivery is tried again a few times; after that the event is still in
+// quilt_inbox, which never depends on the webhook.
+//
+// The pure parts (shapes, signing, validation) are shared by the relay, which
+// delivers for hosted agents, and the local session, which delivers for agents
+// joined from a computer.
+import crypto from 'node:crypto'
+import dns from 'node:dns'
+import net from 'node:net'
+
+export const WEBHOOK_EVENTS = ['chat.mention', 'chat.dm', 'task.assigned']
+export const EVENT_OF_KIND = { mention: 'chat.mention', dm: 'chat.dm', task: 'task.assigned' }
+export const MAX_URL = 2000
+export const MAX_SECRET = 200
+export const MIN_SECRET = 16
+export const MAX_BEARER = 500
+export const DELIVERY_TIMEOUT_MS = 10_000
+// Waits before the second, third and fourth tries.
+export const RETRY_DELAYS_MS = [1000, 5000, 25_000]
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0'])
+const isPrivateIp = (host) => {
+  const h = host.replace(/^\[|\]$/g, '')
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(h)) {
+    const [a, b] = h.split('.').map(Number)
+    return a === 10 || a === 127 || a === 0 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+  }
+  if (h.includes(':')) return /^(::1|::|fc|fd|fe80)/i.test(h)
+  return false
+}
+
+// Addresses that are not on the public internet: unspecified, loopback, private, shared
+// (CGNAT), link-local, benchmarking, multicast and reserved; for IPv6 also unique-local,
+// link-local, site-local, multicast, IPv4-compatible and NAT64. Two lists, because a
+// BlockList matches IPv4 rules against IPv4-mapped IPv6 addresses (wanted) and IPv6 rules
+// covering ::ffff:0:0/96 against every IPv4 address (not wanted).
+const PRIVATE_V4 = new net.BlockList()
+for (const [a, p] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['224.0.0.0', 3]]) PRIVATE_V4.addSubnet(a, p, 'ipv4')
+const PRIVATE_V6 = new net.BlockList()
+for (const [a, p] of [['::', 96], ['64:ff9b::', 96], ['fc00::', 7], ['fe80::', 10], ['fec0::', 10], ['ff00::', 8]]) PRIVATE_V6.addSubnet(a, p, 'ipv6')
+
+/** Whether `address` (an IP, as DNS answers it) is not on the public internet. Anything that isn't an address counts as private. */
+export function isPrivateAddress (address) {
+  let a = String(address || '').replace(/^\[|\]$/g, '').split('%')[0]
+  const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)
+  if (mapped) a = mapped[1]
+  const kind = net.isIP(a)
+  if (kind === 4) return PRIVATE_V4.check(a, 'ipv4')
+  if (kind === 6) return PRIVATE_V6.check(a, 'ipv6') || PRIVATE_V4.check(a, 'ipv6')
+  return true
+}
+
+/**
+ * Whether a webhook URL's host is on the public internet as it resolves now: { ok: true }, or
+ * { ok: false, reason }. A trailing dot is the same host; a local name or address never reaches
+ * DNS; every address the name resolves to must be public. Never throws. `lookup` is for tests.
+ * (parseWebhookUrl only reads the URL as written; this is for sends from Quilt's own servers.)
+ */
+export async function publicWebhookHost (url, { lookup = dns.promises.lookup } = {}) {
+  let host
+  try { host = new URL(url).hostname.toLowerCase() } catch { return { ok: false, reason: 'not a valid URL' } }
+  const bare = host.replace(/^\[|\]$/g, '').replace(/\.+$/, '')
+  if (!bare || LOCAL_HOSTS.has(bare) || bare.endsWith('.localhost')) return { ok: false, reason: `${host} is a local address` }
+  if (net.isIP(bare)) return isPrivateAddress(bare) ? { ok: false, reason: `${host} is a local or private address` } : { ok: true }
+  let addrs
+  try { addrs = await lookup(bare, { all: true, verbatim: true }) } catch (err) { return { ok: false, reason: `${host} did not resolve (${err?.code || err?.message || err})` } }
+  if (!Array.isArray(addrs) || !addrs.length) return { ok: false, reason: `${host} did not resolve` }
+  const bad = addrs.find((a) => isPrivateAddress(a?.address))
+  if (bad) return { ok: false, reason: `${host} resolves to a local or private address (${bad.address})` }
+  return { ok: true }
+}
+
+/**
+ * The URL a subscription may POST to: https, no credentials, and not the relay's own
+ * network. `allowLocal` (the local session) also takes http to this computer, for an
+ * agent whose receiver runs here.
+ */
+export function parseWebhookUrl (raw, { allowLocal = false } = {}) {
+  const s = String(raw || '').trim()
+  if (!s) throw new Error('Give the URL Quilt should POST to.')
+  if (s.length > MAX_URL) throw new Error('That URL is too long.')
+  let u
+  try { u = new URL(s) } catch { throw new Error('That is not a valid URL.') }
+  if (u.username || u.password) throw new Error('The URL may not carry a user name or password.')
+  const host = u.hostname.toLowerCase()
+  const local = LOCAL_HOSTS.has(host) || host.endsWith('.localhost') || isPrivateIp(host)
+  if (u.protocol === 'http:') {
+    if (!allowLocal || !local) throw new Error('The URL must use https (http is only for a receiver on this computer).')
+  } else if (u.protocol !== 'https:') {
+    throw new Error('The URL must start with https://.')
+  } else if (local && !allowLocal) {
+    throw new Error('The URL must be reachable from the internet, not a local or private address.')
+  }
+  return u.toString()
+}
+
+/** The event names in `list` (default: all), or an error naming a bad one. */
+export function parseWebhookEvents (list) {
+  if (list == null) return WEBHOOK_EVENTS.slice()
+  if (!Array.isArray(list)) throw new Error(`events: give a list of ${WEBHOOK_EVENTS.join(', ')}.`)
+  const out = []
+  for (const e of list) {
+    const n = String(e || '').trim()
+    if (!WEBHOOK_EVENTS.includes(n)) throw new Error(`Unknown event "${n}". Events: ${WEBHOOK_EVENTS.join(', ')}.`)
+    if (!out.includes(n)) out.push(n)
+  }
+  if (!out.length) throw new Error(`events: give at least one of ${WEBHOOK_EVENTS.join(', ')}.`)
+  return out
+}
+
+export const newSecret = () => crypto.randomBytes(24).toString('hex')
+
+/**
+ * A subscription from what an agent gave: { url, secret, events, since }. A secret the
+ * agent chose is kept (16 to 200 characters); without one, a new one is made and the
+ * agent is shown it once, in the tool's answer.
+ */
+export function makeSubscription ({ url, secret, events, bearer } = {}, { allowLocal = false, now = Date.now } = {}) {
+  const u = parseWebhookUrl(url, { allowLocal })
+  const ev = parseWebhookEvents(events)
+  let s = secret == null ? '' : String(secret)
+  if (s && (s.length < MIN_SECRET || s.length > MAX_SECRET)) throw new Error(`The secret must be ${MIN_SECRET} to ${MAX_SECRET} characters (or leave it out and Quilt makes one).`)
+  const made = !s
+  if (made) s = newSecret()
+  // A key the receiver wants on every POST (a Grok Bot routine's sender key, for example), sent as Authorization: Bearer <key>.
+  const b = bearer == null ? '' : String(bearer).trim()
+  if (b.length > MAX_BEARER || /[\r\n]/.test(b)) throw new Error(`The bearer key must be one line of at most ${MAX_BEARER} characters.`)
+  return { url: u, secret: s, events: ev, since: now(), made, ...(b ? { bearer: b } : {}) }
+}
+
+/** The subscription as an agent sees it (its secret only when it was just made). */
+export function describeSubscription (sub, { showSecret = false } = {}) {
+  if (!sub) return 'No webhook: Quilt only answers quilt_inbox when you ask.'
+  const lines = [`Webhook: Quilt POSTs to ${sub.url} on ${sub.events.join(', ')}${sub.bearer ? ', with your bearer key in the Authorization header' : ''}.`]
+  if (showSecret) lines.push(`Secret (shown once; check x-quilt-signature with it): ${sub.secret}`)
+  lines.push('Each POST is JSON ({ event, id, session, workspace, room, to, by, text, ts, task?, context? }; session: the session it is from, which you name as `session` in the tools you answer with, so an answer never lands in another session; workspace: { id } or null; context: the messages before this one between you and its sender, oldest first) with x-quilt-event, x-quilt-delivery, x-quilt-timestamp and ' +
+    'x-quilt-signature: sha256=HMAC-SHA256(secret, "<timestamp>.<body>"). Answer 2xx quickly; a failed POST is retried a few times. ' +
+    'What you are told is still in quilt_inbox. Stop with quilt_webhook_unsubscribe.')
+  return lines.join('\n')
+}
+
+/**
+ * The body for one inbox event (see inbox.js) to `to`, in `room`: `session` is the room (the id
+ * to answer in, with every tool's `session`), `workspace` the workspace it is in, when known.
+ */
+export function webhookPayload (e, { room = '', to = '', workspace = '' } = {}) {
+  const p = { event: EVENT_OF_KIND[e.kind] || e.kind, id: String(e.id || ''), room, session: room, workspace: workspace ? { id: String(workspace) } : null, to, by: String(e.by || ''), text: String(e.text || ''), ts: Number(e.ts) || Date.now() }
+  if (e.kind === 'task' && e.task) p.task = { id: e.task.id, title: e.task.title, column: e.task.column, assignee: e.task.assignee ?? null, forAi: !!e.task.forAi, tool: e.task.tool || '', files: e.task.files || [] }
+  if (e.commit) p.commit = true // work this member asked to commit was committed: nothing to answer
+  if (e.nudge) p.nudge = true // a reminder from Quilt (uncommitted work): nothing to answer
+  // The conversation before this with whoever it is from (conversation.js), so an agent woken
+  // fresh knows what "that" refers to; `earlier` older messages are a quilt_conversation away.
+  if (Array.isArray(e.context) && e.context.length) {
+    p.context = e.context.map((m) => ({ id: m.id, by: m.by, ...(m.to ? { to: m.to } : {}), text: m.text, ts: m.ts }))
+    if (e.earlier) p.earlier = e.earlier
+  }
+  return p
+}
+
+/** `sha256=<hex>`: HMAC-SHA256 with `secret` over `<ts>.<body>`. */
+export function signWebhook (secret, ts, body) {
+  return 'sha256=' + crypto.createHmac('sha256', String(secret)).update(`${ts}.${body}`).digest('hex')
+}
+
+/** For receivers: whether `signature` is right for this body and timestamp. */
+export function verifyWebhook (secret, ts, body, signature) {
+  const want = Buffer.from(signWebhook(secret, ts, body))
+  const got = Buffer.from(String(signature || ''))
+  return want.length === got.length && crypto.timingSafeEqual(want, got)
+}
+
+/** Whether a response means "try again later". */
+const retryable = (status) => status === 408 || status === 429 || status >= 500
+
+/**
+ * POSTs `payload` to `sub.url`, signed, trying again after each delay in `delays` when
+ * the receiver is down, slow or answers 5xx/429. Resolves { ok, status, attempts, error? };
+ * never throws. `fetch`, `delays` and `sleep` are for tests.
+ */
+export async function deliverWebhook (sub, payload, { fetch = globalThis.fetch, delays = RETRY_DELAYS_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), timeoutMs = DELIVERY_TIMEOUT_MS, now = Date.now, log = () => {} } = {}) {
+  const body = JSON.stringify(payload)
+  const delivery = crypto.randomUUID()
+  let status = 0
+  let error = ''
+  let attempt = 0
+  while (attempt < delays.length + 1) {
+    attempt++
+    const ts = String(now())
+    try {
+      const res = await fetch(sub.url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'user-agent': 'quilt-webhook',
+          'x-quilt-event': payload.event,
+          'x-quilt-delivery': delivery,
+          'x-quilt-timestamp': ts,
+          'x-quilt-signature': signWebhook(sub.secret, ts, body),
+          ...(sub.bearer ? { authorization: `Bearer ${sub.bearer}` } : {})
+        },
+        body,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(timeoutMs)
+      })
+      status = res.status
+      error = ''
+      if (res.ok) return { ok: true, status, attempts: attempt, delivery }
+      if (!retryable(status)) break
+    } catch (err) {
+      status = 0
+      error = err && err.message ? err.message : String(err)
+    }
+    if (attempt <= delays.length) await sleep(delays[attempt - 1])
+  }
+  log(`webhook to ${sub.url} failed (${payload.event}): ${error || `HTTP ${status}`}`)
+  return { ok: false, status, attempts: attempt, error: error || `HTTP ${status}`, delivery }
+}
+
+/** Delivers each of `events` the subscription asks for, one after another (order kept). */
+export async function deliverEvents (sub, events, { room = '', to = '', workspace = '' } = {}, opts = {}) {
+  const out = []
+  for (const e of events || []) {
+    const p = webhookPayload(e, { room, to, workspace })
+    if (!sub.events.includes(p.event)) continue
+    out.push(await deliverWebhook(sub, p, opts))
+  }
+  return out
+}

package/src/workspace-cli.js

@@ -0,0 +1,62 @@
+// `quilt workspace ...`: the workspace library from a shell, for agents (and people) that work
+// with commands rather than MCP. Each command runs the same tool the MCP offers
+// (workspace-tools.js), as whoever the MCP would act as here (mcp.js workspaceActor): this
+// folder's agent, or the person signed in on this computer.
+import { registerWorkspaceTools } from './workspace-tools.js'
+
+export const WORKSPACE_USAGE = `Usage:
+  quilt workspace list                                    Workspaces you can reach
+  quilt workspace files <workspace> [folder] [--glob g]   What is in its library
+  quilt workspace get <workspace> <path> [--version n]    Read a file (text is printed; anything else is saved and its path printed)
+  quilt workspace put <workspace> <path> <local file> [--note "what it is"]
+                                                          Upload a file from this project (a new version if the path exists)
+  quilt workspace write <workspace> <path> <text> [--note n]
+                                                          Save text as a file
+  quilt workspace mkdir <workspace> <folder>              Make a folder (and any above it)
+  quilt workspace mv <workspace> <path> <new path>        Rename or move a file or folder
+  quilt workspace rm <workspace> <path>                   Delete a file or folder
+  quilt workspace webhook <https url> | webhook-off       Workspace events to your URL (agents)
+<workspace> is its name or id.`
+
+/** Pulls `--name value` options out of `args`: { opts, rest }. */
+function options (args, names) {
+  const opts = {}
+  const rest = []
+  for (let i = 0; i < args.length; i++) {
+    const m = String(args[i]).match(/^--([a-z]+)(?:=(.*))?$/)
+    if (m && names.includes(m[1])) {
+      opts[m[1]] = m[2] !== undefined ? m[2] : args[++i]
+      if (opts[m[1]] === undefined) throw new Error(`--${m[1]} needs a value`)
+    } else rest.push(args[i])
+  }
+  return { opts, rest }
+}
+
+/** Which tool a command runs, with what arguments; throws the usage when it doesn't fit. */
+export function toolCall (sub, args) {
+  const { opts, rest } = options(args, ['glob', 'version', 'note'])
+  const [ws, a, b] = rest
+  const need = (n) => { if (rest.length < n) throw new Error(WORKSPACE_USAGE) }
+  switch (sub) {
+    case 'list': case 'ls': return ['quilt_workspaces', {}]
+    case 'files': need(1); return ['quilt_workspace_files', { workspace: ws, ...(a !== undefined ? { folder: a } : {}), ...(opts.glob ? { glob: opts.glob } : {}) }]
+    case 'get': case 'read': need(2); return ['quilt_workspace_read_file', { workspace: ws, path: a, ...(opts.version ? { version: Number(opts.version) } : {}) }]
+    case 'put': case 'upload': need(3); return ['quilt_workspace_write_file', { workspace: ws, path: a, fromPath: b, ...(opts.note ? { note: opts.note } : {}) }]
+    case 'write': need(3); return ['quilt_workspace_write_file', { workspace: ws, path: a, text: rest.slice(2).join(' '), ...(opts.note ? { note: opts.note } : {}) }]
+    case 'mkdir': need(2); return ['quilt_workspace_make_folder', { workspace: ws, path: a }]
+    case 'mv': case 'move': need(3); return ['quilt_workspace_move_file', { workspace: ws, path: a, to: b }]
+    case 'rm': case 'delete': need(2); return ['quilt_workspace_delete_file', { workspace: ws, path: a }]
+    case 'webhook': need(1); return ['quilt_workspace_webhook', { url: ws }]
+    case 'webhook-off': return ['quilt_workspace_webhook_off', {}]
+    default: throw new Error(WORKSPACE_USAGE)
+  }
+}
+
+/** Runs one command with `access` (localWorkspaceAccess): { ok, text }. */
+export async function runWorkspaceCommand (sub, args, access) {
+  const [name, input] = toolCall(sub, args)
+  const tools = new Map()
+  registerWorkspaceTools({ registerTool: (n, def, fn) => tools.set(n, fn) }, access)
+  const r = await tools.get(name)(input)
+  return { ok: !r.isError, text: r.content.map((c) => c.text).join('\n') }
+}