@qntx/spark 0.0.0-stage → 0.1.0

package/dist/lightning-address-CRULmi9v.d.mts

@@ -0,0 +1,106 @@
+import "@bufbuild/protobuf/codegenv2";
+import "@bufbuild/protobuf/wkt";
+import { Message, UnknownEnum } from "@bufbuild/protobuf";
+//#region src/proto/gen/common_pb.d.ts
+/**
+ * A signature tagged with the scheme used to produce it, which determines how to verify it.
+ *
+ * @generated from message common.Signature
+ */
+type Signature = Message<"common.Signature"> & {
+  /**
+   * @generated from field: common.SignatureScheme scheme = 1;
+   */
+  scheme: SignatureScheme;
+  /**
+   * @generated from field: bytes signature = 2;
+   */
+  signature: Uint8Array;
+};
+/**
+ * The scheme used to produce a Signature.
+ *
+ * @generated from enum common.SignatureScheme
+ */
+declare const SignatureScheme: {
+  /**
+   * @generated from enum value: SIGNATURE_SCHEME_UNSPECIFIED = 0;
+   */
+  readonly UNSPECIFIED: 0;
+  /**
+   * secp256k1 ECDSA, strict DER encoding (variable length).
+   *
+   * @generated from enum value: SIGNATURE_SCHEME_ECDSA = 1;
+   */
+  readonly ECDSA: 1;
+  /**
+   * BIP-340 Schnorr over secp256k1, 64 bytes.
+   *
+   * @generated from enum value: SIGNATURE_SCHEME_SCHNORR = 2;
+   */
+  readonly SCHNORR: 2;
+};
+/**
+ * The scheme used to produce a Signature.
+ *
+ * @generated from enum common.SignatureScheme
+ */
+type SignatureScheme = (typeof SignatureScheme)[keyof typeof SignatureScheme] | UnknownEnum;
+//#endregion
+//#region src/core/network.d.ts
+/** Spark networks: Bitcoin mainnet, or the public regtest deployment. */
+type SparkNetwork = "mainnet" | "regtest";
+/** One Spark signing operator. Values come from the upstream wallet configuration. */
+type SparkOperatorConfig = {
+  readonly id: number;
+  /** 64 lowercase hex characters; the FROST identifier scalar. */
+  readonly identifier: string;
+  readonly address: string;
+  /** 33-byte compressed secp256k1 public key. */
+  readonly identityPublicKey: Uint8Array;
+};
+type SparkNetworkConfig = {
+  readonly network: SparkNetwork;
+  readonly operators: ReadonlyArray<SparkOperatorConfig>;
+  readonly threshold: number;
+  /** Identifier of the coordinator operator (the `…01` identifier upstream). */
+  readonly coordinator: string;
+  readonly ssp: {
+    readonly baseUrl: string;
+    /** 33-byte compressed secp256k1 public key of the SSP service. */
+    readonly identityPublicKey: Uint8Array;
+    /** GraphQL path appended to `baseUrl` by the SSP client (upstream schema endpoint). */
+    readonly graphqlPath: string;
+  };
+  /** Token output parameters stamped on every token transaction (upstream wallet-config defaults). */
+  readonly tokens: {
+    readonly withdrawBondSats: number;
+    readonly withdrawRelativeBlockLocktime: number;
+    readonly validityDurationSeconds: number;
+  };
+};
+/**
+ * Static network parameters for `network`. Each call builds a fresh config — fresh `Uint8Array`
+ * keys — so callers can never corrupt shared module state. Throws {@link SparkInputError} on an
+ * unknown name.
+ */
+declare function sparkNetworkConfig(network: SparkNetwork): SparkNetworkConfig;
+//#endregion
+//#region src/core/lightning-address.d.ts
+/** The statement shape `SparkSigner.signIdentity` accepts for Lightning Address requests. */
+type LightningAddressStatement = {
+  readonly kind: "lightning-address";
+  readonly action: "register";
+  readonly domain: string;
+  readonly username: string;
+  readonly description: string;
+  readonly timestamp: number;
+} | {
+  readonly kind: "lightning-address";
+  readonly action: "unregister";
+  readonly domain: string;
+  readonly username: string;
+  readonly timestamp: number;
+};
+//#endregion
+export { sparkNetworkConfig as a, SparkOperatorConfig as i, SparkNetwork as n, Signature as o, SparkNetworkConfig as r, LightningAddressStatement as t };

package/dist/lightning-address-CZrb8x4p.mjs

@@ -0,0 +1,92 @@
+import { r as SparkInputError } from "./errors-5xLkExNL.mjs";
+import { bytesToHex, concatBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+//#region src/core/lightning-address.ts
+const VERSION = "breez-lnurl:v2";
+/**
+* LUD-16 strict username rule: lowercase alphanumerics plus `-`, `_`, `.` and `+`, 1–64 characters.
+* Callers lowercase before validating — uppercase is an error, never silently folded.
+*/
+const LIGHTNING_ADDRESS_USERNAME_PATTERN = /^[a-z0-9\-_.+]{1,64}$/u;
+const HOST_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/u;
+function fail(message) {
+	throw new SparkInputError(`lightning address: ${message}`);
+}
+/** A registration name: LUD-16 local-part, already lowercase. */
+function checkLightningAddressUsername(username) {
+	if (!LIGHTNING_ADDRESS_USERNAME_PATTERN.test(username)) fail("invalid username");
+}
+/**
+* The domain a message binds to: non-empty lowercase host labels. The check must forbid LF — an LF
+* in the domain would let one tuple read as another.
+*/
+function checkLightningAddressDomain(domain) {
+	if (domain.length === 0 || domain.length > 253) fail("invalid domain");
+	for (const label of domain.split(".")) if (!HOST_LABEL.test(label)) fail("invalid domain");
+}
+function checkTimestamp(timestamp) {
+	if (!Number.isSafeInteger(timestamp) || timestamp < 0) fail("invalid timestamp");
+}
+/** `sha256` of the exact description bytes, lowercase hex — the description enters hashed. */
+function lightningAddressDescriptionHash(description) {
+	return bytesToHex(sha256(utf8ToBytes(description)));
+}
+/**
+* `POST /lnurlpay/{pubkey}`: the message claiming `username` on `domain`, fields joined by LF:
+* `breez-lnurl:v2` ‖ `register` ‖ domain ‖ username ‖ sha256(description) ‖ timestamp.
+*/
+function lightningAddressRegisterMessage(domain, username, description, timestamp) {
+	checkLightningAddressDomain(domain);
+	checkLightningAddressUsername(username);
+	checkTimestamp(timestamp);
+	return [
+		VERSION,
+		"register",
+		domain,
+		username,
+		lightningAddressDescriptionHash(description),
+		String(timestamp)
+	].join("\n");
+}
+/**
+* `DELETE /lnurlpay/{pubkey}`: the message giving up `username` on `domain`: `breez-lnurl:v2` ‖
+* `unregister` ‖ domain ‖ username ‖ timestamp.
+*/
+function lightningAddressUnregisterMessage(domain, username, timestamp) {
+	checkLightningAddressDomain(domain);
+	checkLightningAddressUsername(username);
+	checkTimestamp(timestamp);
+	return [
+		VERSION,
+		"unregister",
+		domain,
+		username,
+		String(timestamp)
+	].join("\n");
+}
+/** Builds the canonical message a {@link LightningAddressStatement} signs, after validation. */
+function lightningAddressMessage(statement) {
+	if (statement.action === "register") return lightningAddressRegisterMessage(statement.domain, statement.username, statement.description, statement.timestamp);
+	return lightningAddressUnregisterMessage(statement.domain, statement.username, statement.timestamp);
+}
+/** `sha256(message)` — the digest the identity key signs and the server verifies. */
+function lightningAddressMessageDigest(message) {
+	return sha256(utf8ToBytes(message));
+}
+/**
+* The replay-protection claim key: `sha256(pubkeyHex ‖ 0x00 ‖ message)`. The pubkey is the
+* lowercase compressed-hex string; the 0x00 separator keeps the pubkey/message boundary unambiguous
+* (Breez `statement_hash`).
+*/
+function lightningAddressStatementHash(pubkeyHex, message) {
+	return bytesToHex(sha256(concatBytes(utf8ToBytes(pubkeyHex), Uint8Array.of(0), utf8ToBytes(message))));
+}
+/**
+* Whether a statement `timestamp` (seconds) is inside the accept window around `nowSecs`, bounded
+* symmetrically so a device whose clock runs fast still works.
+*/
+function lightningAddressTimestampFresh(timestamp, nowSecs) {
+	return Number.isSafeInteger(timestamp) && timestamp >= 0 && Math.abs(timestamp - nowSecs) <= 600;
+}
+//#endregion
+export { lightningAddressRegisterMessage as a, lightningAddressUnregisterMessage as c, lightningAddressMessageDigest as i, checkLightningAddressDomain as n, lightningAddressStatementHash as o, lightningAddressMessage as r, lightningAddressTimestampFresh as s, LIGHTNING_ADDRESS_USERNAME_PATTERN as t };