@truealter/sdk 0.5.1 → 0.5.8

package/dist/index.js

@@ -1,12 +1,13 @@
 import { p256 } from '@noble/curves/p256';
 import { sha256 } from '@noble/hashes/sha256';
 import { randomBytes, bytesToHex as bytesToHex$1, hexToBytes } from '@noble/hashes/utils';
-import { createPrivateKey, createHash } from 'crypto';
+import { createPrivateKey, createPublicKey, createHash, verify as verify$1 } from 'crypto';
+import { statSync, readFileSync, mkdirSync, writeFileSync, chmodSync, renameSync, existsSync, copyFileSync, unlinkSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join, dirname, resolve } from 'path';
 import * as ed25519 from '@noble/ed25519';
 import { sha512 } from '@noble/hashes/sha512';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, copyFileSync, renameSync, unlinkSync } from 'fs';
-import { join, resolve, dirname } from 'path';
-import { homedir, platform } from 'os';
+import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
 import { env } from 'process';
 
@@ -14,14 +15,13 @@ 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 __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -369,11 +369,11 @@ async function tryWellKnown(host, file, timeoutMs, fetchImpl) {
   }
   if (resp.type === "opaqueredirect" || resp.status >= 300 && resp.status < 400) {
     throw new AlterNetworkError(
-      `${url} \u2192 redirect rejected (discovery must not follow redirects; validate the server configuration)`
+      `${url} -> redirect rejected (discovery must not follow redirects; validate the server configuration)`
     );
   }
   if (resp.status === 404) return null;
-  if (!resp.ok) throw new AlterNetworkError(`${url} \u2192 HTTP ${resp.status}`);
+  if (!resp.ok) throw new AlterNetworkError(`${url} -> HTTP ${resp.status}`);
   const doc = await resp.json();
   if (file === "mcp.json") {
     const remotes = doc.remotes || [];
@@ -406,6 +406,309 @@ function ensureMcpPath(url) {
     return url;
   }
 }
+
+// src/meta.ts
+var SDK_NAME = "@truealter/sdk";
+var SDK_VERSION = "0.5.8" ;
+
+// src/floor-preflight.ts
+var MIN_VERSION_ENDPOINT = "/v1/clients/min-version";
+var CLIENT_ID = "alter-identity";
+var CLIENT_CHANNEL = "npm";
+var IN_MEMORY_TTL_DEFAULT_MS = 60 * 60 * 1e3;
+var IN_MEMORY_TTL_MIN_MS = 60 * 1e3;
+var IN_MEMORY_TTL_MAX_MS = 24 * 60 * 60 * 1e3;
+var DISK_FRESH_MS = 24 * 60 * 60 * 1e3;
+var DISK_WARN_MS = 7 * 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 4e3;
+function computeKeyId(publicKeyPem) {
+  if (!publicKeyPem) return "00000000";
+  const pub = createPublicKey({ key: publicKeyPem, format: "pem" });
+  const jwk = pub.export({ format: "jwk" });
+  const rawBytes = Buffer.from(jwk.x, "base64url");
+  return createHash("sha256").update(rawBytes).digest("hex").slice(0, 8);
+}
+function canonicalJson(obj) {
+  return JSON.stringify(sortKeysDeep(obj));
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+  if (value !== null && typeof value === "object") {
+    const obj = value;
+    const sorted = {};
+    for (const k of Object.keys(obj).sort()) {
+      sorted[k] = sortKeysDeep(obj[k]);
+    }
+    return sorted;
+  }
+  return value;
+}
+var KNOWN_FLOOR_PUBLIC_KEYS = {
+  "8aa59e05": `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAgqw28dlniOuiTE1f4BxCPSEgMLaPtHsO8wN5RWEwEhE=
+-----END PUBLIC KEY-----`,
+  "640f7d9a": `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEARzvAWayDwHvZRfOZizGZe+/a7PF082WGhyMS3tx06H4=
+-----END PUBLIC KEY-----`
+};
+var BelowFloorError = class extends Error {
+  name = "BelowFloorError";
+  code = "client_below_floor";
+  client_version;
+  min_version;
+  upgrade_cmd;
+  channel;
+  envelope;
+  constructor(envelope) {
+    super(envelope.error.message);
+    this.envelope = envelope;
+    this.client_version = envelope.error.client_version;
+    this.min_version = envelope.error.min_version;
+    this.upgrade_cmd = envelope.error.upgrade_cmd;
+    this.channel = envelope.error.channel;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var memCache = null;
+async function checkMinVersion(opts = {}) {
+  const apiBase = opts.apiBase ?? defaultApiBase();
+  const clientVersion = opts.clientVersion ?? SDK_VERSION;
+  const clientId = opts.clientId ?? CLIENT_ID;
+  const channel = opts.channel ?? CLIENT_CHANNEL;
+  const knownKeys = opts.knownFloorPublicKeys ?? KNOWN_FLOOR_PUBLIC_KEYS;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const now = opts.now ?? Date.now;
+  const cachePath = opts.diskCachePath === void 0 ? defaultDiskCachePath() : opts.diskCachePath;
+  const mem = readInMemoryCache(now);
+  if (mem) {
+    return compareAndPermit(mem, {
+      clientVersion,
+      clientId,
+      channel,
+      diagnostic: "mem-cache-hit"
+    });
+  }
+  const disk = cachePath ? readDiskCache(cachePath, knownKeys) : null;
+  const diskAgeMs = disk ? now() - disk.fetched_at_ms : Number.POSITIVE_INFINITY;
+  let fetched = null;
+  let fetchError = null;
+  if (!disk || diskAgeMs > IN_MEMORY_TTL_DEFAULT_MS) {
+    try {
+      fetched = await fetchFloorDoc(apiBase, fetchImpl, knownKeys);
+    } catch (err) {
+      fetchError = err.message ?? "fetch-error";
+    }
+  }
+  if (fetched) {
+    populateMemCache(fetched, now());
+    if (cachePath) writeDiskCache(cachePath, fetched, now());
+    return compareAndPermit(fetched, {
+      clientVersion,
+      clientId,
+      channel,
+      diagnostic: "fetched"
+    });
+  }
+  if (disk) {
+    populateMemCache(disk.doc, disk.fetched_at_ms);
+    if (diskAgeMs > DISK_WARN_MS) {
+      return compareAndPermit(disk.doc, {
+        clientVersion,
+        clientId,
+        channel,
+        diagnostic: "below-floor-offline-stale-or-permit",
+        warn: `floor cache is >7d old and backend unreachable (${fetchError ?? "no refresh attempted"}); permitting if above floor`
+      });
+    }
+    if (diskAgeMs > DISK_FRESH_MS) {
+      return compareAndPermit(disk.doc, {
+        clientVersion,
+        clientId,
+        channel,
+        diagnostic: "warn-stale-permit",
+        warn: `floor cache is ${Math.round(diskAgeMs / (60 * 60 * 1e3))}h old; refresh recommended`
+      });
+    }
+    return compareAndPermit(disk.doc, {
+      clientVersion,
+      clientId,
+      channel,
+      diagnostic: "disk-cache-hit"
+    });
+  }
+  return {
+    ok: true,
+    floor: null,
+    diagnostic: "no-cache-no-fetch-permit",
+    warn: `floor preflight skipped: backend unreachable (${fetchError ?? "unknown"})`
+  };
+}
+function compareAndPermit(doc, ctx) {
+  const floor = lookupFloor(doc, ctx.clientId, ctx.channel);
+  if (!floor) {
+    return { ok: true, floor: null, diagnostic: `${ctx.diagnostic}+no-floor`, warn: ctx.warn };
+  }
+  if (compareSemver(ctx.clientVersion, floor.min_version) >= 0) {
+    return { ok: true, floor, diagnostic: ctx.diagnostic, warn: ctx.warn };
+  }
+  const envelope = {
+    error: {
+      code: "client_below_floor",
+      message: `Your ${ctx.clientId} is too old. Upgrade required.`,
+      client_version: ctx.clientVersion,
+      min_version: floor.min_version,
+      upgrade_cmd: floor.upgrade_cmd,
+      channel: ctx.channel
+    }
+  };
+  throw new BelowFloorError(envelope);
+}
+function lookupFloor(doc, clientId, channel) {
+  const entry = doc.floors[clientId];
+  if (!entry) return null;
+  if (isChannelFloor(entry)) return entry;
+  const exact = entry[channel];
+  if (exact) return exact;
+  const fallback = entry["unknown"];
+  if (fallback) return fallback;
+  return null;
+}
+function isChannelFloor(v) {
+  return typeof v.min_version === "string" && typeof v.upgrade_cmd === "string";
+}
+function compareSemver(a, b) {
+  const [aMaj, aMin, aPat, aPre] = parseSemver(a);
+  const [bMaj, bMin, bPat, bPre] = parseSemver(b);
+  if (aMaj !== bMaj) return aMaj - bMaj;
+  if (aMin !== bMin) return aMin - bMin;
+  if (aPat !== bPat) return aPat - bPat;
+  if (aPre && !bPre) return -1;
+  if (!aPre && bPre) return 1;
+  if (aPre && bPre) return aPre.localeCompare(bPre);
+  return 0;
+}
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v);
+  if (!m) return [0, 0, 0, null];
+  return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] ?? null];
+}
+function verifyFloorSignature(doc, keys = KNOWN_FLOOR_PUBLIC_KEYS) {
+  const pem = keys[doc.key_id];
+  if (!pem) return false;
+  if (computeKeyId(pem) !== doc.key_id) return false;
+  try {
+    const pubKeyObject = createPublicKey({ key: pem, format: "pem" });
+    const canonical = canonicalJson({
+      floors: doc.floors,
+      served_at: doc.served_at
+    });
+    return verify$1(
+      null,
+      Buffer.from(canonical, "utf-8"),
+      pubKeyObject,
+      Buffer.from(doc.signature, "hex")
+    );
+  } catch {
+    return false;
+  }
+}
+async function fetchFloorDoc(apiBase, fetchImpl, knownKeys) {
+  const url = `${apiBase.replace(/\/+$/, "")}${MIN_VERSION_ENDPOINT}`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: {
+        accept: "application/json",
+        "X-Alter-Client-Id": CLIENT_ID,
+        "X-Alter-Client-Version": SDK_VERSION,
+        "X-Alter-Client-Channel": CLIENT_CHANNEL,
+        "User-Agent": `${SDK_NAME}/${SDK_VERSION}`
+      },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    throw new Error(`network: ${err.message ?? String(err)}`);
+  }
+  if (!response.ok) throw new Error(`http-${response.status}`);
+  const body = await response.json();
+  if (!body || !body.floors || !body.signature || !body.key_id) {
+    throw new Error("malformed-floor-doc");
+  }
+  if (!verifyFloorSignature(body, knownKeys)) {
+    throw new Error("signature-invalid");
+  }
+  return body;
+}
+function readInMemoryCache(now) {
+  if (!memCache) return null;
+  if (now() - memCache.fetched_at_ms > memCache.ttl_ms) {
+    memCache = null;
+    return null;
+  }
+  return memCache.doc;
+}
+function populateMemCache(doc, fetched_at_ms) {
+  const ttlSec = doc.cache_ttl_seconds ?? 3600;
+  const ttlMs = Math.min(
+    Math.max(ttlSec * 1e3, IN_MEMORY_TTL_MIN_MS),
+    IN_MEMORY_TTL_MAX_MS
+  );
+  memCache = { doc, fetched_at_ms, ttl_ms: ttlMs };
+}
+function defaultDiskCachePath() {
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(xdg, "alter", "floor-cache.json");
+}
+function readDiskCache(path, knownKeys) {
+  if (process.platform !== "win32") {
+    let st;
+    try {
+      st = statSync(path);
+    } catch {
+      return null;
+    }
+    const euid = typeof process.geteuid === "function" ? process.geteuid() : st.uid;
+    if (st.uid !== euid) return null;
+    if ((st.mode & 511) !== 384) return null;
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed.doc || typeof parsed.fetched_at_ms !== "number") return null;
+  if (!verifyFloorSignature(parsed.doc, knownKeys)) {
+    return null;
+  }
+  return parsed;
+}
+function writeDiskCache(path, doc, now_ms) {
+  const entry = { doc, fetched_at_ms: now_ms };
+  const payload = JSON.stringify(entry);
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, payload, { mode: 384 });
+    try {
+      chmodSync(tmp, 384);
+    } catch {
+    }
+    renameSync(tmp, path);
+  } catch {
+  }
+}
+function defaultApiBase() {
+  return process.env.ALTER_API ?? "https://api.truealter.com";
+}
 var X402Client = class {
   signer;
   maxPerQuery;
@@ -516,6 +819,9 @@ var MCPClient = class {
   x402;
   signing;
   extraHeaders;
+  preflightHook;
+  preflightPromise = null;
+  preflightDone = false;
   requestCounter = 0;
   initialised = false;
   constructor(opts = {}) {
@@ -524,17 +830,43 @@ var MCPClient = class {
     this.fetchImpl = opts.fetch ?? fetch;
     this.timeoutMs = opts.timeoutMs ?? 3e4;
     this.maxRetries = opts.maxRetries ?? 2;
-    this.clientInfo = opts.clientInfo ?? { name: "@truealter/sdk", version: "0.2.0" };
+    this.clientInfo = opts.clientInfo ?? { name: SDK_NAME, version: SDK_VERSION };
     this.x402 = opts.x402;
     this.signing = opts.signing;
     this.extraHeaders = opts.extraHeaders;
+    this.preflightHook = opts.preflightHook;
+  }
+  /**
+   * Run the lazy version-floor preflight hook exactly once.
+   * Idempotent and serialised: concurrent callers share the same
+   * promise. Throws from the hook propagate to every concurrent caller.
+   */
+  async runPreflight() {
+    if (this.preflightDone) return;
+    if (!this.preflightHook) {
+      this.preflightDone = true;
+      return;
+    }
+    if (!this.preflightPromise) {
+      this.preflightPromise = this.preflightHook().then(
+        () => {
+          this.preflightDone = true;
+        },
+        (err) => {
+          this.preflightPromise = null;
+          throw err;
+        }
+      );
+    }
+    await this.preflightPromise;
   }
   /**
    * Send the MCP `initialize` handshake and capture the resulting session
-   * id. Idempotent — safe to call multiple times.
+   * id. Idempotent: safe to call multiple times.
    */
   async initialize() {
     if (this.initialised) return null;
+    await this.runPreflight();
     const result = await this.rpc("initialize", {
       protocolVersion: MCP_PROTOCOL_VERSION,
       capabilities: {},
@@ -627,7 +959,14 @@ var MCPClient = class {
           method: "POST",
           headers: this.buildHeaders(signatureHeader),
           body: JSON.stringify(payload),
-          signal: controller.signal
+          signal: controller.signal,
+          // Prevent fetch from silently following 3xx redirects. When
+          // Cloudflare Access credentials are absent or expired the edge
+          // returns HTTP 302 → CF Access login page (text/html). Without
+          // this option undici follows the redirect, lands on a 200 HTML
+          // body, and resp.json() throws the opaque "invalid JSON body"
+          // error that was surfaced as "MCP <method>: invalid JSON body".
+          redirect: "manual"
         });
       } catch (err) {
         clearTimeout(timer);
@@ -644,6 +983,19 @@ var MCPClient = class {
       clearTimeout(timer);
       const sessionHeader = resp.headers.get("Mcp-Session-Id");
       if (sessionHeader) this.sessionId = sessionHeader;
+      if (resp.status >= 300 && resp.status < 400) {
+        const location = resp.headers.get("Location") ?? "";
+        const isAuthRedirect = location.includes("cloudflareaccess.com") || location.includes("/cdn-cgi/access/") || !location.startsWith("/") && !location.startsWith(new URL(this.endpoint).origin);
+        if (isAuthRedirect) {
+          throw new AlterAuthError(
+            `MCP ${method}: Cloudflare Access blocked the request (session expired or credentials missing). Run \`alter login\` to re-authenticate.`,
+            302
+          );
+        }
+        throw new AlterNetworkError(
+          `MCP ${method}: unexpected redirect ${resp.status} to ${location || "(no Location)"}`
+        );
+      }
       if (resp.status === 401 || resp.status === 403) {
         throw new AlterAuthError(`HTTP ${resp.status} on ${method}`, resp.status);
       }
@@ -668,11 +1020,56 @@ var MCPClient = class {
         const body2 = await safeText(resp);
         throw new AlterError("NETWORK", `HTTP ${resp.status} on ${method}: ${body2.slice(0, 200)}`);
       }
+      const contentType = resp.headers.get("Content-Type") ?? "";
+      const isHtml = contentType.includes("text/html");
+      const isSse = contentType.includes("text/event-stream");
+      if (isHtml || isSse) {
+        if (isSse) {
+          const rawText = await safeText(resp);
+          const dataLine = rawText.split("\n").find((l) => l.startsWith("data:"));
+          if (dataLine) {
+            const jsonPart = dataLine.slice("data:".length).trim();
+            try {
+              const parsed = JSON.parse(jsonPart);
+              if (parsed.error) {
+                const code = parsed.error.code;
+                const message = parsed.error.message ?? `MCP ${method} error`;
+                throw new AlterToolError(this.guessToolName(payload), message, code);
+              }
+              return parsed.result;
+            } catch (parseErr) {
+              if (parseErr instanceof AlterError) throw parseErr;
+              throw new AlterInvalidResponse(
+                `MCP ${method}: could not parse SSE data frame as JSON`,
+                parseErr
+              );
+            }
+          }
+          throw new AlterInvalidResponse(
+            `MCP ${method}: received text/event-stream response with no data: frame`
+          );
+        }
+        const excerpt = (await safeText(resp)).slice(0, 300);
+        const looksLikeLoginPage = excerpt.toLowerCase().includes("cloudflareaccess") || excerpt.toLowerCase().includes("access denied") || excerpt.toLowerCase().includes("<title>");
+        if (looksLikeLoginPage) {
+          throw new AlterAuthError(
+            `MCP ${method}: received an HTML login page instead of JSON (Content-Type: ${contentType}). Run \`alter login\` to re-authenticate.`,
+            200
+          );
+        }
+        throw new AlterInvalidResponse(
+          `MCP ${method}: unexpected Content-Type "${contentType}" (expected application/json). Body excerpt: ${excerpt.slice(0, 120)}`
+        );
+      }
       let body;
       try {
         body = await resp.json();
       } catch (err) {
-        throw new AlterInvalidResponse(`MCP ${method}: invalid JSON body`, err);
+        const hint = contentType ? ` (Content-Type: ${contentType})` : "";
+        throw new AlterInvalidResponse(
+          `MCP ${method}: failed to parse JSON response${hint}. The server may have returned a non-JSON body. Run \`alter login\` if the session is expired.`,
+          err
+        );
       }
       if (body.error) {
         const code = body.error.code;
@@ -693,8 +1090,11 @@ var MCPClient = class {
     const headers = {
       ...this.extraHeaders ?? {},
       "Content-Type": "application/json",
-      Accept: "application/json",
-      "User-Agent": `${this.clientInfo.name}/${this.clientInfo.version}`
+      Accept: "application/json, text/event-stream",
+      "User-Agent": `${this.clientInfo.name}/${this.clientInfo.version}`,
+      "X-Alter-Client-Id": "alter-identity",
+      "X-Alter-Client-Version": SDK_VERSION,
+      "X-Alter-Client-Channel": "npm"
     };
     if (this.apiKey) headers["X-ALTER-API-Key"] = this.apiKey;
     if (this.sessionId) headers["Mcp-Session-Id"] = this.sessionId;
@@ -971,7 +1371,7 @@ async function verifyToolSignatures(tools, signatures, opts = {}) {
       out.push({ tool: tool.name, valid: false, reason: "no signature published" });
       continue;
     }
-    const expectedHash = await sha256Hex(canonicalJson(tool.inputSchema));
+    const expectedHash = await sha256Hex(canonicalJson2(tool.inputSchema));
     if (expectedHash !== sig.schema_hash) {
       out.push({ tool: tool.name, valid: false, reason: "schema hash mismatch" });
       continue;
@@ -1055,23 +1455,23 @@ async function fetchJwks(url, fetchImpl) {
   }
   if (resp.type === "opaqueredirect" || resp.status >= 300 && resp.status < 400) {
     throw new AlterProvenanceError(
-      `${url} \u2192 redirect rejected (allowlist enforces initial URL only)`
+      `${url} -> redirect rejected (allowlist enforces initial URL only)`
     );
   }
-  if (!resp.ok) throw new AlterNetworkError(`${url} \u2192 HTTP ${resp.status}`);
+  if (!resp.ok) throw new AlterNetworkError(`${url} -> HTTP ${resp.status}`);
   const contentLength = resp.headers.get("content-length");
   if (contentLength !== null) {
     const n = Number.parseInt(contentLength, 10);
     if (Number.isFinite(n) && n > JWKS_MAX_BYTES) {
       throw new AlterProvenanceError(
-        `${url} \u2192 JWKS too large: ${n} > ${JWKS_MAX_BYTES} bytes`
+        `${url} -> JWKS too large: ${n} > ${JWKS_MAX_BYTES} bytes`
       );
     }
   }
   const body = await resp.text();
   if (body.length > JWKS_MAX_BYTES) {
     throw new AlterProvenanceError(
-      `${url} \u2192 JWKS too large: ${body.length} > ${JWKS_MAX_BYTES} bytes`
+      `${url} -> JWKS too large: ${body.length} > ${JWKS_MAX_BYTES} bytes`
     );
   }
   let doc;
@@ -1155,19 +1555,35 @@ async function sha256Hex(input) {
 function toArrayBuffer(view) {
   return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
 }
-function canonicalJson(value) {
+function canonicalJson2(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
+    return `[${value.map(canonicalJson2).join(",")}]`;
   }
   const obj = value;
   const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson2(obj[k])}`).join(",")}}`;
 }
 
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://mcp.truealter.com/api/v1/mcp";
+var MEMBER_BRIDGE_ENDPOINT = "https://api.truealter.com/api/v1/mcp";
 var DEFAULT_DOMAIN = "truealter.com";
+var CANONICAL_API_BASE = "https://api.truealter.com";
+var JWKS_WELL_KNOWN_PATH = "/.well-known/alter-keys.json";
+function resolveJwksUrl(opts = {}) {
+  if (opts.jwksUrl) return opts.jwksUrl;
+  const base = opts.apiBase ?? (typeof process !== "undefined" ? process.env?.ALTER_API : void 0) ?? originOf(opts.endpoint) ?? CANONICAL_API_BASE;
+  return `${base.replace(/\/+$/, "")}${JWKS_WELL_KNOWN_PATH}`;
+}
+function originOf(url) {
+  if (!url) return void 0;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
 var AlterClient = class {
   mcp;
   x402;
@@ -1178,11 +1594,21 @@ var AlterClient = class {
     this.options = options;
     this.x402 = options.x402;
     const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
-    this.mcp = new MCPClient({ ...options, endpoint, x402: options.x402 });
+    const preflightHook = options.unsafe_skipVersionCheck ? void 0 : () => checkMinVersion({
+      apiBase: options.apiBase,
+      knownFloorPublicKeys: options.knownFloorPublicKeys,
+      fetchImpl: options.fetch
+    }).then(() => void 0);
+    this.mcp = new MCPClient({
+      ...options,
+      endpoint,
+      x402: options.x402,
+      preflightHook
+    });
   }
   /**
    * Resolve the MCP endpoint via discovery if requested. Safe to call
-   * multiple times — the first successful lookup is cached.
+   * multiple times: the first successful lookup is cached.
    */
   async discoverEndpoint() {
     if (this.discovered) return this.discovered;
@@ -1195,7 +1621,7 @@ var AlterClient = class {
     return this.discoveryPromise;
   }
   /**
-   * Initialise the MCP session. Optional — every method calls
+   * Initialise the MCP session. Optional: every method calls
    * `mcp.initialize()` lazily, but you can call this once at startup if
    * you want fail-fast behaviour.
    */
@@ -1203,11 +1629,11 @@ var AlterClient = class {
     await this.mcp.initialize();
   }
   // ── Free tier ────────────────────────────────────────────────────────
-  /** First handshake — confirms the connection, returns trust tier and tool counts. */
+  /** First handshake: confirms the connection, returns trust tier and tool counts. */
   async helloAgent() {
     return this.mcp.callTool("hello_agent", {});
   }
-  /** Resolve a ~handle (e.g. ~drew) to its canonical form and kind. No auth required. */
+  /** Resolve a ~handle (e.g. ~example) to its canonical form and kind. No auth required. */
   async resolveHandle(args) {
     const payload = typeof args === "string" ? { query: args } : args;
     return this.mcp.callTool("alter_resolve_handle", payload);
@@ -1215,7 +1641,7 @@ var AlterClient = class {
   /** Verify a person is registered with ALTER (handle or id). */
   async verify(handleOrId, claims) {
     const args = handleOrId.includes("@") ? { member_id: "", email: handleOrId } : handleOrId.startsWith("~") ? (
-      // ~handle — server resolves these via the member_id field
+      // ~handle: server resolves these via the member_id field
       { member_id: handleOrId }
     ) : { member_id: handleOrId };
     if (claims) args.claims = claims;
@@ -1315,8 +1741,8 @@ var AlterClient = class {
   }
   // ── Alter-to-Alter Messaging ─────────────────────────────────────────
   // Wave 1: cross-handle direct messages between authenticated tilde
-  // handles. Default closed — recipient must have granted the sender via
-  // alter_message_grant. Spec: docs/technical/Alter-to-Alter Messaging.md.
+  // handles. Default closed: recipient must have granted the sender via
+  // alter_message_grant. Spec: the ALTER Alter-to-Alter Messaging spec.
   /** Send a direct message to another tilde handle. */
   async messageSend(args) {
     return this.mcp.callTool("alter_message_send", args);
@@ -1349,12 +1775,16 @@ var AlterClient = class {
   /**
    * Verify the ES256 provenance attestation on a tool response.
    * Accepts either a {@link ProvenanceEnvelope} or the raw `_meta`
-   * object — the latter is more convenient for ad-hoc verification.
+   * object: the latter is more convenient for ad-hoc verification.
    */
   async verifyProvenance(envelope) {
     if (!envelope) return { valid: false, reason: "no provenance envelope" };
     const inner = envelope.provenance ?? envelope;
     return verifyProvenance(inner, {
+      // Pass an explicit jwksUrl only when the caller pinned one. Leaving it
+      // undefined preserves the envelope `verify_at` (allowlist-gated)
+      // resolution path inside verifyProvenance; the allowlist is the
+      // trust-anchor gate there, not a bare hardcoded host.
       jwksUrl: this.options.jwksUrl,
       verifyAtAllowlist: this.options.verifyAtAllowlist
     });
@@ -1367,9 +1797,21 @@ var AlterClient = class {
   async verifyToolSignatures(tools, signatures) {
     return verifyToolSignatures(tools, signatures);
   }
-  /** Fetch the published JWKS for ALTER's signing key (cached 5 min). */
+  /**
+   * Fetch the published JWKS for ALTER's signing key (cached 5 min).
+   *
+   * The JWKS URL is derived from the configured API surface
+   * ({@link resolveJwksUrl}: explicit `jwksUrl` > `apiBase` > `ALTER_API` >
+   * the configured `endpoint` origin > the canonical host) rather than a
+   * single hardcoded host, so the trust anchor tracks the surface the
+   * client is actually pointed at.
+   */
   async fetchPublicKeys() {
-    const url = this.options.jwksUrl ?? "https://api.truealter.com/.well-known/alter-keys.json";
+    const url = resolveJwksUrl({
+      jwksUrl: this.options.jwksUrl,
+      apiBase: this.options.apiBase,
+      endpoint: this.options.endpoint
+    });
     return fetchPublicKeys(url);
   }
 };
@@ -1385,7 +1827,7 @@ function generateGenericMcpConfig(opts = {}) {
   const entry = {
     url: opts.endpoint ?? DEFAULT_ENDPOINT,
     transport: "streamable-http",
-    description: "ALTER Identity \u2014 psychometric identity field for AI agents"
+    description: "ALTER Identity: psychometric identity field for AI agents"
   };
   if (Object.keys(headers).length > 0) entry.headers = headers;
   return { mcpServers: { [serverName]: entry } };
@@ -1404,24 +1846,23 @@ function generateCursorConfig(opts = {}) {
 // src/adapters/claude-desktop.ts
 function generateClaudeDesktopConfig(opts = {}) {
   const serverName = opts.serverName ?? "alter";
-  const bridgeCommand = opts.bridgeCommand ?? "alter-mcp-bridge";
+  const bridgeCommand = opts.bridgeCommand ?? "alter";
   const env2 = {};
-  env2.ALTER_MCP_ENDPOINT = opts.endpoint ?? DEFAULT_ENDPOINT;
+  env2.ALTER_MCP_ENDPOINT = opts.endpoint ?? MEMBER_BRIDGE_ENDPOINT;
   if (opts.apiKey) env2.ALTER_API_KEY = opts.apiKey;
   const entry = {
     command: bridgeCommand,
+    // The `mcp-bridge` subcommand is always the first arg now that the bridge
+    // is invoked through the `alter` CLI, not a bare bridge binary.
+    args: ["mcp-bridge"],
     env: env2,
-    description: "ALTER Identity \u2014 psychometric identity field for AI agents"
+    description: "ALTER Identity: psychometric identity field for AI agents"
   };
   if (opts.extraArgs && opts.extraArgs.length > 0) {
-    entry.args = [...opts.extraArgs];
+    entry.args = [...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() {
@@ -1546,7 +1987,7 @@ function probeAll() {
   ];
 }
 var SYNC_PREFIXES = [
-  // iCloud Drive — both the new and legacy mounts.
+  // iCloud Drive: both the new and legacy mounts.
   "Library/Mobile Documents/com~apple~CloudDocs",
   "iCloud Drive",
   // OneDrive variants Microsoft ships across editions.
@@ -1559,7 +2000,7 @@ var SYNC_PREFIXES = [
   "Google Drive",
   "GoogleDrive",
   "CloudStorage/GoogleDrive",
-  // Box, pCloud, Sync.com, MEGA — high-signal names worth refusing.
+  // Box, pCloud, Sync.com, MEGA: high-signal names worth refusing.
   "Box Sync",
   "pCloud Drive",
   "Sync.com",
@@ -1611,10 +2052,10 @@ function atomicJsonMerge(opts) {
     preBytes = readFileSync(path, "utf8");
     if (preBytes.trim().length > 0) {
       try {
-        parsed = JSON.parse(preBytes);
+        parsed = JSON.parse(preBytes.replace(/^\uFEFF/, ""));
       } 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\`.`
+          `refusing to wire ${path}: existing file is not valid JSON (${err.message}). Hand-fix the file, then re-run \`alter wire\`.`
         );
       }
       if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
@@ -1696,6 +2137,7 @@ function wire(opts = {}) {
   const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
   const apiKey = opts.apiKey;
   const cfAccess = opts.cfAccess ?? readCfAccessEnv();
+  const launcherPath = opts.launcherPath;
   const probes = probeAll();
   const selection = opts.only ?? probes.filter((p) => p.installed).map((p) => p.client.id);
   const ts = TIMESTAMP();
@@ -1714,7 +2156,7 @@ function wire(opts = {}) {
     }
     try {
       if (id === "claude-code") {
-        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess }));
+        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess, launcherPath }));
       } else {
         targets.push(wireFileTarget({ id, endpoint, apiKey, cfAccess, timestamp: ts }));
       }
@@ -1747,7 +2189,7 @@ function wireFileTarget(args) {
   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.`
+      `refusing to wire ${client.label}: config path ${sync.resolvedPath} lives under ${sync.matchedPrefix}. Synced volumes propagate credentials across devices: move the config off the sync root, or run wire on the device you want to target.`
     );
   }
   const cfHeaders = {};
@@ -1785,10 +2227,28 @@ function wireFileTarget(args) {
     postSha256: result.postSha256
   };
 }
-function wireClaudeCode(args) {
-  const cmd = "claude";
-  const bridgePath = resolveBridgeScript();
-  const argList = bridgePath ? ["mcp", "add", "--scope", "user", "alter", "--", "node", bridgePath] : [
+function redactSecret(text, secret) {
+  if (!secret) return text;
+  return text.split(secret).join("***redacted***");
+}
+function buildClaudeCodeAddArgs(args) {
+  if (args.subprocessArgv) {
+    return [
+      "mcp",
+      "add",
+      "--scope",
+      "user",
+      "alter",
+      "--env",
+      `ALTER_MCP_ENDPOINT=${MEMBER_BRIDGE_ENDPOINT}`,
+      "--env",
+      `ALTER_PUBLIC_MCP_ENDPOINT=${MEMBER_BRIDGE_ENDPOINT}`,
+      ...args.apiKey ? ["--env", `ALTER_API_KEY=${args.apiKey}`] : [],
+      "--",
+      ...args.subprocessArgv
+    ];
+  }
+  return [
     "mcp",
     "add",
     "--scope",
@@ -1799,12 +2259,28 @@ function wireClaudeCode(args) {
     args.endpoint,
     ...args.apiKey ? ["--header", `X-ALTER-API-Key:${args.apiKey}`] : []
   ];
-  const full = `${cmd} ${argList.join(" ")}`;
+}
+function wireClaudeCode(args) {
+  const cmd = "claude";
+  const bridgePath = resolveBridgeScript();
+  const launcher = args.launcherPath && existsSync(args.launcherPath) ? args.launcherPath : null;
+  const subprocessArgv = launcher ? ["node", launcher, "mcp-bridge"] : bridgePath ? ["node", bridgePath] : null;
+  const argList = buildClaudeCodeAddArgs({
+    apiKey: args.apiKey,
+    subprocessArgv,
+    endpoint: args.endpoint
+  });
+  const full = redactSecret(`${cmd} ${argList.join(" ")}`, args.apiKey);
   const run = spawnSync(cmd, argList, {
     encoding: "utf8",
     shell: process.platform === "win32",
     timeout: 1e4,
-    env: bridgePath ? { ...process.env, ALTER_PUBLIC_MCP_ENDPOINT: args.endpoint, ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {} } : void 0
+    env: subprocessArgv ? {
+      ...process.env,
+      ALTER_MCP_ENDPOINT: MEMBER_BRIDGE_ENDPOINT,
+      ALTER_PUBLIC_MCP_ENDPOINT: MEMBER_BRIDGE_ENDPOINT,
+      ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {}
+    } : void 0
   });
   if (run.error) {
     return {
@@ -1836,14 +2312,17 @@ function wireClaudeCode(args) {
   };
 }
 function resolveBridgeScript() {
-  const { existsSync: existsSync4 } = __require("fs");
-  const { join: join3, dirname: dirname3 } = __require("path");
-  const siblingBridge = join3(dirname3(__filename), "..", "dist", "mcp-bridge.js");
-  if (existsSync4(siblingBridge)) return siblingBridge;
-  const srcBridge = join3(dirname3(__filename), "..", "mcp-bridge.js");
-  if (existsSync4(srcBridge)) return srcBridge;
-  const npmGlobalBridge = join3(dirname3(__filename), "mcp-bridge.js");
-  if (existsSync4(npmGlobalBridge)) return npmGlobalBridge;
+  const here = dirname(fileURLToPath(import.meta.url));
+  const distBinBridge = join(here, "bin", "mcp-bridge.js");
+  if (existsSync(distBinBridge)) return distBinBridge;
+  const nestedDistBinBridge = join(here, "..", "dist", "bin", "mcp-bridge.js");
+  if (existsSync(nestedDistBinBridge)) return nestedDistBinBridge;
+  const siblingBridge = join(here, "..", "dist", "mcp-bridge.js");
+  if (existsSync(siblingBridge)) return siblingBridge;
+  const srcBridge = join(here, "..", "mcp-bridge.js");
+  if (existsSync(srcBridge)) return srcBridge;
+  const npmGlobalBridge = join(here, "mcp-bridge.js");
+  if (existsSync(npmGlobalBridge)) return npmGlobalBridge;
   return null;
 }
 function unwire() {
@@ -1996,19 +2475,19 @@ var TOOL_COSTS = {
   complete_knot: 0,
   check_golden_thread: 0,
   thread_census: 0,
-  // L1 ($0.005)
-  assess_traits: 5e-3,
-  get_trait_snapshot: 5e-3,
-  // L2 ($0.01)
-  get_full_trait_vector: 0.01,
-  get_side_quest_graph: 0.01,
-  // L3 ($0.025)
-  query_graph_similarity: 0.025,
-  // L4 ($0.05)
-  compute_belonging: 0.05,
-  // L5 ($0.50)
-  get_match_recommendations: 0.5,
-  generate_match_narrative: 0.5
+  // L1 ($0.01)
+  assess_traits: 0.01,
+  get_trait_snapshot: 0.01,
+  // L2 ($0.10)
+  get_full_trait_vector: 0.1,
+  get_side_quest_graph: 0.1,
+  // L3 ($0.30)
+  query_graph_similarity: 0.3,
+  // L4 ($0.60)
+  compute_belonging: 0.6,
+  // L5 ($1.00)
+  get_match_recommendations: 1,
+  generate_match_narrative: 1
 };
 var TOOL_BLAST_RADIUS = {
   // Low: read-only reference
@@ -2048,12 +2527,108 @@ var TOOL_BLAST_RADIUS = {
   query_graph_similarity: "high"
 };
 
+// src/pricing.generated.ts
+var GENERATED_TOOL_TIERS = {
+  // L0 (free)
+  alter_presence_read: 0,
+  alter_resolve_handle: 0,
+  check_assessment_status: 0,
+  create_identity_stub: 0,
+  dispute_attestation: 0,
+  get_competencies: 0,
+  get_earning_summary: 0,
+  get_engagement_level: 0,
+  get_identity_earnings: 0,
+  get_identity_trust_score: 0,
+  get_network_stats: 0,
+  get_privacy_budget: 0,
+  get_profile: 0,
+  initiate_assessment: 0,
+  list_archetypes: 0,
+  query_matches: 0,
+  recommend_tool: 0,
+  search_identities: 0,
+  verify_identity: 0,
+  // L1 ($0.01)
+  assess_traits: 1,
+  attest_domain: 1,
+  get_trait_snapshot: 1,
+  poll_requirement_matches: 1,
+  submit_context: 1,
+  submit_social_links: 1,
+  submit_structured_profile: 1,
+  // L2 ($0.10)
+  attest_claim_provenance: 2,
+  get_full_trait_vector: 2,
+  get_side_quest_graph: 2,
+  submit_batch_context: 2,
+  // L3 ($0.30)
+  alter_alignment: 3,
+  query_graph_similarity: 3,
+  // L4 ($0.60)
+  compute_belonging: 4,
+  // L5 ($1.00)
+  generate_match_narrative: 5,
+  get_match_recommendations: 5,
+  query_field: 5
+};
+var GENERATED_TOOL_PRICING = {
+  // L1: $0.01
+  assess_traits: 0.01,
+  attest_domain: 0.01,
+  get_trait_snapshot: 0.01,
+  poll_requirement_matches: 0.01,
+  submit_context: 0.01,
+  submit_social_links: 0.01,
+  submit_structured_profile: 0.01,
+  // L2: $0.10
+  attest_claim_provenance: 0.1,
+  get_full_trait_vector: 0.1,
+  get_side_quest_graph: 0.1,
+  submit_batch_context: 0.1,
+  // L3: $0.30
+  alter_alignment: 0.3,
+  query_graph_similarity: 0.3,
+  // L4: $0.60
+  compute_belonging: 0.6,
+  // L5: $1.00
+  generate_match_narrative: 1,
+  get_match_recommendations: 1,
+  query_field: 1
+};
+var TIER_PRICES = {
+  L0: 0,
+  L1: 0.01,
+  L2: 0.1,
+  L3: 0.3,
+  L4: 0.6,
+  L5: 1
+};
+var ADVERTISED_TOOL_COUNTS = {
+  /** Free (L0) tools visible to anonymous / agent-class callers. */
+  free: 27,
+  /** Premium (L1-L5) tools requiring x402 payment. */
+  premium: 9,
+  /** Messaging tools (member-self-only; excluded from external advertisement). */
+  messaging: 0,
+  /** Total publicly advertised (free + premium). */
+  total: 36
+};
+var REVENUE_SPLIT = {
+  weaver: 0.75,
+  // data subject (Identity Income)
+  facilitator: 0.05,
+  alter: 0.15,
+  treasury: 0.05
+};
+
 // src/homepage.ts
 var HOMEPAGE_LIMITS = {
   whoami_max_chars: 240,
   opener_max_chars: 280,
   pronouns_max_chars: 32,
-  attunement_glyph_max_chars: 16
+  attunement_glyph_max_chars: 16,
+  contact_email_max_chars: 254
 };
 
 // src/themes.ts
@@ -2066,4 +2641,4 @@ var THEME_LIMITS = {
 };
 var OSC8_ALLOWED_SCHEMES = ["https:", "mailto:"];
 
-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, HOMEPAGE_LIMITS, MCPClient, MCP_PROTOCOL_VERSION, OSC8_ALLOWED_SCHEMES, PREMIUM_TOOL_NAMES, SDK_NAME, SDK_VERSION, THEME_LIMITS, 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 };
+export { ADVERTISED_TOOL_COUNTS, ALL_CLIENTS, AlterAuthError, AlterClient, AlterDiscoveryError, AlterError, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, AlterTimeoutError, AlterToolError, BelowFloorError, CLAUDE_CODE, CLAUDE_DESKTOP, CLIENT_CHANNEL, CLIENT_ID, CURSOR, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, FREE_TOOL_NAMES, GENERATED_TOOL_PRICING, GENERATED_TOOL_TIERS, HOMEPAGE_LIMITS, KNOWN_FLOOR_PUBLIC_KEYS, MCPClient, MCP_PROTOCOL_VERSION, MIN_VERSION_ENDPOINT, OSC8_ALLOWED_SCHEMES, PREMIUM_TOOL_NAMES, REVENUE_SPLIT, SDK_NAME, SDK_VERSION, THEME_LIMITS, TIER_PRICES, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, VSCODE, X402Client, base64urlDecode, base64urlEncode2 as base64urlEncode, canonicalArgsSha256, canonicalJson, canonicalStringify, checkMinVersion, clearDiscoveryCache, compareSemver, computeKeyId, 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, verifyFloorSignature, verifyProvenance, verifyToolSignatures, wire, writeWireState };