@grknbyk/agent-wire 0.4.0 → 0.5.0

package/src/identity.mjs

@@ -1,73 +1,101 @@
-// Every agent in a workspace shares one bot token, so Slack's own bot_id proves
-// only "agent-wire posted this" — not which agent did. The header line is plain
-// text anyone in the channel can type, so it cannot carry identity either.
-// Each install therefore signs what it sends with its own Ed25519 key and
-// publishes the public half alongside the message. A nickname is bound to the
-// first key seen using it (trust on first use); a later message claiming that
-// nickname with a different key is reported, not believed.
-import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
-
-import { paths, readJson, writeJson } from './config.mjs';
-
-const DER_PRIVATE = { type: 'pkcs8', format: 'der' };
-const DER_PUBLIC = { type: 'spki', format: 'der' };
-
-export function generateKeypair() {
-    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
-    return {
-        privateKey: privateKey.export(DER_PRIVATE).toString('base64'),
-        publicKey: publicKey.export(DER_PUBLIC).toString('base64'),
-    };
-}
-
-// Signed over the fields a forger would want to change: who sent it, who it is
-// for, which channel it belongs to, and where it sits in a reply chain. Channel
-// is included so a signed message cannot be replayed into a different channel.
-export const signingPayload = ({ channel, from, to, conv, hop, text }) =>
-    Buffer.from(`agent-wire/v1\n${channel}\n${from}\n${to}\n${conv}\n${hop}\n${text}`, 'utf8');
-
-export function signMessage(privateKeyBase64, fields) {
-    const privateKey = createPrivateKey({ key: Buffer.from(privateKeyBase64, 'base64'), ...DER_PRIVATE });
-    return sign(null, signingPayload(fields), privateKey).toString('base64');
-}
-
-function verifySignature(publicKeyBase64, signature, fields) {
-    try {
-        const publicKey = createPublicKey({ key: Buffer.from(publicKeyBase64, 'base64'), ...DER_PUBLIC });
-        return verify(null, signingPayload(fields), publicKey, Buffer.from(signature, 'base64'));
-    } catch {
-        // A malformed key or signature is a failed verification, not a crash: the
-        // bytes came from a Slack message and anyone in the channel can shape them.
-        return false;
-    }
-}
-
-const loadPeers = () => readJson(paths.peers, {});
-
-// Verdicts, in the order they are decided:
-//   "signed"    — signature valid and the key matches the one pinned to this name
-//   "new"       — signature valid, first time this name appears, key now pinned
-//   "impostor"  — signature valid but the name is pinned to a DIFFERENT key
-//   "unsigned"  — no signature, or the signature does not verify
-export function checkAuthorship({ from, publicKey, signature, ...fields }) {
-    if (!publicKey || !signature) return { verdict: 'unsigned' };
-    if (!verifySignature(publicKey, signature, { from, ...fields })) return { verdict: 'unsigned' };
-
-    const peers = loadPeers();
-    const pinned = peers[from];
-    if (pinned && pinned.publicKey !== publicKey) return { verdict: 'impostor', pinnedSince: pinned.firstSeen };
-    if (pinned) return { verdict: 'signed' };
-
-    peers[from] = { publicKey, firstSeen: new Date().toISOString() };
-    writeJson(paths.peers, peers);
-    return { verdict: 'new' };
-}
-
-export const forgetPeer = (name) => {
-    const peers = loadPeers();
-    delete peers[name];
-    writeJson(paths.peers, peers);
-};
-
-export const listPeers = () => Object.entries(loadPeers())
-    .map(([name, peer]) => ({ name, firstSeen: peer.firstSeen, fingerprint: peer.publicKey.slice(0, 12) }));
+// Every agent in a workspace shares one bot token, so Slack's own bot_id proves
+// only "agent-wire posted this" — not which agent did. The header line is plain
+// text anyone in the channel can type, so it cannot carry identity either.
+// Each install therefore signs what it sends with its own Ed25519 key and
+// publishes the public half alongside the message. A nickname is bound to the
+// first key seen using it (trust on first use); a later message claiming that
+// nickname with a different key is reported, not believed.
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+
+import { paths, readJsonCached, writeJson } from './config.mjs';
+
+// A public key is 44 base64 characters. The prefix is what a human compares out
+// loud when two agents disagree about who somebody is, so it is one decision and
+// it is made once rather than at each of the four places that print it.
+export const FINGERPRINT_CHARS = 12;
+
+const DER_PRIVATE = { type: 'pkcs8', format: 'der' };
+const DER_PUBLIC = { type: 'spki', format: 'der' };
+
+// Parsing DER into a key object costs more than the Ed25519 check that follows
+// it, and one poll verifies a page of messages against the same handful of keys.
+// The object is derived from the bytes alone, so keying the cache on those bytes
+// verifies exactly what it verified before.
+//
+// ponytail: bounded by clearing, not by evicting the oldest. The keys come out of
+// a Slack channel, so an unbounded map is somebody else's memory budget; an LRU
+// would be the upgrade if a workspace ever holds more agents than this.
+const KEY_CACHE_MAX = 512;
+const keyObjects = new Map();
+
+function cachedKey(material, build) {
+    const cached = keyObjects.get(material);
+    if (cached) return cached;
+
+    if (keyObjects.size >= KEY_CACHE_MAX) keyObjects.clear();
+    const key = build();
+    keyObjects.set(material, key);
+    return key;
+}
+
+export function generateKeypair() {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    return {
+        privateKey: privateKey.export(DER_PRIVATE).toString('base64'),
+        publicKey: publicKey.export(DER_PUBLIC).toString('base64'),
+    };
+}
+
+// Signed over the fields a forger would want to change: who sent it, who it is
+// for, which channel it belongs to, where it sits in a reply chain, and which
+// file it points at. Channel is included so a signed message cannot be replayed
+// into a different channel; file is included so a valid signature cannot be
+// re-attached to somebody else's upload.
+export const signingPayload = ({ channel, from, to, conv, hop, file = '', text }) =>
+    Buffer.from(`agent-wire/v2\n${channel}\n${from}\n${to}\n${conv}\n${hop}\n${file}\n${text}`, 'utf8');
+
+export function signMessage(privateKeyBase64, fields) {
+    const privateKey = cachedKey(privateKeyBase64, () => createPrivateKey({ key: Buffer.from(privateKeyBase64, 'base64'), ...DER_PRIVATE }));
+    return sign(null, signingPayload(fields), privateKey).toString('base64');
+}
+
+function verifySignature(publicKeyBase64, signature, fields) {
+    try {
+        const publicKey = cachedKey(publicKeyBase64, () => createPublicKey({ key: Buffer.from(publicKeyBase64, 'base64'), ...DER_PUBLIC }));
+        return verify(null, signingPayload(fields), publicKey, Buffer.from(signature, 'base64'));
+    } catch {
+        // A malformed key or signature is a failed verification, not a crash: the
+        // bytes came from a Slack message and anyone in the channel can shape them.
+        return false;
+    }
+}
+
+const loadPeers = () => readJsonCached(paths.peers, {});
+
+// Verdicts, in the order they are decided:
+//   "signed"    — signature valid and the key matches the one pinned to this name
+//   "new"       — signature valid, first time this name appears, key now pinned
+//   "impostor"  — signature valid but the name is pinned to a DIFFERENT key
+//   "unsigned"  — no signature, or the signature does not verify
+export function checkAuthorship({ from, publicKey, signature, ...fields }) {
+    if (!publicKey || !signature) return { verdict: 'unsigned' };
+    if (!verifySignature(publicKey, signature, { from, ...fields })) return { verdict: 'unsigned' };
+
+    const peers = loadPeers();
+    const pinned = peers[from];
+    if (pinned && pinned.publicKey !== publicKey) return { verdict: 'impostor', pinnedSince: pinned.firstSeen };
+    if (pinned) return { verdict: 'signed' };
+
+    peers[from] = { publicKey, firstSeen: new Date().toISOString() };
+    writeJson(paths.peers, peers);
+    return { verdict: 'new' };
+}
+
+export const forgetPeer = (name) => {
+    const peers = loadPeers();
+    delete peers[name];
+    writeJson(paths.peers, peers);
+};
+
+export const listPeers = () => Object.entries(loadPeers())
+    .map(([name, peer]) => ({ name, firstSeen: peer.firstSeen, fingerprint: peer.publicKey.slice(0, FINGERPRINT_CHARS) }));

package/src/inbox.mjs

@@ -1,76 +1,99 @@
-// The local log is the source of truth, not the Slack channel. Slack history is a
-// cache we can re-read at any time, so a full re-scan is an ordinary idempotent
-// operation rather than a recovery procedure.
-//
-// inbox.jsonl is append-only and keyed by the Slack timestamp, which is unique per
-// channel and survives a re-install. Message state lives in a separate file so the
-// append-only log never has to be rewritten in place.
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
-
-import { HOME, paths, readJson, writeJson } from './config.mjs';
-
-const storageKey = (item) => `${item.channel}:${item.ts}`;
-
-export function readInbox() {
-    if (!existsSync(paths.inbox)) return [];
-    return readFileSync(paths.inbox, 'utf8').split('\n').filter(Boolean)
-        .map((line) => { try { return JSON.parse(line); } catch { return null; } })
-        .filter(Boolean);
-}
-
-export const stateOf = (states, item) => states[storageKey(item)] ?? 'unread';
-
-// The Slack timestamp is the idempotency key: a retried poll, an overlapping
-// window, or a re-installed app all replay the same ts, and a duplicate the human
-// has to clean up by hand is the failure that generates support noise.
-export function appendMessages(items) {
-    if (items.length === 0) return 0;
-
-    const seen = new Set(readInbox().map(storageKey));
-    const fresh = items.filter((item) => !seen.has(storageKey(item)));
-    if (fresh.length === 0) return 0;
-
-    mkdirSync(HOME, { recursive: true });
-    appendFileSync(paths.inbox, fresh.map((item) => JSON.stringify(item)).join('\n') + '\n');
-    return fresh.length;
-}
-
-// `channel` names one channel explicitly and overrides everything. `channels`
-// is the caller's allow-list, which is how switched-off channels stay out of the
-// default view without being deleted from the log.
-export function selectMessages({ state = 'unread', count = 20, channel = null, channels = null } = {}) {
-    const states = readJson(paths.states, {});
-    const visible = readInbox().filter((item) => {
-        if (channel) return item.channel === channel;
-        if (channels) return channels.includes(item.channel);
-        return true;
-    });
-    const wanted = state === 'all' ? visible : visible.filter((item) => stateOf(states, item) === state);
-    return wanted.slice(-count);
-}
-
-export function markRead(items) {
-    const states = readJson(paths.states, {});
-    for (const item of items) states[storageKey(item)] = 'read';
-    writeJson(paths.states, states);
-}
-
-export function archive(ts) {
-    const states = readJson(paths.states, {});
-    const targets = ts
-        ? readInbox().filter((item) => item.ts === ts)
-        : readInbox().filter((item) => stateOf(states, item) === 'read');
-    for (const item of targets) states[storageKey(item)] = 'archived';
-    writeJson(paths.states, states);
-    return targets.length;
-}
-
-export const findByTs = (ts) => readInbox().find((item) => item.ts === ts) ?? null;
-
-export const readCursor = (channelId) => readJson(paths.cursors, {})[channelId] ?? null;
-
-export function writeCursor(channelId, ts) {
-    const cursors = readJson(paths.cursors, {});
-    cursors[channelId] = ts;
-    writeJson(paths.cursors, cursors);
-}
+// The local log is the source of truth, not the Slack channel. Slack history is a
+// cache we can re-read at any time, so a full re-scan is an ordinary idempotent
+// operation rather than a recovery procedure.
+//
+// inbox.jsonl is append-only and keyed by the Slack timestamp, which is unique per
+// channel and survives a re-install. Message state lives in a separate file so the
+// append-only log never has to be rewritten in place.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+
+import { HOME, derivedFromFile, paths, readJsonCached, writeJson } from './config.mjs';
+
+// Enough to catch up on a conversation, short enough not to bury the session that
+// asked. A caller that wants the whole log passes its own count.
+const DEFAULT_COUNT = 20;
+
+const storageKey = (item) => `${item.channel}:${item.ts}`;
+
+// Parsed at most once per write. Four call sites read the whole log — select,
+// append, archive, findByTs — and a poll runs several of them back to back, so
+// without this a 20k-message log is parsed four times to answer one question.
+export function readInbox() {
+    if (!existsSync(paths.inbox)) return [];
+    return derivedFromFile(paths.inbox, 'parsed', () => readFileSync(paths.inbox, 'utf8')
+        .split('\n').filter(Boolean)
+        .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+        .filter(Boolean));
+}
+
+// The dedup check is a lookup, so it is stored as one. Rebuilding a 20k-entry Set
+// per appended message is the whole cost of appending a message.
+const inboxKeys = () => derivedFromFile(paths.inbox, 'keys', () => new Set(readInbox().map(storageKey)));
+
+export const stateOf = (states, item) => states[storageKey(item)] ?? 'unread';
+
+// The Slack timestamp is the idempotency key: a retried poll, an overlapping
+// window, or a re-installed app all replay the same ts, and a duplicate the human
+// has to clean up by hand is the failure that generates support noise.
+export function appendMessages(items) {
+    if (items.length === 0) return 0;
+
+    const seen = inboxKeys();
+    const fresh = items.filter((item) => !seen.has(storageKey(item)));
+    if (fresh.length === 0) return 0;
+
+    mkdirSync(HOME, { recursive: true });
+    appendFileSync(paths.inbox, fresh.map((item) => JSON.stringify(item)).join('\n') + '\n');
+    return fresh.length;
+}
+
+// `channel` names one channel explicitly and overrides everything. `channels`
+// is the caller's allow-list, which is how switched-off channels stay out of the
+// default view without being deleted from the log.
+export function selectMessages({ state = 'unread', count = DEFAULT_COUNT, channel = null, channels = null } = {}) {
+    const states = readJsonCached(paths.states, {});
+    const isVisible = (item) => {
+        if (channel) return item.channel === channel;
+        if (channels) return channels.includes(item.channel);
+        return true;
+    };
+
+    // Scanned from the newest end and stopped at `count`. Filtering the whole log
+    // to keep the last twenty of it was most of what reading an inbox cost, and
+    // the log only grows.
+    const log = readInbox();
+    const picked = [];
+    for (let index = log.length - 1; index >= 0 && picked.length < count; index--) {
+        const item = log[index];
+        if (!isVisible(item)) continue;
+        if (state !== 'all' && stateOf(states, item) !== state) continue;
+        picked.push(item);
+    }
+    return picked.reverse();
+}
+
+export function markRead(items) {
+    const states = readJsonCached(paths.states, {});
+    for (const item of items) states[storageKey(item)] = 'read';
+    writeJson(paths.states, states);
+}
+
+export function archive(ts) {
+    const states = readJsonCached(paths.states, {});
+    const targets = ts
+        ? readInbox().filter((item) => item.ts === ts)
+        : readInbox().filter((item) => stateOf(states, item) === 'read');
+    for (const item of targets) states[storageKey(item)] = 'archived';
+    writeJson(paths.states, states);
+    return targets.length;
+}
+
+export const findByTs = (ts) => readInbox().find((item) => item.ts === ts) ?? null;
+
+export const readCursor = (channelId) => readJsonCached(paths.cursors, {})[channelId] ?? null;
+
+export function writeCursor(channelId, ts) {
+    const cursors = readJsonCached(paths.cursors, {});
+    cursors[channelId] = ts;
+    writeJson(paths.cursors, cursors);
+}