aspl.mjs

// ASPL JavaScript/TypeScript SDK — zero-dependency client for ASPL nodes.
//
// A second independent-language implementation of the ASPL client, to show the
// protocol is language-agnostic (Node 18+, uses built-in fetch + crypto).
//
//   import { ASPLClient } from "./aspl.mjs";
//   const c = new ASPLClient("http://localhost:5010");
//   await c.register("my-js-agent");
//   const matches = await c.need("translate text to french");
//   const cap = await c.get("translate text to french");  // need+accept+deliver+verify

import crypto from "node:crypto";

export class DeliveryVerificationError extends Error {}

// sha256(prefix+nonce) leading-zero-bit count, matching the Python node.
function leadingZeroBits(buf) {
  let bits = 0;
  for (const b of buf) {
    if (b === 0) { bits += 8; continue; }
    for (let i = 7; i >= 0; i--) { if (b & (1 << i)) return bits; bits++; }
    return bits;
  }
  return bits;
}

function solvePow(prefix, difficulty) {
  let n = 0;
  for (;;) {
    const h = crypto.createHash("sha256").update(`${prefix}${n}`).digest();
    if (leadingZeroBits(h) >= difficulty) return String(n);
    n++;
  }
}

// Canonical content hash — must byte-match the Python server (sorted keys,
// compact separators, sha256, first 32 hex chars).
function canonical(value) {
  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
  if (value && typeof value === "object") {
    return "{" + Object.keys(value).sort().map(
      k => JSON.stringify(k) + ":" + canonical(value[k])).join(",") + "}";
  }
  return JSON.stringify(value);
}

export function contentHash(content) {
  const hex = crypto.createHash("sha256").update(canonical(content)).digest("hex");
  return `sha256:${hex.slice(0, 32)}`;
}

// Verify an Ed25519 signature given a raw 32-byte hex public key.
const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
export function verifySig(pubHex, message, sigHex) {
  try {
    const der = Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(pubHex, "hex")]);
    const key = crypto.createPublicKey({ key: der, format: "der", type: "spki" });
    return crypto.verify(null, Buffer.from(message), key, Buffer.from(sigHex, "hex"));
  } catch {
    return false;
  }
}

export class ASPLClient {
  constructor(baseUrl = "http://localhost:5010", apiKey = null) {
    this.base = baseUrl.replace(/\/$/, "");
    this.apiKey = apiKey;
    this.agentId = null;
    this.nodePublicKey = null;
  }

  async _req(method, path, body) {
    const headers = { "Content-Type": "application/json" };
    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
    const res = await fetch(`${this.base}${path}`,
      { method, headers, body: body ? JSON.stringify(body) : undefined });
    if (!res.ok) throw new Error(`ASPL ${method} ${path} → ${res.status}: ${await res.text()}`);
    return res.json();
  }

  async register(name, environment = null) {
    const ch = await this._req("GET", "/v1/pow/challenge");
    const nonce = solvePow(ch.prefix, ch.difficulty);
    const body = { name, pow_challenge_id: ch.challenge_id, pow_nonce: nonce };
    if (environment) body.environment = environment;
    const r = await this._req("POST", "/v1/register", body);
    this.apiKey = r.api_key;
    this.agentId = r.agent_id;
    this.nodePublicKey = (r.passport?.shop_public_key || "").replace("ed25519:", "");
    return r;
  }

  async publish(cap) { return this._req("POST", "/v1/publish", cap); }

  async need(intent, opts = {}) {
    const r = await this._req("POST", "/v1/need",
      { intent, max_results: opts.maxResults ?? 5, min_trust: opts.minTrust ?? 0.0,
        include_imported: opts.includeImported ?? true,
        ...(opts.typeFilter ? { type_filter: opts.typeFilter } : {}) });
    return r.matches;
  }

  async accept(capabilityId) { return this._req("POST", "/v1/accept", { capability_id: capabilityId }); }

  async deliver(transactionId, verify = true) {
    const d = await this._req("GET", `/v1/deliver/${transactionId}`);
    if (verify) {
      const { ok, reason } = this.verifyDelivery(d);
      if (!ok) throw new DeliveryVerificationError(`delivery ${transactionId}: ${reason}`);
    }
    return d;
  }

  verifyDelivery(delivery) {
    const cap = delivery.capability || {};
    const recomputed = contentHash(delivery.content || {});
    if (cap.content_hash !== recomputed)
      return { ok: false, reason: `hash mismatch (${cap.content_hash} vs ${recomputed})` };
    let nodeKey = cap.shop_public_key || this.nodePublicKey || "";
    nodeKey = nodeKey.replace("ed25519:", "");
    const msg = `deliver:${delivery.transaction_id}:${cap.content_hash}`;
    if (!cap.shop_signature || !nodeKey) return { ok: false, reason: "missing signature/key" };
    if (!verifySig(nodeKey, msg, cap.shop_signature)) return { ok: false, reason: "signature invalid" };
    return { ok: true, reason: "ok" };
  }

  async confirm(transactionId, success, feedback = null) {
    const body = { transaction_id: transactionId, success };
    if (feedback) body.feedback = feedback;
    return this._req("POST", "/v1/confirm", body);
  }

  async get(intent, typeFilter = null) {
    const matches = await this.need(intent, { maxResults: 1, typeFilter });
    if (!matches.length) throw new Error(`no capability for: ${intent}`);
    const txn = await this.accept(matches[0].id);
    const d = await this.deliver(txn.transaction_id);
    return { capability: d.capability, content: d.content, transactionId: txn.transaction_id };
  }

  async ingestMcp(serverUrl, tools) { return this._req("POST", "/v1/ingest/mcp", { server_url: serverUrl, tools }); }
  async ingestMcpUrl(serverUrl) { return this._req("POST", "/v1/ingest/mcp/url", { server_url: serverUrl }); }
  async revoke(capabilityId, reason) { return this._req("POST", "/v1/revoke", { capability_id: capabilityId, reason }); }
  async revocations() { return this._req("GET", "/v1/revocations"); }

  // Transparency log
  async logSth() { return this._req("GET", "/v1/log/sth"); }
  async logInclusion(idx) { return this._req("GET", `/v1/log/proof/inclusion?leaf_index=${idx}`); }
  async logConsistency(first, second) { return this._req("GET", `/v1/log/proof/consistency?first=${first}&second=${second}`); }
  async logLeaves(start = 0, end = null) {
    const qs = end != null ? `?start=${start}&end=${end}` : `?start=${start}`;
    return this._req("GET", `/v1/log/leaves${qs}`);
  }

  // Federation
  async federate(peerUrl) { return this._req("POST", "/v1/federation/mirror", { peer_url: peerUrl }); }
  async acquireFederated(capId) { return this._req("POST", "/v1/federation/acquire", { capability_id: capId }); }

  // Discovery / catalog
  async catalog(opts = {}) {
    const params = new URLSearchParams();
    if (opts.limit != null) params.set("limit", opts.limit);
    if (opts.offset != null) params.set("offset", opts.offset);
    if (opts.type) params.set("type", opts.type);
    const qs = params.toString() ? `?${params}` : "";
    return this._req("GET", `/v1/catalog${qs}`);
  }
  async stats() { return this._req("GET", "/v1/stats"); }
  async capability(capId) { return this._req("GET", `/v1/capability/${encodeURIComponent(capId)}`); }
  async passport(agentId) { return this._req("GET", `/v1/passport/${encodeURIComponent(agentId)}`); }

  // Node discovery
  async wellKnown() { return this._req("GET", "/.well-known/aspl"); }
}