feat(kernel): forward identity federation client ID

Author: vuanhphung

KERNEL_REV

@@ -1 +1 @@
-0d46716c466897148dfc1d2976ff03bdf097998c
+eff8950428f4e6cc9975c663ec919f334962f7d0

lib/contracts/IDBSQLClient.ts

@@ -14,6 +14,8 @@ type AuthOptions =
   | {
       authType?: 'access-token';
       token: string;
+      /** Kernel backend: selects mandatory SP-wide Workload Identity Federation. */
+      identityFederationClientId?: string;
     }
   | {
       authType: 'databricks-oauth';
@@ -26,6 +28,8 @@ 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>;
+      /** Kernel backend: selects mandatory SP-wide Workload Identity Federation. */
+      identityFederationClientId?: string;
     }
   | {
       authType: 'custom';

lib/kernel/KernelAuth.ts

@@ -61,6 +61,9 @@ const DEFAULT_OAUTH_CLIENT_ID = 'databricks-sql-connector';
  *                   everything else (client_id, scopes, callback timeout,
  *                   token_url_override) uses kernel defaults.
  *
+ * A non-empty `identityFederationClientId` selects mandatory SP-wide
+ * workload-identity token exchange for every auth mode.
+ *
  * 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
@@ -212,10 +215,19 @@ export interface KernelProxyOptions {
   };
 }
 
+export interface KernelFederationOptions {
+  /**
+   * SP-wide Workload Identity Federation client id. Omitted selects BYOT /
+   * account-wide WIF.
+   */
+  identityFederationClientId?: string;
+}
+
 export type KernelNativeConnectionOptions = KernelSessionDefaults &
   KernelTlsOptions &
   KernelHttpOptions &
   KernelProxyOptions &
+  KernelFederationOptions &
   (
     | {
         hostName: string;
@@ -559,7 +571,8 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
     maxConnections?: number;
   } & KernelTlsOptions &
     KernelHttpOptions &
-    KernelProxyOptions = {
+    KernelProxyOptions &
+    KernelFederationOptions = {
     hostName: options.host,
     httpPath: prependSlash(options.path),
     // Match the NodeJS Thrift driver, which surfaces INTERVAL columns as
@@ -579,6 +592,11 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
     ...buildKernelProxyOptions(options),
   };
 
+  const { identityFederationClientId } = options as { identityFederationClientId?: string };
+  if (identityFederationClientId) {
+    base.identityFederationClientId = identityFederationClientId;
+  }
+
   // kernel-only pool sizing; read via cast to match how this function reads the
   // other kernel-specific options (TLS) — they live on the internal options
   // surface, not the published public `ConnectionOptions` `.d.ts`.

native/kernel/index.d.ts

@@ -43,6 +43,19 @@ describe('KernelAuth + KernelBackend — OAuth M2M auth flow', () => {
       });
     });
 
+    it('forwards a federation client id on M2M auth', () => {
+      const native = buildKernelConnectionOptions({
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'databricks-oauth',
+        oauthClientId: 'client-uuid',
+        oauthClientSecret: 'dose-fake-secret',
+        identityFederationClientId: 'federation-client',
+      });
+
+      expect(native.identityFederationClientId).to.equal('federation-client');
+    });
+
     it('defaults M2M oauthScopes to all-apis (Thrift + kernel parity)', () => {
       const native = buildKernelConnectionOptions({
         host: 'example.cloud.databricks.com',
@@ -190,6 +203,7 @@ describe('KernelAuth + KernelBackend — OAuth M2M auth flow', () => {
         authType: 'databricks-oauth',
         oauthClientId: 'client-uuid',
         oauthClientSecret: 'dose-fake-secret',
+        identityFederationClientId: 'federation-client',
       });
 
       const session = await backend.openSession({});
@@ -207,6 +221,7 @@ describe('KernelAuth + KernelBackend — OAuth M2M auth flow', () => {
         oauthClientId: 'client-uuid',
         oauthClientSecret: 'dose-fake-secret',
         oauthScopes: ['all-apis'],
+        identityFederationClientId: 'federation-client',
       });
 
       await session.close();

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

@@ -53,6 +53,28 @@ describe('KernelAuth — PAT auth options builder', () => {
       }
     });
 
+    it('forwards a federation client id on PAT auth', () => {
+      const native = buildKernelConnectionOptions({
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        identityFederationClientId: 'federation-client',
+      });
+
+      expect(native.identityFederationClientId).to.equal('federation-client');
+    });
+
+    it('omits an empty federation client id', () => {
+      const native = buildKernelConnectionOptions({
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        identityFederationClientId: '',
+      });
+
+      expect(native).not.to.have.property('identityFederationClientId');
+    });
+
     it('prepends `/` to a path missing the leading slash', () => {
       const opts: ConnectionOptions = {
         host: 'example.cloud.databricks.com',

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

@@ -40,6 +40,17 @@ describe('KernelAuth + KernelBackend — OAuth U2M auth flow', () => {
       });
     });
 
+    it('forwards a federation client id on U2M auth', () => {
+      const native = buildKernelConnectionOptions({
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'databricks-oauth',
+        identityFederationClientId: 'federation-client',
+      });
+
+      expect(native.identityFederationClientId).to.equal('federation-client');
+    });
+
     it('defaults U2M oauthScopes to Thrift parity (sql offline_access)', () => {
       const native = buildKernelConnectionOptions({
         host: 'example.cloud.databricks.com',