sigelo-mcp 0.1.5 → 0.1.6

package/contact.mjs

@@ -27,7 +27,7 @@ const int = (d, maximum) => ({ type: 'integer', minimum: 0, ...(maximum !== unde
 // which binds both original DIDs) are what two operators read to each other to know their agents
 // paired with each other, as sigelo-agent's accept, inbox and contacts show them. 44 bits: the
 // 32-digit pair id stays beside them for whoever wants all 128 (THREAT-MODEL.md §2.10).
-const CONFIRM = 'Show your operator the contact\'s DID and its four words (fingerprint): they read them to the other operator; the same words on both sides = nobody, not even the relay, swapped the pairing.';
+const CONFIRM = 'Show your operator the contact\'s DID and four words (fingerprint) to read to the other side. Same words = no mix-up or casual swap; a relay spending GPU time is caught by pair (32 digits).';
 // The proof of work runs at an identity's first login: about 23 s on average at 22 bits on a
 // phone-class CPU, 92 s at 24 (design/relay-plan.md §11), past some clients' tool timeouts.
 const POW = 'A first call can take minutes: your first login to the relay solves a proof of work. If your client gives up, call again.';
@@ -39,7 +39,7 @@ const TOOLS = [
     obj({ name: str('the name you will call the new contact'), ttl: int('seconds the long code lives, at most 604800 (7 days)'), long: { type: 'boolean', description: 'true: the long code only, no short code' } })],
   ['sigelo_accept', `Accept an invite code from another agent's operator: sends your answer (whoever holds the code learns your DID); pairs once the inviter's reply verifies against the code. Returns connected with the pairing id, or waiting until the inviter's agent next connects (sigelo_inbox then reports the pairing). ${CONFIRM} ${POW} ${RELAY_DATA}`,
     obj({ code: str('the short code (K7F3-Q9ZP; case, I/L/O and dashes do not matter) or the sgl1… code, exactly as received'), name: str('the name you will call this contact'), wait: int(`seconds to wait for the reply, default 10, at most ${WAIT_MAX}`, WAIT_MAX) }, ['code'])],
-  ['sigelo_contacts', `Your contacts (name, original DID, current DID, revoked, relay, messages queued for them, pairing id, four words, re_pair) and your pending invites and answers. re_pair not null = after a recovery (own_recovery: yours; contact_recovery: theirs) the pairing key may be a thief's: nothing is sent to that contact until you pair again (sigelo_invite, they accept). ${CONFIRM}`, obj()],
+  ['sigelo_contacts', `Your contacts (name, original DID, current DID, revoked, relay, messages queued for them, pairing id, four words, re_pair), your pending invites and answers, and failed pairings (code_expired: ask for a new code). re_pair not null = after a recovery (own_recovery: yours; contact_recovery: theirs) the pairing key may be a thief's: nothing is sent to that contact until you pair again (sigelo_invite, they accept). ${CONFIRM}`, obj()],
   ['sigelo_send', `Send an end-to-end encrypted message to a contact, by name or DID. The relay sees only ciphertext. status sent = the relay accepted it (it holds it while the contact reads that mailbox); queued = kept here, it goes by itself at your next call that connects (detail says why: the contact's agent does not hold its mailbox yet, as right after a pairing until it next connects, or is away; or waiting for its fresh prekeys): do not send it again. Error not_paired = your answer to its code waits for the inviter's agent. Error re_pair = pair again first (see sigelo_contacts). ${RELAY_DATA}`,
     obj({ to: str('contact name or DID'), text: str('the message'), label: str('optional conversation label, e.g. "billing"') }, ['to', 'text'])],
   ['sigelo_inbox', `Messages from your contacts since you last asked (each returned once), and events: pairings done (with the four words to show your operator) or failed (with why), contacts' key rotations, re_pair (pair again after a recovery), refused (your queued messages to such a contact; or a contact's messages signed by a key its recovery overruled, maybe a thief's), waiting (for a contact's prekeys or its agent). last_resort = weaker forward secrecy. dropped: refusals by check. more > 0: call again now. ${DATA} ${RELAY_DATA}`,
@@ -56,7 +56,7 @@ const TOOLS = [
 // keeps the held inbox. → null, with one line on stderr, when sigelo-contact (in that install) or
 // one of its dependencies is not installed. Anything else (a refused package, a file missing in
 // one, a syntax error) throws: a broken install must not pass for an absent one.
-export async function load({ installed, id, env = process.env, clock }) {
+export async function load({ installed, id, env = process.env, clock, debug = () => {} }) {
   const held = await import(installed ? 'sigelo-agent/dist/sigelo-agent-contact.js' : '../../adapters/moadim/sigelo-agent-contact.ts');
   let lib, kdf;
   try { ({ lib, kdf } = await held.contactLib()); } catch (e) {
@@ -86,10 +86,12 @@ export async function load({ installed, id, env = process.env, clock }) {
     queues.set(path, run.catch(() => {}));
     return run;
   };
-  const text = (v, name) => { if (typeof v !== 'string' || v === '') throw new Error(`${name} is required`); return v; };
+  // A refusal of the call's arguments: code usage (server.mjs codeOf reads .check).
+  const usage = (why) => Object.assign(new Error(why), { check: 'usage' });
+  const text = (v, name) => { if (typeof v !== 'string' || v === '') throw usage(`${name} is required`); return v; };
   const seconds = (v, name, dflt) => {
     if (v === undefined) return dflt;
-    if (!Number.isSafeInteger(v) || v < 0 || v > WAIT_MAX) throw new Error(`${name}: whole seconds, 0 to ${WAIT_MAX}`);
+    if (!Number.isSafeInteger(v) || v < 0 || v > WAIT_MAX) throw usage(`${name}: whole seconds, 0 to ${WAIT_MAX}`);
     return v;
   };
   // The pairing id of a live contact, from the pairing key in the contact store (store.mjs); null
@@ -116,13 +118,14 @@ export async function load({ installed, id, env = process.env, clock }) {
   const inbox = async ({ wait }, path) => {
     const w = seconds(wait, 'wait', 0), file = held.heldPath(path);
     const fresh = held.peekHeld(file).messages.length > 0 ? { messages: [], events: [], dropped: {} } : await carrier(path).inbox({ wait: w });
+    if (fresh.offline !== undefined) debug(carrier(path).lastError, path);
     const { text, rest } = page(held.merge(held.takeHeld(file), fresh));
     held.putBack(file, { messages: rest, events: [], dropped: {} });
     return { text, isError: false };
   };
   const handlers = {
     sigelo_invite: serial(({ name, ttl, long }, path) => {
-      if (long !== undefined && typeof long !== 'boolean') throw new Error('long: true or false');
+      if (long !== undefined && typeof long !== 'boolean') throw usage('long: true or false');
       return carrier(path).invite({ name, ttl, short: long !== true });
     }),
     // A code never contains whitespace; one pasted from a wrapped mail line may, and a short one
@@ -134,7 +137,11 @@ export async function load({ installed, id, env = process.env, clock }) {
     sigelo_contacts: (_, path) => { const r = carrier(path).contacts(); return { ...r, contacts: r.contacts.map((c) => ({ ...c, pair: pairOf(path, c.did) })) }; },
     sigelo_send: serial(({ to, text: t, label }, path) => carrier(path).send(text(to, 'to'), text(t, 'text'), { label: label ?? '' })),
     sigelo_inbox: serial(inbox),
-    sigelo_forget_contact: serial(({ did }, path) => carrier(path).forget(text(did, 'did'))),
+    sigelo_forget_contact: serial(async ({ did }, path) => {
+      const r = await carrier(path).forget(text(did, 'did'));
+      if (r.offline !== undefined) debug(carrier(path).lastError, path);
+      return r;
+    }),
   };
   return { tools: TOOLS, handlers };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigelo-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "mcpName": "io.github.csigelo/sigelo",
   "description": "MCP server: portable, offline-verifiable identity for AI agents (DID, challenges, attestations, bundles), optional Monero wallet",
   "keywords": [
@@ -43,8 +43,8 @@
     "prepublishOnly": "node -e \"if(process.env.SIGELO_PUBLISH!=='1'){console.error('refusing: the npm account and names are an Owner decision (ROADMAP D1); publish the release/build.sh tarballs with SIGELO_PUBLISH=1');process.exit(1)}\""
   },
   "dependencies": {
-    "sigelo": "^0.1.5",
-    "sigelo-agent": "^0.1.5",
-    "sigelo-spend": "^0.1.5"
+    "sigelo": "^0.1.6",
+    "sigelo-agent": "^0.1.6",
+    "sigelo-spend": "^0.1.6"
   }
 }

package/server.mjs

@@ -5,7 +5,8 @@
 // over the agent-side library in adapters/moadim and, when a keeper is configured, the
 // `sigelo-wallet` client in spend/. Zero dependencies of its own: no crypto here, only calls.
 // Transport: one JSON-RPC message per line on stdin/stdout; logs go to stderr only.
-import { dirname, join, sep } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // Installed (npm), the libraries are the packages sigelo, sigelo-agent and sigelo-spend; run
 // from a clone of the repository, they are the sibling directories, and the agent library runs
@@ -25,7 +26,7 @@ console.log = console.info = console.debug = console.error;
 
 const MODERN = ['2026-07-28'];                                            // per-request _meta era
 const LEGACY = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];  // initialize era
-const SERVER_INFO = { name: 'sigelo', version: '0.1.5' };
+const SERVER_INFO = { name: 'sigelo', version: '0.1.6' };
 const PV = 'io.modelcontextprotocol/protocolVersion';
 const env = process.env;
 const WALLET = Boolean(env.SIGELO_WALLET_URL && env.SIGELO_WALLET_TOKEN);
@@ -61,20 +62,52 @@ if (WALLET) TOOLS.push(
 );
 
 const base = id.identityPath();
+// A refusal the framework can branch on: .check is its stable code (the contact library's MsgError
+// carries one already), the message its one human line.
+const refusal = (check, message, cause) => Object.assign(new SigeloError(message, cause === undefined ? undefined : { cause }), { check });
 const pathOf = (name) => {
   if (name === undefined || name === '') return base;
-  if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name)) throw new SigeloError('identity must match [a-z0-9][a-z0-9_-]{0,63}');
+  if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name)) throw refusal('usage', `identity: ${JSON.stringify(name)} is not a profile name; it must match [a-z0-9][a-z0-9_-]{0,63}, e.g. "researcher-1"`);
   return join(dirname(base), `sigelo.${name}.local.json`);
 };
+// The profiles beside the default identity file, for a refusal naming one that is not there.
+const profiles = () => {
+  try {
+    return readdirSync(dirname(base)).map((f) => (f === basename(base) ? '(default)' : /^sigelo\.([a-z0-9][a-z0-9_-]{0,63})\.local\.json$/.exec(f)?.[1])).filter(Boolean);
+  } catch { return []; }
+};
 const nowS = () => Math.floor(Date.now() / 1000);
 const input = (v, name) => {
-  if (v === undefined || v === null) throw new SigeloError(`${name} is required`);
-  return typeof v === 'string' ? parse(v) : v; // text goes through sigelo's strict parser (dup keys rejected)
+  if (v === undefined || v === null) throw refusal('usage', `${name} is required`);
+  // text goes through sigelo's strict parser (dup keys rejected)
+  if (typeof v === 'string') { try { return parse(v); } catch (e) { throw refusal('json', `${name}: not strict JSON (${e.message})`, e); } }
+  return v;
 };
-const update = (path, fn) => withLock(path, () => { const { store, result } = fn(id.load(path)); id.save(path, store); return result; });
 const loadStore = (path) => {
-  try { return id.load(path); } catch (e) { throw new SigeloError(`no identity at ${path} — call sigelo_init once (${e.message})`); }
+  if (!existsSync(path)) {
+    const named = path === base ? '' : ` for the profile "${/^sigelo\.(.+)\.local\.json$/.exec(path.slice(dirname(path).length + 1))?.[1]}"`, have = profiles();
+    throw refusal('no_identity', `no identity${named} at ${path}: call sigelo_init once${named ? ' with the same identity' : ''}${have.length ? `, or use an existing profile: ${have.join(', ')}` : ''}`);
+  }
+  // There, but not loading: never "call sigelo_init", which would make another identity.
+  try { return id.load(path); } catch (e) { throw refusal('identity_unreadable', `identity file ${path} does not load (${e.message.split('\n')[0]}): restore it from your copy; do not call sigelo_init, which makes a new identity`, e); }
 };
+const update = (path, fn) => withLock(path, () => { const { store, result } = fn(loadStore(path)); id.save(path, store); return result; });
+// The stable code of any error a tool throws: its check, else by its class.
+const codeOf = (e) => (typeof e?.check === 'string' ? e.check
+  : { SigeloError: 'refused', MoneroError: 'refused', JcsError: 'json' }[e?.name] ?? (typeof e?.code === 'string' && /^E[A-Z]+$/.test(e.code) ? 'io' : 'error'));
+/** SIGELO_DEBUG=1: what is behind a refusal, on stderr (stdout is the protocol): the identity file,
+ *  the relay settings, the cause chain with the relay's HTTP answers, the stack. */
+function debug(e, path) {
+  if (env.SIGELO_DEBUG !== '1') return;
+  const say = (s) => process.stderr.write(`sigelo-mcp: debug: ${s}\n`);
+  if (path) say(`identity file ${path}${existsSync(path) ? '' : ', missing'}`);
+  say(`relay ${env.SIGELO_RELAY ?? '(default)'}${env.SIGELO_RELAY_ENDPOINTS ? ` endpoints ${env.SIGELO_RELAY_ENDPOINTS}` : ''}`);
+  for (let x = e, i = 0; x && i < 8; x = x.cause, i++) {
+    say(`${i ? 'caused by ' : 'error '}${x.name ?? typeof x}${x.check ? ` check=${x.check}` : ''}: ${x.message ?? String(x)}`);
+    if (x.http) say(`relay answer ${JSON.stringify(x.http)}`);
+  }
+  if (e?.stack) say(e.stack);
+}
 
 async function wallet(argv) {
   const w = await lib('sigelo-spend/dist/wallet.js', '../../spend/dist/wallet.js');
@@ -85,7 +118,7 @@ async function wallet(argv) {
 const HANDLERS = {
   sigelo_whoami: (_, path) => { const s = loadStore(path); return { did: did(id.head(s)), genesis: id.head(s), chain: id.chainOf(s), attestations: s.attestations.length, identity_file: path }; },
   sigelo_init: ({ recovery }, path) => {
-    if (typeof recovery !== 'string' || !recovery) throw new SigeloError('recovery is required: a "z…" public key or "none"');
+    if (typeof recovery !== 'string' || !recovery) throw refusal('usage', 'recovery is required: a "z…" public key or "none"');
     const s = id.init(path, recovery === 'none' ? null : recovery);
     return { did: did(s.genesis), genesis: s.genesis, identity_file: path,
       ...(recovery === 'none' && { warning: 'NO recovery key: if this key is stolen the identity is lost permanently.' }) };
@@ -117,18 +150,24 @@ const HANDLERS = {
 // otherwise, with one line on stderr, and a package that ships no contact.mjs gets null too. This
 // server never depends on them. Anything else wrong in them stops it: a broken install must not
 // pass for an absent one.
-const contact = await import('./contact.mjs').then((m) => m.load({ installed: INSTALLED, id }), (e) => { if (e.code === 'ERR_MODULE_NOT_FOUND') return null; throw e; });
+const contact = await import('./contact.mjs').then((m) => m.load({ installed: INSTALLED, id, debug }), (e) => { if (e.code === 'ERR_MODULE_NOT_FOUND') return null; throw e; });
 if (contact) { TOOLS.push(...contact.tools); Object.assign(HANDLERS, contact.handlers); }
 
 async function callTool(name, args) {
   if (!TOOLS.some(([n]) => n === name)) return null;
+  let path;
   try {
     const a = args ?? {};
-    const r = await HANDLERS[name](a, name.startsWith('sigelo_wallet_') || name === 'sigelo_verify' ? undefined : pathOf(a.identity));
+    path = name.startsWith('sigelo_wallet_') || name === 'sigelo_verify' ? undefined : pathOf(a.identity);
+    const r = await HANDLERS[name](a, path);
     if (r && typeof r.text === 'string' && 'isError' in r) return { content: [{ type: 'text', text: r.text }], structuredContent: r.structured, isError: r.isError };
     return { content: [{ type: 'text', text: JSON.stringify(r, null, 2) }], isError: false };
   } catch (e) {
-    return { content: [{ type: 'text', text: `REFUSED: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    // The message, never the stack (SIGELO_DEBUG=1 puts that on stderr); code: stable, to branch on.
+    const message = e instanceof Error ? e.message : String(e), code = codeOf(e);
+    debug(e, path);
+    // long: the long code a spent short code stood for (contact/carrier.mjs keepLong): keep it.
+    return { content: [{ type: 'text', text: `REFUSED: ${message}` }], structuredContent: { code, message, ...(typeof e?.long === 'string' && { long: e.long }) }, isError: true };
   }
 }