@truealter/sdk 0.2.4 → 0.4.1

package/dist/index.js

@@ -1,6 +1,156 @@
+import { p256 } from '@noble/curves/p256';
+import { sha256 } from '@noble/hashes/sha256';
+import { randomBytes, bytesToHex as bytesToHex$1, hexToBytes } from '@noble/hashes/utils';
 import * as ed25519 from '@noble/ed25519';
 import { sha512 } from '@noble/hashes/sha512';
-import { randomBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { spawnSync } from 'child_process';
+import { homedir, platform } from 'os';
+import { join, resolve, dirname } from 'path';
+import { env } from 'process';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, copyFileSync, renameSync, unlinkSync } from 'fs';
+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 {
@@ -101,7 +251,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;
       }
@@ -142,6 +297,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 {
@@ -202,14 +379,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,
@@ -255,11 +435,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);
@@ -317,6 +500,7 @@ var MCPClient = class {
   maxRetries;
   clientInfo;
   x402;
+  signing;
   requestCounter = 0;
   initialised = false;
   constructor(opts = {}) {
@@ -327,6 +511,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
@@ -413,6 +598,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) {
@@ -423,7 +609,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
         });
@@ -450,7 +636,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);
         }
@@ -486,7 +673,7 @@ var MCPClient = class {
     }
     throw lastErr ?? new AlterNetworkError(`MCP ${method}: exhausted retries`);
   }
-  buildHeaders() {
+  buildHeaders(extra) {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json",
@@ -494,8 +681,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) {
@@ -538,8 +744,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)
   };
 }
@@ -551,7 +757,7 @@ function keypairFromPrivateKey(privateKeyHex) {
   const publicKey = ed25519.getPublicKey(privateKey);
   return {
     privateKey: privateKeyHex,
-    publicKey: bytesToHex(publicKey),
+    publicKey: bytesToHex$1(publicKey),
     did: encodeDid(publicKey)
   };
 }
@@ -559,7 +765,7 @@ async function sign(privateKeyHex, message) {
   const msgBytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
   const privateKey = hexToBytes(privateKeyHex);
   const sig = await ed25519.signAsync(msgBytes, privateKey);
-  return bytesToHex(sig);
+  return bytesToHex$1(sig);
 }
 async function verify(publicKeyHex, signatureHex, message) {
   try {
@@ -571,14 +777,14 @@ async function verify(publicKeyHex, signatureHex, message) {
 }
 function encodeDid(publicKey) {
   const bytes = typeof publicKey === "string" ? hexToBytes(publicKey) : publicKey;
-  return `ed25519:${base64urlEncode(bytes)}`;
+  return `ed25519:${base64urlEncode2(bytes)}`;
 }
 function decodeDid(did) {
   const ed25519Match = did.match(/^ed25519:(.+)$/);
   if (ed25519Match) return base64urlDecode(ed25519Match[1]);
   throw new Error(`Unrecognised DID encoding: ${did}`);
 }
-function base64urlEncode(bytes) {
+function base64urlEncode2(bytes) {
   let b64;
   if (typeof Buffer !== "undefined") {
     b64 = Buffer.from(bytes).toString("base64");
@@ -1047,6 +1253,9 @@ var AlterClient = class {
   }
 };
 
+// src/index.ts
+init_signing();
+
 // src/adapters/generic-mcp.ts
 function generateGenericMcpConfig(opts = {}) {
   const serverName = opts.serverName ?? "alter";
@@ -1071,6 +1280,461 @@ function generateCursorConfig(opts = {}) {
   return generateGenericMcpConfig({ serverName: "alter", ...opts });
 }
 
+// src/adapters/claude-desktop.ts
+function generateClaudeDesktopConfig(opts = {}) {
+  const serverName = opts.serverName ?? "alter";
+  const bridgeCommand = opts.bridgeCommand ?? "alter-mcp-bridge";
+  const env2 = {};
+  env2.ALTER_MCP_ENDPOINT = opts.endpoint ?? DEFAULT_ENDPOINT;
+  if (opts.apiKey) env2.ALTER_API_KEY = opts.apiKey;
+  const entry = {
+    command: bridgeCommand,
+    env: env2,
+    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.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 stderr = (run.stderr ?? "").toLowerCase();
+  const alreadyExists = stderr.includes("already exists") || stderr.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 };
+}
+
 // src/types.ts
 var FREE_TOOL_NAMES = [
   "hello_agent",
@@ -1226,8 +1890,4 @@ var TOOL_BLAST_RADIUS = {
   query_graph_similarity: "high"
 };
 
-// src/index.ts
-var SDK_NAME = "@truealter/sdk";
-var SDK_VERSION = "0.2.4";
-
-export { AlterAuthError, AlterClient, AlterDiscoveryError, AlterError, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, AlterTimeoutError, AlterToolError, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, FREE_TOOL_NAMES, MCPClient, MCP_PROTOCOL_VERSION, PREMIUM_TOOL_NAMES, SDK_NAME, SDK_VERSION, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, X402Client, base64urlDecode, base64urlEncode, clearDiscoveryCache, decodeDid, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, parsePaymentHeader, resolveVerifyAt, sign, verify, verifyProvenance, verifyToolSignatures };
+export { ALL_CLIENTS, AlterAuthError, AlterClient, AlterDiscoveryError, AlterError, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, AlterTimeoutError, AlterToolError, CLAUDE_CODE, CLAUDE_DESKTOP, CURSOR, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, FREE_TOOL_NAMES, MCPClient, MCP_PROTOCOL_VERSION, PREMIUM_TOOL_NAMES, SDK_NAME, SDK_VERSION, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, VSCODE, X402Client, base64urlDecode, base64urlEncode2 as base64urlEncode, canonicalArgsSha256, canonicalStringify, clearDiscoveryCache, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha2562 as sha256, sign, signInvocation, unwire, verify, verifyProvenance, verifyToolSignatures, wire, writeWireState };