sea-auth-u2m: OAuth M2M + U2M through SeaBackend → napi binding → kernel

Adds OAuth M2M and U2M onto the SEA auth path. The auth-u2m worktree
landed both at once (rather than rebasing on top of the M2M branch)
because the JS adapter flow-selector (`oauthClientSecret defined ?
M2M : U2M`, mirroring thrift `DBSQLClient.ts:143`) is cleanest when
both arms exist together — the no-secret branch was rejection-only
in the M2M-alone state.

The napi binding's `AuthMode` enum gains a third variant (`OAuthU2m`),
crossing the FFI as the PascalCase string `'OAuthU2m'`. The JS adapter
hardcodes `oauthRedirectPort: 8030` on the U2M payload to override
the kernel default of 8020 — preserves parity with thrift, which
defaults to 8030 (`OAuthManager.ts:245`). All other U2M knobs
(`client_id`, `scopes`, `callback_timeout`, `token_url_override`)
stay at kernel defaults; thrift hides them from its public surface
too, so SEA follows the same pattern.

`OAuthPersistence` is rejected on U2M with an explicit M1-Phase-2
deferral message: thrift exposes the hook, the kernel doesn't yet —
parity gap to close once `AuthConfig::External` lands. The kernel
disk cache at `~/.config/databricks-sql-kernel/oauth/{sha256}.json`
covers the standard flow today. Azure-direct knobs
(`azureTenantId` / `useDatabricksOAuthInAzure`) rejected on both
M2M and U2M with the same "Phase 2" message — kernel uses workspace
OIDC which works for Azure-databricks workspaces regardless.

Task: M1 OAuth M2M + U2M (sea-auth feature, U2M worktree).

Files:
- native/sea/src/database.rs — AuthMode { Pat, OAuthM2m, OAuthU2m } +
  ConnectionOptions union + open_session dispatch with U2M arm
  forwarding `oauth_redirect_port` from JS and leaving every other
  U2M kernel knob at None
- native/sea/index.{d.ts,js} — regenerated napi artifact
- lib/sea/SeaAuth.ts — buildSeaConnectionOptions grows M2M + U2M
  branches; flow selector mirrors thrift; persistence rejection
  message reads as a parity gap, not a feature add
- lib/sea/SeaNativeLoader.ts — SeaNativeBinding.openSession type
  accepts the three-arm discriminated payload
- tests/unit/sea/auth-pat.test.ts — assertions updated for new
  `authMode: 'Pat'` round-trip; no-secret OAuth now asserts U2M
  happy-path dispatch
- tests/unit/sea/auth-m2m.test.ts — new (8 cases — same as the
  M2M-worktree commit, minus the now-obsolete no-secret rejection)
- tests/unit/sea/auth-u2m.test.ts — new (7 cases — happy path,
  port 8030 hardcode, clientId not propagated, path slash prepend,
  Azure rejected, persistence rejected, SeaBackend round-trip)
- tests/integration/sea/auth-m2m-e2e.test.ts — env-gated live e2e
  (mirrors the M2M-worktree e2e)
- tests/integration/sea/auth-u2m-e2e.test.ts — new (it.skip pending
  TBD-oauth_u2m_test_harness; comment points at testing-agent's
  Playwright/Puppeteer harness work)

Tests:
- Unit: 55/55 pass (`npm run test -- 'tests/unit/sea/**/*.test.ts'`):
  13 PAT (assertions updated for authMode + no-secret now U2M),
  8 M2M, 7 U2M, 25 SeaErrorMapping regression, 2 ConnectionOptions
  base.
- U2M e2e: 1 pending (intentional `it.skip` — gated on browser
  harness).
- M2M e2e: same as the M2M-worktree commit — kernel-side OAuth
  plumbing reaches the workspace; pecotesting SP credentials produce
  the workspace's `invalid_client` (verified reproducible via
  direct curl), an environmental issue not a code defect.

Co-authored-by: Isaac

Author: msrathore-db

lib/sea/SeaAuth.ts

@@ -16,18 +16,58 @@ 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
+ * thrift default (8030) is invariant for SEA callers — preserving parity
+ * with the existing Node driver. Not exposed on the public
+ * `ConnectionOptions` (thrift hides `callbackPorts` from its public
+ * surface too — see nodejs-thrift-expert survey §B.2).
+ */
+const U2M_DEFAULT_REDIRECT_PORT = 8030;
+
 /**
  * Shape consumed by the napi-binding's `openSession()` (see
- * `native/sea/index.d.ts`). M0 supports PAT only — `token` is required.
+ * `native/sea/index.d.ts`). Mirrors `ConnectionOptions` in the binding's
+ * `.d.ts`; declared locally to avoid coupling the JS-side adapter to the
+ * auto-generated TS file.
  *
- * Mirrors `ConnectionOptions` in the binding's `.d.ts`; declared locally
- * to avoid coupling the JS-side adapter to the auto-generated TS file.
+ * Discriminated by `authMode`:
+ * - `'Pat'`       → `token` is the PAT.
+ * - `'OAuthM2m'`  → `oauthClientId` + `oauthClientSecret` drive a
+ *                   kernel-side client_credentials exchange.
+ * - `'OAuthU2m'`  → `oauthRedirectPort` overrides the kernel default;
+ *                   everything else (client_id, scopes, callback timeout,
+ *                   token_url_override) uses kernel defaults.
  */
-export interface SeaNativeConnectionOptions {
-  hostName: string;
-  httpPath: string;
-  token: string;
-}
+export type SeaNativeConnectionOptions =
+  | {
+      hostName: string;
+      httpPath: string;
+      authMode: 'Pat';
+      token: string;
+    }
+  | {
+      hostName: string;
+      httpPath: string;
+      authMode: 'OAuthM2m';
+      oauthClientId: string;
+      oauthClientSecret: string;
+    }
+  | {
+      hostName: string;
+      httpPath: string;
+      authMode: 'OAuthU2m';
+      oauthRedirectPort: number;
+    };
 
 function prependSlash(str: string): string {
   if (str.length > 0 && str.charAt(0) !== '/') {
@@ -37,47 +77,124 @@ function prependSlash(str: string): string {
 }
 
 /**
- * Validate that the user-supplied `ConnectionOptions` describe a PAT auth
- * configuration and build the napi-binding's connection-options shape.
+ * Validate the user-supplied `ConnectionOptions` and build the
+ * napi-binding's connection-options shape.
  *
- * M0 SCOPE: PAT only.
- *   - Accepts `authType: 'access-token'` and the undefined-authType default
- *     (which already means PAT throughout the existing driver — see
+ * Supported auth modes:
+ *   - PAT: `authType: 'access-token'` (or undefined, which already means
+ *     PAT throughout the existing driver — see
  *     `DBSQLClient.createAuthProvider`).
- *   - Rejects every other `authType` discriminant with a clear
- *     "M0 supports only PAT" message so callers know OAuth / Federation /
- *     custom providers land in M1.
+ *   - OAuth M2M: `authType: 'databricks-oauth'` + `oauthClientId` +
+ *     `oauthClientSecret`. Kernel handles OIDC discovery, client_credentials
+ *     exchange, and re-auth on expiry internally (no caching needed — M2M
+ *     never has a refresh token; see `auth/oauth/m2m.rs` and the thrift
+ *     parity note at `OAuthManager.ts:178-181`).
+ *   - OAuth U2M: `authType: 'databricks-oauth'` + NO `oauthClientSecret`.
+ *     Kernel runs the PKCE auth-code dance (opens a browser, listens on
+ *     localhost:8030, exchanges the code, persists to
+ *     `~/.config/databricks-sql-kernel/oauth/{sha256}.json`). The flow
+ *     selector matches thrift at `DBSQLClient.ts:143` —
+ *     `oauthClientSecret defined ? M2M : U2M`.
+ *
+ * Out of scope on the OAuth paths (rejected with a clear error):
+ *   - `azureTenantId` / `useDatabricksOAuthInAzure` → Microsoft Entra
+ *     direct flow with `<tenantId>/.default` scope rewrite. The kernel
+ *     uses workspace-OIDC discovery (which works against Azure workspaces
+ *     too — they serve `/oidc/.well-known/...`); Entra-direct is a
+ *     follow-on M1 Phase 2 task.
+ *   - `persistence` on either flavor — for M2M the kernel doesn't cache
+ *     (re-issuing is cheap; M2M has no refresh token). For U2M, custom
+ *     persistence requires the kernel to expose `AuthConfig::External`
+ *     (M1 Phase 2 task). The kernel-internal disk cache works for the
+ *     standard flow today.
  *
  * Throws:
- *   - `AuthenticationError` when the auth mode is PAT but `token` is missing
- *     or empty.
- *   - `HiveDriverError` when the auth mode is anything other than PAT.
+ *   - `AuthenticationError` for missing required credentials.
+ *   - `HiveDriverError` for unsupported auth modes / Azure-direct /
+ *     custom persistence.
  */
 export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNativeConnectionOptions {
   const { authType } = options as { authType?: string };
 
-  if (authType !== undefined && authType !== 'access-token') {
-    throw new HiveDriverError(
-      `SEA backend (M0) supports only PAT auth (authType: 'access-token'); ` +
-        `got authType: '${authType}'. Other auth modes (databricks-oauth, ` +
-        `token-provider, external-token, static-token, custom) will land in M1.`,
-    );
+  const base = {
+    hostName: options.host,
+    httpPath: prependSlash(options.path),
+  };
+
+  if (authType === undefined || authType === 'access-token') {
+    const { token } = options as { token?: string };
+    if (typeof token !== 'string' || token.length === 0) {
+      throw new AuthenticationError(
+        'SEA backend: a non-empty PAT must be supplied via `token` when using `authType: \'access-token\'`.',
+      );
+    }
+    return { ...base, authMode: 'Pat', token };
   }
 
-  // PAT path — at this point `options` is structurally the access-token branch
-  // of `AuthOptions`, which guarantees a `token` field at the type level. We
-  // still defensively re-check because the public ConnectionOptions type
-  // permits `authType: undefined` with no token at runtime.
-  const { token } = options as { token?: string };
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new AuthenticationError(
-      'SEA backend: a non-empty PAT must be supplied via `token` when using `authType: \'access-token\'`.',
-    );
+  if (authType === 'databricks-oauth') {
+    const oauth = options as {
+      oauthClientId?: string;
+      oauthClientSecret?: string;
+      azureTenantId?: string;
+      useDatabricksOAuthInAzure?: boolean;
+      persistence?: unknown;
+    };
+
+    if (oauth.azureTenantId !== undefined || oauth.useDatabricksOAuthInAzure === true) {
+      throw new HiveDriverError(
+        'SEA backend: Azure-direct OAuth (azureTenantId / useDatabricksOAuthInAzure) ' +
+          'is a later M1 task; the kernel uses workspace-OIDC discovery today, ' +
+          'which works against Azure workspaces with no extra options.',
+      );
+    }
+
+    // Flow selector mirrors thrift's `DBSQLClient.createAuthProvider`
+    // (`DBSQLClient.ts:143`): `oauthClientSecret defined ? M2M : U2M`.
+    if (oauth.oauthClientSecret === undefined) {
+      // U2M.
+      if (oauth.persistence !== undefined) {
+        throw new HiveDriverError(
+          'SEA backend: `persistence` (custom OAuth token store) is not yet wired through ' +
+            'to the kernel — requires `AuthConfig::External` plumbing planned for M1 Phase 2. ' +
+            'Today the kernel auto-persists U2M tokens to ' +
+            '`~/.config/databricks-sql-kernel/oauth/` which works for the standard flow; ' +
+            "the JS-supplied hook (matching thrift's `OAuthPersistence` interface) lands " +
+            'when the kernel exposes it.',
+        );
+      }
+      return {
+        ...base,
+        authMode: 'OAuthU2m',
+        oauthRedirectPort: U2M_DEFAULT_REDIRECT_PORT,
+      };
+    }
+
+    // M2M.
+    if (typeof oauth.oauthClientId !== 'string' || oauth.oauthClientId.length === 0) {
+      throw new AuthenticationError('SEA backend: `oauthClientId` is required for OAuth M2M.');
+    }
+    if (typeof oauth.oauthClientSecret !== 'string' || oauth.oauthClientSecret.length === 0) {
+      throw new AuthenticationError(
+        'SEA backend: `oauthClientSecret` must be a non-empty string for OAuth M2M.',
+      );
+    }
+    if (oauth.persistence !== undefined) {
+      throw new HiveDriverError(
+        'SEA backend: `persistence` is not supported on OAuth M2M ' +
+          '(M2M tokens have no refresh token; the kernel re-issues on expiry).',
+      );
+    }
+    return {
+      ...base,
+      authMode: 'OAuthM2m',
+      oauthClientId: oauth.oauthClientId,
+      oauthClientSecret: oauth.oauthClientSecret,
+    };
   }
 
-  return {
-    hostName: options.host,
-    httpPath: prependSlash(options.path),
-    token,
-  };
+  throw new HiveDriverError(
+    `SEA backend: unsupported auth mode '${authType}'. ` +
+      `Supported modes today: 'access-token' (PAT), 'databricks-oauth' (M2M + U2M). ` +
+      `Other modes (token-provider, external-token, static-token, custom) are M1+ follow-ups.`,
+  );
 }

lib/sea/SeaNativeLoader.ts

@@ -91,8 +91,23 @@ export interface SeaNativeConnection {
 export interface SeaNativeBinding {
   /** Returns the native crate version (smoke test for the binding's load path). */
   version(): string;
-  /** Open a session over PAT auth. Returns an opaque Connection. */
-  openSession(opts: { hostName: string; httpPath: string; token: string }): Promise<SeaNativeConnection>;
+  /**
+   * 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.
+   */
+  openSession(opts: {
+    hostName: string;
+    httpPath: string;
+    authMode: 'Pat' | 'OAuthM2m' | 'OAuthU2m';
+    token?: string;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    oauthRedirectPort?: number;
+  }): Promise<SeaNativeConnection>;
   /** 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

@@ -20,10 +20,34 @@ export interface ExecuteOptions {
   sessionConfig?: Record<string, string>
 }
 /**
- * JS-visible options for opening a Databricks SQL session over PAT.
+ * JS-visible auth-mode discriminant.
  *
- * M0 supports PAT only — `token` is required. OAuth M2M / U2M variants
- * land in M1 along with a discriminated-union shape on the JS side.
+ * 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.
+ */
+export const enum AuthMode {
+  Pat = 'Pat',
+  OAuthM2m = 'OAuthM2m',
+  OAuthU2m = 'OAuthU2m'
+}
+/**
+ * JS-visible options for opening a Databricks SQL session.
+ *
+ * Discriminated by `auth_mode`:
+ * - `AuthMode::Pat`      → requires `token`; ignores oauth_*.
+ * - `AuthMode::OAuthM2m` → requires `oauth_client_id` + `oauth_client_secret`.
+ * - `AuthMode::OAuthU2m` → kernel handles the auth-code flow with
+ *   default client_id (`databricks-cli`), scopes
+ *   (`["all-apis","offline_access"]`), and OIDC discovery; the JS
+ *   adapter hardcodes `oauth_redirect_port` to 8030 to override the
+ *   kernel default of 8020 (thrift uses 8030 — preserves parity).
+ *
+ * Scopes / token_url_override / client_id / callback_timeout are not
+ * exposed — kernel defaults match thrift parity and the public driver
+ * surface has no demand to override them.
  */
 export interface ConnectionOptions {
   /**
@@ -36,15 +60,24 @@ export interface ConnectionOptions {
    * kernel parses out the warehouse id.
    */
   httpPath: string
+  /** Auth-mode discriminant. Required. */
+  authMode: AuthMode
+  /** Personal access token. Required iff `auth_mode == Pat`. */
+  token?: string
+  /** OAuth client id. Required iff `auth_mode == OAuthM2m`. */
+  oauthClientId?: string
+  /** OAuth client secret. Required iff `auth_mode == OAuthM2m`. */
+  oauthClientSecret?: string
   /**
-   * Personal access token. Must be non-empty (the kernel rejects
-   * empty PATs at session construction).
+   * Local listener port for the U2M authorization-code callback.
+   * Forwarded verbatim to the kernel; the JS adapter hardcodes 8030
+   * for thrift parity.
    */
-  token: string
+  oauthRedirectPort?: number
 }
 /**
- * Open a Databricks SQL session over PAT auth and return an opaque
- * `Connection` wrapping the kernel `Session`.
+ * Open a Databricks SQL session and return an opaque `Connection`
+ * wrapping the kernel `Session`. Supports PAT, OAuth M2M, and OAuth U2M.
  *
  * The JS-visible name is `openSession` (napi-rs converts snake_case
  * to camelCase for free functions).

tests/integration/sea/auth-m2m-e2e.test.ts

@@ -0,0 +1,80 @@
+// 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 { expect } from 'chai';
+import { DBSQLClient } from '../../../lib';
+
+/**
+ * sea-auth M1 OAuth M2M end-to-end:
+ *   1. Construct a DBSQLClient.
+ *   2. `connect({ useSEA: true, authType: 'databricks-oauth', oauthClientId,
+ *      oauthClientSecret })` against pecotesting.
+ *   3. `openSession()` — kernel runs OIDC discovery + client_credentials
+ *      exchange. Successful openSession is the proof that the kernel-side
+ *      OAuth M2M plumbing works end-to-end: discovery + token exchange +
+ *      Bearer header on the create-session request all succeeded.
+ *   4. Close the session, then the client.
+ *
+ * No query is executed here — execution is the responsibility of the
+ * sea-execution feature's own e2e (mirror of the M0 PAT e2e scope at
+ * `auth-pat-e2e.test.ts`). If kernel-side OAuth fails, `openSession()`
+ * raises before returning.
+ *
+ * Required env (exported by `~/.zshrc` on the developer machine):
+ *   - DATABRICKS_PECOTESTING_SERVER_HOSTNAME
+ *   - DATABRICKS_PECOTESTING_HTTP_PATH
+ *   - DATABRICKS_PECO_CLIENT_ID
+ *   - DATABRICKS_PECO_CLIENT_SECRET
+ *
+ * Skipped (not failed) when any of the four env vars is missing, so CI
+ * machines without OAuth credentials don't fail-flap.
+ */
+describe('sea-auth e2e — OAuth M2M through DBSQLClient ↔ SeaBackend ↔ napi binding', function suite() {
+  const host = process.env.DATABRICKS_PECOTESTING_SERVER_HOSTNAME;
+  const path = process.env.DATABRICKS_PECOTESTING_HTTP_PATH;
+  const oauthClientId = process.env.DATABRICKS_PECO_CLIENT_ID;
+  const oauthClientSecret = process.env.DATABRICKS_PECO_CLIENT_SECRET;
+
+  this.timeout(120_000);
+
+  before(function gate() {
+    if (!host || !path || !oauthClientId || !oauthClientSecret) {
+      // eslint-disable-next-line no-invalid-this
+      this.skip();
+    }
+  });
+
+  it('connects, opens a session, closes the session, closes the client', async () => {
+    const client = new DBSQLClient();
+
+    const connected = await client.connect({
+      host: host as string,
+      path: path as string,
+      authType: 'databricks-oauth',
+      oauthClientId: oauthClientId as string,
+      oauthClientSecret: oauthClientSecret as string,
+      useSEA: true,
+    });
+    expect(connected).to.equal(client);
+
+    const session = await client.openSession();
+    expect(session.id).to.be.a('string');
+    expect(session.id.length).to.be.greaterThan(0);
+
+    const status = await session.close();
+    expect(status.isSuccess).to.equal(true);
+
+    await client.close();
+  });
+});