@profullstack/coinpay 0.6.11 → 0.9.0

package/src/tokens.js

@@ -0,0 +1,34 @@
+import { CoinPayClient } from './client.js';
+
+/**
+ * List checkout tokens for a business.
+ * @param {Object} params
+ * @param {string} [params.apiKey] - API key if not using client
+ * @param {CoinPayClient} [params.client] - Existing client
+ * @param {string} [params.businessId] - Business ID
+ * @param {boolean} [params.activeOnly] - Only return active wallets
+ * @returns {Promise<Object>} Tokens response
+ */
+export async function getTokens({ apiKey, client, businessId, activeOnly } = {}) {
+  const coinpay = client || new CoinPayClient({ apiKey });
+  return coinpay.getTokens({ businessId, activeOnly });
+}
+
+/**
+ * List supported coins for a business.
+ * @param {Object} params
+ * @param {string} [params.apiKey] - API key if not using client
+ * @param {CoinPayClient} [params.client] - Existing client
+ * @param {string} [params.businessId] - Business ID
+ * @param {boolean} [params.activeOnly] - Only return active wallets
+ * @returns {Promise<Object>} Supported coins response
+ */
+export async function getSupportedCoins({ apiKey, client, businessId, activeOnly } = {}) {
+  const coinpay = client || new CoinPayClient({ apiKey });
+  return coinpay.getSupportedCoins({ businessId, activeOnly });
+}
+
+export default {
+  getTokens,
+  getSupportedCoins,
+};

package/src/wallet.d.ts

@@ -251,6 +251,17 @@ export declare function validateMnemonic(mnemonic: string): boolean;
  */
 export declare function getDerivationPath(chain: string, index?: number): string;
 
+/**
+ * Derive the address for a chain from a raw BIP-39 seed.
+ * (Standalone counterpart to `WalletClient.deriveAddress`; exported from
+ * wallet.js but previously missing from these type declarations.)
+ *
+ * @param seed - Raw seed bytes, e.g. bip39.mnemonicToSeedSync(mnemonic)
+ * @param chain - Chain id (e.g. 'BTC', 'ETH', 'SOL', 'POL', 'BCH')
+ * @param index - Address index (default 0)
+ */
+export declare function deriveAddress(seed: Uint8Array, chain: string, index?: number): string;
+
 /**
  * Restore a seed from encrypted backup
  */

package/src/wallet.js

@@ -33,6 +33,7 @@ export const WalletChain = {
   USDC_ETH: 'USDC_ETH',
   USDC_POL: 'USDC_POL',
   USDC_SOL: 'USDC_SOL',
+  USDC_BASE: 'USDC_BASE',
   USDT_ETH: 'USDT_ETH',
   USDT_POL: 'USDT_POL',
   USDT_SOL: 'USDT_SOL',
@@ -56,6 +57,7 @@ const COIN_TYPES = {
   USDC_ETH: 60,
   USDC_POL: 60,
   USDC_SOL: 501,
+  USDC_BASE: 60, // Base is EVM, uses ETH path — same address as USDC_ETH
   USDT_ETH: 60,
   USDT_POL: 60,
   USDT_SOL: 501,
@@ -64,7 +66,7 @@ const COIN_TYPES = {
 /**
  * Chains that use secp256k1 curve (vs ed25519 for Solana)
  */
-const SECP256K1_CHAINS = ['BTC', 'BCH', 'ETH', 'POL', 'BNB', 'USDC_ETH', 'USDC_POL', 'USDT_ETH', 'USDT_POL'];
+const SECP256K1_CHAINS = ['BTC', 'BCH', 'ETH', 'POL', 'BNB', 'USDC_ETH', 'USDC_POL', 'USDC_BASE', 'USDT_ETH', 'USDT_POL'];
 
 // ============================================================
 // Address derivation helpers
@@ -305,6 +307,7 @@ export function deriveAddress(seed, chain, index = 0) {
     case 'BNB':
     case 'USDC_ETH':
     case 'USDC_POL':
+    case 'USDC_BASE':
     case 'USDT_ETH':
     case 'USDT_POL':
       return deriveETHAddress(publicKey);
@@ -404,8 +407,17 @@ function getSecp256k1PublicKey(seed) {
  * @private
  */
 function signMessage(message, privateKey) {
-  const messageHash = sha256(new TextEncoder().encode(message));
-  const signature = secp256k1.sign(messageHash, privateKey);
+  // Signed over the RAW message bytes, not sha256(message).
+  //
+  // This used to hash first. The server verifies proofs by passing the raw
+  // encoded message straight to `secp256k1.verify` (see
+  // web-wallet/auth.ts::verifySecp256k1Signature), and noble treats that
+  // argument as the thing that was signed — so a signature over the digest
+  // verifies false against the message. Every proof of ownership this SDK
+  // produced was rejected, which meant `WalletClient.fromSeed()` could not
+  // import a wallet at all. Found while wiring the same proof into
+  // `create()` for V-04.
+  const signature = secp256k1.sign(new TextEncoder().encode(message), privateKey);
   // Handle different noble-curves versions:
   // v1.x returns Signature object with toCompactHex()
   // v2.x returns raw Uint8Array directly
@@ -419,6 +431,160 @@ function signMessage(message, privateKey) {
   return bytesToHex(signature.toCompactRawBytes());
 }
 
+// ================================================================
+// Arbitrary tx / message signing
+// ----------------------------------------------------------------
+// These primitives let callers (like b1dz.com's DEX engine) sign
+// EVM contract calls and Solana transactions that CoinPay's built-in
+// `send` flow doesn't cover (e.g., Uniswap swaps, Jupiter routes).
+//
+// The API intentionally stops at the cryptographic primitive:
+//   - EVM:    caller builds the unsigned tx with their own library
+//             (viem / ethers / ethers-v5), hashes it per EIP-1559 or
+//             EIP-155, hands us the 32-byte digest, gets back a
+//             recoverable signature
+//   - Solana: caller builds the unsigned Transaction / VersionedMessage,
+//             hands us the raw message bytes, gets back an ed25519
+//             signature they can attach to the tx
+//
+// This keeps the crypto surface minimal and correct. We don't try to
+// re-implement RLP, EIP-712, or Solana's transaction encoder inside
+// CoinPay — those live in the caller's toolchain.
+// ================================================================
+
+/** Chains that sign via secp256k1 (32-byte digest → recoverable sig). */
+function isSecp256k1Chain(chain) {
+  return SECP256K1_CHAINS.includes(chain);
+}
+
+/** Chains that sign via ed25519 (arbitrary message bytes → 64-byte sig). */
+function isEd25519Chain(chain) {
+  return chain === 'SOL' || chain === 'USDC_SOL' || chain === 'USDT_SOL';
+}
+
+function normalizeHexInput(hex, label = 'hex') {
+  if (typeof hex !== 'string') throw new Error(`${label} must be a string`);
+  const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (stripped.length === 0) throw new Error(`${label} is empty`);
+  if (stripped.length % 2 !== 0) throw new Error(`${label} has odd length`);
+  if (!/^[0-9a-fA-F]+$/.test(stripped)) throw new Error(`${label} contains non-hex chars`);
+  return hexToBytes(stripped);
+}
+
+/**
+ * Sign a 32-byte digest with a secp256k1 chain's derived key.
+ * Returns a 65-byte recoverable signature formatted as `r(32) || s(32) || v(1)`
+ * where v is the low recovery id (0 or 1). This is the layout every
+ * EVM client (viem, ethers v6) expects for post-typed-transaction
+ * (EIP-1559 / EIP-2930) signatures.
+ *
+ * For legacy / EIP-155 transactions the caller is responsible for
+ * converting v to `chainId * 2 + 35 + recId` after receiving the sig.
+ * For EIP-191 (personal_sign) the caller adds 27.
+ *
+ * @param {Uint8Array} seed - Master seed
+ * @param {string} chain - BIP44 chain code (ETH, POL, BNB, ...)
+ * @param {Uint8Array} digest - Exactly 32 bytes
+ * @returns {string} `0x`-prefixed 65-byte hex signature
+ */
+export function signDigestSecp256k1(seed, chain, digest) {
+  if (!isSecp256k1Chain(chain)) {
+    throw new Error(`chain ${chain} does not use secp256k1`);
+  }
+  if (!(digest instanceof Uint8Array) || digest.length !== 32) {
+    throw new Error('digest must be a 32-byte Uint8Array');
+  }
+  const { privateKey } = deriveKeyPair(seed, chain, 0);
+
+  // noble-curves has two incompatible signing APIs across major versions:
+  //   v1.x: sign(hash, key) → Signature object with .r, .s, .recovery
+  //   v2.x: sign(hash, key, { format: 'recovered' }) → 65-byte Uint8Array
+  //         [recovery, r(32), s(32)]
+  // Detect at runtime so this works with whichever version is pinned.
+  // Requesting 'recovered' on v1 is harmless — v1 ignores the option
+  // and still returns a Signature object.
+  const raw = secp256k1.sign(digest, privateKey, { format: 'recovered' });
+  let r, s, recovery;
+  if (raw instanceof Uint8Array && raw.length === 65) {
+    recovery = raw[0] & 0x01;
+    r = raw.subarray(1, 33);
+    s = raw.subarray(33, 65);
+  } else if (raw && typeof raw === 'object' && 'r' in raw && 's' in raw) {
+    if (typeof raw.recovery !== 'number') {
+      throw new Error('signature missing recovery id');
+    }
+    recovery = raw.recovery & 0x01;
+    r = bigIntToBytes32(raw.r);
+    s = bigIntToBytes32(raw.s);
+  } else {
+    throw new Error(`unexpected signature shape (type=${raw?.constructor?.name})`);
+  }
+
+  const evmSig = new Uint8Array(65);
+  evmSig.set(r, 0);
+  evmSig.set(s, 32);
+  evmSig[64] = recovery;
+  return '0x' + bytesToHex(evmSig);
+}
+
+/** Big-endian 32-byte encoding of a bigint. */
+function bigIntToBytes32(n) {
+  const out = new Uint8Array(32);
+  let x = BigInt(n);
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(x & 0xffn);
+    x >>= 8n;
+  }
+  return out;
+}
+
+/**
+ * Sign an EIP-191 "personal_sign" message. Wraps the message with the
+ * `\x19Ethereum Signed Message:\n<length>` prefix, keccak256-hashes,
+ * then signs the digest. Returns a 65-byte sig with v bumped to 27/28
+ * per EIP-191 convention (compatible with Solidity's ecrecover).
+ *
+ * @param {Uint8Array} seed
+ * @param {string} chain
+ * @param {string|Uint8Array} message - UTF-8 string or raw bytes
+ * @returns {string}
+ */
+export function signEip191Message(seed, chain, message) {
+  if (!isSecp256k1Chain(chain)) {
+    throw new Error(`chain ${chain} does not use secp256k1`);
+  }
+  const bytes = typeof message === 'string'
+    ? new TextEncoder().encode(message)
+    : message;
+  const prefix = new TextEncoder().encode(`\x19Ethereum Signed Message:\n${bytes.length}`);
+  const payload = new Uint8Array(prefix.length + bytes.length);
+  payload.set(prefix, 0);
+  payload.set(bytes, prefix.length);
+  const digest = keccak_256(payload);
+  const sig = hexToBytes(signDigestSecp256k1(seed, chain, digest).slice(2));
+  sig[64] = sig[64] + 27; // EIP-191 uses 27/28 for v
+  return '0x' + bytesToHex(sig);
+}
+
+/**
+ * Sign arbitrary Solana transaction message bytes with the derived
+ * ed25519 key. Returns a 64-byte signature that the caller attaches
+ * to the `VersionedTransaction.signatures` array.
+ *
+ * @param {Uint8Array} seed
+ * @param {Uint8Array} messageBytes - The serialized Solana tx message
+ * @param {number} [index=0] - Derivation index
+ * @returns {string} 64-byte hex signature
+ */
+export function signSolanaMessage(seed, messageBytes, index = 0) {
+  if (!(messageBytes instanceof Uint8Array)) {
+    throw new Error('messageBytes must be a Uint8Array');
+  }
+  const { privateKey } = deriveSOLAddress(seed, index);
+  const signature = ed25519.sign(messageBytes, privateKey);
+  return '0x' + bytesToHex(signature);
+}
+
 /**
  * Derive address placeholder - actual address derivation happens on client
  * This returns the public key that the server can use to verify ownership
@@ -515,11 +681,24 @@ export class WalletClient {
       };
     });
     
+    // V-04: /create accepted a public key and a list of on-chain addresses
+    // from anyone, with no proof that either was theirs, while /import required
+    // a signature for the same write. `wallet_addresses` is globally unique on
+    // (address, chain), so an unproved registration permanently denies an
+    // address to whoever actually owns it.
+    const proofMessage = `CoinPay Wallet Create: ${Date.now()}`;
+    const { privateKey: proofKey } = deriveKeyPair(seed, 'ETH', 0);
+    const proofSignature = signMessage(proofMessage, proofKey);
+
     const result = await client.#request('/web-wallet/create', {
       method: 'POST',
       body: JSON.stringify({
         public_key_secp256k1: publicKeySecp256k1,
         initial_addresses: initialAddresses,
+        proof_of_ownership: {
+          message: proofMessage,
+          signature: proofSignature,
+        },
       }),
     });
     
@@ -840,30 +1019,109 @@ export class WalletClient {
       }),
     });
     
-    // Step 2: Sign the transaction locally
-    // Note: This is a simplified version - real implementation would need
-    // chain-specific signing logic
-    const { privateKey } = deriveKeyPair(this.#seed, chain, 0);
-    const unsignedTx = prepareResult.unsigned_tx;
-    
-    // For EVM chains, sign the transaction hash
-    // For BTC, sign each input
-    // This is simplified - real implementation needs chain-specific logic
-    const signedTx = signMessage(unsignedTx, privateKey);
-    
-    // Step 3: Broadcast the signed transaction
-    const broadcastResult = await this.#request(`/web-wallet/${this.#walletId}/broadcast`, {
-      method: 'POST',
-      body: JSON.stringify({
-        tx_id: prepareResult.tx_id,
-        signed_tx: signedTx,
-        chain,
-      }),
-    });
-    
-    return broadcastResult;
+    // Step 2: Sign the transaction locally.
+    //
+    // NOT IMPLEMENTED, and it now says so instead of pretending.
+    //
+    // This used to call `signMessage(unsignedTx, privateKey)` — a generic
+    // message signature over the JSON of the unsigned transaction — and post
+    // the result as `signed_tx`. That is not a signed transaction on any chain:
+    // a real one is the RLP-encoded (EVM), PSBT-finalised (BTC) or
+    // wire-serialised (Solana) transaction carrying the signature in the right
+    // field. What was produced could never be broadcast, so this method failed
+    // for every integrator who called it — silently, by producing plausible
+    // output that only failed later at the node.
+    //
+    // Failing here rather than guessing is deliberate. Serialising each chain
+    // correctly needs the exact shape of `prepareResult.unsigned_tx` (defined by
+    // the server, not this package) and verification against a live node.
+    // Shipping an unverified serialiser would reintroduce the same class of bug
+    // with more code behind it.
+    //
+    // The primitives to do this yourself are exported and do work:
+    // `signDigest()` for EVM digests and `signMessage()` for EIP-191. Build the
+    // transaction with viem / ethers / @solana/web3.js, sign the digest here,
+    // and post the serialised result to the broadcast endpoint.
+    void prepareResult;
+    throw new Error(
+      'WalletClient.send() is not implemented: chain-specific transaction ' +
+      'serialisation is not available in this package. Build and serialise the ' +
+      'transaction with a chain library, sign the digest with signDigest(), and ' +
+      'POST it to /web-wallet/:id/broadcast. See docs/sdk for an example.'
+    );
   }
   
+  // ==========================================================
+  // Arbitrary-transaction signing (PR: arbitrary-tx-signing)
+  //
+  // These methods expose raw cryptographic signing so callers can
+  // use CoinPay as a wallet provider for flows CoinPay itself
+  // doesn't implement (Uniswap swaps, Jupiter routes, EIP-712
+  // typed data, etc.). The caller builds the unsigned tx with
+  // their own library (viem / ethers / @solana/web3.js), passes
+  // the digest or message bytes to CoinPay, and receives the
+  // signature back. CoinPay never learns the tx semantics — it
+  // just produces cryptographic output.
+  //
+  // SECURITY: these methods are intentionally unprivileged from
+  // CoinPay's perspective. If you expose them to untrusted
+  // callers you're handing over signing authority for the wallet.
+  // The CLI `wallet sign-digest` / `sign-message` commands
+  // require the GPG-encrypted wallet to be unlocked, same as
+  // `wallet send`.
+  // ==========================================================
+
+  /**
+   * Sign a 32-byte digest with the wallet's secp256k1 key for the
+   * given EVM chain. Returns a 65-byte recoverable signature laid
+   * out as `r(32) || s(32) || v(1)`, where v is the raw recovery
+   * bit (0 or 1). Suitable for EIP-1559 / EIP-2930 typed txs.
+   *
+   * For legacy EIP-155 signatures the caller converts v to
+   * `chainId * 2 + 35 + v`. For EIP-191 personal_sign, use
+   * `signMessage()` below instead.
+   *
+   * @param {{chain: string, digest: string|Uint8Array}} params
+   * @returns {string} 0x-prefixed 65-byte signature hex
+   */
+  signDigest({ chain, digest }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    const digestBytes = typeof digest === 'string'
+      ? normalizeHexInput(digest, 'digest')
+      : digest;
+    return signDigestSecp256k1(this.#seed, chain, digestBytes);
+  }
+
+  /**
+   * Sign an EIP-191 "personal_sign" message with the wallet's
+   * secp256k1 key. Handles the `\x19Ethereum Signed Message:\n`
+   * prefix internally.
+   *
+   * @param {{chain: string, message: string|Uint8Array}} params
+   * @returns {string} 0x-prefixed 65-byte signature hex
+   */
+  signMessage({ chain, message }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    return signEip191Message(this.#seed, chain, message);
+  }
+
+  /**
+   * Sign raw Solana transaction message bytes with the derived
+   * ed25519 key. Returns a 64-byte signature the caller attaches
+   * to their `VersionedTransaction.signatures` array.
+   *
+   * @param {{message: string|Uint8Array, index?: number}} params
+   *   `message` is either hex-encoded bytes or a raw Uint8Array.
+   * @returns {string} 0x-prefixed 64-byte signature hex
+   */
+  signSolanaMessage({ message, index = 0 }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    const bytes = typeof message === 'string'
+      ? normalizeHexInput(message, 'message')
+      : message;
+    return signSolanaMessage(this.#seed, bytes, index);
+  }
+
   /**
    * Get transaction history
    * @param {Object} [options] - Query options

package/src/webhooks.js

@@ -1,5 +1,19 @@
 /**
  * Webhook utilities for CoinPay SDK
+ *
+ * Contract:
+ *   - Each business has ONE webhook URL + ONE webhook secret. Both crypto
+ *     and card payment events route to the same endpoint, signed with the
+ *     same secret. Distinguish rails via data.metadata.payment_rail
+ *     ("crypto" or "card").
+ *   - Header: X-CoinPay-Signature: t=<unix_seconds>,v1=<hex_hmac>
+ *   - HMAC body: `${timestamp}.${rawBody}`
+ *   - Algorithm: HMAC-SHA256
+ *   - Tolerance: 300 seconds
+ *
+ * The server-side signer (src/lib/webhooks/service.ts) and the d0rz
+ * verifier (lib/coinpay-client.ts) are kept in lockstep with this file
+ * by src/lib/webhooks/contract.test.ts in the main repo. Don't drift.
  */
 
 import { createHmac, timingSafeEqual } from 'crypto';
@@ -44,7 +58,12 @@ export function verifyWebhookSignature({
     const signatureParts = {};
     
     for (const part of parts) {
-      const [key, value] = part.split('=');
+      // Split on the FIRST '=' only. Splitting on every one truncates any value
+      // that legitimately contains '=' (base64 padding, for instance).
+      const separator = part.indexOf('=');
+      if (separator === -1) continue;
+      const key = part.slice(0, separator).trim();
+      const value = part.slice(separator + 1).trim();
       signatureParts[key] = value;
     }
 
@@ -55,8 +74,23 @@ export function verifyWebhookSignature({
       return false;
     }
 
-    // Check timestamp tolerance
-    const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
+    // Check timestamp tolerance.
+    //
+    // parseInt('abc', 10) is NaN, and every comparison against NaN is false —
+    // so `Math.abs(NaN) > tolerance` was false and the freshness check silently
+    // PASSED for any non-numeric timestamp. A security check that no-ops on
+    // malformed input is worse than no check, because it reads as one. Parse
+    // strictly and reject anything that is not a plain integer.
+    if (!/^\d+$/.test(String(timestamp))) {
+      return false;
+    }
+
+    const signedAt = Number(timestamp);
+    if (!Number.isSafeInteger(signedAt) || signedAt <= 0) {
+      return false;
+    }
+
+    const timestampAge = Math.floor(Date.now() / 1000) - signedAt;
     if (Math.abs(timestampAge) > tolerance) {
       return false;
     }