feat: add persistent OAuth token cache and session APIs (#4182)

Stacked on #4173 (diff includes it until that merges; will rebase
after). Addresses the token-cache part of [Colin's
review](https://github.com/lancedb/lancedb/pull/4173#issuecomment-5674048100).

Adds an explicit, opt-in persistent OAuth token cache shared by Rust,
Python, and Node clients, plus `login` / `status` / `logout` session
APIs, so short-lived processes (CLIs, scripts, notebooks) reuse one
session instead of restarting a browser or device flow on every start.

- **Opt-in and minimal**: existing callers stay memory-only and lazy.
Only refresh tokens are persisted (never access tokens, never client
secrets), so there are no local token-expiry decisions to get wrong when
clocks move. Each process start performs one silent refresh grant.
- **Hardened file backend**: private directory (`0700`), per-record
files (`0600`), owner validation, symlink rejection, and atomic `rename`
replacement. Corrupt, truncated, unknown-version, or permission-invalid
records fail with actionable errors naming the file. Native keyring
backends were evaluated (keyring crate routes Linux through D-Bus/zbus:
heavy deps, headless/CI flakiness) and are deferred; the file store is
the explicit opt-in, not a downgrade from a keyring.
- **Cache key**: SHA-256 of the canonical identity (issuer, client ID,
sorted/de-duplicated scopes, flow, public/confidential), so no secret
appears in a filename and distinct identities never collide. Versioned
record schema (`version: 1`). One record per identity: last login wins,
documented.
- **Cross-process rotation locking**: per-key `fs4` file lock (`flock` /
`LockFileEx`) around the refresh critical section — acquire, reread the
durable record, refresh exactly once, atomically store the rotated
refresh token, release. The OS releases locks on process death, so
crashes cannot strand stale locks. Only confirmed
`invalid_grant`/`invalid_token` deletes a record and reauthenticates;
transport, 5xx, 429, and parse failures retain it.
- **Session APIs**: `OAuthSession::login/status/logout` in Rust,
`lancedb.remote.OAuthSession` (async) in Python, `OAuthSession` class in
Node. `status` returns non-secret metadata only. `logout` removes only
the local credential — provider revocation (RFC 7009) is a deliberate
follow-up, and local logout never terminates browser SSO. Azure managed
identity is rejected for persistence (machine identity stays in memory);
client credentials have nothing refreshable to persist and stay
memory-only.
- No CLI binary exists in this repo, so this ships library APIs plus doc
examples in all three languages.

Tests: Rust unit + mock-IdP integration (cache-key
canonicalization/separation, record
versioning/corruption/truncation/symlink/owner/perms, lock serialization
+ release, two concurrent providers proving no `invalid_grant` and
correct rotation, transient-failure retention, `invalid_grant` delete +
reauthenticate, login/status/logout lifecycle, client-credentials no-op,
IMDS rejection, secret redaction); Python lifecycle + a true
two-subprocess cross-process reuse test (second process refreshes once,
never hits the device endpoint); Node lifecycle + device-flow login
test. Local builds were skipped in development; CI validates all
bindings.

---------

Co-authored-by: Xuanwo <github@xuanwo.io>

nodejs/__test__/oauth.test.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import * as fs from "fs";
+import * as http from "http";
+import * as os from "os";
+import * as path from "path";
+import { OAuthConfig, OAuthFlowType, OAuthSession } from "../lancedb/oauth";
+
+function tempCacheDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "lancedb-oauth-cache-"));
+}
+
+function deviceConfig(issuerUrl: string, cacheDir: string): OAuthConfig {
+  return {
+    issuerUrl,
+    clientId: "client-id",
+    scopes: ["openid"],
+    flow: OAuthFlowType.DeviceCode,
+    tokenCache: { cacheDir },
+  };
+}
+
+describe("OAuthSession", () => {
+  beforeAll(() => {
+    // Point the Rust browser helper at a no-op so device-flow logins never
+    // open a real browser window during tests.
+    process.env.LANCEDB_OAUTH_BROWSER = "/usr/bin/true";
+  });
+
+  it("reports an absent session and logout is idempotent", async () => {
+    const cacheDir = tempCacheDir();
+    const session = new OAuthSession(
+      deviceConfig("https://issuer.example.com", cacheDir),
+    );
+
+    const status = await session.status();
+    expect(status.refreshable).toBe(false);
+    expect(status.issuerUrl).toBe("https://issuer.example.com");
+    expect(status.clientId).toBe("client-id");
+    expect(status.scopes).toEqual(["openid"]);
+    expect(status.flow).toBe("device_code");
+    expect(status.obtainedAt).toBeUndefined();
+
+    const logout = await session.logout();
+    expect(logout.removed).toBe(false);
+  });
+
+  it("requires token cache options", () => {
+    const config: OAuthConfig = {
+      issuerUrl: "https://issuer.example.com",
+      clientId: "client-id",
+      scopes: ["openid"],
+      flow: OAuthFlowType.DeviceCode,
+    };
+    expect(() => new OAuthSession(config)).toThrow(/token/);
+  });
+
+  it("rejects azure managed identity persistence", () => {
+    const config: OAuthConfig = {
+      issuerUrl: "https://login.microsoftonline.com/tenant/v2.0",
+      clientId: "app-id",
+      scopes: ["api://app/.default"],
+      flow: OAuthFlowType.AzureManagedIdentity,
+      tokenCache: { cacheDir: tempCacheDir() },
+    };
+    expect(() => new OAuthSession(config)).toThrow(/AzureManagedIdentity/);
+  });
+
+  it("logs in via device flow, caches, and logs out", async () => {
+    const server = new MockIdp();
+    await server.start();
+    try {
+      const cacheDir = tempCacheDir();
+      const issuerUrl = server.issuerUrl();
+
+      const session = new OAuthSession(deviceConfig(issuerUrl, cacheDir));
+      const status = await session.login();
+      expect(status.refreshable).toBe(true);
+      expect(status.obtainedAt).toBeGreaterThan(0);
+      expect(server.state.deviceAuthorizations).toBe(1);
+
+      // An independent session (a fresh "process") sees the cached login.
+      const other = new OAuthSession(deviceConfig(issuerUrl, cacheDir));
+      const cached = await other.status();
+      expect(cached.refreshable).toBe(true);
+
+      const logout = await other.logout();
+      expect(logout.removed).toBe(true);
+      const again = await session.logout();
+      expect(again.removed).toBe(false);
+      expect((await session.status()).refreshable).toBe(false);
+
+      // Only the initial login used the interactive device flow.
+      expect(server.state.deviceAuthorizations).toBe(1);
+      expect(server.state.refreshGrants).toBe(0);
+    } finally {
+      server.close();
+    }
+  }, 15000);
+});
+
+/** Mock IdP with discovery, device authorization, and rotating refresh. */
+class MockIdp {
+  readonly state = {
+    deviceAuthorizations: 0,
+    refreshGrants: 0,
+    accessTokensIssued: 0,
+    currentRefresh: null as string | null,
+  };
+  private server?: http.Server;
+  private port = 0;
+
+  issuerUrl(): string {
+    return `http://127.0.0.1:${this.port}`;
+  }
+
+  async start(): Promise<void> {
+    const server = http.createServer((req, res) => {
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk) => chunks.push(chunk));
+      req.on("end", () => {
+        const body = Buffer.concat(chunks).toString();
+        const params = new URLSearchParams(body);
+        this.handle(req.url ?? "", params, res);
+      });
+    });
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    if (address && typeof address === "object") {
+      this.port = address.port;
+    }
+    this.server = server;
+  }
+
+  private handle(
+    url: string,
+    params: URLSearchParams,
+    res: http.ServerResponse,
+  ): void {
+    const respond = (status: number, payload: unknown): void => {
+      const body = JSON.stringify(payload);
+      res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      });
+      res.end(body);
+    };
+
+    if (url === "/.well-known/openid-configuration") {
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        token_endpoint: `${this.issuerUrl()}/token`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        device_authorization_endpoint: `${this.issuerUrl()}/device`,
+      });
+      return;
+    }
+
+    if (url === "/device") {
+      this.state.deviceAuthorizations += 1;
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        device_code: "device-code",
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        user_code: "ABCD-EFGH",
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        verification_uri: `${this.issuerUrl()}/verify`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        expires_in: 60,
+        interval: 1,
+      });
+      return;
+    }
+
+    if (url === "/token") {
+      const grantType = params.get("grant_type") ?? "";
+      if (grantType === "refresh_token") {
+        this.state.refreshGrants += 1;
+        if (params.get("refresh_token") !== this.state.currentRefresh) {
+          respond(400, { error: "invalid_grant" });
+          return;
+        }
+      } else if (!grantType.includes("device_code")) {
+        respond(400, { error: "unsupported_grant_type" });
+        return;
+      }
+      this.state.accessTokensIssued += 1;
+      const number = this.state.accessTokensIssued;
+      const refresh = `refresh-${number}`;
+      this.state.currentRefresh = refresh;
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        access_token: `access-${number}`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        refresh_token: refresh,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        expires_in: 3600,
+      });
+      return;
+    }
+
+    respond(404, {});
+  }
+
+  close(): void {
+    this.server?.close();
+  }
+}

nodejs/lancedb/index.ts

@@ -170,7 +170,14 @@ export {
   TokenResponse,
 } from "./header";
 
-export { OAuthConfig, OAuthFlowType } from "./oauth";
+export {
+  OAuthConfig,
+  OAuthFlowType,
+  OAuthSession,
+  SessionLogout,
+  SessionStatus,
+  TokenCacheOptions,
+} from "./oauth";
 
 export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
 

nodejs/lancedb/oauth.ts

@@ -1,16 +1,52 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 
+import {
+  OAuthConfig as NativeOAuthConfig,
+  OAuthSession as NativeOAuthSession,
+} from "./native";
+
 /**
  * OAuth authentication flow types.
  */
 export enum OAuthFlowType {
   /** Client Credentials grant (service-to-service / M2M). */
   ClientCredentials = "client_credentials",
+  /** Interactive Authorization Code grant, using PKCE by default. */
+  AuthorizationCode = "authorization_code",
+  /** Device Authorization grant for CLI and headless environments. */
+  DeviceCode = "device_code",
   /** Azure Managed Identity via IMDS. */
   AzureManagedIdentity = "azure_managed_identity",
 }
 
+/**
+ * Options for the persistent OAuth token cache.
+ *
+ * The cache is opt-in: it is only used when set as `tokenCache` on
+ * {@link OAuthConfig}. Only refresh tokens are persisted, in a private
+ * directory with owner-only permissions, so short-lived processes can reuse
+ * an authenticated session instead of re-prompting on every start.
+ *
+ * Multiple identities (issuer, client, scopes, flow, client authentication)
+ * get separate cache entries. Within one identity the most recent login wins.
+ */
+export interface TokenCacheOptions {
+  /**
+   * Directory that holds cached credentials. Defaults to
+   * `$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+   * or `%LOCALAPPDATA%\\lancedb\\oauth` on Windows. The directory is created
+   * with owner-only permissions (`0700`) when missing.
+   */
+  cacheDir?: string;
+
+  /**
+   * How long to wait for the cross-process refresh lock before failing, in
+   * seconds (default: 30).
+   */
+  lockTimeoutSecs?: number;
+}
+
 /**
  * OAuth configuration for LanceDB authentication.
  *
@@ -40,6 +76,21 @@ export enum OAuthFlowType {
  *   flow: OAuthFlowType.AzureManagedIdentity,
  * };
  * ```
+ *
+ * @example Authorization Code with PKCE:
+ * The authorization URL is written to stderr before LanceDB tries to open a
+ * browser, so it can be copied in headless environments.
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0",
+ *   clientId: "app-id",
+ *   scopes: ["openid", "api://lancedb-api/access"],
+ *   flow: OAuthFlowType.AuthorizationCode,
+ * };
+ * ```
+ *
+ * Device Authorization writes the verification URL and user code to stderr
+ * before polling begins.
  */
 export interface OAuthConfig {
   /**
@@ -64,6 +115,15 @@ export interface OAuthConfig {
   /** Client secret (required for ClientCredentials). */
   clientSecret?: string;
 
+  /** Loopback redirect URI for AuthorizationCode. */
+  redirectUri?: string;
+
+  /** Port for the AuthorizationCode loopback callback server (default: 8400). */
+  callbackPort?: number;
+
+  /** Protect AuthorizationCode with S256 PKCE (default: true). */
+  usePkce?: boolean;
+
   /** Client ID for user-assigned managed identity (AzureManagedIdentity). */
   managedIdentityClientId?: string;
 
@@ -73,4 +133,119 @@ export interface OAuthConfig {
    * the TTL, each request refreshes the token.
    */
   refreshBufferSecs?: number;
+
+  /**
+   * Opt in to the persistent token cache so short-lived processes reuse one
+   * session. Only refresh tokens are persisted. Only supported by
+   * AuthorizationCode and DeviceCode; Azure managed identity is rejected.
+   * Default: unset (memory only).
+   */
+  tokenCache?: TokenCacheOptions;
+}
+
+/**
+ * Safe, non-secret view of a cached OAuth session, returned by
+ * {@link OAuthSession.status} and {@link OAuthSession.login}.
+ */
+export interface SessionStatus {
+  /**
+   * Whether a cached session exists that can obtain tokens without
+   * interactive authentication. Because access tokens are not persisted,
+   * this is `true` exactly when a refresh token is cached; the next
+   * connection refreshes with it rather than opening a browser or device
+   * prompt.
+   */
+  refreshable: boolean;
+
+  /** Canonical issuer URL of the cached session. */
+  issuerUrl: string;
+
+  /** Client ID of the cached session. */
+  clientId: string;
+
+  /** Canonical (sorted, de-duplicated) scope set of the cached session. */
+  scopes: string[];
+
+  /** Flow that produced the cached session. */
+  flow: string;
+
+  /** When the cached session was obtained, as Unix seconds. */
+  obtainedAt?: number;
+}
+
+/** Result of {@link OAuthSession.logout}. */
+export interface SessionLogout {
+  /**
+   * Whether a cached credential was removed. `false` means no matching
+   * session was cached; logout is idempotent.
+   */
+  removed: boolean;
+}
+
+/**
+ * Explicit OAuth session lifecycle for the persistent token cache: eager
+ * `login`, non-secret `status`, and local `logout`.
+ *
+ * A session is built from the same {@link OAuthConfig} used to connect
+ * (including its `tokenCache` options). A connection created with the same
+ * configuration shares the cache, so logging in here prepares tokens for
+ * later processes without any database request.
+ *
+ * `login` always runs the configured interactive flow and replaces the cached
+ * session (the most recent login wins). `logout` removes only the local
+ * credential; it does not revoke anything with the provider and does not sign
+ * out of a browser SSO session.
+ *
+ * @example
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   issuerUrl: "https://issuer.example.com",
+ *   clientId: "my-app",
+ *   scopes: ["openid", "offline_access"],
+ *   flow: OAuthFlowType.DeviceCode,
+ *   tokenCache: { cacheDir: "/tmp/my-app/oauth-cache" },
+ * };
+ * const session = new OAuthSession(config);
+ * const status = await session.login();
+ * ```
+ */
+export class OAuthSession {
+  private readonly inner: NativeOAuthSession;
+
+  /** Create a session manager for the given OAuth configuration. */
+  constructor(config: OAuthConfig) {
+    this.inner = new NativeOAuthSession(config as unknown as NativeOAuthConfig);
+  }
+
+  /**
+   * Eagerly run the configured authentication flow and store the session.
+   *
+   * A successful login always replaces any prior cached session for this
+   * identity; if the provider does not issue a refresh token (for example
+   * without `offline_access`), the previous record is removed and the status
+   * reports `refreshable == false`.
+   */
+  async login(): Promise<SessionStatus> {
+    return this.inner.login();
+  }
+
+  /**
+   * Report whether a matching cached session exists, with safe metadata.
+   *
+   * This never contacts the identity provider and never exposes token values.
+   */
+  async status(): Promise<SessionStatus> {
+    return this.inner.status();
+  }
+
+  /**
+   * Remove the matching local cached credential.
+   *
+   * This only deletes the local cache entry. It does not revoke the refresh
+   * token with the provider and does not sign out of a browser SSO session.
+   * Repeated calls succeed; `removed` reports whether a credential existed.
+   */
+  async logout(): Promise<SessionLogout> {
+    return this.inner.logout();
+  }
 }

nodejs/src/remote.rs

@@ -6,6 +6,8 @@ use std::collections::HashMap;
 use lancedb::error::Error;
 use napi_derive::*;
 
+use crate::error::NapiErrorExt;
+
 /// Timeout configuration for remote HTTP client.
 #[napi(object)]
 #[derive(Debug)]
@@ -141,6 +143,34 @@ impl From<TlsConfig> for lancedb::remote::TlsConfig {
     }
 }
 
+/// Options for the persistent OAuth token cache.
+///
+/// The cache is opt-in: it is only used when set as `tokenCache` on
+/// `OAuthConfig`. Only refresh tokens are persisted, in a private directory
+/// with owner-only permissions, so short-lived processes can reuse an
+/// authenticated session instead of re-prompting on every start.
+#[napi(object)]
+#[derive(Clone, Debug, Default)]
+pub struct TokenCacheOptions {
+    /// Directory that holds cached credentials. Defaults to
+    /// `$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+    /// or `%LOCALAPPDATA%\lancedb\oauth` on Windows. The directory is created
+    /// with owner-only permissions (`0700`) when missing.
+    pub cache_dir: Option<String>,
+    /// How long to wait for the cross-process refresh lock before failing,
+    /// in seconds (default: 30).
+    pub lock_timeout_secs: Option<u32>,
+}
+
+impl From<TokenCacheOptions> for lancedb::remote::TokenCacheOptions {
+    fn from(options: TokenCacheOptions) -> Self {
+        Self {
+            cache_dir: options.cache_dir.map(std::path::PathBuf::from),
+            lock_timeout_secs: options.lock_timeout_secs.map(|secs| secs as u64),
+        }
+    }
+}
+
 /// OAuth configuration for LanceDB authentication.
 ///
 /// This is the generated napi-rs binding shape. TypeScript users should prefer
@@ -158,16 +188,26 @@ pub struct OAuthConfig {
     /// OAuth scopes to request. For Azure managed identity, exactly one scope
     /// or resource is required. For example: `["api://{app_id}/.default"]`
     pub scopes: Vec<String>,
-    /// Authentication flow: "client_credentials" or "azure_managed_identity"
+    /// Authentication flow: "client_credentials", "authorization_code",
+    /// "device_code", or "azure_managed_identity"
     pub flow: Option<String>,
     /// Client secret (required for client_credentials).
     pub client_secret: Option<String>,
+    /// Loopback redirect URI for authorization_code.
+    pub redirect_uri: Option<String>,
+    /// Port for the authorization_code loopback callback server.
+    pub callback_port: Option<u16>,
+    /// Whether authorization_code uses S256 PKCE (default: true).
+    pub use_pkce: Option<bool>,
     /// Client ID for user-assigned managed identity (azure_managed_identity).
     pub managed_identity_client_id: Option<String>,
     /// Seconds before expiry to trigger proactive refresh (default: 300).
     /// Keep this well below the token TTL; if it is greater than or equal to
     /// the TTL, each request refreshes the token.
     pub refresh_buffer_secs: Option<u32>,
+    /// Opt in to the persistent token cache so short-lived processes reuse
+    /// one session. Only refresh tokens are persisted.
+    pub token_cache: Option<TokenCacheOptions>,
 }
 
 impl std::fmt::Debug for OAuthConfig {
@@ -181,11 +221,15 @@ impl std::fmt::Debug for OAuthConfig {
                 "client_secret",
                 &self.client_secret.as_deref().map(|_| "<redacted>"),
             )
+            .field("redirect_uri", &self.redirect_uri)
+            .field("callback_port", &self.callback_port)
+            .field("use_pkce", &self.use_pkce)
             .field(
                 "managed_identity_client_id",
                 &self.managed_identity_client_id,
             )
             .field("refresh_buffer_secs", &self.refresh_buffer_secs)
+            .field("token_cache", &self.token_cache)
             .finish()
     }
 }
@@ -194,10 +238,22 @@ impl TryFrom<OAuthConfig> for lancedb::remote::oauth::OAuthConfig {
     type Error = Error;
 
     fn try_from(config: OAuthConfig) -> Result<Self, Self::Error> {
-        use lancedb::remote::oauth::OAuthFlow;
+        use lancedb::remote::oauth::{AuthorizationCodeOptions, OAuthFlow};
 
         let flow = match config.flow.as_deref().unwrap_or("client_credentials") {
             "client_credentials" => OAuthFlow::ClientCredentials,
+            "authorization_code" => {
+                let mut options =
+                    AuthorizationCodeOptions::new().use_pkce(config.use_pkce.unwrap_or(true));
+                if let Some(redirect_uri) = config.redirect_uri {
+                    options = options.redirect_uri(redirect_uri);
+                }
+                if let Some(callback_port) = config.callback_port {
+                    options = options.callback_port(callback_port);
+                }
+                OAuthFlow::AuthorizationCode(options)
+            }
+            "device_code" => OAuthFlow::DeviceCode,
             "azure_managed_identity" => OAuthFlow::AzureManagedIdentity {
                 client_id: config.managed_identity_client_id,
             },
@@ -215,10 +271,115 @@ impl TryFrom<OAuthConfig> for lancedb::remote::oauth::OAuthConfig {
             scopes: config.scopes,
             flow,
             refresh_buffer_secs: config.refresh_buffer_secs.map(|v| v as u64),
+            token_cache: config.token_cache.map(Into::into),
         })
     }
 }
 
+/// Safe, non-secret view of a cached OAuth session, returned by
+/// `OAuthSession.status()` and `OAuthSession.login()`.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct SessionStatus {
+    /// Whether a cached session exists that can obtain tokens without
+    /// interactive authentication.
+    pub refreshable: bool,
+    /// Canonical issuer URL of the cached session.
+    pub issuer_url: String,
+    /// Client ID of the cached session.
+    pub client_id: String,
+    /// Canonical (sorted, de-duplicated) scopes of the cached session.
+    pub scopes: Vec<String>,
+    /// Flow that produced the cached session.
+    pub flow: String,
+    /// When the cached session was obtained, as Unix seconds.
+    pub obtained_at: Option<f64>,
+}
+
+/// Result of `OAuthSession.logout()`.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct SessionLogout {
+    /// Whether a cached credential was removed. `false` means no matching
+    /// session was cached; logout is idempotent.
+    pub removed: bool,
+}
+
+/// Explicit OAuth session lifecycle for the persistent token cache: eager
+/// `login`, non-secret `status`, and local `logout`.
+///
+/// A session is built from the same `OAuthConfig` used to connect (including
+/// its `tokenCache` options). A connection created with the same
+/// configuration shares the cache, so logging in here prepares tokens for
+/// later processes without any database request.
+#[napi]
+pub struct OAuthSession {
+    inner: lancedb::remote::OAuthSession,
+}
+
+#[napi]
+impl OAuthSession {
+    /// Create a session manager for the given OAuth configuration.
+    ///
+    /// The configuration must enable `tokenCache` options and use a flow that
+    /// supports persistent sessions (authorization code or device code).
+    #[napi(constructor)]
+    pub fn new(config: OAuthConfig) -> napi::Result<Self> {
+        let config: lancedb::remote::oauth::OAuthConfig = config.try_into().default_error()?;
+        let inner = lancedb::remote::OAuthSession::new(config).default_error()?;
+        Ok(Self { inner })
+    }
+
+    /// Eagerly run the configured authentication flow and store the session.
+    ///
+    /// A successful login always replaces any prior cached session for this
+    /// identity; if the provider does not issue a refresh token (for example
+    /// without `offline_access`), the previous record is removed and the
+    /// status reports `refreshable == false`.
+    #[napi(catch_unwind)]
+    pub async fn login(&self) -> napi::Result<SessionStatus> {
+        let status = self.inner.login().await.default_error()?;
+        Ok(SessionStatus::from(status))
+    }
+
+    /// Report whether a matching cached session exists, with safe metadata.
+    ///
+    /// This never contacts the identity provider and never exposes token
+    /// values.
+    #[napi(catch_unwind)]
+    pub async fn status(&self) -> napi::Result<SessionStatus> {
+        let status = self.inner.status().await.default_error()?;
+        Ok(SessionStatus::from(status))
+    }
+
+    /// Remove the matching local cached credential.
+    ///
+    /// This only deletes the local cache entry. It does not revoke the
+    /// refresh token with the provider and does not sign out of a browser
+    /// SSO session. Repeated calls succeed; `removed` reports whether a
+    /// credential existed.
+    #[napi(catch_unwind)]
+    pub async fn logout(&self) -> napi::Result<SessionLogout> {
+        let logout = self.inner.logout().await.default_error()?;
+        Ok(SessionLogout {
+            removed: logout.removed,
+        })
+    }
+}
+
+impl From<lancedb::remote::SessionStatus> for SessionStatus {
+    fn from(status: lancedb::remote::SessionStatus) -> Self {
+        Self {
+            refreshable: status.refreshable,
+            issuer_url: status.issuer_url,
+            client_id: status.client_id,
+            scopes: status.scopes,
+            flow: status.flow,
+            obtained_at: status.obtained_at.map(|secs| secs as f64),
+        }
+    }
+}
+
 impl From<ClientConfig> for lancedb::remote::ClientConfig {
     fn from(config: ClientConfig) -> Self {
         Self {
@@ -252,8 +413,12 @@ mod tests {
             scopes: vec!["scope".to_string()],
             flow: Some("typo".to_string()),
             client_secret: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
             managed_identity_client_id: None,
             refresh_buffer_secs: None,
+            token_cache: None,
         };
 
         let err = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap_err();
@@ -272,12 +437,67 @@ mod tests {
             scopes: vec!["scope".to_string()],
             flow: Some("client_credentials".to_string()),
             client_secret: Some("super-secret".to_string()),
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
             managed_identity_client_id: None,
             refresh_buffer_secs: None,
+            token_cache: None,
         };
 
         let debug = format!("{config:?}");
         assert!(!debug.contains("super-secret"));
         assert!(debug.contains("client_secret: Some(\"<redacted>\")"));
     }
+
+    #[test]
+    fn test_authorization_code_conversion_preserves_options() {
+        let config = OAuthConfig {
+            issuer_url: "https://issuer.example.com".to_string(),
+            client_id: "client-id".to_string(),
+            scopes: vec!["openid".to_string()],
+            flow: Some("authorization_code".to_string()),
+            client_secret: Some("secret".to_string()),
+            redirect_uri: Some("http://127.0.0.1:9000/callback".to_string()),
+            callback_port: Some(9000),
+            use_pkce: Some(false),
+            managed_identity_client_id: None,
+            refresh_buffer_secs: None,
+            token_cache: None,
+        };
+
+        let converted = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap();
+        let lancedb::remote::oauth::OAuthFlow::AuthorizationCode(options) = converted.flow else {
+            panic!("expected authorization code flow");
+        };
+        assert_eq!(
+            options.redirect_uri.as_deref(),
+            Some("http://127.0.0.1:9000/callback")
+        );
+        assert_eq!(options.callback_port, Some(9000));
+        assert!(!options.use_pkce);
+    }
+
+    #[test]
+    fn test_device_code_conversion() {
+        let config = OAuthConfig {
+            issuer_url: "https://issuer.example.com".to_string(),
+            client_id: "client-id".to_string(),
+            scopes: vec!["openid".to_string()],
+            flow: Some("device_code".to_string()),
+            client_secret: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
+            managed_identity_client_id: None,
+            refresh_buffer_secs: None,
+            token_cache: None,
+        };
+
+        let converted = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap();
+        assert!(matches!(
+            converted.flow,
+            lancedb::remote::oauth::OAuthFlow::DeviceCode
+        ));
+    }
 }

nodejs/typedoc.json

@@ -4,7 +4,8 @@
     "lancedb/native.d.ts:VectorQuery",
     "lancedb/native.d.ts:TakeQuery",
     "lancedb/native.d.ts:RecordBatchIterator",
-    "lancedb/native.d.ts:NativeMergeInsertBuilder"
+    "lancedb/native.d.ts:NativeMergeInsertBuilder",
+    "lancedb/native.d.ts:TokenCacheOptions"
   ],
   "useHTMLEncodedBrackets": true,
   "useCodeBlocks": true,