@dbx-tools/auth 0.6.182 → 0.9.29

package/src/lifecycle.ts

@@ -0,0 +1,239 @@
+import { AuthError } from "./errors.ts";
+import { authLogger, credentialId, failureMetadata, tokenMetadata } from "./_logging.ts";
+import type { AccessToken, AuthOptions, CredentialStore, Token, TokenProvider } from "./types.ts";
+
+const logger = authLogger("lifecycle");
+
+/** Provider-neutral check-lock-check authentication and persistent token lifecycle. */
+export class TokenLifecycle {
+  constructor(
+    private readonly key: string,
+    private readonly provider: TokenProvider,
+    private readonly store: CredentialStore,
+    private readonly options: 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,
+      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),
+      );
+      await this.store.save(this.key, token);
+      logger.debug("interactive login stored credential", {
+        ...this.context(),
+        token: tokenMetadata(token, this.now()),
+      });
+      return publicToken(token);
+    });
+  }
+
+  token(): Promise<AccessToken> {
+    return this.loadToken(false);
+  }
+
+  tokenOrLogin(): Promise<AccessToken> {
+    return this.loadToken(true);
+  }
+
+  async tokenWithLogin(login?: boolean): Promise<AccessToken> {
+    logger.debug("token requested", { ...this.context(), login: login ?? "auto" });
+    if (login === true) return this.login();
+    if (login === false) return this.token();
+    return this.tokenOrLogin();
+  }
+
+  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);
+  }
+
+  async logout(): Promise<void> {
+    logger.debug("logout requested", this.context());
+    await this.withLock(() => this.store.remove(this.key));
+    logger.debug("stored credential removed", this.context());
+  }
+
+  private async loadToken(login: boolean): Promise<AccessToken> {
+    const existing = await this.store.load(this.key);
+    const reusable = Boolean(existing && this.canReuse(existing));
+    logger.debug("checked credential cache", {
+      ...this.context(),
+      login,
+      reusable,
+      token: tokenMetadata(existing, this.now()),
+    });
+    if (existing && reusable) return publicToken(existing);
+    return this.withLock(async () => {
+      const current = await this.store.load(this.key);
+      const currentReusable = Boolean(current && this.canReuse(current));
+      logger.debug("rechecked credential cache after lock", {
+        ...this.context(),
+        reusable: currentReusable,
+        token: tokenMetadata(current, this.now()),
+      });
+      if (current && currentReusable) return publicToken(current);
+      return this.renew(current, login);
+    });
+  }
+
+  private async refreshRejected(
+    staleAccessToken: string | undefined,
+    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);
+    });
+  }
+
+  private async renew(current: Token | undefined, login: boolean): Promise<AccessToken> {
+    let token: Token;
+    if (current) {
+      logger.debug("refreshing stored credential", {
+        ...this.context(),
+        loginFallback: login,
+        token: tokenMetadata(current, this.now()),
+      });
+      try {
+        token = await this.provider.refresh(current);
+      } catch (error) {
+        logger.debug("credential refresh failed", {
+          ...this.context(),
+          loginFallback: login,
+          error: failureMetadata(error),
+        });
+        if (!login) throw error;
+        logger.debug("falling back to interactive login", this.context());
+        token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+      }
+    } else if (this.provider.canAuthenticateSilently()) {
+      logger.debug("attempting silent credential acquisition", {
+        ...this.context(),
+        loginFallback: login,
+      });
+      try {
+        token = await this.provider.authenticate(this.options.loginTimeoutSeconds * 1000);
+      } catch (error) {
+        logger.debug("silent credential acquisition failed", {
+          ...this.context(),
+          loginFallback: login,
+          error: failureMetadata(error),
+        });
+        if (!login) throw error;
+        logger.debug("falling back to interactive login", this.context());
+        token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+      }
+    } else if (login) {
+      logger.debug("provider requires interactive login", this.context());
+      token = await this.provider.login(this.options.loginTimeoutSeconds * 1000);
+    } else {
+      throw new AuthError(
+        "oauth",
+        "No stored credential is available and interactive login is disabled",
+      );
+    }
+    token = validateToken(token, current);
+    logger.debug("credential acquisition completed", {
+      ...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);
+  }
+
+  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
+    );
+  }
+
+  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);
+    logger.debug("credential lock acquired", this.context());
+    let failure: unknown;
+    try {
+      return await action();
+    } catch (error) {
+      failure = error;
+      throw error;
+    } finally {
+      try {
+        await this.store.releaseLock(lease);
+        logger.debug("credential lock released", this.context());
+      } catch (releaseError) {
+        logger.debug("credential lock release failed", {
+          ...this.context(),
+          error: failureMetadata(releaseError),
+        });
+        if (failure === undefined) throw releaseError;
+      }
+    }
+  }
+
+  private context(): Record<string, unknown> {
+    return { credential: credentialId(this.key), storage: this.store.name() };
+  }
+}
+
+export function publicToken(token: Token): AccessToken {
+  return {
+    accessToken: token.accessToken,
+    tokenType: token.tokenType,
+    ...(token.expiry ? { expiry: token.expiry } : {}),
+    scopes: [...token.scopes],
+  };
+}
+
+export function validateToken(token: Token, previous?: Token): Token {
+  if (!token.accessToken.trim())
+    throw new AuthError("oauth", "Token response did not contain an access token");
+  return {
+    accessToken: token.accessToken,
+    tokenType: token.tokenType || "Bearer",
+    refreshToken: token.refreshToken ?? previous?.refreshToken,
+    expiry: token.expiry,
+    scopes: token.scopes.length ? [...token.scopes] : [...(previous?.scopes ?? [])],
+  };
+}
+
+function isValid(token: Token, now: Date): boolean {
+  return Boolean(token.accessToken) && (!token.expiry || Date.parse(token.expiry) > now.getTime());
+}

package/src/node-storage.ts

@@ -0,0 +1,230 @@
+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/personal-access-token.ts

@@ -0,0 +1,34 @@
+import { authLogger } from "./_logging.ts";
+import type { Token, TokenProvider } from "./types.ts";
+
+const logger = authLogger("pat");
+
+/** Non-refreshing provider for a configured Databricks personal access token. */
+export class DatabricksPersonalAccessTokenProvider implements TokenProvider {
+  constructor(private readonly accessToken: string) {}
+
+  authenticate(): Promise<Token> {
+    return Promise.resolve(this.token());
+  }
+
+  login(): Promise<Token> {
+    return Promise.resolve(this.token());
+  }
+
+  refresh(): Promise<Token> {
+    return Promise.resolve(this.token());
+  }
+
+  canAuthenticateSilently(): boolean {
+    return true;
+  }
+
+  private token(): Token {
+    logger.debug("using configured personal access token");
+    return {
+      accessToken: this.accessToken,
+      tokenType: "Bearer",
+      scopes: [],
+    };
+  }
+}

package/src/service-principal.ts

@@ -0,0 +1,96 @@
+import * as oauth from "oauth4webapi";
+
+import { authLogger, failureMetadata, tokenMetadata } from "./_logging.ts";
+import { AuthError } from "./errors.ts";
+import type { Token, TokenProvider } from "./types.ts";
+
+const logger = authLogger("service-principal");
+
+/** Client-credentials inputs and transport options for Databricks OAuth. */
+export interface DatabricksServicePrincipalConfig {
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+  groupId?: string;
+  fetch?: typeof globalThis.fetch;
+  allowInsecureRequests?: boolean;
+}
+
+/** Databricks service-principal provider backed by client credentials. */
+export class DatabricksServicePrincipalProvider implements TokenProvider {
+  private readonly authorizationServer: oauth.AuthorizationServer;
+  private readonly client: oauth.Client;
+  private readonly requestOptions: oauth.HttpRequestOptions<string, URLSearchParams>;
+
+  constructor(private readonly config: DatabricksServicePrincipalConfig) {
+    this.authorizationServer = {
+      issuer: new URL(config.tokenEndpoint).origin,
+      token_endpoint: config.tokenEndpoint,
+    };
+    this.client = { client_id: config.clientId };
+    this.requestOptions = {
+      ...(config.fetch ? { [oauth.customFetch]: config.fetch as typeof globalThis.fetch } : {}),
+      ...(config.allowInsecureRequests ? { [oauth.allowInsecureRequests]: true } : {}),
+    };
+  }
+
+  authenticate(): Promise<Token> {
+    return this.acquire();
+  }
+
+  login(): Promise<Token> {
+    return this.acquire();
+  }
+
+  refresh(): Promise<Token> {
+    return this.acquire();
+  }
+
+  canAuthenticateSilently(): boolean {
+    return true;
+  }
+
+  private async acquire(): Promise<Token> {
+    logger.debug("requesting service-principal token", {
+      tokenOrigin: new URL(this.config.tokenEndpoint).origin,
+      scopeCount: this.config.scopes.length,
+      hasGroupId: Boolean(this.config.groupId),
+      allowInsecureRequests: Boolean(this.config.allowInsecureRequests),
+    });
+    try {
+      const response = await oauth.clientCredentialsGrantRequest(
+        this.authorizationServer,
+        this.client,
+        oauth.ClientSecretBasic(this.config.clientSecret),
+        {
+          scope: [...new Set(this.config.scopes)].sort().join(" "),
+          ...(this.config.groupId ? { assume_group: this.config.groupId } : {}),
+        },
+        this.requestOptions,
+      );
+      const value = await oauth.processClientCredentialsResponse(
+        this.authorizationServer,
+        this.client,
+        response,
+      );
+      const token = {
+        accessToken: value.access_token,
+        tokenType: value.token_type.toLowerCase() === "bearer" ? "Bearer" : value.token_type,
+        ...(value.expires_in !== undefined
+          ? { expiry: new Date(Date.now() + value.expires_in * 1000).toISOString() }
+          : {}),
+        scopes: value.scope?.split(/\s+/).filter(Boolean) ?? [...this.config.scopes],
+      };
+      logger.debug("received service-principal token", { token: tokenMetadata(token) });
+      return token;
+    } catch (cause) {
+      logger.debug("service-principal token request failed", {
+        error: failureMetadata(cause),
+      });
+      throw new AuthError("oauth", "Databricks service-principal authentication failed", {
+        cause,
+      });
+    }
+  }
+}

package/src/storage.ts

@@ -0,0 +1,104 @@
+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);
+  }
+}