nusadb 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# nusadb — Node.js / TypeScript driver for NusaDB
+
+A zero-dependency Node.js driver (with first-class TypeScript typings) that speaks
+the [Nusa Wire Protocol](../../docs/wire-protocol.md) (`PROTOCOL_VERSION 1.1`)
+directly over a socket. SCRAM-SHA-256 uses Node's built-in `crypto`.
+
+## Install
+
+```bash
+npm install nusadb
+```
+
+Requires Node 16+.
+
+## Usage
+
+```js
+const { connect } = require('nusadb');
+
+(async () => {
+  const conn = await connect({ host: '127.0.0.1', port: 5678, user: 'nusa-root', database: 'nusadb' });
+
+  await conn.query('CREATE TABLE t (id INT NOT NULL, name TEXT)');
+  await conn.query('INSERT INTO t VALUES ($1, $2)', [1, 'alice']);
+
+  const res = await conn.query('SELECT id, name FROM t WHERE id = $1', [1]);
+  console.log(res.rows);        // [[1, 'alice']]  (INT -> number, TEXT -> string)
+  console.log(res.columns);     // ['id', 'name']
+  console.log(res.columnTypes); // ['INT', 'TEXT']  (protocol 1.1 typed metadata)
+
+  await conn.close();
+})();
+```
+
+### Column types
+
+The driver negotiates protocol `minor = 1`, so `query()` returns `columnTypes`
+alongside `columns` — a canonical type name per column (`'INT'`, `'TEXT'`,
+`'BOOL'`, `'TIMESTAMP'`, `'NUMERIC'`, …; see `wire-protocol.md` §9.2). Against a
+1.0 server (which has no typed metadata) every entry is `null`.
+
+`query()` decodes each cell to its natural JS type by that tag, following mainstream Node SQL driver
+conventions:
+
+| NusaDB type | JS type |
+| --- | --- |
+| `BOOL` | `boolean` |
+| `INT` | `number` (a 64-bit value beyond `Number.MAX_SAFE_INTEGER` becomes a `BigInt`, lossless) |
+| `FLOAT` | `number` |
+| `DATE` / `TIMESTAMP` / `TIMESTAMPTZ` | `Date` |
+| `JSON` | parsed object |
+| `ARRAY` | `Array` (elements stay strings — the wire array tag carries no element type) |
+| `BYTEA` | `Buffer` (and a `Buffer` parameter binds as the `\x<hex>` form the server coerces into BYTEA) |
+| `NUMERIC` / `UUID` / `TIME` / `TIMETZ` / `INTERVAL` / `TEXT` | `string` (no lossless native JS type) |
+
+A value that does not parse as its tag falls back to the raw string, so an unexpected wire form
+never throws mid-decode. Against a 1.0 (untyped) server every column stays a string.
+
+TypeScript typings ship in `src/index.d.ts`:
+
+```ts
+import { connect, QueryResult } from 'nusadb';
+const conn = await connect({ port: 5678, user: 'nusa-root', database: 'nusadb' });
+const res: QueryResult = await conn.query('SELECT 1');
+```
+
+### Parameters
+
+Placeholders are positional **`$1`, `$2`, …**. Pass values as the second argument;
+`null` is SQL `NULL`. Values are sent in the wire text format. Result cells are
+returned as strings (`null` for SQL NULL).
+
+### Prepared statements
+
+```js
+const stmt = await conn.prepare('INSERT INTO t VALUES ($1, $2)');
+await stmt.execute([1, 'a']);
+await stmt.execute([2, 'b']);
+```
+
+### Batch (bulk insert/update)
+
+`conn.executeMany(sql, paramSets)` runs one statement once per parameter set, reusing a single
+prepared statement. It returns `{ rowCount, counts }` (`counts[i]` is the i-th set's affected-row
+count). The wire protocol has no batch pipeline, so this is N round-trips, not one.
+
+```js
+const { rowCount } = await conn.executeMany('INSERT INTO t VALUES ($1, $2)', [
+  [1, 'a'],
+  [2, 'b'],
+  [3, 'c'],
+]);
+```
+
+### Bulk load / export (`COPY`)
+
+For high-throughput load/export, `copyIn` / `copyOut` drive the `COPY` sub-protocol — one round-trip
+for the whole dataset. Move bytes in the server's text format (tab-delimited fields, `\N` for SQL
+`NULL`, one row per line); you write the `COPY` statement with any `WITH (...)` options.
+
+```js
+// Bulk load from a Buffer or string.
+const loaded = await conn.copyIn('COPY t (id, name) FROM STDIN', '1\talice\n2\t\\N\n');
+
+// Bulk export: resolves to { rowCount, data } (data is a Buffer).
+const { rowCount, data } = await conn.copyOut('COPY t TO STDOUT');
+```
+
+A `COPY` the server refuses (bad SQL, an RLS-protected table) rejects; the connection stays usable.
+
+### Pool
+
+```js
+const { Pool } = require('nusadb');
+const pool = new Pool({ maxSize: 10, port: 5678, user: 'nusa-root', database: 'nusadb' });
+await pool.withConnection((c) => c.query('SELECT 1'));
+```
+
+### Authentication & TLS
+
+Pass `password` for a server started with `--auth-user`; the driver runs
+SCRAM-SHA-256 and verifies the server signature (mutual auth). Pass `tls` (options
+forwarded to `tls.connect`) for an implicit TLS 1.3 connection.
+
+## Transactions
+
+By default the connection is in **autocommit** mode: the server runs each statement
+on its own implicit transaction. Pass `autocommit: false` for the standard
+transactional model — the driver sends `BEGIN` lazily before the first statement,
+and `commit()` / `rollback()` end the transaction:
+
+```js
+const conn = await connect({ port, user: 'u', database: 'nusadb', autocommit: false });
+await conn.query("INSERT INTO t VALUES (1, 'alice')");
+await conn.rollback();   // the insert is discarded
+await conn.query("INSERT INTO t VALUES (2, 'bob')");
+await conn.commit();     // this one persists
+```
+
+Inside a transaction, `savepoint(name)` marks a point you can later undo to with
+`rollbackToSavepoint(name)` (the transaction stays open) or forget with `releaseSavepoint(name)`:
+
+```js
+await conn.query("INSERT INTO t VALUES (1, 'alice')");
+await conn.savepoint('sp1');
+await conn.query("INSERT INTO t VALUES (2, 'bob')");
+await conn.rollbackToSavepoint('sp1'); // undoes (2), keeps (1); the transaction continues
+await conn.commit();
+```
+
+## Notifications (LISTEN/NOTIFY)
+
+`listen(channel)` subscribes the connection; a `notify(channel, payload)` from any connection on the
+same database is then delivered asynchronously. Collect delivered notifications with `poll(timeoutMs)`
+(`0` polls without blocking, `null` blocks) or drain the ones buffered during other queries with
+`notifications()`:
+
+```js
+await conn.listen('orders');
+// ... elsewhere: await other.notify('orders', '42');
+const note = await conn.poll(5000); // -> { pid, channel, payload }, or null on timeout
+console.log(note.channel, note.payload);
+await conn.unlisten('orders');
+```
+
+## Tests
+
+```bash
+cargo build -p nusadb-server
+node drivers/node/test/test.js
+```
+
+The tests boot a real `nusadb-server` (ephemeral port, honouring
+`CARGO_TARGET_DIR`) and cover simple/parameterised/prepared queries, errors, the
+pool, and SCRAM auth.
+
+## License
+
+Apache-2.0.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "nusadb",
+  "version": "0.1.0",
+  "description": "Node.js / TypeScript driver for NusaDB (Nusa Wire Protocol)",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "nusadb",
+    "database",
+    "sql",
+    "driver"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nusadb/node.git"
+  },
+  "homepage": "https://github.com/nusadb/node#readme",
+  "bugs": {
+    "url": "https://github.com/nusadb/node/issues"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/connection.js

@@ -0,0 +1,695 @@
+'use strict';
+
+const net = require('net');
+const tls = require('tls');
+const { encode, Reader, B, AUTH, HEADER_LEN, MAX_FRAME_LEN, SCRAM_MECHANISM, typeName } = require('./protocol');
+const scram = require('./scram');
+
+/** A server error carrying a 5-character SQLSTATE (docs/wire-protocol.md §14). */
+class NusaError extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.name = 'NusaError';
+    this.code = code;
+    this.sqlMessage = message;
+  }
+}
+
+/** Reads length-delimited frames off a socket and hands them out one at a time. */
+class FrameReader {
+  constructor(socket) {
+    this._buf = Buffer.alloc(0);
+    this._queue = [];
+    this._waiters = [];
+    this._error = null;
+    socket.on('data', (chunk) => this._onData(chunk));
+    socket.on('error', (e) => this._fail(e));
+    socket.on('close', () => this._fail(new Error('nusadb: connection closed')));
+  }
+
+  _onData(chunk) {
+    this._buf = Buffer.concat([this._buf, chunk]);
+    while (this._buf.length >= HEADER_LEN) {
+      const total = this._buf.readUInt32BE(1);
+      if (total < HEADER_LEN || total > MAX_FRAME_LEN) {
+        this._fail(new Error(`nusadb: invalid frame length ${total}`));
+        return;
+      }
+      if (this._buf.length < total) break;
+      const msg = { type: this._buf[0], payload: Buffer.from(this._buf.subarray(HEADER_LEN, total)) };
+      this._buf = this._buf.subarray(total);
+      const waiter = this._waiters.shift();
+      if (waiter) waiter.resolve(msg);
+      else this._queue.push(msg);
+    }
+  }
+
+  _fail(err) {
+    if (this._error) return;
+    this._error = err;
+    for (const w of this._waiters) w.reject(err);
+    this._waiters = [];
+  }
+
+  read() {
+    if (this._queue.length) return Promise.resolve(this._queue.shift());
+    if (this._error) return Promise.reject(this._error);
+    return new Promise((resolve, reject) => this._waiters.push({ resolve, reject }));
+  }
+
+  /** Read the next frame, or resolve to `null` after `ms` if none arrives. `ms === null` blocks.
+   * On timeout the pending waiter is removed so it never swallows a later frame. */
+  readWithTimeout(ms) {
+    if (this._queue.length) return Promise.resolve(this._queue.shift());
+    if (this._error) return Promise.reject(this._error);
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      const waiter = {
+        resolve: (msg) => {
+          if (timer) clearTimeout(timer);
+          resolve(msg);
+        },
+        reject: (err) => {
+          if (timer) clearTimeout(timer);
+          reject(err);
+        },
+      };
+      this._waiters.push(waiter);
+      if (ms !== null && ms !== undefined) {
+        timer = setTimeout(() => {
+          const idx = this._waiters.indexOf(waiter);
+          if (idx >= 0) this._waiters.splice(idx, 1);
+          resolve(null);
+        }, ms);
+      }
+    });
+  }
+}
+
+/** Quotes a savepoint identifier so an arbitrary name is emitted safely; the server folds a quoted
+ * identifier to its literal value, so the same quoting matches across SAVEPOINT/ROLLBACK/RELEASE. */
+function quoteIdentifier(name) {
+  if (typeof name !== 'string') {
+    throw new TypeError('nusadb: savepoint name must be a string');
+  }
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** Quotes a string as a SQL literal (`'…'`, doubling `'`) — used for a NOTIFY payload. */
+function quoteLiteral(text) {
+  return `'${String(text).replace(/'/g, "''")}'`;
+}
+
+/** Decode a NotificationResponse body: `[pid:u32][channel:str][payload:str]`. */
+function decodeNotification(r) {
+  return { pid: r.u32(), channel: r.str(), payload: r.str() };
+}
+
+function encodeParam(value) {
+  if (value === null || value === undefined) return null;
+  // A Buffer binds as the BYTEA text form `\x<hex>`, which the server coerces into a BYTEA column.
+  if (Buffer.isBuffer(value)) return Buffer.from(`\\x${value.toString('hex')}`, 'utf8');
+  if (typeof value === 'boolean') return Buffer.from(value ? 'true' : 'false');
+  return Buffer.from(String(value), 'utf8');
+}
+
+/** Decode the BYTEA text form `\x<hex>` to a Buffer. */
+function decodeBytea(text) {
+  return Buffer.from(text.startsWith('\\x') ? text.slice(2) : text, 'hex');
+}
+
+function decodeBool(text) {
+  if (text === 'true' || text === 't' || text === '1') return true;
+  if (text === 'false' || text === 'f' || text === '0') return false;
+  throw new Error('not a bool');
+}
+
+function decodeInt(text) {
+  const n = Number(text);
+  // A 64-bit value beyond JS's safe-integer range becomes a BigInt to avoid silent precision loss;
+  // BigInt() throws on a non-integer, so the caller falls back to the raw text.
+  return Number.isSafeInteger(n) ? n : BigInt(text);
+}
+
+function decodeFloat(text) {
+  const n = Number(text);
+  if (Number.isNaN(n) && text !== 'NaN') throw new Error('not a float');
+  return n;
+}
+
+function decodeTimestamp(text) {
+  // Make the wire text ISO-parseable: space -> 'T', and pad a bare +HH offset to +HH:00.
+  const iso = text.replace(' ', 'T').replace(/([+-]\d{2})$/, '$1:00');
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) throw new Error('not a date');
+  return d;
+}
+
+function decodeDate(text) {
+  const d = new Date(text);
+  if (Number.isNaN(d.getTime())) throw new Error('not a date');
+  return d;
+}
+
+/** Parse a SQL array literal (`{a,b,c}`, possibly nested, quoted, or with `NULL`) to a JS
+ * array. Elements stay strings (the wire array tag carries no per-element type); a quoted element is
+ * unescaped and an unquoted `NULL` becomes `null`. */
+function parseArray(text) {
+  let pos = 0;
+  function parseList() {
+    if (text[pos] !== '{') throw new Error('not an array');
+    pos += 1;
+    const items = [];
+    if (text[pos] === '}') {
+      pos += 1;
+      return items;
+    }
+    for (;;) {
+      const ch = text[pos];
+      if (ch === '{') items.push(parseList());
+      else if (ch === '"') items.push(parseQuoted());
+      else items.push(parseUnquoted());
+      const sep = text[pos];
+      if (sep === ',') {
+        pos += 1;
+        continue;
+      }
+      if (sep === '}') {
+        pos += 1;
+        break;
+      }
+      throw new Error('malformed array');
+    }
+    return items;
+  }
+  function parseQuoted() {
+    pos += 1; // opening quote
+    let out = '';
+    while (text[pos] !== '"') {
+      if (pos >= text.length) throw new Error('unterminated array element');
+      if (text[pos] === '\\') pos += 1;
+      out += text[pos];
+      pos += 1;
+    }
+    pos += 1; // closing quote
+    return out;
+  }
+  function parseUnquoted() {
+    const start = pos;
+    while (pos < text.length && text[pos] !== ',' && text[pos] !== '}') pos += 1;
+    const token = text.slice(start, pos);
+    return token === 'NULL' ? null : token;
+  }
+  const result = parseList();
+  if (pos !== text.length) throw new Error('trailing array data');
+  return result;
+}
+
+// Maps a RowDescriptionTyped type name (protocol 1.1) to the function that turns wire text into a
+// typed JS value, following mainstream Node SQL driver conventions. NUMERIC, UUID, TIME/TIMETZ, INTERVAL, and
+// TEXT stay strings (no lossless native JS type); BYTES is handled separately in `decodeCell`.
+const TYPED_DECODERS = {
+  BOOL: decodeBool,
+  INT: decodeInt,
+  FLOAT: decodeFloat,
+  JSON: JSON.parse,
+  ARRAY: parseArray,
+  DATE: decodeDate,
+  TIMESTAMP: decodeTimestamp,
+  TIMESTAMPTZ: decodeTimestamp,
+};
+
+/** Decode one text-format field into a typed JS value by its wire type tag (`null` for SQL NULL). A
+ * value that does not parse as its tag falls back to the raw text, so an unexpected form never throws
+ * mid-decode. */
+function decodeCell(cell, type) {
+  if (cell === null) return null;
+  if (type === 'BYTES') return decodeBytea(cell.toString('utf8'));
+  const text = cell.toString('utf8');
+  const decoder = TYPED_DECODERS[type];
+  if (!decoder) return text;
+  try {
+    return decoder(text);
+  } catch {
+    return text;
+  }
+}
+
+/** One authenticated connection to a NusaDB server. */
+class Connection {
+  constructor(socket, options) {
+    this._socket = socket;
+    this._reader = new FrameReader(socket);
+    this._options = options;
+    this._counter = 0;
+    this.backendKey = null;
+    // When `autocommit` is false, a transaction is opened lazily (BEGIN) before the first statement
+    // and ended by commit()/rollback(). In autocommit mode the server runs each statement on its own.
+    this._inTxn = false;
+    // Async LISTEN/NOTIFY messages received while reading other responses; drained by notifications().
+    this._notifications = [];
+  }
+
+  /** Open, handshake, and authenticate. Returns a ready Connection. */
+  static connect(options = {}) {
+    const opts = {
+      host: '127.0.0.1',
+      port: 5678,
+      user: 'nusa-root',
+      database: 'nusadb',
+      password: 'nusa-root',
+      tls: null,
+      autocommit: true,
+      ...options,
+    };
+    return new Promise((resolve, reject) => {
+      const onError = (e) => reject(e);
+      const socket = opts.tls
+        ? tls.connect({ host: opts.host, port: opts.port, ...opts.tls }, onConnect)
+        : net.connect({ host: opts.host, port: opts.port }, onConnect);
+      // Disable Nagle's algorithm: this is a request/response protocol, so
+      // coalescing small frames only adds delayed-ACK latency per round-trip.
+      socket.setNoDelay(true);
+      socket.once('error', onError);
+      function onConnect() {
+        socket.removeListener('error', onError);
+        const conn = new Connection(socket, opts);
+        conn._handshake().then(() => resolve(conn)).catch((err) => {
+          socket.destroy();
+          reject(err);
+        });
+      }
+    });
+  }
+
+  _send(frame) {
+    this._socket.write(frame);
+  }
+
+  /** Send a transaction-control statement (BEGIN/COMMIT/ROLLBACK) and drain to ReadyForQuery. */
+  async _runControl(sql) {
+    this._send(encode.query(sql));
+    await this._collect();
+  }
+
+  /** Open a transaction before the first statement when not in autocommit mode. */
+  async _beginIfNeeded() {
+    if (!this._options.autocommit && !this._inTxn) {
+      await this._runControl('BEGIN');
+      this._inTxn = true;
+    }
+  }
+
+  /** Commit the current transaction. A no-op in autocommit mode or with no open transaction. */
+  async commit() {
+    if (!this._options.autocommit && this._inTxn) {
+      await this._runControl('COMMIT');
+      this._inTxn = false;
+    }
+  }
+
+  /** Roll back the current transaction, discarding its uncommitted changes. A no-op in autocommit
+   * mode or with no open transaction. */
+  async rollback() {
+    if (!this._options.autocommit && this._inTxn) {
+      await this._runControl('ROLLBACK');
+      this._inTxn = false;
+    }
+  }
+
+  /** Establish a savepoint inside the open transaction (SAVEPOINT name) — a named marker you can
+   * later roll back to without ending the transaction. Requires autocommit off; a BEGIN is opened
+   * lazily if none is active yet. */
+  async savepoint(name) {
+    if (this._options.autocommit) {
+      throw new Error('nusadb: cannot set a savepoint in autocommit mode');
+    }
+    await this._beginIfNeeded();
+    await this._runControl(`SAVEPOINT ${quoteIdentifier(name)}`);
+  }
+
+  /** Roll back to a savepoint (ROLLBACK TO SAVEPOINT name); the transaction stays open. */
+  async rollbackToSavepoint(name) {
+    if (this._options.autocommit || !this._inTxn) {
+      throw new Error('nusadb: no active transaction to roll back to a savepoint');
+    }
+    await this._runControl(`ROLLBACK TO SAVEPOINT ${quoteIdentifier(name)}`);
+  }
+
+  /** Release (forget) a savepoint (RELEASE SAVEPOINT name), keeping its work. */
+  async releaseSavepoint(name) {
+    if (this._options.autocommit || !this._inTxn) {
+      throw new Error('nusadb: no active transaction to release a savepoint');
+    }
+    await this._runControl(`RELEASE SAVEPOINT ${quoteIdentifier(name)}`);
+  }
+
+  /** Subscribe to asynchronous notifications on `channel` (LISTEN channel). Collect them with
+   * notifications() or poll(). */
+  async listen(channel) {
+    await this._runControl(`LISTEN ${quoteIdentifier(channel)}`);
+  }
+
+  /** Stop listening on `channel` (UNLISTEN channel), or on every channel when `channel` is omitted
+   * (UNLISTEN *). */
+  async unlisten(channel) {
+    const target = channel === undefined || channel === null ? '*' : quoteIdentifier(channel);
+    await this._runControl(`UNLISTEN ${target}`);
+  }
+
+  /** Send a notification on `channel` with an optional `payload` (NOTIFY channel[, 'payload']). */
+  async notify(channel, payload) {
+    let sql = `NOTIFY ${quoteIdentifier(channel)}`;
+    if (payload !== undefined && payload !== null) sql += `, ${quoteLiteral(payload)}`;
+    await this._runControl(sql);
+  }
+
+  /** Return and clear the notifications already received (buffered while reading other responses).
+   * Does not touch the socket — use poll() to wait for new ones. */
+  notifications() {
+    const pending = this._notifications;
+    this._notifications = [];
+    return pending;
+  }
+
+  /** Wait up to `timeoutMs` for the next notification (a buffered one is returned immediately; `null`
+   * on timeout). `timeoutMs` of `null` blocks until one arrives; `0` polls without blocking. Only
+   * meaningful after listen(). */
+  async poll(timeoutMs = 0) {
+    if (this._notifications.length) return this._notifications.shift();
+    const msg = await this._reader.readWithTimeout(timeoutMs);
+    if (msg === null) return null;
+    if (msg.type === B.NOTIFICATION) return decodeNotification(new Reader(msg.payload));
+    if (msg.type === B.ERROR) {
+      const r = new Reader(msg.payload);
+      throw new NusaError(r.str(), r.str());
+    }
+    throw new Error(`nusadb: unexpected message ${msg.type} while polling for notifications`);
+  }
+
+  async _read() {
+    return this._reader.read();
+  }
+
+  async _handshake() {
+    this._send(encode.startup(this._options.user, this._options.database));
+    for (;;) {
+      const msg = await this._read();
+      if (msg.type === B.READY) return;
+      if (msg.type === B.ERROR) {
+        const r = new Reader(msg.payload);
+        throw new NusaError(r.str(), r.str());
+      }
+      if (msg.type === B.AUTH) {
+        const r = new Reader(msg.payload);
+        const sub = r.u32();
+        if (sub === AUTH.SASL) {
+          const count = r.u16();
+          const mechs = [];
+          for (let i = 0; i < count; i += 1) mechs.push(r.str());
+          await this._scram(mechs);
+        }
+      } else if (msg.type === B.BACKEND_KEY) {
+        const r = new Reader(msg.payload);
+        this.backendKey = { pid: r.u32(), secret: r.u32() };
+      }
+    }
+  }
+
+  async _scram(mechs) {
+    if (!mechs.includes(SCRAM_MECHANISM)) {
+      throw new Error('nusadb: server offered no supported SASL mechanism');
+    }
+    if (this._options.password === null || this._options.password === undefined) {
+      throw new Error('nusadb: server requires a password but none was given');
+    }
+    const { bare, full } = scram.clientFirst(this._options.user);
+    this._send(encode.saslInitial(SCRAM_MECHANISM, Buffer.from(full, 'utf8')));
+
+    let msg = await this._read();
+    if (msg.type === B.ERROR) {
+      const r = new Reader(msg.payload);
+      throw new NusaError(r.str(), r.str());
+    }
+    let r = new Reader(msg.payload);
+    if (msg.type !== B.AUTH || r.u32() !== AUTH.SASL_CONTINUE) {
+      throw new Error('nusadb: expected a SASL continue message');
+    }
+    const serverFirst = r.rest().toString('utf8');
+
+    const { final, expected } = scram.clientFinal(this._options.password, bare, serverFirst);
+    this._send(encode.saslResponse(final));
+
+    msg = await this._read();
+    if (msg.type === B.ERROR) {
+      const er = new Reader(msg.payload);
+      throw new NusaError(er.str(), er.str());
+    }
+    r = new Reader(msg.payload);
+    if (msg.type !== B.AUTH || r.u32() !== AUTH.SASL_FINAL) {
+      throw new Error('nusadb: expected a SASL final message');
+    }
+    if (!scram.verifyServerFinal(r.rest().toString('utf8'), expected)) {
+      throw new Error('nusadb: server signature did not verify');
+    }
+  }
+
+  async _collect() {
+    let columns = [];
+    // Per-column type name, parallel to `columns`. `null` for an untyped (protocol 1.0)
+    // RowDescription; a canonical type name (e.g. 'INT') for the 1.1 typed form.
+    let columnTypes = [];
+    const rows = [];
+    let tag = null;
+    let error = null;
+    for (;;) {
+      const msg = await this._read();
+      const r = new Reader(msg.payload);
+      switch (msg.type) {
+        case B.ROW_DESCRIPTION: {
+          const n = r.u16();
+          columns = [];
+          columnTypes = [];
+          for (let i = 0; i < n; i += 1) {
+            columns.push(r.str());
+            columnTypes.push(null);
+          }
+          break;
+        }
+        case B.ROW_DESCRIPTION_TYPED: {
+          const n = r.u16();
+          columns = [];
+          columnTypes = [];
+          for (let i = 0; i < n; i += 1) {
+            columns.push(r.str());
+            columnTypes.push(typeName(r.u8()));
+          }
+          break;
+        }
+        case B.DATA_ROW:
+          rows.push(r.fields());
+          break;
+        case B.COMMAND_COMPLETE:
+          tag = r.str();
+          break;
+        case B.NOTIFICATION:
+          // A pending LISTEN/NOTIFY message can lead the next query's response; buffer it.
+          this._notifications.push(decodeNotification(r));
+          break;
+        case B.ERROR:
+          error = new NusaError(r.str(), r.str());
+          break;
+        case B.READY:
+          if (error) throw error;
+          return { columns, columnTypes, rows, tag };
+        default:
+          break;
+      }
+    }
+  }
+
+  _freshName(prefix) {
+    this._counter += 1;
+    return `nusa_${prefix}_${this._counter}`;
+  }
+
+  /** Run one SQL string (simple query). Returns { columns, rows, rowCount, command }. */
+  async query(sql, params) {
+    await this._beginIfNeeded();
+    let raw;
+    if (params && params.length) {
+      const encoded = params.map(encodeParam);
+      this._send(encode.parse('', sql));
+      this._send(encode.bind('', '', encoded));
+      this._send(encode.describePortal(''));
+      this._send(encode.execute('', 0));
+      this._send(encode.sync());
+      raw = await this._collect();
+    } else {
+      this._send(encode.query(sql));
+      raw = await this._collect();
+    }
+    return shape(raw);
+  }
+
+  /** Prepare a named statement; returns a handle with .execute(params). */
+  async prepare(sql) {
+    const name = this._freshName('stmt');
+    this._send(encode.parse(name, sql));
+    this._send(encode.sync());
+    await this._collect(); // surfaces a parse error
+    const self = this;
+    return {
+      name,
+      async execute(params) {
+        await self._beginIfNeeded();
+        const encoded = (params || []).map(encodeParam);
+        const portal = self._freshName('portal');
+        self._send(encode.bind(portal, name, encoded));
+        self._send(encode.describePortal(portal));
+        self._send(encode.execute(portal, 0));
+        self._send(encode.sync());
+        return shape(await self._collect());
+      },
+    };
+  }
+
+  /**
+   * Run one statement once per parameter set, reusing a single prepared statement — the bulk
+   * insert/update path. Returns `{ rowCount, counts }`: `counts[i]` is the affected-row count of the
+   * i-th set, `rowCount` their sum. One parse, then one execute per set (the wire protocol has no
+   * batch pipeline, so this is N round-trips, not one). The first failing set rejects.
+   */
+  async executeMany(sql, paramSets) {
+    const stmt = await this.prepare(sql);
+    const counts = [];
+    let rowCount = 0;
+    for (const params of paramSets || []) {
+      const res = await stmt.execute(params);
+      const n = res.rowCount == null ? 0 : res.rowCount;
+      counts.push(n);
+      rowCount += n;
+    }
+    return { rowCount, counts };
+  }
+
+  /**
+   * Bulk-load via `COPY ... FROM STDIN` (§12.1). `data` is a Buffer or string already in the
+   * server's text format (tab-delimited fields, `\N` for SQL NULL, one row per line); it is sent in
+   * 64 KiB `CopyData` chunks. Resolves to the number of rows loaded. A refused COPY (bad SQL, an
+   * RLS-protected table) rejects; the connection stays usable.
+   */
+  async copyIn(sql, data) {
+    await this._beginIfNeeded();
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data), 'utf8');
+    this._send(encode.query(sql));
+    await this._awaitCopyStart(B.COPY_IN);
+    for (let off = 0; off < buf.length; off += 65536) {
+      this._send(encode.copyData(buf.subarray(off, Math.min(off + 65536, buf.length))));
+    }
+    this._send(encode.copyDone());
+    return this._finishCopy();
+  }
+
+  /**
+   * Bulk-export via `COPY ... TO STDOUT` (§12.2). Resolves to `{ rowCount, data }`, where `data` is a
+   * Buffer of the server's text-format rows (tab-delimited, `\N` for NULL).
+   */
+  async copyOut(sql) {
+    await this._beginIfNeeded();
+    this._send(encode.query(sql));
+    await this._awaitCopyStart(B.COPY_OUT);
+    const chunks = [];
+    for (;;) {
+      const msg = await this._read();
+      if (msg.type === B.COPY_DATA) {
+        chunks.push(msg.payload);
+      } else if (msg.type === B.COPY_DONE) {
+        break;
+      } else if (msg.type === B.ERROR) {
+        const r = new Reader(msg.payload);
+        const err = new NusaError(r.str(), r.str());
+        await this._drainToReady();
+        throw err;
+      }
+    }
+    const rowCount = await this._finishCopy();
+    return { rowCount, data: Buffer.concat(chunks) };
+  }
+
+  /** Read until the expected CopyInResponse/CopyOutResponse; a refused COPY arrives as Error then
+   * ReadyForQuery and is thrown, the connection left ready. */
+  async _awaitCopyStart(expected) {
+    let error = null;
+    for (;;) {
+      const msg = await this._read();
+      if (msg.type === expected) return;
+      if (msg.type === B.ERROR) {
+        const r = new Reader(msg.payload);
+        error = new NusaError(r.str(), r.str());
+      } else if (msg.type === B.READY) {
+        throw error || new Error('nusadb: COPY did not start');
+      }
+    }
+  }
+
+  /** Drain to ReadyForQuery, returning the row count from the `COPY <n>` command tag. */
+  async _finishCopy() {
+    let tag = null;
+    let error = null;
+    for (;;) {
+      const msg = await this._read();
+      if (msg.type === B.COMMAND_COMPLETE) {
+        tag = new Reader(msg.payload).str();
+      } else if (msg.type === B.ERROR) {
+        const r = new Reader(msg.payload);
+        error = new NusaError(r.str(), r.str());
+      } else if (msg.type === B.READY) {
+        if (error) throw error;
+        return affected(tag) || 0;
+      }
+    }
+  }
+
+  /** Best-effort resync: read and discard frames until ReadyForQuery. */
+  async _drainToReady() {
+    for (;;) {
+      const msg = await this._read();
+      if (msg.type === B.READY) return;
+    }
+  }
+
+  /** Close the connection (Terminate). */
+  async close() {
+    try {
+      this._send(encode.terminate());
+    } catch (_e) {
+      // ignore
+    }
+    this._socket.destroy();
+  }
+}
+
+function affected(tag) {
+  if (!tag) return null;
+  const last = tag.split(' ').pop();
+  const n = Number.parseInt(last, 10);
+  return Number.isNaN(n) ? null : n;
+}
+
+function shape(raw) {
+  const types = raw.columnTypes || [];
+  // Each cell decodes to its natural JS type by the column's protocol 1.1 type tag (see decodeCell).
+  const rows = raw.rows.map((fieldList) => fieldList.map((cell, i) => decodeCell(cell, types[i])));
+  return {
+    columns: raw.columns,
+    // Per-column type names (protocol 1.1, R42-B.03); each entry is a canonical type name or `null`
+    // when the server answered with the untyped (1.0) RowDescription.
+    columnTypes: raw.columnTypes || raw.columns.map(() => null),
+    rows,
+    rowCount: raw.columns.length ? rows.length : affected(raw.tag),
+    command: raw.tag,
+  };
+}
+
+module.exports = { Connection, NusaError };

package/src/index.d.ts

@@ -0,0 +1,93 @@
+// TypeScript declarations for the nusadb Node.js driver.
+
+import type { ConnectionOptions as TlsConnectionOptions } from 'tls';
+
+export interface ConnectOptions {
+  host?: string;
+  port?: number;
+  user?: string;
+  database?: string;
+  password?: string | null;
+  /** TLS options passed to `tls.connect`; omit for a plaintext connection. */
+  tls?: TlsConnectionOptions | null;
+  /**
+   * When `true` (the default), the server runs each statement on its own implicit transaction. When
+   * `false`, a transaction is opened lazily before the first statement and ended by
+   * {@link Connection.commit} / {@link Connection.rollback}.
+   */
+  autocommit?: boolean;
+}
+
+export type Param = string | number | boolean | Buffer | null | undefined;
+
+/**
+ * A decoded cell value. The driver decodes each cell to its natural JS type by the column's
+ * protocol 1.1 type tag: `BOOL` → boolean, `INT` → number (or `bigint` beyond the safe-integer
+ * range), `FLOAT` → number, `DATE`/`TIMESTAMP`/`TIMESTAMPTZ` → `Date`, `JSON` → parsed value,
+ * `ARRAY` → array, `BYTEA` → `Buffer`; `NUMERIC`/`UUID`/`TIME`/`INTERVAL`/`TEXT` stay strings.
+ * `null` is SQL NULL.
+ */
+export type Cell =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Buffer
+  | Date
+  | unknown[]
+  | Record<string, unknown>
+  | null;
+
+export interface QueryResult {
+  /** Output column names (empty for a non-row statement). */
+  columns: string[];
+  /**
+   * Per-column type name, parallel to `columns` (protocol 1.1). A canonical name such as
+   * `'INT'` / `'TEXT'` / `'TIMESTAMP'`, or `null` when the server answered with the untyped
+   * (1.0) row description.
+   */
+  columnTypes: Array<string | null>;
+  /** Rows of decoded cells (see {@link Cell}); `null` is SQL NULL. */
+  rows: Cell[][];
+  /** Row count for SELECT, affected count for DML, or null. */
+  rowCount: number | null;
+  /** The server's command tag (e.g. "SELECT 3", "INSERT 1"). */
+  command: string | null;
+}
+
+export interface PreparedStatement {
+  readonly name: string;
+  execute(params?: Param[]): Promise<QueryResult>;
+}
+
+export declare class NusaError extends Error {
+  readonly code: string;
+  readonly sqlMessage: string;
+}
+
+export declare class Connection {
+  static connect(options?: ConnectOptions): Promise<Connection>;
+  readonly backendKey: { pid: number; secret: number } | null;
+  query(sql: string, params?: Param[]): Promise<QueryResult>;
+  prepare(sql: string): Promise<PreparedStatement>;
+  /** Commit the current transaction (no-op in autocommit mode or with no open transaction). */
+  commit(): Promise<void>;
+  /** Roll back the current transaction (no-op in autocommit mode or with no open transaction). */
+  rollback(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface PoolOptions extends ConnectOptions {
+  maxSize?: number;
+}
+
+export declare class Pool {
+  constructor(options?: PoolOptions);
+  readonly idleCount: number;
+  acquire(): Promise<Connection>;
+  release(conn: Connection): void;
+  withConnection<T>(fn: (conn: Connection) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+export declare function connect(options?: ConnectOptions): Promise<Connection>;

package/src/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { Connection, NusaError } = require('./connection');
+const { Pool } = require('./pool');
+
+/**
+ * Open a connection to a NusaDB server.
+ * @param {object} options host, port, user, database, password, tls
+ * @returns {Promise<Connection>}
+ */
+function connect(options) {
+  return Connection.connect(options);
+}
+
+module.exports = { connect, Connection, Pool, NusaError };

package/src/pool.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { Connection } = require('./connection');
+
+/** A bounded async connection pool. */
+class Pool {
+  constructor(options = {}) {
+    const { maxSize = 10, ...connOptions } = options;
+    this._max = Math.max(1, maxSize);
+    this._options = connOptions;
+    this._idle = [];
+    this._live = 0;
+    this._waiters = [];
+    this._closed = false;
+  }
+
+  get idleCount() {
+    return this._idle.length;
+  }
+
+  async acquire() {
+    if (this._closed) throw new Error('nusadb: pool is closed');
+    if (this._idle.length) return this._idle.pop();
+    if (this._live < this._max) {
+      this._live += 1;
+      try {
+        return await Connection.connect(this._options);
+      } catch (err) {
+        this._live -= 1;
+        throw err;
+      }
+    }
+    return new Promise((resolve, reject) => this._waiters.push({ resolve, reject }));
+  }
+
+  release(conn) {
+    const waiter = this._waiters.shift();
+    if (waiter) {
+      waiter.resolve(conn);
+    } else {
+      this._idle.push(conn);
+    }
+  }
+
+  /** Acquire a connection, run `fn`, and always release it. */
+  async withConnection(fn) {
+    const conn = await this.acquire();
+    try {
+      return await fn(conn);
+    } finally {
+      this.release(conn);
+    }
+  }
+
+  async close() {
+    this._closed = true;
+    const idle = this._idle;
+    this._idle = [];
+    await Promise.all(idle.map((c) => c.close()));
+  }
+}
+
+module.exports = { Pool };

package/src/protocol.js

@@ -0,0 +1,233 @@
+'use strict';
+
+// Low-level Nusa Wire Protocol codec (docs/wire-protocol.md, PROTOCOL_VERSION 1.1).
+// A frame is [type:u8][len:u32][payload]; len is the total including the 5-byte
+// header. Big-endian throughout; strings are [len:u32][utf8 bytes], not null-terminated.
+
+const PROTOCOL_MAGIC = 0x4e555341; // "NUSA"
+const PROTOCOL_MAJOR = 1;
+// Protocol 1.1 (R42-B.02): request minor 1 to receive the typed RowDescription (per-column type
+// tags). A 1.0 server ignores the minor and answers with the classic untyped RowDescription, which
+// the driver still handles — so requesting 1 is safe against any server.
+const PROTOCOL_MINOR = 1;
+
+// Column type tags carried by RowDescriptionTyped (protocol 1.1, wire-protocol.md §9.2). Maps the
+// 1-byte tag to a canonical type name; an unrecognised tag (or 0x00) is treated as UNKNOWN/TEXT.
+const TYPE_TAGS = {
+  0x00: 'UNKNOWN',
+  0x01: 'BOOL',
+  0x02: 'INT',
+  0x03: 'FLOAT',
+  0x04: 'NUMERIC',
+  0x05: 'TEXT',
+  0x06: 'BYTES',
+  0x07: 'DATE',
+  0x08: 'TIME',
+  0x09: 'TIMETZ',
+  0x0a: 'TIMESTAMP',
+  0x0b: 'TIMESTAMPTZ',
+  0x0c: 'INTERVAL',
+  0x0d: 'UUID',
+  0x0e: 'JSON',
+  0x0f: 'ARRAY',
+  0x10: 'VECTOR',
+};
+
+function typeName(tag) {
+  return TYPE_TAGS[tag] || 'UNKNOWN';
+}
+const HEADER_LEN = 5;
+const MAX_FRAME_LEN = 256 * 1024 * 1024;
+const SCRAM_MECHANISM = 'SCRAM-SHA-256';
+
+// Backend message type bytes.
+const B = {
+  AUTH: 0x52, // R
+  BACKEND_KEY: 0x4b, // K
+  READY: 0x5a, // Z
+  COMMAND_COMPLETE: 0x43, // C
+  ERROR: 0x45, // E
+  ROW_DESCRIPTION: 0x54, // T
+  ROW_DESCRIPTION_TYPED: 0x79, // y (protocol 1.1)
+  DATA_ROW: 0x44, // D
+  PARSE_COMPLETE: 0x31, // 1
+  BIND_COMPLETE: 0x32, // 2
+  NO_DATA: 0x6e, // n
+  PARAMETER_DESCRIPTION: 0x74, // t
+  COPY_IN: 0x47, // G (CopyInResponse, §12.1)
+  COPY_OUT: 0x48, // H (CopyOutResponse, §12.2)
+  COPY_DATA: 0x64, // d (a COPY data chunk)
+  COPY_DONE: 0x63, // c (end of the COPY data stream)
+  NOTIFICATION: 0x41, // A (async LISTEN/NOTIFY: [pid:u32][channel:str][payload:str])
+};
+
+// Frontend message type bytes.
+const F = {
+  STARTUP: 0x53, // S
+  QUERY: 0x51, // Q
+  PARSE: 0x50, // P
+  BIND: 0x42, // B
+  DESCRIBE: 0x44, // D
+  EXECUTE: 0x45, // E
+  SYNC: 0x59, // Y
+  SASL_INITIAL: 0x70, // p
+  SASL_RESPONSE: 0x72, // r
+  CANCEL: 0x4b, // K
+  TERMINATE: 0x58, // X
+  COPY_DATA: 0x64, // d
+  COPY_DONE: 0x63, // c
+  COPY_FAIL: 0x66, // f
+};
+
+const AUTH = { OK: 0, SASL: 10, SASL_CONTINUE: 11, SASL_FINAL: 12 };
+
+function u32(value) {
+  const b = Buffer.alloc(4);
+  b.writeUInt32BE(value >>> 0, 0);
+  return b;
+}
+
+function u16(value) {
+  const b = Buffer.alloc(2);
+  b.writeUInt16BE(value & 0xffff, 0);
+  return b;
+}
+
+function str(s) {
+  const body = Buffer.from(s, 'utf8');
+  return Buffer.concat([u32(body.length), body]);
+}
+
+function frame(type, payload) {
+  const total = payload.length + HEADER_LEN;
+  const head = Buffer.alloc(HEADER_LEN);
+  head[0] = type;
+  head.writeUInt32BE(total, 1);
+  return Buffer.concat([head, payload]);
+}
+
+// Encode a Fields list: [count:u16] then per field a present byte (0 = NULL,
+// 1 = [len:u32][bytes]). `values` is an array of Buffer|null.
+function fields(values) {
+  const parts = [u16(values.length)];
+  for (const v of values) {
+    if (v === null || v === undefined) {
+      parts.push(Buffer.from([0]));
+    } else {
+      parts.push(Buffer.from([1]), u32(v.length), v);
+    }
+  }
+  return Buffer.concat(parts);
+}
+
+// --- frontend message builders ---
+
+const encode = {
+  startup(user, database) {
+    return frame(
+      F.STARTUP,
+      Buffer.concat([u32(PROTOCOL_MAGIC), u16(PROTOCOL_MAJOR), u16(PROTOCOL_MINOR), str(user), str(database)])
+    );
+  },
+  query(sql) {
+    return frame(F.QUERY, str(sql));
+  },
+  parse(name, sql) {
+    return frame(F.PARSE, Buffer.concat([str(name), str(sql), u16(0)]));
+  },
+  bind(portal, statement, values) {
+    return frame(F.BIND, Buffer.concat([str(portal), str(statement), fields(values), u16(0)]));
+  },
+  describePortal(name) {
+    return frame(F.DESCRIBE, Buffer.concat([Buffer.from([0x50]), str(name)]));
+  },
+  execute(portal, maxRows) {
+    return frame(F.EXECUTE, Buffer.concat([str(portal), u32(maxRows || 0)]));
+  },
+  sync() {
+    return frame(F.SYNC, Buffer.alloc(0));
+  },
+  terminate() {
+    return frame(F.TERMINATE, Buffer.alloc(0));
+  },
+  saslInitial(mechanism, data) {
+    return frame(F.SASL_INITIAL, Buffer.concat([str(mechanism), u32(data.length), data]));
+  },
+  saslResponse(data) {
+    return frame(F.SASL_RESPONSE, data);
+  },
+  cancel(pid, secret) {
+    return frame(F.CANCEL, Buffer.concat([u32(pid), u32(secret)]));
+  },
+  copyData(data) {
+    return frame(F.COPY_DATA, data);
+  },
+  copyDone() {
+    return frame(F.COPY_DONE, Buffer.alloc(0));
+  },
+  copyFail(message) {
+    return frame(F.COPY_FAIL, str(message));
+  },
+};
+
+// Reader over a payload Buffer.
+class Reader {
+  constructor(buf) {
+    this.buf = buf;
+    this.pos = 0;
+  }
+  u8() {
+    const v = this.buf.readUInt8(this.pos);
+    this.pos += 1;
+    return v;
+  }
+  u16() {
+    const v = this.buf.readUInt16BE(this.pos);
+    this.pos += 2;
+    return v;
+  }
+  u32() {
+    const v = this.buf.readUInt32BE(this.pos);
+    this.pos += 4;
+    return v;
+  }
+  str() {
+    const n = this.u32();
+    const s = this.buf.toString('utf8', this.pos, this.pos + n);
+    this.pos += n;
+    return s;
+  }
+  rest() {
+    const b = this.buf.subarray(this.pos);
+    this.pos = this.buf.length;
+    return b;
+  }
+  fields() {
+    const n = this.u16();
+    const out = [];
+    for (let i = 0; i < n; i += 1) {
+      if (this.u8() === 0) {
+        out.push(null);
+      } else {
+        const len = this.u32();
+        out.push(Buffer.from(this.buf.subarray(this.pos, this.pos + len)));
+        this.pos += len;
+      }
+    }
+    return out;
+  }
+}
+
+module.exports = {
+  PROTOCOL_MAGIC,
+  HEADER_LEN,
+  MAX_FRAME_LEN,
+  SCRAM_MECHANISM,
+  B,
+  F,
+  AUTH,
+  TYPE_TAGS,
+  typeName,
+  encode,
+  Reader,
+};

package/src/scram.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Client-side SCRAM-SHA-256 (RFC 5802 / RFC 7677), docs/wire-protocol.md §7.2.
+// Uses Node's built-in `crypto` (no dependencies).
+
+const crypto = require('crypto');
+
+const GS2_HEADER = 'n,,';
+const CHANNEL_BINDING = Buffer.from(GS2_HEADER, 'ascii').toString('base64'); // "biws"
+
+function hmac(key, msg) {
+  return crypto.createHmac('sha256', key).update(msg).digest();
+}
+
+function clientFirst(user) {
+  const nonce = crypto.randomBytes(18).toString('base64');
+  const bare = `n=${user},r=${nonce}`;
+  return { bare, full: GS2_HEADER + bare };
+}
+
+function parseServerFirst(message) {
+  const parts = {};
+  for (const field of message.split(',')) {
+    const i = field.indexOf('=');
+    if (i > 0) parts[field.slice(0, i)] = field.slice(i + 1);
+  }
+  const combinedNonce = parts.r;
+  const salt = Buffer.from(parts.s, 'base64');
+  const iterations = parseInt(parts.i, 10);
+  if (!combinedNonce || salt.length === 0 || !(iterations > 0)) {
+    throw new Error('nusadb: malformed server-first message');
+  }
+  return { combinedNonce, salt, iterations };
+}
+
+function clientFinal(password, clientFirstBare, serverFirst) {
+  const { combinedNonce, salt, iterations } = parseServerFirst(serverFirst);
+
+  const salted = crypto.pbkdf2Sync(Buffer.from(password, 'utf8'), salt, iterations, 32, 'sha256');
+  const clientKey = hmac(salted, 'Client Key');
+  const storedKey = crypto.createHash('sha256').update(clientKey).digest();
+
+  const withoutProof = `c=${CHANNEL_BINDING},r=${combinedNonce}`;
+  const authMessage = `${clientFirstBare},${serverFirst},${withoutProof}`;
+  const clientSig = hmac(storedKey, authMessage);
+
+  const proof = Buffer.alloc(clientKey.length);
+  for (let i = 0; i < proof.length; i += 1) proof[i] = clientKey[i] ^ clientSig[i];
+  const final = `${withoutProof},p=${proof.toString('base64')}`;
+
+  const serverKey = hmac(salted, 'Server Key');
+  const serverSig = hmac(serverKey, authMessage);
+  return { final: Buffer.from(final, 'utf8'), expected: serverSig.toString('base64') };
+}
+
+function verifyServerFinal(serverFinal, expectedB64) {
+  let got = '';
+  for (const field of serverFinal.split(',')) {
+    if (field.startsWith('v=')) got = field.slice(2);
+  }
+  const a = Buffer.from(got, 'utf8');
+  const b = Buffer.from(expectedB64, 'utf8');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+module.exports = { clientFirst, clientFinal, verifyServerFinal };