@databricks/sdk-auth 0.0.0-dev → 0.1.0-dev.2

package/src/credentials/u2m.ts

@@ -0,0 +1,212 @@
+/**
+ * Databricks CLI ("U2M") credentials. Obtains access tokens by shelling out
+ * to the `databricks` CLI binary (>= 0.100.0). The CLI must have been logged
+ * in ahead of time via `databricks auth login`.
+ *
+ * Node.js only. Not exported from the browser entry point.
+ */
+
+import {execFile} from 'node:child_process';
+import {stat} from 'node:fs/promises';
+import {join, sep} from 'node:path';
+import {env, platform} from 'node:process';
+import {promisify} from 'node:util';
+
+import {z} from 'zod';
+
+import type {Token, TokenCredentials} from '../auth';
+import {newTokenCredentials, tokenProviderFn} from '../auth';
+
+import {U2mCredentialsError} from './errors';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Distinguishes the modern Go-based Databricks CLI (>= 0.100.0) from the
+ * legacy Python CLI by minimum file size.
+ */
+const DATABRICKS_CLI_MIN_SIZE = 1024 * 1024;
+
+/** Options for the Databricks CLI auth strategy. */
+export interface U2mCredentialsOptions {
+  /**
+   * The Databricks CLI profile name, as configured via `databricks auth
+   * login`.
+   */
+  profile: string;
+
+  /**
+   * Path to the `databricks` CLI binary. If omitted, the binary is searched
+   * for in `PATH`.
+   */
+  cliPath?: string;
+}
+
+/**
+ * Creates a TokenCredentials that obtains Databricks access tokens by
+ * shelling out to the Databricks CLI.
+ *
+ * @param options - CLI profile (required) and optional CLI binary path.
+ * @throws U2mCredentialsError when `profile` is empty, or when the CLI cannot
+ * be located, is out of date, or fails to return a usable token.
+ */
+export function newU2mCredentials(
+  options: U2mCredentialsOptions
+): TokenCredentials {
+  if (options.profile === '') {
+    throw new U2mCredentialsError('PROFILE_REQUIRED', 'profile is required');
+  }
+  const provider = tokenProviderFn(() => fetchCliToken(options));
+  return newTokenCredentials('databricks-cli', provider);
+}
+
+async function fetchCliToken(options: U2mCredentialsOptions): Promise<Token> {
+  const cliPath = await findDatabricksCli(options.cliPath);
+  return execCliCommand([
+    cliPath,
+    'auth',
+    'token',
+    '--profile',
+    options.profile,
+  ]);
+}
+
+const cliTokenResponseSchema = z.object({
+  access_token: z.string().min(1),
+  token_type: z.string().optional(),
+  expiry: z.string(),
+});
+
+async function execCliCommand(args: string[]): Promise<Token> {
+  const [cliPath, ...rest] = args;
+
+  let stdout: string;
+  try {
+    const result = await execFileAsync(cliPath, rest);
+    stdout = result.stdout;
+  } catch (e) {
+    throw new U2mCredentialsError(
+      'TOKEN_FETCH_FAILED',
+      `cannot get access token: ${cliErrorMessage(e)}`
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout);
+  } catch (e) {
+    const cause = e instanceof Error ? e.message : String(e);
+    throw new U2mCredentialsError(
+      'INVALID_RESPONSE',
+      `cannot parse CLI response: ${cause}`
+    );
+  }
+
+  const result = cliTokenResponseSchema.safeParse(raw);
+  if (!result.success) {
+    throw new U2mCredentialsError(
+      'INVALID_RESPONSE',
+      `invalid CLI response: ${result.error.message}`
+    );
+  }
+  const parsed = result.data;
+
+  const expiry = new Date(parsed.expiry);
+  if (Number.isNaN(expiry.getTime())) {
+    throw new U2mCredentialsError(
+      'INVALID_RESPONSE',
+      `cannot parse token expiry: ${parsed.expiry}`
+    );
+  }
+
+  return {
+    value: parsed.access_token,
+    ...(parsed.token_type !== undefined && {type: parsed.token_type}),
+    expiry,
+  };
+}
+
+interface ExecFileError {
+  stderr?: string | Buffer;
+  message: string;
+}
+
+function cliErrorMessage(e: unknown): string {
+  if (typeof e === 'object' && e !== null) {
+    const err = e as ExecFileError;
+    if (err.stderr !== undefined) {
+      return err.stderr.toString().trim();
+    }
+    return err.message;
+  }
+  return String(e);
+}
+
+/**
+ * Locates the `databricks` CLI binary, either at `cliPath` (if provided) or
+ * by searching `PATH`. Validates that the binary is the modern Go CLI and
+ * not the legacy Python one, via a minimum-size check.
+ */
+async function findDatabricksCli(cliPath?: string): Promise<string> {
+  if (cliPath !== undefined) {
+    if (cliPath.includes(sep) || cliPath.includes('/')) {
+      return validateCliPath(cliPath);
+    }
+    return findInPath(cliPath);
+  }
+  try {
+    return await findInPath('databricks');
+  } catch (e) {
+    if (platform === 'win32') {
+      return findInPath('databricks.exe');
+    }
+    throw e;
+  }
+}
+
+async function findInPath(name: string): Promise<string> {
+  const pathEnv = env.PATH ?? '';
+  if (pathEnv === '') {
+    throw new U2mCredentialsError('CLI_NOT_FOUND', 'databricks CLI not found');
+  }
+  const delim = platform === 'win32' ? ';' : ':';
+  let legacyError: U2mCredentialsError | undefined;
+  for (const dir of pathEnv.split(delim)) {
+    if (dir === '') {
+      continue;
+    }
+    try {
+      return await validateCliPath(join(dir, name));
+    } catch (e) {
+      if (
+        e instanceof U2mCredentialsError &&
+        e.code === 'LEGACY_CLI_DETECTED'
+      ) {
+        legacyError = e;
+      }
+    }
+  }
+  throw (
+    legacyError ??
+    new U2mCredentialsError('CLI_NOT_FOUND', 'databricks CLI not found')
+  );
+}
+
+async function validateCliPath(path: string): Promise<string> {
+  let info;
+  try {
+    info = await stat(path);
+  } catch {
+    throw new U2mCredentialsError('CLI_NOT_FOUND', 'databricks CLI not found');
+  }
+  if (info.isDirectory()) {
+    throw new U2mCredentialsError('CLI_NOT_FOUND', 'databricks CLI not found');
+  }
+  if (info.size < DATABRICKS_CLI_MIN_SIZE) {
+    throw new U2mCredentialsError(
+      'LEGACY_CLI_DETECTED',
+      'legacy databricks CLI detected; upgrade to >= 0.100.0'
+    );
+  }
+  return path;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Databricks authentication library for JavaScript/TypeScript.
+ *
+ * @packageDocumentation
+ */
+
+import pkgJson from '../package.json' with {type: 'json'};
+
+export type {
+  Header,
+  Token,
+  Credentials,
+  TokenProvider,
+  TokenCredentials,
+} from './auth';
+export {newTokenCredentials, tokenProviderFn} from './auth';
+
+/** Version of this auth library, sourced from package.json. */
+export const VERSION: string = pkgJson.version;

package/src/oidc/env.ts

@@ -0,0 +1,21 @@
+import {env} from 'node:process';
+
+import type {IdTokenProvider} from './oidc';
+import {idTokenProviderFn} from './oidc';
+
+/**
+ * Returns an IdTokenProvider that reads the ID token from environment variable
+ * `name`.
+ *
+ * Note that the IdTokenProvider does not cache the token and will read the
+ * token from environment variable `name` each time.
+ */
+export function newEnvIdTokenProvider(name: string): IdTokenProvider {
+  return idTokenProviderFn(() => {
+    const t = env[name];
+    if (t === undefined || t === '') {
+      return Promise.reject(new Error(`missing env var "${name}"`));
+    }
+    return Promise.resolve({value: t});
+  });
+}

package/src/oidc/file.ts

@@ -0,0 +1,29 @@
+import {readFile} from 'node:fs/promises';
+
+import type {IdTokenProvider} from './oidc';
+import {idTokenProviderFn} from './oidc';
+
+/**
+ * Returns an IdTokenProvider that reads the ID token from a file. The file
+ * should contain a single line with the token.
+ */
+export function newFileTokenProvider(path: string): IdTokenProvider {
+  return idTokenProviderFn(async () => {
+    if (path === '') {
+      throw new Error('missing path');
+    }
+    let content: string;
+    try {
+      content = await readFile(path, 'utf-8');
+    } catch (e: unknown) {
+      if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+        throw new Error(`file "${path}" does not exist`);
+      }
+      throw e;
+    }
+    if (content.length === 0) {
+      throw new Error(`file "${path}" is empty`);
+    }
+    return {value: content};
+  });
+}

package/src/oidc/index.browser.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser entry point for OIDC ID token utilities and the Databricks OIDC
+ * token-exchange provider.
+ *
+ * This package is experimental and subject to change.
+ *
+ * @packageDocumentation
+ */
+
+export type {IdToken, IdTokenProvider} from './oidc';
+export {idTokenProviderFn} from './oidc';
+export type {
+  DatabricksOidcTokenProviderConfig,
+  OAuthAuthorizationServer,
+} from './tokensource';
+export {newDatabricksOidcTokenProvider} from './tokensource';

package/src/oidc/index.ts

@@ -0,0 +1,17 @@
+/**
+ * OIDC ID token utilities and Databricks OIDC token-exchange provider.
+ *
+ * This package is experimental and subject to change.
+ *
+ * @packageDocumentation
+ */
+
+export type {IdToken, IdTokenProvider} from './oidc';
+export {idTokenProviderFn} from './oidc';
+export {newEnvIdTokenProvider} from './env';
+export {newFileTokenProvider} from './file';
+export type {
+  DatabricksOidcTokenProviderConfig,
+  OAuthAuthorizationServer,
+} from './tokensource';
+export {newDatabricksOidcTokenProvider} from './tokensource';

package/src/oidc/oidc.ts

@@ -0,0 +1,26 @@
+/**
+ * IdToken represents an OIDC ID token that can be exchanged for a Databricks
+ * access token.
+ */
+export interface IdToken {
+  value: string;
+}
+
+/**
+ * IdTokenProvider is anything that returns an IdToken given an audience.
+ */
+export interface IdTokenProvider {
+  idToken(audience: string): Promise<IdToken>;
+}
+
+/**
+ * Adapter to allow the use of ordinary functions as IdTokenProvider.
+ *
+ * @example
+ * const provider = idTokenProviderFn(async () => ({ value: 'my-id-token' }));
+ */
+export function idTokenProviderFn(
+  fn: (audience: string) => Promise<IdToken>
+): IdTokenProvider {
+  return {idToken: fn};
+}

package/src/oidc/tokensource.ts

@@ -0,0 +1,133 @@
+/**
+ * Databricks OIDC token-exchange provider. Exchanges an OIDC ID token for a
+ * Databricks access token using the OAuth 2.0 token-exchange grant.
+ */
+
+import {z} from 'zod';
+
+import type {Token, TokenProvider} from '../auth';
+import {tokenProviderFn} from '../auth';
+
+import type {IdTokenProvider} from './oidc';
+
+/**
+ * OAuthAuthorizationServer describes the OAuth endpoints used to mint
+ * Databricks access tokens.
+ */
+export interface OAuthAuthorizationServer {
+  tokenEndpoint: string;
+}
+
+/**
+ * DatabricksOidcTokenProviderConfig is the configuration for a Databricks OIDC
+ * TokenProvider.
+ */
+export interface DatabricksOidcTokenProviderConfig {
+  /**
+   * Client ID of the Databricks OIDC application. It corresponds to the
+   * Application ID of the Databricks Service Principal.
+   *
+   * This field is only required for Workload Identity Federation and should
+   * be empty for Account-wide token federation.
+   */
+  clientId?: string;
+
+  /**
+   * Account ID of the Databricks Account. This field is only required for
+   * Account-wide token federation.
+   */
+  accountId?: string;
+
+  /**
+   * Host is the host of the Databricks account or workspace.
+   */
+  host: string;
+
+  /**
+   * TokenEndpointProvider returns the token endpoint for the Databricks OIDC
+   * application.
+   */
+  tokenEndpointProvider: () => Promise<OAuthAuthorizationServer>;
+
+  /**
+   * Audience is the audience of the Databricks OIDC application.
+   * This is only used for Workspace level tokens.
+   */
+  audience?: string;
+
+  /**
+   * IdTokenProvider returns the ID token to be used for the token exchange.
+   */
+  idTokenProvider: IdTokenProvider;
+}
+
+/**
+ * Returns a new Databricks OIDC TokenProvider that exchanges an OIDC ID token
+ * for a Databricks access token using the OAuth 2.0 token-exchange grant.
+ */
+export function newDatabricksOidcTokenProvider(
+  config: DatabricksOidcTokenProviderConfig
+): TokenProvider {
+  return tokenProviderFn(() => exchangeIdToken(config));
+}
+
+async function exchangeIdToken(
+  config: DatabricksOidcTokenProviderConfig
+): Promise<Token> {
+  if (config.host === '') {
+    throw new Error('missing Host');
+  }
+  const endpoints = await config.tokenEndpointProvider();
+  const audience = determineAudience(config, endpoints);
+  const idToken = await config.idTokenProvider.idToken(audience);
+
+  const params = new URLSearchParams();
+  if (config.clientId !== undefined && config.clientId !== '') {
+    params.set('client_id', config.clientId);
+  }
+  params.set('scope', 'all-apis');
+  params.set('subject_token_type', 'urn:ietf:params:oauth:token-type:jwt');
+  params.set('subject_token', idToken.value);
+  params.set('grant_type', 'urn:ietf:params:oauth:grant-type:token-exchange');
+
+  const response = await fetch(endpoints.tokenEndpoint, {
+    method: 'POST',
+    headers: {'Content-Type': 'application/x-www-form-urlencoded'},
+    body: params.toString(),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(
+      `token request failed with status ${response.status.toString()}: ${text}`
+    );
+  }
+  const parsed = tokenResponseSchema.parse(await response.json());
+  const expiry =
+    parsed.expires_in !== undefined
+      ? new Date(Date.now() + parsed.expires_in * 1000)
+      : undefined;
+  return {
+    value: parsed.access_token,
+    ...(parsed.token_type !== undefined && {type: parsed.token_type}),
+    ...(expiry !== undefined && {expiry}),
+  };
+}
+
+function determineAudience(
+  config: DatabricksOidcTokenProviderConfig,
+  endpoints: OAuthAuthorizationServer
+): string {
+  if (config.audience !== undefined && config.audience !== '') {
+    return config.audience;
+  }
+  if (config.accountId !== undefined && config.accountId !== '') {
+    return config.accountId;
+  }
+  return endpoints.tokenEndpoint;
+}
+
+const tokenResponseSchema = z.object({
+  access_token: z.string(),
+  token_type: z.string().optional(),
+  expires_in: z.number().optional(),
+});

package/index.js

@@ -1 +0,0 @@
-module.exports = {};