[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 + User-Agent: mirrors the Python connector's
  `use_kernel` path (`session.py` + `backend/kernel/client.py`). Headers
  cross the FFI as an ordered list (`Array<{name,value}>`, the napi
  `HeaderEntry` shape matching the kernel core `Vec<(String,String)>` and
  Python's `List[Tuple]`): the caller's `customHeaders` first, then the
  connector's composed `User-Agent` appended last. The connector UA is
  always emitted (via the same `buildUserAgentString` the Thrift path
  uses, with `userAgentEntry` folded in) and, being last, is authoritative
  — the kernel folds the last `User-Agent` into its base
  `DatabricksJDBCDriverOSS/...` UA, preserving the result-disposition
  gating token. The kernel-managed reserved names `Authorization` /
  `x-databricks-org-id` are dropped before the FFI hop, matching Python's
  `_KERNEL_MANAGED_HEADERS` double-wall.

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, ordered header pass-through, reserved-name
dropping, and User-Agent composition/ordering.

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
+6eda90b6922ee82923f0f590b2e1bdb686007129

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,44 @@ 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).
+ *
+ * An **ordered list** of `{ name, value }` pairs — the napi shape
+ * (`Array<HeaderEntry>`), which mirrors the kernel core's
+ * `Vec<(String, String)>` and the Python connector's `http_headers`
+ * `List[Tuple[str, str]]`. Order is preserved and duplicate names are
+ * allowed (e.g. a caller `User-Agent` followed by the connector's, which
+ * the kernel folds last-wins).
+ */
+export interface SeaHttpOptions {
+  customHeaders?: Array<{ name: string; value: string }>;
 }
 
 export type SeaNativeConnectionOptions = SeaSessionDefaults &
   SeaTlsOptions &
+  SeaHttpOptions &
   (
     | {
         hostName: string;
@@ -168,24 +203,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 +276,80 @@ 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 `use_kernel` path (`session.py` +
+ * `backend/kernel/client.py`), which:
+ *   1. composes a single connector `User-Agent` and **unconditionally**
+ *      appends it last —
+ *      `all_headers = (http_headers or []) + [("User-Agent", useragent_header)]`;
+ *   2. before forwarding to the kernel, **drops** the kernel-managed
+ *      reserved names `Authorization` / `x-databricks-org-id`
+ *      (case-insensitive) — the kernel applies the auth token itself and
+ *      re-derives the org id from the `?o=` in the http path, and would
+ *      otherwise skip-and-warn on every request.
+ *
+ * The result is an ordered list (the napi `Array<HeaderEntry>` shape,
+ * matching the kernel core `Vec<(String, String)>`): the caller's
+ * `customHeaders` first (minus reserved names), then the connector's
+ * `User-Agent` last. The connector UA is always present and, being last,
+ * is authoritative (the kernel folds the last `User-Agent` into its base
+ * UA — `DatabricksJDBCDriverOSS/...` — preserving the result-disposition
+ * gating token). The value is composed via the same `buildUserAgentString`
+ * the Thrift path uses, so the SEA UA carries the identical
+ * `NodejsDatabricksSqlConnector/...` identity (with `userAgentEntry`
+ * folded in). A caller `User-Agent` in `customHeaders` is forwarded too
+ * (mirroring Python, which doesn't dedupe it); the kernel's last-wins fold
+ * means the connector UA still wins.
+ */
+const KERNEL_MANAGED_HEADERS = new Set(['authorization', 'x-databricks-org-id']);
+
+export function buildSeaHttpOptions(options: ConnectionOptions): SeaHttpOptions {
+  const { customHeaders, userAgentEntry } = options;
+
+  const headers: Array<{ name: string; value: string }> = [];
+  if (customHeaders) {
+    for (const [name, value] of Object.entries(customHeaders)) {
+      // Drop kernel-managed reserved names before the FFI hop — same
+      // double-wall as the Python connector's `_KERNEL_MANAGED_HEADERS`.
+      if (KERNEL_MANAGED_HEADERS.has(name.toLowerCase())) {
+        continue;
       }
-      tls.customCaCert = customCaCert;
-    } else {
-      throw new HiveDriverError('SEA backend: `customCaCert` must be a PEM string or a Buffer.');
+      headers.push({ name, value });
     }
   }
 
-  return tls;
+  // Always append the connector's composed User-Agent last — exactly the
+  // Python connector's unconditional `base_headers` append.
+  headers.push({ name: 'User-Agent', value: buildUserAgentString(userAgentEntry) });
+
+  return { customHeaders: headers };
 }
 
 /**
@@ -282,7 +413,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 +424,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