@truealter/sdk 0.2.4 → 0.4.1

package/dist/bin/alter-identity.js

@@ -1,11 +1,158 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
-import { join, dirname } from 'path';
-import { env, stderr, exit, argv, stdout } from 'process';
+import { p256 } from '@noble/curves/p256';
+import { sha256 } from '@noble/hashes/sha256';
+import { hexToBytes, bytesToHex as bytesToHex$1, randomBytes } from '@noble/hashes/utils';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, renameSync, copyFileSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join, dirname, resolve } from 'path';
+import { env, stderr, exit, argv, stdout, stdin } from 'process';
+import { createInterface } from 'readline';
 import * as ed25519 from '@noble/ed25519';
 import { sha512 } from '@noble/hashes/sha512';
-import { hexToBytes, bytesToHex, randomBytes } from '@noble/hashes/utils';
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/signing.ts
+var signing_exports = {};
+__export(signing_exports, {
+  canonicalArgsSha256: () => canonicalArgsSha256,
+  canonicalStringify: () => canonicalStringify,
+  loadPrivateKey: () => loadPrivateKey,
+  signInvocation: () => signInvocation
+});
+function canonicalStringify(value) {
+  return stringifyInner(value);
+}
+function stringifyInner(value) {
+  if (value === null) return "null";
+  if (value === void 0) {
+    throw new TypeError("canonicalStringify: undefined is not representable in JSON");
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("canonicalStringify: non-finite numbers are not representable");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return encodeString(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => stringifyInner(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map((k) => encodeString(k) + ":" + stringifyInner(obj[k])).join(",") + "}";
+  }
+  throw new TypeError(`canonicalStringify: unsupported type ${typeof value}`);
+}
+function encodeString(s) {
+  return JSON.stringify(s);
+}
+function canonicalArgsSha256(toolArgs) {
+  const canonical = canonicalStringify(toolArgs ?? {});
+  const bytes = new TextEncoder().encode(canonical);
+  const digest = sha256(bytes);
+  return bytesToHex(digest);
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function base64urlEncode(bytes) {
+  const raw = typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes;
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(raw).toString("base64url");
+  }
+  let binary = "";
+  for (let i = 0; i < raw.length; i++) binary += String.fromCharCode(raw[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function loadPrivateKey(key) {
+  if (key instanceof Uint8Array) {
+    if (key.length !== 32) {
+      throw new TypeError("ES256 raw private key must be 32 bytes.");
+    }
+    return key;
+  }
+  if (typeof key === "string" && key.includes("-----BEGIN")) {
+    const nodeCrypto = __require("crypto");
+    const keyObj = nodeCrypto.createPrivateKey({ key, format: "pem" });
+    const jwk = keyObj.export({ format: "jwk" });
+    if (jwk.crv !== "P-256" || !jwk.d) {
+      throw new TypeError("PEM is not a P-256 private key.");
+    }
+    return base64urlDecodeToBytes(jwk.d);
+  }
+  throw new TypeError("loadPrivateKey: expected Uint8Array(32) or PEM string.");
+}
+function base64urlDecodeToBytes(s) {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  const b64 = (s + pad).replace(/-/g, "+").replace(/_/g, "/");
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function signInvocation(toolName, toolArgs, options) {
+  const { kid, privateKey, handle } = options;
+  const nonce = options.nonce ?? base64urlEncode(randomBytes(24));
+  const iat = options.iatSeconds ?? Math.floor(Date.now() / 1e3);
+  const claims = {
+    tool: toolName,
+    args_sha256: canonicalArgsSha256(toolArgs ?? {}),
+    nonce,
+    iat,
+    iss: handle
+  };
+  const headerB64 = base64urlEncode(JSON.stringify({ alg: "ES256", kid }));
+  const payloadB64 = base64urlEncode(JSON.stringify(claims));
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signingBytes = new TextEncoder().encode(signingInput);
+  const dBytes = loadPrivateKey(privateKey);
+  const digest = sha256(signingBytes);
+  const sig = p256.sign(digest, dBytes, { prehash: false });
+  const sigBytes = sig.toCompactRawBytes();
+  const sigB64 = base64urlEncode(sigBytes);
+  return `${signingInput}.${sigB64}`;
+}
+var init_signing = __esm({
+  "src/signing.ts"() {
+  }
+});
 
 // src/errors.ts
 var AlterError = class extends Error {
@@ -106,7 +253,12 @@ async function discover(domain, opts = {}) {
     try {
       const dnsHit = await tryDns(host);
       if (dnsHit) {
-        const result = { url: dnsHit, transport: "streamable-http", source: "dns" };
+        const parsed = validateDiscoveredUrl(dnsHit, "dns");
+        const result = {
+          url: parsed.toString().replace(/\/$/, ""),
+          transport: "streamable-http",
+          source: "dns"
+        };
         if (cache) _cache.set(host, result);
         return result;
       }
@@ -144,6 +296,28 @@ function normaliseDomain(input) {
   if (!host) throw new AlterDiscoveryError(`Empty domain: "${input}"`);
   return host;
 }
+function validateDiscoveredUrl(url, source) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new AlterDiscoveryError(`${source}: malformed URL ${url}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new AlterDiscoveryError(
+      `${source}: non-https MCP endpoint rejected (got ${parsed.protocol}//${parsed.hostname})`
+    );
+  }
+  if (parsed.username || parsed.password) {
+    throw new AlterDiscoveryError(
+      `${source}: MCP endpoint must not contain userinfo (user:pass@host)`
+    );
+  }
+  if (!parsed.hostname) {
+    throw new AlterDiscoveryError(`${source}: MCP endpoint missing hostname`);
+  }
+  return parsed;
+}
 async function tryDns(host) {
   let resolveTxt;
   try {
@@ -204,14 +378,17 @@ async function tryWellKnown(host, file, timeoutMs, fetchImpl) {
   if (file === "mcp.json") {
     const remotes = doc.remotes || [];
     const remote = remotes.find((r) => r.transportType === "streamable-http" || r.transportType === "http");
-    const url2 = remote?.url || doc.url;
-    if (!url2) return null;
-    return { url: url2, transport: "streamable-http", source: "mcp.json", raw: doc };
+    const rawUrl = remote?.url || doc.url;
+    if (!rawUrl) return null;
+    const parsed = validateDiscoveredUrl(rawUrl, "mcp.json");
+    return { url: parsed.toString().replace(/\/$/, ""), transport: "streamable-http", source: "mcp.json", raw: doc };
   }
   const mcpHost = doc.mcp;
   if (!mcpHost) return null;
+  const normalised = ensureMcpPath(mcpHost);
+  validateDiscoveredUrl(normalised, "alter.json");
   return {
-    url: ensureMcpPath(mcpHost),
+    url: normalised,
     transport: "streamable-http",
     source: "alter.json",
     publicKey: doc.pk,
@@ -257,11 +434,14 @@ var X402Client = class {
     if (!this.assets.has(envelope.asset)) {
       throw new AlterError("PAYMENT_REQUIRED", `asset ${envelope.asset} not permitted by client policy`);
     }
-    if (this.maxPerQuery !== void 0 && Number(envelope.amount) > this.maxPerQuery) {
-      throw new AlterError(
-        "PAYMENT_REQUIRED",
-        `quote ${envelope.amount} ${envelope.asset} exceeds maxPerQuery ${this.maxPerQuery}`
-      );
+    if (this.maxPerQuery !== void 0) {
+      const amt = Number(envelope.amount);
+      if (!Number.isFinite(amt) || amt < 0 || amt > this.maxPerQuery) {
+        throw new AlterError(
+          "PAYMENT_REQUIRED",
+          `quote ${envelope.amount} ${envelope.asset} exceeds maxPerQuery ${this.maxPerQuery}`
+        );
+      }
     }
     if (!this.signer) {
       throw new AlterPaymentRequired(envelope.resource ?? "unknown", envelope);
@@ -319,6 +499,7 @@ var MCPClient = class {
   maxRetries;
   clientInfo;
   x402;
+  signing;
   requestCounter = 0;
   initialised = false;
   constructor(opts = {}) {
@@ -329,6 +510,7 @@ var MCPClient = class {
     this.maxRetries = opts.maxRetries ?? 2;
     this.clientInfo = opts.clientInfo ?? { name: "@truealter/sdk", version: "0.2.0" };
     this.x402 = opts.x402;
+    this.signing = opts.signing;
   }
   /**
    * Send the MCP `initialize` handshake and capture the resulting session
@@ -415,6 +597,7 @@ var MCPClient = class {
       method
     };
     if (params !== void 0) payload.params = params;
+    const signatureHeader = this.buildSignatureHeader(method, params);
     let attempt = 0;
     let lastErr = null;
     while (attempt <= this.maxRetries) {
@@ -425,7 +608,7 @@ var MCPClient = class {
       try {
         resp = await this.fetchImpl(this.endpoint, {
           method: "POST",
-          headers: this.buildHeaders(),
+          headers: this.buildHeaders(signatureHeader),
           body: JSON.stringify(payload),
           signal: controller.signal
         });
@@ -452,7 +635,8 @@ var MCPClient = class {
         throw new AlterPaymentRequired(this.guessToolName(payload), envelope);
       }
       if (resp.status === 429) {
-        const retryAfter = Number(resp.headers.get("Retry-After") ?? 60);
+        const rawRetryAfter = Number(resp.headers.get("Retry-After") ?? 60);
+        const retryAfter = Number.isFinite(rawRetryAfter) && rawRetryAfter >= 0 ? Math.min(rawRetryAfter, 300) : 60;
         if (attempt > this.maxRetries) {
           throw new AlterRateLimited(`HTTP 429 on ${method}`, retryAfter);
         }
@@ -488,7 +672,7 @@ var MCPClient = class {
     }
     throw lastErr ?? new AlterNetworkError(`MCP ${method}: exhausted retries`);
   }
-  buildHeaders() {
+  buildHeaders(extra) {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json",
@@ -496,8 +680,27 @@ var MCPClient = class {
     };
     if (this.apiKey) headers["X-ALTER-API-Key"] = this.apiKey;
     if (this.sessionId) headers["Mcp-Session-Id"] = this.sessionId;
+    if (extra) Object.assign(headers, extra);
     return headers;
   }
+  /**
+   * Produce the `Mcp-Invocation-Signature` header for a `tools/call`
+   * payload, when signing is configured. Returns `undefined` when no
+   * signing key is attached or the method is not `tools/call`.
+   */
+  buildSignatureHeader(method, params) {
+    if (!this.signing) return void 0;
+    if (method !== "tools/call") return void 0;
+    const p = params;
+    if (!p?.name) return void 0;
+    const { signInvocation: signInvocation2 } = (init_signing(), __toCommonJS(signing_exports));
+    const headerValue = signInvocation2(p.name, p.arguments ?? {}, {
+      kid: this.signing.kid,
+      privateKey: this.signing.privateKey,
+      handle: this.signing.handle
+    });
+    return { "Mcp-Invocation-Signature": headerValue };
+  }
   async extractPaymentEnvelope(resp) {
     const headerValue = resp.headers.get("X-402-Payment") ?? resp.headers.get("x-402-payment");
     if (headerValue) {
@@ -540,8 +743,8 @@ function generateKeypair() {
   const privateKey = randomBytes(32);
   const publicKey = ed25519.getPublicKey(privateKey);
   return {
-    privateKey: bytesToHex(privateKey),
-    publicKey: bytesToHex(publicKey),
+    privateKey: bytesToHex$1(privateKey),
+    publicKey: bytesToHex$1(publicKey),
     did: encodeDid(publicKey)
   };
 }
@@ -553,15 +756,15 @@ function keypairFromPrivateKey(privateKeyHex) {
   const publicKey = ed25519.getPublicKey(privateKey);
   return {
     privateKey: privateKeyHex,
-    publicKey: bytesToHex(publicKey),
+    publicKey: bytesToHex$1(publicKey),
     did: encodeDid(publicKey)
   };
 }
 function encodeDid(publicKey) {
   const bytes = typeof publicKey === "string" ? hexToBytes(publicKey) : publicKey;
-  return `ed25519:${base64urlEncode(bytes)}`;
+  return `ed25519:${base64urlEncode2(bytes)}`;
 }
-function base64urlEncode(bytes) {
+function base64urlEncode2(bytes) {
   let b64;
   if (typeof Buffer !== "undefined") {
     b64 = Buffer.from(bytes).toString("base64");
@@ -1054,9 +1257,460 @@ function generateCursorConfig(opts = {}) {
   return generateGenericMcpConfig({ serverName: "alter", ...opts });
 }
 
-// src/index.ts
+// src/adapters/claude-desktop.ts
+function generateClaudeDesktopConfig(opts = {}) {
+  const serverName = opts.serverName ?? "alter";
+  const bridgeCommand = opts.bridgeCommand ?? "alter-mcp-bridge";
+  const env3 = {};
+  env3.ALTER_MCP_ENDPOINT = opts.endpoint ?? DEFAULT_ENDPOINT;
+  if (opts.apiKey) env3.ALTER_API_KEY = opts.apiKey;
+  const entry = {
+    command: bridgeCommand,
+    env: env3,
+    description: "ALTER Identity \u2014 psychometric identity field for AI agents"
+  };
+  if (opts.extraArgs && opts.extraArgs.length > 0) {
+    entry.args = [...opts.extraArgs];
+  }
+  return { mcpServers: { [serverName]: entry } };
+}
+
+// src/meta.ts
 var SDK_NAME = "@truealter/sdk";
-var SDK_VERSION = "0.2.4";
+var SDK_VERSION = "0.3.0";
+var HOME = homedir();
+var PLAT = platform();
+function appData() {
+  return env.APPDATA ?? join(HOME, "AppData", "Roaming");
+}
+function xdgConfig() {
+  return env.XDG_CONFIG_HOME ?? join(HOME, ".config");
+}
+function macAppSupport() {
+  return join(HOME, "Library", "Application Support");
+}
+function claudeDesktopConfigPath() {
+  if (PLAT === "darwin") return join(macAppSupport(), "Claude", "claude_desktop_config.json");
+  if (PLAT === "win32") return join(appData(), "Claude", "claude_desktop_config.json");
+  return join(xdgConfig(), "Claude", "claude_desktop_config.json");
+}
+function claudeDesktopDir() {
+  if (PLAT === "darwin") return join(macAppSupport(), "Claude");
+  if (PLAT === "win32") return join(appData(), "Claude");
+  return join(xdgConfig(), "Claude");
+}
+function vscodeConfigPath() {
+  if (PLAT === "darwin") return join(macAppSupport(), "Code", "User", "mcp.json");
+  if (PLAT === "win32") return join(appData(), "Code", "User", "mcp.json");
+  return join(xdgConfig(), "Code", "User", "mcp.json");
+}
+function vscodeDir() {
+  if (PLAT === "darwin") return join(macAppSupport(), "Code", "User");
+  if (PLAT === "win32") return join(appData(), "Code", "User");
+  return join(xdgConfig(), "Code", "User");
+}
+var cursorDir = join(HOME, ".cursor");
+var cursorConfigPath = join(cursorDir, "mcp.json");
+var claudeCodeProbeDir = join(HOME, ".claude");
+var CLAUDE_CODE = {
+  id: "claude-code",
+  label: "Claude Code",
+  configPath: null,
+  probeDir: claudeCodeProbeDir,
+  rootKey: "mcpServers"
+};
+var CURSOR = {
+  id: "cursor",
+  label: "Cursor",
+  configPath: cursorConfigPath,
+  probeDir: cursorDir,
+  rootKey: "mcpServers"
+};
+var CLAUDE_DESKTOP = {
+  id: "claude-desktop",
+  label: "Claude Desktop",
+  configPath: claudeDesktopConfigPath(),
+  probeDir: claudeDesktopDir(),
+  rootKey: "mcpServers"
+};
+var VSCODE = {
+  id: "vscode",
+  label: "VS Code",
+  configPath: vscodeConfigPath(),
+  probeDir: vscodeDir(),
+  // VS Code's user-scoped mcp.json uses `servers`, not `mcpServers`.
+  rootKey: "servers"
+};
+var ALL_CLIENTS = [CLAUDE_CODE, CURSOR, CLAUDE_DESKTOP, VSCODE];
+function alterConfigDir() {
+  return join(xdgConfig(), "alter");
+}
+function wireStatePath() {
+  return join(alterConfigDir(), "wire-state.json");
+}
+function probeClaudeCode() {
+  try {
+    const result = spawnSync("claude", ["--version"], {
+      encoding: "utf8",
+      shell: process.platform === "win32",
+      timeout: 5e3
+    });
+    if (result.error) {
+      return {
+        client: ALL_CLIENTS.find((c) => c.id === "claude-code"),
+        installed: false,
+        reason: `claude binary not on PATH (${result.error.message})`
+      };
+    }
+    if (result.status === 0) {
+      return {
+        client: ALL_CLIENTS.find((c) => c.id === "claude-code"),
+        installed: true,
+        version: result.stdout.trim() || void 0,
+        reason: "claude --version returned 0"
+      };
+    }
+    return {
+      client: ALL_CLIENTS.find((c) => c.id === "claude-code"),
+      installed: false,
+      reason: `claude --version exited ${String(result.status)}`
+    };
+  } catch (err) {
+    return {
+      client: ALL_CLIENTS.find((c) => c.id === "claude-code"),
+      installed: false,
+      reason: err.message
+    };
+  }
+}
+function probeByDir(id) {
+  const client = ALL_CLIENTS.find((c) => c.id === id);
+  if (!client) throw new Error(`unknown client id: ${id}`);
+  const installed = existsSync(client.probeDir);
+  return {
+    client,
+    installed,
+    reason: installed ? `found ${client.probeDir}` : `no directory at ${client.probeDir}`
+  };
+}
+function probeAll() {
+  return [
+    probeClaudeCode(),
+    probeByDir("cursor"),
+    probeByDir("claude-desktop"),
+    probeByDir("vscode")
+  ];
+}
+var SYNC_PREFIXES = [
+  // iCloud Drive — both the new and legacy mounts.
+  "Library/Mobile Documents/com~apple~CloudDocs",
+  "iCloud Drive",
+  // OneDrive variants Microsoft ships across editions.
+  "OneDrive",
+  "OneDrive - ",
+  // Dropbox standard + enterprise mounts.
+  "Dropbox",
+  "Dropbox (",
+  // Google Drive (ALTER does not integrate with Google; still refuse).
+  "Google Drive",
+  "GoogleDrive",
+  "CloudStorage/GoogleDrive",
+  // Box, pCloud, Sync.com, MEGA — high-signal names worth refusing.
+  "Box Sync",
+  "pCloud Drive",
+  "Sync.com",
+  "MEGAsync"
+];
+function detectSyncedVolume(path) {
+  const absolute = resolve(path);
+  const normalised = platform() === "win32" ? absolute.replace(/\\/g, "/") : absolute;
+  for (const prefix of SYNC_PREFIXES) {
+    if (normalised.includes(`/${prefix}/`) || normalised.includes(`/${prefix}`)) {
+      return { refused: true, matchedPrefix: prefix, resolvedPath: absolute };
+    }
+  }
+  return null;
+}
+var WIRE_STATE_VERSION = 1;
+function readWireState() {
+  const path = wireStatePath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed.version !== WIRE_STATE_VERSION) {
+      throw new Error(
+        `wire-state.json version ${String(parsed.version)} is not supported by this SDK (expected ${WIRE_STATE_VERSION})`
+      );
+    }
+    return parsed;
+  } catch (err) {
+    throw new Error(`failed to parse wire-state.json: ${err.message}`);
+  }
+}
+function writeWireState(state) {
+  const path = wireStatePath();
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { mode: 384 });
+}
+function sha2562(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function atomicJsonMerge(opts) {
+  const { path, timestamp, merge, idempotent = true } = opts;
+  const tmpPath = `${path}.alter-tmp-${timestamp}`;
+  const backupPath = `${path}.alter-backup-${timestamp}`;
+  let existed = false;
+  let preBytes = null;
+  let parsed = {};
+  if (existsSync(path)) {
+    existed = true;
+    preBytes = readFileSync(path, "utf8");
+    if (preBytes.trim().length > 0) {
+      try {
+        parsed = JSON.parse(preBytes);
+      } catch (err) {
+        throw new Error(
+          `refusing to wire ${path}: existing file is not valid JSON (${err.message}). Hand-fix the file, then re-run \`alter-identity wire\`.`
+        );
+      }
+      if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
+        throw new Error(`refusing to wire ${path}: existing JSON root is not an object`);
+      }
+    }
+  }
+  const merged = merge(parsed);
+  const serialised = JSON.stringify(merged, null, 2) + "\n";
+  if (idempotent && preBytes !== null && preBytes === serialised) {
+    return {
+      path,
+      backupPath: null,
+      preSha256: sha2562(preBytes),
+      postSha256: sha2562(preBytes),
+      noop: true
+    };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(tmpPath, serialised, { mode: 384 });
+  try {
+    if (existed) copyFileSync(path, backupPath);
+    renameSync(tmpPath, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+  return {
+    path,
+    backupPath: existed ? backupPath : null,
+    preSha256: preBytes === null ? null : sha2562(preBytes),
+    postSha256: sha2562(serialised),
+    noop: false
+  };
+}
+function restoreFromBackup(path, backupPath) {
+  if (backupPath === null) {
+    if (existsSync(path)) unlinkSync(path);
+    return;
+  }
+  if (!existsSync(backupPath)) {
+    throw new Error(`cannot restore ${path}: backup missing at ${backupPath}`);
+  }
+  renameSync(backupPath, path);
+}
+
+// src/wire/index.ts
+var TIMESTAMP = () => String(Math.floor(Date.now() / 1e3));
+var ISO_NOW = () => (/* @__PURE__ */ new Date()).toISOString();
+function clientById(id) {
+  const hit = ALL_CLIENTS.find((c) => c.id === id);
+  if (!hit) throw new Error(`unknown client id: ${id}`);
+  return hit;
+}
+function wire(opts = {}) {
+  const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+  const apiKey = opts.apiKey;
+  const probes = probeAll();
+  const selection = opts.only ?? probes.filter((p) => p.installed).map((p) => p.client.id);
+  const ts = TIMESTAMP();
+  const targets = [];
+  for (const id of selection) {
+    const probe = id === "claude-code" ? probeClaudeCode() : probeByDir(id);
+    if (!probe.installed && opts.skipMissing !== false) {
+      targets.push({
+        client: id,
+        method: id === "claude-code" ? "cli" : "file",
+        status: "skipped",
+        ...id === "claude-code" ? { command: "" } : { path: clientById(id).configPath ?? "", backupPath: null, rootKey: clientById(id).rootKey, serverName: "alter", preSha256: null, postSha256: "" },
+        reason: probe.reason
+      });
+      continue;
+    }
+    try {
+      if (id === "claude-code") {
+        targets.push(wireClaudeCode({ endpoint, apiKey }));
+      } else {
+        targets.push(wireFileTarget({ id, endpoint, apiKey, timestamp: ts }));
+      }
+    } catch (err) {
+      const message = err.message;
+      targets.push({
+        client: id,
+        method: id === "claude-code" ? "cli" : "file",
+        status: "failed",
+        ...id === "claude-code" ? { command: "" } : { path: clientById(id).configPath ?? "", backupPath: null, rootKey: clientById(id).rootKey, serverName: "alter", preSha256: null, postSha256: "" },
+        reason: message
+      });
+    }
+  }
+  const state = {
+    version: 1,
+    sdkVersion: SDK_VERSION,
+    writtenAt: ISO_NOW(),
+    endpoint,
+    targets
+  };
+  writeWireState(state);
+  return { state, probes };
+}
+function wireFileTarget(args) {
+  const client = clientById(args.id);
+  if (!client.configPath) {
+    throw new Error(`client ${client.id} has no file-based config path`);
+  }
+  const sync = detectSyncedVolume(client.configPath);
+  if (sync) {
+    throw new Error(
+      `refusing to wire ${client.label}: config path ${sync.resolvedPath} lives under ${sync.matchedPrefix}. Synced volumes propagate credentials across devices \u2014 move the config off the sync root, or run wire on the device you want to target.`
+    );
+  }
+  const entry = args.id === "claude-desktop" ? generateClaudeDesktopConfig({ endpoint: args.endpoint, apiKey: args.apiKey }) : generateGenericMcpConfig({ endpoint: args.endpoint, apiKey: args.apiKey });
+  const rootKey = client.rootKey;
+  const serverName = "alter";
+  const result = atomicJsonMerge({
+    path: client.configPath,
+    timestamp: args.timestamp,
+    merge: (existing) => {
+      const bucket = existing[rootKey] ?? {};
+      const source = entry.mcpServers.alter;
+      return {
+        ...existing,
+        [rootKey]: {
+          ...bucket,
+          [serverName]: source
+        }
+      };
+    }
+  });
+  return {
+    client: args.id,
+    method: "file",
+    status: result.noop ? "already-wired" : "written",
+    path: result.path,
+    backupPath: result.backupPath,
+    rootKey,
+    serverName,
+    preSha256: result.preSha256,
+    postSha256: result.postSha256
+  };
+}
+function wireClaudeCode(args) {
+  const cmd = "claude";
+  const argList = [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "http",
+    "alter",
+    args.endpoint
+  ];
+  if (args.apiKey) {
+    argList.push("--header", `X-ALTER-API-Key:${args.apiKey}`);
+  }
+  const full = `${cmd} ${argList.join(" ")}`;
+  const run = spawnSync(cmd, argList, {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    timeout: 1e4
+  });
+  if (run.error) {
+    return {
+      client: "claude-code",
+      method: "cli",
+      status: "failed",
+      command: full,
+      stdout: run.stdout,
+      stderr: run.stderr,
+      reason: run.error.message
+    };
+  }
+  const stderr2 = (run.stderr ?? "").toLowerCase();
+  const alreadyExists = stderr2.includes("already exists") || stderr2.includes("already configured");
+  if (run.status === 0) {
+    return { client: "claude-code", method: "cli", status: "written", command: full, stdout: run.stdout, stderr: run.stderr };
+  }
+  if (alreadyExists) {
+    return { client: "claude-code", method: "cli", status: "already-wired", command: full, stdout: run.stdout, stderr: run.stderr };
+  }
+  return {
+    client: "claude-code",
+    method: "cli",
+    status: "failed",
+    command: full,
+    stdout: run.stdout,
+    stderr: run.stderr,
+    reason: `claude mcp add exited ${String(run.status)}`
+  };
+}
+function unwire() {
+  const state = readWireState();
+  const undone = [];
+  if (!state || state.targets.length === 0) {
+    return { state, undone };
+  }
+  for (const target of state.targets) {
+    try {
+      if (target.method === "file") {
+        if (target.status === "written") {
+          restoreFromBackup(target.path, target.backupPath);
+          undone.push({ client: target.client, action: target.backupPath ? "restored" : "removed" });
+        } else {
+          undone.push({ client: target.client, action: "skipped", reason: `target status was ${target.status}` });
+        }
+      } else if (target.method === "cli") {
+        if (target.status === "written") {
+          const run = spawnSync("claude", ["mcp", "remove", "--scope", "user", "alter"], {
+            encoding: "utf8",
+            shell: process.platform === "win32",
+            timeout: 1e4
+          });
+          if (run.error) {
+            undone.push({ client: target.client, action: "failed", reason: run.error.message });
+          } else if (run.status === 0) {
+            undone.push({ client: target.client, action: "cli-removed" });
+          } else {
+            undone.push({ client: target.client, action: "failed", reason: `claude mcp remove exited ${String(run.status)}` });
+          }
+        } else {
+          undone.push({ client: target.client, action: "skipped", reason: `target status was ${target.status}` });
+        }
+      }
+    } catch (err) {
+      undone.push({ client: target.client, action: "failed", reason: err.message });
+    }
+  }
+  writeWireState({
+    version: 1,
+    sdkVersion: state.sdkVersion,
+    writtenAt: ISO_NOW(),
+    endpoint: state.endpoint,
+    targets: []
+  });
+  return { state, undone };
+}
 
 // bin/alter-identity.ts
 var CONFIG_DIR = join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "alter");
@@ -1076,6 +1730,12 @@ async function main() {
     case "config":
       await runConfig(rest);
       break;
+    case "wire":
+      await runWire(rest);
+      break;
+    case "unwire":
+      await runUnwire();
+      break;
     case "message":
       await runMessage(rest);
       break;
@@ -1103,11 +1763,15 @@ function printHelp() {
   stdout.write(`${SDK_NAME} ${SDK_VERSION}
 
 Usage:
-  alter-identity init                       Generate Ed25519 keypair, discover MCP, write config
+  alter-identity init [--wire|--no-wire] [--yes]
+                                            Generate keypair, discover MCP, optionally wire detected AI clients
   alter-identity verify <~handle|email>     Verify an identity
   alter-identity status                     Show connection state
-  alter-identity config [--claude|--cursor|--generic]
+  alter-identity config [--claude|--cursor|--claude-desktop|--generic]
                                             Print MCP config snippet
+  alter-identity wire [--only=<ids>] [--yes]
+                                            Merge ALTER into detected AI clients (Claude Code, Cursor, Claude Desktop)
+  alter-identity unwire                     Restore every target from its backup sibling
 
 Alter-to-Alter Messaging:
   alter-identity message send <~handle> <body>     Send a direct message (body '-' = stdin)
@@ -1121,6 +1785,13 @@ Config: ${CONFIG_PATH}
 }
 async function runInit(args) {
   const force = args.includes("--force") || args.includes("-f");
+  const wireFlag = args.includes("--wire");
+  const noWireFlag = args.includes("--no-wire");
+  const yesFlag = args.includes("--yes") || args.includes("-y");
+  if (wireFlag && noWireFlag) {
+    stderr.write("error: --wire and --no-wire are mutually exclusive\n");
+    exit(2);
+  }
   const existing = readConfig();
   if (existing && !force) {
     stdout.write(`already initialised at ${CONFIG_PATH} (re-run with --force to overwrite)
@@ -1147,6 +1818,28 @@ async function runInit(args) {
 `);
   stdout.write(`  did: ${keypair.did}
 `);
+  let shouldWire = false;
+  if (noWireFlag) {
+    shouldWire = false;
+  } else if (wireFlag || yesFlag) {
+    shouldWire = true;
+  } else if (stdin.isTTY) {
+    const probes = probeAll();
+    const found = probes.filter((p) => p.installed).map((p) => p.client.label);
+    if (found.length === 0) {
+      stdout.write("\nNo MCP-aware clients detected on this machine \u2014 skipping wire.\n");
+    } else {
+      stdout.write(`
+Detected MCP-aware clients: ${found.join(", ")}
+`);
+      shouldWire = await confirm("Wire detected AI clients to ALTER?", true);
+    }
+  }
+  if (shouldWire) {
+    stdout.write("\n\u2022 Wiring detected AI clients...\n");
+    const report = wire({ endpoint });
+    printWireReport(report);
+  }
   stdout.write(`
 Next: alter-identity verify ~truealter
 `);
@@ -1205,10 +1898,121 @@ async function runConfig(args) {
   const opts = { endpoint: cfg.endpoint, apiKey: cfg.apiKey };
   let out;
   if (args.includes("--cursor")) out = generateCursorConfig(opts);
+  else if (args.includes("--claude-desktop")) out = generateClaudeDesktopConfig(opts);
   else if (args.includes("--generic")) out = generateGenericMcpConfig(opts);
   else out = generateClaudeConfig(opts);
   stdout.write(JSON.stringify(out, null, 2) + "\n");
 }
+async function runWire(args) {
+  const yesFlag = args.includes("--yes") || args.includes("-y");
+  const onlyArg = args.find((a) => a.startsWith("--only="));
+  const only = onlyArg ? onlyArg.slice("--only=".length).split(",").filter(Boolean) : void 0;
+  const cfg = readConfig() ?? {};
+  if (!cfg.endpoint) {
+    stderr.write("error: no endpoint \u2014 run `alter-identity init` first\n");
+    exit(2);
+  }
+  if (!yesFlag && stdin.isTTY) {
+    const probes = probeAll();
+    const found = probes.filter((p) => p.installed).map((p) => p.client.label);
+    if (found.length === 0) {
+      stdout.write("No MCP-aware clients detected on this machine. Nothing to do.\n");
+      return;
+    }
+    stdout.write(`Detected: ${found.join(", ")}
+`);
+    const proceed = await confirm("Wire these clients to ALTER?", true);
+    if (!proceed) {
+      stdout.write("aborted.\n");
+      return;
+    }
+  }
+  const report = wire({ endpoint: cfg.endpoint, apiKey: cfg.apiKey, only });
+  printWireReport(report);
+}
+async function runUnwire() {
+  const report = unwire();
+  printUnwireReport(report);
+}
+function printWireReport(report) {
+  for (const target of report.state.targets) {
+    const tag = `[${target.client}]`;
+    switch (target.status) {
+      case "written":
+        if (target.method === "file") {
+          stdout.write(`  \u2713 ${tag} wrote ${target.path} (backup: ${target.backupPath ?? "(none \u2014 created new file)"})
+`);
+        } else {
+          stdout.write(`  \u2713 ${tag} registered via \`${target.command}\`
+`);
+        }
+        break;
+      case "already-wired":
+        stdout.write(`  \xB7 ${tag} already wired \u2014 no change
+`);
+        break;
+      case "skipped":
+        stdout.write(`  - ${tag} skipped (${target.reason ?? "not installed"})
+`);
+        break;
+      case "failed":
+        stderr.write(`  \u2717 ${tag} failed: ${target.reason ?? "unknown"}
+`);
+        break;
+    }
+  }
+  stdout.write(`
+wire-state \u2192 ${join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "alter", "wire-state.json")}
+`);
+  stdout.write("run `alter-identity unwire` to reverse.\n");
+}
+function printUnwireReport(report) {
+  if (!report.state) {
+    stdout.write("nothing to unwire \u2014 no wire-state.json found\n");
+    return;
+  }
+  if (report.state.targets.length === 0) {
+    stdout.write("wire-state.json is empty \u2014 nothing to unwire\n");
+    return;
+  }
+  for (const entry of report.undone) {
+    const tag = `[${entry.client}]`;
+    switch (entry.action) {
+      case "restored":
+        stdout.write(`  \u2713 ${tag} restored from backup
+`);
+        break;
+      case "removed":
+        stdout.write(`  \u2713 ${tag} removed (file was created by wire)
+`);
+        break;
+      case "cli-removed":
+        stdout.write(`  \u2713 ${tag} removed via \`claude mcp remove\`
+`);
+        break;
+      case "skipped":
+        stdout.write(`  \xB7 ${tag} skipped (${entry.reason ?? ""})
+`);
+        break;
+      case "failed":
+        stderr.write(`  \u2717 ${tag} failed: ${entry.reason ?? ""}
+`);
+        break;
+    }
+  }
+}
+async function confirm(question, defaultYes) {
+  if (!stdin.isTTY) return false;
+  const rl = createInterface({ input: stdin, output: stdout });
+  const suffix = " [Y/n] " ;
+  const answer = await new Promise((resolve2) => {
+    rl.question(question + suffix, (ans) => resolve2(ans));
+  });
+  rl.close();
+  const trimmed = answer.trim().toLowerCase();
+  if (!trimmed) return defaultYes;
+  return trimmed === "y" || trimmed === "yes";
+}
 async function runMessage(args) {
   const [sub, ...rest] = args;
   if (!sub) {