feat: add tokenCacheEnabled to control kernel U2M on-disk token cache

[eric-wang-1990]

What & why

Adds a tokenCacheEnabled?: boolean connection option (on the databricks-oauth auth type) to control the kernel backend's U2M on-disk OAuth token cache.

On the kernel path with OAuth U2M, the Rust kernel can persist the refresh token to an AES-256 encrypted on-disk cache at dirs::config_dir()/databricks-sql-kernel/oauth/ (~/Library/Application Support/... on macOS, ~/.config/... on Linux), so a later process skips the interactive browser login. This wires a client option through to the napi binding's tokenCacheEnabled field.

Behavior

• U2M-only. No effect on PAT/M2M.
• Disabled by default. When unset, the connector explicitly passes tokenCacheEnabled: false to the kernel — matching Thrift's in-memory (no on-disk persistence) posture, so migrating onto the kernel path doesn't silently start writing tokens to disk. Enabling is opt-in via tokenCacheEnabled: true. (The kernel's own default is enabled; the connector always sends false when the option is unset, so disable-by-default is the connector's deliberate choice.)
• Enable flag only for now (no passphrase surface); when enabled the kernel encrypts at rest with a machine-local derived key.
• The existing Thrift-only persistence (custom OAuthPersistence store) is untouched and still rejected on the kernel path — this new flag is a separate, simpler control.

Dependency

Consumes the napi field tokenCacheEnabled from databricks-sql-kernel #283, now merged to kernel main (merge commit 628abd6). This PR bumps KERNEL_REV 5e5dea9 → 628abd6 (additive over #282, so the Azure SP surface is preserved) and regenerates the committed napi binding, which now exposes the field. The kernel-e2e CI path builds the binding from KERNEL_REV, so it picks up the field.

Published npm pins stay at 0.2.0. No @databricks/databricks-sql-kernel 0.2.1 release has shipped yet, so bumping the 8 platform optionalDependencies to a nonexistent version would break npm install. Until that release lands (a follow-up commit here bumps the pins), npm consumers still get the 0.2.0 binding, which silently drops the unknown field — so disable-by-default doesn't take effect for them yet. Do not merge until the 0.2.1 release ships and the pins are bumped.

Testing

Unit

• mocha U2M mapping tests: unset ⇒ false, true ⇒ true, and the persistence rejection still throws. 322 kernel unit tests green against the rebuilt binding.

Runtime E2E (new)

Added an interactive U2M E2E suite (tests/e2e/kernel/auth-u2m-e2e.test.ts), gated behind DATABRICKS_KERNEL_U2M_INTERACTIVE + workspace host/path so CI still skips it (the browser flow needs a human). It backs up and restores the real on-disk cache dir around the run so a developer's own cached tokens are never destroyed.

Ran it against a live Azure pecotesting workspace, completing the browser login for each case:

Case	Flow	On-disk cache result
tokenCacheEnabled unset	U2M browser login → SELECT 1 = 1	No file written (cache dir empty) ✓
tokenCacheEnabled: true	U2M browser login → SELECT 1 = 1	An AES-encrypted (non-plaintext-JSON) {sha256}.json is written ✓

Result: 2 passing (17s). Confirms disable-by-default (Thrift parity) and opt-in enable end to end through DBSQLClient → KernelBackend → napi binding → live workspace. (Azure U2M routes through the kernel's cloud-blind in-house OAuthU2m flow, as expected — it uses the workspace's OIDC-discovered authorize endpoint verbatim.)

Related: databricks-sql-kernel #283.

This pull request and its description were written by Isaac.

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

✅ No issues identified by the review bot.

[Copilot]

Pull request overview

Adds a new tokenCacheEnabled?: boolean connection option for authType: 'databricks-oauth' to control whether the kernel backend’s U2M OAuth flow may use an on-disk refresh-token cache, while keeping “no persistence” as the default posture when migrating to the kernel path.

Changes:

• Plumbs tokenCacheEnabled through buildKernelConnectionOptions for OAuth U2M, defaulting to false when unset.
• Extends the public connection option types/docs to describe the new flag and its kernel/U2M-only behavior.
• Adds unit tests covering default false and opt-in true mapping for U2M.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
tests/unit/kernel/auth-u2m.test.ts	Adds assertions/tests to ensure tokenCacheEnabled is forwarded (default false, opt-in true) for kernel OAuth U2M.
lib/kernel/KernelAuth.ts	Adds tokenCacheEnabled to the kernel native option type and wires defaulting logic into the U2M mapping.
lib/contracts/IDBSQLClient.ts	Exposes tokenCacheEnabled?: boolean on databricks-oauth connection options with API docs.
CONNECTION_PARAMETERS.md	Documents the new connection parameter and calls out kernel-only behavior and default.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[peco-engineer-bot]

Fixed the misleading error wording and confirmed the mocked U2M auth suite still passes.

Pushed 83b91f0 (bundled with 1 other thread(s)).

[peco-engineer-bot]

Resolved with a documentation edit — the reviewer's point was valid and fully actionable in this PR.

Pushed 83b91f0 (bundled with 1 other thread(s)).

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

✅ No issues identified by the review bot.

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

Verdict: 1 Medium

Clean, well-scoped change wiring tokenCacheEnabled through to the kernel U2M path with sensible disable-by-default parity and good unit + interactive-e2e coverage. One medium concern: the regenerated native/kernel/index.js now enforces binding version 0.2.1 while package.json still pins 0.2.0 — an intentional-but-inconsistent split the author already flags as "do not merge" until the 0.2.1 release and pin bump land together.

[peco-review-bot]

🟡 Medium — The regenerated napi router now expects binding version 0.2.1 in every platform branch (and the WASI branch at ~L651), but package.json optionalDependencies still pin all 8 kernel packages to 0.2.0. The two were bumped out of lockstep.

The check is gated on NAPI_RS_ENFORCE_VERSION_CHECK, so default npm consumers are unaffected — but any environment that sets that flag will now hit Native binding package version mismatch, expected 0.2.1 but got 0.2.0 and fail to load, because npm installs the pinned 0.2.0. This contradicts the PR's own stated intent to keep consumers on 0.2.0 until 0.2.1 ships.

The PR description acknowledges this ("Do not merge until the 0.2.1 release ships and the pins are bumped"), so this is a state-of-the-PR gate rather than a logic bug — flagging so the version-check bump and the dependency pins land together in the same commit that flips to 0.2.1, not split across the merge boundary.

[peco-engineer-bot]

⛔ NEEDS HUMAN DECISION — the bots can't resolve this thread; a maintainer's input is required.

Valid point, but it cannot be actioned in this job. The version-check expects 0.2.1 in native/kernel/index.js (a generated file under the denied native/ path — not writable), while package.json optionalDependencies pin the 8 kernel packages to 0.2.0. Reconciling them requires either reverting the native router to 0.2.0 or bumping the package.json pins to 0.2.1 — but native/ and package.json are both off-limits here, and the reviewer/PR description explicitly gate this on the 0.2.1 kernel release shipping ("Do not merge until 0.2.1 ships and the pins are bumped"). This is a release-coordination / merge-boundary decision for a human: the napi-router version bump and the dependency pins must land together in the commit that flips to 0.2.1, once those packages are published.

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

Verdict: 1 High

Looks solid — the tokenCacheEnabled wiring in KernelAuth.ts is correctly scoped to the U2M branch, and unit/contract changes are consistent. One high concern: the new e2e test's after cleanup can delete a developer's real kernel OAuth token cache on the skip path, because this.skip() runs before the backup is taken but the after hook still deletes the cache dir unconditionally.

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

✅ No issues identified by the review bot.