[SEA-NodeJS] Kernel backend: mTLS, custom HTTP headers & User-Agent

Wire the SEA/kernel path's remaining TLS-adjacent connection options
through to the napi binding:

- mTLS client identity: `clientCertPem` / `clientKeyPem` (PEM string or
  Buffer) on the internal SEA options, normalised to Buffers and routed
  to the kernel `TlsConfig::client_cert_pem` / `client_key_pem`. Enforces
  both-or-neither up front with an actionable error.
- Custom HTTP headers: the public `customHeaders` map is forwarded to the
  kernel `HttpConfig::custom_headers`.
- User-Agent: mirrors the Python connector's `Session.__init__`, which
  composes a single connector `User-Agent` and unconditionally appends it
  last (`all_headers = (http_headers or []) + base_headers`). The node
  driver always emits its own composed `User-Agent` (via the same
  `buildUserAgentString` the Thrift path uses, with `userAgentEntry`
  folded in); it is authoritative and a caller-supplied `User-Agent` in
  `customHeaders` (any casing) is dropped so exactly one canonical header
  is sent. The kernel then appends this to its base UA, preserving the
  result-disposition gating token.

Adds `buildSeaHttpOptions`, extends `buildSeaTlsOptions`/`SeaTlsOptions`,
and factors PEM normalisation into a shared helper. Bumps KERNEL_REV and
regenerates `native/sea/index.d.ts` for the new napi fields. Unit tests
cover mTLS pairing/validation, header pass-through, and User-Agent
composition/override.

Depends on the kernel napi change exposing clientCertPem / clientKeyPem /
customHeaders; KERNEL_REV must be repointed to that commit once merged.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

KERNEL_REV

@@ -1 +1 @@
-8bedaabf69f5bce5a957a8775f29dbb8dbdd2e71
+4c2b7d71a4fb04eff236ec095c5b3b9e64bdd9f0

lib/contracts/InternalConnectionOptions.ts

@@ -41,4 +41,22 @@ export interface InternalConnectionOptions {
    * @internal SEA path only.
    */
   customCaCert?: Buffer | string;
+
+  /**
+   * SEA-only: PEM-encoded client certificate (string or `Buffer`) for
+   * mutual TLS (mTLS). Must be supplied together with `clientKeyPem`; a
+   * leaf cert optionally followed by its intermediate chain is accepted.
+   * Mirrors the Python connector's `_tls_client_cert_file`.
+   * @internal SEA path only.
+   */
+  clientCertPem?: Buffer | string;
+
+  /**
+   * SEA-only: PEM-encoded private key (string or `Buffer`) for the mTLS
+   * client certificate. Must be supplied together with `clientCertPem`.
+   * For portability supply a PKCS#8 key (`BEGIN PRIVATE KEY`). Mirrors the
+   * Python connector's `_tls_client_cert_key_file`.
+   * @internal SEA path only.
+   */
+  clientKeyPem?: Buffer | string;
 }

lib/sea/SeaAuth.ts

@@ -16,6 +16,7 @@ import { ConnectionOptions } from '../contracts/IDBSQLClient';
 import { InternalConnectionOptions } from '../contracts/InternalConnectionOptions';
 import AuthenticationError from '../errors/AuthenticationError';
 import HiveDriverError from '../errors/HiveDriverError';
+import { buildUserAgentString } from '../utils';
 
 /**
  * Default local listener port for the U2M authorization-code callback.
@@ -115,10 +116,37 @@ export interface SeaTlsOptions {
   checkServerCertificate?: boolean;
   /** PEM-encoded CA bytes to add to the trust store. */
   customCaCert?: Buffer;
+  /**
+   * PEM-encoded client certificate for mutual TLS (kernel
+   * `TlsConfig::client_cert_pem`). Paired with {@link clientKeyPem} —
+   * `buildSeaTlsOptions` rejects supplying only one before the FFI hop.
+   * The napi shape takes a `Buffer`; the public surface also accepts a
+   * PEM string, normalised here.
+   */
+  clientCertPem?: Buffer;
+  /**
+   * PEM-encoded private key for the mTLS client certificate (kernel
+   * `TlsConfig::client_key_pem`). Paired with {@link clientCertPem}.
+   */
+  clientKeyPem?: Buffer;
+}
+
+/**
+ * HTTP options shared across all auth-mode variants. Mirrors the napi
+ * binding's `ConnectionOptions.customHeaders` (kernel
+ * `HttpConfig::custom_headers`).
+ *
+ * Carries the extra request headers the SEA path sends on every request:
+ * the caller's `customHeaders` plus the composed `User-Agent` (the kernel
+ * appends a `User-Agent` entry to its base UA rather than replacing it).
+ */
+export interface SeaHttpOptions {
+  customHeaders?: Record<string, string>;
 }
 
 export type SeaNativeConnectionOptions = SeaSessionDefaults &
   SeaTlsOptions &
+  SeaHttpOptions &
   (
     | {
         hostName: string;
@@ -168,24 +196,71 @@ export function isBlankOrReserved(s: string): boolean {
 const MAX_U32 = 0xffffffff;
 
 /**
- * Normalise the public TLS options (`checkServerCertificate` /
- * `customCaCert`) into the napi shape.
+ * Normalise a PEM input (`string` or `Buffer`) accepted on the public
+ * surface into the `Buffer` the napi shape requires. Does a light,
+ * ordered BEGIN…END sanity check so a truncated/headerless blob (or a
+ * stray page that merely contains the literals out of order, e.g. a
+ * proxy-intercept page) is rejected here rather than surfacing as an
+ * opaque kernel TLS error. The bytes are NOT fully parsed in JS — that
+ * is deferred to the kernel, which returns a meaningful error on a
+ * malformed PEM/key.
+ *
+ * `kind` selects the expected block: `'certificate'` matches a
+ * `CERTIFICATE` block; `'private key'` matches any `… PRIVATE KEY` block
+ * (PKCS#8 `PRIVATE KEY`, PKCS#1 `RSA PRIVATE KEY`, SEC1 `EC PRIVATE KEY`).
+ *
+ * Throws `HiveDriverError` when the value is empty or (for strings)
+ * lacks the expected PEM header.
+ */
+function normalizePemBytes(value: Buffer | string, optionName: string, kind: 'certificate' | 'private key'): Buffer {
+  if (typeof value === 'string') {
+    const re =
+      kind === 'certificate'
+        ? /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/
+        : /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z0-9 ]*PRIVATE KEY-----/;
+    if (!re.test(value)) {
+      const expected =
+        kind === 'certificate'
+          ? "a '-----BEGIN CERTIFICATE-----' … '-----END CERTIFICATE-----' block"
+          : "a 'BEGIN … PRIVATE KEY' / 'END … PRIVATE KEY' PEM block (PKCS#8, PKCS#1, or SEC1)";
+      throw new HiveDriverError(
+        `SEA backend: \`${optionName}\` string does not look like a PEM ${kind} (expected ${expected}). ` +
+          'Pass PEM text or a Buffer of PEM bytes.',
+      );
+    }
+    return Buffer.from(value, 'utf8');
+  }
+  if (Buffer.isBuffer(value)) {
+    if (value.length === 0) {
+      throw new HiveDriverError(`SEA backend: \`${optionName}\` Buffer is empty.`);
+    }
+    return value;
+  }
+  throw new HiveDriverError(`SEA backend: \`${optionName}\` must be a PEM string or a Buffer.`);
+}
+
+/**
+ * Normalise the public TLS options into the napi shape.
  *
  * - `checkServerCertificate` passes through verbatim (only when set; an
  *   absent value leaves the kernel default, which is secure — verify on).
- * - `customCaCert` accepts a PEM string or `Buffer` on the public
- *   surface; we convert a string to a `Buffer` here and do a light PEM
- *   sanity check. The bytes are NOT parsed in JS — the kernel returns a
- *   meaningful error if the PEM is malformed.
+ * - `customCaCert` accepts a PEM string or `Buffer`; normalised to a
+ *   `Buffer` via {@link normalizePemBytes}.
+ * - `clientCertPem` / `clientKeyPem` carry the mutual-TLS client identity.
+ *   They must be supplied **together** — supplying only one is rejected
+ *   here with an actionable error (rather than waiting for the kernel's
+ *   `InvalidArgument` at `openSession`). Each accepts a PEM string or
+ *   `Buffer`, normalised the same way.
  *
- * Throws `HiveDriverError` when `customCaCert` is supplied but empty or
- * (for strings) lacks a PEM certificate header.
+ * Throws `HiveDriverError` when a cert/key is empty, mis-typed, lacks the
+ * expected PEM header, or when only one half of the mTLS pair is set.
  */
 export function buildSeaTlsOptions(options: ConnectionOptions): SeaTlsOptions {
   // Read the SEA-only fields through the purpose-built internal options type
   // rather than an ad-hoc inline cast, so the shape can't silently drift from
   // its declaration and a typo'd key fails to compile.
-  const { checkServerCertificate, customCaCert } = options as ConnectionOptions & InternalConnectionOptions;
+  const { checkServerCertificate, customCaCert, clientCertPem, clientKeyPem } = options as ConnectionOptions &
+    InternalConnectionOptions;
 
   const tls: SeaTlsOptions = {};
 
@@ -194,31 +269,79 @@ export function buildSeaTlsOptions(options: ConnectionOptions): SeaTlsOptions {
   }
 
   if (customCaCert !== undefined) {
-    if (typeof customCaCert === 'string') {
-      // Light PEM sanity check — require a well-ordered BEGIN…END block so a
-      // truncated/headerless cert (or a stray page that merely contains both
-      // literals out of order, e.g. a proxy-intercept page) is rejected here
-      // rather than surfacing as an opaque kernel TLS error. Ordered match, not
-      // two independent substring checks. Full parsing is deferred to the kernel.
-      if (!/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/.test(customCaCert)) {
-        throw new HiveDriverError(
-          'SEA backend: `customCaCert` string does not look like a PEM certificate ' +
-            "(expected a '-----BEGIN CERTIFICATE-----' … '-----END CERTIFICATE-----' block). " +
-            'Pass PEM text or a Buffer of PEM bytes.',
-        );
-      }
-      tls.customCaCert = Buffer.from(customCaCert, 'utf8');
-    } else if (Buffer.isBuffer(customCaCert)) {
-      if (customCaCert.length === 0) {
-        throw new HiveDriverError('SEA backend: `customCaCert` Buffer is empty.');
+    tls.customCaCert = normalizePemBytes(customCaCert, 'customCaCert', 'certificate');
+  }
+
+  // mTLS client identity. Enforce both-or-neither up front so a caller who
+  // sets only one gets a clear message naming the missing half, instead of
+  // the kernel's generic `InvalidArgument` after the FFI hop.
+  const hasCert = clientCertPem !== undefined;
+  const hasKey = clientKeyPem !== undefined;
+  if (hasCert !== hasKey) {
+    throw new HiveDriverError(
+      'SEA backend: mutual TLS requires both `clientCertPem` and `clientKeyPem`; only ' +
+        `\`${hasCert ? 'clientCertPem' : 'clientKeyPem'}\` was supplied. ` +
+        `Provide the matching ${hasCert ? 'private key (`clientKeyPem`)' : 'certificate (`clientCertPem`)'}, ` +
+        'or omit both.',
+    );
+  }
+  if (hasCert && hasKey) {
+    tls.clientCertPem = normalizePemBytes(clientCertPem as Buffer | string, 'clientCertPem', 'certificate');
+    tls.clientKeyPem = normalizePemBytes(clientKeyPem as Buffer | string, 'clientKeyPem', 'private key');
+  }
+
+  return tls;
+}
+
+/**
+ * Build the napi HTTP options (`customHeaders`) from the public
+ * `customHeaders` map and `userAgentEntry`.
+ *
+ * Mirrors the Python connector's `Session.__init__`, which composes a
+ * single connector `User-Agent` and **unconditionally** appends it after
+ * the caller's headers:
+ *
+ *     base_headers = [("User-Agent", self.useragent_header)]
+ *     all_headers  = (http_headers or []) + base_headers
+ *
+ * So the connector's own `User-Agent` is **always** emitted and is
+ * authoritative — a caller cannot suppress or replace it via
+ * `customHeaders` (Python appends `base_headers` last; in the node driver,
+ * which sends a header map, "appended last" collapses to "the connector UA
+ * wins", and any caller-supplied `User-Agent`, whatever its casing, is
+ * dropped to avoid emitting two `User-Agent` keys). The value is composed
+ * via the same `buildUserAgentString` the Thrift path uses, so the SEA UA
+ * carries the identical `NodejsDatabricksSqlConnector/...` identity (with
+ * the optional `userAgentEntry` folded in). The kernel then *appends* this
+ * to its own base UA, preserving the `DatabricksJDBCDriverOSS/...` token
+ * the SEA server keys on for result disposition.
+ *
+ * All other `customHeaders` entries pass through unchanged. The kernel
+ * additionally drops the reserved `Authorization` / `x-databricks-org-id`
+ * names, so those can't be overridden here.
+ */
+export function buildSeaHttpOptions(options: ConnectionOptions): SeaHttpOptions {
+  const { customHeaders, userAgentEntry } = options;
+
+  const headers: Record<string, string> = {};
+  if (customHeaders) {
+    for (const [name, value] of Object.entries(customHeaders)) {
+      // Skip any caller-supplied User-Agent (any casing) — the connector
+      // sets its own composed, authoritative User-Agent below, matching the
+      // Python connector which appends its `("User-Agent", …)` last.
+      if (name.toLowerCase() === 'user-agent') {
+        continue;
       }
-      tls.customCaCert = customCaCert;
-    } else {
-      throw new HiveDriverError('SEA backend: `customCaCert` must be a PEM string or a Buffer.');
+      headers[name] = value;
     }
   }
 
-  return tls;
+  // Always emit the connector's composed User-Agent, regardless of whether
+  // `userAgentEntry` or a caller `customHeaders` User-Agent was supplied —
+  // exactly the Python connector's unconditional `base_headers` append.
+  headers['User-Agent'] = buildUserAgentString(userAgentEntry);
+
+  return { customHeaders: headers };
 }
 
 /**
@@ -282,7 +405,8 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
     httpPath: string;
     intervalsAsString: boolean;
     maxConnections?: number;
-  } & SeaTlsOptions = {
+  } & SeaTlsOptions &
+    SeaHttpOptions = {
     hostName: options.host,
     httpPath: prependSlash(options.path),
     // Match the NodeJS Thrift driver, which surfaces INTERVAL columns as
@@ -292,9 +416,12 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
     // (native Arrow) — they already decode identically to Thrift via the
     // shared Arrow converter, so `complexTypesAsJson` is not forced on.
     intervalsAsString: true,
-    // TLS knobs (server-cert verification toggle + custom CA). Validated and
-    // normalised (string PEM → Buffer) here so the napi shape only sees a Buffer.
+    // TLS knobs (server-cert verification toggle + custom CA + mTLS client
+    // identity). Validated and normalised (string PEM → Buffer) here so the
+    // napi shape only sees a Buffer.
     ...buildSeaTlsOptions(options),
+    // HTTP headers (caller `customHeaders` + composed `User-Agent`).
+    ...buildSeaHttpOptions(options),
   };
 
   // SEA-only pool sizing; read via cast to match how this function reads the