fix(security): close 3 low-severity account/side-channel findings

Security review of the auth flows surfaced three low-severity issues, all
fixed here:

- pk-auth-persistence-dynamodb: refresh-token rotation gated the atomic
  ConditionExpression on `expiresAtIso > :now`, a lexicographic compare of
  variable-precision Instant.toString() values (the fractional-seconds field
  is dropped when zero), so "...:00Z" sorts after "...:00.000001Z" and a
  just-expired token could rotate within the rotate TOCTOU window. Compare
  the numeric epoch-second `ttl` attribute instead. Fails closed now.

- pk-auth-jwt: PkAuthJwtValidator in stateful mode guarded the AccessTokenStore
  lookup with `jti != null`, so a validly-signed, in-issuer/-audience, unexpired
  token with no jti bypassed the revocation gate. Reject jti-less tokens with
  MissingClaim("jti") when a non-noop store is bound. The library's own tokens
  always carry a jti, so behavior is unchanged for them.

- pk-auth-magic-link: corrected the MagicLinkService.startLogin javadoc, which
  falsely claimed timing-side-channel resistance; the not-found path returns
  before JWT issuance and email dispatch, so latency still enables enumeration.
  Documentation only; no behavior change.

All affected modules pass spotlessCheck, unit tests, and the DynamoDB Local
refresh-token integration suite (incl. concurrent-rotation and expired-token
cases).

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

Author: wolpert

CHANGELOG.md

@@ -11,6 +11,39 @@ tags.
 
 ## [Unreleased]
 
+## [1.2.0]
+
+### Security
+
+- **DynamoDB refresh-token rotation now compares expiry numerically, not
+  lexically.** `DynamoDbRefreshTokenRepository.rotateAtomically` gated the
+  atomic-rotate `ConditionExpression` on `expiresAtIso > :now`, comparing two
+  `Instant.toString()` strings. That output is variable-precision (the
+  fractional-seconds field is dropped when zero), so a bytewise `>` sorts
+  `…:00Z` *after* `…:00.000001Z` and could treat a just-expired token as still
+  fresh. The condition now compares the numeric epoch-second `ttl` attribute
+  (`#ttl > :nowEpoch`). The authoritative expiry check in `RefreshTokenService`
+  was already correct, so the exposure was limited to a sub-second
+  fail-open in the database-level backstop for the rotate TOCTOU window.
+- **Stateful JWT validation rejects `jti`-less tokens instead of skipping
+  revocation.** When a non-noop `AccessTokenStore` is bound,
+  `PkAuthJwtValidator` previously guarded the store lookup with `jti != null`,
+  so a validly-signed, in-issuer, in-audience, unexpired token carrying no
+  `jti` bypassed the `exists` revocation gate entirely. The validator now
+  returns `MissingClaim("jti")` for a `jti`-less token in stateful mode. Tokens
+  minted by `PkAuthJwtIssuer` always carry a `jti`, so this never affected the
+  library's own tokens; it closes the gap for any other token signed with the
+  same keyset.
+- **Corrected the `MagicLinkService.startLogin` timing-side-channel
+  contract (documentation).** The javadoc claimed the method defeats timing
+  side-channels, but the not-found path returns before JWT issuance and email
+  dispatch, so response latency still distinguishes known from unknown
+  usernames. The contract now documents the result-shape guarantee only and
+  points hosts at uniform-latency / rate-limiting mitigations. No behavioural
+  change.
+
+## [1.1.0] — 2026-06-02
+
 ### Added
 
 - `TokenTtlPolicy` SPI in `pk-auth-jwt` for per-audience JWT access-token TTL
@@ -112,5 +145,7 @@ tags.
 First stable release. Captures the surface produced by the 0.x development
 series; see `git log` for the full history.
 
-[Unreleased]: https://github.com/codeheadsystems/pk-auth/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/codeheadsystems/pk-auth/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/codeheadsystems/pk-auth/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/codeheadsystems/pk-auth/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/codeheadsystems/pk-auth/releases/tag/v1.0.0

gradle.properties

@@ -21,4 +21,4 @@ org.gradle.jvmargs=-Xmx2g \
 
 # Project identity
 group=com.codeheadsystems
-version=1.1.0-SNAPSHOT
+version=1.2.0-SNAPSHOT

pk-auth-jwt/src/main/java/com/codeheadsystems/pkauth/jwt/PkAuthJwtValidator.java

@@ -45,6 +45,7 @@ public final class PkAuthJwtValidator {
   private final ClockProvider clockProvider;
   private final RevocationCheck revocationCheck;
   private final AccessTokenStore accessTokenStore;
+  private final boolean statefulStore;
 
   /**
    * Constructs a validator with no-op revocation and no-op access-token store (tokens are valid
@@ -88,6 +89,7 @@ public PkAuthJwtValidator(
     this.clockProvider = Objects.requireNonNull(clockProvider, "clockProvider");
     this.revocationCheck = Objects.requireNonNull(revocationCheck, "revocationCheck");
     this.accessTokenStore = Objects.requireNonNull(accessTokenStore, "accessTokenStore");
+    this.statefulStore = accessTokenStore != NoopAccessTokenStore.INSTANCE;
   }
 
   /** Verifies signature and standard claims, then reconstructs a {@link JwtClaims}. */
@@ -167,10 +169,18 @@ public JwtVerificationResult validate(String token) {
     if (revocationCheck.isRevoked(jti, subject)) {
       return new JwtVerificationResult.Revoked(jti, subject);
     }
-    if (jti != null && !accessTokenStore.exists(jti)) {
-      // Stateful mode: the token's jti is not in the store (logout / admin-revoke / never
-      // recorded). The noop store always returns true so stateless deployments skip this branch.
-      return new JwtVerificationResult.Revoked(jti, subject);
+    if (statefulStore) {
+      // Stateful mode: every token we issue carries a jti recorded in the store. A token without a
+      // jti can't be checked against the store, so it can't be proven un-revoked — reject it rather
+      // than letting it bypass the revocation gate entirely. (The noop store leaves statefulStore
+      // false, so stateless deployments skip this branch and remain valid-until-exp.)
+      if (jti == null) {
+        return new JwtVerificationResult.MissingClaim("jti");
+      }
+      if (!accessTokenStore.exists(jti)) {
+        // jti not in the store: logout / admin-revoke / never recorded.
+        return new JwtVerificationResult.Revoked(jti, subject);
+      }
     }
 
     String methodClaim = stringClaim(body, PkAuthJwtIssuer.CLAIM_METHOD);

pk-auth-magic-link/src/main/java/com/codeheadsystems/pkauth/magiclink/MagicLinkService.java

@@ -225,13 +225,20 @@ public SendResult startEmailVerification(UserHandle user, String email) {
   /**
    * Sends a login email to the user with the supplied username.
    *
-   * <p><strong>Privacy invariant:</strong> this method ALWAYS returns {@link SendResult.Sent},
-   * regardless of whether the supplied username exists in the system. When no user is found the
-   * method returns early (skipping JWT issuance and email dispatch) but returns the same {@code
-   * Sent} shape as a successful send. This prevents account-enumeration via both result-shape
-   * side-channels and timing side-channels that would otherwise reveal whether an account exists.
-   * Callers MUST NOT rely on a {@link SendResult.UserNotFound} outcome from this method — that
-   * variant is produced only by signup flows where confirming account non-existence is intentional.
+   * <p><strong>Privacy invariant (result-shape only):</strong> this method ALWAYS returns {@link
+   * SendResult.Sent}, regardless of whether the supplied username exists in the system. When no
+   * user is found the method returns early (skipping JWT issuance and email dispatch) but returns
+   * the same {@code Sent} shape as a successful send, so the response body never reveals whether an
+   * account exists. Callers MUST NOT rely on a {@link SendResult.UserNotFound} outcome from this
+   * method — that variant is produced only by signup flows where confirming account non-existence
+   * is intentional.
+   *
+   * <p><strong>This method is NOT constant-time.</strong> The not-found path returns before JWT
+   * issuance and the (typically blocking) email dispatch, so a known username incurs measurably
+   * more latency than an unknown one; an attacker who can time responses can still enumerate
+   * accounts. Equalising this is impractical at the library layer because SMTP/transport latency
+   * dominates and varies — hosts that need timing-side-channel resistance should front this with a
+   * uniform-latency wrapper or rate-limit and monitor for enumeration probing.
    *
    * @since 0.9.1
    */

pk-auth-persistence-dynamodb/src/main/java/com/codeheadsystems/pkauth/persistence/dynamodb/DynamoDbRefreshTokenRepository.java

@@ -138,12 +138,18 @@ public boolean rotateAtomically(
 
           // Transact: conditional update on parent primary (still fresh) + put successor items.
           // ConditionExpression — fresh iff used_at, revoked_at unset and expires_at > now.
+          // Expiry compares the numeric epoch-second `ttl` attribute (== expiresAt.epochSecond),
+          // NOT the ISO string: Instant.toString() is variable-precision (it drops the
+          // fractional-seconds field when zero), so a lexicographic ">" sorts "...:00Z" after
+          // "...:00.000001Z" and would treat an expired token as still fresh.
           Expression freshness =
               Expression.builder()
                   .expression(
                       "attribute_not_exists(usedAtIso) AND attribute_not_exists(revokedAtIso)"
-                          + " AND expiresAtIso > :now")
-                  .putExpressionValue(":now", AttributeValue.fromS(nowIso))
+                          + " AND #ttl > :nowEpoch")
+                  .putExpressionName("#ttl", "ttl")
+                  .putExpressionValue(
+                      ":nowEpoch", AttributeValue.fromN(Long.toString(now.getEpochSecond())))
                   .build();
 
           try {