@owli/agent-sdk 0.1.0

package/src/storage/fileBackend.js

@@ -0,0 +1,152 @@
+// Default backend for real (non-test) use: a single AES-256-GCM-encrypted
+// JSON file on disk, not a database - zero setup, no native deps, works
+// anywhere Node runs. See backend.js for the interface this honors.
+//
+// Encryption key: either derived (PBKDF2) from a passphrase the caller
+// supplies, or - for genuinely zero-config bot use - a random key
+// generated once and stored in a sibling file with 0600 permissions next
+// to the data file. That sibling-key mode is NOT secret against anyone who
+// can already read files as the same OS user (or root) - same framing the
+// browser app's own storage-at-rest design already uses for its
+// device-local encryption: it protects against a stolen/copied data file
+// being useful on its own, not against a fully compromised machine.
+//
+// Writes go through a temp-file-then-rename atomic write - the one real
+// correctness risk a naive port of the browser's IndexedDB-backed design
+// would miss, since IndexedDB gives you that safety for free and a plain
+// fs.writeFile does not (a crash mid-write there would corrupt the file).
+import { webcrypto } from 'node:crypto';
+import { readFile, writeFile, rename, mkdir, chmod } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const { subtle } = webcrypto;
+// Not destructured off webcrypto like `subtle` above - getRandomValues is a
+// method that requires `this` to be the real Crypto object, so it has to
+// stay bound to webcrypto or every call throws ERR_INVALID_THIS.
+const getRandomValues = (arr) => webcrypto.getRandomValues(arr);
+const PBKDF2_ITERATIONS = 600000; // matches the browser app's own vault.js choice (OWASP 2023 guidance)
+
+function toB64(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}
+function fromB64(b64) {
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+async function deriveKey(passphrase, salt) {
+  const material = await subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+  return subtle.deriveKey(
+    { name: 'PBKDF2', salt, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt']
+  );
+}
+
+// Zero-config mode: a random key generated once, stored in its own 0600
+// file next to the data file. Not derived from a passphrase at all, since
+// there isn't one - this is the "just work with no setup" path.
+async function loadOrCreateLocalKey(keyPath) {
+  if (existsSync(keyPath)) {
+    return fromB64(readFileSync(keyPath, 'utf8').trim());
+  }
+  const raw = getRandomValues(new Uint8Array(32));
+  await mkdir(dirname(keyPath), { recursive: true });
+  await writeFile(keyPath, toB64(raw), { mode: 0o600 });
+  await chmod(keyPath, 0o600); // belt-and-suspenders in case the OS/umask ignored the mode above
+  return raw;
+}
+
+// path: where the encrypted data file lives. passphrase: optional - if
+// omitted, a local key file (see above) is used instead, next to `path`
+// with a `.key` suffix. pubkey: used to build a unique default filename
+// when `path` isn't given - without this, every agent run on the same
+// machine without an explicit path would fall back to the exact same
+// file (a real bug this parameter exists to close, not a hypothetical
+// one - see index.js's own comment on the collision it caused).
+export async function createFileBackend({ path, passphrase, pubkey } = {}) {
+  const filePath = path || join(homeDefault(), `${pubkey || 'default'}.json`);
+  await mkdir(dirname(filePath), { recursive: true });
+
+  let cachedKey = null;
+  async function getKey(saltForPassphrase) {
+    if (cachedKey) return cachedKey;
+    if (passphrase) {
+      cachedKey = await deriveKey(passphrase, saltForPassphrase);
+    } else {
+      const raw = await loadOrCreateLocalKey(`${filePath}.key`);
+      cachedKey = await subtle.importKey('raw', raw, 'AES-GCM', false, ['encrypt', 'decrypt']);
+    }
+    return cachedKey;
+  }
+
+  async function readAll() {
+    if (!existsSync(filePath)) return {};
+    let raw;
+    try {
+      raw = await readFile(filePath, 'utf8');
+    } catch {
+      return {};
+    }
+    if (!raw.trim()) return {};
+    const envelope = JSON.parse(raw);
+    const salt = fromB64(envelope.salt);
+    const key = await getKey(salt);
+    const plaintext = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(envelope.iv) }, key, fromB64(envelope.ct));
+    return JSON.parse(new TextDecoder().decode(plaintext));
+  }
+
+  async function writeAll(map) {
+    const salt = getRandomValues(new Uint8Array(16));
+    const iv = getRandomValues(new Uint8Array(12));
+    const key = await getKey(salt);
+    const ct = await subtle.encrypt({ name: 'AES-GCM', iv }, key, new TextEncoder().encode(JSON.stringify(map)));
+    const envelope = JSON.stringify({ v: 1, salt: toB64(salt), iv: toB64(iv), ct: toB64(ct) });
+    // Atomic write: write to a temp file in the same directory (so the
+    // rename is on the same filesystem), then rename over the real path -
+    // a crash mid-write leaves the old file intact, never a half-written one.
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmpPath, envelope);
+    await rename(tmpPath, filePath);
+  }
+
+  // Serialize concurrent writes within this process - two overlapping
+  // set() calls doing read-modify-write on the same file could otherwise
+  // clobber each other's changes.
+  let writeQueue = Promise.resolve();
+  function queueWrite(fn) {
+    writeQueue = writeQueue.then(fn, fn);
+    return writeQueue;
+  }
+
+  return {
+    async get(key) {
+      const all = await readAll();
+      return Object.prototype.hasOwnProperty.call(all, key) ? all[key] : null;
+    },
+    async set(key, value) {
+      return queueWrite(async () => {
+        const all = await readAll();
+        all[key] = value;
+        await writeAll(all);
+      });
+    },
+    async del(key) {
+      return queueWrite(async () => {
+        const all = await readAll();
+        delete all[key];
+        await writeAll(all);
+      });
+    },
+    async keys(prefix) {
+      const all = await readAll();
+      return Object.keys(all).filter((k) => k.startsWith(prefix));
+    },
+  };
+}
+
+function homeDefault() {
+  return join(process.env.HOME || process.env.USERPROFILE || '.', '.owli-agent');
+}

package/src/storage/memoryBackend.js

@@ -0,0 +1,25 @@
+// In-memory-only backend - a plain Map, no disk I/O at all. Default for
+// tests, and for any caller who explicitly wants a fully ephemeral agent
+// (a restart loses everything, including forward-secrecy state - the same
+// "start every contact's ratchet from scratch" tradeoff ratchet.js's own
+// comments already document as by-design for a fresh device, not a new
+// concept introduced here). See backend.js for the interface this honors.
+
+export function createMemoryBackend() {
+  const map = new Map();
+
+  return {
+    async get(key) {
+      return map.has(key) ? map.get(key) : null;
+    },
+    async set(key, value) {
+      map.set(key, value);
+    },
+    async del(key) {
+      map.delete(key);
+    },
+    async keys(prefix) {
+      return [...map.keys()].filter((k) => k.startsWith(prefix));
+    },
+  };
+}

package/src/storage.js

@@ -0,0 +1,71 @@
+// The storage.js that ratchet.js's `import * as storage from './storage.js'`
+// resolves to in this SDK. NOT a port of webapp/src/lib/storage.js (that
+// file is built directly on IndexedDB/localStorage, browser-only) - this is
+// a from-scratch implementation of exactly the interface ratchet.js
+// actually calls, confirmed directly against its source before writing
+// this: getContacts, getRatchetSession, setRatchetSession,
+// deleteRatchetSession, getOwnInvite, setOwnInvite - plus addContact/
+// removeContact for the SDK's own public API to manage the contact list
+// these functions need. Built on a pluggable backend (see storage/) so
+// swapping the default file-based store for something else later never
+// touches ratchet.js or this file's public shape.
+
+const CONTACTS_KEY = 'owl:contacts';
+const OWN_INVITE_KEY = 'owl:ratchet-own-invite';
+const ratchetSessionKey = (pubkey) => `owl:ratchet-session:${pubkey}`;
+
+let backend = null;
+
+// Called once by index.js when an OwliAgent is created, before anything
+// else touches this module - same "wire the real implementation in before
+// first use" pattern ratchet.js's own configure() already establishes for
+// getPool/getActiveRelays.
+export function configure(chosenBackend) {
+  backend = chosenBackend;
+}
+
+function requireBackend() {
+  if (!backend) throw new Error('storage.configure(backend) must be called before use - see OwliAgent.create()');
+  return backend;
+}
+
+export async function getContacts() {
+  const raw = await requireBackend().get(CONTACTS_KEY);
+  return raw ? JSON.parse(raw) : [];
+}
+
+export async function addContact(pubkey) {
+  const contacts = await getContacts();
+  if (contacts.some((c) => c.pubkey === pubkey)) return contacts;
+  const next = [...contacts, { pubkey, addedAt: Date.now() }];
+  await requireBackend().set(CONTACTS_KEY, JSON.stringify(next));
+  return next;
+}
+
+export async function removeContact(pubkey) {
+  const contacts = await getContacts();
+  const next = contacts.filter((c) => c.pubkey !== pubkey);
+  await requireBackend().set(CONTACTS_KEY, JSON.stringify(next));
+  await requireBackend().del(ratchetSessionKey(pubkey));
+  return next;
+}
+
+export async function getRatchetSession(pubkey) {
+  return (await requireBackend().get(ratchetSessionKey(pubkey))) || null;
+}
+
+export async function setRatchetSession(pubkey, serializedState) {
+  await requireBackend().set(ratchetSessionKey(pubkey), serializedState);
+}
+
+export async function deleteRatchetSession(pubkey) {
+  await requireBackend().del(ratchetSessionKey(pubkey));
+}
+
+export async function getOwnInvite() {
+  return (await requireBackend().get(OWN_INVITE_KEY)) || null;
+}
+
+export async function setOwnInvite(serializedInvite) {
+  await requireBackend().set(OWN_INVITE_KEY, serializedInvite);
+}

package/src/transport.js

@@ -0,0 +1,267 @@
+// Minimal rewrite of webapp/src/lib/nostr.js's relevant subset - the
+// send/receive orchestration that actually matters for messaging (relay
+// pool, ratchet-first-then-plain-fallback send, inbox subscription, catch-up
+// fetch), with settings passed in as a plain config object instead of
+// nostr.js's ~45 localStorage-backed getters, and every raw-key-only path
+// kept (no NIP-46 signer branches here yet - v1.1, see this SDK's README).
+// Text messages only for v1: no reactions/receipts/presence/group/trade/
+// profile/session-claim routing, since none of that is core to "an agent
+// sends and receives encrypted messages."
+import { SimplePool } from 'nostr-tools/pool';
+import { generateSecretKey, finalizeEvent } from 'nostr-tools/pure';
+import * as nip59 from 'nostr-tools/nip59';
+import * as nip44 from 'nostr-tools/nip44';
+import * as ratchet from './ratchet.js';
+
+export const DEFAULT_RELAYS = [
+  'wss://relay.damus.io',
+  'wss://nos.lol',
+  'wss://relay.nostr.band',
+  'wss://relay.primal.net',
+  'wss://nostr.wine',
+];
+
+const CHAT_KIND = 14;
+const DISAPPEAR_TAG = 'disappear';
+const TWO_DAYS_SECONDS = 2 * 24 * 60 * 60;
+// Matches the dashboard's own PRESENCE_KIND/PRESENCE_TTL_SECONDS exactly
+// (webapp/src/lib/nostr.js) - the dashboard already has everything needed
+// to receive and render this (Avatar.js's online dot, state.js's
+// isOnline 75s window), it's only ever been unused because no agent has
+// ever sent one. A one-way "I'm here" ping, gift-wrapped like a real
+// message but never through the ratchet transport - no session needed,
+// no reply expected, and a real timestamp doesn't matter given the short
+// TTL, so this deliberately skips trySend's session-bootstrap entirely.
+const PRESENCE_KIND = 10450;
+const PRESENCE_TTL_SECONDS = 90;
+// Matches the dashboard's own PROFILE_KIND exactly (webapp/src/lib/
+// nostr.js's sendProfile) - a plain gift-wrapped {name, emoji} rumor, no
+// ratchet session needed. Real gap this closes: a brand-new agent had no
+// way to tell a human (or another agent) who it is beyond a bare npub -
+// whoever added it saw a generic "Contact" placeholder forever, since
+// nothing on the agent's side ever sent a name. No photo support here
+// (unlike the dashboard's own sendProfile) - an agent has no avatar
+// image to send, only ever the name/emoji baked into its script.
+const PROFILE_KIND = 30079;
+
+function disappearAtFromTags(tags) {
+  const raw = tags.find((t) => t[0] === DISAPPEAR_TAG)?.[1];
+  const seconds = raw ? Number(raw) : NaN;
+  return Number.isFinite(seconds) ? seconds * 1000 : null;
+}
+
+function jitteredNow() {
+  // Matches nostr-tools' own randomNow() for the wrap timestamp -
+  // randomizes apparent send time within the past 2 days so relays can't
+  // use created_at to line up who was messaging whom, when.
+  return Math.round(Date.now() / 1000 - Math.random() * TWO_DAYS_SECONDS);
+}
+
+// Same rumor -> seal -> wrap shape as nip17.wrapEvent/nip59.wrapEvent, but
+// nostr-tools exposes no way to attach a tag to the outer gift-wrap event -
+// createWrap there hardcodes `tags: [["p", recipientPublicKey]]`. Relays
+// only ever see this outer event, so the expiration tag has to live here,
+// not on the inner rumor. Reuses nip59's own exported createRumor/createSeal
+// (identical crypto, no reimplementation) and only recreates the final wrap
+// step to add the tag.
+function wrapEventWithExpiry(event, senderSecretKey, recipientPublicKey, expirySeconds) {
+  const seal = nip59.createSeal(nip59.createRumor(event, senderSecretKey), senderSecretKey, recipientPublicKey);
+  const randomKey = generateSecretKey();
+  const conversationKey = nip44.getConversationKey(randomKey, recipientPublicKey);
+  const tags = [['p', recipientPublicKey]];
+  if (expirySeconds != null) {
+    tags.push(['expiration', String(Math.floor(Date.now() / 1000) + expirySeconds)]);
+  }
+  return finalizeEvent(
+    {
+      kind: 1059,
+      content: nip44.encrypt(JSON.stringify(seal), conversationKey),
+      created_at: jitteredNow(),
+      tags,
+    },
+    randomKey
+  );
+}
+
+// config: { relays?: string[], messageExpirySeconds?: number|null }
+export function createTransport({ relays = DEFAULT_RELAYS, messageExpirySeconds = null } = {}) {
+  let pool = null;
+  const getPool = () => (pool ??= new SimplePool());
+  const getActiveRelays = () => relays;
+
+  // Same wiring nostr.js does at module load - ratchet.js calls back into
+  // these two functions for its own publish/subscribe, never owns a pool
+  // itself.
+  ratchet.configure({ getPool, getActiveRelays });
+
+  // Every send to the same recipient runs through this - real bug found
+  // via a live agent whose CC of its own conversation would work for one
+  // turn, then silently vanish on the next: OwliAgent.ccToOwner fires
+  // twice per turn (once for the message it received, once for its own
+  // reply), both to the SAME ownerPubkey, both fire-and-forget, so they
+  // could genuinely be in flight at once. ratchet.js's trySend (kept
+  // byte-identical to the human webapp's copy, never edited here) reads
+  // its session object, mutates it, publishes, then persists - with real
+  // `await` gaps in between. Two concurrent calls for the same
+  // contactPubkey share that ONE in-memory session object; whichever
+  // call's persist() lands second in wall-clock time silently overwrites
+  // the other's, and a slower network round-trip can easily make that the
+  // FIRST call's write landing last - rolling the saved session back a
+  // step and corrupting what the ratchet protocol thinks comes next. This
+  // never showed up in the human dashboard, where a person sending one
+  // message at a time to the same contact essentially never overlaps like
+  // this - it took an automated script's own concurrent CC calls to
+  // surface it. Fixed at this layer (not inside ratchet.js itself, which
+  // stays untouched) by simply never letting two sends to the same
+  // recipient run concurrently at all.
+  const sendQueues = new Map();
+  function enqueue(recipientPubkey, task) {
+    const previous = sendQueues.get(recipientPubkey) || Promise.resolve();
+    const settled = previous.then(task, task);
+    // Always chain off a resolved promise, even when `task` rejected - a
+    // failed send must not permanently wedge every later send to this
+    // same recipient behind a dead queue entry.
+    sendQueues.set(recipientPubkey, settled.catch(() => {}));
+    return settled;
+  }
+
+  // The actual plain-NIP-17 send, never called directly by anything
+  // outside this module - always through the queued sendPlainMessage
+  // below, or as sendMessageInner's own fallback (already inside the
+  // queue's serialized slot at that point, so calling this directly
+  // there is correct, not a race).
+  async function sendPlainMessageInner(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec) {
+    const tags = [['p', recipientPubkey]];
+    if (disappearAfterSec) tags.push([DISAPPEAR_TAG, String(Math.floor(Date.now() / 1000) + disappearAfterSec)]);
+    const event = { kind: CHAT_KIND, created_at: Math.floor(Date.now() / 1000), tags, content: text };
+    const wrapped = wrapEventWithExpiry(event, secretKey, recipientPubkey, messageExpirySeconds);
+    await Promise.any(getPool().publish(getActiveRelays(), wrapped));
+    return wrapped;
+  }
+
+  // Plain NIP-17 only, no ratchet attempt - used as sendMessage's fallback
+  // and directly by callers who explicitly want no forward-secrecy attempt.
+  async function sendPlainMessage(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec) {
+    return enqueue(recipientPubkey, () => sendPlainMessageInner(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec));
+  }
+
+  async function sendPresencePing(secretKey, myPubkey, recipientPubkey) {
+    const event = { kind: PRESENCE_KIND, created_at: Math.floor(Date.now() / 1000), tags: [['p', recipientPubkey]], content: '' };
+    const wrapped = wrapEventWithExpiry(event, secretKey, recipientPubkey, PRESENCE_TTL_SECONDS);
+    await Promise.any(getPool().publish(getActiveRelays(), wrapped));
+  }
+
+  async function sendProfile(secretKey, recipientPubkey, profile) {
+    const event = {
+      kind: PROFILE_KIND,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: [],
+      content: JSON.stringify(profile),
+    };
+    const wrapped = wrapEventWithExpiry(event, secretKey, recipientPubkey, messageExpirySeconds);
+    await Promise.any(getPool().publish(getActiveRelays(), wrapped));
+    return wrapped;
+  }
+
+  // Tries the Double Ratchet transport first - forward secrecy, not just
+  // gift-wrap metadata protection. Falls back to plain NIP-17 automatically
+  // if the recipient hasn't published an invite yet (hasn't upgraded, or
+  // isn't currently reachable to discover one from) - no caller-visible
+  // difference either way. Calls sendPlainMessageInner directly, not the
+  // queued sendPlainMessage - this whole function only ever runs from
+  // inside enqueue()'s serialized slot (see sendMessage below), so
+  // routing back through the queue here would just wait on itself.
+  async function sendMessageInner(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec) {
+    const viaRatchet = await ratchet.trySend(secretKey, myPubkey, recipientPubkey, text, messageExpirySeconds, disappearAfterSec);
+    if (viaRatchet) return viaRatchet;
+    return sendPlainMessageInner(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec);
+  }
+
+  async function sendMessage(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec) {
+    return enqueue(recipientPubkey, () => sendMessageInner(secretKey, myPubkey, recipientPubkey, text, disappearAfterSec));
+  }
+
+  // Plain-NIP-17 inbox - the ratchet transport has its own separate
+  // subscription inside ratchet.js itself (started via startRatchetInbox
+  // below), so a message can arrive via either path and both need to be
+  // running for onMessage to see everything.
+  function subscribeInbox(secretKey, myPubkey, onMessage) {
+    const seen = new Set();
+    return getPool().subscribeMany(
+      getActiveRelays(),
+      { kinds: [1059], '#p': [myPubkey] },
+      {
+        onevent(event) {
+          if (seen.has(event.id)) return;
+          seen.add(event.id);
+          try {
+            const rumor = nip59.unwrapEvent(event, secretKey);
+            if (rumor.kind !== CHAT_KIND) return; // v1: text messages only
+            onMessage({
+              from: rumor.pubkey,
+              text: rumor.content,
+              createdAt: rumor.created_at,
+              eventId: event.id,
+              disappearAt: disappearAtFromTags(rumor.tags),
+            });
+          } catch {
+            // not decryptable to us (unrelated/relay noise) - ignore
+          }
+        },
+      }
+    );
+  }
+
+  // One-shot re-query for anything since a given time - covers what a dead
+  // socket would otherwise lose, same purpose as nostr.js's own fetchMissed.
+  async function fetchMissedPlain(secretKey, myPubkey, sinceSeconds) {
+    const filter = { kinds: [1059], '#p': [myPubkey] };
+    if (sinceSeconds) filter.since = sinceSeconds;
+    const events = await getPool().querySync(getActiveRelays(), filter);
+    const messages = [];
+    for (const event of events) {
+      try {
+        const rumor = nip59.unwrapEvent(event, secretKey);
+        if (rumor.kind !== CHAT_KIND) continue;
+        messages.push({
+          from: rumor.pubkey,
+          text: rumor.content,
+          createdAt: rumor.created_at,
+          eventId: event.id,
+          disappearAt: disappearAtFromTags(rumor.tags),
+        });
+      } catch {
+        // not ours / not decryptable - ignore
+      }
+    }
+    return messages;
+  }
+
+  async function fetchMissed(secretKey, myPubkey, sinceSeconds) {
+    const [plain, ratchetMissed] = await Promise.all([
+      fetchMissedPlain(secretKey, myPubkey, sinceSeconds),
+      ratchet.fetchMissed(sinceSeconds),
+    ]);
+    return [...plain, ...ratchetMissed].sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  function startRatchetInbox(secretKey, myPubkey, onMessage) {
+    return ratchet.start(secretKey, myPubkey, onMessage, null, null, null, null, null);
+  }
+
+  return {
+    getPool,
+    getActiveRelays,
+    sendMessage,
+    sendPlainMessage,
+    sendPresencePing,
+    sendProfile,
+    subscribeInbox,
+    fetchMissed,
+    startRatchetInbox,
+    stopRatchetInbox: ratchet.stop,
+    hasSession: ratchet.hasSession,
+    refreshInviteListen: ratchet.refreshInviteListen,
+    close: () => getPool().close(getActiveRelays()),
+  };
+}

package/src/websocket.js

@@ -0,0 +1,17 @@
+// nostr-tools' SimplePool reads a module-level WebSocket reference, set via
+// its own exported useWebSocketImplementation(impl) - confirmed directly
+// in its source (lib/esm/pool.js), called once before any SimplePool is
+// constructed. Node 22+ already has a global WebSocket (this becomes a
+// no-op there); older Node needs the `ws` package wired in through this
+// same call.
+import { useWebSocketImplementation } from 'nostr-tools/pool';
+
+let ensured = false;
+
+export async function ensureWebSocket() {
+  if (ensured) return;
+  ensured = true;
+  if (typeof globalThis.WebSocket !== 'undefined') return; // Node 22+, nothing to do
+  const { default: WebSocketImpl } = await import('ws');
+  useWebSocketImplementation(WebSocketImpl);
+}