mycomesh-consumer 0.3.0 → 0.5.0

package/src/consumer.mjs

@@ -9,9 +9,14 @@ import { rpcCall } from "./chain.mjs";
 import { openDelta, openResponse, outputText, prepareRequest, verifiedProvider } from "./protocol.mjs";
 import { recordRequest } from "./disputes.mjs";
 import { chatStream, responseStream } from "./sse.mjs";
+import { consoleRoutes, localRequestAllowed } from "./console.mjs";
+import { pinnedOptions, splitPin } from "./tlspin.mjs";
+import { compareRank, rankKey, reputation } from "./reputation.mjs";
+import { hashApiKey } from "./tenants.mjs";
 
 const PROVIDER_CACHE_MS = 30_000;
 const RELAY_CACHE_MS = 300_000;
+const REPUTATION_CACHE_MS = 600_000;
 const MAX_BODY = 16 * 1024 * 1024;
 
 export function loadNetwork(path) {
@@ -21,14 +26,21 @@ export function loadNetwork(path) {
   return network;
 }
 
-export function httpJson(url, { method = "GET", body, ca, timeoutMs = 330_000 } = {}) {
+async function tlsOptions(target, ca, pin) {
+  if (target.protocol !== "https:") return {};
+  if (pin) return pinnedOptions(target.href, pin);
+  return ca ? { ca: [...rootCertificates, ca] } : {};
+}
+
+export async function httpJson(url, { method = "GET", body, ca, pin, timeoutMs = 330_000 } = {}) {
   const target = new URL(url);
   const data = body === undefined ? undefined : Buffer.from(JSON.stringify(body));
   const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const tls = await tlsOptions(target, ca, pin);
   return new Promise((resolvePromise, reject) => {
     const req = send(target, {
       method, headers: { accept: "application/json", ...(data ? { "content-type": "application/json", "content-length": data.length } : {}) },
-      ...(target.protocol === "https:" && ca ? { ca: [...rootCertificates, ca] } : {}),
+      ...tls,
     }, (res) => {
       const chunks = [];
       let size = 0;
@@ -50,15 +62,16 @@ export function httpJson(url, { method = "GET", body, ca, timeoutMs = 330_000 }
 }
 
 /** POST expecting NDJSON; each line goes to onLine. Non-streamed replies resolve as JSON. */
-export function httpNdjson(url, { body, ca, timeoutMs = 340_000, onLine }) {
+export async function httpNdjson(url, { body, ca, pin, timeoutMs = 340_000, onLine }) {
   const target = new URL(url);
   const data = Buffer.from(JSON.stringify(body));
   const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const tls = await tlsOptions(target, ca, pin);
   return new Promise((resolvePromise, reject) => {
     const req = send(target, {
       method: "POST",
       headers: { accept: "application/x-ndjson", "content-type": "application/json", "content-length": data.length },
-      ...(target.protocol === "https:" && ca ? { ca: [...rootCertificates, ca] } : {}),
+      ...tls,
     }, (res) => {
       const streaming = res.statusCode === 200 && String(res.headers["content-type"] || "").includes("ndjson");
       let buffered = "";
@@ -103,10 +116,9 @@ export async function directoryRelays(network) {
     const base = Number(BigInt(`0x${raw.slice(0, 64)}`));
     if (!Number(BigInt(`0x${raw.slice(64, 128)}`))) continue;
     const entry = raw.slice(base * 2);
-    relays.push({
-      signer: `0x${entry.slice(64 + 24, 128)}`.toLowerCase(),
-      url: decodeString(entry, Number(BigInt(`0x${entry.slice(128, 192)}`))).replace(/\/+$/, ""),
-    });
+    const [url, pin] = splitPin(decodeString(entry, Number(BigInt(`0x${entry.slice(128, 192)}`))));
+    relays.push({ owner: `0x${entry.slice(24, 64)}`.toLowerCase(), signer: `0x${entry.slice(64 + 24, 128)}`.toLowerCase(),
+      url: url.replace(/\/+$/, ""), pin });
   }
   return relays;
 }
@@ -126,6 +138,25 @@ export class Consumer {
     this.relayCache = null;
   }
 
+  /** On-chain reputation and verified probe verdicts for every Provider in view, cached. */
+  async reputations() {
+    if (this.reputationCache && Date.now() - this.reputationCache.at < REPUTATION_CACHE_MS) return this.reputationCache.value;
+    const descriptors = new Map();
+    const relaysByOwner = {};
+    for (const relay of await this.relays()) {
+      try {
+        const owner = relay.owner || `0x${(await rpcCall(this.network.rpc_urls, "eth_call", [{ to: this.network.settlement,
+          data: encodeCall("relaySignerOwner(address)", [["address", relay.signer]]) }, "latest"])).slice(26)}`;
+        relaysByOwner[owner.toLowerCase()] = relay;
+      } catch {}
+      try { for (const descriptor of await this.providers(relay)) descriptors.set(descriptor.provider_signer, descriptor); } catch {}
+    }
+    let value = {};
+    try { value = await reputation(this, [...descriptors.values()], relaysByOwner); } catch {}
+    this.reputationCache = { at: Date.now(), value };
+    return value;
+  }
+
   /** Manifest Relays first, then directory Relays whose /health proves the announced signer. */
   async relays() {
     if (this.relayCache && Date.now() - this.relayCache.at < RELAY_CACHE_MS) return this.relayCache.relays;
@@ -135,7 +166,7 @@ export class Consumer {
       for (const relay of await directoryRelays(this.network)) {
         if (known.has(relay.signer)) continue;
         try {
-          const { status, body } = await this.fetchJson(`${relay.url}/health`, { ca: this.network.tls_ca, timeoutMs: 5_000 });
+          const { status, body } = await this.fetchJson(`${relay.url}/health`, { ca: this.network.tls_ca, pin: relay.pin, timeoutMs: 5_000 });
           if (status === 200 && String(body.relay_signer).toLowerCase() === relay.signer
               && String(body.settlement).toLowerCase() === this.deployment.settlement) {
             relays.push(relay);
@@ -151,7 +182,7 @@ export class Consumer {
   async providers(relay) {
     const cached = this.cache.get(relay.url);
     if (cached && Date.now() - cached.at < PROVIDER_CACHE_MS) return cached.providers;
-    const { status, body } = await this.fetchJson(`${relay.url}/providers`, { ca: this.network.tls_ca, timeoutMs: 10_000 });
+    const { status, body } = await this.fetchJson(`${relay.url}/providers`, { ca: this.network.tls_ca, pin: relay.pin, timeoutMs: 10_000 });
     if (status !== 200) throw new Error(`Relay ${relay.url} /providers returned ${status}`);
     const now = this.now();
     const providers = (body.providers || []).filter((descriptor) => {
@@ -179,7 +210,9 @@ export class Consumer {
           && (!provider || descriptor.provider_signer === provider.toLowerCase()));
       }
       catch (error) { lastError = error; continue; }
-      candidates.sort((a, b) => (a.prices.output_per_1k - b.prices.output_per_1k) || (a.prices.input_per_1k - b.prices.input_per_1k));
+      // What the chain proves ranks first: recent fraud, verified probe failures, reputation; then price.
+      const records = await this.reputations().catch(() => ({}));
+      candidates.sort((a, b) => compareRank(rankKey(a, records[a.provider_signer]), rankKey(b, records[b.provider_signer])));
       for (const descriptor of candidates) {
         const prepared = prepareRequest({
           descriptor, deployment: this.deployment, keyPrivate: this.keyPrivate, relaySigner: relay.signer,
@@ -190,7 +223,7 @@ export class Consumer {
         let final = null;
         try {
           reply = onDelta
-            ? await this.streamJson(`${relay.url}/v11/requests`, { body: prepared.payload, ca: this.network.tls_ca, onLine: (line) => {
+            ? await this.streamJson(`${relay.url}/v11/requests`, { body: prepared.payload, ca: this.network.tls_ca, pin: relay.pin, onLine: (line) => {
               if (line.type === "delta") {
                 streamed.push(openDelta(prepared, line.sealed, streamed.length, this.now()));
                 onDelta(streamed.at(-1));
@@ -198,7 +231,7 @@ export class Consumer {
                 final = line;
               }
             } })
-            : await this.fetchJson(`${relay.url}/v11/requests`, { method: "POST", body: prepared.payload, ca: this.network.tls_ca });
+            : await this.fetchJson(`${relay.url}/v11/requests`, { method: "POST", body: prepared.payload, ca: this.network.tls_ca, pin: relay.pin });
         } catch (error) {
           // The request may have reached the Relay: never replay it elsewhere.
           throw Object.assign(new Error(`request outcome unknown: ${error.message}`), { code: "outcome_unknown", requestId: prepared.authorization.request_id });
@@ -241,7 +274,9 @@ async function readJson(req) {
 }
 
 /** Local OpenAI-compatible endpoint; nothing leaves this machine unsealed except pricing and routing. */
-export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKey } = {}) {
+export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKey, dataDir, tenants = () => ({}) } = {}) {
+  const routes = dataDir ? consoleRoutes({ consumer, dataDir }) : {};
+  const bearer = (req) => /^Bearer (.+)$/.exec(String(req.headers.authorization || ""))?.[1];
   const server = createServer(async (req, res) => {
     let writer = null;
     const send = (status, body, type = "application/json") => {
@@ -249,11 +284,26 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
       res.end(type === "application/json" ? JSON.stringify(body) : body);
     };
     try {
-      if (apiKey && req.headers.authorization !== `Bearer ${apiKey}`) return send(401, openaiError("invalid API key", "unauthorized"));
       const path = new URL(req.url, "http://localhost").pathname.replace(/^\/v1\/v1\//, "/v1/");
+      // A tenant's API key selects its own payment key and budget; tenants may call from anywhere.
+      const tenant = path.startsWith("/v1/") && bearer(req) ? tenants()[hashApiKey(bearer(req))] : undefined;
+      if (!tenant && !localRequestAllowed(req, server.address().port)) {
+        return send(403, openaiError("only this machine may use the local node", "forbidden"));
+      }
+      const active = tenant || consumer;
+      const route = routes[`${req.method} ${path}`];
+      if (route) {
+        if (req.method === "POST" && !String(req.headers["content-type"] || "").startsWith("application/json")) {
+          return send(415, { error: "JSON body required" });
+        }
+        const result = await route(req.method === "POST" ? await readJson(req) : {});
+        return result?.type ? send(200, result.body, result.type) : send(200, result);
+      }
+      if (!tenant && bearer(req) && bearer(req) !== apiKey) return send(401, openaiError("invalid API key", "unauthorized"));
+      if (!tenant && apiKey && bearer(req) !== apiKey) return send(401, openaiError("invalid API key", "unauthorized"));
       if (req.method === "GET" && path === "/health") return send(200, { ok: true, protocol: 11, key: consumer.key });
       if (req.method === "GET" && path === "/v1/models") {
-        return send(200, { object: "list", data: (await consumer.models()).map((id) => ({ id, object: "model", owned_by: "mycomesh" })) });
+        return send(200, { object: "list", data: (await active.models()).map((id) => ({ id, object: "model", owned_by: "mycomesh" })) });
       }
       if (req.method !== "POST" || !["/v1/responses", "/v1/chat/completions", "/responses", "/chat/completions"].includes(path)) {
         return send(404, openaiError("not found", "not_found"));
@@ -269,7 +319,7 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
       delete rest.max_tokens;
       delete rest.max_completion_tokens;
       if (!stream) {
-        const { response } = await consumer.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens, options: rest });
+        const { response } = await active.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens, options: rest });
         return send(200, response.output);
       }
       // Headers go out with the first delta, so a request that fails before dispatch still gets an HTTP error.
@@ -278,12 +328,16 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
         res.write(text);
       };
       writer = chat ? chatStream(write, { model }, { includeUsage: streamOptions?.include_usage === true }) : responseStream(write, { model });
-      const { response } = await consumer.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens,
+      const { response } = await active.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens,
         options: rest, onDelta: (text) => writer.delta(text) });
       writer.finish(response.output);
       return res.end();
     } catch (error) {
       if (res.headersSent) { writer?.fail(error.message); return res.end(); }
+      if (error.message === "wrong wallet password") return send(401, { error: error.message });
+      if (error.status && error.status < 500 && !error.dispatched && routes[`${req.method} ${new URL(req.url, "http://x").pathname}`]) {
+        return send(error.status, { error: error.message });
+      }
       const status = error.code === "outcome_unknown" ? 504 : (error.status && error.status < 500 ? error.status : 502);
       return send(status, openaiError(error.message, error.code || "request_failed"));
     }

package/src/disputes.mjs

@@ -1,5 +1,5 @@
 // V11 Consumer disputes: keep each request's plaintexts locally, reveal them as evidence on demand.
-import { chmodSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalJson } from "./secure-envelope.mjs";
 import { encodeCall, encodeWords, hex, keccak, settlementKey } from "./eip712.mjs";
@@ -52,3 +52,31 @@ export const reportId = (key, reporter, digest) =>
   hex(keccak(encodeWords([["bytes32", key], ["address", reporter], ["bytes32", digest]])));
 
 export const openDisputeCall = (key, digest) => encodeCall("openDispute(bytes32,bytes32)", [["bytes32", key], ["bytes32", digest]]);
+
+function preview(document) {
+  const content = document.endpoint === "chat" ? (document.messages || []).filter((m) => m.role === "user").at(-1)?.content : document.input;
+  const text = typeof content === "string" ? content : Array.isArray(content)
+    ? content.map((part) => (typeof part === "string" ? part : part?.text ?? part?.content ?? "")).join(" ") : JSON.stringify(content ?? "");
+  return String(text).slice(0, 400);
+}
+
+/** Recorded requests, newest first, with short previews (the plaintexts never leave this machine). */
+export function listRequests(dir, outputText, limit = 100) {
+  const folder = journal(dir);
+  if (!existsSync(folder)) return [];
+  return readdirSync(folder).filter((name) => name.endsWith(".json"))
+    .map((name) => JSON.parse(readFileSync(join(folder, name), "utf8")))
+    .sort((a, b) => b.recorded_at - a.recorded_at).slice(0, limit)
+    .map((record) => {
+      let request = {}; let response = {};
+      try { request = JSON.parse(Buffer.from(record.request, "base64").toString("utf8")); } catch {}
+      try { response = JSON.parse(Buffer.from(record.response, "base64").toString("utf8")); } catch {}
+      const { authorization, receipt } = record.signed_receipt;
+      return {
+        settlement_key: record.settlement_key, recorded_at: record.recorded_at, relay_url: record.relay_url,
+        model: request.model, endpoint: request.endpoint, prompt: preview(request),
+        answer: String(outputText(response.output)).slice(0, 600), fee: String(receipt.actual_fee),
+        input_tokens: receipt.input_tokens, output_tokens: receipt.output_tokens, provider: authorization.provider_signer,
+      };
+    });
+}

package/src/probes.mjs

@@ -0,0 +1,70 @@
+// Re-grading Relay probe verdicts (mirrors mycomesh/relay/probes.py and mycomesh/probe_evidence.py).
+import { sha256Hex, outputText } from "./protocol.mjs";
+import { verifySignedReceipt } from "./eip712.mjs";
+
+export const PROBE_EVIDENCE_SCHEMA = "mycomesh.v11.probe-evidence.v1";
+const WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+const numbers = (text) => (text.match(/\d{1,3}(?:[,\s_]\d{3})+(?!\d)|\d+/g) || []).map((match) => match.replace(/[,\s_]/g, ""));
+
+export function buildTask(kind, params) {
+  if (kind === "multiply") return { kind, question: `What is ${params.a} multiplied by ${params.b}?`, reference: String(BigInt(params.a) * BigInt(params.b)), numeric: true };
+  if (kind === "sum") {
+    return { kind, question: `What is the sum of ${params.values.join(", ")}?`, reference: String(params.values.reduce((a, b) => a + Number(b), 0)), numeric: true };
+  }
+  if (kind === "count") {
+    return { kind, question: `How many times does the letter "${params.target}" appear in "${params.letters}"?`,
+      reference: String(params.letters.split(params.target).length - 1), numeric: true };
+  }
+  if (kind === "reverse") return { kind, question: `Write the string "${params.word}" backwards, letter by letter.`, reference: [...params.word].reverse().join(""), numeric: false };
+  if (kind === "sort") return { kind, question: `Sort these words alphabetically: ${params.words.join(", ")}.`, reference: [...params.words].sort().join(", "), numeric: false };
+  if (kind === "weekday") {
+    const day = new Date(`${params.start}T00:00:00Z`);
+    day.setUTCDate(day.getUTCDate() + Number(params.offset));
+    return { kind, question: `What day of the week is ${params.offset} days after ${params.start}?`, reference: WEEKDAYS[(day.getUTCDay() + 6) % 7], numeric: false };
+  }
+  throw new Error(`unknown probe kind ${kind}`);
+}
+
+export function grade(task, answer) {
+  const text = String(answer).trim();
+  if (!text) return "unrelated";
+  if (task.numeric) {
+    const found = numbers(text);
+    return found.length ? (found.includes(task.reference) ? "pass" : "wrong") : "unrelated";
+  }
+  const lower = text.toLowerCase();
+  if (task.kind === "reverse") return lower.includes(task.reference) ? "pass" : "wrong";
+  if (task.kind === "sort") {
+    const positions = task.reference.split(", ").map((word) => lower.indexOf(word));
+    if (positions.every((position) => position < 0)) return "unrelated";
+    return positions.every((p, i) => p >= 0 && (i === 0 || p >= positions[i - 1])) ? "pass" : "wrong";
+  }
+  const named = WEEKDAYS.filter((day) => lower.includes(day.toLowerCase()));
+  if (!named.length) return "unrelated";
+  return named.length === 1 && named[0] === task.reference ? "pass" : "wrong";
+}
+
+function* strings(value) {
+  if (typeof value === "string") yield value;
+  else if (Array.isArray(value)) for (const item of value) yield* strings(item);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) yield* strings(item);
+}
+
+/** Returns { provider, verdict } after re-grading the Provider's own signed answer; throws otherwise. */
+export function verifyProbeEvidence(evidence, deployment) {
+  if (evidence?.schema !== PROBE_EVIDENCE_SCHEMA) throw new Error("not probe evidence");
+  const signed = evidence.signed_receipt;
+  verifySignedReceipt(signed, deployment);
+  const request = Buffer.from(evidence.request, "base64");
+  const response = Buffer.from(evidence.response, "base64");
+  if (sha256Hex(request) !== signed.authorization.request_hash || sha256Hex(response) !== signed.receipt.response_hash) {
+    throw new Error("plaintexts do not match the Provider-signed receipt");
+  }
+  const task = buildTask(evidence.task.kind, evidence.task.params);
+  if (![...strings(JSON.parse(request.toString("utf8")))].some((text) => text.includes(task.question))) {
+    throw new Error("the request does not ask the stated question");
+  }
+  const verdict = grade(task, outputText(JSON.parse(response.toString("utf8")).output));
+  if (verdict !== evidence.verdict || verdict === "unrelated") throw new Error(`re-grading gives ${verdict}`);
+  return { provider: signed.authorization.provider_signer, verdict };
+}

package/src/reputation.mjs

@@ -0,0 +1,86 @@
+// Provider ranking from what the chain and the probe ledger prove, not from what anyone claims.
+import { encodeCall, keccak, hex } from "./eip712.mjs";
+import { rpcCall } from "./chain.mjs";
+import { evidenceHash } from "./disputes.mjs";
+import { verifyProbeEvidence } from "./probes.mjs";
+
+const PROBE_RECORDED = hex(keccak(Buffer.from("ProbeRecorded(address,address,bytes32,bytes32,uint8)")));
+const LOOKBACK_BLOCKS = 50_400n; // about 7 days of 12-second blocks
+const LOG_CHUNK = 10_000n;
+const FRAUD_COOLDOWN = 30 * 86_400;
+const MAX_VERIFIED = 20; // evidence downloads per refresh
+
+const word = (raw, index) => BigInt(`0x${raw.slice(2 + index * 64, 2 + (index + 1) * 64)}`);
+const address = (topic) => `0x${topic.slice(26)}`.toLowerCase();
+
+async function providerRecord(network, signer) {
+  const owner = address((await rpcCall(network.rpc_urls, "eth_call", [{ to: network.settlement,
+    data: encodeCall("providerSignerOwner(address)", [["address", signer]]) }, "latest"])).slice(0, 66));
+  const raw = await rpcCall(network.rpc_urls, "eth_call", [{ to: network.registry,
+    data: encodeCall("providerOf(address)", [["address", owner]]) }, "latest"]);
+  return { owner, counted_volume: word(raw, 10).toString(), counterparties: Number(word(raw, 8)),
+    last_fraud_at: Number(word(raw, 9)), registered_at: Number(word(raw, 5)) };
+}
+
+async function ledgerEvents(network) {
+  if (!network.probe_ledger) return [];
+  const head = BigInt(await rpcCall(network.rpc_urls, "eth_blockNumber", []));
+  const events = [];
+  for (let from = head > LOOKBACK_BLOCKS ? head - LOOKBACK_BLOCKS : 0n; from <= head; from += LOG_CHUNK) {
+    const to = from + LOG_CHUNK - 1n < head ? from + LOG_CHUNK - 1n : head;
+    for (const log of await rpcCall(network.rpc_urls, "eth_getLogs", [{ address: network.probe_ledger, topics: [PROBE_RECORDED],
+      fromBlock: `0x${from.toString(16)}`, toBlock: `0x${to.toString(16)}` }])) {
+      events.push({ provider: address(log.topics[1]), relay: address(log.topics[2]), key: log.topics[3],
+        evidence: `0x${log.data.slice(2, 66)}`, verdict: Number(BigInt(`0x${log.data.slice(66, 130)}`)) === 1 ? "pass" : "wrong" });
+    }
+  }
+  return events;
+}
+
+/**
+ * Per Provider owner: on-chain reputation plus probe verdicts. Passes are counted as reported;
+ * failures count only after this machine re-grades the published evidence, so no Relay can frame anyone.
+ */
+export async function reputation(consumer, descriptors, relaysByOwner) {
+  const network = consumer.network;
+  const records = {};
+  for (const descriptor of descriptors) {
+    try { records[descriptor.provider_signer] = await providerRecord(network, descriptor.provider_signer); } catch {}
+  }
+  let events = [];
+  try { events = await ledgerEvents(network); } catch {}
+  const byOwner = {};
+  for (const record of Object.values(records)) byOwner[record.owner] = { ...record, probes_passed: 0, probes_failed_verified: 0 };
+  let verified = 0;
+  for (const event of events) {
+    const entry = byOwner[event.provider];
+    if (!entry) continue;
+    if (event.verdict === "pass") { entry.probes_passed += 1; continue; }
+    const relay = relaysByOwner[event.relay];
+    if (!relay || verified >= MAX_VERIFIED) continue;
+    verified += 1;
+    try {
+      const { status, body } = await consumer.fetchJson(`${relay.url}/v11/evidence/${event.evidence}`,
+        { ca: network.tls_ca, pin: relay.pin, timeoutMs: 8_000 });
+      if (status === 200 && evidenceHash(body) === event.evidence && verifyProbeEvidence(body, consumer.deployment).verdict === "wrong") {
+        entry.probes_failed_verified += 1;
+      }
+    } catch {}
+  }
+  return Object.fromEntries(Object.entries(records).map(([signer, record]) => [signer, byOwner[record.owner]]));
+}
+
+/** Lower is better: recent confirmed fraud last, then verified probe failure rate, then reputation, then price. */
+export function rankKey(descriptor, record, now = Math.floor(Date.now() / 1000)) {
+  const fraud = record && record.last_fraud_at && now < record.last_fraud_at + FRAUD_COOLDOWN ? 1 : 0;
+  const probes = record ? record.probes_passed + record.probes_failed_verified : 0;
+  const failure = record && probes ? Math.round((10 * record.probes_failed_verified) / probes) : 0;
+  const volume = record ? -Number(BigInt(record.counted_volume) / 1000n) : 0;
+  const price = descriptor.prices.output_per_1k * 1e6 + descriptor.prices.input_per_1k;
+  return [fraud, failure, volume, price];
+}
+
+export function compareRank(a, b) {
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+}

package/src/tenants.mjs

@@ -0,0 +1,69 @@
+// Multi-tenant accounts: one owner deposit, one payment key per tenant with an on-chain budget.
+// A custodial service (or any team) gives each end user an API key; the chain caps what each key can spend.
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { addressOf, encodeCall } from "./eip712.mjs";
+import { rpcCall, sendTransaction } from "./chain.mjs";
+
+const NAME = /^[a-zA-Z0-9_.-]{1,64}$/;
+const file = (dir) => join(dir, "tenants.json");
+export const hashApiKey = (apiKey) => createHash("sha256").update(String(apiKey)).digest("hex");
+
+export function loadTenants(dir) {
+  return existsSync(file(dir)) ? JSON.parse(readFileSync(file(dir), "utf8")).tenants : {};
+}
+
+function saveTenants(dir, tenants) {
+  writeFileSync(file(dir), `${JSON.stringify({ schema: "mycomesh.v11.tenants.v1", tenants }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(file(dir), 0o600);
+}
+
+export function tenantKey(dir, name) {
+  const value = readFileSync(join(dir, "tenants", `${name}.key`), "utf8").trim();
+  return value.startsWith("0x") ? value : `0x${value}`;
+}
+
+/** Create a tenant: a fresh payment key granted on-chain with a per-request cap and a total budget. */
+export async function addTenant(network, dir, ownerPrivate, name, { maxPerRequest, budget = 0n }) {
+  if (!NAME.test(name)) throw new Error("tenant names use letters, digits, '.', '_' and '-'");
+  const tenants = loadTenants(dir);
+  if (tenants[name]) throw new Error(`tenant ${name} already exists`);
+  mkdirSync(join(dir, "tenants"), { recursive: true, mode: 0o700 });
+  const keyPrivate = `0x${randomBytes(32).toString("hex")}`;
+  writeFileSync(join(dir, "tenants", `${name}.key`), `${keyPrivate}\n`, { mode: 0o600 });
+  const key = addressOf(keyPrivate);
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement,
+    data: encodeCall("registerKey(address,uint256,uint64)", [["address", key], ["uint", maxPerRequest], ["uint", 0]]) });
+  if (budget > 0n) await setBudget(network, ownerPrivate, key, budget);
+  const apiKey = `mcm_${randomBytes(24).toString("hex")}`;
+  tenants[name] = { key, max_per_request: String(maxPerRequest), api_key_sha256: hashApiKey(apiKey),
+    created_at: Math.floor(Date.now() / 1000), revoked: false };
+  saveTenants(dir, tenants);
+  return { name, key, api_key: apiKey };
+}
+
+export async function setBudget(network, ownerPrivate, key, budget) {
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement,
+    data: encodeCall("setKeyBudget(address,uint128)", [["address", key], ["uint", budget]]) });
+}
+
+export async function revokeTenant(network, dir, ownerPrivate, name) {
+  const tenants = loadTenants(dir);
+  if (!tenants[name]) throw new Error(`no tenant ${name}`);
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement,
+    data: encodeCall("revokeKey(address)", [["address", tenants[name].key]]) });
+  tenants[name].revoked = true;
+  saveTenants(dir, tenants);
+}
+
+/** Every tenant with its on-chain budget and spend. */
+export async function tenantStatus(network, dir) {
+  const tenants = loadTenants(dir);
+  return Promise.all(Object.entries(tenants).map(async ([name, tenant]) => {
+    const raw = (await rpcCall(network.rpc_urls, "eth_call", [{ to: network.settlement,
+      data: encodeCall("keyBudgets(address)", [["address", tenant.key]]) }, "latest"])).slice(2);
+    return { name, key: tenant.key, max_per_request: tenant.max_per_request, revoked: tenant.revoked,
+      budget: BigInt(`0x${raw.slice(0, 64)}`).toString(), spent: BigInt(`0x${raw.slice(64, 128)}`).toString() };
+  }));
+}

package/src/tlspin.mjs

@@ -0,0 +1,36 @@
+// TLS without certificate authorities: a Relay pins its self-signed certificate on-chain
+// (https://IP:PORT#sha256=<hex> in the RelayDirectoryV11); mirrors mycomesh/tlspin.py.
+import { createHash } from "node:crypto";
+import { connect } from "node:tls";
+
+const PIN_PREFIX = "#sha256=";
+const trusted = new Map(); // pin -> PEM of the certificate that matched it
+
+export function splitPin(endpoint) {
+  const index = String(endpoint).indexOf(PIN_PREFIX);
+  return index < 0 ? [String(endpoint), null] : [endpoint.slice(0, index), endpoint.slice(index + PIN_PREFIX.length).toLowerCase()];
+}
+
+/**
+ * Fetch the Relay's certificate once, check it against the pin, and return
+ * TLS options that trust exactly that certificate (no CA, no host name).
+ */
+export async function pinnedOptions(url, pin) {
+  if (!trusted.has(pin)) {
+    const target = new URL(url);
+    const pem = await new Promise((resolve, reject) => {
+      const socket = connect({ host: target.hostname, port: Number(target.port || 443), rejectUnauthorized: false }, () => {
+        const der = socket.getPeerCertificate(true).raw;
+        socket.end();
+        if (!der || createHash("sha256").update(der).digest("hex") !== pin) {
+          return reject(new Error(`Relay ${target.host} certificate does not match its on-chain pin`));
+        }
+        resolve(`-----BEGIN CERTIFICATE-----\n${der.toString("base64").match(/.{1,64}/g).join("\n")}\n-----END CERTIFICATE-----\n`);
+      });
+      socket.setTimeout(10_000, () => socket.destroy(new Error("TLS handshake timed out")));
+      socket.on("error", reject);
+    });
+    trusted.set(pin, pem);
+  }
+  return { ca: [trusted.get(pin)], checkServerIdentity: () => undefined };
+}

package/src/wallet.mjs

@@ -76,11 +76,12 @@ export async function password(prompt, { confirm = false } = {}) {
 
 export const walletPath = (dir) => join(dir, "owner-wallet.json");
 
-export async function createWallet(dir) {
+export async function createWallet(dir, secret) {
   const path = walletPath(dir);
   if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  if (secret !== undefined && String(secret).length < 8) throw new Error("use a wallet password of at least 8 characters");
   const keystore = encryptKeystore(`0x${randomBytes(32).toString("hex")}`,
-    await password("New wallet password (protects your deposit): ", { confirm: true }));
+    secret ?? await password("New wallet password (protects your deposit): ", { confirm: true }));
   writeFileSync(path, `${JSON.stringify(keystore, null, 2)}\n`, { mode: 0o600 });
   chmodSync(path, 0o600);
   return keystore;
@@ -104,3 +105,10 @@ export function ownerAddress(file, dir) {
   if (/^(0x)?[0-9a-fA-F]{64}$/.test(text)) return addressOf(text.startsWith("0x") ? text : `0x${text}`);
   return walletAddress(JSON.parse(text));
 }
+
+/** Unlock this machine's wallet with a password given by the local console. */
+export function unlockWallet(dir, secret) {
+  const path = walletPath(dir);
+  if (!existsSync(path)) throw new Error("no owner wallet yet");
+  return decryptKeystore(JSON.parse(readFileSync(path, "utf8")), String(secret ?? ""));
+}