feat(kernel): JWT private-key M2M auth on useKernel

[rahuls-db]

What

Adds OAuth machine-to-machine auth with a JWT private-key client assertion (RFC 7523) on the kernel backend (useKernel: true). The kernel signs a short-lived JWT with the service principal's private key instead of sending a client secret, and owns the token lifecycle; the workspace's OAuth IdP verifies it against the SP's registered public key.

Companion to the kernel-side feature (databricks-sql-kernel #249; napi token_url in #275) and the parallel databricks-sql-python / databricks-sql-go changes.

How

• lib/kernel/KernelAuth.ts — new JWT branch in buildKernelConnectionOptions (checked before the U2M/M2M-secret split; a private-key file is unambiguous JWT M2M intent) plus the OAuthM2mJwt native-option shape. Requires oauthClientId + oauthJwtKid; optional oauthJwtPassphrase / oauthJwtAlgorithm / oauthScopes / tokenUrl. Mutually exclusive with oauthClientSecret. Also threads tokenUrl through the existing M2M branch.
• lib/contracts/IDBSQLClient.ts — new oauthJwt* + tokenUrl fields on the databricks-oauth ConnectionOptions member.
• lib/DBSQLClient.ts — on the useKernel path, do not build the connector's own OAuth provider. It eagerly starts the U2M browser flow / M2M token exchange at connect time (a telemetry / feature-flag client calls authProvider.authenticate()) before the kernel is consulted — which, for the no-secret JWT case, launched a spurious browser listener. Hand over a minimal PAT provider only when a token is present. Mirrors the Python connector's use_kernel handling.

Usage

await client.connect({
  host: 'adb-….azuredatabricks.net',
  path: '/sql/1.0/warehouses/…',
  authType: 'databricks-oauth',
  oauthClientId: '<sp-client-id>',
  oauthJwtKeyFile: '/path/private_key.pem',
  oauthJwtKid: '<kid>',
  tokenUrl: 'https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token',
  oauthScopes: ['<databricks-resource-id>/.default'],
  useKernel: true,
});

Testing

• 9 new unit tests in tests/unit/kernel/auth-m2m-jwt.test.ts (routing, precedence, required-field validation, ambiguity guards); full kernel unit suite 318 passing. prettier + eslint clean.
• Verified end-to-end against an Azure Databricks warehouse: SELECT 1 → [{"n":1}], with the client's backend asserted to be KernelBackend (kernel path, not Thrift).

Requires a @databricks/databricks-sql-kernel build with JWT + tokenUrl support.

This pull request and its description were written by Isaac.

[peco-review-bot]

Verdict: 2 Low

Solid, well-documented addition; the JWT branch validation and precedence logic look correct and mirror the existing M2M/U2M handling. Two low-severity notes: telemetry authType misclassifies JWT M2M as external-browser (since it keys off oauthClientSecret), and the connect() auth-provider behavior change lacks direct unit coverage. Minor consistency gap worth noting: the PAT branch's ambiguity guard rejects token + oauthClientId/oauthClientSecret but not token + oauthJwtKeyFile, so a JWT key silently drops when authType: 'access-token' is used.

[rahuls-db]

@eric-wang-1990 what about the failing security scan jobs? They seem to be unrelated to this pr. Should I suppress them in this PR or there's a workaround?

[peco-review-bot]

Verdict: 1 Low

Looks good — solid, well-guarded feature with clear validation and good test coverage on the JWT path. One low: the newly-threaded tokenUrl on the shared-secret M2M branch (KernelAuth.ts:764) has no unit test, while its JWT counterpart does.

[peco-review-bot]

Verdict: 2 Low

Looks good — the JWT M2M branch cleanly mirrors the existing M2M/U2M routing, its guards are consistent, and coverage is solid. Two low, narrow notes: telemetry mapAuthType can mislabel a Thrift-path connection as oauth-m2m-jwt, and the deprecated custom authProvider arg is silently dropped on the useKernel path.

[vikrantpuppala]

@rahuls-db the security scan job is non-blocking

[peco-review-bot]

Verdict: 2 Low

Looks good — the JWT M2M branch is correctly ordered and thoroughly tested; the auth-provider gating on the kernel path is sound. Two low-severity ergonomics notes on the JWT branch around tokenUrl enforcement and the all-apis scope default, both of which would otherwise surface as opaque kernel-side failures.

[peco-review-bot]

🔵 Low — The JWT M2M branch validates oauthClientId and oauthJwtKid but treats tokenUrl as optional. Per this PR's own description, private_key_jwt cannot succeed against Databricks-native OIDC (it doesn't advertise the method), so tokenUrl (pointing at an external IdP like Entra) is effectively required for this flow to work at all. As written, omitting tokenUrl on the JWT branch passes all TS-side validation and then fails opaquely inside the kernel at connect time. Consider validating tokenUrl presence here with a clear, actionable error — matching the early-validation pattern already used for oauthClientId / oauthJwtKid a few lines above — so callers get the same crisp signal instead of a downstream kernel invalid_client.

[peco-review-bot]

🔵 Low — The JWT branch defaults oauthScopes to M2M_DEFAULT_SCOPES (['all-apis']), inherited verbatim from the shared-secret M2M path. But all-apis is a Databricks-native scope; the JWT private_key_jwt flow targets an external IdP (Entra), which rejects all-apis and expects <resource-id>/.default (as the usage example itself shows). Because the value is forwarded explicitly, the kernel's own default is never consulted — so a caller who omits oauthScopes on the JWT branch gets a scope that is essentially guaranteed to be wrong for the only IdP this flow supports. Consider either omitting oauthScopes when unset (letting the kernel default apply) or documenting that oauthScopes is de-facto required for the JWT flow.