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

package/packages/onboarding/service.mjs

@@ -0,0 +1,235 @@
+import { join } from 'node:path';
+import { CredentialStore, digest, protectedDirectory, SafeError } from './storage.mjs';
+import { ApiError, configuredOrigin, post, serviceUrl } from './network.mjs';
+import { pluginVersion } from './version.mjs';
+
+const string = (maxLength = 200) => ({ type: 'string', minLength: 1, maxLength });
+const schema = properties => ({ type: 'object', properties, required: Object.keys(properties), additionalProperties: false });
+export const onboardingTools = [
+  { name: 'wacando_verify_installation', description: 'Verify this installed plugin with the Wacando installation prompt. Saves credentials privately; returns only installation status, ID and plugin version.', inputSchema: schema({ verificationUrl: string(2048), challenge: string(512), protocolVersion: { type: 'integer', enum: [1] } }) },
+  { name: 'wacando_enroll_agent', description: 'Redeem a temporary enrollment token and connect with XMPP/OMEMO. Repeated calls resume using the saved credential without redeeming again. Never returns secrets.', inputSchema: schema({ apiBaseUrl: string(2048), agentId: string(), handle: string(), installationId: string(), enrollmentToken: string(512) }) },
+];
+const identifier = value => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,200}$/.test(value);
+const secret = (value, prefix) => typeof value === 'string' && value.startsWith(prefix) && /^[a-zA-Z0-9_.-]{8,512}$/.test(value);
+const lostEnrollment = 'Enrollment result was not safely saved. Check the agent status on the site. If the token was consumed and no durable credential was saved, revoke this identity and create a new one with a different handle. No automatic recovery exists in v1.';
+export const SESSION_REPLACED = 'SESSION_REPLACED: this identity was taken over by a newer session elsewhere (one session per agent). Nothing reconnects automatically; restart this runtime to take it back.';
+const retryConnection = 'Agent credential is saved, but connection was not confirmed. Automatic retry is scheduled while this MCP host stays open. The same enrollment tool can also resume without consuming the temporary token or recreating the agent.';
+
+export class OnboardingService {
+  constructor({ host, origin, store = new CredentialStore(), request = post, connect,
+    schedule = setTimeout, cancel = clearTimeout, random = Math.random, onStanza, onSession,
+    report = event => process.stderr.write(`${JSON.stringify({ component: 'wacando-connection', ...event })}\n`) } = {}) {
+    this.host = host;
+    this.originSetting = origin;
+    this.store = store;
+    this.request = request;
+    this.connect = connect ?? (async options => (await import('../runtime/session.mjs')).connectSession(options));
+    this.sessions = new Map();
+    this.timers = new Map();
+    this.failures = new Map();
+    this.states = new Map();
+    this.recoveries = new Set();
+    // Identities whose session the server replaced (<conflict/>): terminal for
+    // this process, so two runtimes never steal the session from each other.
+    this.replaced = new Set();
+    this.schedule = schedule; this.cancel = cancel; this.random = random; this.report = report;
+    this.onStanza = onStanza;
+    this.onSession = onSession;
+    this.closed = false;
+  }
+  origin(value) {
+    const expected = configuredOrigin(this.originSetting);
+    const url = serviceUrl(value, { development: expected.startsWith('http:') });
+    if (url.origin !== expected) throw new SafeError('Service origin does not match WACANDO_API_ORIGIN. Configure the intended service origin in this MCP host and reload before using its prompt.');
+    return url;
+  }
+  async verify(args) {
+    const url = this.origin(args.verificationUrl);
+    const match = /^\/v1\/users\/[a-z0-9][a-z0-9_-]{0,31}\/installations\/([a-zA-Z0-9_-]{1,200})\/verify$/.exec(url.pathname);
+    if (!match || args.protocolVersion !== 1 || !secret(args.challenge, 'wacinst_')) throw new SafeError('Invalid installation prompt. Generate a new installation prompt on the site.');
+    const id = match[1];
+    return this.store.lock(url.origin, this.host, 'installation', id, async () => {
+      if (await this.store.read(url.origin, this.host, 'installation', id)) {
+        throw new SafeError('Installation is already verified locally. Continue with the agent enrollment prompt; do not replay the challenge.');
+      }
+      let data;
+      try { data = await this.request(url, args.challenge, { protocolVersion: 1, pluginVersion }); }
+      catch (error) {
+        if (error instanceof ApiError && error.status === 400) throw new SafeError('Installation protocol was rejected. Update the plugin and generate a new installation prompt.');
+        throw new SafeError('Installation verification failed or its response was lost. The challenge may be expired or used. Generate a new installation prompt on the site.');
+      }
+      if (data?.installationId !== id || !secret(data?.installationCredential, 'waciacc_')) throw new SafeError('Invalid installation response. Generate a new installation prompt on the site.');
+      try { await this.store.write(url.origin, this.host, 'installation', id, { origin: url.origin, installationId: id, installationCredential: data.installationCredential }); }
+      catch { throw new SafeError('Installation response could not be saved safely. Repair local storage, then generate a new installation prompt on the site.'); }
+      return { verified: true, installationId: id, pluginVersion };
+    });
+  }
+  async enroll(args) {
+    const url = this.origin(args.apiBaseUrl);
+    if (url.pathname !== '/' || !identifier(args.agentId) || !identifier(args.installationId) ||
+        !/^@[a-z0-9][a-z0-9_-]{0,31}\/[a-z0-9][a-z0-9_-]{0,31}$/.test(args.handle)) throw new SafeError('Invalid enrollment prompt. Request a new enrollment prompt from the site.');
+    return this.store.lock(url.origin, this.host, 'agent', args.agentId, async () => {
+      const installation = await this.store.read(url.origin, this.host, 'installation', args.installationId);
+      if (installation?.origin !== url.origin || installation.installationId !== args.installationId || !secret(installation.installationCredential, 'waciacc_')) {
+        throw new SafeError('Installation not found for this service and host. Use the installation selected on the site and verify it in this host first.');
+      }
+      let agent = await this.store.read(url.origin, this.host, 'agent', args.agentId);
+      if (agent && (agent.origin !== url.origin || agent.agentId !== args.agentId || agent.handle !== args.handle || agent.installationId !== args.installationId)) throw new SafeError('Saved identity does not match this prompt. Use the installation and identity selected on the site.');
+      if (agent?.revoked) throw new SafeError('Agent revoked. Connection attempts have stopped. Create a new identity on the site.');
+      if (!agent) {
+        if (!secret(args.enrollmentToken, 'agtenr_')) throw new SafeError('Invalid temporary token. Request a new enrollment prompt on the site.');
+        let data;
+        try { data = await this.request(new URL(`/v1/agents/${args.agentId}/enroll`, url), args.enrollmentToken, undefined, installation.installationCredential); }
+        catch (error) {
+          if (error instanceof ApiError) {
+            if (error.code === 'AGENT_REVOKED') {
+              await this.store.write(url.origin, this.host, 'agent', args.agentId, { origin: url.origin, agentId: args.agentId, handle: args.handle, installationId: args.installationId, revoked: true });
+              throw new SafeError('Agent revoked. Connection attempts have stopped.');
+            }
+            if (error.status === 401) throw new SafeError('Temporary token expired, used or invalid. Request a new enrollment prompt. If the site says already enrolled and no credential was saved, revoke this identity and create a new one with a different handle.');
+            if (error.status === 403) throw new SafeError('Wrong installation or account. Use the installation selected on the site.');
+            if (error.status === 400) throw new SafeError('Enrollment input was rejected. Request a corrected enrollment prompt.');
+          }
+          throw new SafeError(lostEnrollment);
+        }
+        if (data?.agentId !== args.agentId || data.handle !== args.handle || !secret(data.agentToken, 'agtacc_')) throw new SafeError(lostEnrollment);
+        agent = { origin: url.origin, agentId: args.agentId, handle: args.handle, installationId: args.installationId, agentToken: data.agentToken, xmpp: data.xmpp };
+        // Persist the durable credential BEFORE validating transport metadata or opening a socket.
+        try { await this.store.write(url.origin, this.host, 'agent', args.agentId, agent); }
+        catch { throw new SafeError(lostEnrollment); }
+      }
+      if (!secret(agent.agentToken, 'agtacc_')) throw new SafeError('Saved agent credential is invalid. Preserve local state and check the identity status on the site.');
+      await this.open(agent);
+      return { handle: agent.handle, connected: true };
+    });
+  }
+  async disconnect(id) {
+    this.cancel(this.timers.get(id)); this.timers.delete(id);
+    const session = this.sessions.get(id); this.sessions.delete(id);
+    await session?.stop().catch(() => {});
+  }
+  status(agent, state, step, retryInMs) {
+    const value = { agentId: agent.agentId, state, step, ...(retryInMs === undefined ? {} : { retryInMs }) };
+    this.states.set(agent.agentId, value);
+    // Only locally authored enums and public IDs enter diagnostics, never exceptions.
+    this.report(value);
+  }
+  later(agent, delay) {
+    if (this.closed) return;
+    this.cancel(this.timers.get(agent.agentId));
+    const timer = this.schedule(async () => {
+      this.timers.delete(agent.agentId);
+      if (this.closed) return;
+      const recovery = this.store.lock(agent.origin, this.host, 'agent', agent.agentId, () => this.open(agent));
+      this.recoveries.add(recovery);
+      try { await recovery; }
+      catch {
+        // open() schedules network recovery itself. Lock/storage failures also
+        // remain observable and retryable, except after terminal access rejection.
+        if (!this.closed && !this.timers.has(agent.agentId) && !['revoked', 'replaced'].includes(this.states.get(agent.agentId)?.state)) this.retry(agent, 'local operation');
+      }
+      finally { this.recoveries.delete(recovery); }
+    }, delay);
+    timer.unref?.(); this.timers.set(agent.agentId, timer);
+  }
+  retry(agent, phase) {
+    if (this.closed) return;
+    const count = (this.failures.get(agent.agentId) ?? 0) + 1;
+    this.failures.set(agent.agentId, count);
+    const delay = Math.min(60000, 1000 * 2 ** Math.min(count - 1, 6)) * (0.8 + this.random() * 0.2);
+    this.status(agent, 'retrying', phase, Math.round(delay));
+    this.later(agent, delay);
+  }
+  /** The server replaced this identity's session: stop for good in this process. */
+  async markReplaced(agent, phase = 'XMPP session') {
+    if (this.replaced.has(agent.agentId)) return;
+    this.replaced.add(agent.agentId);
+    this.cancel(this.timers.get(agent.agentId)); this.timers.delete(agent.agentId);
+    this.status(agent, 'replaced', phase);
+    await this.disconnect(agent.agentId);
+  }
+  async open(agent) {
+    this.cancel(this.timers.get(agent.agentId)); this.timers.delete(agent.agentId);
+    let release;
+    let phase = 'local identity';
+    if (this.replaced.has(agent.agentId) || this.sessions.get(agent.agentId)?.session?.isReplaced?.()) {
+      await this.markReplaced(agent);
+      throw new SafeError(SESSION_REPLACED);
+    }
+    try {
+      if (this.closed) throw new Error();
+      let active = this.sessions.get(agent.agentId);
+      if (active?.isOnline?.() === false) { await this.disconnect(agent.agentId); active = null; }
+      if (!active) {
+        release = await this.store.acquire(agent.origin, this.host, 'session', agent.agentId);
+        if (this.closed) throw new Error();
+        const xmpp = agent.xmpp;
+        if (!xmpp || typeof xmpp.domain !== 'string' || !/^[a-z0-9.-]+$/.test(xmpp.domain)) throw new Error();
+        const destination = serviceUrl(xmpp.service, { websocket: true, development: agent.origin.startsWith('http:') });
+        phase = 'XMPP grant';
+        const response = await this.request(new URL('/v1/xmpp/session', agent.origin), agent.agentToken, { agentId: agent.agentId });
+        if (this.closed) throw new Error();
+        const grant = response?.grant;
+        const remaining = Date.parse(grant?.expiresAt) - Date.now();
+        if (grant?.agentId !== agent.agentId || typeof grant.credential !== 'string' || !grant.credential.length || !(remaining > 5000)) throw new Error();
+        const base = await this.store.directory(agent.origin, this.host);
+        const stateBaseDir = await protectedDirectory(join(base, `omemo-${digest(agent.agentId)}`));
+        phase = 'XMPP connection';
+        const session = await this.connect({ jid: `agt_${agent.agentId}@${xmpp.domain}`, password: grant.credential, service: destination.href, stateBaseDir,
+          onReplaced: () => { void this.markReplaced(agent); },
+          ...(this.onStanza ? { onStanza: (stanza, xmpp) => this.onStanza(agent.agentId, stanza, xmpp) } : {}) });
+        const releaseSession = release; release = null;
+        active = { session, isOnline: () => session.isOnline?.() !== false, ping: () => session.ping?.(), stop: async () => { try { await session.stop(); } finally { await releaseSession(); } } };
+        this.sessions.set(agent.agentId, active);
+        this.onSession?.(agent.agentId, session);
+        if (this.closed) throw new Error();
+        phase = 'OMEMO device publication';
+        await session.registerDevice();
+        if (this.closed || session.isOnline?.() === false || Date.parse(grant.expiresAt) <= Date.now()) throw new Error();
+        active.registered = true;
+      }
+      phase = 'XMPP heartbeat';
+      await active.ping();
+      phase = 'connection callback';
+      const confirmation = await this.request(new URL(`/v1/agents/${agent.agentId}/connected`, agent.origin), agent.agentToken);
+      if (confirmation?.connected !== true) throw new Error();
+      this.failures.delete(agent.agentId);
+      if (!this.closed) {
+        this.status(agent, 'connected', 'connection callback');
+        // The v1 grant TTL bounds NEW authentication, not the lifetime of a
+        // bound XMPP stream. Heartbeat checks durable access without rotating
+        // the XMPP password or tearing down a healthy session.
+        this.later(agent, 60000);
+      }
+    } catch (error) {
+      await release?.();
+      if (error instanceof ApiError && (error.code === 'AGENT_REVOKED' || error.status === 401 || error.status === 403)) {
+        await this.disconnect(agent.agentId);
+        this.status(agent, 'revoked', phase);
+        await this.store.write(agent.origin, this.host, 'agent', agent.agentId, { ...agent, revoked: true });
+        throw new SafeError('Agent revoked or durable access rejected. Connection attempts have stopped. Check the identity on the site.');
+      }
+      const active = this.sessions.get(agent.agentId);
+      if (this.replaced.has(agent.agentId) || active?.session?.isReplaced?.()) {
+        // Another process took this identity over (newest session wins). Never
+        // log back in automatically: that would replace it in turn, in a loop.
+        await this.markReplaced(agent, phase);
+        throw new SafeError(SESSION_REPLACED);
+      }
+      if (!active?.registered || active.isOnline() === false || phase === 'XMPP heartbeat' || this.closed) await this.disconnect(agent.agentId);
+      this.retry(agent, phase);
+      throw new SafeError(`${retryConnection} Failed step: ${phase}${error instanceof ApiError ? ` (HTTP ${error.status})` : ''}.`);
+    }
+  }
+  async call(name, args) {
+    try { return await (name === 'wacando_verify_installation' ? this.verify(args) : this.enroll(args)); }
+    catch (error) { throw error instanceof SafeError ? error : new SafeError('Onboarding failed. Check local state permissions and service availability; no success is confirmed.'); }
+  }
+  async close() {
+    this.closed = true;
+    for (const timer of this.timers.values()) this.cancel(timer);
+    this.timers.clear();
+    await Promise.allSettled([...this.recoveries]);
+    await Promise.all([...this.sessions.keys()].map(id => this.disconnect(id)));
+  }
+}

package/packages/onboarding/storage.mjs

@@ -0,0 +1,99 @@
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, readdir, rename, unlink } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export class SafeError extends Error {}
+export const storageError = () => new SafeError('Protected local state is unavailable. Check ownership and permissions; preserve existing credentials and encryption keys.');
+
+export async function protectedDirectory(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  const stat = await lstat(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) ||
+      (process.getuid && stat.uid !== process.getuid())) throw storageError();
+  return path;
+}
+
+export class CredentialStore {
+  // 2.x keeps the 1.x default directory so that saved classic identities are
+  // detected and refused with migration guidance instead of silently ignored.
+  constructor(root = process.env.WACANDO_AGENT_STATE_DIR ?? process.env.WACANDO_PLUGIN_STATE_DIR ?? join(homedir(), '.wacando-plugin')) {
+    this.root = resolve(root);
+  }
+  async directory(origin, host) {
+    await protectedDirectory(this.root);
+    return protectedDirectory(join(this.root, digest(`${origin}\n${host}`)));
+  }
+  async location(origin, host, kind, id) {
+    return join(await this.directory(origin, host), `${kind}-${digest(id)}.json`);
+  }
+  async read(origin, host, kind, id) {
+    const path = await this.location(origin, host, kind, id);
+    let file;
+    try {
+      file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size > 65536 || (stat.mode & 0o077) ||
+          (process.getuid && stat.uid !== process.getuid())) throw storageError();
+      return JSON.parse(await file.readFile('utf8'));
+    } catch (error) {
+      if (error.code === 'ENOENT') return null;
+      throw storageError();
+    } finally { await file?.close(); }
+  }
+  /** Every saved record of one kind for this service origin and host. */
+  async list(origin, host, kind) {
+    const directory = await this.directory(origin, host);
+    const names = (await readdir(directory)).filter(name => new RegExp(`^${kind}-[0-9a-f]{64}\\.json$`).test(name));
+    const records = [];
+    for (const name of names.sort()) {
+      let file;
+      try {
+        file = await open(join(directory, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 65536 || (stat.mode & 0o077) ||
+            (process.getuid && stat.uid !== process.getuid())) throw storageError();
+        records.push(JSON.parse(await file.readFile('utf8')));
+      } catch { throw storageError(); }
+      finally { await file?.close(); }
+    }
+    return records;
+  }
+  async write(origin, host, kind, id, value) {
+    const path = await this.location(origin, host, kind, id);
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    let file;
+    try {
+      file = await open(tmp, 'wx', 0o600);
+      await file.writeFile(JSON.stringify(value));
+      await file.sync();
+      await file.close(); file = null;
+      await rename(tmp, path);
+      const directory = await open(await this.directory(origin, host), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    } catch { throw storageError(); }
+    finally { await file?.close(); await unlink(tmp).catch(() => {}); }
+  }
+  /** Remove a record (and nothing else). Missing records are fine. */
+  async remove(origin, host, kind, id) {
+    try {
+      await unlink(await this.location(origin, host, kind, id));
+      const directory = await open(await this.directory(origin, host), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    } catch (error) { if (error.code !== 'ENOENT') throw storageError(); }
+  }
+  async acquire(origin, host, kind, id) {
+    const path = `${await this.location(origin, host, kind, id)}.lock`;
+    let file;
+    try { file = await open(path, 'wx', 0o600); }
+    catch { throw new SafeError('This identity is locked by another operation. If its MCP process crashed, stop that process and remove only its stale .lock file before retrying.'); }
+    return async () => { await file.close(); await unlink(path); };
+  }
+  async lock(origin, host, kind, id, action) {
+    const release = await this.acquire(origin, host, kind, id);
+    try { return await action(); }
+    finally { await release(); }
+  }
+}

package/packages/onboarding/version.mjs

@@ -0,0 +1,2 @@
+// Must match all distributed plugin manifests; checked by the test suite.
+export const pluginVersion = '2.0.0-rc.1';