@wacando/agent 0.0.0-stage → 2.0.0-rc.1

package/packages/runtime/conversations.mjs

@@ -0,0 +1,384 @@
+import { NS_OMEMO } from '@wacando/omemo';
+import { NS_WACANDO_POLICY, toPolicySubmission } from '@wacando/omemo/wire';
+import {
+  authenticatedMessageOrigin, forwardedStanza, joinRoom, MucJoinError, MucOriginTracker, queryMam, unwrapPolicyDelivery,
+} from '@wacando/xmpp';
+import { ApiError } from '../onboarding/network.mjs';
+import { SafeError } from '../onboarding/storage.mjs';
+
+// Consent-aware conversations (lbframe/wacando docs/CONVERSATION_CONSENT.md):
+// - a request's first message and every message of a gated (`service`) agent
+//   go to the policy component, which holds them for the owner's approval;
+// - an accepted `human` agent is a room member and speaks freely;
+// - only ACCEPTED conversations are ever read; direct 1:1 chat is never used.
+// Message text is never logged; decrypt failures yield `text: null`.
+
+export const HOLD_TTL_MS = 10 * 60 * 1000;
+const SUBMISSION_TIMEOUT_MS = 15000;
+const MAM_PAGE = 100;
+const MAM_MAX_PAGES = 20;
+const MAX_ENTRIES = 1000;
+const DELETED = 'deleted_account';
+
+export const consentErrors = {
+  notContact: 'This address is not an accepted contact of this agent. Ask its owner to accept a contact invitation first.',
+  unknown: 'Unknown or unreachable address. Check the handle (@owner/agent) with your owner.',
+  notAccepted: 'Conversation not found or not accepted. Only accepted conversations can be read.',
+  closed: state => `Conversation is ${state}; nothing was sent. A stopped or refused conversation never reopens.`,
+  waitingOther: 'This request waits for the other owner; only its requester sends the first message.',
+  firstSent: 'The first message of this request was already approved and delivered; wait for the recipient owner to accept.',
+  noDiscovery: 'Secure messaging is unavailable: this Wacando server does not provide recipient discovery (per-device observers). Nothing was sent; the server must be updated.',
+  noDevice: 'Secure messaging is unavailable: an owner or the other agent has no published secure device yet (the owner must open the Wacando desktop app). Nothing was sent; retry later.',
+};
+
+export function apiFailure(error) {
+  if (!(error instanceof ApiError)) return error;
+  const known = {
+    CONTACT_NOT_ACCEPTED: consentErrors.notContact,
+    CONTACT_REVOKED: 'The contact relationship was revoked. Nothing was sent.',
+    AGENT_NOT_REACHABLE: consentErrors.unknown,
+    AGENT_REVOKED: 'One of the agents is revoked. Nothing was sent.',
+    AGENT_OFFLINE: 'The other agent is offline. Retry when it is connected.',
+    CONVERSATION_CLOSED: 'Conversation is closed (stopped, refused or expired). Nothing was sent.',
+    CONVERSATION_NOT_ACTIVE: 'Conversation is not active. Nothing was sent.',
+    NOT_FOUND: consentErrors.notAccepted,
+    FORBIDDEN: 'Refused: the other agent is not reachable for new requests, or this agent may not act here. Nothing was sent.',
+  };
+  return new SafeError(known[error.code] ?? `Wacando API refused the request (${error.code ?? `HTTP ${error.status}`}).`);
+}
+
+/** Pure: which side of a conversation this agent is, and who must receive the ciphertext. */
+export function conversationView(conversation, selfAgentId, domain) {
+  const self = conversation.agentAId === selfAgentId ? 'A' : conversation.agentBId === selfAgentId ? 'B' : null;
+  if (!self) throw new SafeError(consentErrors.notAccepted);
+  const peer = self === 'A' ? 'B' : 'A';
+  const peerAgentId = conversation[`agent${peer}Id`];
+  const recipients = [];
+  if (peerAgentId && peerAgentId !== DELETED) recipients.push(`agt_${peerAgentId}@${domain}`);
+  for (const owner of [conversation.ownerAId, conversation.ownerBId]) {
+    if (owner && owner !== DELETED) recipients.push(`usr_${owner}@${domain}`);
+  }
+  return {
+    id: conversation.id,
+    state: conversation.status,
+    accepted: conversation.activatedAt != null,
+    role: conversation.requestedByAgentId == null ? 'participant' : conversation.requestedByAgentId === selfAgentId ? 'requester' : 'recipient',
+    peerAgentId: peerAgentId === DELETED ? null : peerAgentId,
+    firstMessageDelivered: conversation.requestSentAt != null,
+    requestExpiresAt: conversation.requestExpiresAt ?? null,
+    recipients: [...new Set(recipients)],
+    agentIds: [conversation.agentAId, conversation.agentBId],
+    ownerIds: [conversation.ownerAId, conversation.ownerBId],
+  };
+}
+
+const BARE_JID = /^[^\s/@]+@[^\s/@]+$/;
+
+/**
+ * Pure: validate recipient discovery (lbframe/wacando #35/#108,
+ * GET /v1/conversations/:id/recipients v1) and return every OMEMO recipient
+ * JID: both agents and every active installation of both owners. Anything
+ * unexpected fails closed; there is never a smaller fallback set.
+ */
+export function discoveredRecipients(body, view) {
+  const r = body?.recipients;
+  const ownersPresent = owners => Array.isArray(r?.observers) &&
+    owners.every(owner => r.observers.some(o => o?.ownerUserId === owner));
+  const ok = r && r.version === 1 && r.conversationId === view.id && typeof r.revision === 'string' &&
+    Array.isArray(r.agents) && r.agents.length === 2 && r.agents.every(a => BARE_JID.test(a?.jid ?? '')) &&
+    [...view.agentIds].sort().join('|') === r.agents.map(a => a?.agentId).sort().join('|') &&
+    Array.isArray(r.observers) && r.observers.length > 0 && r.observers.every(o => BARE_JID.test(o?.jid ?? '')) &&
+    ownersPresent([...new Set(view.ownerIds)]);
+  if (!ok) throw new SafeError('Secure messaging is unavailable: the recipient list is malformed or misses a participant. Nothing was sent.');
+  return { revision: r.revision, jids: [...new Set([...r.agents, ...r.observers].map(x => x.jid))] };
+}
+
+/** Pure: public summary of a conversation for agents (no owner identifiers). */
+export function publicConversation(view, extra = {}) {
+  const { recipients: _recipients, agentIds: _agents, ownerIds: _owners, ...rest } = view;
+  return { ...rest, ...extra };
+}
+
+/** Messaging for ONE connected identity. Created by AgentRuntime.conversations(). */
+export class ConversationClient {
+  constructor({ runtime, agent, session }) {
+    this.runtime = runtime;
+    this.agent = agent;
+    this.session = session;
+    this.domain = agent.xmpp.domain;
+    this.selfJid = session.bareJid;
+    this.policyJid = `policy.${this.domain}`;
+    this.mucDomain = `conference.${this.domain}`;
+    this.nick = `agt-${agent.agentId.replace(/[^a-zA-Z0-9]/g, '').slice(-10)}`;
+    this.tracker = new MucOriginTracker(session.client, { trustedRelayJid: this.policyJid });
+    this.rooms = new Map(); // conversationId → 'member' | 'gated'
+    this.transcripts = new Map(); // conversationId → Map(stanzaId → entry)
+    this.claimed = new Set(); // stanza ids already decrypted once (Signal keys are single use)
+    this.sent = new Map(); // own stanza id → text, this process only (Signal cannot self-decrypt)
+    this.held = new Map(); // stanza id → submission status
+    this.submissions = new Map(); // stanza id → resolver for the component's status
+    this.waiters = new Set();
+    this.cancels = new Set();
+    this.chain = Promise.resolve();
+  }
+
+  /** Own sent text, kept in memory only and bounded (Signal cannot self-decrypt). */
+  remember(id, text) {
+    this.sent.set(id, text);
+    while (this.sent.size > MAX_ENTRIES) this.sent.delete(this.sent.keys().next().value);
+  }
+
+  /** Continue on a new session of the same identity (after a reconnection). */
+  rebind(session) {
+    this.tracker.close();
+    this.session = session;
+    this.tracker = new MucOriginTracker(session.client, { trustedRelayJid: this.policyJid });
+    this.rooms.clear();
+    for (const resolve of this.submissions.values()) resolve({ state: 'refused', reason: 'connection-lost' });
+  }
+
+  room(conversationId) { return `c_${conversationId}@${this.mucDomain}`; }
+  conversationOf(room) {
+    const m = /^c_(.+)@(.+)$/.exec(room ?? '');
+    return m && m[2] === this.mucDomain ? m[1] : null;
+  }
+
+  /** Called for every stanza of this identity (attached before the presence echo). */
+  handle(stanza) {
+    if (!stanza.is('message') || stanza.getAttr('type') === 'chat') return; // never a 1:1 channel
+    const from = stanza.getAttr('from');
+    const status = from === this.policyJid ? stanza.getChild('submission', NS_WACANDO_POLICY) : undefined;
+    if (status) {
+      this.submissions.get(status.getAttr('id'))?.(status.attrs);
+      return;
+    }
+    const delivered = unwrapPolicyDelivery(stanza, this.policyJid);
+    if (delivered) { this.ingest(delivered, 'delivery'); return; }
+    if (stanza.getAttr('type') === 'groupchat' && stanza.getChild('encrypted', NS_OMEMO) &&
+        !stanza.getChild('delay', 'urn:xmpp:delay')) {
+      // Let the origin tracker (a later listener) record provenance first.
+      setImmediate(() => this.ingest(stanza, 'live'));
+    }
+  }
+
+  ingest(stanza, source, stamp) {
+    const origin = authenticatedMessageOrigin(stanza);
+    const conversationId = this.conversationOf(origin?.roomJid);
+    const id = stanza.getAttr('id');
+    if (!origin || !conversationId || typeof id !== 'string') return Promise.resolve();
+    const task = this.chain.then(async () => {
+      const transcript = this.transcripts.get(conversationId) ?? new Map();
+      this.transcripts.set(conversationId, transcript);
+      if (transcript.has(id)) return;
+      const own = origin.senderBareJid === this.selfJid;
+      let text = null;
+      if (own) text = this.sent.get(id) ?? null;
+      else if (!this.claimed.has(id)) {
+        this.claimed.add(id);
+        text = await this.session.provider.decryptStanza(stanza, origin).catch(() => null);
+      }
+      if (this.held.has(id)) this.held.get(id).state = 'delivered';
+      const entry = { id, conversationId, sender: own ? 'self' : 'peer', at: stamp ?? new Date().toISOString(), text,
+        ...(text === null && !own ? { undecryptable: true } : {}), source };
+      transcript.set(id, entry);
+      while (transcript.size > MAX_ENTRIES) transcript.delete(transcript.keys().next().value);
+      if (!own) for (const waiter of [...this.waiters]) waiter(entry);
+    });
+    this.chain = task.catch(() => {});
+    return task;
+  }
+
+  async conversation(conversationId) {
+    try {
+      const { conversation } = await this.runtime.api(this.agent, 'GET', `/v1/conversations/${encodeURIComponent(conversationId)}`);
+      return conversationView(conversation, this.agent.agentId, this.domain);
+    } catch (error) { throw apiFailure(error); }
+  }
+
+  /** Accepted conversations, plus this agent's own pending requests. */
+  async list() {
+    let conversations;
+    try { ({ conversations } = await this.runtime.api(this.agent, 'GET', '/v1/conversations')); }
+    catch (error) { throw apiFailure(error); }
+    const views = conversations.map(c => conversationView(c, this.agent.agentId, this.domain));
+    return {
+      accepted: views.filter(v => v.accepted).map(v => publicConversation(v, { mode: this.rooms.get(v.id) ?? 'unknown' })),
+      requests: views.filter(v => !v.accepted && v.role === 'requester' && v.state === 'requested').map(v => publicConversation(v)),
+    };
+  }
+
+  /** Accepted contacts, resolved to handles where the directory shows them. */
+  async contacts() {
+    try {
+      const { contacts } = await this.runtime.api(this.agent, 'GET', '/v1/contacts');
+      return contacts.filter(c => c.status === 'accepted').map(c => ({ contactId: c.id, agentId: c.agentAId === this.agent.agentId ? c.agentBId : c.agentAId }));
+    } catch (error) { throw apiFailure(error); }
+  }
+
+  async resolve(handle) {
+    if (!/^@[a-z0-9][a-z0-9_-]{0,31}\/[a-z0-9][a-z0-9_-]{0,31}$/.test(handle ?? '')) throw new SafeError('Use an address like @owner/agent.');
+    let agent;
+    try { ({ agent } = await this.runtime.api(this.agent, 'GET', `/v1/directory/agents?handle=${encodeURIComponent(handle)}`)); }
+    catch (error) { throw error instanceof ApiError && error.status === 404 ? new SafeError(consentErrors.unknown) : apiFailure(error); }
+    if (!(await this.contacts()).some(c => c.agentId === agent.id)) throw new SafeError(consentErrors.notContact);
+    return agent;
+  }
+
+  /**
+   * Propose a conversation: create the request, then submit the first message
+   * to the policy component, held for this agent's owner. The recipient
+   * agent receives nothing before its owner accepts.
+   */
+  async propose(handle, text) {
+    const peer = await this.resolve(handle);
+    let conversation;
+    try {
+      ({ conversation } = await this.runtime.api(this.agent, 'POST', '/v1/conversations', { fromAgentId: this.agent.agentId, toAgentId: peer.id }));
+    } catch (error) { throw apiFailure(error); }
+    const view = conversationView(conversation, this.agent.agentId, this.domain);
+    try {
+      const submission = await this.submit(view, text, 'first_message');
+      return { conversation: publicConversation(view), to: handle, firstMessage: submission };
+    } catch (error) {
+      // The request exists; its first message can be sent later with send().
+      return { conversation: publicConversation(view), to: handle, firstMessage: { state: 'not_sent', reason: error.message } };
+    }
+  }
+
+  /** Send in a conversation, respecting consent and the agent's mode. */
+  async send(conversationId, text) {
+    const view = await this.conversation(conversationId);
+    if (view.state === 'requested') {
+      if (view.role !== 'requester') throw new SafeError(consentErrors.waitingOther);
+      if (view.firstMessageDelivered) throw new SafeError(consentErrors.firstSent);
+      return { conversation: publicConversation(view), message: await this.submit(view, text, 'first_message') };
+    }
+    if (view.state !== 'active') throw new SafeError(consentErrors.closed(view.state));
+    const mode = await this.enter(view);
+    if (mode === 'gated') return { conversation: publicConversation(view, { mode }), message: await this.submit(view, text, 'service_message') };
+    const stanza = await this.encrypt(view, text);
+    const id = stanza.getAttr('id');
+    this.remember(id, text);
+    await this.session.client.send(stanza);
+    return { conversation: publicConversation(view, { mode }), message: { id, state: 'sent' } };
+  }
+
+  /**
+   * Recipients, discovered fresh before EVERY encryption: owners observe
+   * through per-installation device JIDs (lbframe/wacando #35/#108). There is
+   * no fallback of any kind (never `usr_`, never a smaller set): a server
+   * without discovery is refused.
+   */
+  async recipients(view) {
+    try {
+      const body = await this.runtime.api(this.agent, 'GET', `/v1/conversations/${encodeURIComponent(view.id)}/recipients`);
+      return discoveredRecipients(body, view).jids;
+    } catch (error) {
+      if (error instanceof ApiError && error.unknownRoute) throw new SafeError(consentErrors.noDiscovery);
+      if (error instanceof ApiError && error.code === 'SECURE_MESSAGING_UNAVAILABLE') throw new SafeError(consentErrors.noDevice);
+      throw error instanceof ApiError ? apiFailure(error) : error;
+    }
+  }
+
+  async encrypt(view, text) {
+    const recipients = await this.recipients(view);
+    try { return await this.session.provider.encryptForRoom(this.session.client, this.room(view.id), recipients, text); }
+    catch { throw new SafeError(consentErrors.noDevice); }
+  }
+
+  /** Encrypt for the room, then hand the ciphertext to the policy component. */
+  async submit(view, text, kind) {
+    const stanza = await this.encrypt(view, text);
+    const id = stanza.getAttr('id');
+    let timer;
+    const status = new Promise((resolve, reject) => {
+      this.submissions.set(id, resolve);
+      timer = setTimeout(() => reject(new SafeError('The policy component did not answer; the message may not be held. Retry later.')), SUBMISSION_TIMEOUT_MS);
+    }).finally(() => { clearTimeout(timer); this.submissions.delete(id); });
+    this.remember(id, text);
+    await this.session.client.send(toPolicySubmission(stanza, this.policyJid));
+    const attrs = await status;
+    if (attrs.state !== 'held') {
+      this.sent.delete(id);
+      return { id, state: 'refused', reason: attrs.reason ?? 'refused' };
+    }
+    const held = { id, conversationId: view.id, kind, state: 'held', heldAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + HOLD_TTL_MS).toISOString(), digest: attrs.digest,
+      awaiting: kind === 'first_message' ? "your owner's approval in the Wacando app, then the recipient owner's acceptance" : "your owner's approval in the Wacando app" };
+    this.held.set(id, held);
+    return { ...held };
+  }
+
+  /** Join as a member when the room admits us; otherwise this agent is gated. */
+  async enter(view) {
+    const known = this.rooms.get(view.id);
+    if (known) return known;
+    const room = this.room(view.id);
+    this.tracker.trackRoom(room);
+    try {
+      await joinRoom(this.session.client, room, this.nick);
+      this.rooms.set(view.id, 'member');
+    } catch (error) {
+      if (!(error instanceof MucJoinError)) throw new SafeError('Secure messaging is unavailable. Retry later.');
+      this.rooms.set(view.id, 'gated');
+    }
+    return this.rooms.get(view.id);
+  }
+
+  /** Messages of an ACCEPTED conversation: archive (members) or live deliveries (gated). */
+  async read(conversationId) {
+    const view = await this.conversation(conversationId);
+    if (!view.accepted) throw new SafeError(consentErrors.notAccepted);
+    const mode = view.state === 'active' ? await this.enter(view) : (this.rooms.get(view.id) ?? 'gated');
+    if (mode === 'member') await this.catchUp(view);
+    await this.chain;
+    const messages = [...(this.transcripts.get(view.id)?.values() ?? [])].sort((a, b) => a.at.localeCompare(b.at));
+    return { conversation: publicConversation(view, { mode }), messages,
+      ...(mode === 'gated' ? { note: 'Gated (service) agents cannot read the archive: only messages delivered while this runtime was connected are listed.' } : {}) };
+  }
+
+  async catchUp(view) {
+    // RSM `after` is not exposed by the shared helper: page forward by the
+    // last archived timestamp (inclusive) and stop when a page adds nothing.
+    const room = this.room(view.id);
+    let start;
+    for (let page = 0; page < MAM_MAX_PAGES; page++) {
+      let result;
+      try { result = await queryMam(this.session.client, { to: room, max: MAM_PAGE, ...(start ? { start } : {}), trustedRelayJid: this.policyJid }); }
+      catch { throw new SafeError('Conversation history is unavailable. Retry later.'); }
+      const before = this.transcripts.get(view.id)?.size ?? 0;
+      for (const forwarded of result.messages) {
+        const stamp = forwarded.getChild('delay')?.getAttr('stamp');
+        if (stamp) start = stamp;
+        const inner = forwardedStanza(forwarded);
+        if (!inner?.getChild('encrypted', NS_OMEMO)) continue;
+        await this.ingest(inner, 'archive', stamp);
+      }
+      if (result.complete || result.messages.length < MAM_PAGE || (this.transcripts.get(view.id)?.size ?? 0) === before) break;
+    }
+  }
+
+  /** Wait for the next message from the other agent (bounded; no wake-up when closed). */
+  waitForMessage(conversationId, timeoutMs) {
+    return new Promise(resolve => {
+      const waiter = entry => {
+        if (conversationId && entry.conversationId !== conversationId) return;
+        done(entry);
+      };
+      const timer = setTimeout(() => done(null), timeoutMs);
+      const done = entry => { clearTimeout(timer); this.waiters.delete(waiter); this.cancels.delete(done); resolve(entry); };
+      this.waiters.add(waiter);
+      this.cancels.add(done);
+    });
+  }
+
+  /** Submissions still waiting for this agent's owner. */
+  pending() {
+    return [...this.held.values()].filter(h => h.state === 'held').map(h => ({ ...h, expired: Date.parse(h.expiresAt) <= Date.now() }));
+  }
+
+  close() {
+    this.tracker.close();
+    for (const cancel of [...this.cancels]) cancel(null);
+  }
+}

package/packages/runtime/device.mjs

@@ -0,0 +1,34 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { jidStateDirName, loadNativeOmemoProvider } from '@wacando/omemo';
+import { SafeError } from '../onboarding/storage.mjs';
+
+// Runtime 2.x speaks only the official libsignal (PQXDH) OMEMO profile. A
+// state directory holding a 1.x classic device is never converted or replaced.
+export const CLASSIC_IDENTITY = 'This identity was created by plugin 1.x with the retired classic OMEMO format, which desktop apps cannot decrypt. It cannot be upgraded in place: revoke it on the site and pair a new identity with a different address (docs/MIGRATION-2.0.md). Its keys were left untouched.';
+const unreadable = 'Existing OMEMO state cannot be read. Preserve the keys and repair local storage before reconnecting.';
+
+async function privateEntry(path, directory) {
+  let stat;
+  try { stat = await lstat(path); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw new SafeError(unreadable); }
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (stat.mode & 0o077) ||
+      (process.getuid && stat.uid !== process.getuid())) throw new SafeError(unreadable);
+  return true;
+}
+
+/**
+ * Load (or create on first use) this identity's native OMEMO device under the
+ * protected `stateBaseDir`. Private keys stay in `<stateBaseDir>/<jid>/state.json`
+ * (0700/0600); a corrupt or unsafe file fails closed and is never regenerated.
+ */
+export async function loadDevice(jid, stateBaseDir) {
+  if (await privateEntry(join(stateBaseDir, 'classic-state.json'), false).catch(() => true)) {
+    throw new SafeError(CLASSIC_IDENTITY);
+  }
+  const bare = jid.split('/')[0];
+  const directory = join(stateBaseDir, jidStateDirName(bare));
+  if (await privateEntry(directory, true)) await privateEntry(join(directory, 'state.json'), false);
+  try { return loadNativeOmemoProvider(bare, { baseDir: stateBaseDir }); }
+  catch { throw new SafeError(unreadable); }
+}

package/packages/runtime/index.mjs

@@ -0,0 +1,8 @@
+// Node SDK of the Wacando agent runtime (`import ... from 'wacando-agent'`).
+export { AgentRuntime, publicIdentity } from './runtime.mjs';
+export { connectSession } from './session.mjs';
+export { CLASSIC_IDENTITY, loadDevice } from './device.mjs';
+export { OnboardingService } from '../onboarding/service.mjs';
+export { CredentialStore, SafeError } from '../onboarding/storage.mjs';
+export { ApiError } from '../onboarding/network.mjs';
+export { pluginVersion as runtimeVersion } from '../onboarding/version.mjs';

package/packages/runtime/pairing.mjs

@@ -0,0 +1,110 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
+import { hostname } from 'node:os';
+import { ApiError, post } from '../onboarding/network.mjs';
+import { SafeError } from '../onboarding/storage.mjs';
+
+// Universal pairing (lbframe/wacando docs/ENROLLMENT_PAIRING_API.md, #36/#60).
+export const PAIRING_TTL_MS = 10 * 60 * 1000;
+export const POLL_INTERVAL_MS = 5000;
+const CODE = /^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{8}$/;
+const SPKI_ED25519 = Buffer.from('302a300506032b6570032100', 'hex');
+const b64url = bytes => Buffer.from(bytes).toString('base64url');
+
+export const pairingErrors = {
+  code: 'Invalid pairing code. Use the 8-character code shown in the Wacando app.',
+  refused: 'Pairing code unavailable: it is expired, already used or unknown. Create a new code in the Wacando app.',
+  notConfirmed: 'Pairing was not confirmed in time (the owner refused it, it expired, or it was never confirmed). No identity was saved. Create a new code in the Wacando app.',
+  lost: 'The pairing result was not safely saved. If the app shows this agent as paired, revoke it there and pair a new identity with a different address.',
+};
+
+/** Dedicated Ed25519 runtime authentication key (separate from the OMEMO key). */
+export function generateAuthKey() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  return {
+    publicKey: b64url(publicKey.export({ format: 'der', type: 'spki' }).subarray(SPKI_ED25519.length)),
+    privateKeyPem: privateKey.export({ format: 'pem', type: 'pkcs8' }),
+  };
+}
+
+/** Raw 32-byte public key (base64url) of a stored PKCS#8 Ed25519 private key. */
+export function publicKeyOf(privateKeyPem) {
+  const der = createPublicKey(createPrivateKey(privateKeyPem)).export({ format: 'der', type: 'spki' });
+  return b64url(der.subarray(SPKI_ED25519.length));
+}
+
+export const redeemMessage = (code, publicKey, clientNonce, issuedAt) =>
+  `wacando-pair-redeem-v1|${code}|${publicKey}|${clientNonce}|${issuedAt}`;
+export const claimMessage = (pairingId, serverNonce, publicKey) =>
+  `wacando-pair-claim-v1|${pairingId}|${serverNonce}|${publicKey}`;
+
+/** Raw 64-byte Ed25519 signature over the exact UTF-8 bytes, base64url without padding. */
+export function proof(privateKeyPem, message) {
+  return b64url(sign(null, Buffer.from(message, 'utf8'), createPrivateKey(privateKeyPem)));
+}
+
+/** Runtime-authored display metadata shown to the owner (never trusted as instructions). */
+export function runtimeMetadata({ host, label }) {
+  const clean = (value, max) => String(value).replace(/[\u0000-\u001f\u007f]/g, ' ').trim().slice(0, max);
+  return { host: clean(`wacando-agent ${host}`, 64), label: clean(label ?? hostname() ?? 'agent', 80) || 'agent' };
+}
+
+export function validCode(code) {
+  return typeof code === 'string' && CODE.test(code);
+}
+
+/**
+ * Redeem a code with a fresh key. The key is persisted BEFORE the request so a
+ * crash after the server accepted it can still be resumed with the saved key.
+ */
+export async function redeem({ origin, code, host, label, mode, saveKey, request = post, now = Date.now }) {
+  if (!validCode(code)) throw new SafeError(pairingErrors.code);
+  const key = generateAuthKey();
+  const clientNonce = b64url(randomBytes(32));
+  const issuedAt = Math.floor(now() / 1000);
+  const meta = runtimeMetadata({ host, label });
+  const pending = { origin, publicKey: key.publicKey, privateKeyPem: key.privateKeyPem, mode, startedAt: new Date(now()).toISOString() };
+  await saveKey(pending);
+  let data;
+  try {
+    data = await request(new URL('/v2/pairings/redeem', origin), undefined, {
+      code, publicKey: key.publicKey, clientNonce, issuedAt, ...meta,
+      proof: proof(key.privateKeyPem, redeemMessage(code, key.publicKey, clientNonce, issuedAt)),
+    });
+  } catch (error) {
+    if (error instanceof ApiError && [400, 401, 403, 404].includes(error.status)) throw new SafeError(pairingErrors.refused);
+    if (error instanceof ApiError && error.status === 429) throw new SafeError('Too many pairing attempts. Wait and retry with the same code.');
+    throw error;
+  }
+  if (typeof data?.pairingId !== 'string' || typeof data.pollSecret !== 'string' || typeof data.serverNonce !== 'string') {
+    throw new SafeError(pairingErrors.refused);
+  }
+  return { ...pending, pairingId: data.pairingId, pollSecret: data.pollSecret, serverNonce: data.serverNonce };
+}
+
+/**
+ * Poll the claim endpoint (never faster than every 5 s, honouring Retry-After)
+ * until the owner confirms. The API answers the same 401 while pending, after a
+ * refusal or after expiry, so the local deadline ends the wait.
+ */
+export async function claim({ pending, request = post, sleep, now = Date.now, deadlineMs, onWaiting }) {
+  const deadline = deadlineMs ?? Date.parse(pending.startedAt) + PAIRING_TTL_MS + 30000;
+  const body = () => ({ pollSecret: pending.pollSecret, proof: proof(pending.privateKeyPem, claimMessage(pending.pairingId, pending.serverNonce, pending.publicKey)) });
+  for (;;) {
+    let wait = POLL_INTERVAL_MS;
+    try {
+      const data = await request(new URL(`/v2/pairings/${encodeURIComponent(pending.pairingId)}/claim`, pending.origin), undefined, body());
+      if (typeof data?.agentId !== 'string' || typeof data.handle !== 'string' || typeof data.agentToken !== 'string' ||
+          !data.agentToken.startsWith('agtacc_') || typeof data.xmpp?.domain !== 'string' || typeof data.xmpp?.service !== 'string') {
+        throw new SafeError(pairingErrors.lost);
+      }
+      return data;
+    } catch (error) {
+      if (!(error instanceof ApiError)) throw error;
+      if (error.status === 429) wait = Math.max(POLL_INTERVAL_MS, (error.retryAfter ?? 5) * 1000);
+      else if (error.status !== 401) throw new SafeError(`Pairing service error (HTTP ${error.status}). Retry with the same command.`);
+    }
+    if (now() + wait > deadline) throw new SafeError(pairingErrors.notConfirmed);
+    onWaiting?.();
+    await sleep(wait);
+  }
+}