fix(core): a non-future server cache directive no longer expires the document permanently

`effectiveTtlSeconds()` subtracted the cache timestamp from the server
expiry, so an expiry that was not in the future produced a negative TTL.
`CacheHeaderParser.parseExpiresAt` returns `0` for `Cache-Control:
no-store` and `no-cache`, the current second for `max-age=0`, and a past
epoch for a stale `Expires:` — for `no-store` the result is about
-1.7e9.

A negative TTL is expired on every read, so `get()` took the synchronous
re-fetch branch on the caller's thread every time, forever. The failure
backoff could not cover it: that only arms when a fetch *throws*, and an
endpoint answering `no-store` successfully clears the backoff and
re-arms the expiry on the same call.

This was latent while nothing on a verification path read the metadata
cache. This change series is what puts it there — verification reads
through the cache before every key lookup, and `beforeLookup()` runs
before signature verification, so an unauthenticated caller would have
set the fetch rate against the authorization server. It is the failure
this series exists to remove, reached through a different door.

An expiry at or before the cache timestamp is now read as "no
preference" and the configured interval governs. go-sdk clamps the
equivalent case the same way rather than taking a zero expiry
literally.

Two tests, and the negative control holds: with the clamp removed both
fail and the pre-existing `get_serverExpiresTtl_usesMinOfConfigured...`
still passes, which is why it never covered this — it only exercises a
*future* server expiry.

Also corrects two claims about gate ordering that were not true. The
`requireNoUserinfo` javadoc said it runs "last of the four", and the
changelog said `wellKnownUrl` "enforces the same four gates as the
constructors". The set is the same; the order is not — the three
construction sites run fragment, query, scheme, userinfo and
`wellKnownUrl` runs fragment, scheme, userinfo, query. An identifier
violating two gates can therefore be reported for a different component
depending on the entrypoint. Both reject, so only the message differs;
unifying the four behind one private gate touches four call sites with
different shapes and is left to its own change rather than bolted onto
this one.

990 tests, 0 failures.

Author: RobertoIskandarani

CHANGELOG.md

@@ -21,6 +21,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- A server cache directive that is not in the future no longer makes the document permanently
+  expired. `Cache-Control: no-store` and `no-cache` parse to an expiry of `0`, `max-age=0` to the
+  current second, and a stale `Expires:` to a past one; the effective TTL was computed by
+  subtracting the cache timestamp from that, so any of them produced a *negative* TTL — about
+  -1.7e9 for `no-store`. A negative TTL is expired on every read, so every read took the
+  synchronous re-fetch branch on the caller's thread, and the failure backoff could not help
+  because it only arms when a fetch throws: an endpoint answering `no-store` successfully cleared
+  the backoff and re-armed the expiry on the same call. Such an expiry is now treated as no
+  preference and the configured interval governs. This was latent while nothing on a verification
+  path read the metadata cache; the change above puts it there, before signature verification, so
+  an unauthenticated caller would otherwise have set the fetch rate against the authorization
+  server.
+
 - Authorization server metadata is now re-read under ordinary verification traffic, so
   `metadataRefreshSeconds` takes effect on a resource server that only verifies tokens. Such a
   server never calls the token, introspection or revocation endpoints, so nothing on its request
@@ -107,7 +120,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   question, not settled by this change, and tracked.
 
   **Migration:** A scheme-relative or relative resource identifier now fails at startup instead of
-  at the first 401. Prefix the intended scheme. `wellKnownUrl` enforces the same four gates as the
+  at the first 401. Prefix the intended scheme. `wellKnownUrl` enforces the same four gates (in a
+  different order, so the component named in the message can differ from a constructor's) as the
   constructors, so a caller reaching it directly with a string no constructor saw is refused there
   too rather than splicing a malformed identifier into a challenge.
 

core/src/main/java/ai/authplane/sdk/core/fetching/DocumentCache.java

@@ -366,9 +366,35 @@ private long failureBackoffSeconds() {
         return failureBackoffSeconds(configuredRefreshSeconds);
     }
 
+    /**
+     * The TTL actually in force: the configured interval, shortened by a server expiry when the
+     * server asks for something sooner.
+     *
+     * <p>A server expiry at or before the moment the document was cached is treated as **no
+     * preference** rather than as an expiry, and the configured interval governs. It has to be:
+     * {@code CacheHeaderParser.parseExpiresAt} returns {@code 0L} for {@code Cache-Control:
+     * no-store} or {@code no-cache}, {@code now} for {@code max-age=0}, and a past epoch for a
+     * stale {@code Expires:} — and subtracting {@code cachedAtEpochSeconds} from any of those
+     * yields a negative TTL. For {@code no-store} that is about -1.7e9.
+     *
+     * <p>A negative TTL makes {@code age >= effectiveTtl} true on every read, so {@link #get()}
+     * takes the synchronous re-fetch branch on the caller's thread every single time, forever. The
+     * failure backoff does not cover it, because that only arms when a fetch *throws*: an endpoint
+     * that answers {@code no-store} successfully clears the backoff and re-arms the expiry on the
+     * same call.
+     *
+     * <p>That was harmless while nothing on a verification path read this cache. It stopped being
+     * harmless when metadata moved onto that path — verification now reads through here before
+     * every key lookup, and that runs before signature verification, so an unauthenticated caller
+     * would set the rate. This is the same failure the backoff was added to remove, reached by a
+     * different door.
+     *
+     * <p>go-sdk clamps the equivalent case the same way: a zero expiry falls back to the configured
+     * default rather than being taken literally.
+     */
     private long effectiveTtlSeconds() {
-        long configuredExpiry = cachedAtEpochSeconds + configuredRefreshSeconds;
-        if (serverExpiresAtSeconds != null) {
+        if (serverExpiresAtSeconds != null && serverExpiresAtSeconds > cachedAtEpochSeconds) {
+            long configuredExpiry = cachedAtEpochSeconds + configuredRefreshSeconds;
             return Math.min(configuredExpiry, serverExpiresAtSeconds) - cachedAtEpochSeconds;
         }
         return configuredRefreshSeconds;

core/src/main/java/ai/authplane/sdk/core/prm/ProtectedResourceMetadata.java

@@ -438,8 +438,15 @@ public static void requireScheme(String resourceUri) {
      *
      * <p>Called from the same construction boundaries as the sibling gates — {@link
      * Builder#build()}, the {@code AuthplaneResource} constructor, and {@code
-     * AuthplaneClient.resource(...)} — and last of the four, so an identifier that is also
-     * scheme-relative is reported for the missing scheme, the defect an operator fixes first.
+     * AuthplaneClient.resource(...)} — after {@link #requireScheme(String)}, so an identifier that
+     * is also scheme-relative is reported for the missing scheme, the defect an operator fixes
+     * first.
+     *
+     * <p>The four gates run in the same *set* everywhere but not in the same *order*: the three
+     * construction sites run fragment, query, scheme, userinfo, while {@link #wellKnownUrl(String)}
+     * runs fragment, scheme, userinfo, query. So an identifier that violates two of them can be
+     * reported for a different component depending on the entrypoint. Both reject either way; only
+     * the message differs. Unifying the four behind one private gate is tracked.
      *
      * @param resourceUri the resource identifier, as configured by the operator
      * @throws IllegalArgumentException if the identifier's authority carries a userinfo component

core/src/test/java/ai/authplane/sdk/core/fetching/DocumentCacheTest.java

@@ -136,6 +136,74 @@ void get_triggersBackgroundRefreshAt80PercentTtl() throws Exception {
         assertThat(fetchCount.get()).isEqualTo(2);
     }
 
+    /**
+     * A server expiry that is not in the future is no expiry at all.
+     *
+     * <p>`Cache-Control: no-store` and `no-cache` parse to `0L`, `max-age=0` to `now`, and a stale
+     * `Expires:` to a past epoch. Subtracting the cache timestamp from any of those gives a
+     * negative TTL, which makes the document permanently expired: every read takes the synchronous
+     * re-fetch branch, on the caller's thread. The failure backoff cannot help, because a
+     * `no-store` endpoint that *answers* clears it and re-arms the expiry on the same call.
+     *
+     * <p>This matters now that verification reads through the metadata cache on every key lookup —
+     * and does so before signature verification, so an unauthenticated caller would set the fetch
+     * rate against the authorization server.
+     */
+    @Test
+    void get_serverExpiryNotInTheFuture_fallsBackToTheConfiguredInterval() throws Exception {
+        // 0L is what no-store and no-cache parse to; -1 stands for a stale Expires: header.
+        for (long serverExpiry : new long[] {0L, -1L}) {
+            AtomicInteger fetchCount = new AtomicInteger();
+            TestClock clock = new TestClock();
+            DocumentFetcher fetcher =
+                    url -> {
+                        fetchCount.incrementAndGet();
+                        return CompletableFuture.completedFuture(
+                                new FetchResult(DOC_V1, serverExpiry));
+                    };
+            cache = cacheWith(fetcher, 300, clock);
+            cache.fetch();
+            assertThat(fetchCount.get()).isEqualTo(1);
+
+            for (int i = 0; i < 5; i++) {
+                assertThat(cache.get()).isEqualTo(DOC_V1);
+            }
+            assertThat(fetchCount.get())
+                    .as(
+                            "server expiry %s must not make the document permanently expired",
+                            serverExpiry)
+                    .isEqualTo(1);
+
+            clock.advanceSeconds(301);
+            cache.get();
+            assertThat(fetchCount.get())
+                    .as("the configured interval still governs for server expiry %s", serverExpiry)
+                    .isEqualTo(2);
+        }
+    }
+
+    /**
+     * A server expiry exactly at the cache timestamp is the max-age=0 case, and behaves the same.
+     */
+    @Test
+    void get_serverExpiryEqualToCachedAt_fallsBackToTheConfiguredInterval() throws Exception {
+        AtomicInteger fetchCount = new AtomicInteger();
+        TestClock clock = new TestClock();
+        DocumentFetcher fetcher =
+                url -> {
+                    fetchCount.incrementAndGet();
+                    return CompletableFuture.completedFuture(
+                            new FetchResult(DOC_V1, clock.instant().getEpochSecond()));
+                };
+        cache = cacheWith(fetcher, 300, clock);
+        cache.fetch();
+
+        for (int i = 0; i < 5; i++) {
+            cache.get();
+        }
+        assertThat(fetchCount.get()).as("max-age=0 must not cost a fetch per read").isEqualTo(1);
+    }
+
     @Test
     void get_serverExpiresTtl_usesMinOfConfiguredAndServer() throws Exception {
         // Server says the document expires 10s from now; the configured TTL is 300s. The