Bound the decoded string and bytes payload per lookup

A crafted database can point many data-section pointers at one large
string or bytes value. The value count stays low, but a decoder that
copies each target materializes the value once per pointer, so a file
of a few hundred kilobytes can force gigabytes.

The decoder now charges each string and bytes value its length as it is
decoded and rejects a single lookup that materializes more than 2 MiB,
with an InvalidDatabaseException. Because the charge is made every time
a value is decoded, re-decoding a shared pointer target recharges it, so
the amplification is bounded. Charging before allocation also bounds an
oversized variable-length integer, whose declared size the decoder would
otherwise copy before range-checking. Map keys and inline scalars in a
pointed-to container decode through the same path, so they are charged
too. Metadata is decoded through the same path, so the bound covers the
database-open path as well.

The counter is a per-lookup field on the per-lookup decoder, so
concurrent reads stay thread-safe and the common path stays cheap: small
fixed-width scalars are not charged. This matches the 2 MiB payload limit
used by libmaxminddb and the Go reader. See GHSA-hj94-g986-h9r7.

The test-data submodule is bumped to the MaxMind-DB commit that adds the
payload amplification and boundary fixtures.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: oschwald

CHANGELOG.md

@@ -17,9 +17,12 @@ CHANGELOG
   exceeds it, along with pointer cycles and over-deep data, with an
   `InvalidDatabaseException`. It also rejects a map or array whose declared size
   is larger than the remaining data before allocating for it, so a crafted size
-  cannot force a large list or map allocation from a small file. This matches
-  the reader resource limits now recommended by the MaxMind DB specification.
-  See GHSA-hj94-g986-h9r7.
+  cannot force a large list or map allocation from a small file. A related shape
+  points many pointers at one large string or bytes value; the decoder now
+  bounds the total string and bytes payload it materializes for a single record,
+  charging each value as it is decoded, so re-decoding a shared target cannot
+  amplify a small file into gigabytes. This matches the reader resource limits
+  now recommended by the MaxMind DB specification. See GHSA-hj94-g986-h9r7.
 
 4.1.0 (2026-05-12)
 ------------------

src/main/java/com/maxmind/db/Decoder.java

@@ -9,7 +9,6 @@
 import java.lang.reflect.ParameterizedType;
 import java.math.BigInteger;
 import java.net.InetAddress;
-import java.nio.charset.CharacterCodingException;
 import java.nio.charset.Charset;
 import java.nio.charset.CharsetDecoder;
 import java.nio.charset.StandardCharsets;
@@ -38,13 +37,19 @@ class Decoder {
     // Per-lookup decode limits recommended by the MaxMind DB specification. The
     // depth limit stops pointer cycles and over-deep data before the stack
     // overflows. The value limit stops a pointer fan-out, where nested pointers
-    // to shared targets would otherwise cost 2**depth decode operations. A
-    // Decoder serves a single lookup on a single thread, so these need no
-    // synchronization. The largest real records decode a few hundred values.
+    // to shared targets would otherwise cost 2**depth decode operations. The
+    // payload limit stops a payload amplification, where many pointers to one
+    // large string or bytes value would otherwise materialize N times its size:
+    // each string or bytes value is charged its length every time it is decoded,
+    // so re-decoding a shared target recharges it. A Decoder serves a single
+    // lookup on a single thread, so these need no synchronization. The largest
+    // real records decode a few hundred values and a few kilobytes of payload.
     private static final int MAX_DEPTH = 512;
     private static final int MAX_VALUES = 1 << 16;
+    private static final long MAX_PAYLOAD_BYTES = 1 << 21;
     private int depth;
     private int valuesRemaining = MAX_VALUES;
+    private long payloadRemaining = MAX_PAYLOAD_BYTES;
 
     private final long pointerBase;
 
@@ -116,6 +121,7 @@ <T> T decode(long offset, Class<T> cls) throws IOException {
         }
 
         this.valuesRemaining = MAX_VALUES;
+        this.payloadRemaining = MAX_PAYLOAD_BYTES;
         this.depth = 0;
         this.buffer.position(offset);
         return cls.cast(decode(cls, null).value());
@@ -269,6 +275,24 @@ private void checkContainerSize(long valueCount) throws InvalidDatabaseException
         }
     }
 
+    // Charge a string or bytes payload against the per-lookup budget before it
+    // is materialized. A payload amplification points many pointers at one large
+    // value; because the budget is charged every time the value is decoded, and
+    // a shared pointer target is re-decoded per referencing pointer, N pointers
+    // to an S-byte value are charged N*S and rejected once the total exceeds the
+    // limit. Charging before allocation also bounds an oversized variable-length
+    // integer, whose declared size the decoder would otherwise copy before
+    // range-checking. The comparison is against the remaining budget so it
+    // cannot overflow. The limit is inclusive: a total exactly at the limit is
+    // allowed.
+    private void chargePayload(long length) throws InvalidDatabaseException {
+        if (length > this.payloadRemaining) {
+            throw new InvalidDatabaseException(
+                "The MaxMind DB file's data section exceeds the maximum payload size");
+        }
+        this.payloadRemaining -= length;
+    }
+
     private <T> Object decodeByType(
         Type type,
         int size,
@@ -445,7 +469,8 @@ private static Object coerceFromBigInteger(BigInteger value, Class<?> target) {
         return value;
     }
 
-    private String decodeString(long size) throws CharacterCodingException {
+    private String decodeString(long size) throws IOException {
+        this.chargePayload(size);
         var oldLimit = buffer.limit();
         buffer.limit(buffer.position() + size);
         var s = buffer.decode(utfDecoder);
@@ -493,7 +518,7 @@ static int decodeInteger(Buffer buffer, int base, int size) {
         return integer;
     }
 
-    private BigInteger decodeBigInteger(int size) {
+    private BigInteger decodeBigInteger(int size) throws InvalidDatabaseException {
         var bytes = this.getByteArray(size);
         return new BigInteger(1, bytes);
     }
@@ -1269,7 +1294,8 @@ private CtrlData getCtrlData(long offset)
         return new CtrlData(type, ctrlByte, offset, size);
     }
 
-    private byte[] getByteArray(int length) {
+    private byte[] getByteArray(int length) throws InvalidDatabaseException {
+        this.chargePayload(length);
         return Decoder.getByteArray(this.buffer, length);
     }
 

src/test/java/com/maxmind/db/DecoderTest.java

@@ -571,6 +571,57 @@ public void testAcyclicPointerToPointerThrows() {
         assertThat(ex.getMessage(), containsString("pointer to a pointer"));
     }
 
+    // Writes a large scalar (bytes or string) at offset 0, followed by an array
+    // of pointerCount one-byte pointers that all target it. Every pointer
+    // re-decodes the shared value, so the decoder is charged its size once per
+    // pointer even though the value count stays tiny.
+    private static byte[] sharedScalarFanOut(int scalarType, int scalarSize, int pointerCount) {
+        var out = new ByteArrayOutputStream();
+        // Scalar header: size code 30 covers 285..65820 bytes.
+        out.write((scalarType << 5) | 30);
+        var encoded = scalarSize - 285;
+        out.write((encoded >> 8) & 0xFF);
+        out.write(encoded & 0xFF);
+        for (var i = 0; i < scalarSize; i++) {
+            out.write(0);
+        }
+        // Array header (extended type 11), size code 29 covers 29..284 entries.
+        out.write(29);
+        out.write(0x04);
+        out.write(pointerCount - 29);
+        for (var i = 0; i < pointerCount; i++) {
+            writePointer1(out, 0);
+        }
+        return out.toByteArray();
+    }
+
+    @Test
+    public void testPayloadAmplificationIsBounded() throws IOException {
+        // 33 pointers to a 65,536-byte value would materialize just over 2 MiB,
+        // one byte value at a time, while the value count stays tiny. Only the
+        // payload byte bound rejects this.
+        var scalarSize = 1 << 16;
+        var data = sharedScalarFanOut(4, scalarSize, 33);
+        var top = 3 + scalarSize;
+        var decoder = new Decoder(NoCache.getInstance(), SingleBuffer.wrap(data), 0);
+        var ex = assertThrows(
+                InvalidDatabaseException.class,
+                () -> decoder.decode(top, Object.class));
+        assertThat(ex.getMessage(), containsString("exceeds the maximum payload size"));
+    }
+
+    @Test
+    public void testPayloadAtLimitIsAccepted() throws IOException {
+        // 32 pointers to a 65,536-byte value materialize exactly 2 MiB, at the
+        // inclusive limit, so the record must still decode.
+        var scalarSize = 1 << 16;
+        var data = sharedScalarFanOut(4, scalarSize, 32);
+        var top = 3 + scalarSize;
+        var decoder = new Decoder(NoCache.getInstance(), SingleBuffer.wrap(data), 0);
+        var result = (List<?>) decoder.decode(top, Object.class);
+        assertEquals(32, result.size());
+    }
+
     public static final class EmptyModel {
         @MaxMindDbConstructor
         public EmptyModel() {

src/test/java/com/maxmind/db/ReaderTest.java

@@ -2203,6 +2203,50 @@ public void testNullToPrimitiveErrorMessage(int chunkSize) throws IOException {
         }
     }
 
+    // A crafted database can point many data-section pointers at one large
+    // string or bytes value. The value count stays low, but a decoder that
+    // copies each pointer's target materializes N times its size. Decoding must
+    // reject each of these before it exhausts memory.
+    @Test
+    public void testPayloadAmplificationIsRejected() throws IOException {
+        var fixtures = new String[] {
+            "MaxMind-DB-test-payload-amplification-dos.mmdb",
+            "MaxMind-DB-test-payload-amplification-dos-string.mmdb",
+            "MaxMind-DB-test-payload-amplification-dos-worst-case.mmdb",
+            "MaxMind-DB-test-decoder-payload-limit-over.mmdb",
+        };
+        var ip = InetAddress.getByName("1.1.1.1");
+        for (var fixture : fixtures) {
+            try (var reader = new Reader(getFile(fixture))) {
+                var ex = assertThrows(
+                    InvalidDatabaseException.class,
+                    () -> reader.get(ip, Object.class),
+                    fixture + " should be rejected");
+                assertThat(ex.getMessage(), containsString("exceeds the maximum payload size"));
+            }
+        }
+    }
+
+    // A payload total that lands exactly on the 2 MiB limit is valid and must
+    // still decode, so the bound does not reject legitimate data.
+    @Test
+    public void testPayloadAtLimitDecodes() throws IOException {
+        try (var reader = new Reader(getFile("MaxMind-DB-test-decoder-payload-limit.mmdb"))) {
+            var value = reader.get(InetAddress.getByName("1.1.1.1"), Object.class);
+            assertNotNull(value);
+        }
+    }
+
+    // Metadata is decoded while the database is opened, so the payload bound must
+    // cover that path too. This fixture amplifies a string through the metadata.
+    @Test
+    public void testMetadataPayloadAmplificationIsRejected() {
+        var ex = assertThrows(
+            InvalidDatabaseException.class,
+            () -> new Reader(getFile("MaxMind-DB-test-metadata-payload-limit.mmdb")));
+        assertThat(ex.getMessage(), containsString("exceeds the maximum payload size"));
+    }
+
     static File getFile(String name) {
         return new File(ReaderTest.class.getResource("/maxmind-db/test-data/" + name).getFile());
     }