fix(kernel): move JWT M2M options to internal type; address review

Addresses PR #504 review feedback:

- Move oauthJwtKeyFile/oauthJwtKid/oauthJwtPassphrase/oauthJwtAlgorithm/
  tokenUrl off the public `databricks-oauth` AuthOptions onto
  InternalConnectionOptions (kernel-only), mirroring `useKernel` and the
  TLS knobs. The Thrift backend has no JWT client-assertion path, so
  exposing them on the shared public type would let a Thrift caller set
  them and have them silently ignored (Eric's divergence concern).
- Classify JWT M2M correctly in telemetry `mapAuthType` (`oauth-m2m-jwt`)
  instead of misreporting it as `external-browser` (bot F1).
- Reject a PAT `token` supplied alongside `oauthJwtKeyFile` in the
  PAT-branch ambiguity guard, so a JWT key can't be silently dropped
  under authType 'access-token' (bot consistency note).
- Add regression tests: connect() on the useKernel path installs no
  OAuth provider (no eager browser flow) / a PAT-only provider when a
  token is present (bot F2); plus the new PAT+JWT ambiguity guard.

Co-authored-by: Isaac
Signed-off-by: Rahul Singhal <rahul.singhal@databricks.com>

Author: rahuls-db

lib/DBSQLClient.ts

@@ -497,8 +497,17 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
    */
   private mapAuthType(options: ConnectionOptions): string {
     switch (options.authType) {
-      case 'databricks-oauth':
+      case 'databricks-oauth': {
+        // JWT private-key M2M (kernel-only) presents no `oauthClientSecret`,
+        // so without this check it would misreport as `external-browser`
+        // (U2M) — the opposite of its machine-to-machine nature. The field
+        // lives on the internal options surface (see InternalConnectionOptions).
+        const { oauthJwtKeyFile } = options as ConnectionOptions & InternalConnectionOptions;
+        if (oauthJwtKeyFile !== undefined) {
+          return 'oauth-m2m-jwt';
+        }
         return options.oauthClientSecret === undefined ? 'external-browser' : 'oauth-m2m';
+      }
       case 'custom':
         return 'custom';
       case 'token-provider':

lib/contracts/IDBSQLClient.ts

@@ -26,22 +26,6 @@ type AuthOptions =
       // U2M flow to `['sql', 'offline_access']` (parity with the Thrift driver's
       // `defaultOAuthScopes`), overriding the kernel's bare `all-apis offline_access`.
       oauthScopes?: Array<string>;
-      // JWT private-key M2M (RFC 7523 client assertion) — KERNEL BACKEND ONLY
-      // (`useKernel: true`). Supplying `oauthJwtKeyFile` selects the JWT
-      // client-assertion flow: the kernel signs a short-lived assertion with the
-      // private key instead of sending a client secret. Requires `oauthClientId`
-      // and `oauthJwtKid`. Optional `oauthJwtPassphrase` (encrypted PKCS#8 key),
-      // `oauthJwtAlgorithm` (default `RS256`), `oauthScopes`, and `tokenUrl` (the
-      // IdP token endpoint — required when auth is against an external IdP such as
-      // Entra ID, which is where `private_key_jwt` is supported). Mutually
-      // exclusive with `oauthClientSecret`.
-      oauthJwtKeyFile?: string;
-      oauthJwtKid?: string;
-      oauthJwtPassphrase?: string;
-      oauthJwtAlgorithm?: string;
-      // OAuth token endpoint override (kernel backend). Points the M2M /
-      // JWT client-assertion grant at the workspace's IdP token endpoint.
-      tokenUrl?: string;
     }
   | {
       authType: 'custom';

lib/contracts/InternalConnectionOptions.ts

@@ -74,4 +74,55 @@ export interface InternalConnectionOptions {
    * @internal kernel path only.
    */
   clientKeyPem?: Buffer | string;
+
+  /**
+   * kernel-only: JWT private-key M2M (RFC 7523 client assertion). Supplying
+   * `oauthJwtKeyFile` (alongside `authType: 'databricks-oauth'`) selects the
+   * JWT client-assertion flow: the kernel signs a short-lived assertion with
+   * the private key instead of sending a client secret. Requires
+   * `oauthClientId` (the assertion issuer/subject) and `oauthJwtKid` (the key
+   * id written into the JWT header). Mutually exclusive with
+   * `oauthClientSecret`.
+   *
+   * These live on the internal options surface — NOT the public
+   * `databricks-oauth` `AuthOptions` — because the Thrift backend has no
+   * JWT client-assertion path; exposing them publicly would let a Thrift
+   * caller set them and have them silently ignored. The kernel path reads
+   * them via the `InternalConnectionOptions` cast, exactly like `useKernel`
+   * and the TLS knobs above.
+   * @internal kernel path only.
+   */
+  oauthJwtKeyFile?: string;
+
+  /**
+   * kernel-only: key id written into the JWT assertion header so the IdP can
+   * select the registered public key. Required when `oauthJwtKeyFile` is set.
+   * @internal kernel path only.
+   */
+  oauthJwtKid?: string;
+
+  /**
+   * kernel-only: passphrase for an encrypted PKCS#8 private key
+   * (`oauthJwtKeyFile`). Omit for an unencrypted key.
+   * @internal kernel path only.
+   */
+  oauthJwtPassphrase?: string;
+
+  /**
+   * kernel-only: JWT signing algorithm for the client assertion. Defaults to
+   * `RS256` in the kernel when omitted.
+   * @internal kernel path only.
+   */
+  oauthJwtAlgorithm?: string;
+
+  /**
+   * kernel-only: OAuth token-endpoint override. Points the M2M /
+   * JWT client-assertion grant at the workspace's IdP token endpoint —
+   * required when auth is against an external IdP such as Entra ID, which is
+   * where `private_key_jwt` is supported. Applies to both shared-secret M2M
+   * and JWT M2M (auth-method-agnostic, matching JDBC's
+   * `OAuth2ConnAuthTokenEndpoint`).
+   * @internal kernel path only.
+   */
+  tokenUrl?: string;
 }

lib/kernel/KernelAuth.ts

@@ -629,9 +629,13 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
         "kernel backend: a non-empty PAT must be supplied via `token` when using `authType: 'access-token'`.",
       );
     }
-    if (oauth.oauthClientId !== undefined || oauth.oauthClientSecret !== undefined) {
+    if (
+      oauth.oauthClientId !== undefined ||
+      oauth.oauthClientSecret !== undefined ||
+      oauth.oauthJwtKeyFile !== undefined
+    ) {
       throw new HiveDriverError(
-        'kernel backend: cannot supply both `token` and `oauthClientId`/`oauthClientSecret` ' +
+        'kernel backend: cannot supply both `token` and `oauthClientId`/`oauthClientSecret`/`oauthJwtKeyFile` ' +
           "on the same connection. Pick one: 'access-token' (PAT) uses `token`; " +
           "'databricks-oauth' uses the OAuth fields.",
       );

tests/unit/DBSQLClient.test.ts

@@ -284,6 +284,57 @@ describe('DBSQLClient.connect', () => {
     }
   });
 
+  it('useKernel: true with an OAuth flow installs NO auth provider (kernel owns auth; no eager browser flow)', async () => {
+    const client = new DBSQLClient();
+
+    // `useKernel` + `databricks-oauth` (U2M: no secret, no token). The kernel
+    // owns the full auth lifecycle here, so `connect()` must NOT build the
+    // connector's own OAuth provider (which would eagerly open a browser /
+    // run the token exchange at connect() time via a telemetry client). The
+    // authProvider is assigned before the backend connects, so it is set even
+    // though the subsequent KernelBackend connect() rejects (absent native
+    // binding in CI / no live workspace).
+    const kernelOAuthOptions = {
+      ...connectOptions,
+      token: undefined,
+      authType: 'databricks-oauth',
+      useKernel: true,
+    } as any;
+
+    try {
+      await client.connect(kernelOAuthOptions);
+    } catch (error) {
+      if (error instanceof AssertionError || !(error instanceof Error)) {
+        throw error;
+      }
+      // Expected: KernelBackend connect() rejects (native binding absent / no
+      // live workspace). The contract under test is the authProvider decision,
+      // which happened before the throw.
+    }
+
+    expect(client['authProvider']).to.be.undefined;
+  });
+
+  it('useKernel: true with a token installs a PAT-only PlainHttpAuthentication provider', async () => {
+    const client = new DBSQLClient();
+
+    // `useKernel` + a PAT: the connector hands the kernel a minimal PAT
+    // provider (for the telemetry / feature-flag clients) rather than
+    // undefined, and still must NOT build an OAuth provider.
+    const kernelPatOptions = { ...connectOptions, token: 'dapiXXXX', useKernel: true } as any;
+
+    try {
+      await client.connect(kernelPatOptions);
+    } catch (error) {
+      if (error instanceof AssertionError || !(error instanceof Error)) {
+        throw error;
+      }
+      // Expected: KernelBackend connect() rejects (native binding absent).
+    }
+
+    expect(client['authProvider']).to.be.instanceOf(PlainHttpAuthentication);
+  });
+
   it('populates config.customHeaders with org-id parsed from ?o= (SPOG)', async () => {
     const client = new DBSQLClient();
     await client.connect({ ...connectOptions, path: '/sql/1.0/warehouses/abc?o=12345678901234' });

tests/unit/kernel/auth-m2m-jwt.test.ts

@@ -105,6 +105,22 @@ describe('KernelAuth — OAuth M2M JWT private-key auth flow', () => {
     );
   });
 
+  it('rejects a PAT `token` supplied alongside `oauthJwtKeyFile` (ambiguous)', () => {
+    // A JWT key under the PAT path (authType access-token) would otherwise be
+    // silently dropped; the PAT-branch ambiguity guard must reject it, just as
+    // it does for oauthClientId / oauthClientSecret.
+    expect(() =>
+      buildKernelConnectionOptions({
+        host: 'example.azuredatabricks.net',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'access-token',
+        token: 'dapiXXXX',
+        oauthJwtKeyFile: '/keys/jwt.pem',
+        oauthJwtKid: 'kid-1',
+      } as ConnectionOptions),
+    ).to.throw(HiveDriverError, /both `token` and .*`oauthJwtKeyFile`/);
+  });
+
   it('rejects persistence on the JWT M2M path', () => {
     expect(() =>
       buildKernelConnectionOptions({