@superblocksteam/sdk-api 2.0.165-next.0 → 2.0.166-next.0

package/src/integrations/base/request-body.test.ts

@@ -0,0 +1,565 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { RestApiValidationError } from "../../errors.js";
+import { encodeRequestBody } from "./request-body.js";
+
+const PNG_BYTES = [137, 80, 78, 71];
+const PNG_BASE64 = Buffer.from(PNG_BYTES).toString("base64");
+
+function arrayBufferFrom(bytes: readonly number[]): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.length);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+describe("encodeRequestBody", () => {
+  it("preserves default and explicit JSON wire behavior", () => {
+    expect(encodeRequestBody({ body: undefined })).toEqual({ wire: {} });
+    expect(encodeRequestBody({ body: undefined, bodyType: "json" })).toEqual({
+      wire: {},
+    });
+    expect(encodeRequestBody({ body: { amount: 42 } })).toEqual({
+      wire: { body: JSON.stringify({ amount: 42 }), bodyType: "jsonBody" },
+    });
+    expect(
+      encodeRequestBody({ body: { amount: 42 }, bodyType: "json" }),
+    ).toEqual({
+      wire: { body: JSON.stringify({ amount: 42 }), bodyType: "jsonBody" },
+    });
+    expect(encodeRequestBody({ body: "plain text" })).toEqual({
+      wire: { body: '"plain text"', bodyType: "jsonBody" },
+    });
+    expect(encodeRequestBody({ body: null })).toEqual({
+      wire: { body: "null", bodyType: "jsonBody" },
+    });
+  });
+
+  it("rejects invalid JSON and bodyType inputs", () => {
+    expect(() =>
+      encodeRequestBody({ body: Uint8Array.from(PNG_BYTES) }),
+    ).toThrow(/bodyType: "binary"/);
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(() => encodeRequestBody({ body: circular })).toThrow(
+      /the body contains a circular reference/,
+    );
+    expect(() => encodeRequestBody({ body: 1n })).toThrow(
+      /not JSON-serializable/,
+    );
+    for (const body of [() => undefined, Symbol("token")]) {
+      expect(() => encodeRequestBody({ body })).toThrow(RestApiValidationError);
+      expect(() => encodeRequestBody({ body })).toThrow(/cannot serialize a/);
+    }
+    for (const bodyType of [
+      "jsonBody",
+      "rawBody",
+      "formData",
+      "fileForm",
+      "binaryBody",
+      "formDataBase64",
+    ]) {
+      expect(() => encodeRequestBody({ body: {}, bodyType })).toThrow(
+        new RegExp(`Unsupported bodyType ${JSON.stringify(bodyType)}`),
+      );
+    }
+    // Only an omitted bodyType defaults to "json"; an explicit null is an
+    // invalid value like any other, not a synonym for omission.
+    expect(() => encodeRequestBody({ body: {}, bodyType: null })).toThrow(
+      /Unsupported bodyType null/,
+    );
+  });
+
+  it("classifies a circular body under both V8's and QuickJS's JSON.stringify wording", () => {
+    // Node/V8 throws "Converting circular structure to JSON"; the QuickJS
+    // sandbox sdk-api actually runs in throws "circular reference"
+    // (workers/javascript/packages/quickjs-emscripten vendored quickjs.c).
+    // Both must classify as the same bounded message.
+    for (const message of [
+      "Converting circular structure to JSON",
+      "circular reference",
+    ]) {
+      const stringifySpy = vi
+        .spyOn(JSON, "stringify")
+        .mockImplementationOnce(() => {
+          throw new TypeError(message);
+        });
+      expect(() => encodeRequestBody({ body: {} })).toThrow(
+        /the body contains a circular reference/,
+      );
+      stringifySpy.mockRestore();
+    }
+  });
+
+  it("rejects binary nested inside a JSON body (APPS-2739)", () => {
+    expect(() =>
+      encodeRequestBody({
+        body: { attributes: "{}", file: Uint8Array.from(PNG_BYTES) },
+      }),
+    ).toThrow(
+      /contains binary data at "file"; send file parts with bodyType: "multipartForm"/,
+    );
+    expect(() =>
+      encodeRequestBody({
+        body: {
+          attachments: [{ name: "a" }, { bytes: arrayBufferFrom(PNG_BYTES) }],
+        },
+      }),
+    ).toThrow(/contains binary data at "attachments\.1\.bytes"/);
+  });
+
+  it("rejects binary nested inside a Map or Set value in a JSON body", () => {
+    expect(() =>
+      encodeRequestBody({
+        body: { file: new Map([["bytes", Uint8Array.from(PNG_BYTES)]]) },
+      }),
+    ).toThrow(/contains binary data/);
+    expect(() =>
+      encodeRequestBody({
+        body: { file: new Set([Uint8Array.from(PNG_BYTES)]) },
+      }),
+    ).toThrow(/contains binary data/);
+  });
+
+  it("fails closed instead of silently serializing binary past the scan depth cap", () => {
+    let body: unknown = Uint8Array.from(PNG_BYTES);
+    for (let depth = 0; depth < 105; depth++) {
+      body = { child: body };
+    }
+    expect(() => encodeRequestBody({ body })).toThrow(/contains binary data/);
+  });
+
+  it("bounds the message when a nested getter throws during JSON serialization", () => {
+    const throwingGetter = {
+      get secret(): string {
+        throw new Error("getter boom");
+      },
+    };
+    expect(() => encodeRequestBody({ body: throwingGetter })).toThrow(
+      /not JSON-serializable: a nested value's toJSON, toString, or getter threw/,
+    );
+    let message = "";
+    try {
+      encodeRequestBody({ body: throwingGetter });
+    } catch (error) {
+      message = error instanceof Error ? error.message : "";
+    }
+    expect(message).not.toContain("getter boom");
+  });
+
+  it("keeps caller keys in validation messages bounded and escaped", () => {
+    const longKey = "k".repeat(500);
+    const surrogateKey = "bad\uD800key";
+    const cases: {
+      body: Record<string, unknown>;
+      bodyType: string;
+      expected: RegExp;
+    }[] = [
+      {
+        body: { [longKey]: { nested: true } },
+        bodyType: "formUrlencoded",
+        expected: /is nested/,
+      },
+      {
+        body: { [surrogateKey]: "v" },
+        bodyType: "formUrlencoded",
+        expected: /lone surrogate/,
+      },
+      {
+        body: { [longKey]: Uint8Array.from(PNG_BYTES) },
+        bodyType: "multipartForm",
+        expected: /wrapped as/,
+      },
+      {
+        body: { [surrogateKey]: { value: "x", filename: "f", [longKey]: 1 } },
+        bodyType: "multipartForm",
+        expected: /unexpected key/,
+      },
+    ];
+    for (const { body, bodyType, expected } of cases) {
+      let message = "";
+      try {
+        encodeRequestBody({ body, bodyType });
+      } catch (error) {
+        expect(error).toBeInstanceOf(RestApiValidationError);
+        message = error instanceof Error ? error.message : "";
+      }
+      expect(message).toMatch(expected);
+      expect(message).not.toContain("k".repeat(65));
+      expect(message).not.toContain("\uD800");
+      expect(message.length).toBeLessThan(400);
+    }
+  });
+
+  it("keeps unsupported bodyType messages bounded and free of caller data", () => {
+    expect(() =>
+      encodeRequestBody({ body: {}, bodyType: "x".repeat(500) }),
+    ).toThrow(`"${"x".repeat(64)}..."`);
+    for (const bodyType of [
+      new Uint8Array(50_000),
+      { secret: "s".repeat(1000) },
+    ]) {
+      let caught: unknown;
+      try {
+        encodeRequestBody({ body: {}, bodyType });
+      } catch (error) {
+        caught = error;
+      }
+      if (!(caught instanceof RestApiValidationError)) throw caught;
+      const message = caught.message;
+      expect(message).toMatch(
+        /^Unsupported bodyType (binary data \(50000 bytes\)|object with keys \[secret\])/,
+      );
+      expect(message).not.toContain("s".repeat(10));
+      expect(message.length).toBeLessThan(200);
+      // The mismatch branch must not bypass the module's bounded-error
+      // convention: details.data stays undefined and details.zodError
+      // carries only the already-bounded message, never the raw caller value.
+      expect(caught.details.data).toBeUndefined();
+      const detailMessage = caught.details.zodError.issues[0].message;
+      expect(detailMessage).toBe(message);
+      expect(JSON.stringify(caught.details)).not.toContain("s".repeat(10));
+    }
+  });
+
+  it("bounds caller keys embedded in the zod issue path, not just the message", () => {
+    const longKey = "k".repeat(500);
+    let caught: unknown;
+    try {
+      encodeRequestBody({
+        body: { [longKey]: { nested: true } },
+        bodyType: "formUrlencoded",
+      });
+    } catch (error) {
+      caught = error;
+    }
+    if (!(caught instanceof RestApiValidationError)) throw caught;
+    const path = caught.details.zodError.issues[0].path;
+    expect(JSON.stringify(path)).not.toContain("k".repeat(65));
+    expect(path).toEqual(["body", `${"k".repeat(64)}...`]);
+  });
+
+  it("bounds long keys inside describeOptionValue's object description", () => {
+    const longKey = "k".repeat(10_000);
+    let message = "";
+    try {
+      encodeRequestBody({ body: {}, bodyType: { [longKey]: 1 } });
+    } catch (error) {
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      message = error instanceof Error ? error.message : "";
+    }
+    expect(message).toMatch(/^Unsupported bodyType object with keys/);
+    expect(message).not.toContain("k".repeat(65));
+    expect(message.length).toBeLessThan(200);
+  });
+
+  it("bounds the unexpected-keys list in multipart file-part errors", () => {
+    const extraKeys = Object.fromEntries(
+      Array.from({ length: 50 }, (_, i) => [`extra${i}`, i]),
+    );
+    let message = "";
+    try {
+      encodeRequestBody({
+        body: { file: { value: "hello", filename: "f.txt", ...extraKeys } },
+        bodyType: "multipartForm",
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      message = error instanceof Error ? error.message : "";
+    }
+    expect(message).toMatch(/unexpected keys/);
+    expect(message).toContain(", ...");
+    expect(message.length).toBeLessThan(400);
+  });
+
+  it("passes raw non-empty string bodies through unchanged", () => {
+    expect(
+      encodeRequestBody({ body: "<note>hello</note>", bodyType: "raw" }),
+    ).toEqual({
+      wire: { body: "<note>hello</note>", bodyType: "rawBody" },
+    });
+    expect(() => encodeRequestBody({ body: "", bodyType: "raw" })).toThrow(
+      RestApiValidationError,
+    );
+    expect(() =>
+      encodeRequestBody({ body: { value: "hello" }, bodyType: "raw" }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("encodes form-urlencoded bodies and injects Content-Type only when absent", () => {
+    expect(
+      encodeRequestBody({
+        body: {
+          amount: 2000,
+          currency: "usd",
+          empty: [],
+          enabled: true,
+          optional: undefined,
+          "metadata[order_id]": "6735",
+          tag: ["vip", "repeat"],
+        },
+        bodyType: "formUrlencoded",
+      }),
+    ).toEqual({
+      wire: {
+        body: "amount=2000&currency=usd&enabled=true&metadata%5Border_id%5D=6735&tag=vip&tag=repeat",
+        bodyType: "rawBody",
+      },
+      contentType: "application/x-www-form-urlencoded",
+    });
+    expect(
+      encodeRequestBody({
+        body: { amount: 2000 },
+        bodyType: "formUrlencoded",
+        headers: { "content-type": "application/custom-form" },
+      }),
+    ).toEqual({
+      wire: { body: "amount=2000", bodyType: "rawBody" },
+    });
+  });
+
+  it("drops undefined items from form-urlencoded array values, matching multipart semantics", () => {
+    expect(
+      encodeRequestBody({
+        body: { tags: ["a", undefined, "b"] },
+        bodyType: "formUrlencoded",
+      }).wire.body,
+    ).toBe("tags=a&tags=b");
+    // An array of only undefined items leaves no pairs, same as an empty array.
+    expect(() =>
+      encodeRequestBody({
+        body: { tags: [undefined, undefined] },
+        bodyType: "formUrlencoded",
+      }),
+    ).toThrow(/must encode at least one field/);
+  });
+
+  it("percent-encodes form-urlencoded keys and values with + for spaces", () => {
+    expect(
+      encodeRequestBody({
+        body: {
+          "odd key": "a+b=c&d",
+          scope: "read:orders write:orders",
+          unicode: "caf\u00e9 \u{1F600}",
+        },
+        bodyType: "formUrlencoded",
+      }).wire.body,
+    ).toBe(
+      "odd+key=a%2Bb%3Dc%26d&scope=read%3Aorders+write%3Aorders&unicode=caf%C3%A9+%F0%9F%98%80",
+    );
+  });
+
+  it("percent-encodes characters encodeURIComponent leaves literal but URLSearchParams escapes", () => {
+    expect(
+      encodeRequestBody({
+        body: { "a!b'c(d)e~f*g": "h!i'j(k)l~m*n" },
+        bodyType: "formUrlencoded",
+      }).wire.body,
+    ).toBe("a%21b%27c%28d%29e%7Ef*g=h%21i%27j%28k%29l%7Em*n");
+  });
+
+  it("rejects invalid form-urlencoded bodies", () => {
+    const invalidBodies = [
+      undefined,
+      [],
+      { "": "missing" },
+      { amount: Number.NaN },
+      { metadata: { orderId: "6735" } },
+      { empty: [] },
+      { message: "truncated mid-emoji \uD83D" },
+      { "\uDC00": "lone low surrogate key" },
+    ];
+    for (const body of invalidBodies) {
+      expect(() =>
+        encodeRequestBody({ body, bodyType: "formUrlencoded" }),
+      ).toThrow(RestApiValidationError);
+    }
+    expect(() =>
+      encodeRequestBody({
+        body: { metadata: { orderId: "6735" } },
+        bodyType: "formUrlencoded",
+      }),
+    ).toThrow(/metadata\[order_id\]/);
+    expect(() =>
+      encodeRequestBody({
+        body: { message: "truncated mid-emoji \uD83D" },
+        bodyType: "formUrlencoded",
+      }),
+    ).toThrow(/field "message" contains a lone surrogate/);
+  });
+
+  it.each([
+    ["Uint8Array", Uint8Array.from(PNG_BYTES)],
+    ["ArrayBuffer", arrayBufferFrom(PNG_BYTES)],
+    ["DataView", new DataView(arrayBufferFrom([0, ...PNG_BYTES, 1]), 1, 4)],
+    ["subarray view", Uint8Array.from([0, ...PNG_BYTES, 1]).subarray(1, 5)],
+    ["Buffer", Buffer.from(PNG_BYTES)],
+  ])("base64-encodes exact bytes from %s", (_name, body) => {
+    expect(encodeRequestBody({ body, bodyType: "binary" })).toEqual({
+      wire: { body: PNG_BASE64, bodyType: "binaryBody" },
+      contentType: "application/octet-stream",
+    });
+  });
+
+  it("rejects invalid binary bodies and preserves caller Content-Type", () => {
+    expect(
+      encodeRequestBody({
+        body: Uint8Array.from(PNG_BYTES),
+        bodyType: "binary",
+        headers: { "CONTENT-TYPE": "image/png" },
+      }),
+    ).toEqual({
+      wire: { body: PNG_BASE64, bodyType: "binaryBody" },
+    });
+    for (const body of [new ArrayBuffer(0), "not bytes"]) {
+      expect(() => encodeRequestBody({ body, bodyType: "binary" })).toThrow(
+        RestApiValidationError,
+      );
+    }
+  });
+
+  it("encodes multipart parts as formDataBase64 with base64 file parts", () => {
+    const primitives = encodeRequestBody({
+      body: { active: true, amount: 42, note: "hello" },
+      bodyType: "multipartForm",
+    });
+    expect(primitives).toEqual({
+      wire: {
+        bodyType: "formDataBase64",
+        formData: [
+          { key: "active", value: "true" },
+          { key: "amount", value: "42" },
+          { key: "note", value: "hello" },
+        ],
+      },
+    });
+    expect(primitives.wire).not.toHaveProperty("body");
+    expect(
+      encodeRequestBody({
+        body: {
+          empty: { value: "", filename: "empty.txt" },
+          file: {
+            value: "hello",
+            filename: "hello.txt",
+            contentType: undefined,
+          },
+        },
+        bodyType: "multipartForm",
+      }),
+    ).toEqual({
+      wire: {
+        bodyType: "formDataBase64",
+        formData: [
+          { key: "empty", value: "", file: { filename: "empty.txt" } },
+          {
+            key: "file",
+            value: Buffer.from("hello", "utf8").toString("base64"),
+            file: { filename: "hello.txt" },
+          },
+        ],
+      },
+    });
+    expect(
+      encodeRequestBody({
+        body: {
+          image: { value: Uint8Array.from(PNG_BYTES), filename: "b.png" },
+          note: "mixed",
+          textFile: { value: "cafe \u00e9", filename: "note.txt" },
+        },
+        bodyType: "multipartForm",
+      }),
+    ).toEqual({
+      wire: {
+        bodyType: "formDataBase64",
+        formData: [
+          { key: "image", value: PNG_BASE64, file: { filename: "b.png" } },
+          { key: "note", value: "mixed" },
+          {
+            key: "textFile",
+            value: Buffer.from("cafe \u00e9", "utf8").toString("base64"),
+            file: { filename: "note.txt" },
+          },
+        ],
+      },
+    });
+  });
+
+  it("repeats the key for multipart array values", () => {
+    expect(
+      encodeRequestBody({
+        body: {
+          files: [
+            { value: Uint8Array.from(PNG_BYTES), filename: "a.png" },
+            undefined,
+            { value: "hello", filename: "b.txt" },
+          ],
+          tags: ["x", 2],
+        },
+        bodyType: "multipartForm",
+      }),
+    ).toEqual({
+      wire: {
+        bodyType: "formDataBase64",
+        formData: [
+          { key: "files", value: PNG_BASE64, file: { filename: "a.png" } },
+          {
+            key: "files",
+            value: Buffer.from("hello", "utf8").toString("base64"),
+            file: { filename: "b.txt" },
+          },
+          { key: "tags", value: "x" },
+          { key: "tags", value: "2" },
+        ],
+      },
+    });
+    expect(() =>
+      encodeRequestBody({ body: { files: [] }, bodyType: "multipartForm" }),
+    ).toThrow(/at least one field/);
+  });
+
+  it("rejects malformed multipart bodies", () => {
+    expect(() =>
+      encodeRequestBody({
+        body: { file: "hello" },
+        bodyType: "multipartForm",
+        headers: { "Content-Type": "multipart/form-data" },
+      }),
+    ).toThrow(/boundary/);
+    const invalidBodies = [
+      {},
+      { "": "missing" },
+      { n: Number.NaN },
+      { file: Uint8Array.from(PNG_BYTES) },
+      {
+        file: {
+          contentType: "image/png",
+          filename: "b.png",
+          value: Uint8Array.from(PNG_BYTES),
+        },
+      },
+      { file: { value: "hello", filename: "" } },
+    ];
+    for (const body of invalidBodies) {
+      expect(() =>
+        encodeRequestBody({ body, bodyType: "multipartForm" }),
+      ).toThrow(RestApiValidationError);
+    }
+    expect(() =>
+      encodeRequestBody({
+        body: { file: { value: "contents" } },
+        bodyType: "multipartForm",
+      }),
+    ).toThrow(/missing required key: filename/);
+    expect(() =>
+      encodeRequestBody({
+        body: {
+          file: {
+            value: "contents",
+            filename: "contents.txt",
+            contentType: "text/plain",
+          },
+        },
+        bodyType: "multipartForm",
+      }),
+    ).toThrow(/unexpected key: "contentType"/);
+  });
+});