@ninsei-labs/sdk 0.53.0 → 0.54.0

package/src/relayRequest.mjs

@@ -0,0 +1,188 @@
+// ONE FIRM REQUEST: THE TERMS, THE CLIENT HALF AND THE ENCRYPTED VIEW MATERIAL.
+//
+// The relay signs the payload as the exact UTF-8 string it forwards, so this module serialises it once. Every
+// field that the node or the relay checks is taken from the caller's terms or from the signed features; nothing
+// is filled in from a second source.
+//
+// The builder does not create the client half: the caller has already built one order side and proved it in
+// this context. It normalises the proof's spellings and refuses a half whose point is not the one in its proof.
+import { SdkError } from "./errors.mjs";
+import { ed25519, keccak256 } from "./primitives.mjs";
+import { verifyNodeFeatures } from "./relayFeatures.mjs";
+import { relayViewInfo, sealViewEnvelope } from "./relayView.mjs";
+import { firmTermsDigest, firmTermsMissingFields } from "./relayTerms.mjs";
+
+const hexToBytes = (value, field, width) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!new RegExp("^[0-9a-fA-F]{" + width * 2 + "}$").test(text)) {
+    throw new SdkError("bad-input", { field });
+  }
+  const out = new Uint8Array(width);
+  for (let i = 0; i < width; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+const hex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+const normHex = (value, width, field) => hex(hexToBytes(value, field, width));
+const scalar = (value, field) => {
+  let n = null;
+  try { n = BigInt(value); } catch { n = null; }
+  if (n === null || n <= 0n || n >= ed25519.Point.Fn.ORDER) throw new SdkError("bad-input", { field });
+  return n;
+};
+const scalarBytes = (value, field) => {
+  let n = scalar(value, field);
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0 && n > 0n; i -= 1) { out[i] = Number(n & 0xffn); n >>= 8n; }
+  return out;
+};
+const pointOf = (value, field) => hex(ed25519.Point.BASE.multiply(scalar(value, field)).toBytes());
+const assertPoint = (value, field) => {
+  const bytes = hexToBytes(value, field, 32);
+  try { ed25519.Point.fromHex(hex(bytes).slice(2)); } catch { throw new SdkError("bad-input", { field }); }
+  return hex(bytes);
+};
+
+const PROOF_FIELDS = ["XA", "XB", "proofs"];
+function normaliseProof(proof) {
+  if (!proof || typeof proof !== "object") throw new SdkError("bad-input", { field: "clientHalf.proof" });
+  for (const field of PROOF_FIELDS) {
+    if (proof[field] === undefined || proof[field] === null || proof[field] === "") {
+      throw new SdkError("bad-input", { field: "clientHalf.proof." + field });
+    }
+  }
+  if (!Array.isArray(proof.proofs) || proof.proofs.length !== 253) {
+    throw new SdkError("bad-input", { field: "clientHalf.proof.proofs" });
+  }
+  const xa = normHex(proof.XA, 33, "clientHalf.proof.XA");
+  const xb = normHex(proof.XB, 32, "clientHalf.proof.XB");
+  const proofs = proof.proofs.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || !entry.sig) {
+      throw new SdkError("bad-input", { field: "clientHalf.proof.proofs." + index });
+    }
+    const sig = {};
+    for (const field of ["eA", "eB", "a0", "a1", "b0", "b1"]) {
+      sig[field] = normHex(entry.sig[field], 32, "clientHalf.proof.proofs." + index + ".sig." + field);
+    }
+    return {
+      cA: normHex(entry.cA, 33, "clientHalf.proof.proofs." + index + ".cA"),
+      cB: normHex(entry.cB, 32, "clientHalf.proof.proofs." + index + ".cB"),
+      sig,
+    };
+  });
+  return { XA: xa, XB: xb, proofs };
+}
+
+/**
+ * Build the exact request payload.
+ *
+ * `features` is the signed public object the relay forwarded; `terms` is the client's request terms (its
+ * `featuresHash` may be omitted and is filled from the verified features). `clientHalf` is
+ * `{commitHalf, edPoint, proof}`; `nodeViewScalar` and `clientViewScalar` are the two view halves the client
+ * chose. On ask only the node scalar is sent; on bid both.
+ */
+export async function buildFirmRequest({
+  features, terms, clientHalf, edViewPointClient, edViewPointNode,
+  nodeViewScalar, clientViewScalar = null, side = null,
+} = {}) {
+  const verdict = verifyNodeFeatures({ features, terms });
+  const requestSide = String(side || terms?.side || "");
+  if (requestSide !== "ask" && requestSide !== "bid") throw new SdkError("bad-input", { field: "side" });
+  if (terms?.side !== undefined && terms.side !== requestSide) throw new SdkError("bad-input", { field: "terms.side" });
+  if (!terms || typeof terms !== "object" || !terms.order || typeof terms.order !== "object") {
+    throw new SdkError("bad-input", { field: "terms" });
+  }
+  if (terms.featuresHash !== undefined && terms.featuresHash !== null && terms.featuresHash !== ""
+    && String(terms.featuresHash).toLowerCase() !== verdict.featuresHash) {
+    throw new SdkError("quote-refused", { step: "features", why: "hash" });
+  }
+  const order = terms.order;
+  const orderFields = ["chainId", "factory", "locker", "claimer", "amount", "readyBy", "t1", "salt"];
+  for (const field of orderFields) {
+    if (order[field] === undefined || order[field] === null || order[field] === "") {
+      throw new SdkError("bad-input", { field: "terms.order." + field });
+    }
+  }
+  if (String(order.chainId) !== String(terms.market || "").split(":")[0]) {
+    throw new SdkError("bad-input", { field: "terms.market" });
+  }
+  const half = clientHalf || {};
+  const commitHalf = normHex(half.commitHalf, 32, "clientHalf.commitHalf");
+  const point = normHex(half.edPoint, 32, "clientHalf.edPoint");
+  const proof = normaliseProof(half.proof);
+  if (proof.XB !== point) throw new SdkError("bad-input", { field: "clientHalf.edPoint" });
+  const maker = normHex(terms.maker, 20, "terms.maker");
+  const locker = normHex(order.locker, 20, "terms.order.locker");
+  const claimer = normHex(order.claimer, 20, "terms.order.claimer");
+  if (locker === claimer) throw new SdkError("bad-input", { field: "terms.order.roles" });
+  if (requestSide === "ask") {
+    if (claimer !== maker) throw new SdkError("bad-input", { field: "terms.order.claimer" });
+    if (String(terms.claimTip) !== "0") throw new SdkError("bad-input", { field: "terms.claimTip" });
+  } else if (locker !== maker) {
+    throw new SdkError("bad-input", { field: "terms.order.locker" });
+  }
+  const clientViewPoint = assertPoint(edViewPointClient, "edViewPointClient");
+  const nodeViewPoint = assertPoint(edViewPointNode, "edViewPointNode");
+  const nodeScalar = scalarBytes(nodeViewScalar, "nodeViewScalar");
+  if (pointOf(nodeViewScalar, "nodeViewScalar").toLowerCase() !== nodeViewPoint.toLowerCase()) {
+    throw new SdkError("bad-input", { field: "edViewPointNode" });
+  }
+  let clientScalar = null;
+  if (requestSide === "bid") {
+    clientScalar = scalarBytes(clientViewScalar, "clientViewScalar");
+    if (pointOf(clientViewScalar, "clientViewScalar").toLowerCase() !== clientViewPoint.toLowerCase()) {
+      throw new SdkError("bad-input", { field: "edViewPointClient" });
+    }
+  }
+  const requestTerms = {
+    market: String(terms.market),
+    side: requestSide,
+    maker: normHex(terms.maker, 20, "terms.maker"),
+    registry: normHex(terms.registry, 20, "terms.registry"),
+    featuresHash: verdict.featuresHash,
+    xmrNetwork: String(terms.xmrNetwork),
+    order: {
+      chainId: String(order.chainId),
+      factory: normHex(order.factory, 20, "terms.order.factory"),
+      locker: normHex(order.locker, 20, "terms.order.locker"),
+      claimer: normHex(order.claimer, 20, "terms.order.claimer"),
+      amount: String(order.amount),
+      readyBy: Number(order.readyBy),
+      t1: Number(order.t1),
+      salt: normHex(order.salt, 32, "terms.order.salt"),
+    },
+    xmrAmount: String(terms.xmrAmount),
+    claimTip: String(terms.claimTip),
+  };
+  const missing = firmTermsMissingFields(requestTerms);
+  if (missing.length) throw new SdkError("bad-input", { field: "terms", missing });
+  const termsDigest = hex(firmTermsDigest({ crypto: { keccak256 }, terms: requestTerms }));
+  const info = relayViewInfo({
+    termsDigest,
+    commitHalf,
+    edPoint: point,
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+  });
+  const plaintext = new Uint8Array(requestSide === "ask" ? 32 : 64);
+  plaintext.set(nodeScalar, 0);
+  if (requestSide === "bid") plaintext.set(clientScalar, 32);
+  const viewEnvelope = await sealViewEnvelope({ hpkeKey: verdict.hpkeKey, info, plaintext });
+  const payload = JSON.stringify({
+    terms: requestTerms,
+    clientHalf: { commitHalf, edPoint: point, proof },
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+    viewEnvelope,
+  });
+  return {
+    payload,
+    terms: requestTerms,
+    viewEnvelope,
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+  };
+}

package/src/relayTerms.mjs

@@ -0,0 +1,145 @@
+// THE EIP-712 TERMS A RELAY FIRM REQUEST SIGNS.
+//
+// The relay forwards the client's exact payload as a string and signs its UTF-8 bytes. The same terms are
+// also the HPKE context: `relayViewInfo` takes this digest, so a ciphertext is bound to the amounts, roles,
+// deadlines and salt in the request rather than to a separately supplied label.
+//
+// The domain is the relay domain, not the factory domain: `{name: "Ninsei Relay", version: "1"}` has no
+// chainId and no verifyingContract. The inner `OrderQuote` keeps its own factory domain; the two signatures
+// are deliberately separate.
+//
+// The type strings and field order are wire format. A rearrangement produces another digest, and the node
+// refuses the request before it decrypts anything.
+import { SdkError } from "./errors.mjs";
+
+export const FIRM_DOMAIN_NAME = "Ninsei Relay";
+export const FIRM_DOMAIN_VERSION = "1";
+const DOMAIN_TYPE_PARTS = ["EIP712Domain(", "string name,", "string version)"];
+export const FIRM_DOMAIN_TYPE = DOMAIN_TYPE_PARTS.join("");
+
+export const FIRM_ORDER_FIELDS = [
+  ["chainId", "uint256"],
+  ["factory", "address"],
+  ["locker", "address"],
+  ["claimer", "address"],
+  ["amount", "uint256"],
+  ["readyBy", "uint64"],
+  ["t1", "uint64"],
+  ["salt", "bytes32"],
+];
+export const FIRM_ORDER_TYPE = "FirmOrder(" + FIRM_ORDER_FIELDS.map(([name, type]) => type + " " + name).join(",") + ")";
+
+export const FIRM_TERMS_FIELDS = [
+  ["market", "string"],
+  ["side", "string"],
+  ["maker", "address"],
+  ["registry", "address"],
+  ["featuresHash", "bytes32"],
+  ["xmrNetwork", "string"],
+  ["order", "FirmOrder"],
+  ["xmrAmount", "uint256"],
+  ["claimTip", "uint256"],
+];
+// EIP-712 appends every referenced struct type to the primary type, sorted by name. `FirmOrder` is the only
+// one, so the type hash covers both strings.
+export const FIRM_TERMS_TYPE = "FirmTerms(" + FIRM_TERMS_FIELDS.map(([name, type]) => type + " " + name).join(",") + ")" + FIRM_ORDER_TYPE;
+
+const utf8 = (value) => new TextEncoder().encode(String(value));
+const concat = (...arrays) => {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const array of arrays) { out.set(array, at); at += array.length; }
+  return out;
+};
+const hexToBytes = (value, field) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]*$/.test(text) || text.length % 2) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(text.length / 2);
+  for (let i = 0; i < out.length; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+const number = (value, field, bits) => {
+  let n = null;
+  try { n = BigInt(String(value === undefined || value === null ? "" : value).trim()); } catch { n = null; }
+  if (n === null || n < 0n || n >= (1n << BigInt(bits))) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0 && n > 0n; i -= 1) { out[i] = Number(n & 0xffn); n >>= 8n; }
+  return out;
+};
+const address = (value, field) => {
+  const text = String(value === undefined || value === null ? "" : value).trim();
+  if (!/^(0x)?[0-9a-fA-F]{40}$/.test(text)) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(32);
+  out.set(hexToBytes(text.replace(/^0x/, ""), field), 12);
+  return out;
+};
+const bytes32 = (value, field) => {
+  const bytes = hexToBytes(value, field);
+  if (bytes.length !== 32) throw new SdkError("bad-input", { field });
+  return bytes;
+};
+
+const encodeField = (crypto, type, value, field) => {
+  if (type === "string") return crypto.keccak256(utf8(value === undefined || value === null ? "" : value));
+  if (type === "address") return address(value, field);
+  if (type === "bytes32") return bytes32(value, field);
+  if (type === "uint64") return number(value, field, 64);
+  if (type === "uint256") return number(value, field, 256);
+  throw new SdkError("bad-input", { field });
+};
+
+const structHash = (crypto, typeString, fields, value, prefix) => {
+  const parts = [crypto.keccak256(utf8(typeString))];
+  for (const [field, type] of fields) {
+    if (type === "FirmOrder") {
+      const order = value && value.order;
+      if (!order || typeof order !== "object") throw new SdkError("bad-input", { field: prefix + ".order" });
+      parts.push(firmOrderHash(crypto, order));
+    } else {
+      parts.push(encodeField(crypto, type, value ? value[field] : undefined, prefix + "." + field));
+    }
+  }
+  return crypto.keccak256(concat(...parts));
+};
+
+export function firmOrderHash(crypto, order) {
+  return structHash(crypto, FIRM_ORDER_TYPE, FIRM_ORDER_FIELDS, order, "terms.order");
+}
+
+export function firmTermsDomainSeparator(crypto) {
+  return crypto.keccak256(concat(
+    crypto.keccak256(utf8(FIRM_DOMAIN_TYPE)),
+    crypto.keccak256(utf8(FIRM_DOMAIN_NAME)),
+    crypto.keccak256(utf8(FIRM_DOMAIN_VERSION)),
+  ));
+}
+
+export function firmTermsStructHash({ crypto, terms } = {}) {
+  if (!crypto || typeof crypto.keccak256 !== "function") throw new SdkError("bad-input", { field: "crypto" });
+  return structHash(crypto, FIRM_TERMS_TYPE, FIRM_TERMS_FIELDS, terms, "terms");
+}
+
+export function firmTermsDigest({ crypto, terms } = {}) {
+  if (!crypto || typeof crypto.keccak256 !== "function") throw new SdkError("bad-input", { field: "crypto" });
+  return crypto.keccak256(concat(Uint8Array.from([0x19, 0x01]), firmTermsDomainSeparator(crypto), firmTermsStructHash({ crypto, terms })));
+}
+
+// Absent fields are named, not treated as zero. The relay client builds a request only from a complete set.
+export function firmTermsMissingFields(terms) {
+  const missing = [];
+  if (!terms || typeof terms !== "object") return ["terms"];
+  for (const [name] of FIRM_TERMS_FIELDS) {
+    if (name === "order") {
+      if (!terms.order || typeof terms.order !== "object") missing.push("order");
+      else for (const [field] of FIRM_ORDER_FIELDS) {
+        const value = terms.order[field];
+        if (value === undefined || value === null || value === "") missing.push("order." + field);
+      }
+    } else {
+      const value = terms[name];
+      if (value === undefined || value === null || value === "") missing.push(name);
+    }
+  }
+  return missing;
+}

package/src/relayView.mjs

@@ -0,0 +1,110 @@
+// THE VIEW MATERIAL A RELAY REQUEST CARRIES.
+//
+// The relay `firm/1` exchange does not send a Monero view scalar in clear text. The client chooses the view
+// halves, keeps them in its recovery material, and encrypts only the node's share to the X25519 key in the
+// signed public features. The profile is fixed by the relay wire spec: HPKE RFC 9180 base mode, DHKEM(X25519,
+// HKDF-SHA256), HKDF-SHA256 and ChaCha20-Poly1305.
+//
+// This module owns the profile, not the request shape. It names one encryption and one decryption, both taking
+// the application `info` as bytes, so the caller cannot accidentally use a different suite or a different
+// interpretation of the context. The relay client builds `info` with `relayViewInfo`.
+import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256 } from "@hpke/core";
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { SdkError } from "./errors.mjs";
+
+const utf8 = (value) => new TextEncoder().encode(String(value));
+
+const bytesOf = (value) => {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new SdkError("bad-input", { field: "viewEnvelope" });
+};
+
+const bytesToHex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytesOf(bytes)) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+
+const hexToBytes = (value, width, field) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!new RegExp("^[0-9a-fA-F]{" + (width * 2) + "}$").test(text)) {
+    throw new SdkError("bad-input", { field });
+  }
+  const out = new Uint8Array(width);
+  for (let i = 0; i < width; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+
+const suite = () => new CipherSuite({
+  kem: new DhkemX25519HkdfSha256(),
+  kdf: new HkdfSha256(),
+  aead: new Chacha20Poly1305(),
+});
+
+// The relay binds encryption to the exact terms, the client half and both view points. The prefix and the
+// order of the five words are part of the wire format; a different order still decrypts, which is why it is
+// built here once instead of at each call site.
+export const RELAY_VIEW_INFO_PREFIX = "ninsei-relay-view-v1";
+
+export function relayViewInfo({ termsDigest, commitHalf, edPoint, edViewPointClient, edViewPointNode } = {}) {
+  const words = [
+    ["termsDigest", termsDigest],
+    ["commitHalf", commitHalf],
+    ["edPoint", edPoint],
+    ["edViewPointClient", edViewPointClient],
+    ["edViewPointNode", edViewPointNode],
+  ].map(([field, value]) => hexToBytes(value, 32, field));
+  const prefix = utf8(RELAY_VIEW_INFO_PREFIX);
+  const out = new Uint8Array(prefix.length + words.reduce((n, word) => n + word.length, 0));
+  out.set(prefix, 0);
+  let at = prefix.length;
+  for (const word of words) { out.set(word, at); at += word.length; }
+  return out;
+}
+
+// One sender context, one Seal. The relay spec forbids reusing an ephemeral key for another encryption, so
+// the context is created here and never exposed.
+export async function sealViewEnvelope({ hpkeKey, info, plaintext } = {}) {
+  // The two plaintext lengths are part of the wire contract: ask carries the node's view scalar, bid carries
+  // the node's scalar followed by the client's. A caller that passes another length is refused before any
+  // network or cryptographic work.
+  const publicKey = hexToBytes(hpkeKey, 32, "hpkeKey");
+  const body = bytesOf(plaintext);
+  if (body.length !== 32 && body.length !== 64) {
+    throw new SdkError("bad-input", { field: "plaintext" });
+  }
+  if (!(info instanceof Uint8Array)) throw new SdkError("bad-input", { field: "info" });
+  const ctx = suite();
+  let key = null;
+  try {
+    key = await ctx.kem.deserializePublicKey(publicKey);
+    const sender = await ctx.createSenderContext({ recipientPublicKey: key, info });
+    const ciphertext = bytesOf(await sender.seal(body));
+    return { enc: bytesToHex(sender.enc), ciphertext: bytesToHex(ciphertext) };
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("bad-input", { field: "hpkeKey" });
+  }
+}
+
+// The recipient side exists for checks and for a node that embeds this package. It is not needed by a client
+// that only asks for a quote, but keeping both halves in one module makes a symmetric test possible.
+export async function openViewEnvelope({ privateKey, enc, ciphertext, info } = {}) {
+  const secret = hexToBytes(privateKey, 32, "privateKey");
+  const encapsulated = hexToBytes(enc, 32, "enc");
+  const text = String(ciphertext === undefined || ciphertext === null ? "" : ciphertext).replace(/^0x/, "");
+  const width = text.length / 2;
+  if (width !== 48 && width !== 80) throw new SdkError("bad-input", { field: "ciphertext" });
+  const body = hexToBytes(ciphertext, width, "ciphertext");
+  if (!(info instanceof Uint8Array)) throw new SdkError("bad-input", { field: "info" });
+  const ctx = suite();
+  try {
+    const key = await ctx.kem.deserializePrivateKey(secret, true);
+    const recipient = await ctx.createRecipientContext({ recipientKey: key, enc: encapsulated, info });
+    return bytesOf(await recipient.open(body));
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("bad-input", { field: "ciphertext" });
+  }
+}