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>

docs/src/js/classes/OAuthSession.md

@@ -0,0 +1,105 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / OAuthSession
+
+# Class: OAuthSession
+
+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](../interfaces/OAuthConfig.md) 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();
+```
+
+## Constructors
+
+### new OAuthSession()
+
+```ts
+new OAuthSession(config): OAuthSession
+```
+
+Create a session manager for the given OAuth configuration.
+
+#### Parameters
+
+* **config**: [`OAuthConfig`](../interfaces/OAuthConfig.md)
+
+#### Returns
+
+[`OAuthSession`](OAuthSession.md)
+
+## Methods
+
+### login()
+
+```ts
+login(): Promise<SessionStatus>
+```
+
+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`.
+
+#### Returns
+
+`Promise`&lt;[`SessionStatus`](../interfaces/SessionStatus.md)&gt;
+
+***
+
+### logout()
+
+```ts
+logout(): Promise<SessionLogout>
+```
+
+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.
+
+#### Returns
+
+`Promise`&lt;[`SessionLogout`](../interfaces/SessionLogout.md)&gt;
+
+***
+
+### status()
+
+```ts
+status(): Promise<SessionStatus>
+```
+
+Report whether a matching cached session exists, with safe metadata.
+
+This never contacts the identity provider and never exposes token values.
+
+#### Returns
+
+`Promise`&lt;[`SessionStatus`](../interfaces/SessionStatus.md)&gt;