@truealter/sdk 0.5.0 → 0.5.3

package/dist/bin/alter-identity.js

@@ -2,14 +2,15 @@
 import { p256 } from '@noble/curves/p256';
 import { sha256 } from '@noble/hashes/sha256';
 import { hexToBytes, bytesToHex as bytesToHex$1, randomBytes } from '@noble/hashes/utils';
-import { createHash, createPrivateKey } from 'crypto';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, renameSync, copyFileSync } from 'fs';
+import { createPublicKey, verify, createHash, createPrivateKey } from 'crypto';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, renameSync, statSync, chmodSync, 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 { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
 
 var __defProp = Object.defineProperty;
@@ -362,11 +363,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 || [];
@@ -400,17 +401,326 @@ function ensureMcpPath(url) {
   }
 }
 
-// src/x402.ts
+// src/meta.ts
+var SDK_NAME = "@truealter/sdk";
+var SDK_VERSION = "0.5.3" ;
+
+// 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(
+      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;
   networks;
   assets;
+  // undefined = allowlist check disabled (backward-compatible default).
+  // Non-null = active allowlist; reject any recipient not in the set.
+  recipientAllowlist;
   constructor(opts = {}) {
     this.signer = opts.signer;
     this.maxPerQuery = opts.maxPerQuery !== void 0 ? Number(opts.maxPerQuery) : void 0;
     this.networks = new Set(opts.networks ?? ["base", "base-sepolia"]);
     this.assets = new Set(opts.assets ?? ["USDC"]);
+    if (opts.recipientAllowlist !== void 0) {
+      this.recipientAllowlist = opts.recipientAllowlist.length === 0 ? void 0 : new Set(opts.recipientAllowlist.map((a) => a.toLowerCase()));
+    } else {
+      this.recipientAllowlist = void 0;
+    }
   }
   /**
    * Validate the envelope against this client's policy and, if a signer
@@ -436,6 +746,15 @@ var X402Client = class {
         );
       }
     }
+    if (this.recipientAllowlist !== void 0) {
+      const recipientNorm = (envelope.recipient ?? "").toLowerCase();
+      if (!recipientNorm || !this.recipientAllowlist.has(recipientNorm)) {
+        throw new AlterError(
+          "PAYMENT_REQUIRED",
+          `recipient "${envelope.recipient}" is not on the known-recipient allowlist`
+        );
+      }
+    }
     if (!this.signer) {
       throw new AlterPaymentRequired(envelope.resource ?? "unknown", envelope);
     }
@@ -494,6 +813,9 @@ var MCPClient = class {
   x402;
   signing;
   extraHeaders;
+  preflightHook;
+  preflightPromise = null;
+  preflightDone = false;
   requestCounter = 0;
   initialised = false;
   constructor(opts = {}) {
@@ -502,17 +824,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 preflight hook (D-MIN-VERSION-FLOOR-1) 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: {},
@@ -672,7 +1020,10 @@ var MCPClient = class {
       ...this.extraHeaders ?? {},
       "Content-Type": "application/json",
       Accept: "application/json",
-      "User-Agent": `${this.clientInfo.name}/${this.clientInfo.version}`
+      "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;
@@ -883,9 +1234,46 @@ async function verifyProvenance(envelope, opts = {}) {
       kid: header.kid
     };
   }
+  if (opts.expectedAud !== void 0 && opts.expectedAud !== "") {
+    const tokenAud = payload.aud;
+    const audList = tokenAud === void 0 ? [] : Array.isArray(tokenAud) ? tokenAud : [tokenAud];
+    if (!audList.includes(opts.expectedAud)) {
+      return {
+        valid: false,
+        reason: `aud mismatch: expected "${opts.expectedAud}", got ${JSON.stringify(tokenAud ?? null)}`,
+        payload,
+        kid: header.kid
+      };
+    }
+  }
   return { valid: true, payload, kid: header.kid };
 }
-async function verifyToolSignatures(tools, signatures) {
+async function verifyToolSignatures(tools, signatures, opts = {}) {
+  const jwksUrl = opts.jwksUrl ?? "https://api.truealter.com/.well-known/alter-keys.json";
+  const fetchImpl = opts.fetch ?? fetch;
+  if (!jwksUrl.startsWith("https://")) {
+    return tools.map((t) => ({
+      tool: t.name,
+      valid: false,
+      reason: `jwksUrl must be https: got ${jwksUrl}`
+    }));
+  }
+  const needsJwks = tools.some((t) => {
+    const sig = signatures[t.name];
+    return sig && sig.signature;
+  });
+  let jwks = null;
+  if (needsJwks) {
+    try {
+      jwks = await fetchJwks(jwksUrl, fetchImpl);
+    } catch (err) {
+      return tools.map((t) => ({
+        tool: t.name,
+        valid: false,
+        reason: `jwks fetch failed: ${err.message}`
+      }));
+    }
+  }
   const out = [];
   for (const tool of tools) {
     const sig = signatures[tool.name];
@@ -893,11 +1281,68 @@ async function verifyToolSignatures(tools, signatures) {
       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;
     }
+    const jwsToken = sig.signature;
+    if (!jwsToken) {
+      out.push({ tool: tool.name, valid: true, warn_no_signature: true });
+      continue;
+    }
+    const jwksDoc = jwks;
+    let jHeader;
+    let jPayloadRaw;
+    let jSigBytes;
+    try {
+      const parts2 = jwsToken.split(".");
+      if (parts2.length !== 3) throw new Error("JWS must have three segments");
+      jHeader = JSON.parse(new TextDecoder().decode(base64urlDecode(parts2[0])));
+      jPayloadRaw = new TextDecoder().decode(base64urlDecode(parts2[1]));
+      jSigBytes = base64urlDecode(parts2[2]);
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `malformed tool JWS: ${err.message}` });
+      continue;
+    }
+    if (jHeader.alg !== "ES256") {
+      out.push({ tool: tool.name, valid: false, reason: `unsupported tool sig alg: ${jHeader.alg}` });
+      continue;
+    }
+    if (jPayloadRaw !== sig.schema_hash) {
+      out.push({ tool: tool.name, valid: false, reason: "tool JWS payload does not match schema_hash" });
+      continue;
+    }
+    const jwk = jwksDoc.keys.find((k) => jHeader.kid ? k.kid === jHeader.kid : true);
+    if (!jwk) {
+      out.push({ tool: tool.name, valid: false, reason: `no JWK for kid=${jHeader.kid}` });
+      continue;
+    }
+    let publicKey;
+    try {
+      publicKey = await importEs256JwkAsPublicKey(jwk);
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `jwk import: ${err.message}` });
+      continue;
+    }
+    const parts = jwsToken.split(".");
+    const signedInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    let sigValid = false;
+    try {
+      sigValid = await crypto.subtle.verify(
+        { name: "ECDSA", hash: "SHA-256" },
+        publicKey,
+        toArrayBuffer(jSigBytes),
+        toArrayBuffer(signedInput)
+      );
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `sig verify error: ${err.message}` });
+      continue;
+    }
+    if (!sigValid) {
+      out.push({ tool: tool.name, valid: false, reason: "tool signature mismatch" });
+      continue;
+    }
     out.push({ tool: tool.name, valid: true });
   }
   return out;
@@ -920,23 +1365,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;
@@ -1020,14 +1465,14 @@ 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
@@ -1043,11 +1488,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;
@@ -1060,7 +1515,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.
    */
@@ -1068,11 +1523,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);
@@ -1080,7 +1535,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;
@@ -1180,7 +1635,7 @@ 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
+  // handles. Default closed: recipient must have granted the sender via
   // alter_message_grant. Spec: docs/technical/Alter-to-Alter Messaging.md.
   /** Send a direct message to another tilde handle. */
   async messageSend(args) {
@@ -1214,7 +1669,7 @@ 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" };
@@ -1247,7 +1702,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 } };
@@ -1273,17 +1728,13 @@ function generateClaudeDesktopConfig(opts = {}) {
   const entry = {
     command: bridgeCommand,
     env: env3,
-    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];
   }
   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() {
@@ -1408,7 +1859,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.
@@ -1421,7 +1872,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",
@@ -1473,10 +1924,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) {
@@ -1529,6 +1980,26 @@ function restoreFromBackup(path, backupPath) {
 // src/wire/index.ts
 var TIMESTAMP = () => String(Math.floor(Date.now() / 1e3));
 var ISO_NOW = () => (/* @__PURE__ */ new Date()).toISOString();
+function readCfAccessEnv() {
+  const envPath = join(homedir(), ".config", "alter", "cf-access.env");
+  try {
+    const content = readFileSync(envPath, "utf8");
+    let clientId = "";
+    let clientSecret = "";
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      const key = trimmed.slice(0, eqIdx).replace(/^export\s+/, "").trim();
+      const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, "");
+      if (key === "CF_ACCESS_CLIENT_ID") clientId = val;
+      if (key === "CF_ACCESS_CLIENT_SECRET") clientSecret = val;
+    }
+    if (clientId && clientSecret) return { clientId, clientSecret };
+  } catch {
+  }
+  return void 0;
+}
 function clientById(id) {
   const hit = ALL_CLIENTS.find((c) => c.id === id);
   if (!hit) throw new Error(`unknown client id: ${id}`);
@@ -1537,6 +2008,7 @@ function clientById(id) {
 function wire(opts = {}) {
   const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
   const apiKey = opts.apiKey;
+  const cfAccess = opts.cfAccess ?? readCfAccessEnv();
   const probes = probeAll();
   const selection = opts.only ?? probes.filter((p) => p.installed).map((p) => p.client.id);
   const ts = TIMESTAMP();
@@ -1555,9 +2027,9 @@ function wire(opts = {}) {
     }
     try {
       if (id === "claude-code") {
-        targets.push(wireClaudeCode({ endpoint, apiKey }));
+        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess }));
       } else {
-        targets.push(wireFileTarget({ id, endpoint, apiKey, timestamp: ts }));
+        targets.push(wireFileTarget({ id, endpoint, apiKey, cfAccess, timestamp: ts }));
       }
     } catch (err) {
       const message = err.message;
@@ -1588,10 +2060,15 @@ 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 entry = args.id === "claude-desktop" ? generateClaudeDesktopConfig({ endpoint: args.endpoint, apiKey: args.apiKey }) : generateGenericMcpConfig({ endpoint: args.endpoint, apiKey: args.apiKey });
+  const cfHeaders = {};
+  if (args.cfAccess) {
+    cfHeaders["CF-Access-Client-Id"] = args.cfAccess.clientId;
+    cfHeaders["CF-Access-Client-Secret"] = args.cfAccess.clientSecret;
+  }
+  const entry = args.id === "claude-desktop" ? generateClaudeDesktopConfig({ endpoint: args.endpoint, apiKey: args.apiKey }) : generateGenericMcpConfig({ endpoint: args.endpoint, apiKey: args.apiKey, headers: cfHeaders });
   const rootKey = client.rootKey;
   const serverName = "alter";
   const result = atomicJsonMerge({
@@ -1623,7 +2100,8 @@ function wireFileTarget(args) {
 }
 function wireClaudeCode(args) {
   const cmd = "claude";
-  const argList = [
+  const bridgePath = resolveBridgeScript();
+  const argList = bridgePath ? ["mcp", "add", "--scope", "user", "alter", "--", "node", bridgePath] : [
     "mcp",
     "add",
     "--scope",
@@ -1631,16 +2109,15 @@ function wireClaudeCode(args) {
     "--transport",
     "http",
     "alter",
-    args.endpoint
+    args.endpoint,
+    ...args.apiKey ? ["--header", `X-ALTER-API-Key:${args.apiKey}`] : []
   ];
-  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
+    timeout: 1e4,
+    env: bridgePath ? { ...process.env, ALTER_PUBLIC_MCP_ENDPOINT: args.endpoint, ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {} } : void 0
   });
   if (run.error) {
     return {
@@ -1671,6 +2148,16 @@ function wireClaudeCode(args) {
     reason: `claude mcp add exited ${String(run.status)}`
   };
 }
+function resolveBridgeScript() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  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() {
   const state = readWireState();
   const undone = [];