@ninsei-labs/sdk 0.43.1 → 0.43.3

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.43.3 — 2026-10-18
+
+THE SAME CONTENT AS 0.43.2, PUBLISHED UNDER A NEW NUMBER. The tag-triggered release for 0.43.2 stopped in
+`pnpm/action-setup` before building anything: the workflow named pnpm 12.10.1 while `packageManager` names
+12.11.2, and the action refuses two versions (`ERR_PNPM_BAD_PM_VERSION`). Nothing reached the registry. The
+workflow now reads `packageManager` and pins no version of its own; this release carries that fix and the
+0.43.2 content unchanged.
+
+- `./provider` (Node only) and the two bound verification helpers in `./order` are as described in 0.43.2.
+- The display-name draw uses `randomInt`, as fixed in 0.43.2.
+- No package code changed between 0.43.2 and 0.43.3; only the release pipeline did.
+
+## 0.43.2 — 2026-10-18
+
+THE PROVIDER SIDE AND THE BOUND VERIFICATION HELPERS ARE PUBLIC. Two things the demo and the node used to reach
+through the node's own files are now package surface: `./order` exports `orderQuoteMissingFields` and
+`recoverOrderQuoteKey` (the spec functions bound to the SDK's primitives), and a new Node-only subpath
+`./provider` carries the provider's identity, signing and env-file helpers. A consumer no longer re-derives the
+provider code rule or the public-key path, and the browser entries stay free of `node:fs` and `node:crypto`.
+
+- `./order` gains two names: `orderQuoteMissingFields(quote)` and `recoverOrderQuoteKey(quote)`. Both are the
+  spec's own functions bound to `primitives.mjs`, so verification has one implementation, not two.
+- `./provider` is a separate entry because it reaches the filesystem and `node:crypto`: the provider code of an
+  address, the public key path beside a private key, key generation, payload signing and verification, and the
+  settings-file helpers (`findEnvFile`, `readEnvFile`, `applyEnvFile`, `substituteEnvVars`).
+- The checks gained a `provider` case: the provider code is the address's own name and stable, the public key
+  path follows the private one, a settings file is found, read and applied, and the bound quote verification
+  names what is missing and recovers nothing from an empty quote.
+
 ## 0.43.1 — 2026-10-12
 
 THE DECLINE, THE REFUND AND THE MAKER'S RECLAIM EACH CARRY THEIR OWN STATE, AND THE TERMINAL CHECK READS THE

package/README.md

@@ -32,7 +32,7 @@ value that looks like data is more dangerous than a refusal.
 compares the list of what the SDK returns with what is declared in the contract (both ways).
 
 EVERY PUBLISHED SUBPATH CARRIES ITS OWN DECLARATIONS: `.` (`index.d.ts`), `./xmr`, `./order`, `./evm`,
-`./core` and `./recovery` (`src/public/<entry>.d.ts`). Each of them declares exactly the symbols its barrel
+`./core`, `./recovery` and `./provider` (`src/public/<entry>.d.ts`). Each of them declares exactly the symbols its barrel
 re-exports, so a typed consumer sees the same surface the runtime has, and nothing else.
 `tools/check.mjs --only=types` keeps the two sides equal (a subpath without a `types` target, a declarations
 file that does not read as declarations, or a symbol declared on one side only is red), and

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.43.1",
+  "version": "0.43.3",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "packageManager": "pnpm@12.10.1",
+  "packageManager": "pnpm@12.11.2",
   "description": "XMR <-> EVM swap engine: quotes, guards, order steps, recovery (no DOM, no user-facing strings)",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
     "check:surface": "node tools/check.mjs --only=surface",
     "check:mirror": "node tools/check.mjs --only=mirror",
     "check:pack": "node tools/check.mjs --only=pack",
+    "check:pack-teeth": "node tools/check-pack-teeth.mjs",
     "check:secrets": "node tools/check.mjs --only=secrets",
     "check:types": "node tools/check.mjs --only=types",
     "check:types-teeth": "node tools/check-types-teeth.mjs",
@@ -26,7 +27,8 @@
     "check:decline-teeth": "node tools/check-decline-teeth.mjs",
     "check:terminal": "node tools/check.mjs --only=terminal",
     "check:terminal-teeth": "node tools/check-terminal-teeth.mjs",
-    "check:sweep": "node tools/sweep-refusal.test.mjs", "sync:version": "node tools/sync-version.mjs"
+    "check:sweep": "node tools/sweep-refusal.test.mjs",
+    "sync:version": "node tools/sync-version.mjs"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -57,6 +59,10 @@
     "./recovery": {
       "types": "./src/public/recovery.d.ts",
       "default": "./src/public/recovery.mjs"
+    },
+    "./provider": {
+      "types": "./src/public/provider.d.ts",
+      "default": "./src/public/provider.mjs"
     }
   },
   "files": [

package/src/provider/envFile.mjs

@@ -0,0 +1,106 @@
+// THE SERVICE SETTINGS FILE: WHERE IT LIES AND HOW IT IS READ.
+//
+// The module deliberately imports NOTHING from config.mjs: the entry point connects it BEFORE the config loads, so that
+// the values get into the environment in time. config.mjs reads process.env at module load time, and static
+// imports in ESM run before any code of the file - so 'read the file, then import the config' is
+// possible only through a dynamic import and only from a separate module.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// WHERE TO LOOK WHEN THE FLAG IS NOT GIVEN: the current directory (the command is run from the node tree), then rfq/ under it (the layout of the tree this node was cut from)
+// (the same run from the repository root), then .env - that is also a frequent name for a settings file. What was found
+// is printed: a silent read of 'some' file is exactly the case where people later look for why the settings are wrong.
+//
+// ORDER: THE LOCAL FILE OUTRANKS THE PRODUCTION ONE. The local contour puts its settings BESIDE the production ones
+// (rfq.env.local), and while the search went from the plain name to .local, the developer tool picked up the production
+// file: the wallet path /opt/ninsei/..., the production price feed and its age - and refused with 'nothing to price the order with' where
+// the settings were in place (the quote checks fell exactly on this, and `npm run payout` with them).
+// The reverse order can err in one direction only: on the server there is no .local file at all, and the production
+// one remains the only one. An explicit --env= still outranks everything.
+export const ENV_CANDIDATES = ["rfq.env.local", "rfq.env.local", "rfq.env", "rfq.env", ".env.local", ".env"];
+
+export function findEnvFile(cwd, candidates = ENV_CANDIDATES) {
+  for (const rel of candidates) {
+    const full = join(cwd, rel);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+// A PATH OF A FOREIGN MACHINE IN A SETTINGS FILE IS AN ERROR, NOT A SETTING.
+//
+// The trap was found in battle on 25.09.2026. The local files (*.env.local) travelled to the server with the directory upload
+// (the documented rsync commands had no --exclude '*.env.local'), the tool honestly took the local file -
+// it outranks the production one, see below - start directory and the result was:
+//
+//     /opt/ninsei/keys
+//
+// The check is one-sided DELIBERATELY: the reverse case - production paths /opt/... on a developer machine - is legitimate,
+// because the repository holds copies of the production files, and they must be readable. The function is pure: the platform comes
+// as a parameter, so its behaviour is checkable on any machine.
+export function foreignPathProblem(file, values, platform = process.platform) {
+  if (platform === "win32") return null;
+  for (const [key, value] of Object.entries(values || {})) {
+    const v = String(value).trim();
+    if (/^(?:[A-Za-z]:[\\/]|\\\\)/.test(v)) return { file, key, value: v };
+  }
+  return null;
+}
+
+export function foreignPathMessage(p) {
+  return "settings file " + p.file + " sets a Windows path in setting " + p.key + " (" + p.value
+    + "), and the system is not Windows. This is how a local file (*.env.local) copied from a developer "
+    + "machine looks: it must not be on the server, the service reads <service>/<service>.env. Delete the local "
+    + "file and repeat.";
+}
+
+// We read by the systemd rules: comments and broken lines are skipped, export is stripped, quotes are stripped,
+// spaces are trimmed.
+export function readEnvFile(path) {
+  const out = {};
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).replace(/^export\s+/, "").trim();
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) out[key] = value;
+  }
+  // The file is read, but the values may be FROM A FOREIGN MACHINE - then it is a refusal, not a setting.
+  const foreign = foreignPathProblem(path, out);
+  if (foreign) throw new Error(foreignPathMessage(foreign));
+  return out;
+}
+
+// WE APPLY THE FILE TO THE ENVIRONMENT. The file is the SERVICE's configuration, so it outranks what happened to be
+// exported in the shell; explicit command flags are parsed later and outrank both. We return the key names
+// without values: printing setting values into the log is not allowed.
+// VARIABLE SUBSTITUTION LIVES HERE, NOT IN EVERY TOOL. In the local file the settings are written as
+// ${STACK_DATA}/rfq-wallet.json, and they are substituted by the launcher (the stack itself). A tool that does not do this
+// sees literally "${STACK_DATA}" - and the consequences are not only 'wallet not found': by the same literal path it
+// creates an EMPTY quote database and then reports 'the log is empty' on a live contour, that is, the refusal looks like
+// absence of data. Before, the substitution was copied into one tool; a copy is a sign that the place is shared.
+export function substituteEnvVars(value, { dataDir, root }) {
+  return String(value)
+    .replace(/\$\{STACK_DATA\}/g, dataDir)
+    .replace(/\$\{ROOT\}/g, root);
+}
+
+export function applyEnvFile(path, target = process.env) {
+  const values = readEnvFile(path);
+  const dataDir = target.STACK_DATA || join(tmpdir(), "ninsei-stack");
+  const root = target.ROOT || process.cwd();
+  const substituted = {};
+  for (const [k, v] of Object.entries(values)) substituted[k] = substituteEnvVars(v, { dataDir, root });
+  // THE SUBSTITUTION MAY BRING A FOREIGN PATH: ${STACK_DATA} expands to the directory of THE machine where it is run.
+  // We check after the substitution too - that is exactly how the production case with /opt/ninsei/ surfaced.
+  const foreign = foreignPathProblem(path, substituted);
+  if (foreign) throw new Error(foreignPathMessage(foreign));
+  for (const [k, v] of Object.entries(substituted)) target[k] = v;
+  return Object.keys(values);
+}

package/src/provider/identity.mjs

@@ -0,0 +1,43 @@
+// RFQ NODE IDENTITY: the code from the PROVIDER ADDRESS and a human-readable name.
+//
+// THIS IS THE NODE'S RESPONSIBILITY, NOT OUR BACKEND'S. The node derives its code from its address itself, picks the
+// name itself and only sends them in the packet. Our backend accepts and CHECKS the shape, but invents nothing:
+// if we assigned the code or the name, we would be defining the provider's identity instead of him.
+//
+// WHY FROM THE ADDRESS AND NOT FROM THE KEY. A provider's identity is his EVM address: a quote signature is made with an EIP-712
+// wallet key, and the CHAIN checks that the key belongs to the address (maker registry, providerOf). The Ed25519 key
+// stays with the node, but does something else: the Monero halves are derived from it and the market packets are signed with it. The code
+// must follow the one the chain confirms - the address. The former code was computed from the ed25519 key and
+// therefore changed with it, not with the identity (owner's decision: backward compatibility is not needed).
+import { createHash, randomBytes, randomInt } from "node:crypto";
+
+// Code shape. Strict: "lp-" and exactly 8 hex in lower case.
+export const PROVIDER_CODE_RE = /^lp-[0-9a-f]{8}$/;
+
+// A human-readable name shorter than this limit: long names break tables and logs.
+export const DISPLAY_NAME_MAX = 48;
+
+// PROVIDER CODE. Computed from the provider's EVM ADDRESS (lower case, with 0x), not from the ed25519 key.
+//
+// Why deterministic and from one address: the code must be THE SAME everywhere the maker is seen (decision 14),
+// and must not change when the node restarts. The address IS the identity, so the code survives a key change and does not
+// depend on which of the accepted keys signed the quote this time.
+export function providerCode(address) {
+  const a = String(address == null ? "" : address).trim().toLowerCase();
+  if (!/^0x[0-9a-f]{40}$/.test(a)) {
+    throw new Error("provider code is derived from an EVM address, got " + JSON.stringify(String(address).slice(0, 24)));
+  }
+  return "lp-" + createHash("sha256").update(a).digest("hex").slice(0, 8);
+}
+
+// A RANDOM NAME - for the case when no name is set in the config. The node must not stay nameless: in market
+// view a provider has to be called something for a human. The alphabet is Latin simply because this is a generated name;
+// a manually set one may be anything - identity is defined by the code, not by the name.
+const WORDS = ["north", "harbor", "lumen", "cedar", "atlas", "quartz", "verde", "nova", "orbit", "delta"];
+
+export function randomDisplayName() {
+  // randomInt, not a modulo of random bytes: 65536 % 10 leaves six words one draw more likely than the other
+  // four. The difference is invisible in a display name, but a biased draw has no reason to exist at all.
+  const word = WORDS[randomInt(WORDS.length)];
+  return word + "-" + randomBytes(2).toString("hex");
+}

package/src/provider/sign.mjs

@@ -0,0 +1,164 @@
+// Signing the quote packet of the RFQ node. Ed25519, canonical packet.
+//
+// WHY THIS FILE IS COPIED AND NOT TAKEN FROM OUR SIGNER APPLICATION. The node runs AT THE PROVIDER: he has no
+// signer application of ours, and must not. An application that pulls code from a neighbouring directory is not
+// standalone - and the node must start on its own.
+//
+// THE RISK OF THE THREE IMPLEMENTATIONS DIVERGING (the feeder, rfq, the interface backend) IS CLOSED NOT BY COMMON CODE, BUT BY A CHECK.
+// the check on our side signs the same packet with both senders and confirms it with our
+// backend, and also compares the signatures against each other. They cannot diverge unnoticed.
+//
+// Canonical form: all fields except signature, keys sorted, no spaces. The order of serialisation is part of
+// the contract: if it diverges, the signatures stop matching for everyone at once.
+
+import { generateKeyPairSync, sign as nodeSign, verify as nodeVerify, createPrivateKey, createPublicKey } from "node:crypto";
+import { readFileSync, writeFileSync, chmodSync, existsSync, statSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// The canonical form of the packet: the signature is excluded, the keys are sorted, there are no spaces.
+export function canonical(payload) {
+  const { signature, ...rest } = payload || {};
+  const sortKeys = (v) => {
+    if (Array.isArray(v)) return v.map(sortKeys);
+    if (v && typeof v === "object") {
+      return Object.keys(v).sort().reduce((acc, k) => {
+        acc[k] = sortKeys(v[k]);
+        return acc;
+      }, {});
+    }
+    return v;
+  };
+  return JSON.stringify(sortKeys(rest));
+}
+
+export function signPayload(payload, privateKeyPem, keyId) {
+  // IMPORTANT: the FINAL packet is signed, already including keyId. Otherwise the signature is computed over one set of
+  // bytes while the check is over another (the check sees keyId in the packet), and one's own signature does not match.
+  // Verified by a round-trip test: before this fix 'own packet' gave false.
+  const pkg = { ...payload, keyId };
+  const signature = nodeSign(null, Buffer.from(canonical(pkg), "utf8"), createPrivateKey(privateKeyPem)).toString("base64");
+  return { ...pkg, signature };
+}
+
+// The check is needed by the interface backend when it turns signature checking on. It is not called now,
+// but it lies next to the signing: signing and checking must be computed the same way, otherwise they diverge.
+export function verifyPayload(payload, publicKeyPem) {
+  const { signature, ...rest } = payload || {};
+  if (!signature) return false;
+  try {
+    return nodeVerify(null, Buffer.from(canonical(rest), "utf8"), createPublicKey(publicKeyPem), Buffer.from(signature, "base64"));
+  } catch {
+    return false;
+  }
+}
+
+// The public key path: beside the private one, by the same name without ".key" and with ".pub" at the end.
+//   <path>.key -> <path>.pub
+// That way the operator does not look for the file by eye and does not copy the key from the terminal output: both files appear together.
+export function publicKeyPath(keyFile) {
+  return String(keyFile).replace(/\.key$/i, "") + ".pub";
+}
+
+// Key pair generation: the private one goes to a file with permissions 0600, the public one - TO A FILE BESIDE it and to the output
+// (the public one is not a secret, it is handy both to print and to keep as a file; the private one NEVER gets into the log).
+//
+// Overwriting an existing key is possible ONLY explicitly (force). Otherwise - a refusal: to silently wipe someone else's key
+// means breaking the provider, and he learns about it by rejected quotes rather than by a message.
+export function generateKeyFiles({ keyFile, force = false } = {}) {
+  if (!keyFile) throw new Error("key file is not specified");
+  if (existsSync(keyFile) && !force) {
+    const e = new Error("key already exists: " + keyFile + " - it was NOT overwritten");
+    e.code = "KEY_EXISTS";
+    throw e;
+  }
+  // We create the keys directory ourselves: the keys lie apart from the code (keys/), and it may be absent on a fresh install.
+  try { mkdirSync(dirname(keyFile), { recursive: true }); } catch { /* it is already there - not a reason to fall */ }
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const priv = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const pub = publicKey.export({ type: "spki", format: "pem" }).toString();
+  writeFileSync(keyFile, priv, { mode: 0o600 });
+  try { chmodSync(keyFile, 0o600); } catch { /* on some file systems there are no permissions - not a reason to fall */ }
+  const pubFile = publicKeyPath(keyFile);
+  writeFileSync(pubFile, pub, { mode: 0o644 });
+  return { keyFile, pubFile, publicKeyPem: pub };
+}
+
+// Reading a key with a permission check: if the file is available to anyone besides the owner - a refusal, not silent work.
+// THE RAW KEY BYTES - the material for deriving the halves for orders. For an ed25519 key this is exactly
+// 32 bytes of a uniform seed: HMAC and hashing over them give a result indistinguishable from random.
+//
+// AN IMPORTANT CONSEQUENCE ONE MUST KNOW: the derivation requires the RAW key in the process. So a node whose
+// signing key has moved into hardware (HSM, a hardware wallet) will not be able to issue an order quote - and this is
+// an honest limitation, not a breakdown: while the key is there, the node is both identified and serves such quotes.
+export function privateKeySeedBytes(privateKeyPem) {
+  const ko = createPrivateKey(privateKeyPem);
+  const jwk = ko.export({ format: "jwk" });
+  if (!jwk || !jwk.d) throw new Error("could not get raw bytes from the signing key (an ed25519 key is required)");
+  const bytes = Buffer.from(jwk.d, "base64url");
+  if (bytes.length < 16) throw new Error("signing key is shorter than 16 bytes: unusable for half derivation");
+  return new Uint8Array(bytes);
+}
+
+export function loadPrivateKey(keyFile) {
+  const st = statSync(keyFile);
+  // The permission check - only where permissions exist. On Windows there are no POSIX mode bits (the file is always seen
+  // as 666), and access is defined by ACLs, not by these bits: refusing on Windows would mean not letting the
+  // service start locally at all. This is not a weakening - on Linux the check works as it worked.
+  if (process.platform !== "win32" && (st.mode & 0o077) !== 0) {
+    throw new Error("key file is accessible to others: " + keyFile + " (mode 0600 is required)");
+  }
+  return readFileSync(keyFile, "utf8");
+}
+
+// THE NODE'S PUBLIC KEY: THE ONE IT SIGNS WITH, AND NOT THE CONTENT OF THE FILE BESIDE IT (partner request to the node).
+//
+// WHY FROM THE LOADED KEY AND NOT FROM THE .pub FILE. The signature is made by the key the node read at start
+// (loadPrivateKey), so ITS public key must go out: the file beside it could be left from a former
+// key, come from a backup or be substituted. A reader who took the key from the file would check the signature
+// with the wrong key and would take a live node for a foreign one.
+//
+// WHY THE FILE IS STILL READ. A divergence of the file and the working key is a STATE, and it is NAMED
+// (nodePublicKeyFileMatches: false), not hidden: other tools and a human read the file, and by it they
+// judge the node. The file is re-read on EVERY read, not remembered at start: a file substituted beside the
+// key must be visible at once, not at the next node start.
+export function publicKeyBase64From(publicKeyPem) {
+  return createPublicKey(publicKeyPem).export({ type: "spki", format: "der" }).toString("base64");
+}
+
+// The SIGNING public key from a private PEM - with the same SPKI DER export as in the .pub file.
+// createPublicKey accepts the PRIVATE PEM itself and derives the public key from it; a repeated call on a KeyObject
+// (createPublicKey(createPublicKey(pem))) refuses - "expected private", so there is NO nesting here.
+export function signingPublicKeyBase64(privateKeyPem) {
+  return publicKeyBase64From(privateKeyPem);
+}
+
+// The content of the .pub file in the same form (base64 of SPKI DER), or the reason why it is absent.
+export function publicKeyFileBase64(pubFile) {
+  if (!pubFile) return { key: null, why: "the path of the public key file is not known" };
+  if (!existsSync(pubFile)) return { key: null, why: "the public key file is missing: " + pubFile };
+  try { return { key: publicKeyBase64From(readFileSync(pubFile, "utf8")), why: null }; }
+  catch (e) { return { key: null, why: "the public key file could not be read: " + String((e && e.message) || e).slice(0, 140) }; }
+}
+
+// THE REPORT FOR THE nodePublicKey FIELD IN GET /v1/info. The shape is assembled by ONE place - here; the listener only
+// returns it (makerApi.mjs), and the node passes its key (index.mjs), so the rule does not multiply.
+// key - the public key the node SIGNS with; file - what lies in the file beside it; matches - whether they
+// match (true/false, and null means 'nothing to compare with'); why - the reasons of the fields left null.
+export function nodePublicKeyReport({ privateKeyPem = null, keyFile = null, pubFile = null } = {}) {
+  const pubPath = pubFile || (keyFile ? publicKeyPath(keyFile) : null);
+  const file = publicKeyFileBase64(pubPath);
+  const why = {};
+  if (file.why) why.nodePublicKeyFile = file.why;
+  if (!privateKeyPem) {
+    why.nodePublicKey = "the node has no signing key it could read" + (keyFile ? " (" + keyFile + ")" : "") + ", so the key it signs with is unknown";
+    return { key: null, file: file.key, matches: null, why };
+  }
+  let key = null;
+  try { key = signingPublicKeyBase64(privateKeyPem); }
+  catch (e) { why.nodePublicKey = "the signing key could not be read: " + String((e && e.message) || e).slice(0, 140); }
+  // A DIVERGENCE IS A NAMED STATE, NOT SILENCE: false is the name of the state, and both keys stand side by side,
+  // so that one can sort it out without third-party tools. The node works with ITS OWN key meanwhile - it is loaded and
+  // the packets are signed with it; the file does not replace the signature.
+  const matches = key === null || file.key === null ? null : key === file.key;
+  return { key, file: file.key, matches, why };
+}

package/src/public/order.d.ts

@@ -159,3 +159,15 @@ export declare function signQuoteDigest(request: {
  * verified at all. Null is a refusal for the caller to name, never consent.
  */
 export declare function recoverQuoteKey(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): string | null;
+
+/**
+ * Names of the signed-set fields the quote does not carry, bound to the SDK's own primitives: the same answer as
+ * `quoteMissingFields`, offered so a verifier does not have to pass crypto it already trusts twice.
+ */
+export declare function orderQuoteMissingFields(quote: Partial<OrderQuote> | null | undefined): string[];
+
+/**
+ * The address that signed the quote, recovered with the SDK's own primitives, or null when the quote cannot be
+ * verified at all. Null is a refusal for the caller to name, never consent.
+ */
+export declare function recoverOrderQuoteKey(quote: OrderQuote): string | null;

package/src/public/order.mjs

@@ -20,3 +20,8 @@ export {
   recoverQuoteKey,
   signQuoteDigest,
 } from "../quoteEip712Spec.mjs";
+
+// THE BOUND VERIFICATION HELPERS. The spec above is handed crypto by the caller; these two bind it to the SDK's
+// own primitives, so a consumer verifies a maker's quote without assembling the binding itself. Verification
+// only: the provider's signing key never enters this package.
+export { orderQuoteMissingFields, recoverOrderQuoteKey } from "../quoteEip712.mjs";

package/src/public/provider.d.ts

@@ -0,0 +1,93 @@
+// DECLARATIONS FOR THE `./provider` ENTRY: the node-side helpers, Node only.
+//
+// These declarations name what `src/public/provider.mjs` re-exports: identity, signing and env files. Every
+// signature is copied from the modules the barrel re-exports (`src/provider/identity.mjs`, `sign.mjs`,
+// `envFile.mjs`), and a symbol the barrel does not re-export is not declared here.
+//
+// NOT FOR A BROWSER. These functions use `node:crypto`, `node:fs` and `node:path`; a page must import from the
+// browser entries instead.
+
+/** The shape of a provider code: `lp-` and eight lowercase hex digits, derived from the provider's address. */
+export declare const PROVIDER_CODE_RE: RegExp;
+
+/** The longest display name a provider may set. */
+export declare const DISPLAY_NAME_MAX: number;
+
+/** The provider code of an address: stable for the address, independent of any key. Throws on a malformed address. */
+export declare function providerCode(address: string): string;
+
+/** A display name the operator may keep or replace: a word and four hex digits. */
+export declare function randomDisplayName(): string;
+
+/** The canonical JSON a signature covers: keys sorted at every level, so two writers agree on the bytes. */
+export declare function canonical(payload: unknown): string;
+
+/** A signed package: the payload's fields plus the detached signature and the key identity that made it. */
+export interface SignedPayload {
+  readonly [field: string]: unknown;
+  readonly signature: string;
+  readonly keyId?: string;
+}
+
+/** Signs the canonical form of the payload with a PEM private key. */
+export declare function signPayload(payload: Record<string, unknown>, privateKeyPem: string, keyId?: string): SignedPayload;
+
+/** Verifies a signed package against a PEM public key. False means refused, never "probably fine". */
+export declare function verifyPayload(pkg: SignedPayload, publicKeyPem: string): boolean;
+
+/** The public key file that belongs to a private key file: `x.key` becomes `x.pub`. */
+export declare function publicKeyPath(keyFile: string): string;
+
+/** Creates a key pair on disk and writes the public half beside it. Refuses to overwrite unless `force`. */
+export declare function generateKeyFiles(options?: { readonly keyFile?: string; readonly force?: boolean }): {
+  readonly key?: string;
+  readonly file?: string;
+  readonly why?: string;
+};
+
+/** The raw seed bytes of a PEM private key, for consumers that must not keep the PEM. */
+export declare function privateKeySeedBytes(privateKeyPem: string): Uint8Array;
+
+/** Reads a PEM private key from a file. */
+export declare function loadPrivateKey(keyFile: string): string;
+
+/** The base64 SPKI form of a public key, from either a public or a private PEM. */
+export declare function publicKeyBase64From(publicKeyPem: string): string;
+
+/** The base64 public key that belongs to a private key. */
+export declare function signingPublicKeyBase64(privateKeyPem: string): string;
+
+/** The base64 public key held in a public key file, or a named reason when it is missing. */
+export declare function publicKeyFileBase64(pubFile: string): { readonly key: string | null; readonly why?: string };
+
+/** What the node reports about its own key: the key, its file, and whether the two halves agree. */
+export declare function nodePublicKeyReport(options?: {
+  readonly privateKeyPem?: string | null;
+  readonly keyFile?: string | null;
+  readonly pubFile?: string | null;
+}): { readonly key: string | null; readonly file?: string | null; readonly matches?: boolean | null; readonly why?: string };
+
+/** The settings files looked up, in order, when none is named. */
+export declare const ENV_CANDIDATES: readonly string[];
+
+/** The first settings file that exists under `cwd`, or null. */
+export declare function findEnvFile(cwd: string, candidates?: readonly string[]): string | null;
+
+/** A Windows path found in a settings file on a non-Windows system, or null when the file is usable. */
+export declare function foreignPathProblem(
+  file: string,
+  values: Record<string, string>,
+  platform?: string,
+): { readonly file: string; readonly key: string; readonly value: string } | null;
+
+/** The sentence that explains a foreign path to an operator. */
+export declare function foreignPathMessage(problem: { readonly file: string; readonly key: string; readonly value: string }): string;
+
+/** Reads a settings file into a plain object of its values. */
+export declare function readEnvFile(path: string): Record<string, string>;
+
+/** Substitutes `${STACK_DATA}` and `${ROOT}` in a setting value. */
+export declare function substituteEnvVars(value: unknown, paths: { readonly dataDir: string; readonly root: string }): string;
+
+/** Applies a settings file to a target object (the process environment by default) and returns the names set. */
+export declare function applyEnvFile(path: string, target?: Record<string, string | undefined>): string[];

package/src/public/provider.mjs

@@ -0,0 +1,39 @@
+// THE PROVIDER SIDE, NODE ONLY: identity, signing and env files for the machine that runs the node.
+//
+// Separate entry, like ./adapters, because these helpers reach the filesystem and node:crypto. A browser
+// consumer must never pull them in, and a Node consumer gets them with one import.
+//
+// WHY THEY LIVE HERE. The demo's backend verifies a maker's quote and builds an allow list from the provider's
+// key; the node signs tickets with the same key. One implementation in the package means the identity rule and
+// the key-path rule are not re-derived per consumer.
+
+export {
+  PROVIDER_CODE_RE,
+  DISPLAY_NAME_MAX,
+  providerCode,
+  randomDisplayName,
+} from "../provider/identity.mjs";
+
+export {
+  canonical,
+  signPayload,
+  verifyPayload,
+  publicKeyPath,
+  generateKeyFiles,
+  privateKeySeedBytes,
+  loadPrivateKey,
+  publicKeyBase64From,
+  signingPublicKeyBase64,
+  publicKeyFileBase64,
+  nodePublicKeyReport,
+} from "../provider/sign.mjs";
+
+export {
+  ENV_CANDIDATES,
+  findEnvFile,
+  foreignPathProblem,
+  foreignPathMessage,
+  readEnvFile,
+  substituteEnvVars,
+  applyEnvFile,
+} from "../provider/envFile.mjs";

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.43.1";
+export const SDK_VERSION = "0.43.3";