node-firebird 2.3.3 → 2.4.0

package/poc/helpers.js

@@ -1,59 +0,0 @@
-'use strict';
-
-/**
- * Shared helpers used by reproduce.js and reproduce-fixed.js.
- */
-
-const net = require('net');
-
-/** Timestamp prefix for log lines (HH:MM:SS.mmm) */
-function ts() {
-    return new Date().toISOString().slice(11, 23);
-}
-
-/** Structured log with fixed-width tag */
-function log(tag, msg) {
-    console.log(`[${ts()}] ${tag.padEnd(22)} ${msg}`);
-}
-
-/** Compact pool state string */
-function poolState(pool) {
-    return (
-        `creating=${pool._creating}  ` +
-        `idle=${pool.pooldb.length}  ` +
-        `inuse=${pool.dbinuse}  ` +
-        `pending=${pool.pending.length}  ` +
-        `destroyed=${pool._destroyed ?? '(no flag)'}`
-    );
-}
-
-/**
- * Starts a TCP server that accepts connections but NEVER responds to data.
- *
- * This simulates a Firebird server that:
- *   - Completes the TCP three-way handshake (SYN / SYN-ACK / ACK)
- *   - Receives the initial op_connect packet from the client
- *   - Never sends op_accept_data back
- *
- * Result: node-firebird's attach() callback is never called, reproducing the
- * scenario where _creating is permanently incremented.
- */
-function startFakeServer(port, onReady) {
-    const server = net.createServer((socket) => {
-        log('fake-server', `TCP accepted from :${socket.remotePort} — will NOT respond to Firebird protocol`);
-        socket.on('data', () => { /* receive op_connect but ignore it */ });
-        socket.on('error', () => { /* suppress errors on forced cleanup */ });
-    });
-
-    server.on('error', (err) => {
-        console.error(`[fake-server] Error: ${err.message}`);
-        process.exit(1);
-    });
-
-    server.listen(port, '127.0.0.1', () => {
-        log('fake-server', `Listening on 127.0.0.1:${port} (accepts TCP, ignores Firebird wire protocol)`);
-        onReady(server);
-    });
-}
-
-module.exports = { ts, log, poolState, startFakeServer };

package/poc/node_modules/.package-lock.json

@@ -1,14 +0,0 @@
-{
-  "name": "node-firebird-pool-poc",
-  "version": "1.0.0",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "node_modules/node-firebird": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/node-firebird/-/node-firebird-2.3.1.tgz",
-      "integrity": "sha512-3yTwiLHwgtLYRv+aS4frzsQEwHMDXkP5Z1SPM/W103TvMemVRoCIaxPYO7axnUrKhgTfPHGXzqC5umYlQail/w==",
-      "license": "MPL-2.0"
-    }
-  }
-}

package/poc/node_modules/node-firebird/.eslintrc.json

@@ -1,12 +0,0 @@
-{
-    "parserOptions": {
-        "ecmaVersion": 6,
-        "sourceType": "module",
-        "ecmaFeatures": {
-            "jsx": true
-        }
-    },
-    "rules": {
-        "semi": "error"
-    }
-}

package/poc/node_modules/node-firebird/.github/workflows/codeql.yml

@@ -1,76 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-
-on:
-  push:
-    branches: [ "master" ]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ "master" ]
-  schedule:
-    - cron: '26 2 * * 3'
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [ 'javascript' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
-        # Use only 'java' to analyze code written in Java, Kotlin or both
-        # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both
-        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-
-        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-        # queries: security-extended,security-and-quality
-
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-
-    #   If the Autobuild fails above, remove it and uncomment the following three lines.
-    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
-
-    # - run: |
-    #     echo "Run, Build Application using script"
-    #     ./location_of_script_within_repo/buildscript.sh
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
-      with:
-        category: "/language:${{matrix.language}}"

package/poc/node_modules/node-firebird/.github/workflows/node.js.yml

@@ -1,95 +0,0 @@
-name: CI
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    strategy:
-      fail-fast: false
-      matrix:        
-        node: [20, 22, 24]
-        firebird: [3, 4, 5]
-
-    steps:
-    - uses: actions/checkout@v6
-      with:
-        fetch-depth: 10
-
-    - name: Setup FirebirdSQL ${{ matrix.firebird }} container
-      run: |
-        # Create data directory
-        sudo mkdir -p /firebird/data
-        sudo chmod 755 /firebird/data
-        
-        # Start Firebird container
-        docker run -d \
-          --name firebird \
-          -e FIREBIRD_ROOT_PASSWORD="masterkey" \
-          -e FIREBIRD_CONF_WireCrypt="Enabled" \
-          -e FIREBIRD_CONF_AuthServer="Legacy_Auth;Srp;Win_Sspi" \
-          -p 3050:3050 \
-          -v /firebird/data:/firebird/data \
-          firebirdsql/firebird:${{ matrix.firebird }}
-        
-        # Wait for Firebird to be ready
-        MAX_RETRIES=30
-        RETRY_INTERVAL=2
-        echo "Waiting for Firebird to start..."
-        FIREBIRD_READY=false
-        for i in $(seq 1 $MAX_RETRIES); do
-          if docker exec firebird /opt/firebird/bin/isql -user SYSDBA -password masterkey -z 2>&1 | grep -q "ISQL Version"; then
-            echo "Firebird is ready!"
-            FIREBIRD_READY=true
-            break
-          fi
-          echo "Waiting... ($i/$MAX_RETRIES)"
-          sleep $RETRY_INTERVAL
-        done
-        
-        if [ "$FIREBIRD_READY" = false ]; then
-          echo "ERROR: Firebird failed to start within the timeout period"
-          docker ps -a
-          docker logs firebird
-          exit 1
-        fi
-        
-        # Verify Firebird is running
-        docker ps -a
-        docker logs firebird
-
-    - name: Use Node.js ${{ matrix.node }}
-      uses: actions/setup-node@v3
-      with:
-        node-version: ${{ matrix.node }}
-
-
-    - name: Build
-      shell: bash
-      run: |
-        npm ci         
-
-    - name: Test (Linux)      
-      run: |
-        export FIREBIRD_DATA=/firebird/data
-        export FIREBIRD_DEBUG=1
-        npm test
-
-    - name: Show Firebird log on failure
-      if: failure()
-      run: |
-        echo "=========================================="
-        echo "Firebird Server Log (last 100 lines):"
-        echo "=========================================="
-        docker exec firebird tail -n 100 /firebird/log/firebird.log || echo "Could not read firebird.log"
-        echo ""
-        echo "=========================================="
-        echo "Docker container status:"
-        echo "=========================================="
-        docker ps -a
-        echo ""
-        echo "=========================================="
-        echo "Docker container logs:"
-        echo "=========================================="
-        docker logs firebird --tail 50

package/poc/node_modules/node-firebird/BIGINT_MIGRATION.md

@@ -1,374 +0,0 @@
-# BigInt Migration: Replacing `big-integer` with Native BigInt
-
-## Overview
-
-This document describes the migration from the third-party `big-integer` npm package to JavaScript's
-built-in `BigInt` primitive in `node-firebird`'s SRP authentication implementation.  The change
-removes a runtime dependency, fixes a critical authentication bug that caused connection failures, and
-improves SRP computation performance.
-
----
-
-## Background: Why `big-integer` Was Used
-
-Firebird SRP authentication requires **1024-bit modular arithmetic** (modular exponentiation, multiplication,
-addition, subtraction and comparison over numbers up to ~309 decimal digits).  JavaScript historically
-lacked a built-in arbitrary-precision integer type, so the `big-integer` library was used to fill that gap.
-
-Node.js 10.3 (May 2018) shipped native `BigInt` support as a V8 feature flag; Node.js 10.4 (June 2018)
-enabled it by default.  Node.js 10.x became LTS ("Dubnium") in October 2018.
-`node-firebird` targets Node.js ≥ 10, so the `big-integer` library is now entirely redundant.
-
----
-
-## The Problem: Three Root Causes of Authentication Failure
-
-### 1. Variable Shadowing in `connection.js`
-
-`lib/wire/connection.js` contained:
-
-```js
-const BigInt = require('big-integer');
-```
-
-This line **shadowed the global `BigInt` constructor**.  Any subsequent call to `BigInt(...)` in that
-file created a `big-integer` library object instead of a native primitive, including the server public-key
-parsing:
-
-```js
-// This line used the big-integer constructor, NOT the native one
-public: BigInt('0x' + d.buffer.slice(keyStart).toString('utf8'))
-```
-
-### 2. Incorrect Hex Parsing by `big-integer`
-
-The `big-integer` library uses **base-10 (decimal)** by default and does **not** recognise the `0x`
-prefix as hexadecimal:
-
-```js
-const bigInteger = require('big-integer');
-
-bigInteger('0xff')        // → 0   (wrong! silently returns 0)
-bigInteger('0xff', 16)    // → 0   (still wrong, the 0x prefix confuses the parser)
-bigInteger('ff', 16)      // → 255 (correct, but requires stripping the prefix manually)
-```
-
-Contrast with native BigInt:
-
-```js
-BigInt('0xff')   // → 255n  (correct)
-BigInt('0xFF')   // → 255n  (correct)
-```
-
-Passing `'0x' + hexKey` to the `big-integer` constructor silently produced **zero**, meaning
-the server's public key `B` was treated as `0n` for the rest of the handshake.
-
-### 3. Data Corruption via Decimal/Hex Base Mismatch
-
-Even in code paths that called the `big-integer` constructor correctly (e.g. `BigInt(hexStr, 16)`),
-the resulting library object could corrupt data when mixed with `lib/srp.js` helpers.
-
-`toBigInt` in `lib/srp.js` converts inputs to a string and prepends `'0x'`:
-
-```js
-// lib/srp.js toBigInt helper (original)
-const str = String(hex);          // big-integer.toString() returns DECIMAL
-return BigInt('0x' + str);        // interprets DECIMAL digits as HEX!
-```
-
-Example of the corruption:
-
-| Actual value | `big-integer.toString()` | `BigInt('0x' + …)` (native) | Decimal result |
-|---|---|---|---|
-| 16 | `"16"` | `BigInt('0x16')` | **22** (wrong) |
-| 255 | `"255"` | `BigInt('0x255')` | **597** (wrong) |
-| 1024 | `"1024"` | `BigInt('0x1024')` | **4132** (wrong) |
-
-This mismatch meant the client and server computed mathematically different session keys, so
-the M1 proof verification always failed and the connection was rejected.
-
----
-
-## The Fix: What Changed in Each File
-
-### `lib/wire/connection.js`
-
-**Removed** the shadowing line:
-
-```diff
--const BigInt = require('big-integer');
-```
-
-This one-line removal is the **core fix**.  With the shadowing gone, every `BigInt(...)` call in the
-file correctly uses the native constructor, which properly parses `0x`-prefixed hex strings.
-
-### `lib/srp.js`
-
-Replaced every `big-integer` method call with a native-BigInt equivalent.  The SRP *algorithm* is
-unchanged; only the arithmetic notation changed.
-
-| Before (`big-integer`) | After (native BigInt) |
-|---|---|
-| `require('big-integer')` | *(removed)* |
-| `BigInt(val, 16)` | `BigInt('0x' + val)` |
-| `a.multiply(b)` | `a * b` |
-| `a.add(b)` | `a + b` |
-| `a.subtract(b)` | `a - b` |
-| `a.mod(n)` | `a % n` |
-| `a.modPow(e, m)` | `modPow(a, e, m)` (helper added) |
-| `a.lesser(b)` | `a < b` |
-| `BigInt.isInstance(x)` | `typeof x === 'bigint'` |
-| `x.toString(16)` | `x.toString(16)` *(unchanged)* |
-
-A `modPow(base, exp, mod)` helper function was added at the bottom of the file (see
-[The `modPow` Implementation](#the-modpow-implementation) below).
-
-The `toBigInt` helper was also updated.  Previously it called `String(hex)` on its argument, which
-would produce a decimal string for a `big-integer` object.  Now it branches on `Buffer.isBuffer`:
-
-```js
-// After
-function toBigInt(hex) {
-    return BigInt('0x' + (Buffer.isBuffer(hex) ? hex.toString('hex') : hex));
-}
-```
-
-### `test/srp.js`
-
-```diff
--const bigInt = require('big-integer');
-
--const DEBUG_PRIVATE_KEY = bigInt('60975527035CF2AD...', 16);
-+const DEBUG_PRIVATE_KEY = BigInt('0x60975527035CF2AD...');
-
--assert.ok(keys.public.equals(EXPECT_CLIENT_KEY));
-+assert.ok(keys.public === EXPECT_CLIENT_KEY);
-```
-
-### `package.json` and `package-lock.json`
-
-The `big-integer` dependency was removed:
-
-```diff
--    "big-integer": "^1.6.51",
-```
-
-This shrinks the installed package tree by one package and eliminates a maintenance burden.
-
----
-
-## The `modPow` Implementation
-
-The helper implements **binary (square-and-multiply) modular exponentiation**, which avoids
-computing `base^exp` as a full integer before reducing modulo `mod`.  This is critical: a
-1024-bit base raised to a 1024-bit exponent would produce a ~2 million-bit intermediate value
-before reduction.
-
-```js
-/**
- * Calculates (base ^ exp) % mod using native BigInt.
- * Uses the square-and-multiply (binary) algorithm for efficiency.
- *
- * @param {bigint} base
- * @param {bigint} exp  - must be non-negative
- * @param {bigint} mod
- * @returns {bigint}
- */
-function modPow(base, exp, mod) {
-    let result = 1n;
-    base = base % mod;          // reduce base before starting
-    while (exp > 0n) {
-        if (exp & 1n) {         // if current bit is set
-            result = (result * base) % mod;
-        }
-        base = (base * base) % mod;  // square
-        exp >>= 1n;                  // shift to next bit
-    }
-    return result;
-}
-```
-
-**Algorithm walkthrough** for `modPow(2n, 10n, 1000n)`:
-
-| `exp` (binary) | `exp & 1n` | `result` | `base` |
-|---|---|---|---|
-| `1010` | 0 | 1 | 4 |
-| `101` | 1 | 4 | 16 |
-| `10` | 0 | 4 | 256 |
-| `1` | 1 | `4 * 256 % 1000 = 24` | 65536 |
-
-Result: `24`; check: `2^10 = 1024`, `1024 % 1000 = 24` ✓
-
-### Correctness Property
-
-The algorithm satisfies the invariant: `result * base^exp ≡ base_original^exp_original (mod mod)`
-at every loop iteration, which ensures the final `result` (when `exp = 0`) holds the correct answer.
-
----
-
-## Performance Comparison
-
-The `big-integer` library is pure JavaScript using string-based decimal arithmetic.  Native BigInt
-uses the V8 engine's C++ arbitrary-precision integer library (based on GMP/libtommath), which applies
-hardware multiply instructions directly.
-
-Typical timings for one `modPow(g, a, N)` call on a 1024-bit group (measured on an M2 MacBook Pro):
-
-| Implementation | Time (approx.) |
-|---|---|
-| `big-integer` (v1.6.51) | 30–120 ms |
-| Native `BigInt` (Node.js 20) | 1–3 ms |
-
-For an SRP handshake, `modPow` is called 3–4 times per authentication:
-- `clientSeed`: 1× modPow (`A = g^a mod N`)
-- `clientProof`: 2× modPow (`g^x mod N`, then `(B - kg^x)^(a+ux) mod N`)
-
-The total wall-clock time for SRP drops from **~200 ms** to **~5 ms** on typical hardware.  This
-matters most on CI runners, which are often virtualised and resource-constrained.
-
----
-
-## Security Implications
-
-Replacing a pure-JavaScript library with a native implementation has the following security implications:
-
-1. **No regression**: The same SRP-6a algorithm is implemented; only the arithmetic engine changed.
-2. **Fewer supply-chain risks**: One fewer npm package means one fewer potential malicious update path.
-3. **Constant-time properties**: Neither `big-integer` nor native `BigInt` provides guaranteed
-   constant-time arithmetic, so timing side-channel attacks against SRP remain theoretically possible.
-   This was true before and after the migration and is not specific to this change.
-4. **M2 not validated**: `node-firebird` does not verify the server's M2 proof (see `SRP_PROTOCOL.md`).
-   This is unchanged and is a separate concern.
-
----
-
-## Test Private-Key Size Constraint
-
-### Root Cause of Flaky Tests with Random 1024-bit Keys
-
-`clientSession` in `lib/srp.js` reduces the client exponent modulo `PRIME.N`:
-
-```js
-var ux  = (u * x) % PRIME.N;
-var aux = (a + ux) % PRIME.N;   // ← reduction
-```
-
-The `big-integer` library applied the identical reduction:
-
-```js
-var ux  = u.multiply(x).mod(PRIME.N);
-var aux = a.add(ux).mod(PRIME.N);  // ← same reduction
-```
-
-Both implementations are therefore **identical in behaviour**.
-
-When the client private key `a` is generated as a random 1024-bit number (128 bytes) there is a ~10%
-chance that `a >= PRIME.N` (since `N ≈ 0.9 × 2^1024`).  Combined with `ux < N`, the sum `a + ux`
-can exceed `N`, causing the `% N` reduction to change the effective exponent.  The server side
-(`serverSession`) does **not** apply the same reduction to `b`, so the two session secrets diverge.
-
-### Why this doesn't affect real Firebird authentication
-
-In a real Firebird SRP handshake the client private key is the **only** place where `a` appears, and
-it enters the protocol as `A = g^a mod N`.  The real Firebird server therefore only ever "sees" `A`,
-not `a` itself.  Node.js generates `a` from `crypto.randomBytes(128)`, a 1024-bit value.  When
-`a < N` (~90% of the time) the reduction is a no-op and auth succeeds.  When `a >= N`, the effective
-client exponent changes and auth would fail — this is a pre-existing edge case shared by both the
-`big-integer` and native-BigInt implementations.
-
-### Why tests must use small (< N) private keys
-
-The unit-test helper `serverSession` (used only for testing) mirrors what the real Firebird server
-does: it uses the server private key `b` **without** reduction.  This means that test vectors must
-ensure `a + ux < N` to avoid the divergence.
-
-All test private keys in `test/srp.js` are **256-bit** values — far smaller than the 1024-bit
-`PRIME.N` — so `a + ux < N` always holds and every test is deterministic.
-
-```js
-// ✓ correct — 256-bit key, always << PRIME.N
-const TEST_CLIENT_1 = BigInt('0x3138bb9bc78df27c...aedd3');
-
-// ✗ flaky — 1024-bit random key, ~12% chance of a+ux >= N
-var clientKeys = Srp.clientSeed();  // DO NOT use this in assertions
-```
-
----
-
-## Verifying the Fix
-
-### 1. Unit Tests (offline, no Firebird required)
-
-```bash
-# Run the SRP unit tests
-npx vitest run test/srp.js
-```
-
-Expected output (all tests pass):
-
-```
- ✓ test/srp.js (19 tests)
-   ✓ hexPad helper (3)
-   ✓ clientSeed (2)
-   ✓ serverSeed (2)
-   ✓ Test Srp client (12)
-```
-
-### 2. Mock-Server Tests (offline, no Firebird required)
-
-```bash
-npx vitest run test/mock-server.js
-```
-
-These tests run a full SRP handshake over a TCP loopback against a minimal in-process mock server,
-exercising FB3 (Protocol 14), FB4 (Protocol 16) and FB5 (Protocol 17) code paths.
-
-### 3. Integration Tests (real Firebird required)
-
-Start Firebird with SRP enabled (Docker example):
-
-```bash
-docker run -d \
-  --name firebird \
-  -e FIREBIRD_ROOT_PASSWORD="masterkey" \
-  -e FIREBIRD_CONF_WireCrypt="Enabled" \
-  -e FIREBIRD_CONF_AuthServer="Legacy_Auth;Srp;Win_Sspi" \
-  -p 3050:3050 \
-  firebirdsql/firebird:5
-
-npm test
-```
-
-### 4. Debug Timing
-
-```bash
-FIREBIRD_DEBUG=1 npm test 2>&1 | grep fb-debug
-```
-
-With native BigInt you should see sub-10 ms values for both operations:
-
-```
-[fb-debug] srp.clientSeed: 2ms
-[fb-debug] srp.clientProof(sha1): 4ms
-```
-
----
-
-## Relationship with `SRP_PROTOCOL.md`
-
-[`SRP_PROTOCOL.md`](SRP_PROTOCOL.md) describes the full SRP wire-protocol sequence, opcodes, BLR data
-formats, and timing troubleshooting.  This document focuses specifically on the `big-integer` →
-native `BigInt` migration.
-
----
-
-## References
-
-- [MDN: `BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
-- [V8 blog: BigInt — arbitrary-precision integers in JavaScript](https://v8.dev/blog/bigint)
-- [npm: `big-integer`](https://www.npmjs.com/package/big-integer)
-- [RFC 2945: The SRP Authentication and Key Exchange System](https://www.ietf.org/rfc/rfc2945.txt)
-- [`lib/srp.js`](lib/srp.js) — SRP implementation
-- [`lib/wire/connection.js`](lib/wire/connection.js) — wire protocol / SRP handshake
-- [`test/srp.js`](test/srp.js) — unit tests
-- [`SRP_PROTOCOL.md`](SRP_PROTOCOL.md) — full SRP protocol reference