@owli/agent-sdk 0.1.0

package/src/ratchet.js

@@ -0,0 +1,505 @@
+// Copied verbatim from webapp/src/lib/ratchet.js (2026-08-28) - zero edits.
+// Its only environment coupling is the injected storage module (this SDK's
+// own src/storage.js, built to satisfy the exact 6-function interface this
+// file calls) and the configure({getPool, getActiveRelays}) call (wired
+// from src/transport.js) - both already parameterized in the original, not
+// hardcoded, which is exactly why this file needed no changes to run in
+// Node. Diff against webapp/src/lib/ratchet.js before any protocol change
+// ships on either side - see this SDK's README.
+
+// Double Ratchet (NIP-104-shaped) transport, layered underneath the
+// existing NIP-17 messaging in nostr.js - see architecture-v1_1.md §5a.
+// Attempted automatically for every contact; falls back to plain NIP-17
+// if the other side hasn't published an invite (hasn't upgraded yet, or
+// hasn't been online since upgrading). Verified against live relays in
+// spike/ratchet-roundtrip.mjs and spike/ratchet-owl-pattern.mjs before
+// any of this was written - this module carries that verified shape
+// forward, not a fresh, unverified design.
+//
+// No handshake-ping here (see spike/ratchet-owl-pattern.mjs's Fix 1):
+// that was needed only because the spike tested "accept" and "send the
+// first real message" as separate steps. Here, whichever contact sends
+// first is the one who discovers and accepts the other's invite, and
+// their real message *is* the unlocking event - sent immediately after
+// accepting, with no gap for a separate ping to fill.
+
+import { finalizeEvent } from 'nostr-tools/pure';
+import {
+  Invite,
+  Session,
+  buildTextRumor,
+  serializeSessionState,
+  deserializeSessionState,
+  MESSAGE_EVENT_KIND,
+  GROUP_METADATA_KIND,
+  GROUP_SENDER_KEY_DISTRIBUTION_KIND,
+  GROUP_INVITE_RUMOR_KIND,
+  RECEIPT_KIND,
+} from 'nostr-double-ratchet';
+import * as storage from './storage.js';
+import * as signerLib from './signer.js';
+
+// A signer-backed identity is threaded through every function below the
+// exact same way a raw secretKey Uint8Array always has been - as
+// { signer: BunkerSignerInstance } instead - so every function that just
+// passes secretKey along on its way to one of the three real touch points
+// below needs zero changes at all. Only those three actually branch on
+// which shape they were given. Exported so nostr.js/zap.js/blossom.js
+// reuse this exact check for their own raw-key touch points instead of
+// each re-deriving the same { signer } shape test independently.
+export function isSignerBacked(secretKey) {
+  return !!(secretKey && typeof secretKey === 'object' && secretKey.signer);
+}
+
+const INVITE_DISCOVERY_TIMEOUT_MS = 4000;
+
+// Group chat (architecture-v1_1.md §5b) rides on top of these same
+// pairwise sessions - GroupManager distributes sender keys and roster/
+// metadata updates via ordinary rumors sent through them, confirmed
+// directly against real traffic in spike/group-roundtrip.mjs. Anything
+// arriving with one of these kinds gets routed to the group layer
+// instead of treated as chat text.
+const GROUP_RUMOR_KINDS = new Set([GROUP_METADATA_KIND, GROUP_SENDER_KEY_DISTRIBUTION_KIND, GROUP_INVITE_RUMOR_KIND]);
+
+// Trade requests (architecture-v1_1.md §5d) - not a library kind, Owl's
+// own, verified unused against the installed nostr-double-ratchet package
+// and Owl's other custom kinds before picking it (full taken-kind list in
+// §5d). Same shape as the group kinds above: one rumor kind, routed away
+// from chat text to its own handler, with every action (propose/accept/
+// decline/etc.) distinguished by a `content.action` field rather than a
+// kind per action - matching how group metadata already reuses one kind
+// for name/emoji/founder updates.
+const TRADE_REQUEST_KIND = 10449;
+
+// A reaction to a message - matches nostr.js's own REACTION_KIND constant
+// (each transport file defines its own copy of every custom kind it needs,
+// the same convention TRADE_REQUEST_KIND above already follows).
+const REACTION_KIND = 16;
+
+// Disappearing messages (architecture-v1_1.md §5e) - a tag on the inner
+// rumor, not a kind, matching this. Owl's own, distinct from the
+// library's EXPIRATION_TAG ("expiration"), which the Message Expiry line
+// above already puts on this same inner rumor for a different purpose
+// (relay-side NIP-40 pruning). Value is a Unix-seconds timestamp, same
+// format as EXPIRATION_TAG's, computed at send time.
+const DISAPPEAR_TAG = 'disappear';
+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;
+}
+
+let pool = null;
+let relaysFn = null;
+
+// Wired from nostr.js at module load (see the bottom of this file's
+// import in nostr.js) rather than importing nostr.js directly here, to
+// avoid a circular import (nostr.js's sendMessage calls into this module).
+export function configure({ getPool, getActiveRelays }) {
+  pool = getPool;
+  relaysFn = getActiveRelays;
+}
+
+function publish(event) {
+  return Promise.any(pool().publish(relaysFn(), event));
+}
+
+function ratchetSubscribe(filter, onEvent) {
+  const sub = pool().subscribeMany(relaysFn(), filter, { onevent: onEvent });
+  return () => sub.close();
+}
+
+// In-memory only: rehydrated from storage.js on demand. Never derived from
+// anything the recovery phrase alone could reconstruct - restoring a fresh
+// device via phrase starts every contact's ratchet from scratch, by
+// design (§5a).
+const sessions = new Map(); // contactPubkey -> Session
+let onMessageCallback = null;
+let onNewSessionCallback = null;
+let onGroupRumorCallback = null;
+let onTradeRumorCallback = null;
+let onReactionCallback = null;
+let onReceiptCallback = null;
+let ownInviteListenUnsub = null;
+let msgSubUnsub = null;
+let msgSubAuthorsKey = null;
+
+// Stored as an envelope, not just the raw serialized state: `sourceEventId`
+// carries the invite-response event that produced this session (only set
+// on the inbound/listen path - see the library's Invite.listen, which
+// passes `name: event.id` into Session.init and Session.init assigns it
+// to session.name). Lets a later inbound session be compared against this
+// one by *which event created it*, not just "does a session exist" - see
+// start()'s listen callback for why that distinction matters.
+async function persist(contactPubkey, session) {
+  await storage.setRatchetSession(contactPubkey, JSON.stringify({
+    state: serializeSessionState(session.state),
+    sourceEventId: session.name,
+  }));
+}
+
+async function loadSession(contactPubkey) {
+  if (sessions.has(contactPubkey)) return sessions.get(contactPubkey);
+  const saved = await storage.getRatchetSession(contactPubkey);
+  if (!saved) return null;
+  try {
+    const envelope = JSON.parse(saved);
+    const session = new Session(deserializeSessionState(envelope.state));
+    session.name = envelope.sourceEventId;
+    sessions.set(contactPubkey, session);
+    return session;
+  } catch {
+    // corrupted/incompatible stored state - drop it and start fresh next
+    // time this contact is messaged, rather than blocking on it forever
+    await storage.deleteRatchetSession(contactPubkey);
+    return null;
+  }
+}
+
+// UI-facing: does this contact have an established ratchet session, or
+// would sendMessage currently fall back to plain NIP-17 (no forward
+// secrecy)? Reuses loadSession's own cache/storage lookup rather than a
+// separate check, so this never disagrees with what trySend would actually
+// do for the same contact.
+export async function hasSession(contactPubkey) {
+  return !!(await loadSession(contactPubkey));
+}
+
+async function getOrCreateOwnInvite(myPubkey) {
+  const saved = await storage.getOwnInvite();
+  if (saved) {
+    try {
+      return Invite.deserialize(saved);
+    } catch {
+      // corrupted - fall through and create a fresh one
+    }
+  }
+  const invite = Invite.createNew(myPubkey, 'owl-device');
+  await storage.setOwnInvite(invite.serialize());
+  return invite;
+}
+
+// Publishes (or republishes - same `d` tag, so relays just replace the
+// existing copy) this device's own invite, so contacts can discover and
+// message this identity first. Same "once per unlock" pattern already
+// used for profile broadcast elsewhere in this codebase.
+async function publishOwnInvite(secretKey, myPubkey) {
+  const invite = await getOrCreateOwnInvite(myPubkey);
+  // finalizeEvent needs a raw key and has no callback form - a signer's
+  // signEvent already returns a complete, signed event on its own, so it
+  // replaces finalizeEvent entirely rather than feeding into it.
+  const signedEvent = isSignerBacked(secretKey)
+    ? await signerLib.signEventWithSigner(secretKey.signer, invite.getEvent())
+    : finalizeEvent(invite.getEvent(), secretKey);
+  await publish(signedEvent);
+  return invite;
+}
+
+function knownAuthors() {
+  const authors = new Set();
+  for (const session of sessions.values()) {
+    const s = session.state;
+    if (s.theirCurrentNostrPublicKey) authors.add(s.theirCurrentNostrPublicKey);
+    if (s.theirNextNostrPublicKey) authors.add(s.theirNextNostrPublicKey);
+    for (const pubkey of Object.keys(s.skippedKeys || {})) authors.add(pubkey);
+  }
+  return [...authors];
+}
+
+// One shared subscription across every active session, narrowed to just
+// the pubkeys any session could currently receive from - re-subscribed
+// whenever a DH ratchet step changes that set. See spike/
+// ratchet-owl-pattern.mjs's NarrowedInbox for why this matters: a broad
+// `{kinds:[MESSAGE_EVENT_KIND]}` filter has to try every event on a busy
+// public relay, which measured up to 45s of unrelated background traffic
+// in testing.
+function refreshMessageSubscription() {
+  const authors = knownAuthors();
+  const authorsKey = authors.slice().sort().join(',');
+  if (authorsKey === msgSubAuthorsKey) return;
+  msgSubAuthorsKey = authorsKey;
+  if (msgSubUnsub) msgSubUnsub();
+  if (!authors.length) return;
+  msgSubUnsub = ratchetSubscribe({ kinds: [MESSAGE_EVENT_KIND], authors }, (event) => {
+    for (const [contactPubkey, session] of sessions) {
+      try {
+        const rumor = session.receiveEvent(event);
+        if (!rumor) continue;
+        persist(contactPubkey, session).catch(() => {});
+        refreshMessageSubscription();
+        if (GROUP_RUMOR_KINDS.has(rumor.kind)) {
+          if (onGroupRumorCallback) onGroupRumorCallback(rumor, contactPubkey);
+          return;
+        }
+        if (rumor.kind === TRADE_REQUEST_KIND) {
+          if (onTradeRumorCallback) onTradeRumorCallback(rumor, contactPubkey);
+          return;
+        }
+        if (rumor.kind === REACTION_KIND) {
+          const targetEventId = rumor.tags.find((t) => t[0] === 'e')?.[1];
+          if (targetEventId && onReactionCallback) onReactionCallback({ from: contactPubkey, targetEventId, emoji: rumor.content });
+          return;
+        }
+        if (rumor.kind === RECEIPT_KIND) {
+          if (onReceiptCallback) {
+            try {
+              const payload = JSON.parse(rumor.content);
+              onReceiptCallback({ from: contactPubkey, type: payload.type, messageIds: payload.messageIds || [] });
+            } catch {
+              // malformed receipt payload - drop it, not a chat message either
+            }
+          }
+          return;
+        }
+        if (onMessageCallback) {
+          onMessageCallback({
+            from: contactPubkey,
+            text: rumor.content,
+            createdAt: rumor.created_at,
+            eventId: event.id,
+            disappearAt: disappearAtFromTags(rumor.tags),
+          });
+        }
+        return;
+      } catch {
+        // not this session's event - try the next registered session
+      }
+    }
+  });
+}
+
+// Manual catch-up, mirroring nostr.js's fetchMissed for the NIP-17 path:
+// the live subscription in refreshMessageSubscription can silently die
+// (sleep, network drop, relay hiccup) exactly like the NIP-17 one can, so
+// this exists as the same belt-and-suspenders "Resync" button covers both
+// transports uniformly, rather than only ever fixing NIP-17.
+//
+// Deliberately narrow: only queries for currently-known session authors
+// (same set refreshMessageSubscription filters live delivery to), so it
+// can't discover a session that was never established while this device
+// was closed - if that happens, the sender's next message after this
+// device reopens still delivers live and bootstraps normally; there's no
+// gap in eventual delivery, only in exactly when this specific query can
+// see it. Doesn't re-run invite discovery/bootstrap - only catches up
+// messages on sessions that already exist.
+export async function fetchMissed(sinceSeconds) {
+  const authors = knownAuthors();
+  if (!authors.length) return [];
+  const filter = { kinds: [MESSAGE_EVENT_KIND], authors };
+  if (sinceSeconds) filter.since = sinceSeconds;
+  const events = await pool().querySync(relaysFn(), filter);
+  events.sort((a, b) => a.created_at - b.created_at);
+
+  const missed = [];
+  for (const event of events) {
+    for (const [contactPubkey, session] of sessions) {
+      try {
+        const rumor = session.receiveEvent(event);
+        if (!rumor) continue;
+        await persist(contactPubkey, session);
+        if (GROUP_RUMOR_KINDS.has(rumor.kind)) {
+          if (onGroupRumorCallback) await onGroupRumorCallback(rumor, contactPubkey);
+        } else if (rumor.kind === TRADE_REQUEST_KIND) {
+          if (onTradeRumorCallback) await onTradeRumorCallback(rumor, contactPubkey);
+        } else if (rumor.kind === REACTION_KIND) {
+          const targetEventId = rumor.tags.find((t) => t[0] === 'e')?.[1];
+          if (targetEventId && onReactionCallback) await onReactionCallback({ from: contactPubkey, targetEventId, emoji: rumor.content });
+        } else if (rumor.kind === RECEIPT_KIND) {
+          if (onReceiptCallback) {
+            try {
+              const payload = JSON.parse(rumor.content);
+              await onReceiptCallback({ from: contactPubkey, type: payload.type, messageIds: payload.messageIds || [] });
+            } catch {
+              // malformed receipt payload - drop it
+            }
+          }
+        } else {
+          missed.push({
+            from: contactPubkey,
+            text: rumor.content,
+            createdAt: rumor.created_at,
+            eventId: event.id,
+            disappearAt: disappearAtFromTags(rumor.tags),
+          });
+        }
+        break;
+      } catch {
+        // not this session's event - try the next registered session
+      }
+    }
+  }
+  refreshMessageSubscription();
+  return missed;
+}
+
+// Discovers a contact's published invite and accepts it, becoming the
+// ratchet's sender so a real message can go out immediately after. Times
+// out and returns null (caller falls back to plain NIP-17) if the contact
+// hasn't published an invite - not upgraded yet, or hasn't been online
+// since upgrading.
+async function bootstrapOutbound(secretKey, myPubkey, contactPubkey) {
+  const theirInvite = await Invite.waitFor(contactPubkey, ratchetSubscribe, INVITE_DISCOVERY_TIMEOUT_MS);
+  if (!theirInvite) return null;
+  // accept() natively takes a raw key OR an encrypt callback (its own
+  // type signature already supports this) - a signer's nip44Encrypt does
+  // the same DH(inviter, invitee) + NIP-44 encrypt the doc comment on
+  // accept() describes, just performed remotely instead of locally.
+  const encryptor = isSignerBacked(secretKey) ? signerLib.encryptorFor(secretKey.signer) : secretKey;
+  const { session, event } = await theirInvite.accept(myPubkey, encryptor);
+  await publish(event);
+  sessions.set(contactPubkey, session);
+  await persist(contactPubkey, session);
+  refreshMessageSubscription();
+  if (onNewSessionCallback) onNewSessionCallback(contactPubkey);
+  return session;
+}
+
+async function getOrBootstrapSession(secretKey, myPubkey, contactPubkey) {
+  const existing = await loadSession(contactPubkey);
+  if (existing) {
+    refreshMessageSubscription();
+    return existing;
+  }
+  return bootstrapOutbound(secretKey, myPubkey, contactPubkey);
+}
+
+// Returns the published event on success via the ratchet, or null if no
+// session could be established (contact hasn't upgraded / isn't
+// reachable right now) - callers fall back to nip17.wrapEvent in that case.
+// expirySeconds (from nostr.js's getMessageExpirySeconds) is passed straight
+// through to the library's own NIP-40 expiration handling - null/undefined
+// means no expiration tag at all, matching "Never" in Settings.
+export async function trySend(secretKey, myPubkey, contactPubkey, text, expirySeconds, disappearAfterSec) {
+  const session = await getOrBootstrapSession(secretKey, myPubkey, contactPubkey);
+  if (!session) return null;
+  const rumorOptions = expirySeconds != null ? { expiration: { ttlSeconds: expirySeconds } } : {};
+  // Deliberately its own tag, not the library's EXPIRATION_TAG above - that
+  // one's already spoken for by the ratchet-path Message Expiry line just
+  // above (a relay-side NIP-40 hint), and the two would silently collide
+  // on the same inner rumor if this reused it.
+  if (disappearAfterSec) rumorOptions.tags = [[DISAPPEAR_TAG, String(Math.floor(Date.now() / 1000) + disappearAfterSec)]];
+  const { event } = session.sendEvent(buildTextRumor(text, rumorOptions));
+  await publish(event);
+  await persist(contactPubkey, session);
+  return event;
+}
+
+// Group chat's sendPairwise (architecture-v1_1.md §5b): sends an
+// arbitrary pre-built rumor (roster/metadata updates, sender-key
+// distributions) through the same pairwise session as regular messages,
+// bootstrapping it first if needed. No NIP-17 fallback here, unlike
+// trySend - these are Owl's own ratchet-specific protocol messages, not
+// user-facing chat content with an equivalent plain-NIP-17 shape to fall
+// back to. Throws if no session could be established, so group.js's
+// sendPairwise implementation surfaces that as a real failure rather than
+// silently dropping the distribution.
+export async function sendRumorPairwise(secretKey, myPubkey, contactPubkey, rumor) {
+  const session = await getOrBootstrapSession(secretKey, myPubkey, contactPubkey);
+  if (!session) throw new Error(`no ratchet session with ${contactPubkey} and none could be bootstrapped`);
+  const { event } = session.sendEvent(rumor);
+  await publish(event);
+  await persist(contactPubkey, session);
+  return event;
+}
+
+// Non-throwing variant of the above, for callers with their own plain-
+// NIP-17 fallback (reactions, same as sendMessage/trySend) rather than
+// ratchet-only protocol traffic - returns null instead of throwing so the
+// caller can fall through to that fallback, matching trySend's shape.
+export async function trySendRumorPairwise(secretKey, myPubkey, contactPubkey, rumor) {
+  const session = await getOrBootstrapSession(secretKey, myPubkey, contactPubkey);
+  if (!session) return null;
+  const { event } = session.sendEvent(rumor);
+  await publish(event);
+  await persist(contactPubkey, session);
+  return event;
+}
+
+// The invite-listen half of start() - pulled out so it can also be
+// re-run on demand to recover from a live subscription that's gone
+// stale without anyone noticing (a real risk for an agent meant to run
+// for days/weeks unattended). Invite.listen()'s own subscription is just
+// a relay REQ under the hood (via ratchetSubscribe), and a fresh REQ
+// gets matching events a relay still has stored replayed back
+// immediately, not just future ones - so simply re-subscribing recovers
+// any accept-response that arrived while the old listener wasn't
+// actually delivering anymore. This is the ONLY way a brand-new incoming
+// session can ever be discovered after the fact at all: unlike regular
+// ratchet messages (kind 1060, no plaintext tag), the accept-response
+// event IS tagged with the invite's own ephemeral pubkey, so it's the
+// one part of this protocol a stale listener can actually recover from
+// without live delivery. Exported so a long-running caller (a script
+// using OwliAgent for days at a time) can call this periodically as
+// cheap insurance, not just once at startup.
+export async function refreshInviteListen(secretKey, myPubkey) {
+  const invite = await publishOwnInvite(secretKey, myPubkey);
+  if (ownInviteListenUnsub) ownInviteListenUnsub();
+  // Mirror of accept()'s encryptor above - listen() takes a raw key or a
+  // decrypt callback natively; a signer's nip44Decrypt does the same
+  // DH-based decrypt remotely.
+  const decryptor = isSignerBacked(secretKey) ? signerLib.decryptorFor(secretKey.signer) : secretKey;
+  ownInviteListenUnsub = invite.listen(decryptor, ratchetSubscribe, async (session, contactPubkey) => {
+    // Our own invite is long-lived and reused across unlocks (by design,
+    // so it stays discoverable at a stable identity), so the SAME
+    // accept-response event a contact published when they first messaged
+    // us is still sitting on relays and gets redelivered every time this
+    // listener starts fresh - Invite.listen's own dedup is per-instance/
+    // in-memory and doesn't survive a reload. Compare by *which event*
+    // produced each session (session.name === the causing event.id, set
+    // internally by Invite.listen), not just "do we have any session for
+    // this contact": identical event.id means a genuine replay of one
+    // we've already processed (skip it); a different event.id means the
+    // contact published a fresh accept-response - a real, legitimate
+    // re-bootstrap (e.g. they lost their own local session state) - and
+    // should replace our stale session, not be ignored by it.
+    const existing = sessions.get(contactPubkey) || (await loadSession(contactPubkey));
+    if (existing && existing.name === session.name) return;
+    sessions.set(contactPubkey, session);
+    await persist(contactPubkey, session);
+    refreshMessageSubscription();
+    if (onNewSessionCallback) onNewSessionCallback(contactPubkey);
+  });
+}
+
+// Starts the ratchet subsystem for the current unlocked session: loads
+// every contact's persisted session, publishes this device's own invite,
+// and listens for both new inbound sessions (someone else discovered our
+// invite and messaged us first) and messages on existing sessions. Call
+// once per unlock, alongside subscribeInbox - a separate transport
+// layered under the same contact list, not a replacement for it.
+export async function start(secretKey, myPubkey, onMessage, onNewSession, onGroupRumor, onTradeRumor, onReaction, onReceipt) {
+  onMessageCallback = onMessage;
+  onNewSessionCallback = onNewSession;
+  onGroupRumorCallback = onGroupRumor;
+  onTradeRumorCallback = onTradeRumor;
+  onReactionCallback = onReaction;
+  onReceiptCallback = onReceipt;
+
+  const contacts = await storage.getContacts();
+  for (const c of contacts) await loadSession(c.pubkey);
+  refreshMessageSubscription();
+
+  await refreshInviteListen(secretKey, myPubkey);
+}
+
+export function stop() {
+  if (ownInviteListenUnsub) { ownInviteListenUnsub(); ownInviteListenUnsub = null; }
+  if (msgSubUnsub) { msgSubUnsub(); msgSubUnsub = null; }
+  msgSubAuthorsKey = null;
+  sessions.clear();
+  onMessageCallback = null;
+  onNewSessionCallback = null;
+  onGroupRumorCallback = null;
+  onTradeRumorCallback = null;
+  onReactionCallback = null;
+  onReceiptCallback = null;
+}
+
+// A contact's session is dropped locally when they're removed/declined
+// (storage.js's removeContact/declineContact already clear the persisted
+// copy) - drop the in-memory copy too so a stale session object can't
+// linger and get reused if the same pubkey is re-added later.
+export function forget(contactPubkey) {
+  sessions.delete(contactPubkey);
+  refreshMessageSubscription();
+}

package/src/signer.js

@@ -0,0 +1,110 @@
+// Adapted from webapp/src/lib/signer.js (2026-08-28) - included here only
+// because ratchet.js (copied verbatim into this SDK) statically imports it;
+// NIP-46 remote-signer support isn't wired into OwliAgent's public API yet
+// (v1.1 per the SDK plan). The only real change from the browser version:
+// the 4 localStorage call sites persisting a signer connection now go to a
+// small local JSON file instead - everything else, including the doc
+// comments explaining the actual NIP-46 integration, is unchanged.
+import { BunkerSigner, parseBunkerInput, createNostrConnectURI } from 'nostr-tools/nip46';
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { SimplePool } from 'nostr-tools/pool';
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CONNECTION_FILE = join(homedir(), '.owli-agent', 'signer-connection.json');
+
+let pool = null;
+function getSignerPool() {
+  if (!pool) pool = new SimplePool();
+  return pool;
+}
+
+// The *client* keypair used to talk to the signer over relays - not the
+// identity key, generated fresh per connection, safe to persist locally
+// (it only ever protects the Owli<->signer conversation, never the
+// identity itself).
+function loadOrCreateClientKey() {
+  if (!existsSync(CONNECTION_FILE)) return null;
+  const saved = JSON.parse(readFileSync(CONNECTION_FILE, 'utf8'));
+  return { clientSecretKey: Uint8Array.from(Object.values(saved.clientSecretKey)), bunkerPointer: saved.bunkerPointer };
+}
+
+function persistConnection(clientSecretKey, bunkerPointer) {
+  writeFileSync(CONNECTION_FILE, JSON.stringify({ clientSecretKey: Array.from(clientSecretKey), bunkerPointer }));
+}
+
+export function hasSavedConnection() {
+  return existsSync(CONNECTION_FILE);
+}
+
+export function forgetConnection() {
+  if (existsSync(CONNECTION_FILE)) unlinkSync(CONNECTION_FILE);
+}
+
+// Reconnects using a previously-approved pairing - no new prompt on the
+// signer app needed, same as reopening any app you've already granted
+// access to once.
+export async function reconnect() {
+  const saved = loadOrCreateClientKey();
+  if (!saved) return null;
+  return BunkerSigner.fromBunker(saved.clientSecretKey, saved.bunkerPointer, { pool: getSignerPool() });
+}
+
+// One-time pairing via a bunker:// URL or a NIP-05-style bunker address,
+// pasted from the signer app. Persists the connection so future runs
+// reconnect silently via reconnect() above.
+export async function connectWithBunkerURL(input) {
+  const bunkerPointer = await parseBunkerInput(input);
+  if (!bunkerPointer) throw new Error("That doesn't look like a valid bunker link.");
+  const clientSecretKey = generateSecretKey();
+  const signer = BunkerSigner.fromBunker(clientSecretKey, bunkerPointer, { pool: getSignerPool() });
+  await signer.getPublicKey(); // forces the connection handshake now, surfaces a bad link immediately
+  persistConnection(clientSecretKey, bunkerPointer);
+  return signer;
+}
+
+// One-time pairing the other direction - Owli generates a nostrconnect://
+// link/QR, the signer app scans it and approves. onConnected fires once
+// the signer app actually approves (this can take a while - it's a human
+// tapping "approve" on their phone, not an instant round-trip).
+export function startConnectFlow({ appName = 'Owli Agent', onConnected, onError }) {
+  const clientSecretKey = generateSecretKey();
+  const clientPubkey = getPublicKey(clientSecretKey);
+  const relay = 'wss://relay.nsec.app';
+  const uri = createNostrConnectURI({ clientPubkey, relays: [relay], appName });
+  BunkerSigner.fromURI(clientSecretKey, uri, { pool: getSignerPool() })
+    .then(async (signer) => {
+      await signer.getPublicKey();
+      persistConnection(clientSecretKey, signer.bp);
+      onConnected(signer);
+    })
+    .catch((err) => onError(err));
+  return uri;
+}
+
+// --- Adapters bridging BunkerSigner's real NIP-46 methods to the exact
+// shapes ratchet.js's three real identity-key touch points expect. Kept
+// here, not duplicated at each call site. ---
+
+// finalizeEvent(unsignedEvent, secretKey) needs a raw key and can't take a
+// callback - BunkerSigner.signEvent already returns a complete, signed
+// VerifiedEvent on its own, so this replaces the finalizeEvent call
+// entirely rather than feeding into it.
+export async function signEventWithSigner(signer, unsignedEvent) {
+  return signer.signEvent(unsignedEvent);
+}
+
+// Invite.accept()'s EncryptFunction type is (plaintext, pubkey) - note the
+// reversed argument order from BunkerSigner's own nip44Encrypt(pubkey,
+// plaintext), easy to get backwards, confirmed against both type
+// definitions directly before writing this.
+export function encryptorFor(signer) {
+  return (plaintext, pubkey) => signer.nip44Encrypt(pubkey, plaintext);
+}
+
+// Invite.listen()'s DecryptFunction type is (ciphertext, pubkey) - same
+// reversed-order note as encryptorFor above.
+export function decryptorFor(signer) {
+  return (ciphertext, pubkey) => signer.nip44Decrypt(pubkey, ciphertext);
+}

package/src/storage/backend.js

@@ -0,0 +1,14 @@
+// The low-level KV interface every storage backend implements. Deliberately
+// the same shape as nostr-double-ratchet's own internal StorageAdapter type
+// (get/put/del/list) so a future backend (SQLite, Redis, or wiring in the
+// library's own GroupManager if group chat is ever added here) drops in
+// without touching storage.js's 6-function public surface.
+//
+// This file is documentation, not code that runs - a plain JS project has
+// no interfaces to implement against, so this is the contract every
+// *Backend.js file in this folder honors:
+//
+//   async get(key: string): Promise<string | null>
+//   async set(key: string, value: string): Promise<void>
+//   async del(key: string): Promise<void>
+//   async keys(prefix: string): Promise<string[]>