feat(xdr): add maxLength/maxDepth options to array codec helpers

Author: Ryang-21

src/xdr/index.ts

@@ -40,6 +40,7 @@ export {
   decodeStream,
   encodeArray,
   decodeArray,
+  type XdrArrayOptions,
   type XdrFormat,
   type JsonValue,
   type XdrValueConstructor,

src/xdr/values/xdr-value.ts

@@ -176,6 +176,24 @@ export function decodeStream<Wire, Instance extends XdrValue>(
   return out;
 }
 
+/** Options shared by {@link encodeArray} and {@link decodeArray}. */
+export interface XdrArrayOptions {
+  /**
+   * Largest element count to accept, defaulting to the XDR maximum of
+   * 2^32 - 1. Both encoding and decoding throw `XdrError` past this many
+   * elements. Pass the bound from the XDR definition, so a field declared
+   * `TimeSlicedPeerData peers<25>` decodes with `maxLength: 25`, or any cap
+   * you want to enforce, to reject an oversized array before its elements are
+   * decoded.
+   */
+  maxLength?: number;
+  /**
+   * How many nested schemas may be entered, counting the array itself as the
+   * first level.
+   */
+  maxDepth?: number;
+}
+
 /**
  * Encode a list of XDR values as a single length-prefixed XDR variable-length
  * array (`T values<>` — a 4-byte count followed by the elements). This is the
@@ -188,25 +206,33 @@ export function decodeStream<Wire, Instance extends XdrValue>(
 export function encodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   values: readonly Instance[],
+  options?: XdrArrayOptions,
 ): Uint8Array;
 export function encodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   values: readonly Instance[],
   format: "raw",
+  options?: XdrArrayOptions,
 ): Uint8Array;
 export function encodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   values: readonly Instance[],
   format: "hex" | "base64",
+  options?: XdrArrayOptions,
 ): string;
 export function encodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   values: readonly Instance[],
-  format: XdrFormat = "raw",
+  formatOrOptions?: XdrFormat | XdrArrayOptions,
+  maybeOptions?: XdrArrayOptions,
 ): Uint8Array | string {
-  const codec = array(type.schema, UNBOUNDED_MAX_LENGTH);
-  const bytes = codec.encode(values.map((v) => v.toXdrObject() as Wire));
-  return encodeBytes(bytes, format);
+  const [format, options] = splitArrayArgs(formatOrOptions, maybeOptions);
+  const codec = array(type.schema, options.maxLength ?? UNBOUNDED_MAX_LENGTH);
+  const bytes = codec.encode(
+    values.map((v) => v.toXdrObject() as Wire),
+    { maxDepth: options.maxDepth },
+  );
+  return encodeBytes(bytes, format ?? "raw");
 }
 
 /**
@@ -219,22 +245,42 @@ export function encodeArray<Wire, Instance extends XdrValue>(
 export function decodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   input: Uint8Array,
+  options?: XdrArrayOptions,
 ): Instance[];
 export function decodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   input: string,
   format: "hex" | "base64",
+  options?: XdrArrayOptions,
 ): Instance[];
 export function decodeArray<Wire, Instance extends XdrValue>(
   type: XdrValueConstructor<Wire, Instance>,
   input: Uint8Array | string,
-  format?: "hex" | "base64",
+  formatOrOptions?: "hex" | "base64" | XdrArrayOptions,
+  maybeOptions?: XdrArrayOptions,
 ): Instance[] {
-  const codec = array(type.schema, UNBOUNDED_MAX_LENGTH);
-  const wires = codec.decode(decodeBytes(input, format));
+  const [format, options] = splitArrayArgs(formatOrOptions, maybeOptions);
+  const codec = array(type.schema, options.maxLength ?? UNBOUNDED_MAX_LENGTH);
+  const wires = codec.decode(
+    decodeBytes(input, format as "hex" | "base64" | undefined),
+    { maxDepth: options.maxDepth },
+  );
   return wires.map((w) => type.fromXdrObject(w));
 }
 
+/**
+ * Sort out the trailing `(format?, options?)` arguments of the array helpers,
+ * where the format may be omitted and the options object take its place.
+ */
+function splitArrayArgs(
+  formatOrOptions?: XdrFormat | XdrArrayOptions,
+  maybeOptions?: XdrArrayOptions,
+): [XdrFormat | undefined, XdrArrayOptions] {
+  return typeof formatOrOptions === "string"
+    ? [formatOrOptions, maybeOptions ?? {}]
+    : [undefined, formatOrOptions ?? maybeOptions ?? {}];
+}
+
 export function encodeBytes(
   bytes: Uint8Array,
   format: XdrFormat,

test/unit/xdr/array_codec.test.ts

@@ -53,4 +53,77 @@ describe("encodeArray / decodeArray", () => {
     const padded = new Uint8Array([...bytes, 0, 0, 0, 0]);
     expect(() => decodeArray(ScVal, padded)).toThrow(XdrError);
   });
+
+  describe("maxLength", () => {
+    it("accepts a list at the limit", () => {
+      const bytes = encodeArray(ScVal, values, { maxLength: 3 });
+      const decoded = decodeArray(ScVal, bytes, { maxLength: 3 });
+      decoded.forEach((v, i) => expect(v.equals(values[i])).toBe(true));
+    });
+
+    it("rejects encoding more elements than the limit", () => {
+      expect(() => encodeArray(ScVal, values, { maxLength: 2 })).toThrow(
+        XdrError,
+      );
+      expect(() =>
+        encodeArray(ScVal, values, "base64", { maxLength: 2 }),
+      ).toThrow(XdrError);
+    });
+
+    it("rejects decoding a count past the limit", () => {
+      const bytes = encodeArray(ScVal, values);
+      expect(() => decodeArray(ScVal, bytes, { maxLength: 2 })).toThrow(
+        XdrError,
+      );
+
+      const b64 = encodeArray(ScVal, values, "base64");
+      expect(() => decodeArray(ScVal, b64, "base64", { maxLength: 2 })).toThrow(
+        XdrError,
+      );
+    });
+
+    it("rejects an inflated count before reading any element", () => {
+      // A 4-byte header claiming 2^31 elements over an otherwise empty body:
+      // the count check must fire instead of allocating for the claim.
+      const bogus = new Uint8Array([0x7f, 0xff, 0xff, 0xff]);
+      expect(() => decodeArray(ScVal, bogus, { maxLength: 16 })).toThrow(
+        XdrError,
+      );
+    });
+  });
+
+  describe("maxDepth", () => {
+    /** An `ScVal` vector nested `depth` levels deep around a u32. */
+    const nest = (depth: number): ScVal => {
+      let v: ScVal = ScVal.scvU32(1);
+      for (let i = 0; i < depth; i++) v = ScVal.scvVec([v]);
+      return v;
+    };
+
+    it("rejects encoding past the limit", () => {
+      expect(() => encodeArray(ScVal, [nest(8)], { maxDepth: 4 })).toThrow(
+        XdrError,
+      );
+    });
+
+    it("rejects decoding past the limit", () => {
+      const bytes = encodeArray(ScVal, [nest(8)]);
+      expect(() => decodeArray(ScVal, bytes, { maxDepth: 4 })).toThrow(
+        XdrError,
+      );
+      // Same bytes, same helper — only the cap makes them unacceptable.
+      expect(decodeArray(ScVal, bytes)).toHaveLength(1);
+    });
+
+    it("counts the array itself as a level", () => {
+      // Flat elements, so a cap of 1 leaves no room past the array itself.
+      // (How many levels a given element costs is a js-xdr detail — an
+      // ScVal union arm nests through option/array/lazy wrappers.)
+      const bytes = encodeArray(ScVal, values);
+      expect(() => decodeArray(ScVal, bytes, { maxDepth: 1 })).toThrow(
+        XdrError,
+      );
+      expect(decodeArray(ScVal, bytes, { maxDepth: 2 })).toHaveLength(3);
+    });
+  });
 });