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

package/src/credentials/default/default-credentials.ts

@@ -0,0 +1,40 @@
+import type {Profile} from '@databricks/sdk-core/profiles';
+import {resolve} from '@databricks/sdk-core/profiles';
+
+import type {Credentials} from '../../auth';
+
+import {DefaultCredentials, m2mStrategy, patStrategy} from './chain';
+import type {Strategy} from './chain';
+import {u2mStrategy} from './u2m-strategy';
+
+const STRATEGIES: readonly Strategy[] = [patStrategy, m2mStrategy, u2mStrategy];
+
+interface DefaultCredentialsOptions {
+  /**
+   * Pre-resolved profile. When omitted, the profile is resolved on first
+   * use from the default config file and environment variables.
+   */
+  profile?: Profile;
+}
+
+/**
+ * Returns a lazy {@link Credentials} that resolves to the first configured
+ * authentication strategy on first use.
+ *
+ * Strategies are tried in this order:
+ *   1. PAT (`pat`).
+ *   2. OAuth M2M (`oauth-m2m`).
+ *   3. Databricks CLI (`databricks-cli`).
+ *
+ * When no profile is provided via `options.profile`, the profile is
+ * resolved on first use from the default config file (~/.databrickscfg)
+ * and environment variables.
+ */
+export function defaultCredentials(
+  options?: DefaultCredentialsOptions
+): Credentials {
+  const explicit = options?.profile;
+  const loadProfile = (): Promise<Profile> =>
+    explicit !== undefined ? Promise.resolve(explicit) : resolve();
+  return new DefaultCredentials(STRATEGIES, loadProfile);
+}

package/src/credentials/default/errors.ts

@@ -0,0 +1,18 @@
+/** Discriminant codes for {@link DefaultCredentialsError}. */
+export type DefaultCredentialsErrorCode = 'NO_AUTH_CONFIGURED';
+
+/**
+ * Error thrown when the default credentials chain cannot resolve a
+ * strategy to authenticate with.
+ *
+ * Use the `code` field to distinguish between error causes.
+ */
+export class DefaultCredentialsError extends Error {
+  readonly code: DefaultCredentialsErrorCode;
+
+  constructor(code: DefaultCredentialsErrorCode, message: string) {
+    super(message);
+    this.name = 'DefaultCredentialsError';
+    this.code = code;
+  }
+}

package/src/credentials/default/u2m-strategy.ts

@@ -0,0 +1,20 @@
+import {newU2mCredentials} from '../u2m';
+
+import type {Strategy} from './chain';
+
+/**
+ * U2M (Databricks CLI) strategy. Configured when the profile was loaded
+ * from the config file (so the section name is known) and a host is set.
+ * The CLI must have been logged in ahead of time via `databricks auth
+ * login`.
+ */
+export const u2mStrategy: Strategy = profile => {
+  if (profile.host === undefined) return undefined;
+  if (profile.name === undefined) return undefined;
+  return newU2mCredentials({
+    profile: profile.name,
+    ...(profile.databricksCliPath !== undefined && {
+      cliPath: profile.databricksCliPath,
+    }),
+  });
+};

package/src/credentials/errors.ts

@@ -0,0 +1,51 @@
+/**
+ * Error types for credential operations.
+ *
+ * @module
+ */
+
+/** Discriminant codes for {@link M2mCredentialsError}. */
+export type M2mCredentialsErrorCode =
+  | 'CLIENT_ID_REQUIRED'
+  | 'CLIENT_SECRET_REQUIRED'
+  | 'HOST_REQUIRED'
+  | 'DISCOVERY_FAILED'
+  | 'TOKEN_REQUEST_FAILED';
+
+/**
+ * Error thrown by M2M credential operations.
+ *
+ * Use the `code` field to distinguish between error causes.
+ */
+export class M2mCredentialsError extends Error {
+  readonly code: M2mCredentialsErrorCode;
+
+  constructor(code: M2mCredentialsErrorCode, message: string) {
+    super(message);
+    this.name = 'M2mCredentialsError';
+    this.code = code;
+  }
+}
+
+/** Discriminant codes for {@link U2mCredentialsError}. */
+export type U2mCredentialsErrorCode =
+  | 'PROFILE_REQUIRED'
+  | 'CLI_NOT_FOUND'
+  | 'LEGACY_CLI_DETECTED'
+  | 'TOKEN_FETCH_FAILED'
+  | 'INVALID_RESPONSE';
+
+/**
+ * Error thrown by U2M (databricks-cli) credential operations.
+ *
+ * Use the `code` field to distinguish between error causes.
+ */
+export class U2mCredentialsError extends Error {
+  readonly code: U2mCredentialsErrorCode;
+
+  constructor(code: U2mCredentialsErrorCode, message: string) {
+    super(message);
+    this.name = 'U2mCredentialsError';
+    this.code = code;
+  }
+}

package/src/credentials/host-metadata.ts

@@ -0,0 +1,166 @@
+import {z} from 'zod';
+
+/**
+ * HostMetadata holds the parsed response from the
+ * /.well-known/databricks-config discovery endpoint.
+ */
+export interface HostMetadata {
+  /**
+   * oidcEndpoint is the OIDC discovery URL for this host. For account hosts,
+   * this may contain an {account_id} placeholder that callers must
+   * substitute.
+   */
+  oidcEndpoint: string;
+
+  /**
+   * accountId is the Databricks account ID associated with this host, if
+   * available.
+   */
+  accountId?: string;
+
+  /**
+   * workspaceId is the Databricks workspace ID associated with this host, if
+   * available.
+   */
+  workspaceId?: string;
+}
+
+/**
+ * getHostMetadata fetches the raw Databricks well-known configuration from
+ * {host}/.well-known/databricks-config. The returned HostMetadata contains
+ * raw values with no substitution (e.g., {account_id} placeholders are left
+ * as-is). Callers are responsible for interpreting the result.
+ */
+export async function getHostMetadata(host: string): Promise<HostMetadata> {
+  const url = `${trimTrailingSlash(host)}/.well-known/databricks-config`;
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (e) {
+    throw new Error(
+      `fetching host metadata from ${url} failed: ${stringifyError(e)}`
+    );
+  }
+  if (!response.ok) {
+    const text = await safeReadText(response);
+    throw new Error(
+      `fetching host metadata from ${url} failed with status ` +
+        `${response.status.toString()}: ${text}`
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = await response.json();
+  } catch (e) {
+    throw new Error(
+      `parsing host metadata from ${url} failed: ${stringifyError(e)}`
+    );
+  }
+  const parsed = hostMetadataSchema.parse(raw);
+  return {
+    oidcEndpoint: parsed.oidc_endpoint,
+    ...(parsed.account_id !== undefined && {accountId: parsed.account_id}),
+    ...(parsed.workspace_id !== undefined && {
+      workspaceId: parsed.workspace_id,
+    }),
+  };
+}
+
+/**
+ * resolveTokenEndpoint resolves the OAuth `token_endpoint` for the given
+ * Databricks host via a two-step discovery:
+ *
+ * 1. `GET {host}/.well-known/databricks-config` to obtain the OIDC root.
+ * 2. `GET {oidcRoot}/.well-known/oauth-authorization-server` to obtain the
+ *    RFC 8414 authorization server metadata.
+ *
+ * If the OIDC root contains an `{account_id}` placeholder, it is substituted
+ * with the first defined value from: `configAccountId` (caller-supplied),
+ * then the `account_id` field returned by the host metadata response.
+ * Throws when any step fails, required fields are missing, or the placeholder
+ * cannot be resolved.
+ */
+export async function resolveTokenEndpoint(
+  host: string,
+  configAccountId?: string
+): Promise<string> {
+  const meta = await getHostMetadata(host);
+  // Precedence mirrors the legacy SDK: a caller-supplied account ID
+  // overrides any value returned by the host metadata. The metadata
+  // back-fills only when the caller did not provide one.
+  const accountId =
+    configAccountId !== undefined && configAccountId !== ''
+      ? configAccountId
+      : meta.accountId;
+  let oidcRoot = meta.oidcEndpoint;
+  if (oidcRoot.includes('{account_id}')) {
+    if (accountId === undefined || accountId === '') {
+      throw new Error(
+        'host metadata oidc_endpoint contains {account_id} placeholder but ' +
+          'no account_id was provided or returned by the metadata response'
+      );
+    }
+    oidcRoot = oidcRoot.replaceAll('{account_id}', accountId);
+  }
+  const discoveryUrl = `${trimTrailingSlash(oidcRoot)}/.well-known/oauth-authorization-server`;
+  let response: Response;
+  try {
+    response = await fetch(discoveryUrl);
+  } catch (e) {
+    throw new Error(
+      `fetching oauth authorization server metadata from ${discoveryUrl} ` +
+        `failed: ${stringifyError(e)}`
+    );
+  }
+  if (!response.ok) {
+    const text = await safeReadText(response);
+    throw new Error(
+      `fetching oauth authorization server metadata from ${discoveryUrl} ` +
+        `failed with status ${response.status.toString()}: ${text}`
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = await response.json();
+  } catch (e) {
+    throw new Error(
+      `parsing oauth authorization server metadata from ${discoveryUrl} ` +
+        `failed: ${stringifyError(e)}`
+    );
+  }
+  const parsed = oauthServerSchema.parse(raw);
+  return parsed.token_endpoint;
+}
+
+const hostMetadataSchema = z.object({
+  oidc_endpoint: z.string(),
+  account_id: z.string().optional(),
+  workspace_id: z.string().optional(),
+});
+
+const oauthServerSchema = z.object({
+  token_endpoint: z.string(),
+});
+
+function trimTrailingSlash(s: string): string {
+  let end = s.length;
+  while (end > 0 && s.charAt(end - 1) === '/') {
+    end--;
+  }
+  return s.slice(0, end);
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '';
+  }
+}
+
+function stringifyError(e: unknown): string {
+  if (e instanceof Error) {
+    return e.message;
+  }
+  return String(e);
+}

package/src/credentials/index.browser.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser entry point for credential implementations. Excludes credentials
+ * that depend on Node.js-only APIs (e.g. `databricks-cli` auth which spawns
+ * the CLI binary).
+ */
+
+export {M2mCredentialsError} from './errors';
+export type {M2mCredentialsErrorCode} from './errors';
+export {newM2mCredentials} from './m2m';
+export type {M2mCredentialsOptions} from './m2m';
+export {newPatCredentials} from './pat';

package/src/credentials/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Credential implementations for the Databricks SDK.
+ */
+
+export {M2mCredentialsError, U2mCredentialsError} from './errors';
+export type {M2mCredentialsErrorCode, U2mCredentialsErrorCode} from './errors';
+export {newM2mCredentials} from './m2m';
+export type {M2mCredentialsOptions} from './m2m';
+export {newPatCredentials} from './pat';
+export {newU2mCredentials} from './u2m';
+export type {U2mCredentialsOptions} from './u2m';
+export {defaultCredentials} from './default/default-credentials';
+export {DefaultCredentialsError} from './default/errors';
+export type {DefaultCredentialsErrorCode} from './default/errors';

package/src/credentials/m2m.ts

@@ -0,0 +1,156 @@
+/**
+ * Machine-to-machine (M2M) OAuth credentials for the Databricks SDK.
+ */
+
+import {z} from 'zod';
+
+import type {Token, TokenCredentials} from '../auth';
+import {newTokenCredentials, tokenProviderFn} from '../auth';
+
+import {M2mCredentialsError} from './errors';
+import {resolveTokenEndpoint} from './host-metadata';
+
+/** Options for {@link newM2mCredentials}. */
+export interface M2mCredentialsOptions {
+  /**
+   * Databricks host (workspace or account) used to discover the OAuth token
+   * endpoint.
+   */
+  host: string;
+
+  /**
+   * OAuth client ID issued to the service principal.
+   */
+  clientId: string;
+
+  /**
+   * OAuth client secret issued to the service principal.
+   */
+  clientSecret: string;
+
+  /**
+   * Databricks account ID. Required for account hosts.
+   */
+  accountId?: string;
+
+  /**
+   * OAuth scopes to request. When omitted or empty, defaults to
+   * `['all-apis']`.
+   */
+  scopes?: string[];
+}
+
+const DEFAULT_SCOPES: readonly string[] = ['all-apis'];
+
+/**
+ * Creates a TokenCredentials that authenticates as a Databricks service
+ * principal using the OAuth client credentials grant.
+ *
+ * @param options - Host plus client credentials.
+ * @throws M2mCredentialsError when host, clientId, or clientSecret is empty,
+ * when token-endpoint discovery fails, or when the token endpoint returns
+ * an error.
+ */
+export function newM2mCredentials(
+  options: M2mCredentialsOptions
+): TokenCredentials {
+  if (options.clientId === '') {
+    throw new M2mCredentialsError('CLIENT_ID_REQUIRED', 'clientId is required');
+  }
+  if (options.clientSecret === '') {
+    throw new M2mCredentialsError(
+      'CLIENT_SECRET_REQUIRED',
+      'clientSecret is required'
+    );
+  }
+  if (options.host === '') {
+    throw new M2mCredentialsError('HOST_REQUIRED', 'host is required');
+  }
+
+  const scopes =
+    options.scopes !== undefined && options.scopes.length > 0
+      ? options.scopes
+      : DEFAULT_SCOPES;
+
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    scope: scopes.join(' '),
+  }).toString();
+
+  // Client ID and secret are URL-encoded before Basic auth encoding to
+  // avoid ambiguity with special characters in either value, matching the
+  // behavior of golang.org/x/oauth2.
+  const basicAuth = btoa(
+    `${encodeURIComponent(options.clientId)}:${encodeURIComponent(options.clientSecret)}`
+  );
+
+  let cachedTokenEndpoint: string | undefined;
+  const getTokenEndpoint = async (): Promise<string> => {
+    if (cachedTokenEndpoint === undefined) {
+      try {
+        cachedTokenEndpoint = await resolveTokenEndpoint(
+          options.host,
+          options.accountId
+        );
+      } catch (e) {
+        throw new M2mCredentialsError(
+          'DISCOVERY_FAILED',
+          `discovering token endpoint failed: ${stringifyError(e)}`
+        );
+      }
+    }
+    return cachedTokenEndpoint;
+  };
+
+  const provider = tokenProviderFn(async () => {
+    const tokenEndpoint = await getTokenEndpoint();
+    return fetchAccessToken(tokenEndpoint, basicAuth, body);
+  });
+
+  return newTokenCredentials('oauth-m2m', provider);
+}
+
+async function fetchAccessToken(
+  tokenEndpoint: string,
+  basicAuth: string,
+  body: string
+): Promise<Token> {
+  const response = await fetch(tokenEndpoint, {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${basicAuth}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body,
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new M2mCredentialsError(
+      'TOKEN_REQUEST_FAILED',
+      `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}),
+  };
+}
+
+const tokenResponseSchema = z.object({
+  access_token: z.string(),
+  token_type: z.string().optional(),
+  expires_in: z.number().optional(),
+});
+
+function stringifyError(e: unknown): string {
+  if (e instanceof Error) {
+    return e.message;
+  }
+  return String(e);
+}

package/src/credentials/pat.ts

@@ -0,0 +1,44 @@
+/**
+ * Personal Access Token (PAT) credentials for the Databricks SDK.
+ */
+
+import type {Credentials, Header} from '../auth';
+
+/**
+ * Error thrown when a token is required but not provided.
+ */
+class TokenRequiredError extends Error {
+  constructor() {
+    super('token is required');
+    this.name = 'TokenRequiredError';
+  }
+}
+
+/**
+ * Creates a Credentials that can be used to authenticate with a Personal
+ * Access Token.
+ *
+ * @param token - The personal access token.
+ * @returns Credentials for PAT authentication.
+ * @throws TokenRequiredError if token is empty.
+ */
+export function newPatCredentials(token: string): Credentials {
+  if (token === '') {
+    throw new TokenRequiredError();
+  }
+  return new PatCredentials(token);
+}
+
+class PatCredentials implements Credentials {
+  constructor(private readonly token: string) {}
+
+  name(): string {
+    return 'pat';
+  }
+
+  authHeaders(): Promise<Header[]> {
+    return Promise.resolve([
+      {key: 'Authorization', value: `Bearer ${this.token}`},
+    ]);
+  }
+}