@truealter/sdk 0.0.1 → 0.2.0

package/dist/bin/alter-identity.js

@@ -0,0 +1,1330 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { env, stderr, exit, argv, stdout } from 'process';
+import * as ed25519 from '@noble/ed25519';
+import { sha512 } from '@noble/hashes/sha512';
+import { hexToBytes, bytesToHex, randomBytes } from '@noble/hashes/utils';
+
+// 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 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.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
+function generateKeypair() {
+  const privateKey = randomBytes(32);
+  const publicKey = ed25519.getPublicKey(privateKey);
+  return {
+    privateKey: bytesToHex(privateKey),
+    publicKey: bytesToHex(publicKey),
+    did: encodeDid(publicKey)
+  };
+}
+function keypairFromPrivateKey(privateKeyHex) {
+  const privateKey = hexToBytes(privateKeyHex);
+  if (privateKey.length !== 32) {
+    throw new Error(`Ed25519 private key must be 32 bytes, got ${privateKey.length}`);
+  }
+  const publicKey = ed25519.getPublicKey(privateKey);
+  return {
+    privateKey: privateKeyHex,
+    publicKey: bytesToHex(publicKey),
+    did: encodeDid(publicKey)
+  };
+}
+function encodeDid(publicKey) {
+  const bytes = typeof publicKey === "string" ? hexToBytes(publicKey) : publicKey;
+  return `ed25519:${base64urlEncode(bytes)}`;
+}
+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/index.ts
+var SDK_NAME = "@truealter/sdk";
+var SDK_VERSION = "0.1.1";
+
+// bin/alter-identity.ts
+var CONFIG_DIR = join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "alter");
+var CONFIG_PATH = join(CONFIG_DIR, "identity.json");
+async function main() {
+  const [, , command, ...rest] = argv;
+  switch (command) {
+    case "init":
+      await runInit(rest);
+      break;
+    case "verify":
+      await runVerify(rest);
+      break;
+    case "status":
+      await runStatus();
+      break;
+    case "config":
+      await runConfig(rest);
+      break;
+    case "message":
+      await runMessage(rest);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case void 0:
+      printHelp();
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      stdout.write(`${SDK_NAME} ${SDK_VERSION}
+`);
+      break;
+    default:
+      stderr.write(`unknown command: ${command}
+
+`);
+      printHelp();
+      exit(2);
+  }
+}
+function printHelp() {
+  stdout.write(`${SDK_NAME} ${SDK_VERSION}
+
+Usage:
+  alter-identity init                       Generate Ed25519 keypair, discover MCP, write config
+  alter-identity verify <~handle|email>     Verify an identity
+  alter-identity status                     Show connection state
+  alter-identity config [--claude|--cursor|--generic]
+                                            Print MCP config snippet
+
+Alter-to-Alter Messaging:
+  alter-identity message send <~handle> <body>     Send a direct message (body '-' = stdin)
+  alter-identity message inbox [--unread]          List your inbound messages
+  alter-identity message thread <~handle>          Bidirectional thread view with a peer
+  alter-identity message grant <~handle>           Allow a peer to message you
+  alter-identity message revoke <~handle>          Revoke a peer's grant
+
+Config: ${CONFIG_PATH}
+`);
+}
+async function runInit(args) {
+  const force = args.includes("--force") || args.includes("-f");
+  const existing = readConfig();
+  if (existing && !force) {
+    stdout.write(`already initialised at ${CONFIG_PATH} (re-run with --force to overwrite)
+`);
+    return;
+  }
+  stdout.write("\u2022 Generating Ed25519 keypair...\n");
+  const keypair = generateKeypair();
+  stdout.write("\u2022 Discovering MCP endpoint for truealter.com...\n");
+  let endpoint;
+  try {
+    const result = await discover("truealter.com");
+    endpoint = result.url;
+    stdout.write(`  \u2192 ${endpoint} (via ${result.source})
+`);
+  } catch (err) {
+    endpoint = "https://mcp.truealter.com/api/v1/mcp";
+    stdout.write(`  \u2192 ${endpoint} (discovery failed: ${err.message})
+`);
+  }
+  const cfg = { endpoint, keypair, initialisedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  writeConfig(cfg);
+  stdout.write(`\u2022 Wrote config to ${CONFIG_PATH}
+`);
+  stdout.write(`  did: ${keypair.did}
+`);
+  stdout.write(`
+Next: alter-identity verify ~truealter
+`);
+}
+async function runVerify(args) {
+  const handle = args[0];
+  if (!handle) {
+    stderr.write("usage: alter-identity verify <~handle|email|uuid>\n");
+    exit(2);
+  }
+  const cfg = readConfig() ?? {};
+  const client = new AlterClient({ endpoint: cfg.endpoint, apiKey: cfg.apiKey });
+  try {
+    const result = await client.verify(handle);
+    const text = result.content?.[0]?.text ?? JSON.stringify(result.data ?? result, null, 2);
+    stdout.write(text + "\n");
+  } catch (err) {
+    stderr.write(`verify failed: ${err.message}
+`);
+    exit(1);
+  }
+}
+async function runStatus() {
+  const cfg = readConfig();
+  if (!cfg) {
+    stdout.write(`not initialised \u2014 run \`alter-identity init\`
+`);
+    return;
+  }
+  stdout.write(`config:        ${CONFIG_PATH}
+`);
+  stdout.write(`endpoint:      ${cfg.endpoint ?? "(default)"}
+`);
+  stdout.write(`api key:       ${cfg.apiKey ? "(set)" : "(none)"}
+`);
+  if (cfg.keypair) {
+    const recovered = keypairFromPrivateKey(cfg.keypair.privateKey);
+    stdout.write(`did:           ${recovered.did}
+`);
+  }
+  stdout.write(`initialised:   ${cfg.initialisedAt ?? "(unknown)"}
+`);
+  const client = new AlterClient({ endpoint: cfg.endpoint, apiKey: cfg.apiKey });
+  try {
+    const stats = await client.getNetworkStats();
+    const text = stats.content?.[0]?.text ?? JSON.stringify(stats.data ?? "");
+    stdout.write(`network probe: ok \u2014 ${text.slice(0, 120)}
+`);
+  } catch (err) {
+    stdout.write(`network probe: failed \u2014 ${err.message}
+`);
+  }
+}
+async function runConfig(args) {
+  const cfg = readConfig() ?? {};
+  const opts = { endpoint: cfg.endpoint, apiKey: cfg.apiKey };
+  let out;
+  if (args.includes("--cursor")) out = generateCursorConfig(opts);
+  else if (args.includes("--generic")) out = generateGenericMcpConfig(opts);
+  else out = generateClaudeConfig(opts);
+  stdout.write(JSON.stringify(out, null, 2) + "\n");
+}
+async function runMessage(args) {
+  const [sub, ...rest] = args;
+  if (!sub) {
+    stderr.write("usage: alter-identity message <send|inbox|thread|grant|revoke> ...\n");
+    exit(2);
+  }
+  const cfg = readConfig() ?? {};
+  const client = new AlterClient({ endpoint: cfg.endpoint, apiKey: cfg.apiKey });
+  const printResult = (result) => {
+    const text = result.content?.[0]?.text;
+    if (text) {
+      stdout.write(text + "\n");
+      return;
+    }
+    if (result.data !== void 0) {
+      stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      return;
+    }
+    stdout.write(JSON.stringify(result, null, 2) + "\n");
+  };
+  try {
+    switch (sub) {
+      case "send": {
+        const to = rest[0];
+        let body = rest[1];
+        if (!to || !body) {
+          stderr.write("usage: alter-identity message send <~handle> <body|->\n");
+          exit(2);
+        }
+        if (body === "-") {
+          const chunks = [];
+          for await (const chunk of (await import('process')).stdin) {
+            chunks.push(chunk);
+          }
+          body = Buffer.concat(chunks).toString("utf8").trim();
+          if (!body) {
+            stderr.write("error: empty body on stdin\n");
+            exit(2);
+          }
+        }
+        const result = await client.messageSend({ to, body });
+        printResult(result);
+        break;
+      }
+      case "inbox": {
+        const unreadOnly = rest.includes("--unread");
+        const sinceArg = rest.find((a) => a.startsWith("--since="));
+        const since = sinceArg ? sinceArg.slice("--since=".length) : void 0;
+        const result = await client.messageInbox({
+          unread_only: unreadOnly || void 0,
+          since
+        });
+        printResult(result);
+        break;
+      }
+      case "thread": {
+        const peer = rest[0];
+        if (!peer) {
+          stderr.write("usage: alter-identity message thread <~handle>\n");
+          exit(2);
+        }
+        const result = await client.messageThread({ with: peer });
+        printResult(result);
+        break;
+      }
+      case "grant": {
+        const peer = rest[0];
+        if (!peer) {
+          stderr.write("usage: alter-identity message grant <~handle>\n");
+          exit(2);
+        }
+        const result = await client.messageGrant({ peer });
+        printResult(result);
+        break;
+      }
+      case "revoke": {
+        const peer = rest[0];
+        if (!peer) {
+          stderr.write("usage: alter-identity message revoke <~handle>\n");
+          exit(2);
+        }
+        const result = await client.messageRevoke({ peer });
+        printResult(result);
+        break;
+      }
+      case "mark-read": {
+        const ids = rest.filter((a) => !a.startsWith("--"));
+        if (ids.length === 0) {
+          stderr.write("usage: alter-identity message mark-read <id> [<id> ...]\n");
+          exit(2);
+        }
+        const result = await client.messageMarkRead({ message_ids: ids });
+        printResult(result);
+        break;
+      }
+      case "redact": {
+        const id = rest[0];
+        if (!id) {
+          stderr.write("usage: alter-identity message redact <id>\n");
+          exit(2);
+        }
+        const result = await client.messageRedact({ message_id: id });
+        printResult(result);
+        break;
+      }
+      default:
+        stderr.write(`unknown message subcommand: ${sub}
+`);
+        exit(2);
+    }
+  } catch (err) {
+    stderr.write(`message ${sub} failed: ${err.message}
+`);
+    exit(1);
+  }
+}
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeConfig(cfg) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true, mode: 448 });
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 384 });
+}
+main().catch((err) => {
+  stderr.write(`error: ${err.message}
+`);
+  exit(1);
+});
+//# sourceMappingURL=alter-identity.js.map
+//# sourceMappingURL=alter-identity.js.map