@dbx-tools/auth 0.9.31 → 0.9.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbx-tools/auth",
-  "description": "Persistent Databricks authentication with CLI-owned user credentials, App auth, profile resolution, and portable storage adapters",
+  "description": "Databricks profile resolution and token or authentication-header production for Node.js and Bun",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reggie-db/dbx-tools.git",
@@ -19,14 +19,14 @@
     "projen": "projen"
   },
   "devDependencies": {
-    "@types/bun": "1.3.14",
     "@types/ini": "^4.1.1",
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@dbx-tools/core": "^0.9.31",
-    "@dbx-tools/shared-core": "^0.9.31",
+    "@dbx-tools/core": "^0.9.36",
+    "@dbx-tools/shared-auth": "^0.9.36",
+    "@dbx-tools/shared-core": "^0.9.36",
     "ini": "^6.0.0",
     "oauth4webapi": "^3.8.8"
   },
@@ -41,17 +41,46 @@
         "types": "./lib/index.d.ts",
         "default": "./lib/index.js"
       },
+      "./client": {
+        "types": "./lib/src/client.d.ts",
+        "default": "./lib/src/client.js"
+      },
+      "./config": {
+        "types": "./lib/src/config.d.ts",
+        "default": "./lib/src/config.js"
+      },
+      "./profile": {
+        "types": "./lib/src/profile.d.ts",
+        "default": "./lib/src/profile.js"
+      },
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.31",
+  "version": "0.9.36",
   "types": "./lib/index.d.ts",
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
   "type": "module",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./client": {
+      "types": "./lib/src/client.d.ts",
+      "default": "./lib/src/client.js"
+    },
+    "./config": {
+      "types": "./lib/src/config.d.ts",
+      "default": "./lib/src/config.js"
+    },
+    "./profile": {
+      "types": "./lib/src/profile.d.ts",
+      "default": "./lib/src/profile.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -59,10 +88,5 @@
     "src",
     "lib"
   ],
-  "dbxToolsConfig": {
-    "tags": [
-      "node"
-    ]
-  },
   "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
 }

package/src/{databricks-cli.ts → _databricks-cli.ts}

@@ -1,60 +1,34 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-import * as bin from "@dbx-tools/core/bin";
 import * as exec from "@dbx-tools/core/exec";
 import * as stringUtils from "@dbx-tools/shared-core/string-utils";
 
-import cliAssets from "./generated/databricks-cli-assets.json" with { type: "json" };
+import { AuthError } from "./_errors.ts";
 import { authLogger, failureMetadata, tokenMetadata } from "./_logging.ts";
-import { AuthError } from "./errors.ts";
-import type { Token, TokenProvider } from "./types.ts";
+import type { Token, TokenProvider } from "./_types.ts";
 
 const resolutionCache = new Map<string, Promise<string | undefined>>();
 const logger = authLogger("cli");
 
-interface DatabricksCliAsset {
-  readonly url: string;
-  readonly sha256: string;
-}
-
 /** Deferred Databricks CLI lookup used by U2M token acquisition. */
 export type DatabricksCliResolver = () => Promise<string | undefined>;
 
-/** Controls whether CLI resolution may install the pinned managed executable. */
-export interface DatabricksCliResolutionOptions {
-  install?: boolean;
-}
-
-/** Resolve a compatible Databricks CLI, installing the pinned build asset when needed. */
+/** Resolve an available Databricks CLI without installing executables. */
 export function resolveDatabricksCli(
   environment: Readonly<Record<string, string | undefined>> = process.env,
-  options: DatabricksCliResolutionOptions = {},
 ): Promise<string | undefined> {
   const candidate = stringValue(environment.DATABRICKS_CLI_PATH) ?? "databricks";
-  const key = `${candidate}\0${homedir()}\0${process.platform}\0${process.arch}\0${options.install !== false}`;
-  const cached = resolutionCache.get(key);
+  const cached = resolutionCache.get(candidate);
   if (cached) {
-    logger.debug("reused Databricks CLI resolution", {
-      candidate,
-      install: options.install !== false,
-    });
+    logger.debug("reused Databricks CLI resolution", { candidate });
     return cached;
   }
-  logger.debug("resolving Databricks CLI", {
-    candidate,
-    install: options.install !== false,
-    platform: process.platform,
-    arch: process.arch,
-    minimumVersion: cliAssets.minimumVersion,
-  });
-  const resolved = resolveDatabricksCliUncached(candidate, options.install !== false).catch(
-    (error) => {
-      resolutionCache.delete(key);
+  logger.debug("resolving Databricks CLI", { candidate });
+  const resolved = compatibleDatabricksCli(candidate)
+    .then((compatible) => (compatible ? candidate : undefined))
+    .catch((error) => {
+      resolutionCache.delete(candidate);
       throw error;
-    },
-  );
-  resolutionCache.set(key, resolved);
+    });
+  resolutionCache.set(candidate, resolved);
   return resolved;
 }
 
@@ -64,59 +38,6 @@ export function resetDatabricksCliResolution(): void {
   logger.debug("cleared Databricks CLI resolution cache");
 }
 
-async function resolveDatabricksCliUncached(
-  candidate: string,
-  install: boolean,
-): Promise<string | undefined> {
-  if (await compatibleDatabricksCli(candidate)) {
-    logger.debug("selected installed Databricks CLI", { executable: candidate });
-    return candidate;
-  }
-  const managed = managedExecutable();
-  if (await compatibleDatabricksCli(managed)) {
-    logger.debug("selected managed Databricks CLI", { executable: managed });
-    return managed;
-  }
-  if (!install) {
-    logger.debug("compatible Databricks CLI unavailable and installation disabled");
-    return undefined;
-  }
-  const asset = platformAsset();
-  if (!asset) {
-    logger.debug("no managed Databricks CLI asset for platform", {
-      platform: process.platform,
-      arch: process.arch,
-    });
-    return undefined;
-  }
-  const root = join(homedir(), ".databricks");
-  const binDir = join(root, "bin");
-  const executable = managedExecutableName();
-  const installed = await bin.ensure("databricks", asset, {
-    autoUnpackage: true,
-    destination: { root, binDir, path: join(binDir, executable) },
-    minVersion: cliAssets.minimumVersion,
-    selector: ({ source }) => join(source, executable),
-    versionParser: (output) => {
-      const version = bin.parseVersion(output);
-      return version === cliAssets.version ? version : undefined;
-    },
-  });
-  logger.debug("ensured managed Databricks CLI", {
-    executable: installed.path,
-    version: cliAssets.version,
-  });
-  return installed.path;
-}
-
-function managedExecutable(): string {
-  return join(homedir(), ".databricks", "bin", managedExecutableName());
-}
-
-function managedExecutableName(): string {
-  return process.platform === "win32" ? "databricks.exe" : "databricks";
-}
-
 async function compatibleDatabricksCli(executable: string): Promise<boolean> {
   try {
     const result = await runProcess(executable, ["--version"], {}, 10_000);
@@ -127,16 +48,8 @@ async function compatibleDatabricksCli(executable: string): Promise<boolean> {
       });
       return false;
     }
-    const version = bin.parseVersion(result);
-    const compatible =
-      version !== undefined && bin.isVersionAtLeast(version, cliAssets.minimumVersion);
-    logger.debug("probed Databricks CLI version", {
-      executable,
-      version: version ?? "unknown",
-      minimumVersion: cliAssets.minimumVersion,
-      compatible,
-    });
-    return compatible;
+    logger.debug("selected installed Databricks CLI", { executable });
+    return true;
   } catch (cause) {
     logger.debug("Databricks CLI version probe unavailable", {
       executable,
@@ -146,11 +59,6 @@ async function compatibleDatabricksCli(executable: string): Promise<boolean> {
   }
 }
 
-function platformAsset(): DatabricksCliAsset | undefined {
-  const key = `${process.platform}-${process.arch}` as keyof typeof cliAssets.assets;
-  return cliAssets.assets[key];
-}
-
 /** Run interactive Databricks CLI login for one profile. */
 export async function databricksCliLogin(
   profile: string,
@@ -164,8 +72,9 @@ export async function databricksCliLogin(
     ["auth", "login", "--profile", profile, "--timeout", `${Math.ceil(timeoutMs / 1000)}s`],
     environment,
   );
-  if (result.exitCode !== 0)
+  if (result.exitCode !== 0) {
     throw new AuthError("cli", result.stderr || `databricks auth login exited ${result.exitCode}`);
+  }
   logger.debug("Databricks CLI login completed", { profile, executable });
 }
 
@@ -180,8 +89,9 @@ export async function databricksCliToken(
   const args = ["auth", "token", "--profile", profile, "--output", "json"];
   if (forceRefresh) args.push("--force-refresh");
   const result = await runProcess(executable, args, environment);
-  if (result.exitCode !== 0)
+  if (result.exitCode !== 0) {
     throw new AuthError("cli", result.stderr || `databricks auth token exited ${result.exitCode}`);
+  }
   let value: Record<string, unknown>;
   try {
     value = JSON.parse(result.stdout ?? "") as Record<string, unknown>;
@@ -281,8 +191,9 @@ export class DatabricksCliProvider implements TokenProvider {
     logger.debug("resolving provider CLI lazily", { profile: this.profile });
     this.resolution = this.executableOrResolver()
       .then((executable) => {
-        if (!executable)
+        if (!executable) {
           throw new AuthError("cli", "Databricks CLI is unavailable on this platform");
+        }
         return executable;
       })
       .catch((error) => {

package/src/_errors.ts

@@ -0,0 +1,11 @@
+/** Authentication failure with a stable category for callers and language shims. */
+export class AuthError extends Error {
+  constructor(
+    readonly kind: "config" | "oauth" | "cli",
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "AuthError";
+  }
+}

package/src/{lifecycle.ts → _lifecycle.ts}

@@ -1,6 +1,8 @@
-import { AuthError } from "./errors.ts";
+import { AuthError } from "./_errors.ts";
 import { authLogger, credentialId, failureMetadata, tokenMetadata } from "./_logging.ts";
-import type { AccessToken, AuthOptions, CredentialStore, Token, TokenProvider } from "./types.ts";
+import type { CredentialStore, Token, TokenProvider } from "./_types.ts";
+import type { AccessToken } from "./client.ts";
+import type { AuthOptions } from "./config.ts";
 
 const logger = authLogger("lifecycle");
 
@@ -10,30 +12,22 @@ export class TokenLifecycle {
     private readonly key: string,
     private readonly provider: TokenProvider,
     private readonly store: CredentialStore,
-    private readonly options: AuthOptions,
+    private readonly options: Required<AuthOptions>,
     private readonly now: () => Date = () => new Date(),
   ) {
     logger.debug("created authentication lifecycle", {
       credential: credentialId(key),
-      storage: store.name(),
-      refreshBufferSeconds: options.refreshBufferSeconds,
-      lockTimeoutSeconds: options.lockTimeoutSeconds,
-      loginTimeoutSeconds: options.loginTimeoutSeconds,
+      refreshBufferMs: options.refreshBufferMs,
+      lockTimeoutMs: options.lockTimeoutMs,
+      loginTimeoutMs: options.loginTimeoutMs,
       silentProvider: provider.canAuthenticateSilently(),
     });
   }
 
-  storeName(): string {
-    return this.store.name();
-  }
-
   async login(): Promise<AccessToken> {
     logger.debug("interactive login requested", this.context());
     return this.withLock(async () => {
-      await this.store.prepareWrite();
-      const token = validateToken(
-        await this.provider.login(this.options.loginTimeoutSeconds * 1000),
-      );
+      const token = validateToken(await this.provider.login(this.options.loginTimeoutMs));
       await this.store.save(this.key, token);
       logger.debug("interactive login stored credential", {
         ...this.context(),
@@ -60,12 +54,7 @@ export class TokenLifecycle {
 
   forceRefresh(login = true): Promise<AccessToken> {
     logger.debug("forced refresh requested", { ...this.context(), login });
-    return this.refreshRejected(undefined, login);
-  }
-
-  refreshRejectedToken(staleAccessToken: string, login = true): Promise<AccessToken> {
-    logger.debug("rejected token refresh requested", { ...this.context(), login });
-    return this.refreshRejected(staleAccessToken, login);
+    return this.refresh(login);
   }
 
   async logout(): Promise<void> {
@@ -97,24 +86,9 @@ export class TokenLifecycle {
     });
   }
 
-  private async refreshRejected(
-    staleAccessToken: string | undefined,
-    login: boolean,
-  ): Promise<AccessToken> {
+  private async refresh(login: boolean): Promise<AccessToken> {
     return this.withLock(async () => {
       const current = await this.store.load(this.key);
-      if (
-        staleAccessToken &&
-        current?.accessToken &&
-        current.accessToken !== staleAccessToken &&
-        isValid(current, this.now())
-      ) {
-        logger.debug("reused replacement for rejected credential", {
-          ...this.context(),
-          token: tokenMetadata(current, this.now()),
-        });
-        return publicToken(current);
-      }
       return this.renew(current, login);
     });
   }
@@ -137,7 +111,7 @@ export class TokenLifecycle {
         });
         if (!login) throw error;
         logger.debug("falling back to interactive login", this.context());
-        token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+        token = await this.provider.login(this.options.loginTimeoutMs);
       }
     } else if (this.provider.canAuthenticateSilently()) {
       logger.debug("attempting silent credential acquisition", {
@@ -145,7 +119,7 @@ export class TokenLifecycle {
         loginFallback: login,
       });
       try {
-        token = await this.provider.authenticate(this.options.loginTimeoutSeconds * 1000);
+        token = await this.provider.authenticate(this.options.loginTimeoutMs);
       } catch (error) {
         logger.debug("silent credential acquisition failed", {
           ...this.context(),
@@ -154,11 +128,11 @@ export class TokenLifecycle {
         });
         if (!login) throw error;
         logger.debug("falling back to interactive login", this.context());
-        token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+        token = await this.provider.login(this.options.loginTimeoutMs);
       }
     } else if (login) {
       logger.debug("provider requires interactive login", this.context());
-      token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+      token = await this.provider.login(this.options.loginTimeoutMs);
     } else {
       throw new AuthError(
         "oauth",
@@ -170,7 +144,6 @@ export class TokenLifecycle {
       ...this.context(),
       token: tokenMetadata(token, this.now()),
     });
-    await this.store.prepareWrite();
     await this.store.save(this.key, token);
     logger.debug("credential saved", this.context());
     return publicToken(token);
@@ -179,14 +152,16 @@ export class TokenLifecycle {
   private canReuse(token: Token): boolean {
     if (!isValid(token, this.now())) return false;
     if (!token.expiry) return true;
-    return (
-      Date.parse(token.expiry) - this.now().getTime() > this.options.refreshBufferSeconds * 1000
-    );
+    return Date.parse(token.expiry) - this.now().getTime() > this.options.refreshBufferMs;
   }
 
   private async withLock<T>(action: () => Promise<T>): Promise<T> {
     logger.debug("waiting for credential lock", this.context());
-    const lease = await this.store.acquireLock(this.key, this.options.lockTimeoutSeconds * 1000);
+    // Omit the timeout (wait indefinitely) unless a positive cap is configured.
+    // The holder may run for minutes; the caller owns the overall request budget
+    // and the lock is always released when `action` settles (success or error).
+    const lockTimeoutMs = this.options.lockTimeoutMs > 0 ? this.options.lockTimeoutMs : undefined;
+    const lease = await this.store.acquireLock(this.key, lockTimeoutMs);
     logger.debug("credential lock acquired", this.context());
     let failure: unknown;
     try {
@@ -209,7 +184,7 @@ export class TokenLifecycle {
   }
 
   private context(): Record<string, unknown> {
-    return { credential: credentialId(this.key), storage: this.store.name() };
+    return { credential: credentialId(this.key) };
   }
 }
 
@@ -223,8 +198,9 @@ export function publicToken(token: Token): AccessToken {
 }
 
 export function validateToken(token: Token, previous?: Token): Token {
-  if (!token.accessToken.trim())
+  if (!token.accessToken.trim()) {
     throw new AuthError("oauth", "Token response did not contain an access token");
+  }
   return {
     accessToken: token.accessToken,
     tokenType: token.tokenType || "Bearer",

package/src/_logging.ts

@@ -1,8 +1,8 @@
 import * as hash from "@dbx-tools/shared-core/hash";
 import * as log from "@dbx-tools/shared-core/log";
 
-import { AuthError } from "./errors.ts";
-import type { Token } from "./types.ts";
+import { AuthError } from "./_errors.ts";
+import type { Token } from "./_types.ts";
 
 /** Auth logger with a stable capability-specific tag. */
 export function authLogger(scope: string): log.Logger {

package/src/{personal-access-token.ts → _personal-access-token.ts}

@@ -1,5 +1,5 @@
 import { authLogger } from "./_logging.ts";
-import type { Token, TokenProvider } from "./types.ts";
+import type { Token, TokenProvider } from "./_types.ts";
 
 const logger = authLogger("pat");