Refine token-store cross-process and load semantics

Run clear() under the cross-process lock. A bare deleteIfExists let a
peer mid-refresh atomically rename a fresh file in just after the delete,
resurrecting the entry; clear() now deletes inside inLock (which cleans
up its own lock and degrades to lock-free if it cannot acquire one). A
Files.isDirectory guard keeps clear() a true no-op on a never-used store
rather than creating the directory just to run the locked delete. Cross-
process clear stays best-effort: a peer holding a live in-memory token
may legitimately re-persist afterwards.

Derive the adopted token lifetime from the absolute expiry. adopt()
clamped expires_at_millis and token_ttl_millis from the file
independently, so a tampered file could make them disagree and throw off
effectiveSkewMillis (which caps the skew at half the lifetime). Derive
tokenTtlMillis from the clamped expiry instead, so the skew basis always
matches the authoritative remaining lifetime; a legitimate file is
unaffected.

Document the cross-process contract more precisely. The README now notes
that lock-file staleness is judged by modification time, so coordination
assumes a shared clock (a single machine or synchronized clocks; NFS
clock skew can mis-judge it), and that clearCache() is best-effort across
processes. The frozen on-disk contract now states the document must be a
single flat JSON object, which the parser already enforces by rejecting
an array-wrapped or non-object shape - so the Python client mirrors it.

Order parseAndVerify before parseLongOrZero to match the alphabetical
member ordering.

Add tests for the expiry-derived lifetime and the clear-on-empty-store
no-op; both were proven to fail with their fix reverted.

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

Author: glasstiger

README.md

@@ -248,7 +248,7 @@ try (OidcDeviceAuth auth = OidcDeviceAuth.fromQuestDB(
 
 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 prints a one-line warning to `System.err` the first time it cannot enforce them. 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 — a tampered, corrupt, oversized, or identity-mismatched entry is ignored (the client falls back to a refresh or an interactive sign-in), and a token carrying control or non-ASCII characters is never placed on the wire.
 
-`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.
+`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
 

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

@@ -191,11 +191,22 @@ public static FileTokenStore atDefaultLocation() {
 
     @Override
     public void clear(TokenStoreKey key) {
-        try {
-            Files.deleteIfExists(tokenFile(key));
-        } catch (IOException e) {
-            throw new OidcAuthException(e).put("could not remove the OIDC token store file");
-        }
+        if (!Files.isDirectory(directory)) {
+            return; // nothing is persisted yet; do not create the directory just to clear it
+        }
+        // delete under the cross-process lock, like the read-refresh-write, so a peer's in-flight refresh
+        // cannot resurrect the entry by atomically renaming a fresh file in just after we delete. inLock cleans
+        // up its own lock file and degrades to lock-free if it cannot acquire one. Cross-process clear is still
+        // best-effort: a peer holding a live in-memory token may legitimately re-persist later - clearing forces
+        // a fresh sign-in for THIS process regardless, since the caller resets its in-memory token state.
+        inLock(key, () -> {
+            try {
+                Files.deleteIfExists(tokenFile(key));
+            } catch (IOException e) {
+                throw new OidcAuthException(e).put("could not remove the OIDC token store file");
+            }
+            return true;
+        });
     }
 
     @Override
@@ -295,14 +306,6 @@ private static boolean nullableEquals(String keyValue, StringSink fileValue) {
         return fileHasValue && Chars.equals(keyValue, fileValue);
     }
 
-    private static long parseLongOrZero(CharSequence value) {
-        try {
-            return Numbers.parseLong(value);
-        } catch (NumericException e) {
-            return 0;
-        }
-    }
-
     private static PersistedToken parseAndVerify(TokenStoreKey key, byte[] bytes) {
         if (bytes.length == 0) {
             return null;
@@ -339,6 +342,14 @@ private static PersistedToken parseAndVerify(TokenStoreKey key, byte[] bytes) {
         return new PersistedToken(accessToken, idToken, refreshToken, parser.expiresAtMillis, parser.tokenTtlMillis);
     }
 
+    private static long parseLongOrZero(CharSequence value) {
+        try {
+            return Numbers.parseLong(value);
+        } catch (NumericException e) {
+            return 0;
+        }
+    }
+
     private static void putBooleanMember(StringSink sink, String name, boolean value) {
         sink.put(',');
         putName(sink, name);

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

@@ -1038,8 +1038,13 @@ private boolean adopt(PersistedToken token) {
         // positive and serve a garbage-expiry token as valid forever. An already-expired entry still reads as
         // expired and falls through to a refresh rather than being served.
         long maxTokenLifeMillis = MAX_EXPIRES_IN_SECONDS * 1000L;
-        tokenTtlMillis = Math.max(0L, Math.min(token.getTokenTtlMillis(), maxTokenLifeMillis));
-        expiresAtMillis = Math.max(0L, Math.min(token.getExpiresAtMillis(), System.currentTimeMillis() + maxTokenLifeMillis));
+        long now = System.currentTimeMillis();
+        expiresAtMillis = Math.max(0L, Math.min(token.getExpiresAtMillis(), now + maxTokenLifeMillis));
+        // derive the trusted lifetime from the clamped absolute expiry, not the file's separately-stored ttl, so
+        // a tampered file cannot make the two disagree and throw off effectiveSkewMillis (which caps the skew at
+        // half the lifetime); for a legitimate file the two already agree, and the expiry clamp bounds this to
+        // [0, maxLife]
+        tokenTtlMillis = Math.max(0L, expiresAtMillis - now);
         // it is already on disk, so a later non-rotating refresh must not rewrite the file
         lastPersistedRefreshToken = refreshToken;
         return true;

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

@@ -170,6 +170,18 @@ public void testClearDeletesFile() throws Exception {
         });
     }
 
+    @Test
+    public void testClearOnEmptyStoreIsNoOp() throws Exception {
+        assertMemoryLeak(() -> {
+            Path dir = storeDir(); // a non-existent subdirectory
+            FileTokenStore store = new FileTokenStore(dir);
+            // clearing an identity that was never saved must be a no-op and must not create the store directory
+            // just to run the now-locked delete
+            store.clear(sampleKey());
+            Assert.assertFalse("clear must not create the store directory", Files.exists(dir));
+        });
+    }
+
     @Test
     public void testControlCharactersRoundTrip() throws Exception {
         assertMemoryLeak(() -> {

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

@@ -56,6 +56,35 @@ public class OidcDeviceAuthPersistenceTest {
     @Rule
     public final TemporaryFolder temp = TemporaryFolder.builder().assureDeletion().build();
 
+    @Test(timeout = 30_000)
+    public void testAdoptDerivesTtlFromExpiry() throws Exception {
+        assertMemoryLeak(() -> {
+            AtomicInteger device = new AtomicInteger();
+            AtomicInteger token = new AtomicInteger();
+            MockOidcServer.Handler handler = countingHandler(device, token, "ACCESS-FRESH", "REFRESH-FRESH", "ACCESS-2", "REFRESH-2");
+            try (MockOidcServer server = new MockOidcServer(handler)) {
+                FakeTokenStore fake = new FakeTokenStore();
+                // a (tampered) entry whose stored ttl (5m) disagrees with its absolute expiry (now + 10m).
+                // adopt() must derive the trusted lifetime from the authoritative expiry, not the stored ttl, so
+                // the effectiveSkewMillis basis matches the real remaining lifetime
+                long now = System.currentTimeMillis();
+                fake.loadReturns = new PersistedToken("ACCESS-1", null, "REFRESH-1", now + 600_000, 300_000);
+                try (OidcDeviceAuth auth = baseBuilder(server).tokenStore(fake).build()) {
+                    Assert.assertEquals("the still-valid persisted token is served", "ACCESS-1", auth.signIn());
+                    long ttl = readPrivateLong(auth, "tokenTtlMillis");
+                    long expiry = readPrivateLong(auth, "expiresAtMillis");
+                    Assert.assertTrue("ttl must be derived from the ~10m expiry, not the stored 5m: " + ttl,
+                            ttl >= 9 * 60_000L);
+                    Assert.assertTrue("ttl must not exceed the clamped 1h lifetime: " + ttl, ttl <= 60 * 60_000L);
+                    Assert.assertTrue("ttl must match expiresAtMillis - now within tolerance",
+                            Math.abs(ttl - (expiry - now)) < 5_000L);
+                }
+                Assert.assertEquals("no device flow for a valid persisted token", 0, device.get());
+                Assert.assertEquals("no refresh for a valid persisted token", 0, token.get());
+            }
+        });
+    }
+
     @Test(timeout = 30_000)
     public void testBuilderRejectsHttpTimeoutAboveCap() throws Exception {
         assertMemoryLeak(() -> {

design/oidc-token-persistence.md

@@ -337,6 +337,10 @@ serving — but it defeats *sharing*, leaving each client to re-prompt).
   encoding under which every present value round-trips verbatim (a token equal to the string
   `"null"` included); a reader treats an absent field as null. The Python client MUST do the
   same: omit null fields on write, and treat an absent field as null on read.
+
+  The document MUST be a single flat JSON object. A reader rejects any other shape - an array
+  anywhere (for example a top-level `[ {…} ]` wrapper) or a non-object root - rather than
+  extract fields from a malformed structure. The Python client MUST do the same.
 - **Write protocol (atomicity):** write a sibling temp file created with 0600, flush, then
   **atomically rename** over the target — Java `Files.move(tmp, target, ATOMIC_MOVE,
   REPLACE_EXISTING)`, Python `os.replace(tmp, target)`. Both are `rename(2)` on POSIX