@qntx/spark 0.1.1 → 0.2.1

package/README.md

@@ -27,6 +27,36 @@ is kept, and `withdrawals.unilateralExit` on that leaf reports the precise failu
 Key custody: private keys never leave the `SparkSigner` — the client only ever sees protocol
 values (public keys, signatures, ciphertexts).
 
+Outflow verification: `createSparkSigner` accepts an optional
+`authorize?: (outflow: SparkOutflow) => Promise<void>` gate. Before every signature that sends
+value out, the signer independently derives the outflow — it never trusts caller-supplied
+amounts or receivers. Authorization happens at two points, each backed by what the SO enforces:
+
+- `signFrost` checks every job before producing any share. A target spending a foreign input
+  (connector refund) is an `exit` candidate: the job must carry `exit: { connectorTx, exitTx }`,
+  the signer checks that the connector spends `exitTx` and matches the foreign input, and the
+  outflow reports the payout's `exitOutputs`. Every other output must be an ephemeral anchor, the
+  spent prevout's own script, the signer's identity, a pending transfer's recorded receiver, or
+  — for `leaf`/`static-deposit` keys only — the job's own key. A single-input target with any
+  other output is a `lightning` candidate carrying that output script (`lightningSendHtlcScript`
+  reproduces it for an invoice's payment hash); a multi-input one is rejected, as is a batch
+  mixing candidates. Candidates are authorized before any share is produced, since a signed
+  package can later be paired with any shares the signer issued.
+- `signIdentity` on `transfer-package` signs only when the package's `key_tweak_package` is
+  byte-equal to what `prepareTransfer` sealed this session and every leaf has a recorded refund
+  signature (the amount is the per-key maximum the SO verifies end-to-end). Receivers equal to
+  the bound SSP report `swap` — or nothing when `signFrost` already authorized every leaf (a
+  partially authorized SSP transfer is rejected); any other receiver reports `transfer` with
+  per-receiver totals.
+
+`signKeySpend`, `signHtlcTimeout` and the
+`static-deposit-refund`/`watchtower-recovery` statements report `onchain` outputs decoded from
+the transaction being signed plus `inputSats` (the spent prevout total, so callers derive the
+fee); `token-transaction` reports `token` outputs with u128 amounts as
+`bigint`. A throwing `authorize` aborts the signature; records stay for retry. Session records
+are bounded (4,096 signing keys, 256 prepared transfers, oldest evicted) and wiped on
+`dispose()`.
+
 Idempotent retries: `transfers.send`/`sendMany`, `lightning.pay` and
 `withdrawals.cooperativeExit` accept a `transferId` — reuse the same id to retry a call whose
 response may have committed; the same id with different terms fails rather than paying twice.

package/dist/{text-DC_Vptn6.mjs → bolt11-rfxnyLcb.mjs}

@@ -292,12 +292,4 @@ function isExpired(invoice, nowMs) {
 	return nowMs > (invoice.timestamp + invoice.expirySeconds) * 1e3;
 }
 //#endregion
-//#region src/core/text.ts
-const CONTROL = /[\u0000-\u001F\u007F-\u009F]/g;
-/** Server-supplied error text made safe to embed in an error message. */
-function serverErrorText(text) {
-	const cleaned = text.replace(CONTROL, "");
-	return cleaned.length <= 256 ? cleaned : `${cleaned.slice(0, 256)}\u2026`;
-}
-//#endregion
-export { decodeBolt11 as n, isExpired as r, serverErrorText as t };
+export { isExpired as n, decodeBolt11 as t };

package/dist/{index-B_g3vHnT.d.mts → index-DISbAuPB.d.mts}

@@ -1,10 +1,9 @@
 import { i as SparkOperatorConfig, n as SparkNetwork, o as Signature, r as SparkNetworkConfig } from "./lightning-address-CRULmi9v.mjs";
-import { g as SparkSigner } from "./types-jBCznYd6.mjs";
+import { v as SparkSigner } from "./transactions-DjTZU8ev.mjs";
 import "@bufbuild/protobuf/codegenv2";
 import "@bufbuild/protobuf/wkt";
 import { Message, UnknownEnum } from "@bufbuild/protobuf";
 import "@connectrpc/connect";
-import "@scure/btc-signer/utils.js";
 //#region src/connection/index.d.ts
 /**
  * A Spark protocol event delivered by the coordinator's `subscribe_to_events` stream. Plain types;

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { a as SparkTokenBroadcastError, i as SparkRequestError, n as SparkError, r as SparkInputError, t as SparkCryptoError } from "./index-D1fBaHTa.mjs";
 import { a as sparkNetworkConfig, i as SparkOperatorConfig, n as SparkNetwork, r as SparkNetworkConfig } from "./lightning-address-CRULmi9v.mjs";
 import { i as isExpired, n as Bolt11Network, r as decodeBolt11, t as Bolt11Invoice } from "./bolt11-DsNTTS_O.mjs";
-import { A as CooperativeExitStatus, C as exitTransactions, D as CooperativeExitQuote, E as createMemorySparkStore, F as UnusedDepositAddress, I as SparkLeaf, L as SparkEvent, M as StaticDepositClaim, N as StaticDepositRefund, O as CooperativeExitResult, P as StaticDepositUtxo, S as ExitTransaction, T as SparkStore, _ as LightningSendStatus, a as createSparkClient, b as LightningInvoice, c as buildCpfpChild, d as SparkTokenBalance, f as SparkTokenOutput, g as LightningSendOutcome, h as LightningReceiveStatus, i as SparkInvoiceStatus, j as MIN_STATIC_REFUND_FEE_SATS, k as CooperativeExitSpeed, l as SparkTransfer, m as SparkWalletSettings, n as SparkClient, o as StaticDepositClaimResult, p as SparkTokenOutputStatus, r as SparkClientOptions, s as FundingInput, t as ClaimPendingResult, u as SparkTransferLeaf, v as LightningSendStatusRequest, w as SparkExitChain, x as WatchtowerExitedLeaf, y as LightningPayment } from "./index-B_g3vHnT.mjs";
-import { g as SparkSigner } from "./types-jBCznYd6.mjs";
+import { A as CooperativeExitStatus, C as exitTransactions, D as CooperativeExitQuote, E as createMemorySparkStore, F as UnusedDepositAddress, I as SparkLeaf, L as SparkEvent, M as StaticDepositClaim, N as StaticDepositRefund, O as CooperativeExitResult, P as StaticDepositUtxo, S as ExitTransaction, T as SparkStore, _ as LightningSendStatus, a as createSparkClient, b as LightningInvoice, c as buildCpfpChild, d as SparkTokenBalance, f as SparkTokenOutput, g as LightningSendOutcome, h as LightningReceiveStatus, i as SparkInvoiceStatus, j as MIN_STATIC_REFUND_FEE_SATS, k as CooperativeExitSpeed, l as SparkTransfer, m as SparkWalletSettings, n as SparkClient, o as StaticDepositClaimResult, p as SparkTokenOutputStatus, r as SparkClientOptions, s as FundingInput, t as ClaimPendingResult, u as SparkTransferLeaf, v as LightningSendStatusRequest, w as SparkExitChain, x as WatchtowerExitedLeaf, y as LightningPayment } from "./index-DISbAuPB.mjs";
+import { n as EPHEMERAL_ANCHOR_SCRIPT, t as addressToScript, v as SparkSigner } from "./transactions-DjTZU8ev.mjs";
 //#region src/core/invoice.d.ts
 /** Payment carried by a Spark invoice: satoshis or BTKN tokens. */
 type SparkPayment = {
@@ -68,6 +68,14 @@ export declare function encodeTokenIdentifier(tokenIdentifier: Uint8Array, netwo
  */
 export declare function decodeTokenIdentifier(text: string): SparkTokenIdentifierData;
 //#endregion
+//#region src/core/uuid.d.ts
+/**
+ * UUIDv7 (RFC 9562 §5.7): 48-bit millisecond timestamp, then 74 random bits with the version (0111)
+ * and variant (10) fields applied. Randomness and the clock are injected so the function stays
+ * platform-neutral and deterministic under test.
+ */
+export declare function uuidv7(random: (length: number) => Uint8Array, now?: () => number): string;
+//#endregion
 //#region src/invoice/create.d.ts
 type InvoiceOptions = {
   readonly signer: SparkSigner;
@@ -112,4 +120,4 @@ export declare function parseSparkInvoice(text: string, options: {
   readonly now: number;
 }): ParsedSparkInvoice;
 //#endregion
-export { type Bolt11Invoice, type Bolt11Network, type ClaimPendingResult, type CooperativeExitQuote, type CooperativeExitResult, type CooperativeExitSpeed, type CooperativeExitStatus, type ExitTransaction, type FundingInput, type LightningInvoice, type LightningPayment, type LightningReceiveStatus, type LightningSendOutcome, type LightningSendStatus, type LightningSendStatusRequest, MIN_STATIC_REFUND_FEE_SATS, type ParsedSparkInvoice, type SparkAddress, type SparkClient, type SparkClientOptions, SparkCryptoError, SparkError, type SparkEvent, type SparkExitChain, SparkInputError, type SparkInvoiceFields, type SparkInvoiceStatus, type SparkLeaf, type SparkNetwork, type SparkNetworkConfig, type SparkOperatorConfig, type SparkPayment, SparkRequestError, type SparkStore, type SparkTokenBalance, SparkTokenBroadcastError, type SparkTokenIdentifierData, type SparkTokenOutput, type SparkTokenOutputStatus, type SparkTransfer, type SparkTransferLeaf, type SparkWalletSettings, type StaticDepositClaim, type StaticDepositClaimResult, type StaticDepositRefund, type StaticDepositUtxo, type UnusedDepositAddress, type WatchtowerExitedLeaf, buildCpfpChild, createMemorySparkStore, createSparkClient, decodeBolt11, exitTransactions, isExpired, sparkNetworkConfig };
+export { type Bolt11Invoice, type Bolt11Network, type ClaimPendingResult, type CooperativeExitQuote, type CooperativeExitResult, type CooperativeExitSpeed, type CooperativeExitStatus, EPHEMERAL_ANCHOR_SCRIPT, type ExitTransaction, type FundingInput, type LightningInvoice, type LightningPayment, type LightningReceiveStatus, type LightningSendOutcome, type LightningSendStatus, type LightningSendStatusRequest, MIN_STATIC_REFUND_FEE_SATS, type ParsedSparkInvoice, type SparkAddress, type SparkClient, type SparkClientOptions, SparkCryptoError, SparkError, type SparkEvent, type SparkExitChain, SparkInputError, type SparkInvoiceFields, type SparkInvoiceStatus, type SparkLeaf, type SparkNetwork, type SparkNetworkConfig, type SparkOperatorConfig, type SparkPayment, SparkRequestError, type SparkStore, type SparkTokenBalance, SparkTokenBroadcastError, type SparkTokenIdentifierData, type SparkTokenOutput, type SparkTokenOutputStatus, type SparkTransfer, type SparkTransferLeaf, type SparkWalletSettings, type StaticDepositClaim, type StaticDepositClaimResult, type StaticDepositRefund, type StaticDepositUtxo, type UnusedDepositAddress, type WatchtowerExitedLeaf, addressToScript, buildCpfpChild, createMemorySparkStore, createSparkClient, decodeBolt11, exitTransactions, isExpired, sparkNetworkConfig };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { a as SparkTokenBroadcastError, i as SparkRequestError, n as SparkError, r as SparkInputError, t as SparkCryptoError } from "./errors-5xLkExNL.mjs";
 import { $ as SparkAuthnService, A as EPHEMERAL_ANCHOR_SCRIPT, B as parseTransaction, Bt as TransferReceiverStatus, C as createInitialTimelockRefundTxs, Ct as InitiatePreimageSwapRequest_Reason, D as txId, Dt as RenewNodeTimelockSigningJobSchema, E as estimateVbytes, Et as Order, Ft as SparkAddressSchema, G as PartialTokenOutputSchema, Gt as SignatureScheme, Ht as TransferType, I as doesTxnNeedRenewed, It as SparkInvoiceFieldsSchema, J as SparkTokenService, K as PartialTokenTransactionSchema, L as getNextHTLCTransactionSequence, Lt as SparkService, M as computeTaprootKeyNoScript, N as p2trScriptFromPublicKey, Nt as SenderTransferPackageSchema, O as txIdInputBytes, Ot as RenewNodeZeroTimelockSigningJobSchema, P as xOnlyPublicKey, Pt as SigningJobSchema, Q as ChallengeSchema, R as getTimelockFromSequence, Rt as StartTransferRequestSchema, S as createInitialTimelockNodeTx, St as HashVariant, T as createZeroTimelockNodeTx, Tt as InvoiceStatus, U as CommitStatus, Ut as TreeNodeStatus, V as taprootKeySpendSighash, Vt as TransferStatus, W as InvoiceAttachmentSchema, Wt as UserSignedTxSigningJobSchema, X as TokenTransactionMetadataSchema, Y as TokenOutputStatus, Z as TokenTransactionStatus, _ as addressToScript, _t as AdaptorPublicKeyPackageSchema, a as proofOfPossessionDigest, at as uuidToBytes, b as createDecrementedTimelockNodeTx, bt as ClaimPackageSchema, d as LIGHTNING_HTLC_SEQUENCE, dt as assertU32, et as hashSparkInvoice, f as constructHtlcSenderSpend, ft as requireLength, g as lightningHtlcOutputScript, gt as sparkNetworkProto, h as finalizeHtlcSpend, ht as sparkNetworkFromProto, it as uuidFromBytes, j as btcNetwork, k as verifyFinalizedTaprootSignature, kt as RenewRefundTimelockSigningJobSchema, lt as assertCompressedKey, mt as sparkNetworkConfig, nt as protoInvoiceToPlain, o as sendLeafSigningDigest, ot as uuidv7, p as createRefundTxsForLightning, pt as u64ToSats, q as SignatureWithIndexSchema, rt as validateInvoiceFields, st as compareBytes, t as hashFinalTokenTransaction, tt as encodeInvoiceFields, ut as assertSats, v as createConnectorRefundTxs, w as createMultiInputRootTx, wt as InputSigningDataSchema, x as createDecrementedTimelockRefundTxs, xt as Direction, y as createCurrentTimelockRefundTxs, z as isZeroTimelock, zt as TransferPackageSchema } from "./token-DmojVTWi.mjs";
-import { n as decodeBolt11, r as isExpired, t as serverErrorText } from "./text-DC_Vptn6.mjs";
+import { n as isExpired, t as decodeBolt11 } from "./bolt11-rfxnyLcb.mjs";
+import { t as serverErrorText } from "./text-CDhN7qo4.mjs";
 import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
 import { timestampDate, timestampFromDate, timestampFromMs } from "@bufbuild/protobuf/wkt";
 import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
@@ -2413,7 +2414,8 @@ async function signUserJobs(signer, specs) {
 				verifyingKey: spec.verifyingKey,
 				commitment,
 				operatorCommitments: operatorCommitments(spec.commitments),
-				...spec.adaptorPublicKey === void 0 ? {} : { adaptorPublicKey: spec.adaptorPublicKey }
+				...spec.adaptorPublicKey === void 0 ? {} : { adaptorPublicKey: spec.adaptorPublicKey },
+				...spec.exit === void 0 ? {} : { exit: spec.exit }
 			};
 		}));
 		if (shares.length !== chunk.length) throw new SparkError("signUserJobs: signer returned fewer shares than requested");
@@ -3917,7 +3919,7 @@ function refundJobGroups(leaves, buildRefunds, signingCommitments, context) {
 	const directFromCpfp = [];
 	for (const [i, entry] of leaves.entries()) {
 		const nodeOutput = prevout(entry.leaf.nodeTx, 0, `${context} leaf ${entry.leaf.id} node tx`);
-		const { refunds, extraPrevout } = buildRefunds(entry, refundTxSequence(entry.refundTx, context));
+		const { refunds, extraPrevout, exit } = buildRefunds(entry, refundTxSequence(entry.refundTx, context));
 		const commitments = signingCommitments[i];
 		const directCommitment = signingCommitments[count + i];
 		const directFromCpfpCommitment = signingCommitments[2 * count + i];
@@ -3935,7 +3937,8 @@ function refundJobGroups(leaves, buildRefunds, signingCommitments, context) {
 				inputIndex: 0,
 				prevouts: extraPrevout === void 0 ? [nodeOutput] : [nodeOutput, extraPrevout]
 			},
-			commitments
+			commitments,
+			...exit === void 0 ? {} : { exit }
 		});
 		if (refunds.directRefund !== void 0) {
 			const directOutput = prevout(entry.leaf.directTx ?? /* @__PURE__ */ new Uint8Array(), 0, `${context} leaf ${entry.leaf.id} direct node tx`);
@@ -3952,7 +3955,8 @@ function refundJobGroups(leaves, buildRefunds, signingCommitments, context) {
 					inputIndex: 0,
 					prevouts: extraPrevout === void 0 ? [directOutput] : [directOutput, extraPrevout]
 				},
-				commitments: directCommitment
+				commitments: directCommitment,
+				...exit === void 0 ? {} : { exit }
 			});
 		}
 		directFromCpfp.push({
@@ -3968,7 +3972,8 @@ function refundJobGroups(leaves, buildRefunds, signingCommitments, context) {
 				inputIndex: 0,
 				prevouts: extraPrevout === void 0 ? [nodeOutput] : [nodeOutput, extraPrevout]
 			},
-			commitments: directFromCpfpCommitment
+			commitments: directFromCpfpCommitment,
+			...exit === void 0 ? {} : { exit }
 		});
 	}
 	return {
@@ -6824,7 +6829,11 @@ async function cooperativeExit(deps, options) {
 						directFromCpfpRefund: job(txs.directFromCpfpRefundTx, nodePrevout),
 						directRefund: txs.directRefundTx === void 0 || entry.leaf.directTx === void 0 ? void 0 : job(txs.directRefundTx, prevout0(entry.leaf.directTx, `leaf ${entry.leaf.id} direct node tx`))
 					},
-					extraPrevout: connectorPrevout
+					extraPrevout: connectorPrevout,
+					exit: {
+						connectorTx: request.rawConnectorTransaction,
+						exitTx: request.rawCoopExitTransaction
+					}
 				};
 			}
 		});
@@ -7319,4 +7328,4 @@ function createMemorySparkStore() {
 	};
 }
 //#endregion
-export { MIN_STATIC_REFUND_FEE_SATS, SparkCryptoError, SparkError, SparkInputError, SparkRequestError, SparkTokenBroadcastError, buildCpfpChild, createMemorySparkStore, createSatsInvoice, createSparkClient, createTokensInvoice, decodeBolt11, decodeSparkAddress, decodeTokenIdentifier, encodeSparkAddress, encodeTokenIdentifier, exitTransactions, isExpired, parseSparkInvoice, sparkNetworkConfig, verifySparkAddressSignature };
+export { EPHEMERAL_ANCHOR_SCRIPT, MIN_STATIC_REFUND_FEE_SATS, SparkCryptoError, SparkError, SparkInputError, SparkRequestError, SparkTokenBroadcastError, addressToScript, buildCpfpChild, createMemorySparkStore, createSatsInvoice, createSparkClient, createTokensInvoice, decodeBolt11, decodeSparkAddress, decodeTokenIdentifier, encodeSparkAddress, encodeTokenIdentifier, exitTransactions, isExpired, parseSparkInvoice, sparkNetworkConfig, uuidv7, verifySparkAddressSignature };

package/dist/{lnurl-kcdXU75g.mjs → lnurl-BhEGaRok.mjs}

@@ -1,5 +1,6 @@
 import { i as SparkRequestError, r as SparkInputError } from "./errors-5xLkExNL.mjs";
-import { n as decodeBolt11, t as serverErrorText } from "./text-DC_Vptn6.mjs";
+import { t as decodeBolt11 } from "./bolt11-rfxnyLcb.mjs";
+import { t as serverErrorText } from "./text-CDhN7qo4.mjs";
 import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
 import { base64, bech32 } from "@scure/base";
 import { sha256 } from "@noble/hashes/sha2.js";

package/dist/lnurl.mjs

@@ -1 +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";
+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-BhEGaRok.mjs";

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { n as SparkClient } from "./index-B_g3vHnT.mjs";
+import { n as SparkClient } from "./index-DISbAuPB.mjs";
 //#region src/server/store.d.ts
 type LightningAddressUser = {
   /** Lowercase LUD-16 local-part. */

package/dist/server.mjs

@@ -1,7 +1,7 @@
 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 { t as serverErrorText } from "./text-CDhN7qo4.mjs";
+import { m as encodeLnurl, v as isJsonObject } from "./lnurl-BhEGaRok.mjs";
 import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { sha256 } from "@noble/hashes/sha2.js";

package/dist/signer.d.mts

@@ -1,7 +1,71 @@
 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 { a as sparkNetworkConfig, n as SparkNetwork } from "./lightning-address-CRULmi9v.mjs";
+import { r as decodeBolt11 } from "./bolt11-DsNTTS_O.mjs";
+import { _ as SparkOperator, a as HtlcTimeoutSignRequest, b as SigningTarget, c as PrepareClaimRequest, d as PreparedLightningReceive, f as PreparedTransfer, g as SparkLeafKey, h as SparkKey, i as FrostSignJob, l as PrepareTransferRequest, m as SigningCommitment, n as EPHEMERAL_ANCHOR_SCRIPT, o as IdentityStatement, p as PreparedTransferLeaf, r as FrostAggregateJob, s as OperatorCommitment, t as addressToScript, u as PreparedClaim, v as SparkSigner, y as StaticDepositClaimRequest } from "./transactions-DjTZU8ev.mjs";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
+//#region src/signer/outflow.d.ts
+/** What an authorized signature sends out, derived inside the signer (never caller-supplied). */
+type SparkOutflow = {
+  readonly kind: "transfer";
+  readonly transferId: string;
+  readonly totalSats: number;
+  readonly receivers: ReadonlyArray<{
+    readonly identityPublicKey: Uint8Array;
+    readonly amountSats: number;
+  }>;
+} | {
+  readonly kind: "lightning";
+  readonly htlcOutputScript: Uint8Array;
+  readonly totalSats: number;
+  readonly leaves: ReadonlyArray<{
+    readonly publicKey: Uint8Array;
+    readonly amountSats: number;
+  }>;
+} | {
+  readonly kind: "exit";
+  readonly connectorTxid: Uint8Array;
+  readonly totalSats: number;
+  readonly leaves: ReadonlyArray<{
+    readonly publicKey: Uint8Array;
+    readonly amountSats: number;
+  }>;
+  /** Every output of the SSP-provided coop-exit payout transaction. */
+  readonly exitOutputs: ReadonlyArray<{
+    readonly script: Uint8Array;
+    readonly amountSats: number;
+  }>;
+} | {
+  readonly kind: "swap";
+  readonly transferId: string;
+  readonly totalSats: number;
+} | {
+  readonly kind: "onchain";
+  readonly source: "static-deposit-refund" | "watchtower-recovery" | "htlc-timeout" | "key-spend";
+  readonly totalSats: number;
+  readonly inputSats: number;
+  readonly outputs: ReadonlyArray<{
+    readonly script: Uint8Array;
+    readonly amountSats: number;
+  }>;
+} | {
+  readonly kind: "token";
+  readonly outputs: ReadonlyArray<{
+    readonly tokenIdentifier: Uint8Array;
+    readonly ownerPublicKey: Uint8Array;
+    readonly amount: bigint;
+  }>;
+};
+/**
+ * The output-0 script of a lightning send's HTLC refund: hash lock to the SSP, sequence lock to the
+ * sender identity — the same script `createRefundTxsForLightning` commits to.
+ */
+export declare function lightningSendHtlcScript(options: {
+  readonly paymentHash: Uint8Array;
+  readonly sspIdentityPublicKey: Uint8Array;
+  readonly identityPublicKey: Uint8Array;
+}): Uint8Array;
+type AuthorizeOutflow = (outflow: SparkOutflow) => Promise<void>;
+//#endregion
 //#region src/signer/keys.d.ts
 /**
  * The 64-byte extended private key (private key ‖ chain code) at `m/8797555'/account'` — the input
@@ -36,6 +100,12 @@ export declare function createSparkSigner(options: {
   readonly threshold?: number;
   /** SSP identity the static-deposit secret is sealed to; defaults to the network's SSP key. */
   readonly sspIdentityPublicKey?: Uint8Array;
+  /**
+   * Optional gate invoked with the signer-derived {@link SparkOutflow} before every signature that
+   * sends value out (transfer packages, onchain spends, token transactions). Throwing aborts the
+   * signature; the records stay so a later authorize can be retried.
+   */
+  readonly authorize?: AuthorizeOutflow;
 }): SparkSigner;
 //#endregion
 //#region src/signer/lnurl-auth.d.ts
@@ -69,4 +139,4 @@ 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 };
+export { type AuthorizeOutflow, EPHEMERAL_ANCHOR_SCRIPT, type FrostAggregateJob, type FrostSignJob, type HtlcTimeoutSignRequest, type IdentityStatement, type LnurlAuthSigner, type OperatorCommitment, type PrepareClaimRequest, type PrepareTransferRequest, type PreparedClaim, type PreparedLightningReceive, type PreparedTransfer, type PreparedTransferLeaf, type SigningCommitment, type SigningTarget, type SparkKey, type SparkLeafKey, type SparkNetwork, type SparkOperator, type SparkOutflow, type SparkSigner, type StaticDepositClaimRequest, addressToScript, decodeBolt11, sparkNetworkConfig };

package/dist/signer.mjs

@@ -1,5 +1,6 @@
 import { n as SparkError, r as SparkInputError, t as SparkCryptoError } from "./errors-5xLkExNL.mjs";
-import { At as SecretShareSchema, B as parseTransaction, F as checkIfValidSequence, H as taprootScriptSpendSighash, It as SparkInvoiceFieldsSchema, K as PartialTokenTransactionSchema, Mt as SendLeafKeyTweaksSchema, Q as ChallengeSchema, R as getTimelockFromSequence, V as taprootKeySpendSighash, bt as ClaimPackageSchema, c as staticDepositStatementDigest, ct as uint64be, d as LIGHTNING_HTLC_SEQUENCE, et as hashSparkInvoice, ft as requireLength, g as lightningHtlcOutputScript, i as claimPackageDigest, jt as SendLeafKeyTweakSchema, l as transferPackageDigest, m as createSequenceLockScript, mt as sparkNetworkConfig, n as hashPartialTokenTransaction, nt as protoInvoiceToPlain, o as sendLeafSigningDigest, r as authnChallengeDigest, s as sspChallengeDigest, u as watchtowerRecoveryStatementDigest, vt as ClaimLeafKeyTweakSchema, yt as ClaimLeafKeyTweaksSchema, zt as TransferPackageSchema } from "./token-DmojVTWi.mjs";
+import { A as EPHEMERAL_ANCHOR_SCRIPT, At as SecretShareSchema, B as parseTransaction, F as checkIfValidSequence, H as taprootScriptSpendSighash, It as SparkInvoiceFieldsSchema, K as PartialTokenTransactionSchema, Mt as SendLeafKeyTweaksSchema, N as p2trScriptFromPublicKey, O as txIdInputBytes, Q as ChallengeSchema, R as getTimelockFromSequence, V as taprootKeySpendSighash, _ as addressToScript, bt as ClaimPackageSchema, c as staticDepositStatementDigest, ct as uint64be, d as LIGHTNING_HTLC_SEQUENCE, et as hashSparkInvoice, ft as requireLength, g as lightningHtlcOutputScript, i as claimPackageDigest, jt as SendLeafKeyTweakSchema, l as transferPackageDigest, m as createSequenceLockScript, mt as sparkNetworkConfig, n as hashPartialTokenTransaction, nt as protoInvoiceToPlain, o as sendLeafSigningDigest, r as authnChallengeDigest, s as sspChallengeDigest, u as watchtowerRecoveryStatementDigest, vt as ClaimLeafKeyTweakSchema, yt as ClaimLeafKeyTweaksSchema, zt as TransferPackageSchema } from "./token-DmojVTWi.mjs";
+import { t as decodeBolt11 } from "./bolt11-rfxnyLcb.mjs";
 import { i as lightningAddressMessageDigest, r as lightningAddressMessage } from "./lightning-address-CZrb8x4p.mjs";
 import "./crypto.mjs";
 import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
@@ -7,6 +8,7 @@ import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
 import { schnorr, secp256k1 } from "@noble/curves/secp256k1.js";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToNumberBE } from "@noble/curves/utils.js";
 import { taprootTweakPrivKey } from "@scure/btc-signer/utils.js";
 import { HDKey } from "@scure/bip32";
 import { hmac } from "@noble/hashes/hmac.js";
@@ -434,6 +436,347 @@ function createNonceStore(crypto, accountPrivate, random) {
 	};
 }
 //#endregion
+//#region src/signer/outflow.ts
+/**
+* Signer-side outflow derivation: the signer independently computes what an authorized signature
+* sends out, without trusting the caller. Authorization happens at two points, each backed by what
+* the SO enforces:
+*
+* - `signFrost` per-job whitelist: a multi-input target whose inputs spend a foreign prevout script
+*   is a connector (cooperative-exit) candidate — its outputs are not checked (they pay the SSP),
+*   the job must carry the SSP's `{connectorTx, exitTx}` pair, the pair's txid must match the
+*   foreign input, connectorTx input 0 must spend exitTx, and every exit job in the batch must
+*   carry the same pair. Otherwise every output must be whitelisted: an ephemeral anchor, the spent
+*   prevout's own script (intra-tree node transactions), a P2TR to the signer's own identity, a
+*   P2TR to a pending prepared transfer's recorded receiver for that leaf, or — for
+*   `leaf`/`static-deposit` keys only — a P2TR to the job's own signing key. A single-input target
+*   outside the whitelist is a lightning (HTLC) candidate; a multi-input same-script target outside
+*   it fails. Exit and lightning candidates are authorized BEFORE any share is produced — the same
+*   signed package can be paired with any shares the signer ever issued, so HTLC/connector shares
+*   must never be issuable unchecked; a batch mixing the two kinds, or carrying more than one HTLC
+*   script or connector txid, is rejected outright.
+* - `signIdentity({kind:"transfer-package"})`: the package's `key_tweak_package` must be byte-equal
+*   to this session's recorded `prepareTransfer`, every leaf needs a recorded refund signature
+*   (amount = per-pubkey max prevout), and the receivers decide `transfer`/`swap` — or no further
+*   authorization when a `signFrost` service authorization already covered the leaves (all
+*   receivers the bound SSP).
+*
+* Non-package outflows (onchain spends with `inputSats` for fee derivation, token transactions) are
+* decoded from the transaction being signed. `authorize` runs before every outflow signature; a
+* throw aborts it without consuming commitments.
+*
+* Upstream reference: sdks/js/packages/spark-sdk signer.ts / services/transfer.ts and
+* so/handler/transfer_package_validation.go — buildonspark/spark@0b3a32a.
+*/
+/**
+* The output-0 script of a lightning send's HTLC refund: hash lock to the SSP, sequence lock to the
+* sender identity — the same script `createRefundTxsForLightning` commits to.
+*/
+function lightningSendHtlcScript(options) {
+	return lightningHtlcOutputScript(options.paymentHash, options.sspIdentityPublicKey, options.identityPublicKey);
+}
+const MAX_SIGNING_KEYS = 4096;
+const MAX_TRANSFERS = 256;
+const eq = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+function outputScripts(tx) {
+	const scripts = [];
+	for (let i = 0; i < tx.outputsLength; i++) {
+		const output = tx.getOutput(i);
+		if (output.script === void 0) throw new SparkInputError("transaction: output carries no script");
+		scripts.push(output.script);
+	}
+	return scripts;
+}
+/**
+* `onchain` outflow decoded from the transaction being signed; `inputSats` = the spent prevout
+* amounts (one per input) so the consumer can derive the fee.
+*/
+function onchainOutflow(source, target) {
+	const tx = parseTransaction(target.transaction);
+	if (target.prevouts.length !== tx.inputsLength) throw new SparkInputError("transaction: prevouts must contain one entry per input to account the spend");
+	const outputs = [];
+	for (let i = 0; i < tx.outputsLength; i++) {
+		const output = tx.getOutput(i);
+		if (output.script === void 0 || output.amount === void 0) throw new SparkInputError("transaction: output carries no script or amount");
+		outputs.push({
+			script: output.script,
+			amountSats: Number(output.amount)
+		});
+	}
+	return {
+		kind: "onchain",
+		source,
+		outputs,
+		inputSats: target.prevouts.reduce((sum, p) => sum + p.amount, 0),
+		totalSats: outputs.reduce((sum, o) => sum + o.amountSats, 0)
+	};
+}
+/** `token` outflow decoded from a PartialTokenTransaction: owner, identifier, u128 amount. */
+function tokenOutflow(partialTransaction) {
+	let partial;
+	try {
+		partial = fromBinary(PartialTokenTransactionSchema, partialTransaction);
+	} catch (error) {
+		throw new SparkInputError("token transaction: failed to decode protobuf", { cause: error });
+	}
+	return {
+		kind: "token",
+		outputs: partial.partialTokenOutputs.map((output) => ({
+			tokenIdentifier: output.tokenIdentifier,
+			ownerPublicKey: output.ownerPublicKey,
+			amount: bytesToNumberBE(output.tokenAmount)
+		}))
+	};
+}
+function createOutflowTracker(sspIdentityPublicKey, network, identityPublicKey) {
+	const signs = /* @__PURE__ */ new Map();
+	const transfers = /* @__PURE__ */ new Map();
+	const leafReceivers = /* @__PURE__ */ new Map();
+	const receiverScripts = /* @__PURE__ */ new Map();
+	const serviceAuthorized = /* @__PURE__ */ new Set();
+	const identityScript = p2trScriptFromPublicKey(identityPublicKey, network);
+	const evaluateJobs = (jobs) => {
+		const exits = /* @__PURE__ */ new Map();
+		const lightnings = /* @__PURE__ */ new Map();
+		let batchExit;
+		const leaves = /* @__PURE__ */ new Map();
+		for (const job of jobs) {
+			const prevout = job.target.prevouts[job.target.inputIndex];
+			if (prevout === void 0) throw new SparkInputError("signFrost: inputIndex out of range for prevouts");
+			const tx = parseTransaction(job.target.transaction);
+			const key = bytesToHex(job.publicKey);
+			if (tx.inputsLength > 1) {
+				const foreign = /* @__PURE__ */ new Map();
+				for (let i = 0; i < tx.inputsLength; i++) {
+					const otherPrevout = job.target.prevouts[i];
+					if (otherPrevout === void 0) throw new SparkInputError("signFrost: prevouts must cover every input");
+					if (!eq(otherPrevout.script, prevout.script)) {
+						const { txid } = tx.getInput(i);
+						if (txid === void 0) throw new SparkInputError("signFrost: foreign input carries no prevout txid");
+						foreign.set(bytesToHex(txid), txid);
+					}
+				}
+				if (foreign.size > 0) {
+					if (foreign.size !== 1) throw new SparkInputError("signFrost: foreign inputs carry more than one connector txid");
+					const txid = foreign.values().next().value;
+					if (txid === void 0) throw new SparkInputError("signFrost: malformed input set");
+					if (job.exit === void 0) throw new SparkInputError("signFrost: connector refund job missing its connector/exit transaction pair");
+					const connectorTx = parseTransaction(job.exit.connectorTx);
+					if (!eq(txIdInputBytes(job.exit.connectorTx), txid)) throw new SparkInputError("signFrost: connectorTx txid does not match the foreign input");
+					const parentTxid = connectorTx.getInput(0).txid;
+					if (parentTxid === void 0) throw new SparkInputError("signFrost: connectorTx has no input 0 txid");
+					if (!eq(parentTxid, txIdInputBytes(job.exit.exitTx))) throw new SparkInputError("signFrost: connectorTx input 0 does not spend exitTx");
+					if (batchExit === void 0) batchExit = job.exit;
+					else if (!eq(batchExit.connectorTx, job.exit.connectorTx) || !eq(batchExit.exitTx, job.exit.exitTx)) throw new SparkInputError("signFrost: exit jobs in one batch carry different transaction pairs");
+					const entry = leaves.get(key) ?? {
+						publicKey: job.publicKey,
+						amountSats: 0
+					};
+					entry.amountSats = Math.max(entry.amountSats, prevout.amount);
+					leaves.set(key, entry);
+					exits.set(bytesToHex(txid), txid);
+					continue;
+				}
+			}
+			const allowedReceivers = leafReceivers.get(key);
+			const violations = outputScripts(tx).filter((script) => {
+				if (eq(script, EPHEMERAL_ANCHOR_SCRIPT) || eq(script, prevout.script)) return false;
+				if (eq(script, identityScript)) return false;
+				if ((job.key.type === "leaf" || job.key.type === "static-deposit") && eq(script, p2trScriptFromPublicKey(job.publicKey, network))) return false;
+				if (allowedReceivers !== void 0) for (const receiver of allowedReceivers.keys()) {
+					const accepted = receiverScripts.get(receiver);
+					if (accepted !== void 0 && eq(script, accepted)) return false;
+				}
+				return true;
+			});
+			if (violations.length === 0) {
+				if (job.exit !== void 0) throw new SparkInputError("signFrost: connector/exit pair on a non-exit job");
+				continue;
+			}
+			if (job.exit !== void 0) throw new SparkInputError("signFrost: connector/exit pair on a non-exit job");
+			const entry = leaves.get(key) ?? {
+				publicKey: job.publicKey,
+				amountSats: 0
+			};
+			entry.amountSats = Math.max(entry.amountSats, prevout.amount);
+			leaves.set(key, entry);
+			if (tx.inputsLength === 1) {
+				const distinct = /* @__PURE__ */ new Map();
+				for (const script of violations) distinct.set(bytesToHex(script), script);
+				if (distinct.size !== 1) throw new SparkInputError("signFrost: job carries multiple non-whitelisted outputs");
+				const script = distinct.values().next().value;
+				if (script === void 0) throw new SparkInputError("signFrost: malformed output set");
+				lightnings.set(bytesToHex(script), script);
+			} else throw new SparkInputError(`signFrost: non-whitelisted output on a ${tx.inputsLength}-input transaction`);
+		}
+		if (exits.size > 0 && lightnings.size > 0) throw new SparkInputError("signFrost: batch mixes connector and HTLC refunds");
+		const leafList = [...leaves.values()];
+		const totalSats = leafList.reduce((sum, l) => sum + l.amountSats, 0);
+		if (exits.size > 1 || lightnings.size > 1) throw new SparkInputError("signFrost: inconsistent connector txids or HTLC scripts in one batch");
+		const connectorTxid = exits.values().next().value;
+		if (connectorTxid !== void 0) {
+			if (batchExit === void 0) throw new SparkInputError("signFrost: exit candidates without their transaction pair");
+			const exitTx = parseTransaction(batchExit.exitTx);
+			const exitOutputs = [];
+			for (let i = 0; i < exitTx.outputsLength; i++) {
+				const output = exitTx.getOutput(i);
+				if (output.script === void 0 || output.amount === void 0) throw new SparkInputError("signFrost: exitTx output carries no script or amount");
+				exitOutputs.push({
+					script: output.script,
+					amountSats: Number(output.amount)
+				});
+			}
+			return {
+				kind: "exit",
+				connectorTxid,
+				leaves: leafList,
+				totalSats,
+				exitOutputs
+			};
+		}
+		const htlcOutputScript = lightnings.values().next().value;
+		if (htlcOutputScript !== void 0) return {
+			kind: "lightning",
+			htlcOutputScript,
+			leaves: leafList,
+			totalSats
+		};
+	};
+	const recordSign = (signingPublicKey, target) => {
+		const prevout = target.prevouts[target.inputIndex];
+		if (prevout === void 0) throw new SparkInputError("signFrost: inputIndex out of range for prevouts");
+		const key = bytesToHex(signingPublicKey);
+		let record = signs.get(key);
+		if (record === void 0) {
+			if (signs.size >= MAX_SIGNING_KEYS) {
+				const oldest = signs.keys().next().value;
+				if (oldest !== void 0) signs.delete(oldest);
+			}
+			record = { maxAmount: 0 };
+			signs.set(key, record);
+		}
+		if (prevout.amount > record.maxAmount) record.maxAmount = prevout.amount;
+	};
+	const recordPrepare = (transferId, leaves, operatorPackages) => {
+		if (!transfers.has(transferId) && transfers.size >= MAX_TRANSFERS) {
+			const oldest = transfers.keys().next().value;
+			if (oldest !== void 0) transfers.delete(oldest);
+		}
+		for (const leaf of leaves) {
+			const pk = bytesToHex(leaf.publicKey);
+			let receivers = leafReceivers.get(pk);
+			if (receivers === void 0) {
+				receivers = /* @__PURE__ */ new Map();
+				leafReceivers.set(pk, receivers);
+			}
+			const receiver = bytesToHex(leaf.receiverIdentityPublicKey);
+			receivers.set(receiver, (receivers.get(receiver) ?? 0) + 1);
+			receiverScripts.set(receiver, p2trScriptFromPublicKey(leaf.receiverIdentityPublicKey, network));
+		}
+		transfers.set(transferId, {
+			leaves: leaves.map((leaf) => ({
+				...leaf,
+				key: { ...leaf.key },
+				publicKey: new Uint8Array(leaf.publicKey),
+				receiverIdentityPublicKey: new Uint8Array(leaf.receiverIdentityPublicKey)
+			})),
+			operatorPackages: Object.fromEntries(Object.entries(operatorPackages).map(([id, pkg]) => [id, new Uint8Array(pkg)]))
+		});
+	};
+	const packageOutflow = (transferId, packageBytes) => {
+		const prepared = transfers.get(transferId);
+		if (prepared === void 0) throw new SparkInputError("transfer package: no recorded prepareTransfer for this transferId");
+		const keyTweakPackage = (() => {
+			try {
+				return fromBinary(TransferPackageSchema, packageBytes).keyTweakPackage;
+			} catch (error) {
+				throw new SparkInputError("transfer package: failed to decode protobuf", { cause: error });
+			}
+		})();
+		const expected = Object.keys(prepared.operatorPackages).sort();
+		const actual = Object.keys(keyTweakPackage).sort();
+		if (expected.length !== actual.length || !expected.every((id, i) => id === actual[i]) || !expected.every((id) => {
+			const value = keyTweakPackage[id];
+			const recorded = prepared.operatorPackages[id];
+			return value !== void 0 && recorded !== void 0 && eq(recorded, value);
+		})) throw new SparkInputError("transfer package: key_tweak_package does not match the recorded operator packages");
+		const leafAmounts = prepared.leaves.map((leaf) => {
+			const record = signs.get(bytesToHex(leaf.publicKey));
+			if (record === void 0) throw new SparkInputError(`transfer package: no recorded refund signature for leaf ${leaf.leafId}`);
+			return record.maxAmount;
+		});
+		const totalSats = leafAmounts.reduce((sum, amount) => sum + amount, 0);
+		const sspCount = prepared.leaves.map((leaf) => eq(leaf.receiverIdentityPublicKey, sspIdentityPublicKey)).filter(Boolean).length;
+		if (sspCount > 0 && sspCount !== prepared.leaves.length) throw new SparkInputError("transfer package: SSP and non-SSP receivers in one transfer");
+		if (sspCount > 0) {
+			const authorized = prepared.leaves.filter((leaf) => serviceAuthorized.has(bytesToHex(leaf.publicKey))).length;
+			if (authorized === prepared.leaves.length) return;
+			if (authorized !== 0) throw new SparkInputError("transfer package: SSP transfer mixes service-authorized and unauthorized leaves");
+			return {
+				kind: "swap",
+				transferId,
+				totalSats
+			};
+		}
+		const receivers = /* @__PURE__ */ new Map();
+		for (const [i, leaf] of prepared.leaves.entries()) {
+			const key = bytesToHex(leaf.receiverIdentityPublicKey);
+			const amount = leafAmounts[i];
+			if (amount === void 0) throw new SparkInputError("transfer package: leaf amount out of range");
+			const entry = receivers.get(key);
+			if (entry === void 0) receivers.set(key, {
+				identityPublicKey: leaf.receiverIdentityPublicKey,
+				amountSats: amount
+			});
+			else entry.amountSats += amount;
+		}
+		return {
+			kind: "transfer",
+			transferId,
+			totalSats,
+			receivers: [...receivers.values()]
+		};
+	};
+	const drop = (transferId) => {
+		const prepared = transfers.get(transferId);
+		if (prepared !== void 0) {
+			for (const leaf of prepared.leaves) {
+				const pk = bytesToHex(leaf.publicKey);
+				const receivers = leafReceivers.get(pk);
+				const receiver = bytesToHex(leaf.receiverIdentityPublicKey);
+				if (receivers !== void 0) {
+					const count = receivers.get(receiver);
+					if (count !== void 0) {
+						if (count > 1) receivers.set(receiver, count - 1);
+						else {
+							receivers.delete(receiver);
+							if (receivers.size === 0) leafReceivers.delete(pk);
+						}
+					}
+				}
+			}
+			transfers.delete(transferId);
+		}
+	};
+	return {
+		evaluateJobs,
+		markServiceAuthorized: (publicKeys) => {
+			for (const pk of publicKeys) serviceAuthorized.add(bytesToHex(pk));
+		},
+		recordSign,
+		recordPrepare,
+		packageOutflow,
+		drop,
+		wipe: () => {
+			signs.clear();
+			transfers.clear();
+			leafReceivers.clear();
+			serviceAuthorized.clear();
+			receiverScripts.clear();
+		}
+	};
+}
+//#endregion
 //#region src/signer/statements.ts
 /**
 * Computes the digest for a statement from its complete protocol content, plus the signature format
@@ -757,6 +1100,17 @@ function createSparkSigner(options) {
 	}
 	const keys = openKeys(options.accountKey, crypto);
 	const nonces = createNonceStore(crypto, keys.accountPrivate, random);
+	const outflow = createOutflowTracker(sspIdentityPublicKey, network, keys.identityPublicKey);
+	const { authorize } = options;
+	/** The signing public key for any key descriptor — resolved here, private copy wiped. */
+	const publicKeyOf = (key) => {
+		const secretKey = keys.resolve(key);
+		try {
+			return secp256k1.getPublicKey(secretKey, true);
+		} finally {
+			secretKey.fill(0);
+		}
+	};
 	const statements = {
 		identityPoint: keys.identityPoint,
 		identityPublicKey: keys.identityPublicKey,
@@ -805,7 +1159,26 @@ function createSparkSigner(options) {
 		ensureAlive();
 		await ready;
 		ensureAlive();
-		return frostSignJobs(crypto, jobs, keys, nonces);
+		const publicKeys = jobs.map((job) => publicKeyOf(job.key));
+		const batchOutflow = outflow.evaluateJobs(jobs.map((job, i) => {
+			const publicKey = publicKeys[i];
+			if (publicKey === void 0) throw new SparkError("signFrost: public key resolution out of range");
+			return {
+				key: job.key,
+				publicKey,
+				target: job.target,
+				...job.exit === void 0 ? {} : { exit: job.exit }
+			};
+		}));
+		if (batchOutflow !== void 0) await authorize?.(batchOutflow);
+		const shares = frostSignJobs(crypto, jobs, keys, nonces);
+		for (const [i, job] of jobs.entries()) {
+			const publicKey = publicKeys[i];
+			if (publicKey === void 0) throw new SparkError("signFrost: public key resolution out of range");
+			outflow.recordSign(publicKey, job.target);
+		}
+		if (batchOutflow !== void 0) outflow.markServiceAuthorized(batchOutflow.leaves.map((leaf) => leaf.publicKey));
+		return shares;
 	};
 	const aggregateFrost = async (jobs) => {
 		ensureAlive();
@@ -817,13 +1190,24 @@ function createSparkSigner(options) {
 		ensureAlive();
 		await ready;
 		ensureAlive();
+		if (statement.kind === "transfer-package") {
+			const transferOutflow = outflow.packageOutflow(statement.transferId, statement.package);
+			if (transferOutflow !== void 0) await authorize?.(transferOutflow);
+			const { digest, format } = statementDigest(statement, statements);
+			const signature = signDigest(digest, format, keys.identityPrivateKey, random);
+			outflow.drop(statement.transferId);
+			return signature;
+		}
 		const { digest, format } = statementDigest(statement, statements);
+		if (statement.kind === "static-deposit-refund" || statement.kind === "watchtower-recovery") await authorize?.(onchainOutflow(statement.kind, statement.target));
+		else if (statement.kind === "token-transaction") await authorize?.(tokenOutflow(statement.partialTransaction));
 		return signDigest(digest, format, keys.identityPrivateKey, random);
 	};
 	const signKeySpend = async (key, target) => {
 		ensureAlive();
 		await ready;
 		ensureAlive();
+		await authorize?.(onchainOutflow("key-spend", target));
 		const secretKey = keys.resolve(key);
 		let tweaked;
 		try {
@@ -838,6 +1222,14 @@ function createSparkSigner(options) {
 		ensureAlive();
 		await ready;
 		ensureAlive();
+		await authorize?.(onchainOutflow("htlc-timeout", {
+			transaction: request.transaction,
+			inputIndex: request.inputIndex,
+			prevouts: [{
+				script: lightningHtlcOutputScript(request.paymentHash, request.hashLockPublicKey, keys.identityPublicKey),
+				amount: request.prevoutAmountSats
+			}]
+		}));
 		const tx = parseTransaction(request.transaction);
 		if (tx.inputsLength !== 1 || request.inputIndex !== 0) throw new SparkInputError("htlc timeout: only the single-input sender sweep is supported");
 		const { sequence } = tx.getInput(0);
@@ -858,7 +1250,17 @@ function createSparkSigner(options) {
 		ensureAlive();
 		await ready;
 		ensureAlive();
-		return prepareTransferPackage(request, packages);
+		const prepared = prepareTransferPackage(request, packages);
+		const leafPublicKeys = keys.publicKeys(request.leaves.map((leaf) => leaf.key));
+		outflow.recordPrepare(request.transferId, request.leaves.map((leaf, i) => {
+			const publicKey = leafPublicKeys[i];
+			if (publicKey === void 0) throw new SparkError("prepareTransfer: public key resolution out of range");
+			return {
+				...leaf,
+				publicKey
+			};
+		}), prepared.operatorPackages);
+		return prepared;
 	};
 	const prepareClaim = async (request) => {
 		ensureAlive();
@@ -883,6 +1285,7 @@ function createSparkSigner(options) {
 		disposed = true;
 		nonces.wipe();
 		keys.wipe();
+		outflow.wipe();
 	};
 	return {
 		identityPublicKey,
@@ -1021,4 +1424,4 @@ function createLnurlAuthSigner(options) {
 	};
 }
 //#endregion
-export { createLnurlAuthSigner, createSparkSigner, lnurlAuthRootKey, sparkAccountKey };
+export { EPHEMERAL_ANCHOR_SCRIPT, addressToScript, createLnurlAuthSigner, createSparkSigner, decodeBolt11, lightningSendHtlcScript, lnurlAuthRootKey, sparkAccountKey, sparkNetworkConfig };

package/dist/text-CDhN7qo4.mjs

@@ -0,0 +1,9 @@
+//#region src/core/text.ts
+const CONTROL = /[\u0000-\u001F\u007F-\u009F]/g;
+/** Server-supplied error text made safe to embed in an error message. */
+function serverErrorText(text) {
+	const cleaned = text.replace(CONTROL, "");
+	return cleaned.length <= 256 ? cleaned : `${cleaned.slice(0, 256)}\u2026`;
+}
+//#endregion
+export { serverErrorText as t };

package/dist/{types-jBCznYd6.d.mts → transactions-DjTZU8ev.d.mts}

@@ -1,5 +1,6 @@
 import { n as SparkNetwork, t as LightningAddressStatement } from "./lightning-address-CRULmi9v.mjs";
 import { Transaction } from "@scure/btc-signer";
+import "@scure/btc-signer/utils.js";
 //#region src/core/bitcoin/sighash.d.ts
 /** A transaction to sign: raw bytes plus every input's prevout script and amount. */
 type SigningTarget = {
@@ -62,6 +63,16 @@ type FrostSignJob = {
   readonly operatorCommitments: ReadonlyArray<OperatorCommitment>;
   /** Optional 33-byte adaptor point; omit or leave empty for plain signatures. */
   readonly adaptorPublicKey?: Uint8Array;
+  /**
+   * For connector (cooperative-exit) refunds only: the raw connector transaction plus the
+   * SSP-provided coop-exit payout transaction it spends — binds the signed refund shares to a
+   * disclosed exit destination. Required on jobs spending a foreign connector input; rejected on
+   * any other job.
+   */
+  readonly exit?: {
+    readonly connectorTx: Uint8Array;
+    readonly exitTx: Uint8Array;
+  };
 };
 /** Aggregation of the user's share (obtained from {@link SparkSigner.signFrost}) with the SOs'. */
 type FrostAggregateJob = {
@@ -319,4 +330,16 @@ type SparkSigner = {
   readonly dispose: () => void;
 };
 //#endregion
-export { StaticDepositClaimRequest as _, OperatorCommitment as a, PreparedClaim as c, PreparedTransferLeaf as d, SigningCommitment as f, SparkSigner as g, SparkOperator as h, IdentityStatement as i, PreparedLightningReceive as l, SparkLeafKey as m, FrostSignJob as n, PrepareClaimRequest as o, SparkKey as p, HtlcTimeoutSignRequest as r, PrepareTransferRequest as s, FrostAggregateJob as t, PreparedTransfer as u, SigningTarget as v };
+//#region src/core/bitcoin/script.d.ts
+/** Ephemeral anchor (P2A): OP_TRUE, push 2 bytes, 0x4e73 — value 0 sats. */
+declare const EPHEMERAL_ANCHOR_SCRIPT: Uint8Array;
+//#endregion
+//#region src/core/bitcoin/transactions.d.ts
+/**
+ * Decodes a Bitcoin address to its output script under any network — matching upstream
+ * `Address::from_str(..).assume_checked()`, which never checks that the address's network matches
+ * the operating network.
+ */
+declare function addressToScript(address: string): Uint8Array;
+//#endregion
+export { SparkOperator as _, HtlcTimeoutSignRequest as a, SigningTarget as b, PrepareClaimRequest as c, PreparedLightningReceive as d, PreparedTransfer as f, SparkLeafKey as g, SparkKey as h, FrostSignJob as i, PrepareTransferRequest as l, SigningCommitment as m, EPHEMERAL_ANCHOR_SCRIPT as n, IdentityStatement as o, PreparedTransferLeaf as p, FrostAggregateJob as r, OperatorCommitment as s, addressToScript as t, PreparedClaim as u, SparkSigner as v, StaticDepositClaimRequest as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qntx/spark",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Spark Bitcoin L2 protocol for TypeScript: platform-neutral client, signer and crypto-backend interfaces.",
   "keywords": [
     "bitcoin",
@@ -85,7 +85,7 @@
     "publint": "0.3.25",
     "typescript": "7.0.2",
     "undici": "8.12.2",
-    "vite-plus": "1.2.0"
+    "vite-plus": "1.3.0"
   },
   "devEngines": {
     "packageManager": {