@dbx-tools/databricks 0.6.182 → 0.6.185

package/README.md

@@ -1,6 +1,7 @@
 # @dbx-tools/databricks
 
-Databricks runtime, workspace, filesystem, cloud, and network utilities.
+Databricks authentication, runtime, workspace, filesystem, cloud, and network
+utilities.
 
 Import this package when backend code needs workspace URL/id discovery, cloud
 provider/region lookup, App runtime detection, DNS resolution, or public-IP
@@ -10,8 +11,10 @@ Key features:
 
 - Workspace URL and numeric workspace id resolution from AppKit context,
   Databricks SDK config, env, and config files.
-- Rust-backed Databricks App detection shared with authentication providers.
-- Cached detection of whether the Databricks CLI auth surface is available.
+- U2M browser OAuth, M2M client credentials, PAT, `app_obo`, and `app_sp`
+  authentication.
+- Rust-backed App detection, CLI token access, file locks, and file-backed
+  caches.
 - `DatabricksFileSystem` (`FileSystem` over workspace files, UC volumes, and DBFS)
   with intelligent roots: `/Workspace/...`, `/Volumes/...` (also `/Volume/...` and
   `catalog.schema.volume`), `~` → `/Workspace/Users/<userName>`, and `/dbfs/...`.
@@ -23,27 +26,39 @@ Key features:
 - DNS A/AAAA lookup helpers for Databricks and adjacent service hosts.
 - Memoized outbound public-IP discovery for setup and diagnostics.
 
-## Detect The Runtime
+## Authenticate
 
 ```ts
-import { databricksCliAvailable, isDatabricksApp } from "@dbx-tools/databricks";
+import {
+  createPersistentAuth,
+  createPersistentAuthForRequest,
+  DatabricksAuthOptions,
+} from "@dbx-tools/databricks";
+
+const auth = await createPersistentAuth(DatabricksAuthOptions.create({}));
+const token = await auth.token();
+```
+
+Inside a Databricks App, request-scoped auth prefers OBO, then falls back to the
+ambient service principal:
 
-const inApp = isDatabricksApp();
-const hasDatabricksAuth = databricksCliAvailable();
+```ts
+const requestHeaders = new Map<string, string>();
+const forwardedToken = req.header("x-forwarded-access-token");
+if (forwardedToken) requestHeaders.set("x-forwarded-access-token", forwardedToken);
+const auth = await createPersistentAuthForRequest(DatabricksAuthOptions.create({}), requestHeaders);
 ```
 
-`isDatabricksApp()` honors `DBX_TOOLS_DATABRICKS_APP_ENV`, then requires a
-valid `DATABRICKS_APP_NAME`, HTTP(S) `DATABRICKS_HOST`, and
-`DATABRICKS_APP_PORT`. `databricksCliAvailable()` caches whether
-`databricks auth --help` succeeds for the process. The generated bindings and
-the package's direct TypeScript modules share this package root.
+OBO tokens are forwarded directly without caching. `app_sp` shares the complete
+M2M client-credentials implementation. Set `authType` or `profile` explicitly
+to override automatic App resolution.
 
 ## Relationship To Native AppKit
 
 Use native AppKit for its standard workspace client and plugin integrations.
-Use this package when code also needs App detection shared with Rust,
-Databricks filesystem root normalization, cloud region discovery, network
-helpers, or workspace identity fallbacks outside an AppKit request.
+Use this package when code needs Databricks filesystem root normalization,
+cloud region discovery, network helpers, or workspace identity fallbacks
+outside an AppKit request, or when direct Rust-backed authentication is needed.
 
 ## Databricks filesystem
 
@@ -127,8 +142,6 @@ short-lived reuse.
 - `workspace` - workspace URL/id, `tryGetWorkspaceClient` / `getWorkspaceClient`, and current username.
 - `cloud` - provider/region detection from public cloud IP ranges.
 - `net` - DNS A/AAAA resolution and outbound public-IP discovery.
-- package root - Rust-backed `isDatabricksApp` and
-  `databricksCliAvailable`.
 
 Zerobus endpoint construction builds on these helpers in
 [`@dbx-tools/databricks-zerobus`](../databricks-zerobus).

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/databricks";
-export const PACKAGE_VERSION = "0.6.182";
+export const PACKAGE_VERSION = "0.6.185";
 export * from "./src/bindings.ts";
 export * as cloud from "./src/cloud.ts";
 export * as databricksFS from "./src/databricks-fs.ts";