@qntx/spark 0.0.0-stage → 0.1.1

package/dist/server.mjs

@@ -0,0 +1,373 @@
+import { r as SparkInputError } from "./errors-5xLkExNL.mjs";
+import { t as serverErrorText } from "./text-DC_Vptn6.mjs";
+import { a as lightningAddressRegisterMessage, c as lightningAddressUnregisterMessage, i as lightningAddressMessageDigest, n as checkLightningAddressDomain, o as lightningAddressStatementHash, s as lightningAddressTimestampFresh, t as LIGHTNING_ADDRESS_USERNAME_PATTERN } from "./lightning-address-CZrb8x4p.mjs";
+import { m as encodeLnurl, v as isJsonObject } from "./lnurl-kcdXU75g.mjs";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+//#region src/server/store.ts
+/**
+* In-memory {@link LightningAddressStore} — a reference implementation and the test store. `now` is
+* injectable so statement claims can prune expired entries deterministically.
+*/
+function createMemoryLightningAddressStore(now = Date.now) {
+	const byName = /* @__PURE__ */ new Map();
+	const byPubkey = /* @__PURE__ */ new Map();
+	const claimed = /* @__PURE__ */ new Map();
+	const invoices = /* @__PURE__ */ new Map();
+	return {
+		userByName: async (name) => {
+			await Promise.resolve();
+			return byName.get(name);
+		},
+		userByPublicKey: async (pubkeyHex) => {
+			await Promise.resolve();
+			return byPubkey.get(pubkeyHex);
+		},
+		countUsers: async () => {
+			await Promise.resolve();
+			return byName.size;
+		},
+		putUser: async (user) => {
+			await Promise.resolve();
+			const holder = byName.get(user.name);
+			if (holder !== void 0 && holder.pubkeyHex !== user.pubkeyHex) return false;
+			const previous = byPubkey.get(user.pubkeyHex);
+			if (previous !== void 0 && previous.name !== user.name) byName.delete(previous.name);
+			byName.set(user.name, user);
+			byPubkey.set(user.pubkeyHex, user);
+			return true;
+		},
+		deleteUser: async (pubkeyHex, name) => {
+			await Promise.resolve();
+			const held = byName.get(name);
+			if (held === void 0 || held.pubkeyHex !== pubkeyHex) return false;
+			byName.delete(name);
+			byPubkey.delete(pubkeyHex);
+			return true;
+		},
+		claimStatement: async (hashHex, expiresAtMs) => {
+			await Promise.resolve();
+			const nowMs = now();
+			for (const [hash, expiry] of claimed) if (expiry <= nowMs) claimed.delete(hash);
+			if (claimed.has(hashHex)) return false;
+			claimed.set(hashHex, expiresAtMs);
+			return true;
+		},
+		putInvoice: async (invoice) => {
+			await Promise.resolve();
+			invoices.set(invoice.paymentHash, invoice);
+		},
+		invoiceByPaymentHash: async (hashHex) => {
+			await Promise.resolve();
+			return invoices.get(hashHex);
+		},
+		pendingInvoices: async (nowMs, limit) => {
+			await Promise.resolve();
+			return [...invoices.values()].filter((invoice) => invoice.preimageHex === void 0 && invoice.expiresAtMs > nowMs).sort((a, b) => (a.lastCheckedAtMs ?? 0) - (b.lastCheckedAtMs ?? 0) || a.expiresAtMs - b.expiresAtMs).slice(0, limit);
+		},
+		markChecked: async (hashHex, nowMs) => {
+			await Promise.resolve();
+			const invoice = invoices.get(hashHex);
+			if (invoice !== void 0) invoices.set(hashHex, {
+				...invoice,
+				lastCheckedAtMs: nowMs
+			});
+		},
+		countPendingInvoices: async (nowMs, pubkeyHex) => {
+			await Promise.resolve();
+			let count = 0;
+			for (const invoice of invoices.values()) if (invoice.preimageHex === void 0 && invoice.expiresAtMs > nowMs && (pubkeyHex === void 0 || invoice.pubkeyHex === pubkeyHex)) count += 1;
+			return count;
+		},
+		pruneInvoices: async (nowMs, settledRetentionMs) => {
+			await Promise.resolve();
+			let removed = 0;
+			for (const [hash, invoice] of invoices) {
+				const settled = invoice.preimageHex !== void 0;
+				if (!settled && invoice.expiresAtMs <= nowMs || settled && invoice.expiresAtMs <= nowMs - settledRetentionMs) {
+					invoices.delete(hash);
+					removed += 1;
+				}
+			}
+			return removed;
+		},
+		settleInvoice: async (hashHex, preimageHex) => {
+			await Promise.resolve();
+			const invoice = invoices.get(hashHex);
+			if (invoice === void 0) return;
+			const settled = {
+				...invoice,
+				preimageHex
+			};
+			invoices.set(hashHex, settled);
+			return settled;
+		}
+	};
+}
+//#endregion
+//#region src/server/index.ts
+function result(status, body) {
+	return {
+		status,
+		body
+	};
+}
+/** LUD convention: business errors ride a 200 with the `{"status": "ERROR"}` envelope. */
+function lnurlError(reason) {
+	return result(200, {
+		status: "ERROR",
+		reason
+	});
+}
+/** `settlePending` polls at most this many invoice statuses in parallel. */
+const SETTLE_CONCURRENCY = 8;
+const DEFAULT_INVOICE_EXPIRY_SECS = 3600;
+const DEFAULT_MAX_PENDING_PER_USER = 100;
+const DEFAULT_MAX_PENDING = 1e4;
+const DEFAULT_MAX_USERS = 1e5;
+const DEFAULT_SETTLE_BATCH = 200;
+function positiveInt(value, fallback, name) {
+	const resolved = value ?? fallback;
+	if (!Number.isSafeInteger(resolved) || resolved < 1) throw new SparkInputError(`lightning address server: ${name} must be a positive integer`);
+	return resolved;
+}
+function asStringField(body, field) {
+	const value = body[field];
+	if (typeof value !== "string") throw new SparkInputError(`${field} is not a string`);
+	return value;
+}
+function asTimestampField(body) {
+	const value = body["timestamp"];
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new SparkInputError("timestamp is not a non-negative integer");
+	return value;
+}
+function parseKeyAndSignature(pubkeyHex, signatureHex) {
+	let pubkey;
+	try {
+		pubkey = secp256k1.Point.fromBytes(hexToBytes(pubkeyHex));
+	} catch {
+		return result(400, "invalid pubkey");
+	}
+	let signature;
+	try {
+		signature = secp256k1.Signature.fromBytes(hexToBytes(signatureHex), "der").toBytes("der");
+	} catch {
+		return result(400, "invalid signature");
+	}
+	return {
+		pubkey: pubkey.toBytes(true),
+		pubkeyHex: bytesToHex(pubkey.toBytes(true)),
+		signature
+	};
+}
+function verifyStatement(pubkey, signature, message) {
+	try {
+		return secp256k1.verify(signature, lightningAddressMessageDigest(message), pubkey, {
+			format: "der",
+			prehash: false
+		});
+	} catch {
+		return false;
+	}
+}
+/**
+* Creates the Lightning Address handlers for one `domain`. The registration LNURL handed out is the
+* LUD-01 bech32 encoding of `https://{domain}/lnurlp/{name}` (not the `lnurlp://` LUD-17 scheme) —
+* every LUD-16 wallet resolves the bare address without scheme support.
+*/
+function createLightningAddressServer(options) {
+	const domain = options.domain.toLowerCase();
+	checkLightningAddressDomain(domain);
+	if (!Number.isSafeInteger(options.minSendableMsat) || options.minSendableMsat < 1 || !Number.isSafeInteger(options.maxSendableMsat) || options.maxSendableMsat < options.minSendableMsat) throw new SparkInputError("lightning address server: invalid sendable bounds");
+	if (!Number.isSafeInteger(options.commentAllowed) || options.commentAllowed < 0) throw new SparkInputError("lightning address server: invalid commentAllowed");
+	if (options.zap !== void 0 && !/^[0-9a-f]{64}$/u.test(options.zap.receiptPublicKey)) throw new SparkInputError("lightning address server: zap.receiptPublicKey must be 32-byte lowercase hex");
+	const { client, store } = options;
+	const { zap } = options;
+	const invoiceExpirySecs = positiveInt(options.invoiceExpirySecs, DEFAULT_INVOICE_EXPIRY_SECS, "invoiceExpirySecs");
+	const maxPendingPerUser = positiveInt(options.maxPendingInvoicesPerUser, DEFAULT_MAX_PENDING_PER_USER, "maxPendingInvoicesPerUser");
+	const maxPending = positiveInt(options.maxPendingInvoices, DEFAULT_MAX_PENDING, "maxPendingInvoices");
+	const maxUsers = positiveInt(options.maxUsers, DEFAULT_MAX_USERS, "maxUsers");
+	const settleBatch = positiveInt(options.settleBatch, DEFAULT_SETTLE_BATCH, "settleBatch");
+	const now = options.now ?? (() => Date.now());
+	const nowSecs = () => Math.floor(now() / 1e3);
+	function metadataOf(user) {
+		return JSON.stringify([["text/plain", user.description], ["text/identifier", `${user.name}@${domain}`]]);
+	}
+	/**
+	* Claims the signed statement before anything else — replay protection burns the signature
+	* unconditionally, so a registration that then loses a name race still consumes its statement and
+	* the caller must sign a fresh one (its timestamp window has moved on anyway).
+	*/
+	async function claimAndStore(pubkeyHex, message, timestamp, user) {
+		const statementHash = lightningAddressStatementHash(pubkeyHex, message);
+		if (!await store.claimStatement(statementHash, (timestamp + 600) * 1e3)) return result(409, "signature has already been used");
+		if (user !== void 0) {
+			if (await store.userByPublicKey(user.pubkeyHex) === void 0 && await store.countUsers() >= maxUsers) return result(409, "registered user limit reached");
+			if (!await store.putUser(user)) return result(409, "name already taken");
+		}
+	}
+	async function register(pubkeyHex, body) {
+		if (!isJsonObject(body)) return result(400, "invalid request body");
+		let parsed;
+		try {
+			parsed = {
+				username: asStringField(body, "username").toLowerCase(),
+				signature: asStringField(body, "signature"),
+				timestamp: asTimestampField(body),
+				description: asStringField(body, "description")
+			};
+		} catch {
+			return result(400, "invalid request body");
+		}
+		if (!LIGHTNING_ADDRESS_USERNAME_PATTERN.test(parsed.username)) return result(400, "invalid username");
+		if (parsed.description.length > 512) return result(400, "description too long");
+		const key = parseKeyAndSignature(pubkeyHex, parsed.signature);
+		if ("status" in key) return key;
+		if (!lightningAddressTimestampFresh(parsed.timestamp, nowSecs())) return result(400, "invalid timestamp");
+		const message = lightningAddressRegisterMessage(domain, parsed.username, parsed.description, parsed.timestamp);
+		if (!verifyStatement(key.pubkey, key.signature, message)) return result(400, `invalid signature for domain '${domain}'`);
+		const failure = await claimAndStore(key.pubkeyHex, message, parsed.timestamp, {
+			name: parsed.username,
+			pubkeyHex: key.pubkeyHex,
+			description: parsed.description
+		});
+		if (failure !== void 0) return failure;
+		return result(200, {
+			lnurl: encodeLnurl(`https://${domain}/lnurlp/${parsed.username}`),
+			lightning_address: `${parsed.username}@${domain}`
+		});
+	}
+	async function unregister(pubkeyHex, body) {
+		if (!isJsonObject(body)) return result(400, "invalid request body");
+		let parsed;
+		try {
+			parsed = {
+				username: asStringField(body, "username").toLowerCase(),
+				signature: asStringField(body, "signature"),
+				timestamp: asTimestampField(body)
+			};
+		} catch {
+			return result(400, "invalid request body");
+		}
+		if (!LIGHTNING_ADDRESS_USERNAME_PATTERN.test(parsed.username)) return result(400, "invalid username");
+		const key = parseKeyAndSignature(pubkeyHex, parsed.signature);
+		if ("status" in key) return key;
+		if (!lightningAddressTimestampFresh(parsed.timestamp, nowSecs())) return result(400, "invalid timestamp");
+		const message = lightningAddressUnregisterMessage(domain, parsed.username, parsed.timestamp);
+		if (!verifyStatement(key.pubkey, key.signature, message)) return result(400, `invalid signature for domain '${domain}'`);
+		const failure = await claimAndStore(key.pubkeyHex, message, parsed.timestamp, void 0);
+		if (failure !== void 0) return failure;
+		const held = await store.userByPublicKey(key.pubkeyHex);
+		if (held === void 0) return result(200, "");
+		if (held.name !== parsed.username) return result(400, "username does not match the registered name");
+		if (!await store.deleteUser(key.pubkeyHex, parsed.username)) return result(400, "username does not match the registered name");
+		return result(200, "");
+	}
+	async function payRequest(name) {
+		const user = await store.userByName(name.toLowerCase());
+		if (user === void 0) return result(404, "");
+		return result(200, {
+			tag: "payRequest",
+			callback: `https://${domain}/lnurlp/${user.name}/invoice`,
+			minSendable: options.minSendableMsat,
+			maxSendable: options.maxSendableMsat,
+			metadata: metadataOf(user),
+			commentAllowed: options.commentAllowed,
+			...zap === void 0 ? {} : {
+				allowsNostr: true,
+				nostrPubkey: zap.receiptPublicKey
+			}
+		});
+	}
+	async function invoice(name, params) {
+		const user = await store.userByName(name.toLowerCase());
+		if (user === void 0) return result(404, "");
+		if (typeof params.amount !== "number" || !Number.isSafeInteger(params.amount)) return lnurlError("missing amount");
+		if (params.amount % 1e3 !== 0) return lnurlError("amount must be a whole sat amount");
+		if (params.amount < options.minSendableMsat || params.amount > options.maxSendableMsat) return lnurlError("amount out of bounds");
+		if (params.comment !== void 0 && params.comment.length > options.commentAllowed) return lnurlError("comment too long");
+		if (params.nostr !== void 0) {
+			if (zap === void 0) return lnurlError("nostr zap not supported");
+			try {
+				zap.validateRequest(params.nostr, params.amount);
+			} catch (error) {
+				return lnurlError(serverErrorText(error instanceof Error ? error.message : String(error)));
+			}
+		}
+		if (await store.countPendingInvoices(now(), user.pubkeyHex) >= maxPendingPerUser || await store.countPendingInvoices(now()) >= maxPending) return lnurlError("too many pending invoices");
+		const descriptionHash = sha256(utf8ToBytes(params.nostr ?? metadataOf(user)));
+		let created;
+		try {
+			created = await client.lightning.createInvoice({
+				amountSats: params.amount / 1e3,
+				descriptionHash,
+				receiver: hexToBytes(user.pubkeyHex),
+				expirySecs: invoiceExpirySecs
+			});
+		} catch {
+			return lnurlError("failed to create invoice");
+		}
+		const paymentHash = bytesToHex(created.paymentHash);
+		await store.putInvoice({
+			paymentHash,
+			requestId: created.id,
+			name: user.name,
+			pubkeyHex: user.pubkeyHex,
+			invoice: created.invoice,
+			expiresAtMs: created.expiresAtMs,
+			...params.nostr === void 0 ? {} : { zapRequest: params.nostr },
+			...params.comment === void 0 ? {} : { comment: params.comment }
+		});
+		return result(200, {
+			pr: created.invoice,
+			routes: [],
+			verify: `https://${domain}/lnurlp/verify/${paymentHash}`
+		});
+	}
+	async function verify(paymentHashHex) {
+		const hash = paymentHashHex.toLowerCase();
+		const record = /^[0-9a-f]{64}$/u.test(hash) ? await store.invoiceByPaymentHash(hash) : void 0;
+		if (record === void 0) return lnurlError("Not found");
+		return result(200, {
+			status: "OK",
+			settled: record.preimageHex !== void 0,
+			...record.preimageHex === void 0 ? {} : { preimage: record.preimageHex },
+			pr: record.invoice
+		});
+	}
+	async function settleOne(record) {
+		try {
+			const { preimage } = await client.lightning.receiveStatus({
+				requestId: record.requestId,
+				paymentHash: hexToBytes(record.paymentHash)
+			});
+			if (preimage === void 0) return;
+			return await store.settleInvoice(record.paymentHash, bytesToHex(preimage));
+		} catch {
+			return;
+		} finally {
+			await store.markChecked(record.paymentHash, now()).catch(() => void 0);
+		}
+	}
+	async function settlePending() {
+		const pending = await store.pendingInvoices(now(), settleBatch);
+		const settled = [];
+		for (let start = 0; start < pending.length; start += SETTLE_CONCURRENCY) {
+			const chunk = pending.slice(start, start + SETTLE_CONCURRENCY);
+			const results = await Promise.all(chunk.map(settleOne));
+			settled.push(...results.filter((invoice) => invoice !== void 0));
+		}
+		return settled;
+	}
+	return {
+		register,
+		unregister,
+		payRequest,
+		invoice,
+		verify,
+		settlePending
+	};
+}
+//#endregion
+export { createLightningAddressServer, createMemoryLightningAddressStore };

package/dist/signer.d.mts

@@ -0,0 +1,72 @@
+import { n as SparkCrypto } from "./index-DUSx3L3J.mjs";
+import { n as SparkNetwork } from "./lightning-address-CRULmi9v.mjs";
+import { _ as StaticDepositClaimRequest, a as OperatorCommitment, c as PreparedClaim, d as PreparedTransferLeaf, f as SigningCommitment, g as SparkSigner, h as SparkOperator, i as IdentityStatement, l as PreparedLightningReceive, m as SparkLeafKey, n as FrostSignJob, o as PrepareClaimRequest, p as SparkKey, r as HtlcTimeoutSignRequest, s as PrepareTransferRequest, t as FrostAggregateJob, u as PreparedTransfer, v as SigningTarget } from "./types-jBCznYd6.mjs";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+//#region src/signer/keys.d.ts
+/**
+ * The 64-byte extended private key (private key ‖ chain code) at `m/8797555'/account'` — the input
+ * {@link createSparkSigner} expects. The default account matches the official SDK: mainnet 1,
+ * regtest 0.
+ */
+export declare function sparkAccountKey(seed: Uint8Array, network: SparkNetwork, account?: number): Uint8Array;
+//#endregion
+//#region src/signer/local.d.ts
+/**
+ * Creates the local Spark signer: the implementation of {@link SparkSigner} that holds the account
+ * extended private key and delegates curve-heavy FROST/ECIES/VSS work to a `SparkCrypto` backend.
+ * Throws `SparkInputError` on an ABI version mismatch or a malformed `accountKey`.
+ *
+ * The operator set, VSS threshold and SSP identity are bound here and default to the network's
+ * `sparkNetworkConfig`; every key-tweak share and the static-deposit secret is sealed to these keys
+ * and no request can retarget them. Pass explicit values only to point the signer at a different
+ * deployment (the local stack's operators/SSP), exactly like the client's `operators` and `ssp`
+ * options.
+ */
+export declare function createSparkSigner(options: {
+  readonly crypto: SparkCrypto;
+  readonly accountKey: Uint8Array;
+  readonly network: SparkNetwork;
+  readonly random: (length: number) => Uint8Array;
+  /**
+   * Signing-operator set the key-tweak and preimage shares are sealed to; defaults to the network's
+   * operator set.
+   */
+  readonly operators?: ReadonlyArray<SparkOperator>;
+  /** VSS threshold across `operators`; defaults to the network's threshold. */
+  readonly threshold?: number;
+  /** SSP identity the static-deposit secret is sealed to; defaults to the network's SSP key. */
+  readonly sspIdentityPublicKey?: Uint8Array;
+}): SparkSigner;
+//#endregion
+//#region src/signer/lnurl-auth.d.ts
+/**
+ * The 64-byte extended private key (private key ‖ chain code) at `m/138'` — the input
+ * {@link createLnurlAuthSigner} expects. The caller wipes the result when it is done holding the
+ * material.
+ */
+export declare function lnurlAuthRootKey(seed: Uint8Array): Uint8Array;
+/**
+ * A signer that derives LUD-05 domain-specific linking keys and signs LUD-04 `k1` challenges with
+ * them. `domain` must already be lowercase — the LNURL layer lowercases the host when parsing; an
+ * uppercase input here means the caller skipped that step.
+ */
+type LnurlAuthSigner = {
+  /** Compressed linking public key for `domain` (lowercase host). */
+  readonly linkingKey: (domain: string) => Promise<Uint8Array>;
+  /** DER ECDSA over the raw 32-byte k1 with the domain's linking key. */
+  readonly sign: (request: {
+    readonly domain: string;
+    readonly k1: Uint8Array;
+  }) => Promise<{
+    readonly linkingKey: Uint8Array;
+    readonly signature: Uint8Array;
+  }>;
+  /** Wipes the root key and cached material; later calls reject. */
+  readonly dispose: () => void;
+};
+/** Creates the signer from a `m/138'` extended private key produced by {@link lnurlAuthRootKey}. */
+export declare function createLnurlAuthSigner(options: {
+  readonly rootKey: Uint8Array;
+}): LnurlAuthSigner;
+//#endregion
+export type { FrostAggregateJob, FrostSignJob, HtlcTimeoutSignRequest, IdentityStatement, LnurlAuthSigner, OperatorCommitment, PrepareClaimRequest, PrepareTransferRequest, PreparedClaim, PreparedLightningReceive, PreparedTransfer, PreparedTransferLeaf, SigningCommitment, SigningTarget, SparkKey, SparkLeafKey, SparkNetwork, SparkOperator, SparkSigner, StaticDepositClaimRequest };