@bzync/nextsql 0.1.0 → 0.1.1

package/client-encryption.js

@@ -1,18 +1,20 @@
 'use strict';
 
-// Node-specific NSCE1 implementation. The dependency injection keeps this
+// Node-specific NSCE1/NSCE2 implementation. The dependency injection keeps this
 // module on the driver's single public NextSQLError/Kind surface.
-const { createCipheriv, createDecipheriv, randomBytes } = require('node:crypto');
+const { createCipheriv, createDecipheriv, hkdfSync, randomBytes, timingSafeEqual } = require('node:crypto');
 const fs = require('node:fs/promises');
 
 module.exports = function createClientEncryption(deps) {
   const { NextSQLError, Kind, encodeDecimalString, decodeDecimal, decodeNSJB, formatUUID, parseUUID } = deps;
   const PREFIX = 'NSCE1.';
+	const DETERMINISTIC_PREFIX = 'NSCE2.';
   const MAX_PLAINTEXT = 1 << 20;
   const MAX_KEY_ID = 64;
   const MAX_KEYS = 64;
   const NONCE_SIZE = 12;
   const TAG_SIZE = 16;
+  const DETERMINISTIC_KEY_INFO = Buffer.from('NextSQL NSCE2 AES-SIV v2', 'utf8');
 
   const FieldType = Object.freeze({
     UUID: Object.freeze({ kind: Kind.UUID, precision: 0, scale: 0, vecElem: 0 }),
@@ -334,18 +336,18 @@ module.exports = function createClientEncryption(deps) {
     return Buffer.concat([Buffer.from([tag]), u32(raw.length), raw]);
   }
 
-  function makeHeader(keyID, type, nonce) {
+  function makeHeader(keyID, type, nonce = null) {
     const id = Buffer.from(keyID, 'ascii');
-    const out = Buffer.alloc(3 + id.length + 6 + NONCE_SIZE);
-    out[0] = 1; out[1] = 1; out[2] = id.length; id.copy(out, 3);
+	const out = Buffer.alloc(3 + id.length + 6 + (nonce ? NONCE_SIZE : 0));
+	out[0] = nonce ? 1 : 2; out[1] = nonce ? 1 : 2; out[2] = id.length; id.copy(out, 3);
     const off = 3 + id.length;
     out[off] = type.kind; out.writeUInt16LE(type.precision, off + 1); out.writeUInt16LE(type.scale, off + 3); out[off + 5] = type.vecElem;
-    nonce.copy(out, off + 6);
+	if (nonce) nonce.copy(out, off + 6);
     return out;
   }
 
-  function aad(database, table, column, publicHeader) {
-    const parts = [Buffer.from(PREFIX, 'ascii')];
+  function aad(database, table, column, publicHeader, prefix = PREFIX) {
+	const parts = [Buffer.from(prefix, 'ascii')];
     for (const name of [database, table, column]) {
       const raw = validateName(name);
       parts.push(u16(raw.length), raw);
@@ -355,22 +357,65 @@ module.exports = function createClientEncryption(deps) {
   }
 
   function inspectField(ciphertext) {
-    if (typeof ciphertext !== 'string' || !ciphertext.startsWith(PREFIX)) fail('invalid_format', 'invalid client ciphertext prefix');
-    const enc = ciphertext.slice(PREFIX.length);
+	let prefix, version, suite, nonceSize, mode;
+	if (typeof ciphertext === 'string' && ciphertext.startsWith(PREFIX)) {
+	  prefix = PREFIX; version = 1; suite = 1; nonceSize = NONCE_SIZE; mode = 'randomized';
+	} else if (typeof ciphertext === 'string' && ciphertext.startsWith(DETERMINISTIC_PREFIX)) {
+	  prefix = DETERMINISTIC_PREFIX; version = 2; suite = 2; nonceSize = 0; mode = 'deterministic';
+	} else fail('invalid_format', 'invalid client ciphertext prefix');
+	const enc = ciphertext.slice(prefix.length);
     if (!enc || enc.length % 4 === 1 || !/^[A-Za-z0-9_-]+$/.test(enc) || enc.length > Math.ceil((MAX_PLAINTEXT + 101) * 4 / 3)) {
       fail('invalid_format', 'client ciphertext length out of range');
     }
     const body = Buffer.from(enc, 'base64url');
-    if (body.toString('base64url') !== enc || body.length < 38 || body[0] !== 1 || body[1] !== 1) fail('invalid_format', 'unsupported or truncated client ciphertext');
+	if (body.toString('base64url') !== enc || body.length < 3 + 1 + 6 + nonceSize + TAG_SIZE || body[0] !== version || body[1] !== suite) fail('invalid_format', 'unsupported or truncated client ciphertext');
     const n = body[2];
-    if (n < 1 || n > MAX_KEY_ID || body.length < 3 + n + 6 + NONCE_SIZE + TAG_SIZE) fail('invalid_format', 'invalid field key id length');
+	if (n < 1 || n > MAX_KEY_ID || body.length < 3 + n + 6 + nonceSize + TAG_SIZE) fail('invalid_format', 'invalid field key id length');
     const keyID = body.subarray(3, 3 + n).toString('ascii');
     if (!validKeyID(keyID)) fail('invalid_format', 'invalid field key id');
     const off = 3 + n;
     const type = normalizeType({ kind: body[off], precision: body.readUInt16LE(off + 1), scale: body.readUInt16LE(off + 3), vecElem: body[off + 5] }, 'invalid_format');
-    return { keyID, type, body, headerLength: off + 6 + NONCE_SIZE };
+	return { keyID, type, body, headerLength: off + 6 + nonceSize, mode, prefix };
   }
 
+	function aesBlock(key, block) {
+	  const cipher = createCipheriv('aes-128-ecb', key, null);
+	  cipher.setAutoPadding(false);
+	  return Buffer.concat([cipher.update(block), cipher.final()]);
+	}
+	function dbl(block) {
+	  const out = Buffer.alloc(16); let carry = 0;
+	  for (let i = 15; i >= 0; i--) { const b = block[i]; out[i] = ((b << 1) & 0xff) | carry; carry = b >>> 7; }
+	  if (carry) out[15] ^= 0x87;
+	  return out;
+	}
+	function xor16(a, b) { const out = Buffer.alloc(16); for (let i = 0; i < 16; i++) out[i] = a[i] ^ b[i]; return out; }
+	function cmac(key, msg) {
+	  const l = aesBlock(key, Buffer.alloc(16)); const k1 = dbl(l); const k2 = dbl(k1);
+	  const blocks = Math.max(1, Math.ceil(msg.length / 16)); let last = Buffer.alloc(16);
+	  if (msg.length && msg.length % 16 === 0) last = xor16(msg.subarray(msg.length - 16), k1);
+	  else { const rem = msg.length % 16; msg.copy(last, 0, msg.length - rem); last[rem] = 0x80; last = xor16(last, k2); }
+	  let y = Buffer.alloc(16);
+	  for (let i = 0; i < blocks - 1; i++) y = aesBlock(key, xor16(y, msg.subarray(i * 16, i * 16 + 16)));
+	  return aesBlock(key, xor16(y, last));
+	}
+	function s2v(key, vectors) {
+	  let d = cmac(key, Buffer.alloc(16));
+	  for (let i = 0; i < vectors.length - 1; i++) d = xor16(dbl(d), cmac(key, vectors[i]));
+	  const last = vectors[vectors.length - 1]; let t;
+	  if (last.length >= 16) { t = Buffer.from(last); const off = t.length - 16; for (let i = 0; i < 16; i++) t[off + i] ^= d[i]; }
+	  else { const padded = Buffer.alloc(16); last.copy(padded); padded[last.length] = 0x80; t = xor16(dbl(d), padded); }
+	  return cmac(key, t);
+	}
+	function sivCrypt(material, input, tag, decrypt) {
+	  const q = Buffer.from(tag); q[8] &= 0x7f; q[12] &= 0x7f;
+	  const cipher = decrypt ? createDecipheriv('aes-128-ctr', material.subarray(16), q) : createCipheriv('aes-128-ctr', material.subarray(16), q);
+	  return Buffer.concat([cipher.update(input), cipher.final()]);
+	}
+	function deterministicKey(material) {
+	  return Buffer.from(hkdfSync('sha256', material, Buffer.alloc(0), DETERMINISTIC_KEY_INFO, 32));
+	}
+
   async function encryptField(provider, database, table, column, type, value) {
     if (value === null || value === undefined) return null;
     if (!provider || typeof provider.currentFieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
@@ -395,7 +440,8 @@ module.exports = function createClientEncryption(deps) {
     const expected = normalizeType(expectedType);
     if (ciphertext === null || ciphertext === undefined) return null;
     if (!provider || typeof provider.fieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
-    const parsed = inspectField(ciphertext);
+	const parsed = inspectField(ciphertext);
+	if (parsed.mode !== 'randomized') fail('invalid_format', 'deterministic ciphertext requires decryptFieldDeterministic');
     if (!sameType(expected, parsed.type)) fail('invalid_format', 'encrypted logical type mismatch');
     let key;
     try { key = await provider.fieldKey(database, table, column, parsed.keyID); } catch { fail('crypto', 'field key unavailable or revoked'); }
@@ -415,6 +461,31 @@ module.exports = function createClientEncryption(deps) {
     }
   }
 
+	async function encryptFieldDeterministic(provider, database, table, column, type, value) {
+	  if (value === null || value === undefined) return null;
+	  if (!provider || typeof provider.currentFieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
+	  const t = normalizeType(type); const plain = encodeScalar(t, value);
+	  if (plain.length > MAX_PLAINTEXT) fail('exhausted', 'plaintext exceeds field limit');
+	  let key; try { key = await provider.currentFieldKey(database, table, column); } catch { fail('crypto', 'field key unavailable'); }
+	  const material = deterministicKey(keyMaterial(key)); const hdr = makeHeader(key.id, t);
+	  const associated = aad(database, table, column, hdr, DETERMINISTIC_PREFIX);
+	  const tag = s2v(material.subarray(0, 16), [associated, plain]);
+	  return DETERMINISTIC_PREFIX + Buffer.concat([hdr, tag, sivCrypt(material, plain, tag, false)]).toString('base64url');
+	}
+
+	async function decryptFieldDeterministic(provider, database, table, column, expectedType, ciphertext) {
+	  const expected = normalizeType(expectedType); if (ciphertext == null) return null;
+	  if (!provider || typeof provider.fieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
+	  const parsed = inspectField(ciphertext);
+	  if (parsed.mode !== 'deterministic' || !sameType(expected, parsed.type)) fail('invalid_format', 'encrypted mode or logical type mismatch');
+	  let key; try { key = await provider.fieldKey(database, table, column, parsed.keyID); } catch { fail('crypto', 'field key unavailable or revoked'); }
+	  const material = deterministicKey(keyMaterial(key, parsed.keyID)); const tag = parsed.body.subarray(parsed.headerLength, parsed.headerLength + 16);
+	  const plain = sivCrypt(material, parsed.body.subarray(parsed.headerLength + 16), tag, true);
+	  const expectedTag = s2v(material.subarray(0, 16), [aad(database, table, column, parsed.body.subarray(0, parsed.headerLength), DETERMINISTIC_PREFIX), plain]);
+	  if (!timingSafeEqual(tag, expectedTag)) fail('crypto', 'ciphertext authentication failed');
+	  return decodeScalar(expected, plain);
+	}
+
   function generateFieldKey(id) {
     if (!validKeyID(id)) fail('invalid_argument', 'invalid field key id');
     return { id, material: randomBytes(32) };
@@ -630,5 +701,5 @@ module.exports = function createClientEncryption(deps) {
     }
   }
 
-  return { FieldType, MemoryFieldKeyring, FileFieldKeyring, decryptField, encryptField, generateFieldKey, inspectField };
+  return { FieldType, MemoryFieldKeyring, FileFieldKeyring, decryptField, decryptFieldDeterministic, encryptField, encryptFieldDeterministic, generateFieldKey, inspectField };
 };

package/nextsql.d.ts

@@ -31,9 +31,10 @@ export interface Config {
   /** Single-node entry point. Required for connect(); optional when nodes is set. */
   address?: string;
   database?: string;
-  /** Selects which hosted realm this connection targets (M2-2). Optional:
-   * an unset realm sends the exact pre-realm Hello and connects to the
-   * server's configured default. */
+  /** Reserved; must stay empty. Multi-realm hosting was removed — a
+   * deployment serves exactly one database, and a server rejects a Hello
+   * naming any other realm. The field remains only because the wire
+   * frame's trailing realm slot does. */
   realm?: string;
   user: string;
   password?: string;
@@ -212,6 +213,8 @@ export interface Conn {
   encryptField(table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
   /** Authenticate and decode an opaque NSCE1 STRING; null passes through. */
   decryptField(table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
+  encryptFieldDeterministic(table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
+  decryptFieldDeterministic(table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
 }
 
 /** Routing client over every node of a NextSQL HA cluster. */
@@ -236,6 +239,8 @@ export interface HelloOK {
   version: number;
   authMethod: number;
   secret: bigint;
+  /** Capability bits the server accepted from Hello.flags; 0 when none. */
+  flags: number;
 }
 
 export interface DecodeValue {
@@ -246,7 +251,14 @@ export interface DecodeValue {
 
 export declare class NextSQLError extends Error {
   readonly code: string;
-  constructor(code: string, message?: string);
+  /**
+   * Stable ERR_* name from docs/error-codes.md, present only on an error
+   * received over a connection that negotiated the public taxonomy and empty
+   * otherwise. `code` always carries the legacy class, so retry logic should
+   * keep reading that.
+   */
+  readonly publicCode: string;
+  constructor(code: string, message?: string, publicCode?: string);
 }
 
 export declare const Kind: {
@@ -322,11 +334,17 @@ export declare function generateFieldKey(id: string): FieldKey;
 export declare function inspectField(ciphertext: string): { keyID: string; type: FieldTypeDescriptor };
 export declare function encryptField(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
 export declare function decryptField(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
+export declare function encryptFieldDeterministic(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
+export declare function decryptFieldDeterministic(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
 export declare function validateConfig(cfg: Config): void;
 export declare function isLoopback(addr: string): boolean;
 export declare function encodeParam(v: Param): Uint8Array;
 export declare function struct(fields: Array<[string, unknown]>): { __struct: Array<[string, unknown]> };
 export declare function decodeValue(buf: Uint8Array, off: number): DecodeValue;
+/** Hello.flags bit requesting cancellation instead of a session. */
+export declare const FlagCancel: number;
+/** Hello.flags bit requesting the stable ERR_* error taxonomy. */
+export declare const FlagPublicErrorCodes: number;
 export declare function encodeHello(h: Hello): Uint8Array;
 export declare function decodeHelloOK(b: Uint8Array): HelloOK;
 export declare function encodeDecimalString(s: string): Uint8Array;

package/nextsql.js

@@ -57,6 +57,12 @@ const STATUS_TTL_MS = 500;
 const AuthPassword = 1;
 const AuthPasswordKey = 2;
 const FlagCancel = 1;
+// FlagPublicErrorCodes asks the server for the stable ERR_* error taxonomy
+// (docs/error-codes.md). A server that does not implement it ignores the bit
+// and keeps the NSQL v1 error shape, which decodeError still reads, so setting
+// it is safe against any server version. The server echoes it in HelloOK.flags
+// when it was accepted.
+const FlagPublicErrorCodes = 2;
 const FlagNull = 0x01;
 
 const Kind = {
@@ -104,10 +110,16 @@ const MAX_STRUCT_FIELDS = 128;
 const MAX_COLLECTION_LEN = 1 << 20;
 
 class NextSQLError extends Error {
-  constructor(code, message) {
+  constructor(code, message, publicCode) {
     super(message || code);
     this.name = 'NextSQLError';
     this.code = code;
+    // publicCode is the stable ERR_* name the server sent, present only on
+    // an error received over a connection that negotiated the taxonomy and
+    // empty otherwise. code always carries the legacy class, so existing
+    // retry checks keep working and nothing should branch on publicCode
+    // being present.
+    this.publicCode = publicCode || '';
   }
 }
 
@@ -116,7 +128,9 @@ const {
   MemoryFieldKeyring,
   FileFieldKeyring,
   decryptField,
+  decryptFieldDeterministic,
   encryptField,
+  encryptFieldDeterministic,
   generateFieldKey,
   inspectField,
 } = require('./client-encryption')({
@@ -1279,10 +1293,19 @@ function encodeHello(h) {
 }
 
 function decodeHelloOK(b) {
-  if (b.length !== 11) {
+  if (b.length !== 11 && b.length !== 13) {
     throw new NextSQLError('protocol', 'bad hello-ok length');
   }
-  return { version: u16(b, 0), authMethod: b[2], secret: u64(b, 3) };
+  let flags = 0;
+  if (b.length === 13) {
+    flags = u16(b, 11);
+    // The server omits the field when it accepted no capability, so a
+    // present-but-zero field is a second encoding of the v1 hello-ok.
+    if (flags === 0) {
+      throw new NextSQLError('protocol', 'empty hello-ok flags');
+    }
+  }
+  return { version: u16(b, 0), authMethod: b[2], secret: u64(b, 3), flags };
 }
 
 function encodeAuth(password) {
@@ -1374,7 +1397,18 @@ function decodeDataBatch(b) {
 function decodeError(b) {
   const code = readU16String(b, 0, MAX_NAME);
   const msg = readU16String(b, code.next, MAX_NAME);
-  return new NextSQLError(code.value, msg.value);
+  // Optional trailing field, present only from a server that accepted
+  // FlagPublicErrorCodes. Its absence is normal — an older server ignores the
+  // request bit — so this must never be required.
+  let publicCode = '';
+  if (msg.next < b.length) {
+    const p = readU16String(b, msg.next, MAX_NAME);
+    if (p.value === '') {
+      throw new NextSQLError('protocol', 'empty public error code');
+    }
+    publicCode = p.value;
+  }
+  return new NextSQLError(code.value, msg.value, publicCode);
 }
 
 function decodeCommandComplete(b) {
@@ -1567,8 +1601,8 @@ function connectSocket(cfg) {
       if (cfg.tls.ca) {
         opts.ca = cfg.tls.ca;
       }
-      if (cfg.tls.rejectUnauthorized === false) {
-        opts.rejectUnauthorized = false;
+      if (typeof cfg.tls.rejectUnauthorized === 'boolean') {
+        opts.rejectUnauthorized = cfg.tls.rejectUnauthorized;
       }
       const sock = tls.connect(opts, () => resolve(sock));
       sock.on('error', onErr);
@@ -1724,11 +1758,13 @@ class Conn {
     this.wire = wire;
     this.secret = 0n;
     this.busy = false;
+    this.publicErrorCodes = false;
   }
 
   async handshake() {
     await this.wire.writeFrame(Type.Hello, encodeHello({
       version: VERSION,
+      flags: FlagPublicErrorCodes,
       database: this.cfg.database || '',
       user: this.cfg.user,
       realm: this.cfg.realm || '',
@@ -1739,6 +1775,9 @@ class Conn {
     }
     const ok = decodeHelloOK(msg.payload);
     this.secret = ok.secret;
+    // Diagnostic only: decodeError reads the field whenever it is present,
+    // so nothing depends on this having been echoed.
+    this.publicErrorCodes = (ok.flags & FlagPublicErrorCodes) !== 0;
     await this.wire.writeFrame(Type.Auth, encodeAuth(this.cfg.password || ''));
     msg = await this.wire.readFrame();
     if (msg.type !== Type.AuthOK) {
@@ -1888,6 +1927,14 @@ class Conn {
     return decryptField(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, ciphertext);
   }
 
+  async encryptFieldDeterministic(table, column, type, value) {
+    return encryptFieldDeterministic(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, value);
+  }
+
+  async decryptFieldDeterministic(table, column, type, ciphertext) {
+    return decryptFieldDeterministic(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, ciphertext);
+  }
+
   async prepare(sql) {
     if (!this.wire) {
       throw new NextSQLError('unavailable', 'connection closed');
@@ -2152,6 +2199,8 @@ async function connectCluster(cfg) {
 
 module.exports = {
   connect,
+  FlagCancel,
+  FlagPublicErrorCodes,
   connectCluster,
   Cluster,
   NextSQLError,
@@ -2181,7 +2230,9 @@ module.exports = {
   MemoryFieldKeyring,
   FileFieldKeyring,
   decryptField,
+  decryptFieldDeterministic,
   encryptField,
+  encryptFieldDeterministic,
   generateFieldKey,
   inspectField,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bzync/nextsql",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official NextSQL Node.js driver. Keys never go in URLs.",
   "license": "MIT",
   "main": "nextsql.js",