@qntx/spark 0.0.0-stage → 0.1.1

package/dist/lnurl.d.mts

@@ -0,0 +1,258 @@
+import { n as SparkNetwork, t as LightningAddressStatement } from "./lightning-address-CRULmi9v.mjs";
+import { t as Bolt11Invoice } from "./bolt11-DsNTTS_O.mjs";
+//#region src/lnurl/auth.d.ts
+type LnurlAuthAction = "register" | "login" | "link" | "auth";
+type LnurlAuthRequest = {
+  readonly tag: "login";
+  /** The full service URL to GET in the second step, normalized. */
+  readonly url: string;
+  /** The 32-byte challenge, lowercase hex. */
+  readonly k1: string;
+  readonly action?: LnurlAuthAction | undefined;
+  /** The service's lowercase hostname — shown to the user on login. */
+  readonly domain: string;
+};
+/**
+ * Parses an LNURL-auth URL (the decoded form of a `lnurl1…` string or a bare https/onion URL).
+ * Requires `tag=login` and a 64-hex `k1` query parameter; `action` must be one of the LUD-04 enum
+ * values when present.
+ */
+export declare function parseLnurlAuth(url: string): LnurlAuthRequest;
+/**
+ * The signing shape the auth flow needs — a structural subset of `LnurlAuthSigner` (the lnurl layer
+ * must not import the signer implementation).
+ */
+type LnurlAuthSigning = {
+  readonly sign: (request: {
+    readonly domain: string;
+    readonly k1: Uint8Array;
+  }) => Promise<{
+    readonly linkingKey: Uint8Array;
+    readonly signature: Uint8Array;
+  }>;
+};
+/**
+ * LUD-04 step 3: signs the `k1` challenge with the domain's linking key and GETs the service URL
+ * with `sig` and `key` appended. The k1 challenge and the signature never appear in error
+ * messages.
+ */
+export declare function submitLnurlAuth(request: LnurlAuthRequest, options: {
+  readonly fetch: typeof globalThis.fetch;
+  readonly signer: LnurlAuthSigning;
+}): Promise<void>;
+//#endregion
+//#region src/lnurl/codec.d.ts
+/** LUD-01 §HTTPS or Onion: clearnet https, or http only for a `.onion` host. */
+export declare function checkLnurlUrl(url: string): void;
+/**
+ * Decodes a bech32 `lnurl1…` string into the normalized URL it wraps (LUD-01). Accepts upper- or
+ * lowercase (never mixed) and an optional `lightning:` scheme prefix.
+ */
+export declare function decodeLnurl(text: string): string;
+/** Bech32-encodes an https/onion URL into a lowercase `lnurl1…` string (LUD-01). */
+export declare function encodeLnurl(url: string): string;
+/**
+ * LUD-16 `<username>@<domain>` → the well-known pay endpoint. `@<domain>` resolves to the default
+ * identifier `_`. An `.onion` domain yields http, a clearnet domain https. Usernames are lowercased
+ * and must match `a-z0-9-_.` plus `+` for service tags; ports, userinfo and paths are rejected.
+ */
+export declare function lightningAddressUrl(address: string): string;
+//#endregion
+//#region src/lnurl/http.d.ts
+type JsonObject = Record<string, unknown>;
+/**
+ * One GET against an LNURL endpoint with the injected fetch. HTTP failures and the protocol-level
+ * `{"status": "ERROR", "reason"}` envelope map onto the SSP client's error vocabulary; error
+ * messages never echo request URLs — withdraw callbacks carry the ephemeral `k1`, which authorizes
+ * a payout.
+ */
+export declare function lnurlGetJson(url: string, fetch: typeof globalThis.fetch): Promise<JsonObject>;
+/**
+ * One JSON request with a body (POST/DELETE) against an LNURL endpoint. Same error vocabulary as
+ * {@link lnurlGetJson}; a 2xx response with an empty body returns `undefined`, and request bodies
+ * never echo into error messages — the server's response text is sanitized before it is embedded.
+ */
+export declare function lnurlSendJson(url: string, fetch: typeof globalThis.fetch, options: {
+  readonly method: string;
+  readonly body: JsonObject;
+  /** Whole-round-trip bound; defaults to {@link LNURL_REQUEST_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+}): Promise<JsonObject | undefined>;
+//#endregion
+//#region src/lnurl/success-action.d.ts
+type LnurlSuccessAction = {
+  readonly tag: "message";
+  readonly message: string;
+} | {
+  readonly tag: "url";
+  readonly description: string;
+  readonly url: string;
+} | {
+  readonly tag: "aes";
+  readonly description: string;
+  readonly ciphertext: string;
+  readonly iv: string;
+};
+/**
+ * Parses a `successAction` object (LUD-09). `callbackHost` is the payRequest callback's hostname:
+ * `url` actions must stay on that domain. Unknown tags are rejected — a wallet that cannot show the
+ * action must not proceed (LUD-09).
+ */
+export declare function parseSuccessAction(value: unknown, callbackHost: string): LnurlSuccessAction;
+/**
+ * LUD-10: decrypts an `aes` successAction with the payment preimage — AES-256-CBC, the preimage is
+ * the key, `iv` is base64 of 16 bytes, `ciphertext` base64 of at most 4 KiB, PKCS#7 padding, UTF-8
+ * plaintext.
+ */
+export declare function decryptSuccessAction(action: Extract<LnurlSuccessAction, {
+  readonly tag: "aes";
+}>, preimage: Uint8Array): string;
+//#endregion
+//#region src/lnurl/pay.d.ts
+type LnurlPayRequest = {
+  readonly tag: "payRequest";
+  /** Second-callback URL from the service. */
+  readonly callback: string;
+  readonly minSendableMsat: number;
+  readonly maxSendableMsat: number;
+  /** Raw metadata JSON string — hashed verbatim into the invoice's `h` field. */
+  readonly metadata: string;
+  /** The metadata's single `text/plain` entry (LUD-06, mandatory). */
+  readonly description: string;
+  /** Max comment characters the service accepts (LUD-12); 0 = unsupported. */
+  readonly commentAllowed: number;
+  /** NIP-57 zaps: the service accepts a signed `nostr` zap-request event. */
+  readonly allowsNostr: boolean;
+  /** 32-byte x-only nostr pubkey; present exactly when `allowsNostr`. */
+  readonly nostrPubkey?: Uint8Array | undefined;
+};
+export declare function parseLnurlPayRequest(body: JsonObject): LnurlPayRequest;
+type LnurlInvoice = {
+  /** The service's BOLT-11 payment request string. */
+  readonly invoice: string;
+  readonly decoded: Bolt11Invoice;
+  readonly successAction?: LnurlSuccessAction | undefined;
+};
+/**
+ * LUD-06 second callback: requests the invoice for `amountMsat`, then verifies it against the
+ * request — exact amount, invoice network, and a `h` description-hash over the raw metadata (or
+ * over the zap-request event alone for a nostr zap, NIP-57).
+ */
+export declare function requestInvoice(request: LnurlPayRequest, options: {
+  readonly fetch: typeof globalThis.fetch;
+  readonly network: SparkNetwork;
+  readonly amountMsat: number;
+  readonly comment?: string;
+  readonly zapRequest?: string;
+}): Promise<LnurlInvoice>;
+//#endregion
+//#region src/lnurl/withdraw.d.ts
+type LnurlWithdrawRequest = {
+  readonly tag: "withdrawRequest";
+  /** Second-callback URL accepting `k1` and `pr` query params. */
+  readonly callback: string;
+  /** Ephemeral service challenge echoed back verbatim on the callback. */
+  readonly k1: string;
+  readonly defaultDescription: string;
+  readonly minWithdrawableMsat: number;
+  readonly maxWithdrawableMsat: number;
+};
+export declare function parseLnurlWithdrawRequest(body: JsonObject): LnurlWithdrawRequest;
+/**
+ * LUD-03 step 5: submits the wallet's BOLT-11 `invoice` for payment. The service pays
+ * asynchronously; a `{"status": "OK"}` body means it accepted — errors surface as
+ * `SparkRequestError` (`lnurl_error` / `http_*`).
+ */
+export declare function submitWithdraw(request: LnurlWithdrawRequest, options: {
+  readonly fetch: typeof globalThis.fetch;
+  readonly invoice: string;
+}): Promise<void>;
+//#endregion
+//#region src/lnurl/fetch.d.ts
+type LnurlResolved = LnurlPayRequest | LnurlWithdrawRequest | LnurlAuthRequest;
+/**
+ * Resolves an `lnurl1…` string, a lightning address (`user@domain`, LUD-16) or a bare https/onion
+ * URL into a typed LNURL service request. A `tag=login` query is a LUD-04 auth challenge carried
+ * inside the LNURL itself and returns without fetching; otherwise the endpoint is fetched and only
+ * the interactive `payRequest` (LUD-06) and `withdrawRequest` (LUD-03) tags are supported.
+ */
+export declare function resolveLnurl(input: string, options: {
+  readonly fetch: typeof globalThis.fetch;
+}): Promise<LnurlResolved>;
+//#endregion
+//#region src/lnurl/lightning-address.d.ts
+/**
+ * The signing shape the registration helpers need — a structural subset of `SparkSigner` (the lnurl
+ * layer must not import the signer implementation).
+ */
+type LightningAddressSigning = {
+  readonly identityPublicKey: () => Promise<Uint8Array>;
+  readonly signIdentity: (statement: LightningAddressStatement) => Promise<Uint8Array>;
+};
+type RegisterLightningAddressBody = {
+  readonly username: string;
+  readonly signature: string;
+  readonly timestamp: number;
+  readonly description: string;
+};
+type UnregisterLightningAddressBody = {
+  readonly username: string;
+  readonly signature: string;
+  readonly timestamp: number;
+};
+type LightningAddressRegistration = {
+  readonly lnurl: string;
+  readonly lightningAddress: string;
+};
+/**
+ * Builds the register request body the signed statement commits to — lowercased domain and
+ * username, fresh timestamp — and signs it. Split from {@link registerLightningAddress} so the same
+ * bytes can be handed to a server handler in tests without HTTP.
+ */
+export declare function lightningAddressRegisterBody(options: {
+  readonly domain: string;
+  readonly username: string;
+  readonly description: string;
+  readonly signer: LightningAddressSigning;
+  readonly now?: (() => number) | undefined;
+}): Promise<{
+  readonly pubkeyHex: string;
+  readonly body: RegisterLightningAddressBody;
+}>;
+/** The unregister counterpart of {@link lightningAddressRegisterBody}. */
+export declare function lightningAddressUnregisterBody(options: {
+  readonly domain: string;
+  readonly username: string;
+  readonly signer: LightningAddressSigning;
+  readonly now?: (() => number) | undefined;
+}): Promise<{
+  readonly pubkeyHex: string;
+  readonly body: UnregisterLightningAddressBody;
+}>;
+/**
+ * Claims `username` on the Lightning Address server at `serverUrl`: signs the register statement
+ * and POSTs it to `/lnurlpay/{pubkey}`. `serverUrl` must be https or an `.onion` http URL.
+ */
+export declare function registerLightningAddress(options: {
+  readonly fetch: typeof globalThis.fetch;
+  readonly serverUrl: string;
+  readonly domain: string;
+  readonly username: string;
+  readonly description: string;
+  readonly signer: LightningAddressSigning;
+  readonly now?: (() => number) | undefined;
+}): Promise<LightningAddressRegistration>;
+/**
+ * Gives up `username` on the server: signs the unregister statement and DELETEs
+ * `/lnurlpay/{pubkey}`.
+ */
+export declare function unregisterLightningAddress(options: {
+  readonly fetch: typeof globalThis.fetch;
+  readonly serverUrl: string;
+  readonly domain: string;
+  readonly username: string;
+  readonly signer: LightningAddressSigning;
+  readonly now?: (() => number) | undefined;
+}): Promise<void>;
+//#endregion
+export type { JsonObject, LightningAddressRegistration, LightningAddressSigning, LnurlAuthAction, LnurlAuthRequest, LnurlAuthSigning, LnurlInvoice, LnurlPayRequest, LnurlResolved, LnurlSuccessAction, LnurlWithdrawRequest, RegisterLightningAddressBody, UnregisterLightningAddressBody };

package/dist/lnurl.mjs

@@ -0,0 +1 @@
+export { f as checkLnurlUrl, p as decodeLnurl, u as decryptSuccessAction, m as encodeLnurl, t as lightningAddressRegisterBody, n as lightningAddressUnregisterBody, h as lightningAddressUrl, y as lnurlGetJson, b as lnurlSendJson, g as parseLnurlAuth, c as parseLnurlPayRequest, o as parseLnurlWithdrawRequest, d as parseSuccessAction, r as registerLightningAddress, l as requestInvoice, a as resolveLnurl, _ as submitLnurlAuth, s as submitWithdraw, i as unregisterLightningAddress } from "./lnurl-kcdXU75g.mjs";

package/dist/server.d.mts

@@ -0,0 +1,158 @@
+import { n as SparkClient } from "./index-B_g3vHnT.mjs";
+//#region src/server/store.d.ts
+type LightningAddressUser = {
+  /** Lowercase LUD-16 local-part. */
+  readonly name: string;
+  /** The owner's compressed secp256k1 identity public key, lowercase hex. */
+  readonly pubkeyHex: string;
+  /** The registration description — verbatim into the payRequest `text/plain` metadata. */
+  readonly description: string;
+};
+type LightningAddressInvoice = {
+  /** Lowercase hex payment hash of the BOLT-11 invoice. */
+  readonly paymentHash: string;
+  /** The SSP lightning-receive request id — the settlement status is polled through it. */
+  readonly requestId: string;
+  /** The registered name the invoice was issued to. */
+  readonly name: string;
+  /** The payee's compressed identity public key, lowercase hex. */
+  readonly pubkeyHex: string;
+  /** The encoded BOLT-11 invoice handed to the payer. */
+  readonly invoice: string;
+  readonly expiresAtMs: number;
+  /** Last `settlePending` status check — the pending queue is served least-recently-checked first. */
+  readonly lastCheckedAtMs?: number;
+  /** The raw zap-request event JSON (NIP-57), when the payer sent one. */
+  readonly zapRequest?: string;
+  readonly comment?: string;
+  /** Lowercase hex settled preimage — present only once settled. */
+  readonly preimageHex?: string;
+};
+/**
+ * The persistence the server handlers need. A pubkey holds at most one name: registering a new name
+ * releases the old one.
+ */
+type LightningAddressStore = {
+  readonly userByName: (name: string) => Promise<LightningAddressUser | undefined>;
+  readonly userByPublicKey: (pubkeyHex: string) => Promise<LightningAddressUser | undefined>;
+  /** Registered name count — one row per name, and each pubkey holds at most one. */
+  readonly countUsers: () => Promise<number>;
+  /**
+   * Registers `user.name` for `user.pubkeyHex`. Returns `false` when another pubkey already holds
+   * the name; otherwise removes the pubkey's previous name and stores the record.
+   */
+  readonly putUser: (user: LightningAddressUser) => Promise<boolean>;
+  /** Removes the name only when it is still held by `pubkeyHex`. */
+  readonly deleteUser: (pubkeyHex: string, name: string) => Promise<boolean>;
+  /**
+   * Claims a signed statement for replay protection: `false` when the hash was already claimed,
+   * else records it with `expiresAtMs` (after which the record may be dropped) and returns `true`.
+   */
+  readonly claimStatement: (hashHex: string, expiresAtMs: number) => Promise<boolean>;
+  readonly putInvoice: (invoice: LightningAddressInvoice) => Promise<void>;
+  readonly invoiceByPaymentHash: (hashHex: string) => Promise<LightningAddressInvoice | undefined>;
+  /**
+   * Unsettled invoices whose expiry has not passed at `nowMs` — at most `limit`, ordered
+   * least-recently-checked first so a bounded `settlePending` round rotates fairly.
+   */
+  readonly pendingInvoices: (nowMs: number, limit: number) => Promise<ReadonlyArray<LightningAddressInvoice>>;
+  /** Records that `hashHex` was status-checked at `nowMs`; feeds the {@link pendingInvoices} order. */
+  readonly markChecked: (hashHex: string, nowMs: number) => Promise<void>;
+  /** Unsettled, unexpired invoice count at `nowMs` — scoped to `pubkeyHex` when given. */
+  readonly countPendingInvoices: (nowMs: number, pubkeyHex?: string) => Promise<number>;
+  /**
+   * Deletes expired unsettled invoices and settled invoices whose expiry passed more than
+   * `settledRetentionMs` ago. Returns the number of rows removed.
+   */
+  readonly pruneInvoices: (nowMs: number, settledRetentionMs: number) => Promise<number>;
+  readonly settleInvoice: (hashHex: string, preimageHex: string) => Promise<LightningAddressInvoice | undefined>;
+};
+/**
+ * In-memory {@link LightningAddressStore} — a reference implementation and the test store. `now` is
+ * injectable so statement claims can prune expired entries deterministically.
+ */
+export declare function createMemoryLightningAddressStore(now?: () => number): LightningAddressStore;
+//#endregion
+//#region src/server/index.d.ts
+export type LightningAddressResult = {
+  readonly status: number;
+  readonly body: unknown;
+};
+/** NIP-57 zap support: the receipt key plus the app's own zap-request validation. */
+export type LightningAddressZapConfig = {
+  /** The receipt signer's 32-byte x-only public key, lowercase hex — the `nostrPubkey` payers see. */
+  readonly receiptPublicKey: string;
+  /**
+   * Validates a raw zap-request event JSON for `amountMsat`; throwing rejects the invoice. The
+   * registered user record holds no nostr key, so the request's `p` tag (the nostr pubkey the
+   * receipt attributes the zap to) cannot be bound to the payee — same behavior as Breez.
+   */
+  readonly validateRequest: (json: string, amountMsat: number) => void;
+};
+/** The wallet the server creates invoices through — a `SparkClient` or its lightning slice. */
+export type LightningAddressServerClient = Pick<SparkClient, "lightning">;
+export type LightningAddressServer = {
+  /** `POST /lnurlpay/{pubkey}` — signed statement claims a name. */
+  readonly register: (pubkeyHex: string, body: unknown) => Promise<LightningAddressResult>;
+  /** `DELETE /lnurlpay/{pubkey}` — signed statement gives the held name up. */
+  readonly unregister: (pubkeyHex: string, body: unknown) => Promise<LightningAddressResult>;
+  /** `GET /.well-known/lnurlp/{name}` (or `/lnurlp/{name}`) — the LUD-06 payRequest. */
+  readonly payRequest: (name: string) => Promise<LightningAddressResult>;
+  /** `GET /lnurlp/{name}/invoice?amount=&comment=&nostr=` — the LUD-06 callback. */
+  readonly invoice: (name: string, params: {
+    readonly amount: unknown;
+    readonly comment?: string;
+    readonly nostr?: string;
+  }) => Promise<LightningAddressResult>;
+  /** `GET /lnurlp/verify/{paymentHash}` — LUD-21 payment status. */
+  readonly verify: (paymentHashHex: string) => Promise<LightningAddressResult>;
+  /**
+   * Polls `client.lightning.receiveStatus` for a bounded batch of pending invoices —
+   * least-recently-checked first — and settles the ones whose verified preimage arrived. Returns
+   * the records settled this round so the app can publish zap receipts or webhooks.
+   */
+  readonly settlePending: () => Promise<ReadonlyArray<LightningAddressInvoice>>;
+};
+/**
+ * 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.
+ */
+export declare function createLightningAddressServer(options: {
+  readonly client: LightningAddressServerClient;
+  /** The served hostname — validated, lowercased, and signed into every registration message. */
+  readonly domain: string;
+  readonly store: LightningAddressStore;
+  readonly minSendableMsat: number;
+  readonly maxSendableMsat: number;
+  /** Longest payer comment accepted (LUD-12 `commentAllowed`). */
+  readonly commentAllowed: number;
+  /** BOLT-11 expiry requested for every issued invoice; default {@link DEFAULT_INVOICE_EXPIRY_SECS}. */
+  readonly invoiceExpirySecs?: number;
+  /**
+   * Pending (unsettled, unexpired) invoices one payee may hold — an unauthenticated callback is a
+   * write, so without a cap a name's quota is a free database row each. Default 100. The cap is a
+   * storage bound, not abuse protection: anyone can fill one name's quota with unpaid invoices for
+   * up to `invoiceExpirySecs`, temporarily blocking that name's payments — operators should add
+   * per-IP rate limiting at the reverse proxy.
+   */
+  readonly maxPendingInvoicesPerUser?: number;
+  /** Pending invoices the whole server holds; default 10_000. */
+  readonly maxPendingInvoices?: number;
+  /**
+   * Registered names the whole server holds; default 100_000. A pubkey re-registering a new name is
+   * never blocked by the cap. This is a storage bound, not abuse protection: registration needs a
+   * valid signature but pubkeys are free to generate — put per-IP rate limiting on the register
+   * route at the reverse proxy.
+   */
+  readonly maxUsers?: number;
+  /**
+   * Invoices status-checked per `settlePending` round, least-recently-checked first so a backlog
+   * rotates fairly instead of starving the tail. Default {@link DEFAULT_SETTLE_BATCH}.
+   */
+  readonly settleBatch?: number;
+  readonly zap?: LightningAddressZapConfig | undefined;
+  readonly now?: (() => number) | undefined;
+}): LightningAddressServer;
+//#endregion
+export type { LightningAddressInvoice, LightningAddressStore, LightningAddressUser };