@dbx-tools/auth 0.6.182 → 0.9.28

package/src/databricks-cli.ts

@@ -0,0 +1,298 @@
+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 { authLogger, failureMetadata, tokenMetadata } from "./_logging.ts";
+import { AuthError } from "./errors.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. */
+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);
+  if (cached) {
+    logger.debug("reused Databricks CLI resolution", {
+      candidate,
+      install: options.install !== false,
+    });
+    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);
+      throw error;
+    },
+  );
+  resolutionCache.set(key, resolved);
+  return resolved;
+}
+
+/** Clear cached CLI resolution, primarily after installation or environment changes. */
+export function resetDatabricksCliResolution(): void {
+  resolutionCache.clear();
+  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);
+    if (result.exitCode !== 0) {
+      logger.debug("Databricks CLI version probe failed", {
+        executable,
+        exitCode: result.exitCode,
+      });
+      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;
+  } catch (cause) {
+    logger.debug("Databricks CLI version probe unavailable", {
+      executable,
+      error: failureMetadata(cause),
+    });
+    return false;
+  }
+}
+
+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,
+  timeoutMs: number,
+  executable = process.env.DATABRICKS_CLI_PATH ?? "databricks",
+  environment: Record<string, string> = {},
+): Promise<void> {
+  logger.debug("starting Databricks CLI login", { profile, executable, timeoutMs });
+  const result = await runProcess(
+    executable,
+    ["auth", "login", "--profile", profile, "--timeout", `${Math.ceil(timeoutMs / 1000)}s`],
+    environment,
+  );
+  if (result.exitCode !== 0)
+    throw new AuthError("cli", result.stderr || `databricks auth login exited ${result.exitCode}`);
+  logger.debug("Databricks CLI login completed", { profile, executable });
+}
+
+/** Request one profile token from the Databricks CLI. */
+export async function databricksCliToken(
+  profile: string,
+  forceRefresh = false,
+  executable = process.env.DATABRICKS_CLI_PATH ?? "databricks",
+  environment: Record<string, string> = {},
+): Promise<Token> {
+  logger.debug("requesting Databricks CLI token", { profile, executable, forceRefresh });
+  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)
+    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>;
+  } catch (cause) {
+    throw new AuthError("cli", "Databricks CLI token output was not JSON", { cause });
+  }
+  const accessToken = stringValue(value.access_token ?? value.accessToken);
+  if (!accessToken) throw new AuthError("cli", "Databricks CLI token output had no access token");
+  const token = {
+    accessToken,
+    tokenType: stringValue(value.token_type ?? value.tokenType) ?? "Bearer",
+    ...(stringValue(value.refresh_token ?? value.refreshToken)
+      ? { refreshToken: stringValue(value.refresh_token ?? value.refreshToken) }
+      : {}),
+    ...(stringValue(value.expiry ?? value.expires_at)
+      ? { expiry: stringValue(value.expiry ?? value.expires_at) }
+      : {}),
+    scopes: Array.isArray(value.scopes)
+      ? value.scopes.filter((scope): scope is string => typeof scope === "string")
+      : [],
+  };
+  logger.debug("received Databricks CLI token", {
+    profile,
+    forceRefresh,
+    token: tokenMetadata(token),
+  });
+  return token;
+}
+
+async function runProcess(
+  command: string,
+  args: string[],
+  environment: Record<string, string>,
+  timeoutMs?: number,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const controller = timeoutMs === undefined ? undefined : new AbortController();
+  const timeout = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+  try {
+    return await exec.spawn(command, args, {
+      env: { ...process.env, ...environment },
+      stdin: "ignore",
+      stdout: "capture",
+      stderr: "capture",
+      signal: controller?.signal,
+    });
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+/** Provider that lazily delegates U2M credentials to the Databricks CLI. */
+export class DatabricksCliProvider implements TokenProvider {
+  private resolution?: Promise<string>;
+
+  constructor(
+    private readonly profile: string,
+    private readonly executableOrResolver: string | DatabricksCliResolver = () =>
+      resolveDatabricksCli(),
+    private readonly environment: Record<string, string> = {},
+  ) {}
+
+  async authenticate(_timeoutMs: number): Promise<Token> {
+    return databricksCliToken(
+      this.profile,
+      false,
+      await this.resolveExecutable(),
+      this.environment,
+    );
+  }
+
+  async login(timeoutMs: number): Promise<Token> {
+    const executable = await this.resolveExecutable();
+    await databricksCliLogin(this.profile, timeoutMs, executable, this.environment);
+    return databricksCliToken(this.profile, false, executable, this.environment);
+  }
+
+  async refresh(_token: Token): Promise<Token> {
+    return databricksCliToken(this.profile, true, await this.resolveExecutable(), this.environment);
+  }
+
+  canAuthenticateSilently(): boolean {
+    return true;
+  }
+
+  private resolveExecutable(): Promise<string> {
+    if (typeof this.executableOrResolver === "string") {
+      logger.debug("using configured Databricks CLI executable", {
+        profile: this.profile,
+        executable: this.executableOrResolver,
+      });
+      return Promise.resolve(this.executableOrResolver);
+    }
+    if (this.resolution) {
+      logger.debug("reused provider CLI resolution", { profile: this.profile });
+      return this.resolution;
+    }
+    logger.debug("resolving provider CLI lazily", { profile: this.profile });
+    this.resolution = this.executableOrResolver()
+      .then((executable) => {
+        if (!executable)
+          throw new AuthError("cli", "Databricks CLI is unavailable on this platform");
+        return executable;
+      })
+      .catch((error) => {
+        this.resolution = undefined;
+        throw error;
+      });
+    return this.resolution;
+  }
+}
+
+function stringValue(value: unknown): string | undefined {
+  return stringUtils.trimToNull(value) ?? undefined;
+}

package/src/errors.ts

@@ -0,0 +1,16 @@
+/** Authentication failure with a stable category for callers and language shims. */
+export class AuthError extends Error {
+  constructor(
+    readonly kind: "config" | "oauth" | "storage" | "lock-timeout" | "cli" | "http",
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "AuthError";
+  }
+}
+
+/** Normalize arbitrary failures without erasing their original cause. */
+export function authError(kind: AuthError["kind"], message: string, cause?: unknown): AuthError {
+  return cause instanceof AuthError ? cause : new AuthError(kind, message, { cause });
+}

package/src/generated/databricks-cli-assets.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "dbxToolsVersion": "0.9.21",
+  "minimumVersion": "0.296.0",
+  "version": "1.19.0",
+  "publishedAt": "2026-09-30T13:13:22Z",
+  "assets": {
+    "darwin-arm64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_darwin_arm64.tar.gz",
+      "sha256": "b84c6a8c623578308a724cdd7181b92b0816c2531564f16f8de7559b2a39f51f"
+    },
+    "darwin-x64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_darwin_amd64.tar.gz",
+      "sha256": "d29a5dc1ea7d44d0d892fd4beac05d22daa932982ca6bf98a06d52c95f5ed4cd"
+    },
+    "linux-arm64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_linux_arm64.tar.gz",
+      "sha256": "2997ccbda57090ee48bd9282d5cb3a5bef78025db64fd1573fbd7c8726856086"
+    },
+    "linux-x64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_linux_amd64.tar.gz",
+      "sha256": "bddf87df3d72b61384da724b40f18ab483a98af742748260097a7bb8154b070e"
+    },
+    "win32-arm64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_windows_arm64.tar.gz",
+      "sha256": "c28d098490ea1966230c07585312f8bc66e18d468e34b06319d44e29d61c4602"
+    },
+    "win32-x64": {
+      "url": "https://github.com/databricks/cli/releases/download/v1.19.0/databricks_cli_1.19.0_windows_amd64.tar.gz",
+      "sha256": "0ded24a2b001e001c815b9c1c66dc2ef1f6c2e60c64f63c6d9afb8e9fe85afdb"
+    }
+  }
+}

package/src/http-client.ts

@@ -0,0 +1,147 @@
+import { authLogger } from "./_logging.ts";
+import { AuthError } from "./errors.ts";
+import { createAuthClient, type DatabricksAuthDependencies } from "./databricks-auth.ts";
+import type { AuthClient, DatabricksAuthOptions } from "./types.ts";
+import { DEFAULT_ACCESS_TOKEN_HEADER, WORKSPACE_ID_HEADER } from "./types.ts";
+
+const logger = authLogger("http");
+
+/** Options for one Databricks JSON API request. */
+export interface DatabricksRequestOptions {
+  method?: string;
+  body?: unknown;
+  headers?: Headers | Record<string, string> | [string, string][];
+  login?: boolean;
+  signal?: AbortSignal;
+}
+
+/** Dependency-light Databricks JSON client with one rejected-token refresh. */
+export class DatabricksClient {
+  private constructor(
+    readonly auth: AuthClient,
+    private readonly fetcher: typeof globalThis.fetch,
+  ) {}
+
+  static async create(
+    options: DatabricksAuthOptions = { preferUserToMachine: true },
+    dependencies: DatabricksAuthDependencies = {},
+  ): Promise<DatabricksClient> {
+    const client = new DatabricksClient(
+      await createAuthClient(options, undefined, dependencies),
+      dependencies.fetch ?? globalThis.fetch,
+    );
+    logger.debug("created Databricks HTTP client", {
+      profile: client.profile(),
+      host: client.host(),
+      hasWorkspaceId: Boolean(client.workspaceId()),
+    });
+    return client;
+  }
+
+  profile(): string {
+    return this.auth.status().profile;
+  }
+
+  host(): string {
+    return this.auth.status().host;
+  }
+
+  principal(): string {
+    return this.auth.principal();
+  }
+
+  workspaceId(): string | undefined {
+    return this.auth.workspaceId();
+  }
+
+  async request(path: string, options: DatabricksRequestOptions = {}): Promise<unknown> {
+    const url = new URL(path, `${this.host().replace(/\/$/, "")}/`).toString();
+    const method = options.method ?? (options.body === undefined ? "GET" : "POST");
+    const requestUrl = new URL(url);
+    logger.debug("sending Databricks API request", {
+      method,
+      origin: requestUrl.origin,
+      path: requestUrl.pathname,
+      hasBody: options.body !== undefined,
+      login: options.login ?? "auto",
+    });
+    let authHeaders = await this.auth.authenticate(options.login);
+    let response = await this.send(url, method, authHeaders, options);
+    logger.debug("received Databricks API response", {
+      method,
+      path: requestUrl.pathname,
+      status: response.status,
+      attempt: 1,
+    });
+    if (response.status === 401) {
+      logger.debug("refreshing rejected Databricks API credential", {
+        method,
+        path: requestUrl.pathname,
+      });
+      await this.auth.refreshRejectedToken(
+        accessTokenFromHeaders(authHeaders),
+        options.login ?? true,
+      );
+      authHeaders = await this.auth.authenticate(false);
+      response = await this.send(url, method, authHeaders, options);
+      logger.debug("received Databricks API response", {
+        method,
+        path: requestUrl.pathname,
+        status: response.status,
+        attempt: 2,
+      });
+    }
+    const text = await response.text();
+    if (!response.ok)
+      throw new AuthError(
+        "http",
+        `Databricks API ${path} returned HTTP ${response.status}: ${text}`,
+      );
+    if (!text) {
+      logger.debug("Databricks API response had no body", {
+        method,
+        path: requestUrl.pathname,
+      });
+      return undefined;
+    }
+    try {
+      const value = JSON.parse(text);
+      logger.debug("parsed Databricks API JSON response", {
+        method,
+        path: requestUrl.pathname,
+      });
+      return value;
+    } catch (cause) {
+      throw new AuthError("http", `Databricks API ${path} did not return JSON`, { cause });
+    }
+  }
+
+  private send(
+    url: string,
+    method: string,
+    authHeaders: Record<string, string>,
+    options: DatabricksRequestOptions,
+  ): Promise<Response> {
+    const headers = new Headers(options.headers);
+    headers.delete(DEFAULT_ACCESS_TOKEN_HEADER);
+    headers.delete(WORKSPACE_ID_HEADER);
+    for (const [name, value] of Object.entries(authHeaders)) headers.set(name, value);
+    headers.set("accept", "application/json");
+    if (options.body !== undefined) headers.set("content-type", "application/json");
+    return this.fetcher(url, {
+      method,
+      headers,
+      ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+      signal: options.signal,
+    });
+  }
+}
+
+function accessTokenFromHeaders(headers: Record<string, string>): string {
+  const authorization = headers[DEFAULT_ACCESS_TOKEN_HEADER];
+  const separator = authorization?.indexOf(" ") ?? -1;
+  if (separator < 1 || !authorization?.slice(separator + 1).trim()) {
+    throw new AuthError("http", "Authentication headers did not contain an access token");
+  }
+  return authorization.slice(separator + 1).trim();
+}