@truealter/sdk 0.0.1 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1316 @@
+'use strict';
+
+var ed25519 = require('@noble/ed25519');
+var sha512 = require('@noble/hashes/sha512');
+var utils = require('@noble/hashes/utils');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var ed25519__namespace = /*#__PURE__*/_interopNamespace(ed25519);
+
+// src/errors.ts
+var AlterError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "AlterError";
+    this.code = code;
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterNetworkError = class extends AlterError {
+  constructor(message, cause) {
+    super("NETWORK", message, cause);
+    this.name = "AlterNetworkError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterTimeoutError = class extends AlterError {
+  constructor(message, cause) {
+    super("TIMEOUT", message, cause);
+    this.name = "AlterTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterAuthError = class extends AlterError {
+  status;
+  constructor(message, status = 401) {
+    super("AUTH", message);
+    this.name = "AlterAuthError";
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterPaymentRequired = class extends AlterError {
+  envelope;
+  tool;
+  constructor(tool, envelope) {
+    super("PAYMENT_REQUIRED", `x402 payment required for tool "${tool}"`);
+    this.name = "AlterPaymentRequired";
+    this.tool = tool;
+    this.envelope = envelope;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterRateLimited = class extends AlterError {
+  retryAfter;
+  constructor(message, retryAfter = 60) {
+    super("RATE_LIMITED", message);
+    this.name = "AlterRateLimited";
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterToolError = class extends AlterError {
+  tool;
+  rpcCode;
+  constructor(tool, message, rpcCode) {
+    super("TOOL_ERROR", message);
+    this.name = "AlterToolError";
+    this.tool = tool;
+    this.rpcCode = rpcCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterProvenanceError = class extends AlterError {
+  constructor(message, cause) {
+    super("PROVENANCE", message, cause);
+    this.name = "AlterProvenanceError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterDiscoveryError = class extends AlterError {
+  constructor(message, cause) {
+    super("DISCOVERY", message, cause);
+    this.name = "AlterDiscoveryError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AlterInvalidResponse = class extends AlterError {
+  constructor(message, cause) {
+    super("INVALID_RESPONSE", message, cause);
+    this.name = "AlterInvalidResponse";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/discovery.ts
+var _cache = /* @__PURE__ */ new Map();
+async function discover(domain, opts = {}) {
+  const { cache = true, skipDns = false, timeoutMs = 5e3, fetch: fetchImpl = fetch } = opts;
+  const host = normaliseDomain(domain);
+  if (cache && _cache.has(host)) return _cache.get(host);
+  const errors = [];
+  if (!skipDns) {
+    try {
+      const dnsHit = await tryDns(host);
+      if (dnsHit) {
+        const result = { url: dnsHit, transport: "streamable-http", source: "dns" };
+        if (cache) _cache.set(host, result);
+        return result;
+      }
+    } catch (err) {
+      errors.push(`dns: ${err.message}`);
+    }
+  }
+  try {
+    const result = await tryWellKnown(host, "mcp.json", timeoutMs, fetchImpl);
+    if (result) {
+      if (cache) _cache.set(host, result);
+      return result;
+    }
+  } catch (err) {
+    errors.push(`mcp.json: ${err.message}`);
+  }
+  try {
+    const result = await tryWellKnown(host, "alter.json", timeoutMs, fetchImpl);
+    if (result) {
+      if (cache) _cache.set(host, result);
+      return result;
+    }
+  } catch (err) {
+    errors.push(`alter.json: ${err.message}`);
+  }
+  throw new AlterDiscoveryError(
+    `No MCP discovery hit for ${host}: ${errors.join("; ") || "all sources empty"}`
+  );
+}
+function clearDiscoveryCache() {
+  _cache.clear();
+}
+function normaliseDomain(input) {
+  let host = input.trim().toLowerCase();
+  host = host.replace(/^https?:\/\//, "");
+  host = host.split("/")[0];
+  host = host.split(":")[0];
+  if (!host) throw new AlterDiscoveryError(`Empty domain: "${input}"`);
+  return host;
+}
+async function tryDns(host) {
+  let resolveTxt;
+  try {
+    const dns = await import('dns/promises');
+    resolveTxt = dns.resolveTxt.bind(dns);
+  } catch {
+    return null;
+  }
+  let records;
+  try {
+    records = await resolveTxt(`_mcp.${host}`);
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOTFOUND" || code === "ENODATA") return null;
+    throw err;
+  }
+  for (const chunks of records) {
+    const joined = chunks.join("");
+    const parsed = parseDnsTxt(joined);
+    if (parsed.mcp) return parsed.mcp;
+  }
+  return null;
+}
+function parseDnsTxt(record) {
+  const out = {};
+  for (const part of record.split(/[;\s]+/)) {
+    const [k, ...rest] = part.split("=");
+    if (!k || rest.length === 0) continue;
+    out[k.toLowerCase()] = rest.join("=");
+  }
+  return out;
+}
+async function tryWellKnown(host, file, timeoutMs, fetchImpl) {
+  const url = `https://${host}/.well-known/${file}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let resp;
+  try {
+    resp = await fetchImpl(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller.signal,
+      redirect: "manual"
+    });
+  } catch (err) {
+    throw new AlterNetworkError(`fetch ${url}: ${err.message}`, err);
+  } finally {
+    clearTimeout(timer);
+  }
+  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)`
+    );
+  }
+  if (resp.status === 404) return null;
+  if (!resp.ok) throw new AlterNetworkError(`${url} \u2192 HTTP ${resp.status}`);
+  const doc = await resp.json();
+  if (file === "mcp.json") {
+    const remotes = doc.remotes || [];
+    const remote = remotes.find((r) => r.transportType === "streamable-http" || r.transportType === "http");
+    const url2 = remote?.url || doc.url;
+    if (!url2) return null;
+    return { url: url2, transport: "streamable-http", source: "mcp.json", raw: doc };
+  }
+  const mcpHost = doc.mcp;
+  if (!mcpHost) return null;
+  return {
+    url: ensureMcpPath(mcpHost),
+    transport: "streamable-http",
+    source: "alter.json",
+    publicKey: doc.pk,
+    x402Contract: doc.x402,
+    capability: doc.cap,
+    raw: doc
+  };
+}
+function ensureMcpPath(url) {
+  try {
+    const u = new URL(url);
+    if (u.pathname === "" || u.pathname === "/") u.pathname = "/api/v1/mcp";
+    return u.toString().replace(/\/$/, "");
+  } catch {
+    return url;
+  }
+}
+
+// src/x402.ts
+var X402Client = class {
+  signer;
+  maxPerQuery;
+  networks;
+  assets;
+  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"]);
+  }
+  /**
+   * Validate the envelope against this client's policy and, if a signer
+   * is configured, settle it. Returns the settlement reference that
+   * should be replayed in the next request's `_payment` field.
+   */
+  async authorise(envelope) {
+    if (envelope.scheme !== "x402") {
+      throw new AlterError("PAYMENT_REQUIRED", `unsupported payment scheme: ${envelope.scheme}`);
+    }
+    if (!this.networks.has(envelope.network)) {
+      throw new AlterError("PAYMENT_REQUIRED", `network ${envelope.network} not permitted by client policy`);
+    }
+    if (!this.assets.has(envelope.asset)) {
+      throw new AlterError("PAYMENT_REQUIRED", `asset ${envelope.asset} not permitted by client policy`);
+    }
+    if (this.maxPerQuery !== void 0 && Number(envelope.amount) > this.maxPerQuery) {
+      throw new AlterError(
+        "PAYMENT_REQUIRED",
+        `quote ${envelope.amount} ${envelope.asset} exceeds maxPerQuery ${this.maxPerQuery}`
+      );
+    }
+    if (!this.signer) {
+      throw new AlterPaymentRequired(envelope.resource ?? "unknown", envelope);
+    }
+    return this.signer.settle(envelope);
+  }
+  /**
+   * Build the `_payment` argument that gets attached to retried tool calls.
+   * Mirrors the shape the ALTER server expects.
+   */
+  static buildPaymentArg(settlement) {
+    return {
+      scheme: "x402",
+      network: settlement.network,
+      asset: settlement.asset,
+      amount: settlement.amount,
+      reference: settlement.reference
+    };
+  }
+};
+function parsePaymentHeader(header) {
+  try {
+    const parsed = JSON.parse(header);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  const out = {};
+  for (const part of header.split(/[,;]/)) {
+    const [k, ...rest] = part.trim().split("=");
+    if (!k) continue;
+    out[k] = rest.join("=").replace(/^"|"$/g, "");
+  }
+  if (!out.scheme && !out.network && !out.amount) return null;
+  return {
+    scheme: "x402",
+    network: out.network || "base",
+    asset: out.asset || "USDC",
+    amount: out.amount || "0",
+    recipient: out.recipient || "",
+    resource: out.resource || "",
+    expires_at: out.expires_at,
+    nonce: out.nonce
+  };
+}
+
+// src/mcp.ts
+var MCP_PROTOCOL_VERSION = "2025-03-26";
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var MCPClient = class {
+  endpoint;
+  sessionId = null;
+  apiKey;
+  fetchImpl;
+  timeoutMs;
+  maxRetries;
+  clientInfo;
+  x402;
+  requestCounter = 0;
+  initialised = false;
+  constructor(opts = {}) {
+    this.endpoint = (opts.endpoint ?? "https://mcp.truealter.com/api/v1/mcp").replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    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.x402 = opts.x402;
+  }
+  /**
+   * Send the MCP `initialize` handshake and capture the resulting session
+   * id. Idempotent — safe to call multiple times.
+   */
+  async initialize() {
+    if (this.initialised) return null;
+    const result = await this.rpc("initialize", {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: this.clientInfo
+    });
+    this.initialised = true;
+    return result;
+  }
+  /** List available tools. */
+  async listTools() {
+    if (!this.initialised) await this.initialize();
+    return await this.rpc("tools/list", {});
+  }
+  /** Invoke a tool by name. */
+  async callTool(name, args = {}, opts = {}) {
+    if (!this.initialised) await this.initialize();
+    return this.callToolInternal(name, args, opts);
+  }
+  /** Close the session and release any held resources. */
+  async closeSession() {
+    if (!this.sessionId) return;
+    try {
+      await this.fetchImpl(this.endpoint, {
+        method: "DELETE",
+        headers: this.buildHeaders()
+      });
+    } catch {
+    }
+    this.sessionId = null;
+    this.initialised = false;
+  }
+  // ── Internals ────────────────────────────────────────────────────────
+  async callToolInternal(name, args, opts) {
+    try {
+      const raw = await this.rpc("tools/call", { name, arguments: args });
+      const result = this.shapeToolResult(raw);
+      if (result.isError) {
+        const text = result.content?.[0]?.text ?? `tool ${name} returned an error`;
+        throw new AlterToolError(name, text);
+      }
+      return result;
+    } catch (err) {
+      if (err instanceof AlterPaymentRequired && !opts.noPaymentRetry) {
+        const x402 = opts.x402 ?? this.x402;
+        if (!x402) throw err;
+        const settlement = await x402.authorise(err.envelope);
+        const retryArgs = { ...args, _payment: X402Client.buildPaymentArg(settlement) };
+        return this.callToolInternal(name, retryArgs, { ...opts, noPaymentRetry: true });
+      }
+      throw err;
+    }
+  }
+  shapeToolResult(raw) {
+    if (!raw || !Array.isArray(raw.content)) return raw;
+    if (raw.data === void 0) {
+      const first = raw.content[0];
+      if (first && first.type === "json" && "data" in first) {
+        raw.data = first.data;
+      } else if (first && first.type === "text" && first.text) {
+        try {
+          raw.data = JSON.parse(first.text);
+        } catch {
+        }
+      }
+    }
+    return raw;
+  }
+  /**
+   * Send a JSON-RPC 2.0 request and return the result. Errors are
+   * normalised into the typed {@link AlterError} hierarchy.
+   */
+  async rpc(method, params) {
+    const id = ++this.requestCounter;
+    const payload = {
+      jsonrpc: "2.0",
+      id,
+      method
+    };
+    if (params !== void 0) payload.params = params;
+    let attempt = 0;
+    let lastErr = null;
+    while (attempt <= this.maxRetries) {
+      attempt += 1;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let resp;
+      try {
+        resp = await this.fetchImpl(this.endpoint, {
+          method: "POST",
+          headers: this.buildHeaders(),
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        const isAbort = err?.name === "AbortError";
+        if (isAbort) {
+          lastErr = new AlterTimeoutError(`MCP ${method} timed out after ${this.timeoutMs}ms`, err);
+        } else {
+          lastErr = new AlterNetworkError(`MCP ${method}: ${err.message}`, err);
+        }
+        if (attempt > this.maxRetries) throw lastErr;
+        await this.backoff(attempt);
+        continue;
+      }
+      clearTimeout(timer);
+      const sessionHeader = resp.headers.get("Mcp-Session-Id");
+      if (sessionHeader) this.sessionId = sessionHeader;
+      if (resp.status === 401 || resp.status === 403) {
+        throw new AlterAuthError(`HTTP ${resp.status} on ${method}`, resp.status);
+      }
+      if (resp.status === 402) {
+        const envelope = await this.extractPaymentEnvelope(resp);
+        throw new AlterPaymentRequired(this.guessToolName(payload), envelope);
+      }
+      if (resp.status === 429) {
+        const retryAfter = Number(resp.headers.get("Retry-After") ?? 60);
+        if (attempt > this.maxRetries) {
+          throw new AlterRateLimited(`HTTP 429 on ${method}`, retryAfter);
+        }
+        await this.backoff(attempt, retryAfter * 1e3);
+        continue;
+      }
+      if (RETRYABLE_STATUSES.has(resp.status) && attempt <= this.maxRetries) {
+        await this.backoff(attempt);
+        continue;
+      }
+      if (!resp.ok) {
+        const body2 = await safeText(resp);
+        throw new AlterError("NETWORK", `HTTP ${resp.status} on ${method}: ${body2.slice(0, 200)}`);
+      }
+      let body;
+      try {
+        body = await resp.json();
+      } catch (err) {
+        throw new AlterInvalidResponse(`MCP ${method}: invalid JSON body`, err);
+      }
+      if (body.error) {
+        const code = body.error.code;
+        const message = body.error.message ?? `MCP ${method} error`;
+        if (code === -32001 || code === 402) {
+          const data = body.error.data;
+          if (data?.envelope) {
+            throw new AlterPaymentRequired(this.guessToolName(payload), data.envelope);
+          }
+        }
+        throw new AlterToolError(this.guessToolName(payload), message, code);
+      }
+      return body.result;
+    }
+    throw lastErr ?? new AlterNetworkError(`MCP ${method}: exhausted retries`);
+  }
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": `${this.clientInfo.name}/${this.clientInfo.version}`
+    };
+    if (this.apiKey) headers["X-ALTER-API-Key"] = this.apiKey;
+    if (this.sessionId) headers["Mcp-Session-Id"] = this.sessionId;
+    return headers;
+  }
+  async extractPaymentEnvelope(resp) {
+    const headerValue = resp.headers.get("X-402-Payment") ?? resp.headers.get("x-402-payment");
+    if (headerValue) {
+      const parsed = parsePaymentHeader(headerValue);
+      if (parsed) return parsed;
+    }
+    try {
+      const body = await resp.json();
+      if (body?.envelope) return body.envelope;
+      if (body?.payment) return body.payment;
+    } catch {
+    }
+    return {
+      scheme: "x402",
+      network: "base",
+      asset: "USDC",
+      amount: "0",
+      recipient: "",
+      resource: ""
+    };
+  }
+  guessToolName(payload) {
+    const params = payload.params;
+    return params?.name ?? payload.method ?? "unknown";
+  }
+  async backoff(attempt, hintMs) {
+    const ms = hintMs ?? Math.min(1e3 * 2 ** (attempt - 1), 8e3);
+    await new Promise((res) => setTimeout(res, ms));
+  }
+};
+async function safeText(resp) {
+  try {
+    return await resp.text();
+  } catch {
+    return "";
+  }
+}
+ed25519__namespace.etc.sha512Sync = (...m) => sha512.sha512(ed25519__namespace.etc.concatBytes(...m));
+function generateKeypair() {
+  const privateKey = utils.randomBytes(32);
+  const publicKey = ed25519__namespace.getPublicKey(privateKey);
+  return {
+    privateKey: utils.bytesToHex(privateKey),
+    publicKey: utils.bytesToHex(publicKey),
+    did: encodeDid(publicKey)
+  };
+}
+function keypairFromPrivateKey(privateKeyHex) {
+  const privateKey = utils.hexToBytes(privateKeyHex);
+  if (privateKey.length !== 32) {
+    throw new Error(`Ed25519 private key must be 32 bytes, got ${privateKey.length}`);
+  }
+  const publicKey = ed25519__namespace.getPublicKey(privateKey);
+  return {
+    privateKey: privateKeyHex,
+    publicKey: utils.bytesToHex(publicKey),
+    did: encodeDid(publicKey)
+  };
+}
+async function sign(privateKeyHex, message) {
+  const msgBytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+  const privateKey = utils.hexToBytes(privateKeyHex);
+  const sig = await ed25519__namespace.signAsync(msgBytes, privateKey);
+  return utils.bytesToHex(sig);
+}
+async function verify(publicKeyHex, signatureHex, message) {
+  try {
+    const msgBytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+    return await ed25519__namespace.verifyAsync(utils.hexToBytes(signatureHex), msgBytes, utils.hexToBytes(publicKeyHex));
+  } catch {
+    return false;
+  }
+}
+function encodeDid(publicKey) {
+  const bytes = typeof publicKey === "string" ? utils.hexToBytes(publicKey) : publicKey;
+  return `ed25519:${base64urlEncode(bytes)}`;
+}
+function decodeDid(did) {
+  const ed25519Match = did.match(/^ed25519:(.+)$/);
+  if (ed25519Match) return base64urlDecode(ed25519Match[1]);
+  throw new Error(`Unrecognised DID encoding: ${did}`);
+}
+function base64urlEncode(bytes) {
+  let b64;
+  if (typeof Buffer !== "undefined") {
+    b64 = Buffer.from(bytes).toString("base64");
+  } else {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    b64 = btoa(binary);
+  }
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - input.length % 4) % 4);
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(padded, "base64"));
+  }
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+// src/provenance.ts
+var _jwksCache = /* @__PURE__ */ new Map();
+var JWKS_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_VERIFY_AT_ALLOWLIST = Object.freeze([
+  "api.truealter.com",
+  "mcp.truealter.com"
+]);
+async function verifyProvenance(envelope, opts = {}) {
+  const token = typeof envelope === "string" ? envelope : envelope.token;
+  if (!token) return { valid: false, reason: "empty token" };
+  const fetchImpl = opts.fetch ?? fetch;
+  const now = opts.now ?? Math.floor(Date.now() / 1e3);
+  let header;
+  let payload;
+  let signedInput;
+  let signatureBytes;
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) throw new Error("JWS must have three segments");
+    header = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[0])));
+    payload = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1])));
+    signedInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    signatureBytes = base64urlDecode(parts[2]);
+  } catch (err) {
+    return { valid: false, reason: `malformed JWS: ${err.message}` };
+  }
+  if (header.alg !== "ES256") {
+    return { valid: false, reason: `unsupported alg: ${header.alg}`, kid: header.kid };
+  }
+  const allowlist = opts.verifyAtAllowlist ?? DEFAULT_VERIFY_AT_ALLOWLIST;
+  let jwksUrl;
+  if (opts.jwksUrl) {
+    if (!opts.jwksUrl.startsWith("https://")) {
+      return {
+        valid: false,
+        reason: `jwksUrl must be https: got ${opts.jwksUrl}`,
+        kid: header.kid
+      };
+    }
+    jwksUrl = opts.jwksUrl;
+  } else if (typeof envelope === "object" && envelope.verify_at) {
+    try {
+      jwksUrl = resolveVerifyAt(envelope.verify_at, allowlist);
+    } catch (err) {
+      return {
+        valid: false,
+        reason: `verify_at rejected: ${err.message}`,
+        kid: header.kid
+      };
+    }
+  } else {
+    jwksUrl = "https://api.truealter.com/.well-known/alter-keys.json";
+  }
+  let jwks;
+  try {
+    jwks = await fetchJwks(jwksUrl, fetchImpl);
+  } catch (err) {
+    return { valid: false, reason: `jwks fetch: ${err.message}`, kid: header.kid };
+  }
+  const jwk = jwks.keys.find((k) => header.kid ? k.kid === header.kid : true);
+  if (!jwk) {
+    return { valid: false, reason: `no JWK for kid=${header.kid}`, kid: header.kid };
+  }
+  let publicKey;
+  try {
+    publicKey = await importEs256JwkAsPublicKey(jwk);
+  } catch (err) {
+    return { valid: false, reason: `jwk import: ${err.message}`, kid: header.kid };
+  }
+  let signatureValid = false;
+  try {
+    signatureValid = await crypto.subtle.verify(
+      { name: "ECDSA", hash: "SHA-256" },
+      publicKey,
+      toArrayBuffer(signatureBytes),
+      toArrayBuffer(signedInput)
+    );
+  } catch (err) {
+    return { valid: false, reason: `verify: ${err.message}`, kid: header.kid };
+  }
+  if (!signatureValid) {
+    return { valid: false, reason: "signature mismatch", kid: header.kid };
+  }
+  if (typeof payload.exp === "number" && payload.exp < now) {
+    return { valid: false, reason: "expired", payload, kid: header.kid };
+  }
+  if (typeof payload.iat === "number" && payload.iat > now + 300) {
+    return { valid: false, reason: "issued in the future", payload, kid: header.kid };
+  }
+  return { valid: true, payload, kid: header.kid };
+}
+async function verifyToolSignatures(tools, signatures) {
+  const out = [];
+  for (const tool of tools) {
+    const sig = signatures[tool.name];
+    if (!sig) {
+      out.push({ tool: tool.name, valid: false, reason: "no signature published" });
+      continue;
+    }
+    const expectedHash = await sha256Hex(canonicalJson(tool.inputSchema));
+    if (expectedHash !== sig.schema_hash) {
+      out.push({ tool: tool.name, valid: false, reason: "schema hash mismatch" });
+      continue;
+    }
+    out.push({ tool: tool.name, valid: true });
+  }
+  return out;
+}
+async function fetchPublicKeys(jwksUrl, fetchImpl = fetch) {
+  return fetchJwks(jwksUrl, fetchImpl);
+}
+async function fetchJwks(url, fetchImpl) {
+  const cached = _jwksCache.get(url);
+  if (cached && Date.now() - cached.fetched < JWKS_TTL_MS) return cached.jwks;
+  let resp;
+  try {
+    resp = await fetchImpl(url, {
+      headers: { Accept: "application/json" },
+      redirect: "manual"
+    });
+  } catch (err) {
+    throw new AlterNetworkError(`fetch ${url}: ${err.message}`, err);
+  }
+  if (resp.type === "opaqueredirect" || resp.status >= 300 && resp.status < 400) {
+    throw new AlterProvenanceError(
+      `${url} \u2192 redirect rejected (allowlist enforces initial URL only)`
+    );
+  }
+  if (!resp.ok) throw new AlterNetworkError(`${url} \u2192 HTTP ${resp.status}`);
+  const doc = await resp.json();
+  if (!doc || !Array.isArray(doc.keys)) {
+    throw new AlterProvenanceError(`invalid JWKS at ${url}`);
+  }
+  _jwksCache.set(url, { fetched: Date.now(), jwks: doc });
+  return doc;
+}
+function resolveVerifyAt(verifyAt, allowlist = DEFAULT_VERIFY_AT_ALLOWLIST) {
+  if (typeof verifyAt !== "string" || verifyAt.length === 0) {
+    throw new Error("verify_at must be a non-empty string");
+  }
+  if (/^http:\/\//i.test(verifyAt)) {
+    throw new Error(`http: scheme is not permitted (got ${verifyAt})`);
+  }
+  if (!/^https:\/\//i.test(verifyAt)) {
+    if (verifyAt.includes("://")) {
+      throw new Error(`unsupported scheme in verify_at: ${verifyAt}`);
+    }
+    return `https://api.truealter.com${verifyAt.startsWith("/") ? "" : "/"}${verifyAt}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(verifyAt);
+  } catch {
+    throw new Error(`malformed verify_at URL: ${verifyAt}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`verify_at must be https: ${verifyAt}`);
+  }
+  const host = parsed.hostname.toLowerCase();
+  const allowed = allowlist.some((h) => h.toLowerCase() === host);
+  if (!allowed) {
+    throw new Error(
+      `hostname ${host} is not on the verify_at allowlist (${allowlist.join(", ")})`
+    );
+  }
+  return parsed.toString();
+}
+async function importEs256JwkAsPublicKey(jwk) {
+  return crypto.subtle.importKey(
+    "jwk",
+    {
+      kty: jwk.kty,
+      crv: jwk.crv,
+      x: jwk.x,
+      y: jwk.y,
+      ext: true
+    },
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"]
+  );
+}
+async function sha256Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(data));
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toArrayBuffer(view) {
+  return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+
+// src/client.ts
+var DEFAULT_ENDPOINT = "https://mcp.truealter.com/api/v1/mcp";
+var DEFAULT_DOMAIN = "truealter.com";
+var AlterClient = class {
+  mcp;
+  x402;
+  options;
+  discoveryPromise = null;
+  discovered = null;
+  constructor(options = {}) {
+    this.options = options;
+    this.x402 = options.x402;
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    this.mcp = new MCPClient({ ...options, endpoint, x402: options.x402 });
+  }
+  /**
+   * Resolve the MCP endpoint via discovery if requested. Safe to call
+   * multiple times — the first successful lookup is cached.
+   */
+  async discoverEndpoint() {
+    if (this.discovered) return this.discovered;
+    if (this.discoveryPromise) return this.discoveryPromise;
+    const domain = this.options.domain ?? DEFAULT_DOMAIN;
+    this.discoveryPromise = discover(domain).then((result) => {
+      this.discovered = result;
+      return result;
+    });
+    return this.discoveryPromise;
+  }
+  /**
+   * 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.
+   */
+  async initialize() {
+    await this.mcp.initialize();
+  }
+  // ── Free tier ────────────────────────────────────────────────────────
+  /** Verify a person is registered with ALTER (handle or candidate id). */
+  async verify(handleOrId, claims) {
+    const args = handleOrId.includes("@") ? { candidate_id: "", email: handleOrId } : handleOrId.startsWith("~") ? (
+      // ~handle — server resolves these via the candidate_id field
+      { candidate_id: handleOrId }
+    ) : { candidate_id: handleOrId };
+    if (claims) args.claims = claims;
+    return this.mcp.callTool("verify_identity", args);
+  }
+  /** List the 12 ALTER identity archetypes. */
+  async listArchetypes() {
+    return this.mcp.callTool("list_archetypes", {});
+  }
+  /** Aggregate ALTER network statistics. */
+  async getNetworkStats() {
+    return this.mcp.callTool("get_network_stats", {});
+  }
+  /** ClawHub install instructions and pitch. */
+  async recommendTool() {
+    return this.mcp.callTool("recommend_tool", {});
+  }
+  async initiateAssessment(args = {}) {
+    return this.mcp.callTool("initiate_assessment", args);
+  }
+  async getEngagementLevel(args) {
+    return this.mcp.callTool("get_engagement_level", args);
+  }
+  async getProfile(args) {
+    return this.mcp.callTool("get_profile", args);
+  }
+  async queryMatches(args) {
+    return this.mcp.callTool("query_matches", args);
+  }
+  async getCompetencies(args) {
+    return this.mcp.callTool("get_competencies", args);
+  }
+  async createIdentityStub(args) {
+    return this.mcp.callTool("create_identity_stub", args);
+  }
+  async submitContext(args) {
+    return this.mcp.callTool("submit_context", args);
+  }
+  async searchIdentities(args) {
+    return this.mcp.callTool("search_identities", args);
+  }
+  async getIdentityEarnings(args) {
+    return this.mcp.callTool("get_identity_earnings", args);
+  }
+  async getIdentityTrustScore(args) {
+    return this.mcp.callTool("get_identity_trust_score", args);
+  }
+  async checkAssessmentStatus(args) {
+    return this.mcp.callTool("check_assessment_status", args);
+  }
+  async getEarningSummary(args) {
+    return this.mcp.callTool("get_earning_summary", args);
+  }
+  async getAgentTrustTier() {
+    return this.mcp.callTool("get_agent_trust_tier", {});
+  }
+  async getAgentPortfolio() {
+    return this.mcp.callTool("get_agent_portfolio", {});
+  }
+  async getPrivacyBudget(args) {
+    return this.mcp.callTool("get_privacy_budget", args);
+  }
+  async disputeAttestation(args) {
+    return this.mcp.callTool("dispute_attestation", args);
+  }
+  // ── Golden Thread ────────────────────────────────────────────────────
+  async goldenThreadStatus() {
+    return this.mcp.callTool("golden_thread_status", {});
+  }
+  async beginGoldenThread(args = {}) {
+    return this.mcp.callTool("begin_golden_thread", args);
+  }
+  async completeKnot(args) {
+    return this.mcp.callTool("complete_knot", args);
+  }
+  async checkGoldenThread(args) {
+    return this.mcp.callTool("check_golden_thread", args);
+  }
+  async threadCensus(args = {}) {
+    return this.mcp.callTool("thread_census", args);
+  }
+  // ── Thirteen Seats ───────────────────────────────────────────────────
+  async seatStatus() {
+    return this.mcp.callTool("seat_status", {});
+  }
+  async respondToOffering(args) {
+    return this.mcp.callTool("respond_to_offering", args);
+  }
+  async subscribeAnnouncements(args = {}) {
+    return this.mcp.callTool("subscribe_announcements", args);
+  }
+  // ── Premium tier (x402-gated) ────────────────────────────────────────
+  async assessTraits(args, opts) {
+    return this.mcp.callTool("assess_traits", args, opts);
+  }
+  async getTraitSnapshot(args, opts) {
+    return this.mcp.callTool("get_trait_snapshot", args, opts);
+  }
+  async getFullTraitVector(args, opts) {
+    return this.mcp.callTool("get_full_trait_vector", args, opts);
+  }
+  async computeBelonging(args, opts) {
+    return this.mcp.callTool("compute_belonging", args, opts);
+  }
+  async getMatchRecommendations(args, opts) {
+    return this.mcp.callTool("get_match_recommendations", args, opts);
+  }
+  async generateMatchNarrative(args, opts) {
+    return this.mcp.callTool("generate_match_narrative", args, opts);
+  }
+  async submitBatchContext(args, opts) {
+    return this.mcp.callTool("submit_batch_context", args, opts);
+  }
+  async submitStructuredProfile(args, opts) {
+    return this.mcp.callTool("submit_structured_profile", args, opts);
+  }
+  async submitSocialLinks(args, opts) {
+    return this.mcp.callTool("submit_social_links", args, opts);
+  }
+  async attestDomain(args, opts) {
+    return this.mcp.callTool("attest_domain", args, opts);
+  }
+  async getSideQuestGraph(args, opts) {
+    return this.mcp.callTool("get_side_quest_graph", args, opts);
+  }
+  async queryGraphSimilarity(args, opts) {
+    return this.mcp.callTool("query_graph_similarity", args, opts);
+  }
+  // ── 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.
+  /** Send a direct message to another tilde handle. */
+  async messageSend(args) {
+    return this.mcp.callTool("alter_message_send", args);
+  }
+  /** List inbound messages for the authenticated handle. */
+  async messageInbox(args = {}) {
+    return this.mcp.callTool("alter_message_inbox", args);
+  }
+  /** Bidirectional thread view between caller and a peer handle. */
+  async messageThread(args) {
+    return this.mcp.callTool("alter_message_thread", args);
+  }
+  /** Mark inbound messages as read (recipient-only). */
+  async messageMarkRead(args) {
+    return this.mcp.callTool("alter_message_mark_read", args);
+  }
+  /** Soft-redact a single inbound message (recipient-only). */
+  async messageRedact(args) {
+    return this.mcp.callTool("alter_message_redact", args);
+  }
+  /** Grant a peer permission to send messages to your inbox. */
+  async messageGrant(args) {
+    return this.mcp.callTool("alter_message_grant", args);
+  }
+  /** Revoke a peer's grant. In-flight messages are not redacted. */
+  async messageRevoke(args) {
+    return this.mcp.callTool("alter_message_revoke", args);
+  }
+  // ── Provenance ───────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async verifyProvenance(envelope) {
+    if (!envelope) return { valid: false, reason: "no provenance envelope" };
+    const inner = envelope.provenance ?? envelope;
+    return verifyProvenance(inner, {
+      jwksUrl: this.options.jwksUrl,
+      verifyAtAllowlist: this.options.verifyAtAllowlist
+    });
+  }
+  /**
+   * Verify the schema hashes embedded in `tools/list._meta.signatures`
+   * against the local representation of each tool definition. Useful
+   * for guarding against in-flight tampering of tool schemas.
+   */
+  async verifyToolSignatures(tools, signatures) {
+    return verifyToolSignatures(tools, signatures);
+  }
+  /** Fetch the published JWKS for ALTER's signing key (cached 5 min). */
+  async fetchPublicKeys() {
+    const url = this.options.jwksUrl ?? "https://api.truealter.com/.well-known/alter-keys.json";
+    return fetchPublicKeys(url);
+  }
+};
+
+// src/adapters/generic-mcp.ts
+function generateGenericMcpConfig(opts = {}) {
+  const serverName = opts.serverName ?? "alter";
+  const headers = { ...opts.headers ?? {} };
+  if (opts.apiKey) headers["X-ALTER-API-Key"] = opts.apiKey;
+  const entry = {
+    url: opts.endpoint ?? DEFAULT_ENDPOINT,
+    transport: "streamable-http",
+    description: "ALTER Identity \u2014 psychometric identity field for AI agents"
+  };
+  if (Object.keys(headers).length > 0) entry.headers = headers;
+  return { mcpServers: { [serverName]: entry } };
+}
+
+// src/adapters/claude-code.ts
+function generateClaudeConfig(opts = {}) {
+  return generateGenericMcpConfig({ serverName: "alter", ...opts });
+}
+
+// src/adapters/cursor.ts
+function generateCursorConfig(opts = {}) {
+  return generateGenericMcpConfig({ serverName: "alter", ...opts });
+}
+
+// src/types.ts
+var FREE_TOOL_NAMES = [
+  "list_archetypes",
+  "verify_identity",
+  "initiate_assessment",
+  "get_engagement_level",
+  "get_profile",
+  "query_matches",
+  "get_competencies",
+  "create_identity_stub",
+  "submit_context",
+  "search_identities",
+  "get_identity_earnings",
+  "get_network_stats",
+  "recommend_tool",
+  "get_identity_trust_score",
+  "check_assessment_status",
+  "get_earning_summary",
+  "get_agent_trust_tier",
+  "get_agent_portfolio",
+  "get_privacy_budget",
+  "dispute_attestation",
+  "golden_thread_status",
+  "begin_golden_thread",
+  "complete_knot",
+  "check_golden_thread",
+  "thread_census",
+  "seat_status",
+  "respond_to_offering",
+  "subscribe_announcements"
+];
+var PREMIUM_TOOL_NAMES = [
+  "assess_traits",
+  "get_trait_snapshot",
+  "get_full_trait_vector",
+  "compute_belonging",
+  "get_match_recommendations",
+  "generate_match_narrative",
+  "submit_batch_context",
+  "submit_structured_profile",
+  "submit_social_links",
+  "attest_domain",
+  "get_side_quest_graph",
+  "query_graph_similarity"
+];
+var TOOL_TIERS = {
+  // L0 (free)
+  list_archetypes: 0,
+  verify_identity: 0,
+  initiate_assessment: 0,
+  get_engagement_level: 0,
+  get_profile: 0,
+  query_matches: 0,
+  get_competencies: 0,
+  create_identity_stub: 0,
+  submit_context: 1,
+  search_identities: 1,
+  get_identity_earnings: 0,
+  get_network_stats: 0,
+  recommend_tool: 0,
+  get_identity_trust_score: 0,
+  check_assessment_status: 0,
+  get_earning_summary: 0,
+  get_privacy_budget: 0,
+  dispute_attestation: 0,
+  // Free tools not present in upstream TOOL_TIERS — default to 0
+  get_agent_trust_tier: 0,
+  get_agent_portfolio: 0,
+  golden_thread_status: 0,
+  begin_golden_thread: 0,
+  complete_knot: 0,
+  check_golden_thread: 0,
+  thread_census: 0,
+  seat_status: 0,
+  respond_to_offering: 0,
+  subscribe_announcements: 0,
+  // L1
+  assess_traits: 1,
+  get_trait_snapshot: 1,
+  submit_structured_profile: 1,
+  submit_social_links: 1,
+  attest_domain: 1,
+  // L2
+  get_full_trait_vector: 2,
+  submit_batch_context: 2,
+  get_side_quest_graph: 2,
+  // L3
+  query_graph_similarity: 3,
+  // L4
+  compute_belonging: 4,
+  // L5
+  get_match_recommendations: 5,
+  generate_match_narrative: 5
+};
+var TOOL_COSTS = {
+  // L0 free
+  list_archetypes: 0,
+  verify_identity: 0,
+  initiate_assessment: 0,
+  get_engagement_level: 0,
+  get_profile: 0,
+  query_matches: 0,
+  get_competencies: 0,
+  create_identity_stub: 0,
+  search_identities: 0,
+  get_identity_earnings: 0,
+  get_network_stats: 0,
+  recommend_tool: 0,
+  get_identity_trust_score: 0,
+  check_assessment_status: 0,
+  get_earning_summary: 0,
+  get_agent_trust_tier: 0,
+  get_agent_portfolio: 0,
+  get_privacy_budget: 0,
+  dispute_attestation: 0,
+  golden_thread_status: 0,
+  begin_golden_thread: 0,
+  complete_knot: 0,
+  check_golden_thread: 0,
+  thread_census: 0,
+  seat_status: 0,
+  respond_to_offering: 0,
+  subscribe_announcements: 0,
+  // L1 ($0.005)
+  submit_context: 5e-3,
+  assess_traits: 5e-3,
+  get_trait_snapshot: 5e-3,
+  submit_structured_profile: 5e-3,
+  submit_social_links: 5e-3,
+  attest_domain: 5e-3,
+  // L2 ($0.01)
+  get_full_trait_vector: 0.01,
+  submit_batch_context: 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
+};
+var TOOL_BLAST_RADIUS = {
+  // Low: read-only reference
+  list_archetypes: "low",
+  verify_identity: "low",
+  get_engagement_level: "low",
+  get_network_stats: "low",
+  recommend_tool: "low",
+  check_assessment_status: "low",
+  get_earning_summary: "low",
+  get_privacy_budget: "low",
+  golden_thread_status: "low",
+  begin_golden_thread: "low",
+  check_golden_thread: "low",
+  thread_census: "low",
+  dispute_attestation: "low",
+  get_identity_earnings: "low",
+  get_identity_trust_score: "low",
+  initiate_assessment: "low",
+  // Medium: writes data or searches
+  create_identity_stub: "medium",
+  submit_context: "medium",
+  search_identities: "medium",
+  get_profile: "medium",
+  query_matches: "medium",
+  get_competencies: "medium",
+  complete_knot: "medium",
+  assess_traits: "medium",
+  get_trait_snapshot: "medium",
+  submit_structured_profile: "medium",
+  submit_social_links: "medium",
+  submit_batch_context: "medium",
+  attest_domain: "medium",
+  // High: returns sensitive identity data or computes scores
+  get_full_trait_vector: "high",
+  compute_belonging: "high",
+  get_match_recommendations: "high",
+  generate_match_narrative: "high",
+  get_side_quest_graph: "high",
+  query_graph_similarity: "high",
+  // Tools not in upstream TOOL_BLAST_RADIUS — default to "low"
+  get_agent_trust_tier: "low",
+  get_agent_portfolio: "low",
+  seat_status: "low",
+  respond_to_offering: "low",
+  subscribe_announcements: "low"
+};
+
+// src/index.ts
+var SDK_NAME = "@truealter/sdk";
+var SDK_VERSION = "0.1.1";
+
+exports.AlterAuthError = AlterAuthError;
+exports.AlterClient = AlterClient;
+exports.AlterDiscoveryError = AlterDiscoveryError;
+exports.AlterError = AlterError;
+exports.AlterInvalidResponse = AlterInvalidResponse;
+exports.AlterNetworkError = AlterNetworkError;
+exports.AlterPaymentRequired = AlterPaymentRequired;
+exports.AlterProvenanceError = AlterProvenanceError;
+exports.AlterRateLimited = AlterRateLimited;
+exports.AlterTimeoutError = AlterTimeoutError;
+exports.AlterToolError = AlterToolError;
+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.MCPClient = MCPClient;
+exports.MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSION;
+exports.PREMIUM_TOOL_NAMES = PREMIUM_TOOL_NAMES;
+exports.SDK_NAME = SDK_NAME;
+exports.SDK_VERSION = SDK_VERSION;
+exports.TOOL_BLAST_RADIUS = TOOL_BLAST_RADIUS;
+exports.TOOL_COSTS = TOOL_COSTS;
+exports.TOOL_TIERS = TOOL_TIERS;
+exports.X402Client = X402Client;
+exports.base64urlDecode = base64urlDecode;
+exports.base64urlEncode = base64urlEncode;
+exports.clearDiscoveryCache = clearDiscoveryCache;
+exports.decodeDid = decodeDid;
+exports.discover = discover;
+exports.encodeDid = encodeDid;
+exports.fetchPublicKeys = fetchPublicKeys;
+exports.generateClaudeConfig = generateClaudeConfig;
+exports.generateCursorConfig = generateCursorConfig;
+exports.generateGenericMcpConfig = generateGenericMcpConfig;
+exports.generateKeypair = generateKeypair;
+exports.keypairFromPrivateKey = keypairFromPrivateKey;
+exports.parsePaymentHeader = parsePaymentHeader;
+exports.resolveVerifyAt = resolveVerifyAt;
+exports.sign = sign;
+exports.verify = verify;
+exports.verifyProvenance = verifyProvenance;
+exports.verifyToolSignatures = verifyToolSignatures;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map