Enforce OIDC token store lock staleness floor

build() now rejects a FileTokenStore whose lockStaleMillis is below
4x httpTimeoutMillis. The cross-process lock presumes a holder has
crashed once its lock outlives that staleness window and steals it; if
the window is shorter than the worst-case time a live refresh holds the
lock (send + await + parse + body drain, each bounded by
httpTimeoutMillis), a peer can steal a live holder's lock mid-refresh
and reopen the rotating-refresh-token race the lock exists to prevent.
The store cannot see the client's timeout, so build() enforces the
invariant where both values are known. The default store (600s) and any
non-coordinating TokenStore are unaffected.

Also add the two load-path security tests this subsystem lacked:
- a groups-in-token instance rejects a persisted entry whose served id
  token carries CR/LF (adopt() must validate the id token, not the
  access token, in that mode) and falls back to the device flow;
- a persisted served token carrying a non-ASCII char (> 0x7e), not just
  a control char, is rejected on load.

Each new test was confirmed to fail without its fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: glasstiger

core/src/main/java/io/questdb/client/cutlass/auth/FileTokenStore.java

@@ -280,6 +280,12 @@ public void save(TokenStoreKey key, PersistedToken token) {
         }
     }
 
+    long getLockStaleMillis() {
+        // exposed package-private so OidcDeviceAuth.build() can verify this window dominates the worst-case time
+        // a coordinated refresh holds the lock, before a peer could otherwise judge a live lock stale and steal it
+        return lockStaleMillis;
+    }
+
     private static void createLockFile(Path lock) throws IOException {
         try {
             Files.createFile(lock, FILE_ATTRS);

core/src/main/java/io/questdb/client/cutlass/auth/OidcDeviceAuth.java

@@ -132,6 +132,11 @@ public class OidcDeviceAuth implements QuietCloseable {
     // tokens fail to parse with "String is too long".
     private static final int JSON_LEXER_CACHE_SIZE = 1024;
     private static final int JSON_LEXER_MAX_VALUE_BYTES = 1 << 20;
+    // the worst case a coordinated refresh can hold a FileTokenStore cross-process lock, as a multiple of
+    // httpTimeoutMillis: one refresh under the lock runs send + await + parse, plus a body drain on a parse
+    // failure, each separately bounded by httpTimeoutMillis. build() rejects a FileTokenStore whose
+    // lock-staleness window does not exceed this, so a peer never judges a live holder's lock stale mid-refresh
+    private static final int LOCK_HOLD_HTTP_TIMEOUT_MULTIPLE = 4;
     // upper bound on the device code lifetime (the device authorization response's expires_in), so a
     // hostile or buggy provider cannot make the client poll for an absurd duration; matches the Python client
     private static final int MAX_DEVICE_CODE_TTL_SECONDS = 1800;
@@ -1579,6 +1584,23 @@ public OidcDeviceAuth build() {
             // discovery, so the documented guarantee holds for the explicit builder too
             validateEndpointOrigins(parsedTokenEndpoint, deviceEndpoint, issuerEndpoint);
             ClientTlsConfiguration tls = tlsConfig != null ? tlsConfig : defaultTlsConfig();
+            // a FileTokenStore steals a lock older than its staleness window, presuming a crashed holder; that
+            // window must exceed the worst-case time a live refresh holds the lock (the refresh under the lock is
+            // bounded by httpTimeoutMillis, up to LOCK_HOLD_HTTP_TIMEOUT_MULTIPLE times it), or a peer could steal
+            // a live holder's lock mid-refresh and reopen the rotating-refresh-token race the lock prevents. The
+            // store cannot see this client's timeout, so enforce the invariant here, where both are known, rather
+            // than leave the caller to size it by hand. A non-coordinating TokenStore is exempt - it takes no lock.
+            if (tokenStore instanceof FileTokenStore) {
+                long minStaleMillis = (long) LOCK_HOLD_HTTP_TIMEOUT_MULTIPLE * httpTimeoutMillis;
+                long staleMillis = ((FileTokenStore) tokenStore).getLockStaleMillis();
+                if (staleMillis < minStaleMillis) {
+                    throw new OidcAuthException()
+                            .put("the FileTokenStore lockStaleMillis (").put(staleMillis)
+                            .put(") must be at least ").put(LOCK_HOLD_HTTP_TIMEOUT_MULTIPLE)
+                            .put("x httpTimeoutMillis (").put(minStaleMillis)
+                            .put("), otherwise a slow refresh's live cross-process lock could be stolen by a peer mid-refresh");
+                }
+            }
             return new OidcDeviceAuth(this, tls);
         }
 

core/src/test/java/io/questdb/client/test/cutlass/auth/OidcDeviceAuthPersistenceTest.java

@@ -85,6 +85,34 @@ public void testAdoptDerivesTtlFromExpiry() throws Exception {
         });
     }
 
+    @Test(timeout = 30_000)
+    public void testBuildRejectsFileTokenStoreWithTooSmallStaleWindow() throws Exception {
+        assertMemoryLeak(() -> {
+            try (MockOidcServer server = new MockOidcServer((method, path, body) -> MockOidcServer.json(200, "{}"))) {
+                Path dir = storeDir();
+                // a lock-staleness window below LOCK_HOLD_HTTP_TIMEOUT_MULTIPLE (4) x httpTimeoutMillis would let a
+                // peer judge a live holder's lock stale and steal it mid-refresh, reopening the rotating-refresh-
+                // token race the lock prevents; build() must reject the combination rather than ship the race
+                try {
+                    baseBuilder(server)
+                            .httpTimeoutMillis(30_000)
+                            .tokenStore(new FileTokenStore(dir, 3_000, 119_999))
+                            .build();
+                    Assert.fail("a lockStaleMillis below 4x httpTimeoutMillis must be rejected");
+                } catch (OidcAuthException expected) {
+                    Assert.assertTrue(expected.getMessage(), expected.getMessage().contains("lockStaleMillis"));
+                }
+                // exactly 4x httpTimeoutMillis is the boundary and builds
+                try (OidcDeviceAuth ignored = baseBuilder(server)
+                        .httpTimeoutMillis(30_000)
+                        .tokenStore(new FileTokenStore(dir, 3_000, 120_000))
+                        .build()) {
+                    // building at the boundary succeeds
+                }
+            }
+        });
+    }
+
     @Test(timeout = 30_000)
     public void testBuilderRejectsHttpTimeoutAboveCap() throws Exception {
         assertMemoryLeak(() -> {
@@ -557,6 +585,37 @@ public void testTamperedFileWithCrlfTokenFallsBackToDeviceFlow() throws Exceptio
         });
     }
 
+    @Test(timeout = 30_000)
+    public void testTamperedIdTokenRejectedOnLoadWithGroupsInToken() throws Exception {
+        assertMemoryLeak(() -> {
+            AtomicInteger device = new AtomicInteger();
+            AtomicInteger token = new AtomicInteger();
+            MockOidcServer.Handler handler = (method, path, body) -> {
+                if (DEVICE_PATH.equals(path)) {
+                    device.incrementAndGet();
+                    return MockOidcServer.json(200, deviceAuthJson());
+                }
+                token.incrementAndGet();
+                return MockOidcServer.json(200, tokenJson("ACCESS-FRESH", "ID-FRESH", "REFRESH-FRESH", 3600));
+            };
+            try (MockOidcServer server = new MockOidcServer(handler)) {
+                Path dir = storeDir();
+                // groups-in-token mode serves the ID token, so adopt() must validate the ID token, not the access
+                // token. A genuine on-disk file (valid groups fingerprint) with a CLEAN access token but a CR/LF
+                // id token must be rejected and fall back to the device flow, never routing the tampered id token
+                // onto the wire. A bug that validated the access token would accept this entry and serve "I\r\nD".
+                new FileTokenStore(dir).save(keyForGroups(server),
+                        new PersistedToken("ACCESS-CLEAN", "I\r\nD", "REFRESH-1", System.currentTimeMillis() + 300_000, 300_000));
+                try (OidcDeviceAuth auth = baseBuilder(server).groupsInToken(true).tokenStore(new FileTokenStore(dir)).build()) {
+                    String result = auth.signIn();
+                    Assert.assertEquals("ID-FRESH", result);
+                    Assert.assertNotEquals("I\r\nD", result);
+                }
+                Assert.assertTrue("a rejected on-disk id token must fall back to the device flow", device.get() >= 1);
+            }
+        });
+    }
+
     @Test(timeout = 30_000)
     public void testTamperedServedTokenRejectedOnLoad() throws Exception {
         assertMemoryLeak(() -> {
@@ -582,6 +641,33 @@ public void testTamperedServedTokenRejectedOnLoad() throws Exception {
         });
     }
 
+    @Test(timeout = 30_000)
+    public void testTamperedServedTokenWithNonAsciiRejectedOnLoad() throws Exception {
+        assertMemoryLeak(() -> {
+            AtomicInteger device = new AtomicInteger();
+            MockOidcServer.Handler handler = (method, path, body) -> {
+                if (DEVICE_PATH.equals(path)) {
+                    device.incrementAndGet();
+                    return MockOidcServer.json(200, deviceAuthJson());
+                }
+                return MockOidcServer.json(200, tokenJson("ACCESS-FRESH", null, "REFRESH-1", 3600));
+            };
+            try (MockOidcServer server = new MockOidcServer(handler)) {
+                FakeTokenStore fake = new FakeTokenStore();
+                // hasOnlyTokenChars rejects a non-ASCII char (> 0x7e), not just a control char: a persisted served
+                // token carrying one (here U+00E9) is the byte the ASCII Authorization-header writer would
+                // truncate, so adopt() must reject the entry and fall back rather than serve a corrupt credential
+                fake.loadReturns = new PersistedToken("ACC\u00e9SS", null, "REFRESH-1", System.currentTimeMillis() + 300_000, 300_000);
+                try (OidcDeviceAuth auth = baseBuilder(server).tokenStore(fake).build()) {
+                    String result = auth.signIn();
+                    Assert.assertEquals("ACCESS-FRESH", result);
+                    Assert.assertNotEquals("ACC\u00e9SS", result);
+                }
+                Assert.assertTrue("a rejected non-ASCII persisted token must fall back to the device flow", device.get() >= 1);
+            }
+        });
+    }
+
     private static OidcDeviceAuth.Builder baseBuilder(MockOidcServer server) {
         return OidcDeviceAuth.builder()
                 .clientId("questdb")