@breeztech/breez-sdk-spark 0.23.1 → 0.24.0

package/nodejs/postgres-storage/index.cjs

@@ -730,7 +730,7 @@ class PostgresStorage {
   async listDeposits() {
     try {
       const result = await this.pool.query(
-        "SELECT txid, vout, amount_sats, is_mature, claim_error, refund_tx, refund_tx_id, instant_claim_status FROM brz_unclaimed_deposits WHERE user_id = $1",
+        "SELECT txid, vout, amount_sats, is_mature, claim_error, refund_tx, refund_tx_id, instant_claim_status, refund_state FROM brz_unclaimed_deposits WHERE user_id = $1",
         [this.identity]
       );
 
@@ -743,6 +743,7 @@ class PostgresStorage {
         refundTx: row.refund_tx,
         refundTxId: row.refund_tx_id,
         instantClaimStatus: row.instant_claim_status || null,
+        refundState: row.refund_state || null,
       }));
     } catch (error) {
       throw new StorageError(
@@ -757,16 +758,23 @@ class PostgresStorage {
       if (payload.type === "claimError") {
         await this.pool.query(
           `UPDATE brz_unclaimed_deposits
-           SET claim_error = $1, refund_tx = NULL, refund_tx_id = NULL
+           SET claim_error = $1
            WHERE user_id = $2 AND txid = $3 AND vout = $4`,
           [JSON.stringify(payload.error), this.identity, txid, vout]
         );
       } else if (payload.type === "refund") {
         await this.pool.query(
           `UPDATE brz_unclaimed_deposits
-           SET refund_tx = $1, refund_tx_id = $2, claim_error = NULL
-           WHERE user_id = $3 AND txid = $4 AND vout = $5`,
-          [payload.refundTx, payload.refundTxid, this.identity, txid, vout]
+           SET refund_tx = $1, refund_tx_id = $2, refund_state = $3, claim_error = NULL
+           WHERE user_id = $4 AND txid = $5 AND vout = $6`,
+          [
+            payload.refundTx,
+            payload.refundTxid,
+            JSON.stringify(payload.state),
+            this.identity,
+            txid,
+            vout,
+          ]
         );
       } else if (payload.type === "instantClaim") {
         await this.pool.query(
@@ -775,6 +783,19 @@ class PostgresStorage {
            WHERE user_id = $2 AND txid = $3 AND vout = $4`,
           [JSON.stringify(payload.status), this.identity, txid, vout]
         );
+      } else if (payload.type === "refundBroadcastState") {
+        await this.pool.query(
+          `UPDATE brz_unclaimed_deposits
+           SET refund_state = $1
+           WHERE user_id = $2 AND txid = $3 AND vout = $4 AND refund_tx_id = $5`,
+          [
+            JSON.stringify(payload.state),
+            this.identity,
+            txid,
+            vout,
+            payload.refundTxid,
+          ]
+        );
       } else {
         throw new StorageError(`Unknown payload type: ${payload.type}`);
       }
@@ -1606,6 +1627,112 @@ async function createPostgresStorage(config, identity, logger = null) {
   );
 }
 
+/**
+ * Translates the `sslmode` URI parameter into pg's `ssl` option.
+ * The pinned `pg` maps `require` to verified TLS but warns that pg v9 reverts
+ * it to libpq semantics (no verification); handling `sslmode` here keeps the
+ * documented guarantees stable across driver versions. The parameter (and the
+ * `ssl`/`sslcert`/`sslkey`/`sslrootcert` parameters folded into the option)
+ * are stripped from the URI because a connection string's ssl settings
+ * override the explicit option.
+ *
+ * Spellings mirror the Rust SDK where pg has an equivalent:
+ * - absent or `disable`: no TLS
+ * - `prefer` / `require` / `verify-full`: TLS with certificate chain and
+ *   hostname verification (pg cannot fall back to plaintext, so `prefer`
+ *   behaves like `require`)
+ * - `verify-ca`: chain verification only, hostname not checked
+ * - `no-verify`: TLS without certificate verification (explicit opt-in)
+ *
+ * An unrecognized value throws rather than silently changing the TLS level.
+ * Pin a private CA with `sslrootcert=<path>` (required for `verify-ca`); for
+ * the hostname-verified modes, adding the CA to Node's trust store
+ * (e.g. NODE_EXTRA_CA_CERTS) also works, though it extends the store rather
+ * than pinning.
+ */
+function extractSslMode(connectionString) {
+  if (
+    !connectionString.startsWith("postgres://") &&
+    !connectionString.startsWith("postgresql://")
+  ) {
+    return { connectionString, ssl: undefined };
+  }
+  const queryIndex = connectionString.indexOf("?");
+  if (queryIndex === -1) {
+    return { connectionString, ssl: undefined };
+  }
+  const params = connectionString.slice(queryIndex + 1).split("&");
+  if (!params.some((param) => param.startsWith("sslmode="))) {
+    return { connectionString, ssl: undefined };
+  }
+
+  const base = connectionString.slice(0, queryIndex);
+  const retained = [];
+  const files = {};
+  let sslMode;
+  for (const param of params) {
+    const eq = param.indexOf("=");
+    const key = eq === -1 ? param : param.slice(0, eq);
+    const value = eq === -1 ? "" : decodeURIComponent(param.slice(eq + 1));
+    if (key === "sslmode") {
+      sslMode = value;
+    } else if (key === "sslcert" || key === "sslkey" || key === "sslrootcert") {
+      files[key] = value;
+    } else if (key === "ssl") {
+      // consumed: sslmode governs TLS when present
+    } else {
+      retained.push(param);
+    }
+  }
+  const rebuilt = retained.length ? `${base}?${retained.join("&")}` : base;
+  return { connectionString: rebuilt, ssl: sslOptionForMode(sslMode, files) };
+}
+
+function sslOptionForMode(mode, files) {
+  let ssl;
+  switch (mode) {
+    case "disable":
+      return false;
+    case "prefer":
+    case "require":
+    case "verify-full":
+      ssl = { rejectUnauthorized: true };
+      break;
+    case "verify-ca":
+      // Without a pinned CA, chain-only verification accepts a certificate
+      // from any trusted CA for any host, which authenticates nothing.
+      if (!files.sslrootcert) {
+        throw new StorageError(
+          "sslmode=verify-ca requires sslrootcert=<path>; supply the CA to " +
+            "pin, or use sslmode=require / verify-full for " +
+            "hostname-verified TLS"
+        );
+      }
+      ssl = { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+      break;
+    case "no-verify":
+      ssl = { rejectUnauthorized: false };
+      break;
+    default:
+      throw new StorageError(
+        `Unrecognized sslmode value \`${mode}\`; expected one of: ` +
+          "disable, prefer, require, verify-ca, verify-full, no-verify"
+      );
+  }
+  const fs =
+    files.sslcert || files.sslkey || files.sslrootcert ? require("fs") : null;
+  if (files.sslcert) {
+    ssl.cert = fs.readFileSync(files.sslcert).toString();
+  }
+  if (files.sslkey) {
+    ssl.key = fs.readFileSync(files.sslkey).toString();
+  }
+  if (files.sslrootcert) {
+    ssl.ca = fs.readFileSync(files.sslrootcert).toString();
+  }
+  return ssl;
+}
+
 /**
  * Create a pg.Pool from a config object.
  * The returned pool can be shared across multiple store implementations.
@@ -1614,8 +1741,10 @@ async function createPostgresStorage(config, identity, logger = null) {
  * @returns {pg.Pool}
  */
 function createPostgresPool(config) {
+  const { connectionString, ssl } = extractSslMode(config.connectionString);
   return new pg.Pool({
-    connectionString: config.connectionString,
+    connectionString,
+    ...(ssl !== undefined && { ssl }),
     max: config.maxPoolSize,
     connectionTimeoutMillis: config.createTimeoutSecs * 1000,
     idleTimeoutMillis: config.recycleTimeoutSecs * 1000,

package/nodejs/postgres-storage/migrations.cjs

@@ -524,6 +524,22 @@ class PostgresMigrationManager {
           `ALTER TABLE brz_unclaimed_deposits ADD COLUMN instant_claim_status JSONB`,
         ],
       },
+      {
+        // Only the Declined shape changed, and clearing it costs at most one
+        // extra quote. Submitted rows are left alone: their shape is unchanged
+        // and they are the only guard against re-claiming a settling deposit.
+        name: "Clear declined instant claim status after its shape changed",
+        sql: [
+          `UPDATE brz_unclaimed_deposits SET instant_claim_status = NULL
+             WHERE LOWER(instant_claim_status::text) LIKE '%declined%'`,
+        ],
+      },
+      {
+        name: "Add refund state to brz_unclaimed_deposits",
+        sql: [
+          `ALTER TABLE brz_unclaimed_deposits ADD COLUMN refund_state JSONB`,
+        ],
+      },
     ];
   }
 }

package/nodejs/postgres-token-store/index.cjs

@@ -1267,6 +1267,112 @@ class PostgresTokenStore {
   }
 }
 
+/**
+ * Translates the `sslmode` URI parameter into pg's `ssl` option.
+ * The pinned `pg` maps `require` to verified TLS but warns that pg v9 reverts
+ * it to libpq semantics (no verification); handling `sslmode` here keeps the
+ * documented guarantees stable across driver versions. The parameter (and the
+ * `ssl`/`sslcert`/`sslkey`/`sslrootcert` parameters folded into the option)
+ * are stripped from the URI because a connection string's ssl settings
+ * override the explicit option.
+ *
+ * Spellings mirror the Rust SDK where pg has an equivalent:
+ * - absent or `disable`: no TLS
+ * - `prefer` / `require` / `verify-full`: TLS with certificate chain and
+ *   hostname verification (pg cannot fall back to plaintext, so `prefer`
+ *   behaves like `require`)
+ * - `verify-ca`: chain verification only, hostname not checked
+ * - `no-verify`: TLS without certificate verification (explicit opt-in)
+ *
+ * An unrecognized value throws rather than silently changing the TLS level.
+ * Pin a private CA with `sslrootcert=<path>` (required for `verify-ca`); for
+ * the hostname-verified modes, adding the CA to Node's trust store
+ * (e.g. NODE_EXTRA_CA_CERTS) also works, though it extends the store rather
+ * than pinning.
+ */
+function extractSslMode(connectionString) {
+  if (
+    !connectionString.startsWith("postgres://") &&
+    !connectionString.startsWith("postgresql://")
+  ) {
+    return { connectionString, ssl: undefined };
+  }
+  const queryIndex = connectionString.indexOf("?");
+  if (queryIndex === -1) {
+    return { connectionString, ssl: undefined };
+  }
+  const params = connectionString.slice(queryIndex + 1).split("&");
+  if (!params.some((param) => param.startsWith("sslmode="))) {
+    return { connectionString, ssl: undefined };
+  }
+
+  const base = connectionString.slice(0, queryIndex);
+  const retained = [];
+  const files = {};
+  let sslMode;
+  for (const param of params) {
+    const eq = param.indexOf("=");
+    const key = eq === -1 ? param : param.slice(0, eq);
+    const value = eq === -1 ? "" : decodeURIComponent(param.slice(eq + 1));
+    if (key === "sslmode") {
+      sslMode = value;
+    } else if (key === "sslcert" || key === "sslkey" || key === "sslrootcert") {
+      files[key] = value;
+    } else if (key === "ssl") {
+      // consumed: sslmode governs TLS when present
+    } else {
+      retained.push(param);
+    }
+  }
+  const rebuilt = retained.length ? `${base}?${retained.join("&")}` : base;
+  return { connectionString: rebuilt, ssl: sslOptionForMode(sslMode, files) };
+}
+
+function sslOptionForMode(mode, files) {
+  let ssl;
+  switch (mode) {
+    case "disable":
+      return false;
+    case "prefer":
+    case "require":
+    case "verify-full":
+      ssl = { rejectUnauthorized: true };
+      break;
+    case "verify-ca":
+      // Without a pinned CA, chain-only verification accepts a certificate
+      // from any trusted CA for any host, which authenticates nothing.
+      if (!files.sslrootcert) {
+        throw new TokenStoreError(
+          "sslmode=verify-ca requires sslrootcert=<path>; supply the CA to " +
+            "pin, or use sslmode=require / verify-full for " +
+            "hostname-verified TLS"
+        );
+      }
+      ssl = { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+      break;
+    case "no-verify":
+      ssl = { rejectUnauthorized: false };
+      break;
+    default:
+      throw new TokenStoreError(
+        `Unrecognized sslmode value \`${mode}\`; expected one of: ` +
+          "disable, prefer, require, verify-ca, verify-full, no-verify"
+      );
+  }
+  const fs =
+    files.sslcert || files.sslkey || files.sslrootcert ? require("fs") : null;
+  if (files.sslcert) {
+    ssl.cert = fs.readFileSync(files.sslcert).toString();
+  }
+  if (files.sslkey) {
+    ssl.key = fs.readFileSync(files.sslkey).toString();
+  }
+  if (files.sslrootcert) {
+    ssl.ca = fs.readFileSync(files.sslrootcert).toString();
+  }
+  return ssl;
+}
+
 /**
  * Create a PostgresTokenStore instance from a config object.
  *
@@ -1280,8 +1386,10 @@ class PostgresTokenStore {
  * @returns {Promise<PostgresTokenStore>}
  */
 async function createPostgresTokenStore(config, identity, logger = null) {
+  const { connectionString, ssl } = extractSslMode(config.connectionString);
   const pool = new pg.Pool({
-    connectionString: config.connectionString,
+    connectionString,
+    ...(ssl !== undefined && { ssl }),
     max: config.maxPoolSize,
     connectionTimeoutMillis: config.createTimeoutSecs * 1000,
     idleTimeoutMillis: config.recycleTimeoutSecs * 1000,

package/nodejs/postgres-tree-store/index.cjs

@@ -1392,6 +1392,112 @@ class PostgresTreeStore {
   }
 }
 
+/**
+ * Translates the `sslmode` URI parameter into pg's `ssl` option.
+ * The pinned `pg` maps `require` to verified TLS but warns that pg v9 reverts
+ * it to libpq semantics (no verification); handling `sslmode` here keeps the
+ * documented guarantees stable across driver versions. The parameter (and the
+ * `ssl`/`sslcert`/`sslkey`/`sslrootcert` parameters folded into the option)
+ * are stripped from the URI because a connection string's ssl settings
+ * override the explicit option.
+ *
+ * Spellings mirror the Rust SDK where pg has an equivalent:
+ * - absent or `disable`: no TLS
+ * - `prefer` / `require` / `verify-full`: TLS with certificate chain and
+ *   hostname verification (pg cannot fall back to plaintext, so `prefer`
+ *   behaves like `require`)
+ * - `verify-ca`: chain verification only, hostname not checked
+ * - `no-verify`: TLS without certificate verification (explicit opt-in)
+ *
+ * An unrecognized value throws rather than silently changing the TLS level.
+ * Pin a private CA with `sslrootcert=<path>` (required for `verify-ca`); for
+ * the hostname-verified modes, adding the CA to Node's trust store
+ * (e.g. NODE_EXTRA_CA_CERTS) also works, though it extends the store rather
+ * than pinning.
+ */
+function extractSslMode(connectionString) {
+  if (
+    !connectionString.startsWith("postgres://") &&
+    !connectionString.startsWith("postgresql://")
+  ) {
+    return { connectionString, ssl: undefined };
+  }
+  const queryIndex = connectionString.indexOf("?");
+  if (queryIndex === -1) {
+    return { connectionString, ssl: undefined };
+  }
+  const params = connectionString.slice(queryIndex + 1).split("&");
+  if (!params.some((param) => param.startsWith("sslmode="))) {
+    return { connectionString, ssl: undefined };
+  }
+
+  const base = connectionString.slice(0, queryIndex);
+  const retained = [];
+  const files = {};
+  let sslMode;
+  for (const param of params) {
+    const eq = param.indexOf("=");
+    const key = eq === -1 ? param : param.slice(0, eq);
+    const value = eq === -1 ? "" : decodeURIComponent(param.slice(eq + 1));
+    if (key === "sslmode") {
+      sslMode = value;
+    } else if (key === "sslcert" || key === "sslkey" || key === "sslrootcert") {
+      files[key] = value;
+    } else if (key === "ssl") {
+      // consumed: sslmode governs TLS when present
+    } else {
+      retained.push(param);
+    }
+  }
+  const rebuilt = retained.length ? `${base}?${retained.join("&")}` : base;
+  return { connectionString: rebuilt, ssl: sslOptionForMode(sslMode, files) };
+}
+
+function sslOptionForMode(mode, files) {
+  let ssl;
+  switch (mode) {
+    case "disable":
+      return false;
+    case "prefer":
+    case "require":
+    case "verify-full":
+      ssl = { rejectUnauthorized: true };
+      break;
+    case "verify-ca":
+      // Without a pinned CA, chain-only verification accepts a certificate
+      // from any trusted CA for any host, which authenticates nothing.
+      if (!files.sslrootcert) {
+        throw new TreeStoreError(
+          "sslmode=verify-ca requires sslrootcert=<path>; supply the CA to " +
+            "pin, or use sslmode=require / verify-full for " +
+            "hostname-verified TLS"
+        );
+      }
+      ssl = { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+      break;
+    case "no-verify":
+      ssl = { rejectUnauthorized: false };
+      break;
+    default:
+      throw new TreeStoreError(
+        `Unrecognized sslmode value \`${mode}\`; expected one of: ` +
+          "disable, prefer, require, verify-ca, verify-full, no-verify"
+      );
+  }
+  const fs =
+    files.sslcert || files.sslkey || files.sslrootcert ? require("fs") : null;
+  if (files.sslcert) {
+    ssl.cert = fs.readFileSync(files.sslcert).toString();
+  }
+  if (files.sslkey) {
+    ssl.key = fs.readFileSync(files.sslkey).toString();
+  }
+  if (files.sslrootcert) {
+    ssl.ca = fs.readFileSync(files.sslrootcert).toString();
+  }
+  return ssl;
+}
+
 /**
  * Create a PostgresTreeStore instance from a config object.
  *
@@ -1405,8 +1511,10 @@ class PostgresTreeStore {
  * @returns {Promise<PostgresTreeStore>}
  */
 async function createPostgresTreeStore(config, identity, logger = null) {
+  const { connectionString, ssl } = extractSslMode(config.connectionString);
   const pool = new pg.Pool({
-    connectionString: config.connectionString,
+    connectionString,
+    ...(ssl !== undefined && { ssl }),
     max: config.maxPoolSize,
     connectionTimeoutMillis: config.createTimeoutSecs * 1000,
     idleTimeoutMillis: config.recycleTimeoutSecs * 1000,

package/nodejs/storage/index.cjs

@@ -700,7 +700,7 @@ class SqliteStorage {
   listDeposits() {
     try {
       const stmt = this.db.prepare(`
-                SELECT txid, vout, amount_sats, is_mature, claim_error, refund_tx, refund_tx_id, instant_claim_status
+                SELECT txid, vout, amount_sats, is_mature, claim_error, refund_tx, refund_tx_id, instant_claim_status, refund_state
                 FROM unclaimed_deposits
             `);
 
@@ -717,6 +717,7 @@ class SqliteStorage {
           instantClaimStatus: row.instant_claim_status
             ? JSON.parse(row.instant_claim_status)
             : null,
+          refundState: row.refund_state ? JSON.parse(row.refund_state) : null,
         }))
       );
     } catch (error) {
@@ -731,7 +732,7 @@ class SqliteStorage {
       if (payload.type === "claimError") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits 
-          SET claim_error = ?, refund_tx = NULL, refund_tx_id = NULL 
+          SET claim_error = ?
           WHERE txid = ? AND vout = ?
         `);
 
@@ -739,11 +740,17 @@ class SqliteStorage {
       } else if (payload.type === "refund") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits
-          SET refund_tx = ?, refund_tx_id = ?, claim_error = NULL
+          SET refund_tx = ?, refund_tx_id = ?, refund_state = ?, claim_error = NULL
           WHERE txid = ? AND vout = ?
         `);
 
-        stmt.run(payload.refundTx, payload.refundTxid, txid, vout);
+        stmt.run(
+          payload.refundTx,
+          payload.refundTxid,
+          JSON.stringify(payload.state),
+          txid,
+          vout
+        );
       } else if (payload.type === "instantClaim") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits
@@ -752,6 +759,14 @@ class SqliteStorage {
         `);
 
         stmt.run(JSON.stringify(payload.status), txid, vout);
+      } else if (payload.type === "refundBroadcastState") {
+        const stmt = this.db.prepare(`
+          UPDATE unclaimed_deposits
+          SET refund_state = ?
+          WHERE txid = ? AND vout = ? AND refund_tx_id = ?
+        `);
+
+        stmt.run(JSON.stringify(payload.state), txid, vout, payload.refundTxid);
       } else {
         return Promise.reject(
           new StorageError(`Unknown payload type: ${payload.type}`)

package/nodejs/storage/migrations.cjs

@@ -486,6 +486,20 @@ class MigrationManager {
           `ALTER TABLE unclaimed_deposits ADD COLUMN instant_claim_status TEXT`,
         ],
       },
+      {
+        // Only the Declined shape changed, and clearing it costs at most one
+        // extra quote. Submitted rows are left alone: their shape is unchanged
+        // and they are the only guard against re-claiming a settling deposit.
+        name: "Clear declined instant claim status after its shape changed",
+        sql: [
+          `UPDATE unclaimed_deposits SET instant_claim_status = NULL
+             WHERE LOWER(instant_claim_status) LIKE '%declined%'`,
+        ],
+      },
+      {
+        name: "Add refund state to unclaimed_deposits",
+        sql: [`ALTER TABLE unclaimed_deposits ADD COLUMN refund_state TEXT`],
+      },
     ];
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@breeztech/breez-sdk-spark",
-    "version": "0.23.1",
+    "version": "0.24.0",
     "description": "Breez Spark SDK",
     "repository": "https://github.com/breez/spark-sdk",
     "author": "Breez <contact@breez.technology> (https://github.com/breez)",