lumi-check 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 `npm install lumi-check` (Node >= 20). CLI: `npx lumi-check` or, once installed, `lumi-scan`.
 
-A thin client for checking an x402 seller **before you pay** and, if you choose, contributing **signed,
+A thin client for checking an x402 seller **before you pay** (a free, signed allow/warn/block verdict backed by Lumi's own paid test-buys on XRPL, Base and Stellar) and, if you choose, contributing **signed,
 on-ledger-verifiable delivery receipts** to Lumi ("Tested by Lumi"). Scoring, verification, the catalog and anti-fraud
 stay on Lumi's server.
 
@@ -20,7 +20,7 @@ sent (query strings are dropped). Paying Lumi never changes any score, tier, ran
 ```js
 import { createLumiCheck, x402BeforePaymentHook, mcpOnPaymentRequiredHook, withOutcomeReporting } from "lumi-check";
 
-const lumi = createLumiCheck();             // fail-open, 2.5 s timeout; pin keys with { publicKeys: ["<hex>"] }
+const lumi = createLumiCheck();             // fail-open, 2.5 s timeout; verdicts must be signed by a pinned Lumi key
 
 // From code
 const r = await lumi.check({ url: "https://seller.example/x402/data", payTo: "0x...", amountUsd: 0.01, network: "eip155:8453" });
@@ -40,11 +40,18 @@ CLI: `lumi-scan check https://seller.example/x402/data --pay-to 0x... --amount 0
 
 **Fail mode (defaults):** `fail_mode: "open"` with `timeout_ms: 2500`. If Lumi is slow,
 unreachable, or returns a verdict whose signature does not verify, the result is `warn` (`lumi_unreachable` /
-`lumi_unverified`) and the payment goes ahead. Set `"fail_mode": "closed"` in the config (or `failMode: "closed"`) to
+`lumi_unverified`, or `lumi_untrusted_key` / `lumi_retired_key` when it is signed by a key that is not pinned) and the
+payment goes ahead. Set `"fail_mode": "closed"` in the config (or `failMode: "closed"`) to
 block instead. The detailed paid check (`/v1/trust/check`, x402) adds reason details and a signed `lumi_receipt`.
 
-Verify any Lumi-signed response yourself: `verifyLumiSigned(response, { publicKeys })`, keys at
-`/v1/check/keys` (or `/.well-known/lumi-keys.json`).
+**Pinned keys.** The kit ships Lumi's signing public keys in `src/lumi_keys.js` (`LUMI_SIGNING_KEYS`, with a rotation
+status: `next`, `active` or `retired`) and never fetches keys at runtime, so whoever answers a request cannot choose the
+key it is checked against. A verdict or receipt signed by any other key is rejected with `lumi_untrusted_key` (a retired
+key: `lumi_retired_key`); a key rotation ships as a kit update. Current key: `lsk_5c8c2f54fd228547`.
+`/v1/check/keys` lists the same keys for reference only.
+
+Verify any Lumi-signed response yourself: `verifyLumiSigned(response)` checks against the pinned keys; the result has
+`ok`, `errors`, and on failure `error` + `detail`. `{ publicKeys }` replaces the pins (tests or a self-hosted Lumi only).
 
 ## What is shared
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "lumi-check",
-  "version": "0.1.0",
-  "description": "Lumi Check: a free signed pre-pay check for x402 sellers, plus optional, opt-in signed delivery receipts.",
+  "version": "0.1.1",
+  "description": "Lumi Check: a free signed allow/warn/block check before your agent pays an x402 seller, backed by Lumi's own paid test-buys on XRPL, Base and Stellar. Plus optional, opt-in signed delivery receipts.",
   "license": "Apache-2.0",
   "repository": { "type": "git", "url": "git+https://github.com/lumitrades/lumi-api.git", "directory": "packages/scanner-kit" },
   "homepage": "https://github.com/lumitrades/lumi-api/tree/main/packages/scanner-kit#readme",
   "bugs": { "url": "https://github.com/lumitrades/lumi-api/issues" },
-  "keywords": ["x402", "lumi-check", "pre-pay check", "agent payments", "mcp"],
+  "keywords": ["x402", "lumi-check", "x402-seller-check", "check-seller-before-paying", "payment-safety", "agent-payments", "ai-agents", "pre-pay check", "xrpl", "base", "stellar", "usdc", "mcp"],
   "type": "module",
   "main": "src/index.js",
   "exports": { ".": "./src/index.js" },

package/src/check.js

@@ -10,6 +10,7 @@
  */
 import { originPath } from "./origin.js";
 import { verifyLumiSigned } from "./lumi_signed.js";
+import { pinnedPublicKeys } from "./lumi_keys.js";
 import { loadConfig } from "./config.js";
 import { reportOutcome } from "./telemetry.js";
 import { kitHeader, DEFAULT_API } from "./version.js";
@@ -37,15 +38,11 @@ export function createLumiCheck({ api = DEFAULT_API, publicKeys, timeoutMs, fail
   const base = api.replace(/\/+$/, "");
   const ms = timeoutMs ?? cfg.timeout_ms ?? 2500;
   const mode = (failMode ?? cfg.fail_mode) === "closed" ? "closed" : "open";
-  let keys = publicKeys ?? cfg.public_keys ?? null;
-
-  async function trustedKeys() {
-    if (keys?.length) return keys;
-    const r = await fetchImpl(base + "/v1/check/keys", { headers: { "Lumi-Kit": kitHeader() }, signal: AbortSignal.timeout(ms) });
-    const j = await r.json();
-    keys = (j.keys ?? []).map((k) => k.public_key).filter(Boolean);
-    return keys;
-  }
+  // Pinned keys shipped with the kit. No network fetch and no config-file keys: the server being checked must not be able
+  // to choose the key. `publicKeys` (code only) replaces the pins, for tests or a self-hosted Lumi.
+  if (publicKeys !== undefined && (!Array.isArray(publicKeys) || !publicKeys.length || !publicKeys.every((k) => /^[0-9a-f]{64}$/i.test(String(k)))))
+    throw new TypeError("publicKeys must be a non-empty array of 64-hex Ed25519 public keys");
+  const keys = publicKeys ?? pinnedPublicKeys();
   const unavailable = (code, detail, extra = {}) => ({
     decision: mode === "closed" ? "block" : "warn", reasons: [{ code, severity: mode === "closed" ? "block" : "warn", detail }],
     score: null, link: null, verified: false, fail_mode: mode, unavailable: true, ...extra,
@@ -66,8 +63,11 @@ export function createLumiCheck({ api = DEFAULT_API, publicKeys, timeoutMs, fail
       return unavailable("lumi_unreachable", e?.name === "TimeoutError" ? `No answer within ${ms} ms.` : "Network error reaching Lumi.");
     }
     let v;
-    try { v = verifyLumiSigned(j.receipt, { publicKeys: await trustedKeys(), now: now() }); } catch { v = { ok: false, errors: ["keys_unavailable"] }; }
-    if (!v.ok) return unavailable("lumi_unverified", `Lumi's signature did not verify (${(v.errors ?? []).join(", ")}).`);
+    try { v = verifyLumiSigned(j.receipt, { publicKeys: keys, now: now() }); } catch { v = { ok: false, errors: ["verify_failed"] }; }
+    if (!v.ok) {
+      const keyErr = v.error === "lumi_untrusted_key" || v.error === "lumi_retired_key";
+      return unavailable(keyErr ? v.error : "lumi_unverified", v.detail ?? `Lumi's signature did not verify (${(v.errors ?? []).join(", ")}).`, { errors: v.errors });
+    }
     const p = j.receipt.payload; // the signed payload is the source of truth
     return { decision: p.decision, reasons: p.reasons, score: p.score, link: p.link, matched: p.matched, verified: true, key_id: v.key_id, receipt: j.receipt, fail_mode: mode };
   }

package/src/index.js

@@ -13,6 +13,7 @@ export { testBuy, pickQuote } from "./buy.js";
 export { capsFrom, checkSpend, recordSpend, loadState, saveState, defaultStatePath, DEFAULT_CAPS, HARD_CEILING } from "./caps.js";
 export { originPath } from "./origin.js";
 export { verifyLumiSigned, lumiSignedMessage, lumiKeyId, LUMI_SIGNED_TYPE } from "./lumi_signed.js";
+export { LUMI_SIGNING_KEYS, pinnedPublicKeys, retiredPublicKeys } from "./lumi_keys.js";
 export { loadConfig, saveConfig, recordShareChoice, sharingEnabled, telemetryEnabled, defaultConfigPath, DEFAULT_CONFIG, DISCLOSURE, TIER2_NOTICE, ACCOUNT_DELETE_NOTICE, SHARING_OFF_ERROR } from "./config.js";
 export { maybeAskToShare, shareQuestionState, renderShareQuestion, parseShareAnswer, hintOnce, isCi, SHARE_QUESTION, SHARE_DETAIL, SHARE_HINT } from "./first_run.js";
 export { reportOutcome, buildOutcome, subjectOf, statusClassOf, OUTCOME_FIELDS } from "./telemetry.js";

package/src/lumi_keys.js

@@ -0,0 +1,16 @@
+/**
+ * Pinned Lumi signing keys (public keys only). Lumi Check answers, paid trust/check `lumi_receipt`s and Tested-by-Lumi
+ * badge verdicts are accepted ONLY when signed by a non-retired key from this list. The kit never fetches keys at
+ * runtime: whoever answers a request must not be able to choose the key it is checked against.
+ * Same list as the server (src/trust/lumi_keys.ts) and lumi-trades-mcp (mcp/src/lumi_keys.js); a test keeps them equal.
+ *
+ * Rotation: a new key ships here as "next" first (trusted), becomes "active" when Lumi switches to it, and the old key
+ * becomes "retired" (rejected with lumi_retired_key). See docs/lumi-check-keys.md in the Lumi API repo.
+ */
+export const LUMI_SIGNING_KEYS = Object.freeze([
+  Object.freeze({ key_id: "lsk_5c8c2f54fd228547", public_key: "7d8806265f0ce62af2bf354392246019e5f607ae2470c611bffedba59ef82e52", status: "active", added: "2026-10-23" }),
+]);
+
+/** Public keys the kit trusts by default: every pinned key that is not retired. */
+export const pinnedPublicKeys = (list = LUMI_SIGNING_KEYS) => list.filter((k) => k.status !== "retired").map((k) => k.public_key.toLowerCase());
+export const retiredPublicKeys = (list = LUMI_SIGNING_KEYS) => list.filter((k) => k.status === "retired").map((k) => k.public_key.toLowerCase());

package/src/lumi_signed.js

@@ -2,18 +2,25 @@
  * Verify a Lumi-signed response (free /v1/check receipt, paid trust/check `lumi_receipt`, Tested-by-Lumi badge verdict).
  * Same shape as RECEIPT_FORMAT: receipt_hash = sha256(canonical JSON without receipt_hash and signer);
  * signer.message = `lumi-signed:<kind>:<receipt_hash>`; ed25519 over the UTF-8 message; public key hex; signature base64.
- * Pin Lumi's public key(s) from GET /v1/check/keys (or /.well-known/lumi-keys.json).
+ * Trusted keys default to the keys pinned in this package (./lumi_keys.js), never to keys fetched from the network.
+ * A response signed by any other key fails with `untrusted_key` (error lumi_untrusted_key); a retired pinned key with
+ * `retired_key` (lumi_retired_key).
  */
 import { ed25519 } from "@noble/curves/ed25519";
 import { canonicalJson, sha256Hex, fromHex, unb64, enc } from "./util.js";
+import { pinnedPublicKeys, retiredPublicKeys, LUMI_SIGNING_KEYS } from "./lumi_keys.js";
 
 export const LUMI_SIGNED_TYPE = "lumi_signed_response";
 const HEX64 = /^[0-9a-f]{64}$/i;
 export const lumiSignedMessage = (kind, hash) => `lumi-signed:${kind}:${hash}`;
 export const lumiKeyId = (publicKeyHex) => "lsk_" + sha256Hex(String(publicKeyHex).toLowerCase()).slice(0, 16);
 
-/** @returns {{ ok: boolean, errors: string[], expired: boolean, key_id: string|null }} */
-export function verifyLumiSigned(r, { publicKeys = [], now = Date.now() } = {}) {
+/**
+ * @param publicKeys trusted public keys (hex). Default: the pinned, non-retired Lumi keys. Pass your own only for tests or
+ *   a self-hosted Lumi.
+ * @returns {{ ok: boolean, errors: string[], expired: boolean, key_id: string|null, error?: string, detail?: string }}
+ */
+export function verifyLumiSigned(r, { publicKeys = pinnedPublicKeys(), now = Date.now() } = {}) {
   const errors = [];
   if (!r || typeof r !== "object" || r.type !== LUMI_SIGNED_TYPE) return { ok: false, errors: ["not_a_lumi_signed_response"], expired: false, key_id: null };
   const { receipt_hash: _h, signer: _s, ...body } = r;
@@ -26,9 +33,22 @@ export function verifyLumiSigned(r, { publicKeys = [], now = Date.now() } = {})
     try { good = ed25519.verify(unb64(String(s.signature)), enc.encode(String(s.message)), fromHex(String(s.public_key).toLowerCase())); } catch { good = false; }
     if (!good) errors.push("bad_signature");
     if (s.key_id !== lumiKeyId(s.public_key)) errors.push("key_id_mismatch");
-    if (!publicKeys.map((k) => String(k).toLowerCase()).includes(String(s.public_key).toLowerCase())) errors.push("untrusted_key");
+    const pk = String(s.public_key).toLowerCase();
+    if (!publicKeys.map((k) => String(k).toLowerCase()).includes(pk)) errors.push(retiredPublicKeys().includes(pk) ? "retired_key" : "untrusted_key");
   }
   const expired = !(Date.parse(String(r.expires_at)) >= now);
   if (expired) errors.push("expired");
-  return { ok: errors.length === 0, errors, expired, key_id: s.key_id ?? null };
+  const ok = errors.length === 0;
+  return { ok, errors, expired, key_id: s.key_id ?? null, ...(ok ? {} : explain(errors, s)) };
+}
+
+/** One clear error code + sentence for a failed verification (key problems first: they mean "not from Lumi"). */
+function explain(errors, s) {
+  const kid = typeof s.key_id === "string" ? s.key_id.slice(0, 40) : "unknown";
+  const pinned = LUMI_SIGNING_KEYS.filter((k) => k.status !== "retired").map((k) => k.key_id).join(", ");
+  if (errors.includes("untrusted_key")) return { error: "lumi_untrusted_key", detail: `Signed by key ${kid}, which is not a pinned Lumi signing key (pinned: ${pinned}). Rejected: this answer did not come from Lumi, or this kit is older than a key rotation (update it).` };
+  if (errors.includes("retired_key")) return { error: "lumi_retired_key", detail: `Signed by retired Lumi key ${kid}. Rejected: retired keys are no longer trusted.` };
+  if (errors.includes("unsigned")) return { error: "lumi_unsigned", detail: "The response carries no Lumi signature." };
+  if (errors.includes("expired") && errors.length === 1) return { error: "lumi_expired", detail: "The signed answer has expired; ask Lumi again." };
+  return { error: "lumi_bad_signature", detail: `Lumi's signature did not verify (${errors.join(", ")}).` };
 }