@ninsei-labs/sdk 0.40.0 → 0.42.0

package/src/public/order.d.ts

@@ -0,0 +1,161 @@
+// DECLARATIONS FOR THE `./order` ENTRY: what a signature commits to, and the quote types it commits under.
+//
+// src/public/order.mjs only NAMES what the engine already offers; these declarations NAME the same thing for a
+// TypeScript consumer. Every signature is copied from the modules the barrel re-exports
+// (`../../engine/atomic/orderContext.js`, `../../engine/atomic/orderHalfCommit.js`,
+// `../quoteEip712Spec.mjs`), and a symbol the barrel does not re-export is not declared here.
+
+/** The order conditions a context is built from. Numbers may be decimal text, hex text or a bigint: one order. */
+export interface OrderContextFields {
+  /** The network: the same order on another network is another order. */
+  readonly chainId: string | number | bigint;
+  /** The factory that creates the escrow. */
+  readonly factory: string;
+  /** The address that deposits the settlement coin. */
+  readonly locker: string;
+  /** The address the contract pays. */
+  readonly claimer: string;
+  /** The amount in wei. */
+  readonly amount: string | number | bigint;
+  /** The readiness deadline. */
+  readonly readyBy: string | number | bigint;
+  /** The settlement deadline. */
+  readonly t1: string | number | bigint;
+  /** The order salt. */
+  readonly salt: string | number | bigint;
+}
+
+/**
+ * The prefix that separates the order context from any other signature or proof, and the version of its field
+ * set. It moves only together with that set, so a proof made under an older prefix never verifies under this one.
+ */
+export declare const ORDER_CONTEXT_VERSION: string;
+
+/**
+ * The canonical context string the DLEQ proof binds to, built from the order fields alone and identically in
+ * every implementation, so the proof can be checked from the on-chain order.
+ *
+ * Refuses (throws) an object without the fields: a partial set is not a context.
+ */
+export declare function orderContextString(order: OrderContextFields): string;
+
+/** The secp256k1 members the half commitment calls: the base point and its uncompressed encoding. */
+export interface Secp256k1BasePoint {
+  readonly multiply: (scalar: bigint) => { readonly toBytes: (isCompressed: boolean) => Uint8Array };
+}
+
+/** The secp256k1 primitive, as the engine and the SDK's own `primitives` module hand it in. */
+export interface Secp256k1Primitive {
+  readonly Point: { readonly BASE: Secp256k1BasePoint };
+}
+
+/** keccak256 over bytes - the same function Solidity's `keccak256` computes. */
+export type Keccak256 = (bytes: Uint8Array) => Uint8Array;
+
+/**
+ * The commitment to a half: `keccak256(x || y)` of the secp256k1 point `half*G`, taken UNCOMPRESSED (64 bytes,
+ * big-byte-first, like Ethereum key coordinates). The chain compares the presented half against the POINT behind
+ * this hash, not against a hash of the number, so this formula must match everywhere it is computed.
+ */
+export declare function halfCommitmentHex(
+  half: bigint | string | number,
+  secp256k1: Secp256k1Primitive,
+  keccak256: Keccak256,
+): string;
+
+/**
+ * The crypto the quote spec is bound to. The spec signs nothing itself: it is handed keccak256 and secp256k1 -
+ * the same two the SDK's `primitives` module exports.
+ */
+export interface QuoteCrypto {
+  readonly keccak256: (bytes: Uint8Array) => Uint8Array;
+  readonly secp256k1: {
+    /** A signature over the digest, `format: "recovered"`, as 65 bytes [recovery, r, s]. */
+    readonly sign: (
+      message: Uint8Array,
+      privateKey: Uint8Array,
+      options?: { readonly format?: string; readonly prehash?: boolean },
+    ) => Uint8Array;
+    readonly Signature: {
+      readonly fromBytes: (bytes: Uint8Array) => {
+        readonly addRecoveryBit: (bit: number) => {
+          readonly recoverPublicKey: (message: Uint8Array) => { readonly toBytes: (isCompressed: boolean) => Uint8Array };
+        };
+      };
+    };
+  };
+}
+
+/**
+ * A signed quote: the fields the provider's signature covers, the factory the EIP-712 domain names, and the
+ * signature itself. Field names and values are the protocol's; a missing field is refused, never read as zero.
+ */
+export interface OrderQuote {
+  readonly provider: string;
+  readonly quoteKey: string;
+  readonly registry: string;
+  readonly cashier: string;
+  readonly locker: string;
+  readonly claimer: string;
+  readonly amount: string | number | bigint;
+  readonly readyBy: string | number | bigint;
+  readonly t1: string | number | bigint;
+  readonly salt: string;
+  readonly commitHalfClaimer: string;
+  readonly edPointClaimer: string;
+  readonly chainId: string | number | bigint;
+  readonly feeBps: string | number | bigint;
+  readonly fee: string | number | bigint;
+  readonly feeRecipient: string;
+  readonly validUntil: string | number | bigint;
+  readonly nonce: string | number | bigint;
+  readonly xmrAmount: string | number | bigint;
+  /** The escrow factory the domain names as `verifyingContract`. */
+  readonly factory: string;
+  /** r || s || v over the digest, 65 bytes, with or without the `0x` prefix; v is normalised to 27/28. */
+  readonly signature: string;
+}
+
+/** The EIP-712 domain type string, assembled from its parts. */
+export declare const EIP712_DOMAIN_TYPE: string;
+
+/** The domain name and its version string: the domain's identity, not the message shape. */
+export declare const ORDER_QUOTE_DOMAIN_NAME: string;
+export declare const ORDER_QUOTE_DOMAIN_VERSION: string;
+
+/** The request-shape generation label. It moves WITH the signed field set; the domain identity does not. */
+export declare const ORDER_QUOTE_VERSION: number;
+
+/** `[name, type]` pairs IN CONTRACT ORDER. The order is the protocol: a rearrangement moves every digest. */
+export declare const ORDER_QUOTE_FIELDS: readonly (readonly [string, string])[];
+
+/** The message type string, assembled from `ORDER_QUOTE_FIELDS`. */
+export declare const ORDER_QUOTE_TYPE: string;
+
+/**
+ * Names of the signed-set fields (`factory` and `signature` included) the quote does not carry. A non-empty
+ * answer means the quote is not verifiable at all.
+ */
+export declare function quoteMissingFields(quote: Partial<OrderQuote> | null | undefined): string[];
+
+/** The EIP-712 domain separator, with `chainId` and the factory taken live from the quote. */
+export declare function quoteDomainSeparator(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The hash of the message struct. */
+export declare function quoteStructHash(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The digest the provider's key signs: `0x1901` || domain separator || struct hash. */
+export declare function quoteDigest(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The signature on the wire: r || s || v with v in {27, 28}, `0x`-prefixed. */
+export declare function signQuoteDigest(request: {
+  readonly crypto: QuoteCrypto;
+  readonly digest: Uint8Array;
+  readonly privateKey: string;
+}): string;
+
+/**
+ * The address that signed the quote, recovered without knowing it beforehand, or null when the quote cannot be
+ * 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;

package/src/public/order.mjs

@@ -0,0 +1,22 @@
+// THE ORDER SIDE: what a signature commits to, and the quote types it commits under.
+//
+// The canonical context string, the commitment on a half key, the EIP-712 quote types and digests. Same rule
+// as ./xmr: names only, no second implementation, no browser.
+
+export { ORDER_CONTEXT_VERSION, orderContextString } from "../../engine/atomic/orderContext.js";
+export { halfCommitmentHex } from "../../engine/atomic/orderHalfCommit.js";
+
+export {
+  EIP712_DOMAIN_TYPE,
+  ORDER_QUOTE_DOMAIN_NAME,
+  ORDER_QUOTE_DOMAIN_VERSION,
+  ORDER_QUOTE_FIELDS,
+  ORDER_QUOTE_TYPE,
+  ORDER_QUOTE_VERSION,
+  quoteDigest,
+  quoteDomainSeparator,
+  quoteMissingFields,
+  quoteStructHash,
+  recoverQuoteKey,
+  signQuoteDigest,
+} from "../quoteEip712Spec.mjs";

package/src/public/recovery.d.ts

@@ -0,0 +1,243 @@
+// DECLARATIONS FOR THE `./recovery` ENTRY: the recovery file as it travels - the envelope a wallet writes and a
+// sweep page reads back.
+//
+// src/public/recovery.mjs only NAMES what the engine already offers; these declarations NAME the same thing for a
+// TypeScript consumer. Every signature is copied from the module the barrel re-exports
+// (`engine/recovery/recoveryFile.js`, itself a generated byte-for-byte copy of the engine source), and a symbol
+// the barrel does not re-export is not declared here.
+//
+// NO DOM AND NO ARGUMENTS: the module touches WebCrypto (`crypto.subtle`), `btoa`/`atob` and the text encoders,
+// so the environment hands those in and nothing has to be passed as a parameter here.
+
+/**
+ * The envelope version (encryption) - NOT the payload version inside it. 1 is a file written without AAD, 2 is a
+ * file whose header is authenticated. Both stay readable: people hold version-1 files, and a recovery file is the
+ * only way to claim their XMR.
+ */
+export declare const ENVELOPE_VERSION: number;
+
+/** The payload version (deal content), raised independently of the envelope: 1 keys as fields, 2 the mnemonic, 3 halves. */
+export declare const PAYLOAD_VERSION: number;
+
+/** The mark every Ninsei recovery file carries in its payload, so a foreign file is refused by name. */
+export declare const FILE_MAGIC: string;
+
+/** The deal fields of the envelope header that sit under authentication (`meta`). Each one is optional: a header without `meta` is still a header. */
+export interface RecoveryEnvelopeMeta {
+  /** The deal id the file belongs to. */
+  readonly id?: string | null;
+  /** The side of the deal the file was issued for. */
+  readonly side?: string | null;
+  /** When the file was written, as the deal record carries it. */
+  readonly createdAt?: string | number | null;
+  /** The order terms hash from the contract: the file's tie to the chain. */
+  readonly termsHash?: string | null;
+}
+
+/** The envelope header BEFORE encryption: the same fields also form the AAD of the ciphertext, which is why the writer and the reader build them from one place. */
+export interface RecoveryEnvelopeHeader {
+  readonly v: number;
+  /** The algorithm identifier: one string for the whole module. */
+  readonly alg: string;
+  /** The PBKDF2 iteration count, read FROM THE FILE on decryption so it can be raised without losing already issued files. */
+  readonly iter: number;
+  /** The PBKDF2 salt, base64. */
+  readonly salt: string;
+  /** The AES-GCM IV, base64. */
+  readonly iv: string;
+}
+
+/** The recovery file object as it is written (`ninsei-<id>.json.enc`) and read back. */
+export interface RecoveryEnvelope extends RecoveryEnvelopeHeader {
+  /** The AES-GCM ciphertext of the payload, base64. */
+  readonly ciphertext: string;
+  /** The authenticated deal fields of the header. */
+  readonly meta?: RecoveryEnvelopeMeta | null;
+}
+
+/**
+ * The AAD string: the header fields, in one FIXED order, that AES-GCM authenticates beside the ciphertext.
+ *
+ * Exported on purpose - the string is part of the format, so a check builds it with this same code instead of its
+ * own copy. An absent `meta` contributes nulls; any edit to a header field changes the string and decryption is
+ * refused.
+ */
+export declare function envelopeAad(envelope: RecoveryEnvelope): string;
+
+/** The heights a recovery scan may start from. All three are optional; a source that did not answer is simply not a source. */
+export interface RecoveryScanHeightRequest {
+  /** The escrow's birth height, from the creation receipt. */
+  readonly escrowBirthHeight?: string | number | null;
+  /** The height the application stored when it registered the watch - the source that survives a deal record without one. */
+  readonly serverRestoreHeight?: string | number | null;
+  /** The Monero node's current height. */
+  readonly nodeHeight?: string | number | null;
+}
+
+/**
+ * The height to start the recovery scan from: the smallest KNOWN height, one block lower and never below 1, or null
+ * when no source answered. A scan that starts below the money finds it; one that starts above never does.
+ */
+export declare function scanStartHeight(request?: RecoveryScanHeightRequest): number | null;
+
+/** One side of the payment the payload carries. */
+export interface RecoveryPayment {
+  readonly token?: string | null;
+  readonly amount?: string | number | null;
+}
+
+/** What the deal receives: XMR, at the address the file was issued for. */
+export interface RecoveryReceive {
+  readonly token?: string | null;
+  readonly amount?: string | number | null;
+  readonly address?: string | null;
+}
+
+/** The signed quote as the payload carries it: the signature, and the last eight characters of it as the nonce. */
+export interface RecoveryQuote {
+  readonly signature?: string | null;
+  readonly nonce?: string | null;
+}
+
+/** The escrow of the deal, as the deal record carries it. Fields beyond these travel through unchanged. */
+export interface RecoveryEscrow {
+  readonly address?: string | null;
+  readonly termsHash?: string | null;
+  readonly [key: string]: unknown;
+}
+
+/** A wallet built from HALVES (payload v3): no full spend key exists for anyone, so there is no mnemonic here. */
+export interface RecoveryWalletHalves {
+  readonly source?: string | null;
+  readonly library?: string | null;
+  readonly network?: string | null;
+  readonly address?: string | null;
+  readonly subaddress?: string | null;
+  /** MY half of the spend key. */
+  readonly spendHalf?: string | null;
+  /** MY half of the view key. */
+  readonly viewHalf?: string | null;
+  /** The counterparty's public spend point. */
+  readonly otherSpendPoint?: string | null;
+  /** The counterparty's public view point. */
+  readonly otherViewPoint?: string | null;
+  /** The counterparty's view HALF - not a secret: the full view key sees funds and cannot spend them. */
+  readonly otherViewHalf?: string | null;
+  /** The escrow address the revealed half is read from. */
+  readonly escrowAddress?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/** A wallet built from a MNEMONIC (payload v1/v2): the phrase is the single source of both keys. */
+export interface RecoveryWalletMnemonic {
+  readonly source?: string | null;
+  readonly library?: string | null;
+  readonly network?: string | null;
+  readonly address?: string | null;
+  readonly subaddress?: string | null;
+  readonly mnemonic?: string | null;
+  readonly publicSpendKey?: string | null;
+  readonly publicViewKey?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/** The Monero wallet data of the payload. Which shape it is follows the payload version. */
+export type RecoveryWallet = RecoveryWalletHalves | RecoveryWalletMnemonic;
+
+/**
+ * The payload inside the ciphertext: everything needed to complete or roll back the deal without the site.
+ *
+ * The fields are OPTIONAL on purpose - a file issued earlier carries fewer of them and must still read, and an
+ * unknown extra key is tolerated rather than refused. `magic`, `swapId`, `moneroWallet` and a supported `version`
+ * are what validation requires, and it names the one that is missing.
+ */
+export interface RecoveryPayload {
+  readonly magic?: string;
+  readonly version?: number;
+  readonly swapId?: string;
+  readonly termsHash?: string | null;
+  readonly side?: string | null;
+  readonly network?: string | null;
+  readonly moneroNetwork?: string | null;
+  readonly createdAt?: string | number | null;
+  readonly pay?: RecoveryPayment | null;
+  readonly receive?: RecoveryReceive | null;
+  readonly rate?: string | number | null;
+  readonly maker?: string | null;
+  readonly quote?: RecoveryQuote | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly moneroWallet?: RecoveryWallet | null;
+  /** The deal's timeline, taken from the record unchanged. */
+  readonly deadlines?: unknown;
+  readonly recoveryClient?: string;
+  readonly [key: string]: unknown;
+}
+
+/** The deal record the payload is built from. Only the fields `buildPayload` reads are named here. */
+export interface RecoverySwapRecord {
+  readonly id: string;
+  readonly side?: string | null;
+  readonly network?: string | null;
+  readonly moneroNetwork?: string | null;
+  readonly createdAt?: string | number | null;
+  readonly payToken?: string | null;
+  readonly payAmount?: string | number | null;
+  readonly xmrAmount?: string | number | null;
+  readonly rate?: string | number | null;
+  readonly maker?: string | null;
+  readonly quoteSignature?: string | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly timeline?: unknown;
+  readonly [key: string]: unknown;
+}
+
+/** Everything `buildPayload` assembles the payload from. `escrow` is the sender's COPY, not necessarily the one on the deal. */
+export interface RecoveryBuildRequest {
+  readonly swap: RecoverySwapRecord;
+  /** The wallet the file is issued for; without it no wallet block is written at all. */
+  readonly swapWallet?: RecoveryWallet | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly receiveAddress?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/**
+ * The payload of one deal: the deal fields, the escrow, the wallet data and the deadlines.
+ *
+ * The version tells the truth about the CONTENT, not about the module: a halves wallet is 3 and a mnemonic wallet
+ * is 2, whatever version this build happens to be.
+ */
+export declare function buildPayload(request: RecoveryBuildRequest): RecoveryPayload;
+
+/** The verdict of a successful validation: the warnings a sweep page should show, each one naming what is missing. */
+export interface RecoveryValidation {
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Validates a payload AFTER decryption: garbage can decrypt too, so the magic, the version, the deal id and the
+ * wallet fields are each checked, and a refusal throws with a clear cause - and never with a secret in its text.
+ */
+export declare function validatePayload(payload: RecoveryPayload): RecoveryValidation;
+
+/**
+ * Encrypts one payload into a recovery file envelope: a fresh salt and IV, the key derived from the passphrase, and
+ * the header authenticated as AAD. A passphrase shorter than 12 characters is refused.
+ */
+export declare function encryptPayload(payload: RecoveryPayload, passphrase: string): Promise<RecoveryEnvelope>;
+
+/**
+ * Decrypts a recovery file: the envelope version, the algorithm, the required fields and the iteration count are
+ * checked BEFORE the key is derived, a version-1 file is read without AAD, and the payload is validated before it
+ * is returned. A wrong password and an altered file are both named refusals, never a silent failure.
+ */
+export declare function decryptFile(fileObject: unknown, passphrase: string): Promise<RecoveryPayload>;
+
+/** The whole file as TEXT, ready to be written: the envelope, pretty-printed, with BigInt key halves as hex strings. */
+export declare function createRecoveryFile(payload: RecoveryPayload, passphrase: string): Promise<string>;
+
+/**
+ * The name the file is written under: lowercase, tied to the deal, `ninsei-pending.json.enc` while there is no id
+ * yet. Stable, so a repeated download shows up as a second copy of one name rather than a new random file.
+ */
+export declare function recoveryFileName(swapId?: string | null): string;

package/src/public/recovery.mjs

@@ -0,0 +1,19 @@
+// THE RECOVERY FILE AS IT TRAVELS: the envelope a wallet writes and a sweep page reads back.
+//
+// A sweep page opens a file the user was given earlier and has to prove it is the file this protocol wrote, take
+// the keys out of it and start scanning from the right height. Those rules live in the engine next to this file;
+// this entry only NAMES them, so the page does not keep a copy of them to stay in step with the package.
+
+export {
+  ENVELOPE_VERSION,
+  FILE_MAGIC,
+  PAYLOAD_VERSION,
+  buildPayload,
+  createRecoveryFile,
+  decryptFile,
+  encryptPayload,
+  envelopeAad,
+  recoveryFileName,
+  scanStartHeight,
+  validatePayload,
+} from "../../engine/recovery/recoveryFile.js";