@txnod/sdk 1.0.1

package/dist/verify/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Multi-chain address-verification dispatcher consumed by TxnodClient.createInvoice.
+ * Routes the invoice's coin → chain → per-chain verifier with multi-xpub
+ * iteration (newest-first per AD-10) and selective error rethrow.
+ */
+import type { Chain, InvoiceResponse, WalletEdgeKind } from '../_shared/index.js';
+import type { TonXpubConfig } from './config.js';
+/**
+ * Input shape for {@link verifyAddress}. The `invoice` field is a `Pick` of
+ * the fields actually consumed (`coin`, `address`, `derivation_path`, plus
+ * optional `id` for log correlation), so test fixtures are trivial.
+ *
+ * @example
+ * ```ts
+ * import { verifyAddress, type VerifyAddressInput } from '@txnod/sdk';
+ *
+ * const input: VerifyAddressInput = {
+ *   invoice: {
+ *     id: '01HK8MAR2QEXAMPLE000000000',
+ *     coin: 'btc',
+ *     address: 'bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu',
+ *     derivation_path: "m/84'/0'/0'/0/0",
+ *   },
+ *   config: {
+ *     btc: ['zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs'],
+ *     eth: [],
+ *     tron: [],
+ *     ada: [],
+ *     polygon: [],
+ *     bsc: [],
+ *   },
+ * };
+ * verifyAddress(input);
+ * ```
+ */
+export interface VerifyAddressInput {
+    invoice: Pick<InvoiceResponse, 'coin' | 'address' | 'derivation_path'> & {
+        id?: string;
+        /**
+         * Optional explicit project kind override. The invoice envelope no longer
+         * carries a `network` discriminator — kind is implied from the project a
+         * given API key is bound to. Pass `kind` here only if the partner is
+         * verifying a TON invoice and needs to assert the user-friendly address
+         * encoding flag. Defaults to `'production'`.
+         */
+        kind?: WalletEdgeKind;
+    };
+    config: Record<Chain, string[]>;
+    /**
+     * Optional TON-specific config. When the invoice's chain resolves to `ton`
+     * and this is set, the SDK calls {@link verifyTonAddress} automatically.
+     * When `undefined`, TON verification is skipped silently — same behaviour as
+     * an HD chain with no `TXNOD_<chain>_XPUB` configured. Populate via
+     * {@link parseTonConfig} (env-driven).
+     */
+    tonConfig?: TonXpubConfig;
+}
+/**
+ * Result type for {@link verifyAddress}. The function returns void on success
+ * or skip and throws on mismatch — this alias documents the void contract.
+ *
+ * @example
+ * ```ts
+ * import { verifyAddress, type VerificationResult } from '@txnod/sdk';
+ *
+ * const result: VerificationResult = verifyAddress({
+ *   invoice: {
+ *     coin: 'btc',
+ *     address: 'bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu',
+ *     derivation_path: "m/84'/0'/0'/0/0",
+ *   },
+ *   config: { btc: [], eth: [], tron: [], ada: [], polygon: [], bsc: [] },
+ * });
+ * console.log(result); // undefined
+ * ```
+ */
+export type VerificationResult = void;
+/**
+ * Verify that the API-returned invoice address derives from one of the
+ * partner's configured xpubs for the invoice's chain. Returns void on
+ * success, on edge case (a) (missing `derivation_path` → log+skip), or on
+ * edge case (b) (no xpub configured → silent skip). Throws
+ * `AddressVerificationError` when all configured xpubs fail to derive the
+ * address. Rethrows `TxnodInvalidXpubFormatError` (and other non-
+ * `AddressVerificationError`) immediately — a malformed xpub is a config
+ * bug, not a "try the next one" signal.
+ *
+ * @example
+ * ```ts
+ * import { verifyAddress, AddressVerificationError } from '@txnod/sdk';
+ *
+ * try {
+ *   verifyAddress({
+ *     invoice: {
+ *       id: '01HK8MAR2QEXAMPLE000000000',
+ *       coin: 'btc',
+ *       address: 'bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu',
+ *       derivation_path: "m/84'/0'/0'/0/0",
+ *     },
+ *     config: {
+ *       btc: ['zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs'],
+ *       eth: [],
+ *       tron: [],
+ *       ada: [],
+ *       polygon: [],
+ *       bsc: [],
+ *     },
+ *   });
+ * } catch (err) {
+ *   if (err instanceof AddressVerificationError) {
+ *     console.error('verify failed', err.chain, err.expected_address, err.derived_address);
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
+ */
+export declare function verifyAddress(input: VerifyAddressInput): VerificationResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/verify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAUlF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAAC,GAAG;QACvE,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ;;;;;;WAMG;QACH,IAAI,CAAC,EAAE,cAAc,CAAC;KACvB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAqCtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,kBAAkB,CA+D3E"}

package/dist/verify/index.js

@@ -0,0 +1,166 @@
+/**
+ * Multi-chain address-verification dispatcher consumed by TxnodClient.createInvoice.
+ * Routes the invoice's coin → chain → per-chain verifier with multi-xpub
+ * iteration (newest-first per AD-10) and selective error rethrow.
+ */
+import { logger } from '../internals/logger.js';
+import { AddressVerificationError } from './errors.js';
+import { verifyBtc } from './chains/btc.js';
+import { verifyEvm } from './chains/evm.js';
+import { verifyTron } from './chains/tron.js';
+import { verifyCardano } from './chains/cardano.js';
+import { verifyPolygon } from './chains/polygon.js';
+import { verifyBsc } from './chains/bsc.js';
+import { verifyTonAddress } from './chains/ton.js';
+// Mirrors packages/shared/src/schemas/coin.ts COIN_TO_CHAIN — drift is coupled with the shared table.
+const COIN_TO_CHAIN_LITERAL = {
+    btc: 'btc',
+    eth: 'eth',
+    usdt_erc20: 'eth',
+    usdc_erc20: 'eth',
+    trx: 'tron',
+    usdt_trc20: 'tron',
+    ada: 'ada',
+    pol: 'polygon',
+    usdt_polygon: 'polygon',
+    usdc_polygon: 'polygon',
+    bnb: 'bsc',
+    usdt_bep20: 'bsc',
+    usdc_bep20: 'bsc',
+    ton: 'ton',
+    usdt_ton: 'ton',
+};
+function dispatchByChain(chain, xpub, derivation_path, expected_address) {
+    switch (chain) {
+        case 'btc':
+            verifyBtc({ xpub, derivation_path, expected_address });
+            return;
+        case 'eth':
+            verifyEvm({ xpub, derivation_path, expected_address, chain: 'eth' });
+            return;
+        case 'tron':
+            verifyTron({ xpub, derivation_path, expected_address });
+            return;
+        case 'ada':
+            verifyCardano({ xpub, derivation_path, expected_address });
+            return;
+        case 'polygon':
+            verifyPolygon({ xpub, derivation_path, expected_address });
+            return;
+        case 'bsc':
+            verifyBsc({ xpub, derivation_path, expected_address });
+            return;
+        case 'ton':
+            // Unreachable — TON is handled in verifyAddress() before dispatchByChain.
+            return;
+        default: {
+            const _exhaustive = chain;
+            throw new Error(`unreachable chain: ${_exhaustive}`);
+        }
+    }
+}
+/**
+ * Verify that the API-returned invoice address derives from one of the
+ * partner's configured xpubs for the invoice's chain. Returns void on
+ * success, on edge case (a) (missing `derivation_path` → log+skip), or on
+ * edge case (b) (no xpub configured → silent skip). Throws
+ * `AddressVerificationError` when all configured xpubs fail to derive the
+ * address. Rethrows `TxnodInvalidXpubFormatError` (and other non-
+ * `AddressVerificationError`) immediately — a malformed xpub is a config
+ * bug, not a "try the next one" signal.
+ *
+ * @example
+ * ```ts
+ * import { verifyAddress, AddressVerificationError } from '@txnod/sdk';
+ *
+ * try {
+ *   verifyAddress({
+ *     invoice: {
+ *       id: '01HK8MAR2QEXAMPLE000000000',
+ *       coin: 'btc',
+ *       address: 'bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu',
+ *       derivation_path: "m/84'/0'/0'/0/0",
+ *     },
+ *     config: {
+ *       btc: ['zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs'],
+ *       eth: [],
+ *       tron: [],
+ *       ada: [],
+ *       polygon: [],
+ *       bsc: [],
+ *     },
+ *   });
+ * } catch (err) {
+ *   if (err instanceof AddressVerificationError) {
+ *     console.error('verify failed', err.chain, err.expected_address, err.derived_address);
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
+ */
+export function verifyAddress(input) {
+    const { invoice, config, tonConfig } = input;
+    const chain = COIN_TO_CHAIN_LITERAL[invoice.coin];
+    // TON has no xpub/derivation — operator pubkey + wallet metadata are
+    // supplied via TonXpubConfig (TXNOD_TON_PUBKEY + siblings). When unset, the
+    // SDK silently skips verification (parity with omitting TXNOD_<chain>_XPUB
+    // for HD chains); `createInvoice` still surfaces a single warn so partners
+    // are not silently relying on server trust.
+    if (chain === 'ton') {
+        if (tonConfig === undefined) {
+            logger.warn({
+                msg: 'SDK verify: TON address verification skipped — set TXNOD_TON_PUBKEY to enable',
+                invoice_id: invoice.id,
+            });
+            return;
+        }
+        const kind = invoice.kind ?? 'production';
+        try {
+            verifyTonAddress({
+                chain: 'ton',
+                publicKeyHex: tonConfig.publicKeyHex,
+                walletVersion: tonConfig.walletVersion,
+                subwalletId: tonConfig.subwalletId,
+                workchain: tonConfig.workchain,
+                kind,
+                expectedAddress: invoice.address,
+            });
+        }
+        catch (err) {
+            if (err instanceof AddressVerificationError)
+                throw err;
+            throw err;
+        }
+        return;
+    }
+    const xpubs = config[chain] ?? [];
+    if (xpubs.length === 0)
+        return;
+    if (!invoice.derivation_path) {
+        logger.warn({
+            msg: 'SDK verify: derivation_path absent on response; skipping verification',
+            chain,
+            invoice_id: invoice.id,
+        });
+        return;
+    }
+    for (const xpub of xpubs) {
+        try {
+            dispatchByChain(chain, xpub, invoice.derivation_path, invoice.address);
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof AddressVerificationError))
+                throw err;
+        }
+    }
+    // Sentinel: count of attempted xpubs is encoded in derived_address to keep AddressVerificationError shape unchanged.
+    throw new AddressVerificationError({
+        chain,
+        derivation_path: invoice.derivation_path,
+        expected_address: invoice.address,
+        derived_address: `<no match across ${xpubs.length} configured xpub${xpubs.length === 1 ? '' : 's'} for chain '${chain}'>`,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/verify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"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"}

package/dist/verify/xpub-safety.d.ts

@@ -0,0 +1,33 @@
+import type { Chain } from '../_shared/index.js';
+/**
+ * Returns the 4-char prefix of an xpub-shaped string. Used by the xpub-prefix
+ * guard to detect testnet-shape xpubs (`tpub`/`vpub`/`upub`) configured for
+ * production environments.
+ */
+export declare function detectXpubPrefix(xpub: string): string;
+/**
+ * Synchronous guard called from `TxnodClient.constructor` and
+ * `refreshXpubConfig()`. Iterates every chain × xpub in `xpubConfig`; throws
+ * `TxnodSandboxXpubInProductionError` for the first testnet-shape prefix
+ * found when `env === 'production'`.
+ *
+ * Carve-outs (no-ops, by spec §7.2 layer 3 + §4.6):
+ *  - **Cardano (`ada`)**: CIP-5 hrp does not distinguish testnet at the
+ *    account-pubkey level. Network safety lives at the address-level
+ *    NetworkId byte, enforced server-side by the chain watcher and at the
+ *    SDK boundary by `verify/chains/cardano.ts`. The xpub prefix is
+ *    structurally non-discriminating for ADA.
+ *  - **TON (`ton`)**: there is no xpub concept — `TXNOD_TON_PUBKEY` is a
+ *    32-byte ed25519 public key, never an extended key. The guard does not
+ *    inspect `TonXpubConfig` at all (that's why the function takes only
+ *    `xpubConfig`).
+ *  - **EVM-family `xpub` ambiguity (`eth`/`polygon`/`bsc`)**: mainnet and
+ *    testnet on EVM chains both commonly use `xpub`-prefixed extended keys;
+ *    network differentiation lives in the per-address checksum and the chain
+ *    id, not in the xpub prefix. The guard ONLY catches `tpub`/`vpub`/`upub`
+ *    — an `xpub` configured for a testnet EVM chain falls through to the
+ *    server-side cross-mode check (§7.2 layer 4) and the webhook envelope
+ *    `mode` discriminator (§7.2 layer 5).
+ */
+export declare function assertNoTestnetXpubsInProduction(xpubConfig: Record<Chain, string[]>, env: 'production' | 'non-production' | 'unknown'): void;
+//# sourceMappingURL=xpub-safety.d.ts.map

package/dist/verify/xpub-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xpub-safety.d.ts","sourceRoot":"","sources":["../../src/verify/xpub-safety.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAM3C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EACnC,GAAG,EAAE,YAAY,GAAG,gBAAgB,GAAG,SAAS,GAC/C,IAAI,CAYN"}

package/dist/verify/xpub-safety.js

@@ -0,0 +1,54 @@
+import { TxnodSandboxXpubInProductionError } from '../errors.js';
+const TESTNET_XPUB_PREFIXES = ['tpub', 'vpub', 'upub'];
+const PREFIX_LENGTH = 4;
+/**
+ * Returns the 4-char prefix of an xpub-shaped string. Used by the xpub-prefix
+ * guard to detect testnet-shape xpubs (`tpub`/`vpub`/`upub`) configured for
+ * production environments.
+ */
+export function detectXpubPrefix(xpub) {
+    return xpub.slice(0, PREFIX_LENGTH);
+}
+function isTestnetPrefix(prefix) {
+    return TESTNET_XPUB_PREFIXES.includes(prefix);
+}
+/**
+ * Synchronous guard called from `TxnodClient.constructor` and
+ * `refreshXpubConfig()`. Iterates every chain × xpub in `xpubConfig`; throws
+ * `TxnodSandboxXpubInProductionError` for the first testnet-shape prefix
+ * found when `env === 'production'`.
+ *
+ * Carve-outs (no-ops, by spec §7.2 layer 3 + §4.6):
+ *  - **Cardano (`ada`)**: CIP-5 hrp does not distinguish testnet at the
+ *    account-pubkey level. Network safety lives at the address-level
+ *    NetworkId byte, enforced server-side by the chain watcher and at the
+ *    SDK boundary by `verify/chains/cardano.ts`. The xpub prefix is
+ *    structurally non-discriminating for ADA.
+ *  - **TON (`ton`)**: there is no xpub concept — `TXNOD_TON_PUBKEY` is a
+ *    32-byte ed25519 public key, never an extended key. The guard does not
+ *    inspect `TonXpubConfig` at all (that's why the function takes only
+ *    `xpubConfig`).
+ *  - **EVM-family `xpub` ambiguity (`eth`/`polygon`/`bsc`)**: mainnet and
+ *    testnet on EVM chains both commonly use `xpub`-prefixed extended keys;
+ *    network differentiation lives in the per-address checksum and the chain
+ *    id, not in the xpub prefix. The guard ONLY catches `tpub`/`vpub`/`upub`
+ *    — an `xpub` configured for a testnet EVM chain falls through to the
+ *    server-side cross-mode check (§7.2 layer 4) and the webhook envelope
+ *    `mode` discriminator (§7.2 layer 5).
+ */
+export function assertNoTestnetXpubsInProduction(xpubConfig, env) {
+    if (env !== 'production')
+        return;
+    for (const chain of Object.keys(xpubConfig)) {
+        if (chain === 'ada' || chain === 'ton')
+            continue;
+        const xpubs = xpubConfig[chain] ?? [];
+        for (const xpub of xpubs) {
+            const prefix = detectXpubPrefix(xpub);
+            if (isTestnetPrefix(prefix)) {
+                throw new TxnodSandboxXpubInProductionError(chain, prefix);
+            }
+        }
+    }
+}
+//# sourceMappingURL=xpub-safety.js.map

package/dist/verify/xpub-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xpub-safety.js","sourceRoot":"","sources":["../../src/verify/xpub-safety.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iCAAiC,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,qBAAqB,GAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9E,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gCAAgC,CAC9C,UAAmC,EACnC,GAAgD;IAEhD,IAAI,GAAG,KAAK,YAAY;QAAE,OAAO;IACjC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAY,EAAE,CAAC;QACvD,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK;YAAE,SAAS;QACjD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,iCAAiC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/verify-webhook-signature.d.ts

@@ -0,0 +1,30 @@
+import type { WebhookEvent } from './_shared/index.js';
+/**
+ * Verifies an inbound webhook signature and returns a typed event. Parses
+ * the `X-Txnod-Signature: t=<unix>,v1=<hex>` header, recomputes HMAC-SHA256
+ * over `${timestamp}.${rawBody}` using the project secret, compares in
+ * constant time, and enforces a ±300s timestamp window. Throws typed errors
+ * on any failure.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature, TxnodHmacError, TxnodTimestampError } from '@txnod/sdk';
+ *
+ * export async function POST(req: Request) {
+ *   const rawBody = await req.text();
+ *   try {
+ *     const event = verifyWebhookSignature(req.headers, rawBody, process.env.TXNOD_WEBHOOK_SECRET!);
+ *     if (event.event_type === 'invoice.paid') {
+ *       console.log('paid', event.event_id);
+ *     }
+ *     return Response.json({ ok: true });
+ *   } catch (err) {
+ *     if (err instanceof TxnodHmacError) return new Response('bad sig', { status: 401 });
+ *     if (err instanceof TxnodTimestampError) return new Response('stale', { status: 401 });
+ *     throw err;
+ *   }
+ * }
+ * ```
+ */
+export declare function verifyWebhookSignature(headers: Headers | Record<string, string> | Record<string, string[]>, rawBody: string, secret: string): WebhookEvent;
+//# sourceMappingURL=verify-webhook-signature.d.ts.map

package/dist/verify-webhook-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-webhook-signature.d.ts","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA8BlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACpE,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,YAAY,CAqCd"}

package/dist/verify-webhook-signature.js

@@ -0,0 +1,84 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { TxnodHmacError, TxnodSignatureFormatError, TxnodTimestampError, TxnodWebhookPayloadParseError, } from './errors.js';
+const TIMESTAMP_WINDOW_SECONDS = 300;
+const DIGEST_BYTES = 32;
+const SIGNATURE_HEADER = 'x-txnod-signature';
+const HEADER_PATTERN = /^t=(\d+),v1=([0-9a-fA-F]+)$/;
+function getHeader(headers, name) {
+    if (headers instanceof Headers) {
+        return headers.get(name) ?? undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        if (Array.isArray(value)) {
+            return value[0];
+        }
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Verifies an inbound webhook signature and returns a typed event. Parses
+ * the `X-Txnod-Signature: t=<unix>,v1=<hex>` header, recomputes HMAC-SHA256
+ * over `${timestamp}.${rawBody}` using the project secret, compares in
+ * constant time, and enforces a ±300s timestamp window. Throws typed errors
+ * on any failure.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature, TxnodHmacError, TxnodTimestampError } from '@txnod/sdk';
+ *
+ * export async function POST(req: Request) {
+ *   const rawBody = await req.text();
+ *   try {
+ *     const event = verifyWebhookSignature(req.headers, rawBody, process.env.TXNOD_WEBHOOK_SECRET!);
+ *     if (event.event_type === 'invoice.paid') {
+ *       console.log('paid', event.event_id);
+ *     }
+ *     return Response.json({ ok: true });
+ *   } catch (err) {
+ *     if (err instanceof TxnodHmacError) return new Response('bad sig', { status: 401 });
+ *     if (err instanceof TxnodTimestampError) return new Response('stale', { status: 401 });
+ *     throw err;
+ *   }
+ * }
+ * ```
+ */
+export function verifyWebhookSignature(headers, rawBody, secret) {
+    const raw = getHeader(headers, SIGNATURE_HEADER);
+    if (raw === undefined) {
+        throw new TxnodSignatureFormatError();
+    }
+    const match = HEADER_PATTERN.exec(raw);
+    if (match === null) {
+        throw new TxnodSignatureFormatError();
+    }
+    const timestampStr = match[1];
+    const providedHex = match[2];
+    if (providedHex.length !== DIGEST_BYTES * 2) {
+        throw new TxnodSignatureFormatError();
+    }
+    const timestamp = Number(timestampStr);
+    const nowSec = Math.floor(Date.now() / 1000);
+    const skewSeconds = nowSec - timestamp;
+    if (Math.abs(skewSeconds) > TIMESTAMP_WINDOW_SECONDS) {
+        throw new TxnodTimestampError(skewSeconds);
+    }
+    const expected = createHmac('sha256', secret)
+        .update(`${timestamp}.${rawBody}`)
+        .digest();
+    // `provided` is structurally `DIGEST_BYTES` long: HEADER_PATTERN + the
+    // `providedHex.length === DIGEST_BYTES * 2` check above guarantee 64 hex
+    // chars in, which `Buffer.from(_, 'hex')` decodes to exactly 32 bytes.
+    if (!timingSafeEqual(Buffer.from(providedHex, 'hex'), expected)) {
+        throw new TxnodHmacError();
+    }
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch (cause) {
+        throw new TxnodWebhookPayloadParseError(cause);
+    }
+}
+//# sourceMappingURL=verify-webhook-signature.js.map

package/dist/verify-webhook-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-webhook-signature.js","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AAErB,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD,SAAS,SAAS,CAChB,OAAoE,EACpE,IAAY;IAEZ,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;IACxC,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI;YAAE,SAAS;QACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAoE,EACpE,OAAe,EACf,MAAc;IAEd,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC9B,IAAI,WAAW,CAAC,MAAM,KAAK,YAAY,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,wBAAwB,EAAE,CAAC;QACrD,MAAM,IAAI,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC1C,MAAM,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;SACjC,MAAM,EAAE,CAAC;IACZ,uEAAuE;IACvE,yEAAyE;IACzE,uEAAuE;IACvE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,cAAc,EAAE,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,6BAA6B,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/docs/00-getting-started.md

@@ -0,0 +1,135 @@
+---
+title: "Getting started"
+description: "Install @txnod/sdk, configure env vars, create the first invoice, verify the first webhook."
+sdk_version: 1.0.0
+---
+
+# Getting started
+
+## Runtime requirements
+
+- Node ≥ 20 (the SDK uses `node:crypto`, `globalThis.fetch`, and the `Headers` Web API).
+- Server-side only. Do not import `@txnod/sdk` into browser bundles — the `apiSecret` must never leave the server.
+
+## Install
+
+```bash
+npm install @txnod/sdk
+# or
+pnpm add @txnod/sdk
+# or
+yarn add @txnod/sdk
+# or
+bun add @txnod/sdk
+```
+
+The tarball ships **zero dependencies** — runtime or type-level. The compiled JS has no external imports beyond `node:crypto`. Published `.d.ts` types are fully expanded to plain TypeScript at build time (no `zod` type constructs, no `@txnod/*` references), so the SDK coexists with any version of zod your project may already use — or none at all. Bundle size is enforced in CI.
+
+## Configure environment variables
+
+```bash
+# .env.local (never commit)
+TXNOD_PROJECT_ID=01JXXXXXXXXXXXXXXXXXXXXXXX
+TXNOD_API_SECRET=<64-hex-character secret>
+TXNOD_WEBHOOK_SECRET=<same value as TXNOD_API_SECRET>
+
+# Optional — omit unless targeting a non-default endpoint.
+# TXNOD_BASE_URL=https://txnod.com
+```
+
+- `TXNOD_PROJECT_ID` is a ULID surfaced when the operator creates a project in the dashboard.
+- `TXNOD_API_SECRET` is shown **exactly once** on key generation. Copy into secrets manager immediately; the server stores only a hash.
+- `TXNOD_WEBHOOK_SECRET` intentionally equals `TXNOD_API_SECRET`. Two names let callers wire distinct env vars in their framework without re-deriving the relationship.
+- `TXNOD_BASE_URL` is optional and defaults to `https://txnod.com`. Set it to point the SDK at a self-hosted txnod-compatible API (for example when someone runs the project under a different domain) or at a staging instance. The HMAC scheme and all endpoints are endpoint-agnostic — only the origin changes.
+
+See [`01-authentication.md`](./01-authentication.md) for how these values are consumed.
+
+## First invoice
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  // Omit baseUrl (defaults to https://txnod.com) unless you are pointing at
+  // a self-hosted instance or a staging environment. Passing process.env
+  // conditionally keeps prod and dev wiring in the same file:
+  ...(process.env.TXNOD_BASE_URL ? { baseUrl: process.env.TXNOD_BASE_URL } : {}),
+});
+
+const invoice = await client.createInvoice({
+  amount_usd: 9.99,
+  coin: 'usdt_trc20',
+  external_id: 'order-42',
+  callback_url: 'https://your-site.com/api/txnod-webhook',
+});
+
+// Show these to the payer:
+//   invoice.address          — deposit address for this invoice
+//   invoice.amount_crypto    — decimal string, e.g. "9.990000"
+//   invoice.amount_crypto_units — integer string in base units (sats, wei, ...)
+//   invoice.payment_uri           — BIP-21 / EIP-681 / Cardano URI for QR generation
+//   invoice.expires_at_iso   — invoice auto-expires at this ISO-8601 UTC timestamp
+```
+
+`external_id` is your side's idempotency key — see [`06-idempotency.md`](./06-idempotency.md). `coin` must be one of the 15 supported coins listed in [`reference/types.md`](./reference/types.md#coin).
+
+For staging or development, ask the operator to spin up a separate `kind='testnet'` project (dashboard → New project → Testnet). The SDK code path is identical — partner code talks to the testnet project's API key and the SDK accepts testnet-prefix xpubs (`tpub`/`vpub`/`zpub`, `addr_test1...` for Cardano) for address verification automatically. See [`02-invoices.md`](./02-invoices.md#testnet) for the canonical testnet setup.
+
+For deterministic integration tests, the SDK ships a sandbox surface (`client.sandbox.*`) that walks the invoice state machine without touching a chain. See [`05-sandbox.md`](./05-sandbox.md) for the full surface, environment-detection guards, and the [`examples/sandbox-vitest-suite.md`](./examples/sandbox-vitest-suite.md) end-to-end harness.
+
+## First verified webhook
+
+```ts
+// Next.js 16 App Router — app/api/txnod-webhook/route.ts
+import {
+  verifyWebhookSignature,
+  TxnodHmacError,
+  TxnodTimestampError,
+} from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text(); // must be the exact bytes, pre-parsing
+  try {
+    const event = verifyWebhookSignature(
+      request.headers,
+      rawBody,
+      process.env.TXNOD_WEBHOOK_SECRET!,
+    );
+    if (event.event_type === 'invoice.paid') {
+      // event is narrowed to the paid variant. See 04-webhooks.md for the discriminants.
+    }
+    return Response.json({ ok: true });
+  } catch (err) {
+    if (err instanceof TxnodHmacError) return new Response('bad sig', { status: 401 });
+    if (err instanceof TxnodTimestampError) return new Response('stale', { status: 401 });
+    throw err;
+  }
+}
+```
+
+**Critical:** do not parse the body before signing verification. HMAC is computed over the raw bytes as sent; any middleware that re-serializes JSON breaks the signature.
+
+## Self-hosted or alternative-origin deployments
+
+`TxnodClient` accepts `baseUrl?: string` explicitly, which always wins over `TXNOD_BASE_URL`. The SDK's HMAC scheme, retry logic, and `verifyWebhookSignature` helper are endpoint-agnostic — they work unchanged against any server that implements the TxNod API contract. Typical uses:
+
+- **Default:** omit `baseUrl`. The SDK targets `https://txnod.com`.
+- **Staging:** set `TXNOD_BASE_URL=https://staging.txnod.com` in the staging environment only.
+- **Self-hosted TxNod:** if someone operates their own non-custodial txnod-compatible gateway, their partners point the SDK at that origin the same way (`baseUrl: 'https://pay.mycompany.com'`). No code changes, no rebuild — the SDK is origin-neutral.
+
+```ts
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  baseUrl: 'https://pay.mycompany.com', // trailing slash optional; SDK normalises it.
+});
+```
+
+## Where to go next
+
+- To understand the HMAC scheme and headers → [`01-authentication.md`](./01-authentication.md).
+- To branch on every invoice status and error_code → [`02-invoices.md`](./02-invoices.md) and [`05-errors.md`](./05-errors.md).
+- To read each webhook event shape → [`04-webhooks.md`](./04-webhooks.md).
+- Full working code → [`examples/nextjs-route-handler.md`](./examples/nextjs-route-handler.md).