document-haness/docs/clean-architecture-backend-template/final/evidence/raw/040-persistence-jpa-api-history.txt

Command: git history for cursor/capability/entity-not-found API hotspots
Working directory: /shared/codebase/clean-architecture-backend-template
Executed at: 2026-08-29T07:50:26Z
Source revision: a24ece9cf797f7ea647e33bf846b115208ed1ba5
Observation boundary: Repository history for the three selected API hotspots; commit text/diffs show when code entered or changed but do not establish unstated author intent.
--- stdout/stderr ---
=== SignedJsonCursorCodec history ===
2f5d2fc feat: jpa, messaging, notification, mongo, graphql 어댑터터 구현체 추가
0e61f86 feat(jpa): implement the JPA relational persistence platform
=== decodedLengthOf introducing diff ===
COMMIT 2f5d2fc21954286213c1474d19935f571ef896ea feat: jpa, messaging, notification, mongo, graphql 어댑터터 구현체 추가

diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/query/SignedJsonCursorCodec.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/query/SignedJsonCursorCodec.java
index 0263e77..7c306cd 100644
--- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/query/SignedJsonCursorCodec.java
+++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/query/SignedJsonCursorCodec.java
@@ -50,13 +50,33 @@ public final class SignedJsonCursorCodec<C> implements CursorCodec<C> {
     this.key = key.clone();
   }
 
+  /** Longest token this codec will look at, in characters. */
+  public static final int MAX_ENCODED_LENGTH = 4096;
+
+  /** Largest payload this codec will decode, in bytes. */
+  public static final int MAX_PAYLOAD_BYTES = 2048;
+
+  /** HMAC-SHA256 produces exactly this many bytes. */
+  private static final int MAC_LENGTH_BYTES = 32;
+
   @Override
   public String encode(C cursor) {
     Objects.requireNonNull(cursor, "cursor");
-    String payload =
-        encoder.encodeToString(payloadCodec.toJson(cursor).getBytes(StandardCharsets.UTF_8));
+    byte[] json = payloadCodec.toJson(cursor).getBytes(StandardCharsets.UTF_8);
+    if (json.length > MAX_PAYLOAD_BYTES) {
+      // The application's own bug, not a caller's: a cursor this large is a payload the codec
+      // cannot hand back, so producing it would mint a token that fails on the next page.
+      throw new IllegalStateException(
+          "cursor payload is " + json.length + " bytes; the bound is " + MAX_PAYLOAD_BYTES);
+    }
+    String payload = encoder.encodeToString(json);
     String signed = VERSION + SEPARATOR + payload;
-    return signed + SEPARATOR + encoder.encodeToString(mac(signed));
+    String token = signed + SEPARATOR + encoder.encodeToString(mac(signed));
+    if (token.length() > MAX_ENCODED_LENGTH) {
+      throw new IllegalStateException(
+          "cursor token is " + token.length() + " characters; the bound is " + MAX_ENCODED_LENGTH);
+    }
+    return token;
   }
 
   @Override
@@ -64,6 +84,13 @@ public final class SignedJsonCursorCodec<C> implements CursorCodec<C> {
     if (encoded == null || encoded.isBlank()) {
       throw new IllegalArgumentException("cursor must not be blank");
     }
+    // First line, before any substring, decode or MAC. A paging endpoint is public, and everything
+    // below this point allocates in proportion to what the caller sent: repeatedly posting a very
+    // large token made the server build strings, byte arrays and a MAC input before it had any
+    // reason to believe the token was real. A page-size bound does not bound the token.
+    if (encoded.length() > MAX_ENCODED_LENGTH) {
+      throw new IllegalArgumentException("cursor exceeds the maximum token length");
+    }
     int payloadSeparator = encoded.indexOf(SEPARATOR);
     int macSeparator = encoded.lastIndexOf(SEPARATOR);
     if (payloadSeparator <= 0 || macSeparator <= payloadSeparator) {
@@ -73,15 +100,33 @@ public final class SignedJsonCursorCodec<C> implements CursorCodec<C> {
     if (!VERSION.equals(version)) {
       throw new IllegalArgumentException("unknown cursor version");
     }
+    // Base64 expands by 4/3, so the encoded payload segment's length bounds the decoded size
+    // exactly. Checking it here refuses an oversized payload without allocating it first.
+    int encodedPayloadLength = macSeparator - payloadSeparator - 1;
+    if (decodedLengthOf(encodedPayloadLength) > MAX_PAYLOAD_BYTES) {
+      throw new IllegalArgumentException("cursor payload exceeds the maximum size");
+    }
     String signed = encoded.substring(0, macSeparator);
     byte[] presented = decodeBase64(encoded.substring(macSeparator + 1));
+    if (presented.length != MAC_LENGTH_BYTES) {
+      // Checked before the comparison. `MessageDigest.isEqual` is constant time for equal-length
+      // inputs; feeding it a differently-sized array asks it a question it was not built to answer.
+      throw new IllegalArgumentException("malformed cursor");
+    }
     if (!MessageDigest.isEqual(mac(signed), presented)) {
       throw new IllegalArgumentException("cursor signature does not verify");
     }
+    // The payload decoder runs only after the signature verified, so an unsigned token never
+    // reaches the application's JSON parsing at all.
     byte[] payload = decodeBase64(encoded.substring(payloadSeparator + 1, macSeparator));
     return payloadCodec.fromJson(new String(payload, StandardCharsets.UTF_8));
   }
 
+  /** The number of bytes a Base64 segment of this many characters decodes to, at most. */
+  private static int decodedLengthOf(int encodedLength) {
+    return encodedLength / 4 * 3 + 3;
+  }
+
   private byte[] decodeBase64(String value) {
     try {
       return decoder.decode(value);
=== CapabilitySupport history ===
0e61f86 feat(jpa): implement the JPA relational persistence platform
=== JpaEntityNotFoundException history ===
0e61f86 feat(jpa): implement the JPA relational persistence platform

Exit code: 0