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

[glasstiger]

Adds interactive OIDC sign-in to the Java client using the OAuth 2.0 Device Authorization Grant (RFC 8628). A process with no local browser — a remote notebook kernel, a container, a headless job — can sign a human in against QuestDB Enterprise: 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, by default, also tries to open the URL in a local browser); once the user authorizes, the token is cached in memory and refreshed silently on later calls.

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

    // Pass a token provider, not a fixed string: the sender pulls a freshly refreshed token on each
    // request, so a long-lived sender keeps working as the token rotates. getToken() refreshes
    // silently and never prompts on the flush path.
    try (Sender sender = Sender.builder(Sender.Transport.HTTP)
            .address("questdb.example.com:9000")
            .enableTls()
            .httpTokenProvider(auth::getToken)
            .build()) {
        sender.table("trades")
                .symbol("symbol", "ETH-USD")
                .doubleColumn("price", 2615.54)
                .atNow();
    }
}

What's new

OidcDeviceAuth (io.questdb.client.cutlass.auth) — runs the flow and owns the token:

• OidcDeviceAuth.fromQuestDB(url) discovers the client id, scope, audience and IdP endpoints from the server's unauthenticated /settings; OidcDeviceAuth.fromQuestDB(url, DiscoveryOptions) adds an identity-provider pin (.issuer(...)), a TLS config, an allowInsecureTransport opt-in, and the prompt (see Discovery and trust below); OidcDeviceAuth.builder() configures the identity provider explicitly.
• signIn() signs in interactively on first use, then serves a cached token and refreshes it silently; getToken() never prompts and never waits behind an interactive sign-in (safe on a request/flush path); getAuthorizationHeaderValue() returns the full Bearer … value; clearCache() drops the cached token so the next signIn() re-signs-in; close() cancels an in-flight sign-in (observed between polls, so it can take up to one HTTP request timeout to return). Calls are serialized by a ReentrantLock; getToken() uses tryLock and fails fast rather than wait behind an interactive sign-in. Token state is in-memory only by default; pass a TokenStore to persist it across restarts (see Token persistence below).

Sender integration — new HttpTokenProvider interface and Sender.builder(...).httpTokenProvider(auth::getToken). The sender pulls a freshly refreshed token on every request, so a long-lived sender keeps working as the token rotates — unlike a fixed httpToken(...), which is captured once and eventually starts returning 401s. Mutually exclusive with httpToken/httpUsernamePassword. Supported over HTTP and WebSocket transport (a WebSocket sender re-queries the provider on every (re)connect/upgrade); rejected for TCP and UDP. The two transports differ in mechanism but both keep the producer alive across a sustained token outage: over HTTP a failed pull leaves the request token-pending and is retried on the next row; over WebSocket the token must be obtainable when build() runs (the initial handshake fails fast otherwise), after which a pull that keeps failing on later reconnects is retried indefinitely, with the buffered rows held in store-and-forward, until a token is available again — a token outage does not terminate a running WebSocket sender, just as a persistent transport reconnect failure does not (store-and-forward Invariant B). The first pull is deferred off the build path to the first row, so the documented construct → signIn() → send ordering works and a provider that throws leaves the request retriable instead of corrupting the sender.

QWP egress query client — QwpQueryClient.withBearerTokenProvider(HttpTokenProvider) accepts the same on-demand provider, so OidcDeviceAuth::getToken plugs into the egress query path as well as ingress. The provider is queried at every WebSocket upgrade — the initial connect() and each failover reconnect — so a long-lived query client follows token rotation; each returned token is validated before it reaches the header, and a provider that throws fails that connection attempt (matching the ingress sender). Mutually exclusive with withBearerToken/withBasicAuth.

DeviceCodePrompt / DeviceAuthorizationChallenge — how the verification URL and user code are shown. The default, DeviceCodePrompt.openBrowser(), prints the instructions to System.out and also tries to open the verification URL in the local default browser; the browser open is best-effort (skipped on a headless JVM, without the java.desktop module, or for a non-http(s) URL, and disabled by -Dquestdb.client.oidc.open.browser=false) and never blocks or fails sign-in. Use DeviceCodePrompt.SYSTEM_OUT to print only, or supply your own to render a clickable link or a QR code, e.g. in a notebook.

audience — builder().audience(...) / discovered from acl.oidc.audience. When set, the audience parameter is sent on the device-authorization and refresh requests, for providers that require it to stamp the aud claim QuestDB expects.

The token can be presented to QuestDB over any auth path the server already validates:

• REST / ingestion — Authorization: Bearer <token>.
• PG-wire — connect as _sso with the token as the password (requires acl.oidc.pg.token.as.password.enabled=true on the server).

Discovery and trust

fromQuestDB(...) takes the IdP endpoints from the server's unauthenticated /settings, so by default it trusts that server to designate where the user signs in: a spoofed, compromised, or man-in-the-middled server could otherwise redirect the sign-in — and the long-lived refresh token — to an attacker-controlled identity provider. An optional DiscoveryOptions.issuer(...) pin addresses this, and also covers servers that do not advertise a device-authorization endpoint. The pin separates two sources of endpoints and trusts them differently — an endpoint the untrusted /settings advertised is constrained to the issuer, while an endpoint read from the identity provider's own .well-known is trusted wherever the provider hosts it:

• .well-known discovery fallback. Current servers do not advertise the device-authorization endpoint. When it (and/or the token endpoint) is missing, a pinned issuer reads it from {issuer}/.well-known/openid-configuration. The discovery origin comes only from the caller-supplied issuer, never from a /settings-supplied value, so a tampered /settings cannot choose where discovery — and the credential POSTs it resolves — are aimed. Without a pin, discovery is refused rather than guessed.
• Co-location pin. validateEndpointOrigins, enforced on every construction path (discovery and the explicit builder()), requires the token and device-authorization endpoints to share one origin (RFC 8628 co-locates them on a single authorization server), so a tampered /settings or discovery document cannot siphon one of the two credential POSTs off to a different origin.
• /settings-advertised endpoints are pinned to the issuer. An endpoint the untrusted /settings response supplied must sit on the pinned issuer's origin, and — when the issuer has a path — under that path (compared segment by segment, rejecting ./.., percent-encoded traversal, and a percent-encoded path separator such as %2f or %5c, at every decode level). The path check matters for a path-based provider that shares one origin per tenant (e.g. a Keycloak realm path /realms/<realm>), where the origin check alone cannot stop a tampered /settings from steering credentials to a sibling tenant. The issuer is supplied out of band and cannot be forged.
• IdP-discovered endpoints are trusted where the issuer hosts them. An endpoint read from the issuer's own .well-known is neither origin-pinned nor path-scoped: that document is fetched from the pinned issuer origin and is authoritative for wherever the provider hosts its endpoints. This is deliberate — some providers (e.g. Google, Azure AD) serve their token and device endpoints from a different origin or path than the issuer, and discovery against them signs in normally. The co-location pin above still applies.
• Plaintext-channel pin. A /settings response fetched over plaintext http to a non-loopback host (only reachable with allowInsecureTransport) is MITM-able, so its advertised endpoints are not trusted to route credentials without an issuer pin.

Without a pin, the behaviour against an https server that advertises its endpoints is unchanged: that server is trusted, as before.

Security

• https is required by default for both the QuestDB server and the IdP endpoints; http is rejected unless the caller opts in with allowInsecureTransport(true). That opt-in relaxes only the QuestDB /settings link — the IdP device-authorization and token endpoints always require https (loopback excepted), so the device code and refresh token never cross the network in cleartext (matching the Python client).
• Tokens never leak into logs or exceptions. Only the HTTP status of a token/device response is captured; the body — which carries access, id and refresh tokens — is never retained or surfaced in a message. The captured status is validated to be exactly three digits, so a malformed or hostile status line cannot splice ANSI/control bytes into a later [httpStatus=…] echo, nor can a short all-digit status (2, 5) be misread as a 2xx/5xx class — a malformed-length status falls through to the terminal reject path.
• Untrusted IdP text is sanitized before it is shown in a prompt or an exception message: per-code-point stripping of control characters, ANSI escapes, CR/LF, and bidirectional / zero-width / Unicode-format characters (including supplementary-plane "tag" characters that arrive as surrogate pairs, and unpaired surrogates), so an attacker-influenced field cannot reorder, hide, or forge what a human reads — e.g. a right-to-left override that makes the displayed verification URL differ from the one the browser opens. A user code or verification URL that is non-empty on the wire but sanitizes to nothing is rejected (or, for verification_uri_complete, treated as absent) rather than shown as a blank line or handed to the browser launcher.
• The token itself is validated before use. The token QuestDB will actually receive — the id token when the server encodes groups in the token, the access token otherwise — is rejected if it carries a control or non-ASCII character (outside 0x20–0x7e) before it is cached, placed in the Authorization: Bearer header, or used as the PG-wire password — so a tampered or hostile identity provider cannot smuggle a CR/LF into the request the client then sends to the trusted QuestDB server. Only the served kind is checked; a stray character in the unused token kind, which never reaches the wire, no longer aborts an otherwise usable grant. (The JsonLexer change below decodes JSON escapes, which is what turns a \r/\n in a token into a real byte rather than two literal characters.)
• URLs are validated up front. Endpoint.parse rejects control characters, whitespace and display-unsafe code points anywhere in the url (so a tampered endpoint cannot inject a CR/LF into the request line or a bidi char into a log line), rejects bracketed IPv6 literals rather than mis-parsing them, rejects userinfo (user@host) — which the HTTP layer would otherwise try to connect to literally — terminates the authority at the first /, ? or # so a query or fragment is never folded into the host, and range-checks the port to 1..65535.
• Bounded against a hostile or stalled server. Response reads are capped by a 4 MiB byte limit and a monotonic (System.nanoTime) deadline that bounds the whole read — covering both a chunked response whose chunk-size line is dribbled a byte at a time and a Content-Length body dribbled through stalled TLS records, either of which previously could keep a single read running well past the deadline. After such a bounded-read abort the half-read poll connection is dropped so the next poll reconnects on a clean socket, rather than the loop spinning on the stalled response's leftover bytes until the device code expires. The device-code lifetime, the poll interval, and the token TTL are all clamped (defaults applied for absent/zero values, hard caps for absurd ones). A 429 with no OAuth error is treated as a transient back-off (a 429 that also carries a terminal error such as access_denied still aborts on the error); a transient transport failure or 5xx during polling keeps polling until the device-code deadline rather than failing the sign-in (RFC 8628; matches the Python client), while a definitive OAuth error or a terminal 4xx aborts immediately. The trade-off is that a persistently flaky network is no longer cut short by a separate error budget — it polls to the device-code deadline.

Token persistence (opt-in)

By default token state is in-memory only, so a restarted process re-runs the interactive device flow. Passing a TokenStore persists it, so the restarted process resumes from the saved refresh token (one silent token-endpoint round-trip) instead of re-prompting — getToken() then even works as the first call, with no explicit signIn().

• TokenStore SPI (io.questdb.client.cutlass.auth) — load/save/clear keyed by a non-secret TokenStoreKey (endpoints, client id, scope, audience, groups-in-token mode), plus an optional inLock hook for cross-process coordination. Wire it in with builder().tokenStore(...) or DiscoveryOptions.tokenStore(...). Persistence is best-effort: a store failure logs a warning through SLF4J at WARN and the in-memory token is used regardless — and the library ships slf4j-api with no binding, so that warning, like every other client warning, is discarded unless the application supplies one.
• FileTokenStore (the default) — one plaintext JSON file per OIDC configuration under ${user.home}/.questdb/oidc-tokens/ (override with questdb.client.oidc.token.store.dir), the refresh token protected at rest by file permissions (0600 file, 0700 directory on POSIX) rather than encryption — the same approach gcloud, aws and gh take. The file name is a SHA-256 of that configuration (endpoints, client id, scope, audience, groups-in-token mode), so it leaks neither endpoint nor client id, and different servers, providers or client configurations stay in separate files. FileTokenStore.atDefaultLocation() / FileTokenStore.at(dir).
• One store, one active login. The key names a configuration, and no field of it names a subject, so the hashed file name is not a per-person partition: two people signing in through the same configuration address the same file and the later sign-in overwrites the earlier. Signing several application users in at once needs a store each — FileTokenStore.at(dir) on a per-user directory, or a per-user questdb.client.oidc.token.store.dir — rather than a reliance on the name to separate them. The default location is per OS user already, so this only arises inside one OS user: a shared service account, or a process signing in on behalf of several people.
• Treated as untrusted on load. A persisted file is attacker-writable, so on load it is size-bounded, parsed defensively (a corrupt/oversized/garbage file is ignored, not fatal), its fingerprint re-checked against the live config (a token minted for one identity is never served for another), and the served token re-validated for control/non-ASCII characters before it can reach a header — the same CR/LF / non-ASCII rejection the device flow applies to IdP responses. A tampered far-future expiry is clamped, not trusted. A bad file degrades to a refresh or an interactive sign-in.
• Integrity and cross-process coordination. Each update is written to a temp file then atomically renamed, so a concurrent reader never sees a half-written credential. When the IdP rotates the refresh token on each refresh, the read-refresh-write is serialized across processes with an O_CREAT|O_EXCL lock file (not an OS advisory lock, which Java FileLock and Python flock cannot share); a process that cannot acquire the lock degrades to a lock-free refresh rather than stall.
• The on-disk format is a frozen cross-language contract (design/oidc-token-persistence.md): the file name, JSON schema, atomic-write and lock-file protocols are specified so the Python client (and others) can share one file.

Supporting changes

• JsonLexer now resolves JSON string escape sequences (\", \\, \/, \b \f \n \r \t, \uXXXX; lenient on malformed input), so string values arrive fully decoded. This also reaches the existing ILP error-response parser, which now sees decoded message/code/line/errorId fields.
• Response.recv(int timeout) — a default method delegating to recv(), so an implementation of this exported interface written before the overload existed keeps compiling and linking, and keeps its previous behaviour. Both implementations here override it. It bounds the whole read to the timeout in total, not per socket read, so a server that dribbles the body — the chunk-size line of a chunked response, or Content-Length bytes behind stalled TLS records — cannot keep a single read running past the caller's deadline. A non-positive timeout keeps the legacy unbounded behaviour. Every ILP flush-path body read now passes an explicit timeout — actualTimeoutMillis, the base request timeout plus the throughput extension, not the raw request_timeout — so a tuned-low request_timeout paired with request_min_throughput cannot abort a large, still-progressing chunked body. That bounds each recv() call in total rather than the body cumulatively across calls; the ILP server is trusted, unlike the identity provider, whose reads OidcDeviceAuth.parseBody additionally caps by total bytes and one monotonic deadline. A response that completes within the per-call bound is unaffected, while one that dribbles a single fragment for longer than it — previously tolerated as long as each socket read made progress — now aborts. The only no-arg recv() left is the construct-time /settings protocol-version probe, whose retry loop already catches the abort. Both flush-path consequences of that newly reachable abort are handled — see the third review round below.
• AbstractLineHttpSender plumbs the token provider through with a deferred, retriable per-request pull (a throwing or blank-returning provider leaves the request token-pending for the next row instead of corrupting the half-built request), so the very first send already carries a provider-sourced token. Its error rendering now routes every untrusted server-supplied string through putAsPrintable — the decoded JSON error body, the [http-status=…] field, and the line-protocol-version detection probe body — escaping control and Unicode format characters (bidi overrides, zero-width joiners, the BOM), so a hostile or proxied endpoint cannot reorder, hide, or forge the text shown in a LineSenderException (or spliced into a log line or terminal).
• QwpWebSocketSender sources its auth header from the token provider too, re-querying it on every connect/reconnect so a rotating token keeps a long-lived WebSocket sender authenticated.

Tradeoffs and limitations

• The origin pin behaves differently on the two construction paths. fromQuestDB(...) discovery trusts an endpoint read from the issuer's .well-known wherever the provider hosts it, so an off-origin provider (e.g. Google) signs in normally through a pinned issuer; only an endpoint the /settings response itself advertised is held to the issuer's origin and path. The explicit builder().issuer(...) pin is stricter — a plain sanity check that both supplied endpoints sit on the issuer origin — so an off-origin provider configured that way must have its issuer omitted, or its endpoints supplied to match. This matches the Python client.
• A failed token pull is handled differently per transport, but neither drops buffered rows: over HTTP it leaves the request token-pending and retries on the next row; over WebSocket the initial handshake must obtain a token at build() (it fails fast otherwise), after which a pull that keeps failing on later reconnects is retried indefinitely with the buffered rows held in store-and-forward, until a token is available again — a token outage does not terminate a running WebSocket sender (store-and-forward Invariant B). A getToken() provider that fails only transiently recovers on both transports; a long WebSocket outage grows store-and-forward (and eventually applies backpressure) rather than ending the sender.
• The co-location check requires the token and device-authorization endpoints to share an origin. A test that previously pointed the token endpoint at a dead second port to simulate an unreachable endpoint was reworked to drop a co-located connection instead (MockOidcServer.dropConnection()).
• The plaintext-channel pin's firing path is exercised end to end by reaching the loopback mock through a short-form 127.x address that the loopback classifier deliberately rejects as non-loopback. That trick relies on the OS resolver expanding the short form (BSD inet_aton, on Linux/macOS), which Windows getaddrinfo does not do, so that one end-to-end test is skipped on Windows; the loopback classifier itself is covered cross-platform.
• Persistence writes a long-lived refresh token to disk in plaintext, protected only by file permissions — anyone who can read the file holds a credential until the IdP expires or revokes it. This is why persistence is opt-in; for at-rest encryption, supply a TokenStore backed by an OS keychain or a secrets manager instead of FileTokenStore. On Windows 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 SLF4J warning at WARN the first time it cannot enforce them — which an application with no SLF4J binding never sees, so this boundary has to be read here rather than watched for at runtime.
• Two stampede guards make a credential failure sticky for a few seconds. getToken() runs once per ILP flush and once per WebSocket (re)connect, so a failing credential path would otherwise cost one token-endpoint round trip — or one blocking store read, two stack-trace fills and a WARN line — per flush, on the producer thread and under this instance's lock, which is enough to trip an identity provider's rate limits and lengthen the very outage being retried. So a silent refresh that fails is not re-attempted for 5 s: calls inside that window fail immediately with the cached-token-expired error instead of re-hitting the provider, and only a real attempt re-arms the latch, which an explicit signIn() or clearCache() clears outright. A TokenStore.load that throws is retried once immediately (a one-shot fault, notably a carried interrupt flag, must recover on the next call), then backed off 5 s, doubling to a 60 s cap; a store that simply has nothing to return reports that by returning null and is unaffected. Both are deliberately short — a stampede guard, not a circuit breaker — but the cost is that a credential which recovers inside a window is picked up on the first call after that window rather than the first call after it recovers.
• The HTTP chunk-size line is bounded where it is read. An overflowing chunk size was reading as valid framing (see the second review round below). The bound lives in AbstractChunkedResponse, which counts significant hex digits and rejects more than 15 BEFORE parsing — the only form that works, since the worst residue (10000000000000000 wrapping to zero, read as the terminal chunk) is indistinguishable from a genuine 0 afterwards. Numbers.parseHexLong keeps its two's-complement contract: ffffffffffffffff is still -1, matching parseHexInt beside it and the server-side io.questdb.std.Numbers of the same name, whose Long256 decoding depends on the wrap. io.questdb.client.std is exported, so that contract is shipped and is deliberately left alone; a caller parsing a count a remote peer chose must bound the digits itself, which is what the chunk parser now does. The javadoc says so and points at it as the worked example.
• TokenStore.inLock may now return false without running the action. An implementation that waits for its lock must make that wait interruptible and abandon it on an interrupt, because the wait can outlast a caller's shutdown budget (see the second review round below). The false return reads as "no refresh happened", which OidcDeviceAuth already handled, but a third-party TokenStore inherits the new obligation.
• A store-coordinated getToken() may briefly wait to acquire the cross-process lock before a silent refresh (a few seconds at most for FileTokenStore — the acquire budget is capped — then it proceeds without the lock). It still never waits behind an interactive sign-in; this is a quick silent refresh, not an interactive wait.
• The Response.recv(int) bound (see Supporting changes) also tightens existing, non-OIDC ILP flushes. Each flush-response body read is now bounded in total rather than re-arming its timeout per socket read, so a response that legitimately dribbles a single fragment for longer than the per-flush budget (request_timeout plus the request_min_throughput extension) — previously tolerated as long as each socket read made progress — now aborts. The bound is per recv() call, not cumulative across the whole body, so it is a ceiling on one stalled fragment rather than on the response as a whole. A healthy response is unaffected. Making that abort reachable inside flush0's retry scope had two consequences, both fixed in the third review round below rather than accepted: a drain abort after a 2xx no longer re-sends a batch the server had already committed, and a body-read abort under an error status no longer reclassifies a definitive 401/403/405 as a transport failure. The pre-existing ILP-over-HTTP at-least-once window is therefore not widened; the only observable effect is that a pathologically slow single fragment is cut short instead of tolerated indefinitely.
• A malformed HTTP response head now fails the flush instead of being retried. This is the second change in this branch that existing, non-OIDC ILP-over-HTTP users can observe (the Response.recv(int) bound above is the first). HttpHeaderParser rejects a response head past its fixed 4096-byte buffer, a malformed Content-Length, or a non-HTTP/1.x status line. Reaching one needs an intermediary — QuestDB's own /write answers 204 with a small head — but where one does, the flush now fails immediately with a non-retryable LineSenderException naming the malformed head, rather than spending the retry budget re-sending a batch the server had already answered. A healthy response is unaffected.

Tests & docs

OidcDeviceAuthTest (~123 cases) + MockOidcServer, BrowserLauncherTest, LineHttpSenderTokenProviderTest, WebSocketTokenProviderTest + TestWebSocketServer, SenderBuilderErrorApiTest, JsonLexerTest, LineHttpSenderErrorResponseTest, DisplaySafeTest, ChunkedResponseTest/ResponseTest, QwpQueryClientTokenProviderTest, FileTokenStoreTest, OidcDeviceAuthPersistenceTest, WebSocketCredentialCancellationTest, SenderPoolSfTokenProviderTest, BackgroundDrainerCredentialOutageReportTest, NumbersTest, HttpClientConstructorLeakTest; runnable OidcDeviceFlowExample / OIDCAuthExample; and README "OIDC Sign-In (Device Flow)" and "Persisting the Token Across Restarts" sections. Coverage includes:

• .well-known discovery via a pinned issuer; a discovery document that omits the device-authorization endpoint
• the co-location check rejecting split-origin endpoints; the builder().issuer(...) origin pin rejecting off-origin endpoints; a /settings-advertised endpoint rejected when off the issuer origin; an endpoint discovered from the issuer's .well-known accepted even when off the issuer origin (the Google case)
• issuer path scoping: endpoints under the issuer path accepted; a sibling realm, percent-encoded traversal, an encoded path separator (%2f), and a percent-encoded backslash (%5c) rejected
• the plaintext-channel pin requiring an issuer pin for advertised endpoints over http (firing path skipped on Windows)
• the audience parameter discovered from /settings and sent on the device and refresh requests
• token-provider support over HTTP and WebSocket (initial upgrade and re-queried per reconnect; static token / username-password still work over WebSocket); rejected for TCP/UDP; mutual exclusion with other auth; null/empty provider token rejected; deferred build-time pull; no sender corruption when the provider throws after a flush; the QWP egress query client's token provider — header synthesis, per-resolve re-query, token validation, and mutual exclusion
• a token with a control or non-ASCII character rejected rather than sent (the served kind validated); tokens never echoed in messages
• bounded reads: a stalled body and an oversized body aborting on the deadline / 4 MiB cap; a chunked body read aborting when the chunk-size line is dribbled; a bounded-read abort dropping the dirty poll connection so the next poll reconnects and signs in
• the poll model: a 429 and a transient 5xx/transport failure keep polling to the deadline; a terminal 4xx and an OAuth error fail fast (including a 429 that also carries a terminal error); slow_down growth and the 60 s interval clamp; device-code-lifetime and clock-skew clamps
• Endpoint.parse rejecting a malformed url: userinfo (user@host), a bracketed IPv6 literal, an out-of-range port, and control/whitespace/display-unsafe characters
• a malformed HTTP status code rejected on both the device-authorization and the token-poll path: a non-numeric status, and a short all-digit status (2, 5) that must not be read as a 2xx/5xx class
• display sanitizing: bidi/zero-width, lone-surrogate and supplementary-plane format characters stripped from the challenge and OAuth error; a server's JSON error body, its HTTP status field, and the protocol-version probe body with such characters escaped, not rendered raw; a user code or verification URL that sanitizes to empty rejected, and a verification_uri_complete that sanitizes to empty treated as absent
• JsonLexer escape decoding, including a \uXXXX escape split across two parse fragments, and the lenient/exotic escape arms
• getToken() failing fast while another thread holds the lock in an interactive sign-in or a silent refresh; native-memory cleanup on the error/rejection construction paths
• discovery gated on status: a /settings body and a .well-known body under an HTTP error status refused as configuration, and a malformed status rejected without echoing its bytes
• a dribbled response body under a 2xx not re-sending the batch, and under an error status still surfacing the status rather than a transport timeout
• a TokenStore throwing before its action degrading to exactly one uncoordinated refresh, and throwing after it keeping the completed refresh
• HttpClient constructor rollback at four failure points, asserted through assertMemoryLeak
• token persistence: round-trip save/load with 0600/0700 permissions and control-char JSON escaping; a corrupt, empty, oversized, schema-version-mismatched, or per-field fingerprint-mismatched file ignored; a tampered far-future expiry clamped and a CR/LF served token rejected on load; a restart serving a valid persisted token (or silently refreshing an expired one) without re-running the device flow; rotating vs non-rotating refresh write behaviour; a swallowed save not replaying a revoked token; the cross-process lock-file protocol (acquire, mutual exclusion, stale-steal, degrade); getToken() degrading to a lock-free refresh when a peer holds the lock; the HTTP-timeout cap; the file-name hash pinned as a cross-language contract

Review follow-ups

A level-3 review of this branch surfaced the issues below; all are fixed here, each production fix with a regression test proven to fail without it (see the commit history for detail).

Confirmed defects:

• Blank served token: adopt()/storeTokens() accepted a whitespace-only served token (it passed isEmpty()/hasOnlyTokenChars() vacuously), so signIn() reported success and getToken() served a blank Bearer header the server only answers with 401, never falling back. Now rejected via Chars.isBlank; a blank served kind is folded to absent so selectToken() surfaces the actionable error.
• getToken() lock contention: the unconditional tryLock() failed fast on any lock hold, so concurrent callers sharing one OidcDeviceAuth threw on every token refresh. It now waits briefly behind a peer's silent refresh (bounded by httpTimeoutMillis) and fails fast only behind an interactive sign-in.
• SYNC initial connect: a token-provider failure was treated as a transport outage and retried for the whole reconnect budget (5 min default) then wrapped. It now fails fast with the provider's own exception, matching the OFF-mode and background-reconnect paths.

Hardening and coverage:

• Discovery parsers reject array-wrapped JSON, so {"config":[{...}]} can no longer surface fields at the trusted config depth.
• The cross-process lock file is created with its owner stamp in one atomic exclusive open, removing the create-then-stamp gap a GC pause could straddle (design doc updated; the Python client must mirror it).
• The ILP token-provider request is built once per flush rather than twice. (validateToken still re-scans every pulled token by design - a provider may mutate a reused buffer between flushes - but that scan is O(token length), runs once per flush, and is dwarfed by the network round-trip.)
• Added regression tests for previously untested load-bearing guards: the parseHex4 non-ASCII guard, the raw .. issuer-path reject, the FileTokenStore size caps, the store-and-forward credential-timer reset, and the ILP flush whole-read timeout bound.
• Docs: HttpTokenProvider.getToken() now discloses the OS-bounded connect stall; TokenStore.inLock documents its no-reentrancy contract; FileTokenStore states the concurrent-refresh residual (token-family revocation on a reuse-detecting IdP) instead of understating it.

Review follow-ups (second round)

A further review round surfaced the issues below. As before, every production fix carries a regression test shown to fail without it; the commit messages record the counterfactual output for each.

Confirmed defects:

• A device grant inherited the previous user's refresh token. storeTokens() kept the current refresh token whenever a response omitted one, for refresh grants and fresh device grants alike. For a refresh that is right — RFC 6749 §6 makes the field optional and the same authorization is continuing — but a device grant is a new authorization and may be a different human. So user A's refresh fails, user B completes the device flow without a refresh token, B's access token expires, and the next silent refresh presents A's retained token and resumes as A: no prompt, no error, nothing in any log recording that the identity changed. Persisted it is worse — the refresh token is unchanged, so persistIfRotated() sees no rotation and skips the save, leaving A's whole entry on disk for the next process start to adopt. The omission policy is now grant-specific: a device grant that returns no refresh token clears it, so getToken() asks for an interactive sign-in instead. Covered end to end, including a restart over the same store.
• The token store's lock waits could not be interrupted. A credential pull owns no socket, so closeTraffic() cannot reach it; the only lever is an interrupt, sent by the send loop's connect cancellation on the foreground path and by BackgroundDrainerPool's shutdownNow() on the orphan-drainer path. Neither reached the built-in path: the in-process lock was taken with lock(), and the lock file was polled through Os.sleep, which catches InterruptedException and keeps sleeping to its own deadline. Since the acquire budget caps at 30 s — the same as the QWP shutdown budget — a sender closing while another same-identity instance held the lock burned the whole budget and then gave up on its I/O thread, delegating teardown of the native client, the cursor engine and the store-and-forward slot lock; on the drainer path it abandoned the drainer still holding the orphan slot's lock. inLock now takes the process lock interruptibly, polls with Thread.sleep, and checks for an interrupt before running the critical section. Every prior test blocked the pull in an interruptible test double, so the shipped path was untested; the new tests block it in a real OidcDeviceAuth over a real FileTokenStore whose lock a peer holds.
• An overflowing chunk size was accepted as valid framing. The guard rejected only a negative parse result, which is one of three ways an unchecked val << 4 accumulation wraps, and the least harmful — a negative size matches neither the data branch nor the terminator, so the state machine spins, which is at least visible. The other two report success with the wrong bytes: 10000000000000000 wraps to zero and reads as the terminal chunk, so the caller gets a complete-looking body that is truncated and the connection's framing is lost for the next keep-alive response, while a longer value wraps to a short positive count that mis-frames everything after it. Truncated JSON parses. The size line is chosen by the server, untrusted for a discovery or token response. The size line is now bounded in the chunk parser itself, before the parse, so all three residues are refused at the point the untrusted digits are read — see the chunk-size note in Tradeoffs.
• An orphan drainer reported a credential outage nowhere, and mislabelled it. The drainer's error sink was never wired into its drain loop, so the loop's credential-unavailable report was dispatched into a null; at initial connect the exception matched none of the typed arms and landed in the generic transport arm, whose warning says the cluster is unreachable. A revoked token therefore surfaced as a network fault while rows accumulated in store-and-forward, pointing an operator at disk sizing rather than at their credentials. The sink is now wired and the condition named. TERMINAL is filtered on the way through: on an orphan loop a terminal is the loop handing the slot back to the drainer to decide, so forwarding it would announce a dead producer for a rotating credential the next sweep accepts, and double-report every quarantine.

Exported API compatibility:

• Three public signatures had been replaced rather than added to, in packages module-info.java exports and that ship a javadoc jar, with no japicmp gate to catch it: Response.recv(int) arrived as an abstract interface method, two QwpWebSocketSender.connect(..., String, ...) overloads were retyped to Supplier<String>, and the multi-host AbstractLineHttpSender.createLineSender gained a parameter in place. An existing caller would fail with NoSuchMethodError, an external Response implementation with AbstractMethodError. No affected caller exists in this repo, questdb, or questdb-enterprise, so this is a latent break rather than an observed one. The exact old signatures are restored as delegates; the supplier-backed connect entry points are renamed connectWithCredentialSupplier rather than left as overloads, because a String and a Supplier<String> parameter of equal arity make a bare null credential argument ambiguous and would trade a link error for a compile error. Verified by compiling a caller written against the pre-branch signatures against both the unfixed and fixed classes.

Coverage:

• Token providers on store-and-forward pooled senders — the pooled WebSocket + SF + OIDC combination this client is built for, and the one no test covered. SenderPool applies the provider on two legs and only the non-SF one was exercised. Unwired, every SF pooled sender's upgrade would go out unauthenticated and take a 401, surfacing later as ring backpressure or a quarantined slot rather than at connect time; on the recovery leg a recovery delegate replays the previous run's data, so it would quarantine the slot and report DATA_LOSS for replayable rows.
• The fixed-versus-rotating credential tag, which decides whether a 401 during an orphan drain may quarantine a slot. Nothing connected the builder half to the drainer half. A mis-tag is silent at build time and asymmetric: tagging a rotating credential as fixed drops a .failed sentinel that nothing in production clears, permanently abandoning replayable rows over a token the next pull would have refreshed, while the other direction only delays the operator's signal. isCredentialDynamic() exposes the tag on a built sender, asserted alongside the header the server actually received and the value the drainer's reconnect factory reports.

Review follow-ups (third round)

A third review round surfaced the issues below. As before, every production fix carries a regression test shown to fail without it; the commit messages record the counterfactual output for each.

Confirmed defects:

• Discovery trusted a response body whatever its status. fetchJson awaited the response headers and went straight to parsing, so both discovery paths read configuration out of a non-2xx body. A discovery document decides where the user signs in and where the long-lived refresh token is POSTed, and an error body can easily carry the keys — an error envelope, a proxy's branded page, a captive portal, a tenant-not-found stub. Black-box proofs constructed a working instance from an HTTP 500 /settings response and from an HTTP 404 .well-known response. The token and device-authorization paths already gated on status; this one did not. requireSuccessStatus now runs before parseBody: it validates the status is exactly three bare digits before echoing any of it — the header parser copies the status-line token verbatim apart from SP/CR/LF, so a non-digit byte means a malformed or hostile line that must not splice ESC or other control bytes into a message, a log or a terminal — and then requires a leading 2. A short all-digit status is malformed too and must not be read as a class by its leading digit, matching isHttpStatusSuccess elsewhere in the class. On rejection the body is drained within the usual bound so the keep-alive connection stays usable, and the connection is dropped when the drain cannot finish, mirroring readResponse on the token path. Each call site passes its own message, so a /settings failure and a .well-known failure are told apart.
• A response-body read abort could re-send a committed flush. Both body reads in flush0 sit inside the try whose only catch treats HttpClientException as a retryable network error. Base could not throw there for a dribbling-but-progressing server, because recv() re-armed its timeout on every socket read; bounding the whole call (see Supporting changes) made it reachable, and the two branches fail differently. On the success branch a 2xx is the commit — the server already has the rows — so draining its body afterwards is only bookkeeping to keep the connection reusable, and an abort there re-sent a batch the server had accepted, with a retry budget that kept trying. The drain is now wrapped: on abort the connection is dropped, since unconsumed bytes would mis-frame the next response, and the flush is reported as the success it was. On the error branch the status is the verdict and the body is only detail for the message; an abort escaping into the catch reclassified a definitive 401, 403 or 405 as a transport failure, burned the whole retry budget against an endpoint that would keep refusing, and finally reported "Connection Failed: timed out" with the real status nowhere in it. throwOnHttpErrorResponse now wraps its body reads — all four branches at once — and falls back to a status-only exception. Reaching either needs a chunked, slowly dribbled body, which QuestDB's own /write does not produce (it answers 204 non-chunked), so exposure is through intermediaries. The pre-existing testFlushResponseBodyDribbleAbortsOnRequestTimeout asserted that a dribbled body fails the flush, against a mock that answers 200 — so it was pinning this defect rather than guarding against it. It is reworked rather than left in place: it still proves the whole-read bound, since an unbounded read would hang to the test timeout, and now also proves the batch is sent exactly once, against a retry budget a re-send would visibly spend.
• A throwing TokenStore took the whole sign-in down with it. TokenStore is a user-implemented SPI and persistence is documented best-effort, but tryRefreshCoordinated called inLock bare, so a store that threw before running its action refreshed nothing even though the client held a perfectly good refresh token. What the right degrade is depends entirely on whether the refresh already ran, which only the action can report, so the call now tracks whether it entered and completed. Threw before the action: nothing was refreshed, so run one — exactly one — uncoordinated refresh; the point of the lock is that a rotating refresh token must not be POSTed twice, and a reuse-detecting provider answers a replay by revoking the whole family. Threw after the action completed, releasing a lock or closing a handle: the refresh happened and the token is live, so report what the action returned; re-running it is that same double-POST, and throwing tells the caller a completed sign-in failed. The action itself threw: that is the refresh's own failure, not the store's, so it propagates untouched — never swallowed, never replayed. Error is deliberately not caught; an OutOfMemoryError is not a store fault to degrade around. FileTokenStore also let unchecked exceptions escape its own lock bookkeeping — SecurityException from a SecurityManager, UnsupportedOperationException from a filesystem that cannot carry POSIX permissions — so the acquire path now degrades to lock-free on those as it already did on IOException, and the release path, which runs in a finally after the critical section, absorbs them so bookkeeping cannot replace a completed result. The guard above already contains such an escape, so this second half is about the quality of the degrade — coordination is kept for that refresh rather than lost — and about the reference implementation honouring the contract TokenStore.inLock publishes.

Pre-existing defect newly exposed:

• HttpClient construction leaked when it failed partway. A constructor that fails partway leaves an object nobody can close: it never reaches the caller, so no finally, no try-with-resources and no close() ever runs on it, and whatever it had already taken is lost for the life of the process. HttpClient's base constructor takes a socket and two native buffers, then each platform subclass builds its poller, and neither step guarded the earlier ones. What makes it worth fixing is the trigger: epoll_create and kqueue fail on fd exhaustion, and the mallocs fail under memory pressure, so the failure arrives exactly when resources are already scarce, and a caller that retries compounds the loss each time. The root predates this branch; OIDC discovery newly exposes it by building a client per fetch. The base constructor now stages the socket and both buffers in locals, assigns the fields only once ResponseHeaders has succeeded, and frees in reverse order under catch (Throwable); each platform subclass wraps its poller construction and calls super.close() before rethrowing. Kqueue already guarded its own constructor this way, so this is the same pattern applied one level out; Epoll, Kqueue and FDSet each free their own allocations on failure already, and what leaked was purely what the caller had taken before calling them. HttpClientConstructorLeakTest covers four failure points through assertMemoryLeak — removing the rollback leaks 65536 bytes on the base path and 131072 on the poller path. The base case injects a negative response-buffer size and runs everywhere; the poller cases are Assume-guarded so only the running platform's executes, leaving epoll and FDSet to CI, which the class javadoc records. The pollers are failed through their facades rather than through a failing size, even though a size would need no facade: Kqueue's own failure path calls close() with its descriptor still zero, so an allocation failure there would close the test JVM's stdin — a facade returning a negative descriptor is the shape fd exhaustion actually takes and touches no real descriptors.

Review follow-ups (fourth round)

A fourth review round surfaced the issues below. As before, every production fix carries a regression test shown to fail without it; the commit messages record the counterfactual output for each.

Confirmed defects:

• A carried interrupt failed a store-and-forward delegate close. PoolHousekeeper.stop() and SenderPool.stopStartupRecoveryDriver() escalate to Thread.interrupt() when their join times out, to break a recovery build's credential pull — and the thread they interrupt is the same one that then runs senderPool.reapIdle() and the startup-recovery step's finally, both of which close a delegate. CountDownLatch.await(t, u) tests Thread.interrupted() before it ever consults the latch, so the shutdown await returned having waited 0 ms, close() took the failed-stop branch, and the slot was reported with its flock still held — precisely the outcome the interrupt was added to prevent. That branch re-asserts the flag, so in a reap sweep every remaining delegate failed the same way and QuestDB.close() returned still holding their slots. QwpWebSocketSender.close() is now interrupt-neutral, the shape QwpQueryClient.close() and QueryWorker.shutdown() already use — the query half of the pool got that treatment when the escalation landed; the ingest half, which reapIdle() reaches first, did not. An interrupt delivered during the close still takes the failed-stop branch, which is correct. PoolHousekeeper's comment claimed every wait on the pull path is interruptible; the token POST's connect, send, await and parse run on the native HTTP client, which no interrupt breaks, so it now says what the escalation does and does not buy.
• An unparseable response head was retried as a transport failure. HttpException had been added to flush0's transport catch, which was right about the disconnect and the exception type — uncaught it escaped flush0 entirely, leaving the next flush on a connection holding a half-read response and throwing a raw HttpException past every caller's catch (LineSenderException). But it must not be retried. HttpHeaderParser only runs on bytes that arrived, so the exception is positive evidence the server answered — the same evidence the 2xx drain arm treats as decisive — and the head is chosen by an intermediary, so the next attempt parses the same block and fails identically. Measured against a mock returning a 5000-byte head: 16 sends over 10.8 s per flush at the default retry budget, where the same trigger sent once before. It now disconnects, reports a non-retryable LineSenderException naming the malformed head, and does not re-send. The existing test asserted the retry, so it was pinning this rather than guarding against it.
• A recovered store read reverted a completed sign-in. maybeLoadFromStore() deliberately leaves its latch unset when a read throws, so a transient fault is retried — but it runs at the top of getToken(), ahead of the cache check, and adopt() assigns the served kind, the expiry and the ttl unconditionally, never comparing the file against what is already in memory. A store directory unavailable across signIn() and readable afterwards (an unmounted home, a container started before its volume attaches) therefore undid it: the read failed, the human authenticated, the save failed the same way and was swallowed, and the next getToken() — one per ILP flush — installed the previous entry over the grant just obtained. persistIfRotated() now latches the flag, above the rotation check so it holds whether or not the save succeeds, and covering the refresh-only path through adoptRotatedRefreshToken() with the same line. A store that never yielded a token is unaffected.
• The client wrote a store entry adopt() refuses to read back. adopt() rejects a refresh token carried with neither token kind as positive evidence of a foreign writer — the guard that stops someone who can write the store directory swapping in their own refresh token. Its justification rested on a callsite count ("persistIfRotated runs solely at the tail of storeTokens"), and that count was wrong: under groupsInToken, a stored entry carrying only an access token takes adopt()'s own served-kind-absent branch, which nulls both kinds and keeps the refresh token, so a refresh that rotates the refresh token but still returns no id token reaches adoptRotatedRefreshToken() → persistIfRotated() with both null. The file it wrote was one it would never read back, so every restart re-ran the device flow over a live refresh token on disk. persistIfRotated() now declines that shape; the previous entry stays, its burned refresh token costs one silent round trip on the next start, and the rejection keeps its teeth.

Tandem

OSS: questdb/questdb#7331
Ent: https://github.com/questdb/questdb-enterprise/pull/1090

[mtopolnik]

[PR Coverage check]

😍 pass : 2201 / 2457 (89.58%)

file detail

	path	covered line	new line	coverage
🔵	io/questdb/client/cutlass/line/http/LineHttpSenderV1.java	0	4	00.00%
🔵	io/questdb/client/cutlass/http/client/HttpClientWindows.java	0	7	00.00%
🔵	io/questdb/client/cutlass/http/client/HttpClientOsx.java	0	7	00.00%
🔵	io/questdb/client/cutlass/line/http/LineHttpSenderV2.java	0	4	00.00%
🔵	io/questdb/client/cutlass/qwp/protocol/QwpTableBuffer.java	2	3	66.67%
🔵	io/questdb/client/cutlass/auth/BrowserLauncher.java	15	22	68.18%
🔵	io/questdb/client/impl/QueryWorker.java	3	4	75.00%
🔵	io/questdb/client/impl/SenderPool.java	10	13	76.92%
🔵	io/questdb/client/cutlass/qwp/client/QwpWebSocketSender.java	84	106	79.25%
🔵	io/questdb/client/cutlass/qwp/client/QwpCredentialUnavailableException.java	5	6	83.33%
🔵	io/questdb/client/cutlass/auth/FileTokenStore.java	437	511	85.52%
🔵	io/questdb/client/cutlass/http/client/HttpClient.java	31	36	86.11%
🔵	io/questdb/client/cutlass/line/http/AbstractLineHttpSender.java	91	102	89.22%
🔵	io/questdb/client/cutlass/auth/DeviceCodePrompt.java	22	24	91.67%
🔵	io/questdb/client/std/str/Utf16Sink.java	22	24	91.67%
🔵	io/questdb/client/cutlass/auth/OidcDeviceAuth.java	1043	1140	91.49%
🔵	io/questdb/client/cutlass/auth/TokenStoreKey.java	42	45	93.33%
🔵	io/questdb/client/cutlass/qwp/client/sf/cursor/BackgroundDrainer.java	70	73	95.89%
🔵	io/questdb/client/Sender.java	31	32	96.88%
🔵	io/questdb/client/cutlass/qwp/client/QwpQueryClient.java	34	35	97.14%
🔵	io/questdb/client/impl/PoolHousekeeper.java	3	3	100.00%
🔵	io/questdb/client/cutlass/auth/TokenStore.java	1	1	100.00%
🔵	io/questdb/client/QuestDB.java	4	4	100.00%
🔵	io/questdb/client/std/str/DirectUtf8Sink.java	9	9	100.00%
🔵	io/questdb/client/std/str/StringSink.java	4	4	100.00%
🔵	io/questdb/client/cutlass/qwp/client/QwpUdpSender.java	1	1	100.00%
🔵	io/questdb/client/cutlass/http/client/HttpClientLinux.java	7	7	100.00%
🔵	io/questdb/client/QuestDBBuilder.java	7	7	100.00%
🔵	io/questdb/client/cutlass/line/LineSenderException.java	6	6	100.00%
🔵	io/questdb/client/cutlass/http/client/Response.java	1	1	100.00%
🔵	io/questdb/client/impl/QueryClientPool.java	5	5	100.00%
🔵	io/questdb/client/cutlass/auth/DeviceAuthorizationChallenge.java	12	12	100.00%
🔵	io/questdb/client/cutlass/http/client/AbstractChunkedResponse.java	17	17	100.00%
🔵	io/questdb/client/cutlass/qwp/client/sf/cursor/CursorWebSocketSendLoop.java	32	32	100.00%
🔵	io/questdb/client/cutlass/json/JsonLexer.java	68	68	100.00%
🔵	io/questdb/client/cutlass/auth/PersistedToken.java	12	12	100.00%
🔵	io/questdb/client/impl/QuestDBImpl.java	2	2	100.00%
🔵	io/questdb/client/cutlass/auth/OidcAuthException.java	33	33	100.00%
🔵	io/questdb/client/cutlass/http/client/AbstractResponse.java	8	8	100.00%
🔵	io/questdb/client/std/str/DisplaySafe.java	20	20	100.00%
🔵	io/questdb/client/HttpTokenProvider.java	7	7	100.00%