sea-auth-u2m: address round-1 M2M review parity — shared fakeBinding helper, doc + loader cleanup

Ports the M2M-side round-1 review fixes (commit 88d7d21 on
sea-auth-m2m) onto the U2M worktree so the two branches stay aligned
in review quality. The U2M-specific work in 5eba37f is unchanged;
this commit is pure cleanup applied across all three SEA-auth test
files (PAT / M2M / U2M).

- Extracted `makeFakeBinding()` to
  `tests/unit/sea/_helpers/fakeBinding.ts` and refactored all three
  auth-*.test.ts files to import it. The U2M-worktree commit had
  THREE copies of the closure (the third was the cause for the
  bloat reviewer's "rule of three" call-out that the M2M-worktree
  fixup was meant to forestall).
- Dropped the unused `SeaAuthMode` type alias from `SeaAuth.ts` —
  zero callers; inlined literals already power the discriminated
  union.
- Tightened `SeaNativeBinding.openSession` parameter type to consume
  the discriminated `SeaNativeConnectionOptions` union from
  `SeaAuth.ts`, restoring compile-time per-mode field enforcement
  at the FFI seam.
- Augmented the Rust `AuthMode` doc-comment with the napi-emission
  explanation (PascalCase verbatim, not kebab-case) plus the
  cross-reference reminder to extend `open_session()`'s match on
  every new variant.
- Added the const-enum hazard note to `SeaNativeConnectionOptions`'
  doc-comment, locking in the duplicated-literal pattern as
  deliberate (importing the napi `const enum AuthMode` breaks
  `isolatedModules`).
- Cleaned up the conditional-type-cast lobotomy in `auth-pat.test.ts`
  on the token-provider fixture; plain `as any` + eslint-disable.

Skipped findings (same justification as M2M-worktree commit):
F-3 borderline error-class taxonomy, F-4 cosmetic arg-order,
F-5 redundant comment-anchor (compiler already enforces), F-8 null
vs undefined paranoia, F-9 mocha named-function style.

Tests:
- Unit: 55/55 pass (same count as 5eba37f — pure restructure).
- Native build: clean (1m04s release profile).
- Type-check: clean (tsc --noEmit).

Co-authored-by: Isaac

Author: msrathore-db

lib/sea/SeaAuth.ts

@@ -16,14 +16,6 @@ import { ConnectionOptions } from '../contracts/IDBSQLClient';
 import AuthenticationError from '../errors/AuthenticationError';
 import HiveDriverError from '../errors/HiveDriverError';
 
-/**
- * Auth-mode discriminant value crossing the napi boundary. The string
- * literals are what napi-rs emits from the `#[napi(string_enum)] AuthMode`
- * enum at `native/sea/src/database.rs` — they MUST match the variant
- * names verbatim (`'Pat'`, `'OAuthM2m'`, `'OAuthU2m'`).
- */
-export type SeaAuthMode = 'Pat' | 'OAuthM2m' | 'OAuthU2m';
-
 /**
  * Default local listener port for the U2M authorization-code callback.
  * Hardcoded here so the override of the kernel default (8020) to the
@@ -47,6 +39,15 @@ const U2M_DEFAULT_REDIRECT_PORT = 8030;
  * - `'OAuthU2m'`  → `oauthRedirectPort` overrides the kernel default;
  *                   everything else (client_id, scopes, callback timeout,
  *                   token_url_override) uses kernel defaults.
+ *
+ * The `authMode` string literals MUST match the napi-emitted `AuthMode`
+ * variant names verbatim (`'Pat'`, `'OAuthM2m'`, `'OAuthU2m'` — napi-rs's
+ * `#[napi(string_enum)]` without an explicit case option emits the
+ * Rust variant identifier as-is). We duplicate the values here instead
+ * of importing `AuthMode` from `native/sea/index.d.ts` because that
+ * file declares `AuthMode` as `export const enum`, which is
+ * incompatible with `isolatedModules` and a runtime-coupling hazard.
+ * The Rust source of truth lives at `native/sea/src/database.rs`.
  */
 export type SeaNativeConnectionOptions =
   | {

lib/sea/SeaNativeLoader.ts

@@ -27,6 +27,8 @@
  * forwards to the binding's `installLogger()` once that surface lands.
  */
 
+import type { SeaNativeConnectionOptions } from './SeaAuth';
+
 // The path is relative to this file at runtime (`dist/sea/SeaNativeLoader.js`)
 // resolving to `dist/sea/../../native/sea/index.js` once `tsc` has emitted
 // to `dist/`. We use a require-time path resolution because the napi
@@ -52,21 +54,14 @@ export interface SeaNativeBinding {
   version(): string;
   /**
    * Open a session over PAT, OAuth M2M, or OAuth U2M auth. Returns an
-   * opaque Connection. The discriminated payload mirrors the
-   * auto-generated `ConnectionOptions` in `native/sea/index.d.ts`; we
-   * keep the static type permissive (all fields optional except the
-   * discriminant) so the JS adapter layer's union narrows correctly
-   * without three overloads.
+   * opaque Connection. The discriminated `SeaNativeConnectionOptions`
+   * union from `SeaAuth` is the source of truth for the per-mode
+   * required fields, so the loader-seam enforces the same compile-time
+   * check the adapter applies — a caller can't bypass
+   * `buildSeaConnectionOptions` and pass, say, `{ authMode: 'Pat' }`
+   * with no token.
    */
-  openSession(opts: {
-    hostName: string;
-    httpPath: string;
-    authMode: 'Pat' | 'OAuthM2m' | 'OAuthU2m';
-    token?: string;
-    oauthClientId?: string;
-    oauthClientSecret?: string;
-    oauthRedirectPort?: number;
-  }): Promise<unknown>;
+  openSession(opts: SeaNativeConnectionOptions): Promise<unknown>;
   /** Opaque Connection class — instance methods on the binding-generated d.ts. */
   Connection: Function;
   /** Opaque Statement class — instance methods on the binding-generated d.ts. */

native/sea/index.d.ts

@@ -22,11 +22,22 @@ export interface ExecuteOptions {
 /**
  * JS-visible auth-mode discriminant.
  *
- * Crosses the FFI as the string value (napi-rs string-enums emit the
- * Rust variant name verbatim on the JS side — `'Pat'`, `'OAuthM2m'`,
- * `'OAuthU2m'`). Keeping the discriminant explicit instead of inferring
- * it from "which Option is set" makes the napi-side validation
- * single-pass and the JS-side schema typed.
+ * Crosses the FFI as the variant name verbatim — napi-rs's
+ * `#[napi(string_enum)]` without an explicit case option emits the
+ * Rust variant identifier as-is, so this enum becomes
+ * `AuthMode.Pat = 'Pat'` / `AuthMode.OAuthM2m = 'OAuthM2m'` /
+ * `AuthMode.OAuthU2m = 'OAuthU2m'` in the auto-generated
+ * `native/sea/index.d.ts`. The JS adapter
+ * (`SeaNativeConnectionOptions` in `lib/sea/SeaAuth.ts`) must use the
+ * PascalCase literals verbatim.
+ *
+ * Keeping the discriminant explicit instead of inferring it from
+ * "which Option is set" makes the napi-side validation single-pass
+ * and the JS-side schema typed.
+ *
+ * Note: adding a variant here requires extending `open_session()`'s
+ * `match` — Rust will fail the build if the match is non-exhaustive,
+ * but the cross-reference shortens the review loop.
  */
 export const enum AuthMode {
   Pat = 'Pat',

native/sea/src/database.rs

@@ -40,11 +40,22 @@ use crate::util::guarded;
 
 /// JS-visible auth-mode discriminant.
 ///
-/// Crosses the FFI as the string value (napi-rs string-enums emit the
-/// Rust variant name verbatim on the JS side — `'Pat'`, `'OAuthM2m'`,
-/// `'OAuthU2m'`). Keeping the discriminant explicit instead of inferring
-/// it from "which Option is set" makes the napi-side validation
-/// single-pass and the JS-side schema typed.
+/// Crosses the FFI as the variant name verbatim — napi-rs's
+/// `#[napi(string_enum)]` without an explicit case option emits the
+/// Rust variant identifier as-is, so this enum becomes
+/// `AuthMode.Pat = 'Pat'` / `AuthMode.OAuthM2m = 'OAuthM2m'` /
+/// `AuthMode.OAuthU2m = 'OAuthU2m'` in the auto-generated
+/// `native/sea/index.d.ts`. The JS adapter
+/// (`SeaNativeConnectionOptions` in `lib/sea/SeaAuth.ts`) must use the
+/// PascalCase literals verbatim.
+///
+/// Keeping the discriminant explicit instead of inferring it from
+/// "which Option is set" makes the napi-side validation single-pass
+/// and the JS-side schema typed.
+///
+/// Note: adding a variant here requires extending `open_session()`'s
+/// `match` — Rust will fail the build if the match is non-exhaustive,
+/// but the cross-reference shortens the review loop.
 #[napi(string_enum)]
 pub enum AuthMode {
     Pat,

tests/unit/sea/_helpers/fakeBinding.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { SeaNativeBinding } from '../../../../lib/sea/SeaNativeLoader';
+
+export interface RecordedCall {
+  method: string;
+  args: unknown[];
+}
+
+export interface FakeBinding {
+  binding: SeaNativeBinding;
+  calls: RecordedCall[];
+}
+
+/**
+ * Build a fake `SeaNativeBinding` that records every `openSession` call
+ * and returns a `Connection` whose `close()` is also recorded. Shared
+ * across the SEA auth unit-test files (PAT / M2M / U2M / future flows)
+ * so the closure shape lives in exactly one place.
+ *
+ * No real native code runs — the fake is structural-typing-only.
+ */
+export function makeFakeBinding(): FakeBinding {
+  const calls: RecordedCall[] = [];
+
+  const fakeConnection = {
+    async executeStatement() {
+      throw new Error('not used in this test');
+    },
+    async close() {
+      calls.push({ method: 'connection.close', args: [] });
+    },
+  };
+
+  const binding: SeaNativeBinding = {
+    version() {
+      return 'fake-binding';
+    },
+    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
+      calls.push({ method: 'openSession', args: [opts] });
+      return fakeConnection as unknown;
+    },
+    Connection: function FakeConnection() {} as unknown as Function,
+    Statement: function FakeStatement() {} as unknown as Function,
+  };
+
+  return { binding, calls };
+}

tests/unit/sea/auth-m2m.test.ts

@@ -15,37 +15,10 @@
 import { expect } from 'chai';
 import SeaBackend from '../../../lib/sea/SeaBackend';
 import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
-import { SeaNativeBinding } from '../../../lib/sea/SeaNativeLoader';
 import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
 import AuthenticationError from '../../../lib/errors/AuthenticationError';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
-
-function makeFakeBinding() {
-  const calls: Array<{ method: string; args: unknown[] }> = [];
-
-  const fakeConnection = {
-    async executeStatement() {
-      throw new Error('not used in this test');
-    },
-    async close() {
-      calls.push({ method: 'connection.close', args: [] });
-    },
-  };
-
-  const binding: SeaNativeBinding = {
-    version() {
-      return 'fake-binding';
-    },
-    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
-      calls.push({ method: 'openSession', args: [opts] });
-      return fakeConnection as unknown;
-    },
-    Connection: function FakeConnection() {} as unknown as Function,
-    Statement: function FakeStatement() {} as unknown as Function,
-  };
-
-  return { binding, calls };
-}
+import { makeFakeBinding } from './_helpers/fakeBinding';
 
 describe('SeaAuth + SeaBackend — OAuth M2M auth flow', () => {
   describe('buildSeaConnectionOptions', () => {

tests/unit/sea/auth-pat.test.ts

@@ -15,42 +15,10 @@
 import { expect } from 'chai';
 import SeaBackend from '../../../lib/sea/SeaBackend';
 import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
-import { SeaNativeBinding } from '../../../lib/sea/SeaNativeLoader';
 import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
 import AuthenticationError from '../../../lib/errors/AuthenticationError';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
-
-/**
- * Fake napi binding that records the option object handed to `openSession`
- * and returns a fake `Connection` whose `close()` we can observe. No real
- * native code runs in this suite.
- */
-function makeFakeBinding() {
-  const calls: Array<{ method: string; args: unknown[] }> = [];
-
-  const fakeConnection = {
-    async executeStatement() {
-      throw new Error('not used in this test');
-    },
-    async close() {
-      calls.push({ method: 'connection.close', args: [] });
-    },
-  };
-
-  const binding: SeaNativeBinding = {
-    version() {
-      return 'fake-binding';
-    },
-    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
-      calls.push({ method: 'openSession', args: [opts] });
-      return fakeConnection as unknown;
-    },
-    Connection: function FakeConnection() {} as unknown as Function,
-    Statement: function FakeStatement() {} as unknown as Function,
-  };
-
-  return { binding, calls };
-}
+import { makeFakeBinding } from './_helpers/fakeBinding';
 
 describe('SeaAuth + SeaBackend — PAT auth flow', () => {
   describe('buildSeaConnectionOptions', () => {
@@ -133,10 +101,8 @@ describe('SeaAuth + SeaBackend — PAT auth flow', () => {
         host: 'example.cloud.databricks.com',
         path: '/sql/1.0/warehouses/abc',
         authType: 'token-provider',
-        tokenProvider: { getToken: async () => 'tok' } as unknown as ConnectionOptions extends infer T
-          ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            any
-          : never,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        tokenProvider: { getToken: async () => 'tok' } as any,
       };
 
       expect(() => buildSeaConnectionOptions(opts)).to.throw(

tests/unit/sea/auth-u2m.test.ts

@@ -15,36 +15,9 @@
 import { expect } from 'chai';
 import SeaBackend from '../../../lib/sea/SeaBackend';
 import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
-import { SeaNativeBinding } from '../../../lib/sea/SeaNativeLoader';
 import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
-
-function makeFakeBinding() {
-  const calls: Array<{ method: string; args: unknown[] }> = [];
-
-  const fakeConnection = {
-    async executeStatement() {
-      throw new Error('not used in this test');
-    },
-    async close() {
-      calls.push({ method: 'connection.close', args: [] });
-    },
-  };
-
-  const binding: SeaNativeBinding = {
-    version() {
-      return 'fake-binding';
-    },
-    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
-      calls.push({ method: 'openSession', args: [opts] });
-      return fakeConnection as unknown;
-    },
-    Connection: function FakeConnection() {} as unknown as Function,
-    Statement: function FakeStatement() {} as unknown as Function,
-  };
-
-  return { binding, calls };
-}
+import { makeFakeBinding } from './_helpers/fakeBinding';
 
 describe('SeaAuth + SeaBackend — OAuth U2M auth flow', () => {
   describe('buildSeaConnectionOptions', () => {