@dbx-tools/auth 0.9.31 → 0.9.36

package/src/node-storage.ts

@@ -1,230 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
-
-import { acquireFileLock, type FileLockLease } from "@dbx-tools/core/file-lock";
-
-import { authLogger, credentialId, tokenMetadata } from "./_logging.ts";
-import { AuthError } from "./errors.ts";
-import type { CredentialStore, LockAdapter, Token } from "./types.ts";
-import { FileLayout } from "./types.ts";
-
-const logger = authLogger("file-storage");
-
-interface TokenCache {
-  version: number;
-  tokens: Record<string, unknown>;
-}
-
-class NodeFileLocks implements LockAdapter {
-  private readonly leases = new Map<string, FileLockLease>();
-
-  constructor(private readonly lockDirectory: string) {}
-
-  async acquire(key: string, timeoutMs: number): Promise<string> {
-    logger.debug("waiting for file lock", {
-      credential: credentialId(key),
-      timeoutMs,
-    });
-    const lease = await acquireFileLock(key, { dir: this.lockDirectory, timeoutMs });
-    const id = randomUUID();
-    this.leases.set(id, lease);
-    logger.debug("file lock acquired", {
-      credential: credentialId(key),
-      backend: lease.backend,
-    });
-    return id;
-  }
-
-  async release(id: string): Promise<void> {
-    const lease = this.leases.get(id);
-    if (!lease) return;
-    this.leases.delete(id);
-    await lease.release();
-    logger.debug("file lock released", { backend: lease.backend });
-  }
-}
-
-/** File-backed credential store preserving unrelated Databricks CLI entries. */
-export class FileCredentialStore implements CredentialStore {
-  private readonly locks: LockAdapter;
-
-  constructor(
-    private readonly root = join(homedir(), ".databricks"),
-    private readonly layout = FileLayout.Single,
-    locks?: LockAdapter,
-  ) {
-    this.locks = locks ?? new NodeFileLocks(join(root, "locks"));
-  }
-
-  async load(key: string): Promise<Token | undefined> {
-    const store = this.forKey(key);
-    return store.withCacheLock(async () => {
-      const token = deserializeToken((await store.readCache()).tokens[key]);
-      logger.debug("loaded file credential", {
-        credential: credentialId(key),
-        layout: this.layout,
-        token: tokenMetadata(token),
-      });
-      return token;
-    });
-  }
-
-  async prepareWrite(): Promise<void> {
-    await ensureDirectory(this.root, 0o700);
-    logger.debug("prepared credential directory", { layout: this.layout });
-  }
-
-  async save(key: string, token: Token): Promise<void> {
-    const store = this.forKey(key);
-    await store.withCacheLock(async () => {
-      const cache = await store.readCache();
-      cache.tokens[key] = serializeToken(token);
-      await store.writeCache(cache);
-      logger.debug("saved file credential", {
-        credential: credentialId(key),
-        layout: this.layout,
-        token: tokenMetadata(token),
-      });
-    });
-  }
-
-  async remove(key: string): Promise<void> {
-    const store = this.forKey(key);
-    await store.withCacheLock(async () => {
-      const cache = await store.readCache();
-      delete cache.tokens[key];
-      await store.writeCache(cache);
-      logger.debug("removed file credential", {
-        credential: credentialId(key),
-        layout: this.layout,
-      });
-    });
-  }
-
-  acquireLock(key: string, timeoutMs: number): Promise<string> {
-    return this.locks.acquire(
-      this.layout === FileLayout.Single ? `${this.root}:refresh` : `${this.root}:${key}:refresh`,
-      timeoutMs,
-    );
-  }
-
-  releaseLock(lease: string): Promise<void> {
-    return this.locks.release(lease);
-  }
-
-  name(): string {
-    return "file";
-  }
-
-  private forKey(key: string): FileCredentialStore {
-    if (this.layout === FileLayout.Single) return this;
-    const digest = createHash("sha256").update(key).digest("hex");
-    return new FileCredentialStore(join(this.root, digest), FileLayout.Single, this.locks);
-  }
-
-  private async withCacheLock<T>(action: () => Promise<T>): Promise<T> {
-    await ensureDirectory(this.root, 0o700);
-    const lease = await this.locks.acquire(`${this.root}:cache`, 30_000);
-    try {
-      return await action();
-    } finally {
-      await this.locks.release(lease);
-    }
-  }
-
-  private async readCache(): Promise<TokenCache> {
-    try {
-      const source = await readTextFile(join(this.root, "token-cache.json"));
-      const cache = source ? (JSON.parse(source) as TokenCache) : { version: 1, tokens: {} };
-      if (cache.version !== 1 || typeof cache.tokens !== "object" || !cache.tokens) {
-        throw new AuthError("storage", "Token cache must use version 1");
-      }
-      logger.debug("read token cache", {
-        exists: Boolean(source),
-        credentialCount: Object.keys(cache.tokens).length,
-      });
-      return cache;
-    } catch (cause) {
-      if (cause instanceof AuthError) throw cause;
-      throw new AuthError("storage", "Could not read Databricks token cache", { cause });
-    }
-  }
-
-  private async writeCache(cache: TokenCache): Promise<void> {
-    try {
-      await atomicWriteTextFile(
-        join(this.root, "token-cache.json"),
-        `${JSON.stringify(cache, null, 2)}\n`,
-        0o600,
-      );
-      logger.debug("wrote token cache", { credentialCount: Object.keys(cache.tokens).length });
-    } catch (cause) {
-      throw new AuthError("storage", "Could not write Databricks token cache", { cause });
-    }
-  }
-}
-
-async function ensureDirectory(path: string, mode: number): Promise<void> {
-  await mkdir(path, { recursive: true, mode });
-  await chmod(path, mode);
-}
-
-async function readTextFile(path: string): Promise<string | undefined> {
-  try {
-    return await readFile(path, "utf8");
-  } catch (cause) {
-    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw cause;
-  }
-}
-
-async function atomicWriteTextFile(path: string, content: string, mode: number): Promise<void> {
-  const parent = dirname(path);
-  await ensureDirectory(parent, 0o700);
-  const temporary = join(parent, `.${basename(path)}-${randomUUID()}.tmp`);
-  try {
-    await writeFile(temporary, content, { mode, flag: "wx" });
-    await chmod(temporary, mode);
-    await rename(temporary, path);
-  } finally {
-    await unlink(temporary).catch((cause: NodeJS.ErrnoException) => {
-      if (cause.code !== "ENOENT") throw cause;
-    });
-  }
-}
-
-function serializeToken(token: Token): Record<string, unknown> {
-  return {
-    access_token: token.accessToken,
-    token_type: token.tokenType,
-    ...(token.refreshToken ? { refresh_token: token.refreshToken } : {}),
-    ...(token.expiry ? { expiry: token.expiry } : {}),
-    ...(token.scopes.length ? { scopes: token.scopes } : {}),
-  };
-}
-
-function deserializeToken(value: unknown): Token | undefined {
-  if (!value || typeof value !== "object") return undefined;
-  const record = value as Record<string, unknown>;
-  const accessToken = stringValue(record.access_token ?? record.accessToken);
-  if (!accessToken) return undefined;
-  return {
-    accessToken,
-    tokenType: stringValue(record.token_type ?? record.tokenType) ?? "Bearer",
-    ...(stringValue(record.refresh_token ?? record.refreshToken)
-      ? { refreshToken: stringValue(record.refresh_token ?? record.refreshToken) }
-      : {}),
-    ...(stringValue(record.expiry ?? record.expires_at)
-      ? { expiry: stringValue(record.expiry ?? record.expires_at) }
-      : {}),
-    scopes: Array.isArray(record.scopes)
-      ? record.scopes.filter((scope): scope is string => typeof scope === "string")
-      : [],
-  };
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value : undefined;
-}

package/src/storage.ts

@@ -1,104 +0,0 @@
-import { authLogger, credentialId, tokenMetadata } from "./_logging.ts";
-import type { CredentialStore, LockAdapter, Token } from "./types.ts";
-
-const logger = authLogger("memory-storage");
-
-/** Process-local generic lease registry used by the in-memory store. */
-export class MemoryLockAdapter implements LockAdapter {
-  readonly #tails = new Map<string, Promise<void>>();
-  readonly #leases = new Map<string, () => void>();
-  #sequence = 0;
-
-  async acquire(key: string, timeoutMs: number): Promise<string> {
-    const credential = credentialId(key);
-    const previous = this.#tails.get(key) ?? Promise.resolve();
-    let release!: () => void;
-    const current = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    const tail = previous.then(() => current);
-    this.#tails.set(key, tail);
-    try {
-      logger.debug("waiting for memory lock", { credential, timeoutMs });
-      await withTimeout(previous, timeoutMs, `Timed out waiting for lock ${key}`);
-    } catch (error) {
-      release();
-      if (this.#tails.get(key) === tail) this.#tails.delete(key);
-      throw error;
-    }
-    const lease = `${++this.#sequence}:${key}`;
-    this.#leases.set(lease, () => {
-      release();
-      this.#leases.delete(lease);
-      if (this.#tails.get(key) === tail) this.#tails.delete(key);
-    });
-    logger.debug("memory lock acquired", { credential });
-    return lease;
-  }
-
-  async release(lease: string): Promise<void> {
-    logger.debug("releasing memory lock", {
-      credential: credentialId(lease.split(":").slice(1).join(":")),
-    });
-    this.#leases.get(lease)?.();
-  }
-}
-
-/** Process-local credential store with per-key refresh locks. */
-export class MemoryCredentialStore implements CredentialStore {
-  readonly #tokens = new Map<string, Token>();
-
-  constructor(private readonly locks: LockAdapter = new MemoryLockAdapter()) {}
-
-  async load(key: string): Promise<Token | undefined> {
-    const token = this.#tokens.get(key);
-    logger.debug("loaded memory credential", {
-      credential: credentialId(key),
-      token: tokenMetadata(token),
-    });
-    return token ? structuredClone(token) : undefined;
-  }
-
-  async prepareWrite(): Promise<void> {}
-
-  async save(key: string, token: Token): Promise<void> {
-    this.#tokens.set(key, structuredClone(token));
-    logger.debug("saved memory credential", {
-      credential: credentialId(key),
-      token: tokenMetadata(token),
-    });
-  }
-
-  async remove(key: string): Promise<void> {
-    this.#tokens.delete(key);
-    logger.debug("removed memory credential", { credential: credentialId(key) });
-  }
-
-  acquireLock(key: string, timeoutMs: number): Promise<string> {
-    return this.locks.acquire(key, timeoutMs);
-  }
-
-  releaseLock(lease: string): Promise<void> {
-    return this.locks.release(lease);
-  }
-
-  name(): string {
-    return "memory";
-  }
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
-  if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
-    throw new TypeError("timeoutMs must be non-negative");
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<never>((_, reject) => {
-        timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
-      }),
-    ]);
-  } finally {
-    if (timeout) clearTimeout(timeout);
-  }
-}

package/src/types.ts

@@ -1,188 +0,0 @@
-/** Authentication strategy selected from Databricks configuration. */
-export enum AuthKind {
-  UserToMachine = "user-to-machine",
-  MachineToMachine = "machine-to-machine",
-  PersonalAccessToken = "personal-access-token",
-  AppServicePrincipal = "app-service-principal",
-  AppOnBehalfOf = "app-on-behalf-of",
-}
-
-/** Scope of the Databricks authentication target. */
-export enum TargetKind {
-  Workspace = "workspace",
-  Account = "account",
-  Unified = "unified",
-}
-
-/** Built-in credential storage backend. */
-export enum Storage {
-  Auto = "auto",
-  Memory = "memory",
-  File = "file",
-}
-
-/** File organization used by a persistent credential store. */
-export enum FileLayout {
-  Single = "single",
-  PerCredential = "per-credential",
-}
-
-/** Stored OAuth credential, including renewal metadata. */
-export interface Token {
-  accessToken: string;
-  tokenType: string;
-  refreshToken?: string;
-  expiry?: string;
-  scopes: string[];
-}
-
-/** Public credential result; deliberately excludes the refresh token. */
-export interface AccessToken {
-  accessToken: string;
-  tokenType: string;
-  expiry?: string;
-  scopes: string[];
-}
-
-/** Shared lifecycle configuration embedded by every provider. */
-export interface AuthOptions {
-  refreshBufferSeconds: number;
-  lockTimeoutSeconds: number;
-  loginTimeoutSeconds: number;
-}
-
-const AUTH_DEFAULTS: AuthOptions = {
-  refreshBufferSeconds: 300,
-  lockTimeoutSeconds: 30,
-  loginTimeoutSeconds: 900,
-};
-
-/** Record-style factory retained for straightforward Node/Python bridging. */
-export const AuthOptions = {
-  create(options: Partial<AuthOptions> = {}): AuthOptions {
-    return { ...AUTH_DEFAULTS, ...options };
-  },
-  defaults(): Readonly<AuthOptions> {
-    return Object.freeze({ ...AUTH_DEFAULTS });
-  },
-};
-
-/** Secret-free metadata discovered from one Databricks CLI profile. */
-export interface DatabricksProfileSummary {
-  name: string;
-  host?: string;
-  accountId?: string;
-  workspaceId?: string;
-  target: TargetKind;
-  authKind: AuthKind;
-}
-
-/** Resolved Databricks identity and active storage backend. */
-export interface DatabricksAuthStatus {
-  profile: string;
-  host: string;
-  storage: Storage;
-}
-
-/** Public Databricks authentication options. */
-export interface DatabricksAuthOptions {
-  profile?: string;
-  host?: string;
-  accountId?: string;
-  workspaceId?: string;
-  configFile?: string;
-  clientId?: string;
-  clientSecret?: string;
-  accessToken?: string;
-  groupId?: string;
-  authType?: string;
-  scopes?: string[];
-  target?: string;
-  cacheDir?: string;
-  auth?: AuthOptions;
-  requestHeaders?: Record<string, string>;
-  accessTokenHeader?: string;
-  installCliInApp?: boolean;
-  preferUserToMachine: boolean;
-}
-
-/** Record-style factory retained for callers migrating from generated bindings. */
-export const DatabricksAuthOptions = {
-  create(options: Partial<DatabricksAuthOptions> = {}): DatabricksAuthOptions {
-    return { preferUserToMachine: true, ...options };
-  },
-  defaults(): Readonly<DatabricksAuthOptions> {
-    return Object.freeze({ preferUserToMachine: true });
-  },
-};
-
-/** Resolved profile with secrets retained only for provider construction. */
-export interface DatabricksProfile extends DatabricksProfileSummary {
-  host: string;
-  authType?: string;
-  clientId: string;
-  groupId?: string;
-  scopes: string[];
-  clientSecret?: string;
-  accessToken?: string;
-  cacheKey: string;
-  principal: string;
-}
-
-/** Cross-language lease adapter; implementations may use files, databases, or FFI. */
-export interface LockAdapter {
-  acquire(key: string, timeoutMs: number): Promise<string>;
-  release(lease: string): Promise<void>;
-}
-
-/** Cross-language credential persistence contract. */
-export interface CredentialStore {
-  load(key: string): Promise<Token | undefined>;
-  prepareWrite(): Promise<void>;
-  save(key: string, token: Token): Promise<void>;
-  remove(key: string): Promise<void>;
-  acquireLock(key: string, timeoutMs: number): Promise<string>;
-  releaseLock(lease: string): Promise<void>;
-  name(): string;
-}
-
-/** Provider-specific token acquisition. */
-export interface TokenProvider {
-  authenticate(timeoutMs: number): Promise<Token>;
-  login(timeoutMs: number): Promise<Token>;
-  refresh(token: Token): Promise<Token>;
-  canAuthenticateSilently(): boolean;
-}
-
-/** Stable facade shared by Node, the CLI, and generated language bindings. */
-export interface AuthClient {
-  challenge(): Promise<void>;
-  token(login?: boolean): Promise<AccessToken>;
-  authenticate(login?: boolean): Promise<Record<string, string>>;
-  authorizationHeaderForUrl(requestUrl: string, login?: boolean): Promise<string | undefined>;
-  requestHeadersForUrl(requestUrl: string, login?: boolean): Promise<Record<string, string>>;
-  forceRefreshToken(login?: boolean): Promise<AccessToken>;
-  refreshRejectedToken(staleAccessToken: string, login?: boolean): Promise<AccessToken>;
-  logout(): Promise<void>;
-  status(): DatabricksAuthStatus;
-  principal(): string;
-  workspaceId(): string | undefined;
-  authKind(): AuthKind;
-  profile(name?: string): DatabricksProfileSummary;
-  listProfiles(refresh?: boolean): DatabricksProfileSummary[];
-}
-
-/** Public OAuth client used by Databricks CLI-compatible user authentication. */
-export const DEFAULT_CLIENT_ID = "databricks-cli";
-/** Default Databricks profile configuration path. */
-export const DEFAULT_CONFIG_FILE = "~/.databrickscfg";
-/** Default Databricks account console origin. */
-export const DEFAULT_ACCOUNTS_HOST = "https://accounts.cloud.databricks.com";
-/** Canonical request header carrying a bearer access token. */
-export const DEFAULT_ACCESS_TOKEN_HEADER = "authorization";
-/** Canonical request header carrying the resolved Databricks workspace ID. */
-export const WORKSPACE_ID_HEADER = "x-databricks-workspace-id";
-/** Authentication type for Databricks App on-behalf-of request credentials. */
-export const AUTH_TYPE_APP_OBO = "app_obo";
-/** Authentication type for Databricks App service-principal credentials. */
-export const AUTH_TYPE_APP_SP = "app_sp";