feat(core): OIDC sign-in via device flow (RFC 8628)

README.md

@@ -385,6 +385,106 @@ try (QuestDB db = QuestDB.connect("wss::addr=localhost:9000;tls_verify=unsafe_of
 }
 ```
 
+### OIDC Sign-In (Device Flow)
+
+For QuestDB Enterprise instances secured with OIDC, `OidcDeviceAuth` signs a user in interactively using the [OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628). It works from environments that have no local browser — a remote notebook kernel, a container, a headless job — because the user authorizes on any device (laptop or phone) while the process only makes outbound calls to the identity provider.
+
+On first use it prints a verification URL and a short code, and opens the URL in your default browser when one is available; authorize there (or open the URL on any device, such as your phone), enter the code, and the token is cached in memory and refreshed silently on later calls.
+
+```java
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.cutlass.auth.OidcDeviceAuth;
+
+// Discover the client id, scope and endpoints from the QuestDB server's /settings:
+try (OidcDeviceAuth auth = OidcDeviceAuth.fromQuestDB("https://questdb.example.com:9000")) {
+    auth.signIn(); // sign in once: prompts on first use, then caches and refreshes
+
+    // The provider is shared by the ingest and query pools. It is queried for
+    // every initial WebSocket upgrade and reconnect, so both pools follow token
+    // rotation without putting a credential in the configuration string.
+    try (QuestDB db = QuestDB.connect(
+            "wss::addr=questdb.example.com:9000;",
+            auth::getToken)) {
+        try (Sender sender = db.borrowSender()) {
+            sender.table("trades")
+                    .symbol("symbol", "ETH-USD")
+                    .doubleColumn("price", 2615.54)
+                    .atNow();
+        }
+        // db.borrowQuery() uses the same provider for query connections.
+    }
+}
+```
+
+For a standalone sender, use `httpTokenProvider(auth::getToken)` for the same rotating-token behavior. A fixed `httpToken(token)` or `token=` connect-string value captures the token once, so a client that reconnects after that token expires starts failing authentication. Hand rotating credentials to the provider API, not a `Sender.fromConfig(...)` string or the `QDB_CLIENT_CONF` environment variable, which are easily logged, persisted, or left in shell history.
+
+`getToken()` sits on a hot path — it is called once per ILP flush and once per WebSocket upgrade or reconnect — so a credential failure is rate-limited rather than retried on every call. When a silent refresh fails, `getToken()` does not attempt another one for 5 seconds: calls inside that window fail immediately, asking for an interactive `signIn()`, instead of hitting the identity provider again. Without that guard a producer retrying its rows would drive one token-endpoint round trip per flush, blocking the producer thread for each one and hitting the provider hard enough to trip its rate limits and lengthen the very outage being retried. Only a real refresh attempt arms the guard, and an explicit `signIn()` or `clearCache()` clears it outright. It is deliberately short — a stampede guard, not a circuit breaker — so a credential that comes back within seconds is picked up on the first call after the window rather than on the first call after it recovers.
+
+By default the prompt prints the verification URL and code to `System.out` **and** tries to open the URL in your default browser. The browser open is best-effort: it only opens an `http(s)` URL, is skipped on a headless host or a JVM without the `java.desktop` module, and never blocks sign-in (the client declares `requires static java.desktop`, so the module is optional at run time and its absence can never break module resolution; a modular application therefore gets the browser launch only when `java.desktop` is in its own module graph) — the URL and code are always printed too, so a remote or browserless process still works. To disable the browser launch for a whole process (a server, automation, CI), set the system property `-Dquestdb.client.oidc.open.browser=false`. To print only (no browser) for a single client, pass `DeviceCodePrompt.SYSTEM_OUT`; to render the challenge yourself (a clickable link or QR code in a notebook), pass any `DeviceCodePrompt`:
+
+```java
+// print only, do not open a browser:
+try (OidcDeviceAuth auth = OidcDeviceAuth.fromQuestDB(
+        "https://questdb.example.com:9000",
+        new OidcDeviceAuth.DiscoveryOptions().prompt(DeviceCodePrompt.SYSTEM_OUT))) {
+    auth.signIn();
+}
+```
+
+The same token can be presented to QuestDB over any auth path the server already validates:
+
+- **REST API:** send it as an `Authorization: Bearer <token>` header (`auth.getAuthorizationHeaderValue()` returns the full value).
+- **PG-wire:** connect as user `_sso` with the token as the password (requires `acl.oidc.pg.token.as.password.enabled=true` on the server).
+
+To configure the identity provider explicitly instead of discovering it from the server:
+
+```java
+OidcDeviceAuth auth = OidcDeviceAuth.builder()
+        .clientId("questdb")
+        .deviceAuthorizationEndpoint("https://idp.example.com/as/device_authz.oauth2")
+        .tokenEndpoint("https://idp.example.com/as/token.oauth2")
+        .scope("openid groups")
+        .groupsInToken(true) // matches acl.oidc.groups.encoded.in.token on the server
+        .build();
+```
+
+Discovery via `fromQuestDB(...)` reads the OIDC client id, scope, audience and endpoints from the server's `/settings`, and the identity provider's client must have the device authorization grant enabled. When the server does not advertise its device authorization endpoint (today's servers), pin the identity provider by its issuer so the client can discover the endpoint from the issuer's `.well-known/openid-configuration` document:
+
+```java
+try (OidcDeviceAuth auth = OidcDeviceAuth.fromQuestDB(
+        "https://questdb.example.com:9000",
+        new OidcDeviceAuth.DiscoveryOptions().issuer("https://idp.example.com"))) {
+    auth.signIn();
+}
+```
+
+The identity provider's device authorization and token endpoints must use `https` — a loopback endpoint (`localhost` or `127.0.0.0/8`) may use `http`, since the request never leaves the host — so the device code and refresh token are never sent in cleartext. `allowInsecureTransport(true)` relaxes only the QuestDB `/settings` link (for local development against an `http` QuestDB server), e.g. `OidcDeviceAuth.fromQuestDB(url, new OidcDeviceAuth.DiscoveryOptions().allowInsecureTransport(true))`; it never relaxes the identity provider endpoints, matching the Python client.
+
+`fromQuestDB(...)` takes the identity provider endpoints from the server's unauthenticated `/settings`, so it trusts that server to designate where you sign in: a spoofed, compromised, or man-in-the-middled server could redirect the sign-in to an attacker-controlled identity provider. Only use it against a server you trust, reached over `https`. Passing an issuer hardens this: the token and device authorization endpoints are then pinned to the issuer's origin (and, when the issuer has a path, an endpoint advertised by `/settings` must also be under that path — so a tampered `/settings` cannot redirect to a different tenant on a path-based provider such as Keycloak `…/realms/{realm}`), and an endpoint outside it is rejected; the issuer itself comes from you out of band, so a tampered `/settings` cannot move it. When the server is not trusted, configure the identity provider explicitly with `OidcDeviceAuth.builder()` (optionally with `.issuer(...)`) instead of discovering it.
+
+#### Persisting the Token Across Restarts
+
+By default the token lives in memory only, so a process that restarts has to run the device flow again. Pass a `TokenStore` to persist it; the restarted process then resumes from the saved refresh token — a silent call to the token endpoint — instead of prompting the user again:
+
+```java
+import io.questdb.client.cutlass.auth.FileTokenStore;
+
+try (OidcDeviceAuth auth = OidcDeviceAuth.fromQuestDB(
+        "https://questdb.example.com:9000",
+        new OidcDeviceAuth.DiscoveryOptions().tokenStore(FileTokenStore.atDefaultLocation()))) {
+    auth.signIn(); // prompts the first time; after a restart it refreshes silently from the saved token
+}
+```
+
+`FileTokenStore.atDefaultLocation()` writes one file per OIDC configuration under `${user.home}/.questdb/oidc-tokens/` (override the directory with the `questdb.client.oidc.token.store.dir` system property). The file name is a hash of the endpoints, client id, scope, audience and groups-in-token mode — the *configuration*, not the person who signed in through it, since none of those fields names a subject. Entries for different servers, providers or client configurations therefore stay separate, but **two people signing in through the same configuration share one entry**: whoever signs in last overwrites the previous token, so a store represents a single active login. If more than one application user has to be signed in at the same time, give each their own store — `FileTokenStore.at(dir)` on a per-user directory, or a per-user `questdb.client.oidc.token.store.dir` — rather than relying on the file name to separate them. The default location is already per OS user, so this only arises when one OS user (a shared service account, a multi-tenant process) signs in as several people. After a restart, `getToken()` also works as the first call — no explicit `signIn()` needed — which suits a long-lived `Sender` built with `httpTokenProvider(auth::getToken)`. `clearCache()` removes the persisted entry and forces a fresh sign-in next time.
+
+A store read that *throws* — an unreadable file after a `chmod` or a uid change in a container, `EIO`/`ESTALE` on an NFS home — is not fatal and does not disable persistence for the life of the process, but it is not retried on every call either, since `getToken()` would otherwise pay a blocking file open and a `WARN` line per ILP flush, forever. The first failure is retried immediately, so a one-shot fault (notably a carried interrupt flag, which makes the channel underneath `FileTokenStore` throw on a thread that merely carries it) recovers on the next call; each consecutive failure after that backs off 5 seconds, doubling to a 60 second cap. A store that simply has nothing to return is unaffected — `load` reports that by returning `null` rather than by throwing, and the client stops asking.
+
+The token is stored as **plaintext JSON protected by file permissions** — `0600` file, `0700` directory on POSIX systems (Linux, macOS), the same approach `gcloud`, `aws` and `gh` take. On Windows these POSIX permissions cannot be enforced, so the file currently relies on the user-profile directory's default ACL (owner-only ACL hardening is a follow-up); the client logs a one-line warning through SLF4J at `WARN` the first time it cannot enforce them (the library ships `slf4j-api` only, so this - and every other client warning - is discarded unless your application supplies an SLF4J binding). Enabling persistence therefore writes a long-lived refresh token to disk: anyone who can read the file holds a credential until it expires or is revoked. To encrypt it at rest, supply your own `TokenStore` (backed by an OS keychain or a secrets manager) instead of `FileTokenStore`. A persisted file is treated as untrusted input on load, but it is **not cryptographically authenticated** — there is no MAC or signature over its contents. Anyone who can write the file can therefore substitute a well-formed entry of their own, and the client will adopt it and present those tokens: the file permissions, not the file format, are what protect it. What the load path rejects is corruption and mix-ups rather than forgery — an oversized, malformed or unparseable file; an entry whose recorded client id, endpoints, scope, audience or groups-in-token mode does not match the identity being loaded; an entry carrying no usable token; and a token with control or non-ASCII characters, which is never placed on the wire — with the recorded expiry and lifetime clamped rather than trusted. In each case the client falls back to a refresh or an interactive sign-in. On POSIX the container is checked too: if the directory was writable by other local users, it is tightened back to `0700` and **every** entry in it is discarded — not just the one being read, since the tightening is what destroys the evidence, so anything left behind would look protected to the next load. Each identity then signs in again. Inside those permissions, though, the client cannot tell a planted credential from its own.
+
+`FileTokenStore` is safe to share between processes that sign in as the same identity: each update is written atomically (so a concurrent reader never sees a half-written credential), and when the identity provider rotates the refresh token on each refresh, the read-refresh-write is serialized across processes with a lock file so they do not race each other into an unnecessary re-prompt. The lock file's staleness is judged by its modification time, so this coordination assumes the processes share a clock — a single machine, or machines with synchronized clocks; under significant clock skew (for example a store directory on NFS shared across hosts) a live lock can be mis-judged stale or a dead one never expire. `clearCache()` removes the persisted entry under the same lock, but across processes it is best-effort: a peer that still holds a live in-memory token may legitimately re-persist afterwards (it always forces a fresh sign-in for the calling process).
+
 ### Explicit Timestamps
 
 ```java

core/src/main/java/io/questdb/client/HttpTokenProvider.java

@@ -0,0 +1,109 @@
+/*+*****************************************************************************
+ *     ___                  _   ____  ____
+ *    / _ \ _   _  ___  ___| |_|  _ \| __ )
+ *   | | | | | | |/ _ \/ __| __| | | |  _ \
+ *   | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+ *    \__\_\\__,_|\___||___/\__|____/|____/
+ *
+ *  Copyright (c) 2014-2019 Appsicle
+ *  Copyright (c) 2019-2026 QuestDB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
+package io.questdb.client;
+
+import io.questdb.client.cutlass.line.LineSenderException;
+import io.questdb.client.std.Chars;
+
+/**
+ * Supplies an HTTP authentication token to a {@link Sender} or pooled {@link QuestDB} connection on
+ * demand, so a provider returning a freshly refreshed token - e.g. {@code OidcDeviceAuth::getToken}
+ * - keeps long-lived ingest and query connections authenticated as the token rotates, without
+ * rebuilding them. An HTTP sender calls {@link #getToken()} as it builds each request; WebSocket
+ * ingest and query clients call it once per connection handshake, on the initial connect and again
+ * on every reconnect.
+ * <p>
+ * {@link #getToken()} runs on HTTP flush and pooled connection/reconnection paths. Different pooled
+ * connections may call it concurrently, so implementations must be thread-safe. It must return
+ * promptly and must not block on interactive input. A quick silent token refresh is fine, but it must
+ * not start an interactive sign-in; a provider that coordinates a shared token store across processes
+ * (for example {@code OidcDeviceAuth} with a {@code FileTokenStore}) may add a brief, bounded wait to
+ * acquire that store's cross-process lock before such a refresh, which still counts as a quick silent
+ * refresh. Note that "quick" bounds the interactive wait, not the network: the silent refresh is a
+ * synchronous HTTP round-trip to the token endpoint, and its connection phase (DNS, TCP connect, TLS)
+ * is bounded by the client timeout as well for the bundled {@code OidcDeviceAuth}, leaving only DNS
+ * resolution to the OS. A provider that builds its own HTTP client should bound its connect and TLS
+ * handshake likewise, or a black-holed token endpoint stalls a flush for the OS connect timeout. An exception from {@link #getToken()} fails the
+ * in-flight flush (HTTP) or the connection attempt (WebSocket).
+ *
+ * @see QuestDB#connect(CharSequence, HttpTokenProvider)
+ * @see QuestDBBuilder#httpTokenProvider(HttpTokenProvider)
+ * @see Sender.LineSenderBuilder#httpTokenProvider(HttpTokenProvider)
+ */
+@FunctionalInterface
+public interface HttpTokenProvider {
+    /**
+     * Validates a token returned by {@link #getToken()} before the client writes it into an
+     * {@code Authorization: Bearer} header.
+     * <p>
+     * Callers must pass a value that cannot change between this check and the write that follows it.
+     * {@code getToken()} may return a reused buffer, so validating the provider's sequence and then
+     * re-reading it to build the header reads it twice: a mutation in between passes the check and
+     * splices the mutated bytes - a CR/LF among them - into the header. Snapshot with
+     * {@link Object#toString()} first, then validate and send the snapshot. Every call site in this
+     * library does.
+     * <p>
+     * Rejects a null, empty or blank token, and any token
+     * carrying a control or non-ASCII character (outside {@code 0x20}-{@code 0x7e}): a real bearer
+     * token is printable ASCII, so a stray CR/LF (which would inject into the HTTP request line) or a
+     * non-ASCII byte (silently truncated to one byte by the ASCII header writer, yielding a corrupt
+     * credential the server only answers with 401) is refused rather than sent. The token itself is
+     * never placed in the exception message - it is the secret this guards.
+     *
+     * @param token the token returned by a provider
+     * @throws LineSenderException if the token is null, empty, blank, or carries a control or
+     *                             non-ASCII character
+     */
+    static void validateToken(CharSequence token) {
+        if (Chars.isBlank(token)) {
+            throw new LineSenderException("token provider returned a null or empty token");
+        }
+        for (int i = 0, n = token.length(); i < n; i++) {
+            char c = token.charAt(i);
+            if (c < 0x20 || c > 0x7e) {
+                throw new LineSenderException("token provider returned a token containing a control or non-ASCII character; refusing to send it as a credential");
+            }
+        }
+    }
+
+    /**
+     * Returns the current HTTP authentication token, without the {@code "Bearer "} prefix (the client
+     * adds it). Must not return null or empty, and must contain only printable ASCII (no control or
+     * non-ASCII characters) - the client splices the value verbatim into an {@code Authorization:
+     * Bearer} header and rejects a token that violates this (see {@link #validateToken(CharSequence)}).
+     * <p>
+     * Returning a reused, mutable {@link CharSequence} - the idiomatic zero-allocation style - is
+     * supported and expected: the client re-validates every pulled token rather than trusting instance
+     * identity, so a buffer whose contents changed since the last call is checked again. What an
+     * implementation must not do is mutate a sequence it has already returned <i>while the client is
+     * still reading it</i>. The client snapshots each returned value before validating it, so a
+     * concurrent mutation cannot slip past the check into the header; an implementation that mutates
+     * mid-call is nonetheless racing with a reader and may see its own token dropped for the one the
+     * snapshot captured. Mutate between calls, not during one.
+     *
+     * @return the current HTTP authentication token
+     */
+    CharSequence getToken();
+}