@truealter/sdk 0.5.0 → 0.5.3

package/dist/index.cjs

@@ -4,13 +4,14 @@ var p256 = require('@noble/curves/p256');
 var sha256 = require('@noble/hashes/sha256');
 var utils = require('@noble/hashes/utils');
 var crypto$1 = require('crypto');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
 var ed25519 = require('@noble/ed25519');
 var sha512 = require('@noble/hashes/sha512');
+var url = require('url');
 var child_process = require('child_process');
-var os = require('os');
-var path = require('path');
 var process$1 = require('process');
-var fs = require('fs');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -54,8 +55,11 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
   "node_modules/tsup/assets/cjs_shims.js"() {
+    getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+    importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
   }
 });
 
@@ -402,11 +406,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 || [];
@@ -440,6 +444,313 @@ function ensureMcpPath(url) {
   }
 }
 
+// src/floor-preflight.ts
+init_cjs_shims();
+
+// src/meta.ts
+init_cjs_shims();
+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 = crypto$1.createPublicKey({ key: publicKeyPem, format: "pem" });
+  const jwk = pub.export({ format: "jwk" });
+  const rawBytes = Buffer.from(jwk.x, "base64url");
+  return crypto$1.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 = crypto$1.createPublicKey({ key: pem, format: "pem" });
+    const canonical = canonicalJson({
+      floors: doc.floors,
+      served_at: doc.served_at
+    });
+    return crypto$1.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 ?? path.join(os.homedir(), ".config");
+  return path.join(xdg, "alter", "floor-cache.json");
+}
+function readDiskCache(path, knownKeys) {
+  if (process.platform !== "win32") {
+    let st;
+    try {
+      st = fs.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 = fs.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$1, doc, now_ms) {
+  const entry = { doc, fetched_at_ms: now_ms };
+  const payload = JSON.stringify(entry);
+  try {
+    fs.mkdirSync(path.dirname(path$1), { recursive: true, mode: 448 });
+    const tmp = `${path$1}.tmp`;
+    fs.writeFileSync(tmp, payload, { mode: 384 });
+    try {
+      fs.chmodSync(tmp, 384);
+    } catch {
+    }
+    fs.renameSync(tmp, path$1);
+  } catch {
+  }
+}
+function defaultApiBase() {
+  return process.env.ALTER_API ?? "https://api.truealter.com";
+}
+
 // src/mcp.ts
 init_cjs_shims();
 
@@ -450,11 +761,19 @@ var X402Client = class {
   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
@@ -480,6 +799,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);
     }
@@ -538,6 +866,9 @@ var MCPClient = class {
   x402;
   signing;
   extraHeaders;
+  preflightHook;
+  preflightPromise = null;
+  preflightDone = false;
   requestCounter = 0;
   initialised = false;
   constructor(opts = {}) {
@@ -546,17 +877,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: {},
@@ -716,7 +1073,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;
@@ -952,9 +1312,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];
@@ -962,11 +1359,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;
@@ -989,23 +1443,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;
@@ -1089,14 +1543,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
@@ -1112,11 +1566,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;
@@ -1129,7 +1593,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.
    */
@@ -1137,11 +1601,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);
@@ -1149,7 +1613,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;
@@ -1249,7 +1713,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) {
@@ -1283,7 +1747,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" };
@@ -1323,7 +1787,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 } };
@@ -1351,7 +1815,7 @@ function generateClaudeDesktopConfig(opts = {}) {
   const entry = {
     command: bridgeCommand,
     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];
@@ -1362,11 +1826,6 @@ function generateClaudeDesktopConfig(opts = {}) {
 // src/wire/index.ts
 init_cjs_shims();
 
-// src/meta.ts
-init_cjs_shims();
-var SDK_NAME = "@truealter/sdk";
-var SDK_VERSION = "0.3.0";
-
 // src/wire/paths.ts
 init_cjs_shims();
 var HOME = os.homedir();
@@ -1499,7 +1958,7 @@ function probeAll() {
 // src/wire/sync.ts
 init_cjs_shims();
 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.
@@ -1512,7 +1971,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",
@@ -1570,10 +2029,10 @@ function atomicJsonMerge(opts) {
     preBytes = fs.readFileSync(path$1, "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$1}: existing file is not valid JSON (${err.message}). Hand-fix the file, then re-run \`alter-identity wire\`.`
+          `refusing to wire ${path$1}: 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) {
@@ -1626,6 +2085,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 = path.join(os.homedir(), ".config", "alter", "cf-access.env");
+  try {
+    const content = fs.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}`);
@@ -1634,6 +2113,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();
@@ -1652,9 +2132,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;
@@ -1685,10 +2165,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({
@@ -1720,7 +2205,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",
@@ -1728,16 +2214,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 = child_process.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 {
@@ -1768,6 +2253,16 @@ function wireClaudeCode(args) {
     reason: `claude mcp add exited ${String(run.status)}`
   };
 }
+function resolveBridgeScript() {
+  const here = path.dirname(url.fileURLToPath(importMetaUrl));
+  const siblingBridge = path.join(here, "..", "dist", "mcp-bridge.js");
+  if (fs.existsSync(siblingBridge)) return siblingBridge;
+  const srcBridge = path.join(here, "..", "mcp-bridge.js");
+  if (fs.existsSync(srcBridge)) return srcBridge;
+  const npmGlobalBridge = path.join(here, "mcp-bridge.js");
+  if (fs.existsSync(npmGlobalBridge)) return npmGlobalBridge;
+  return null;
+}
 function unwire() {
   const state = readWireState();
   const undone = [];
@@ -1919,19 +2414,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
@@ -1971,13 +2466,110 @@ var TOOL_BLAST_RADIUS = {
   query_graph_similarity: "high"
 };
 
+// src/pricing.generated.ts
+init_cjs_shims();
+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: 26,
+  /** Premium (L1-L5) tools requiring x402 payment. */
+  premium: 8,
+  /** Messaging tools (member-self-only; excluded from external advertisement). */
+  messaging: 0,
+  /** Total publicly advertised (free + premium). */
+  total: 34
+};
+var REVENUE_SPLIT = {
+  weaver: 0.75,
+  // data subject (Identity Income)
+  facilitator: 0.05,
+  alter: 0.15,
+  treasury: 0.05
+};
+
 // src/homepage.ts
 init_cjs_shims();
 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
@@ -1991,6 +2583,7 @@ var THEME_LIMITS = {
 };
 var OSC8_ALLOWED_SCHEMES = ["https:", "mailto:"];
 
+exports.ADVERTISED_TOOL_COUNTS = ADVERTISED_TOOL_COUNTS;
 exports.ALL_CLIENTS = ALL_CLIENTS;
 exports.AlterAuthError = AlterAuthError;
 exports.AlterClient = AlterClient;
@@ -2003,21 +2596,30 @@ exports.AlterProvenanceError = AlterProvenanceError;
 exports.AlterRateLimited = AlterRateLimited;
 exports.AlterTimeoutError = AlterTimeoutError;
 exports.AlterToolError = AlterToolError;
+exports.BelowFloorError = BelowFloorError;
 exports.CLAUDE_CODE = CLAUDE_CODE;
 exports.CLAUDE_DESKTOP = CLAUDE_DESKTOP;
+exports.CLIENT_CHANNEL = CLIENT_CHANNEL;
+exports.CLIENT_ID = CLIENT_ID;
 exports.CURSOR = CURSOR;
 exports.DEFAULT_DOMAIN = DEFAULT_DOMAIN;
 exports.DEFAULT_ENDPOINT = DEFAULT_ENDPOINT;
 exports.DEFAULT_VERIFY_AT_ALLOWLIST = DEFAULT_VERIFY_AT_ALLOWLIST;
 exports.FREE_TOOL_NAMES = FREE_TOOL_NAMES;
+exports.GENERATED_TOOL_PRICING = GENERATED_TOOL_PRICING;
+exports.GENERATED_TOOL_TIERS = GENERATED_TOOL_TIERS;
 exports.HOMEPAGE_LIMITS = HOMEPAGE_LIMITS;
+exports.KNOWN_FLOOR_PUBLIC_KEYS = KNOWN_FLOOR_PUBLIC_KEYS;
 exports.MCPClient = MCPClient;
 exports.MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSION;
+exports.MIN_VERSION_ENDPOINT = MIN_VERSION_ENDPOINT;
 exports.OSC8_ALLOWED_SCHEMES = OSC8_ALLOWED_SCHEMES;
 exports.PREMIUM_TOOL_NAMES = PREMIUM_TOOL_NAMES;
+exports.REVENUE_SPLIT = REVENUE_SPLIT;
 exports.SDK_NAME = SDK_NAME;
 exports.SDK_VERSION = SDK_VERSION;
 exports.THEME_LIMITS = THEME_LIMITS;
+exports.TIER_PRICES = TIER_PRICES;
 exports.TOOL_BLAST_RADIUS = TOOL_BLAST_RADIUS;
 exports.TOOL_COSTS = TOOL_COSTS;
 exports.TOOL_TIERS = TOOL_TIERS;
@@ -2026,8 +2628,12 @@ exports.X402Client = X402Client;
 exports.base64urlDecode = base64urlDecode;
 exports.base64urlEncode = base64urlEncode2;
 exports.canonicalArgsSha256 = canonicalArgsSha256;
+exports.canonicalJson = canonicalJson;
 exports.canonicalStringify = canonicalStringify;
+exports.checkMinVersion = checkMinVersion;
 exports.clearDiscoveryCache = clearDiscoveryCache;
+exports.compareSemver = compareSemver;
+exports.computeKeyId = computeKeyId;
 exports.decodeDid = decodeDid;
 exports.detectSyncedVolume = detectSyncedVolume;
 exports.discover = discover;
@@ -2051,6 +2657,7 @@ exports.sign = sign;
 exports.signInvocation = signInvocation;
 exports.unwire = unwire;
 exports.verify = verify;
+exports.verifyFloorSignature = verifyFloorSignature;
 exports.verifyProvenance = verifyProvenance;
 exports.verifyToolSignatures = verifyToolSignatures;
 exports.wire = wire;