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

package/src/errors.ts

@@ -2,35 +2,309 @@
  * Error classes for SDK runtime errors.
  */
 
-import type { z } from "zod";
+import { z } from "zod";
 
 export const REDACTED_BINARY_RESPONSE_DATA = Object.freeze({
   dataType: "binary",
   redacted: true,
 });
 
-function isWorkerBufferJson(data: unknown): boolean {
-  if (typeof data !== "object" || data === null) {
-    return false;
-  }
+// Recursion guard for containsBinary/redactBinaryDeep: a cycle is caught by
+// tracking visited objects, but a long non-cyclic chain has no other bound,
+// so it would otherwise recurse until the real call stack overflows at a
+// depth that varies by environment (e.g. the WASM sdk-api sandbox vs. Node).
+// Cap at a fixed depth instead so the failure is deterministic and caught by
+// the try/catch below rather than crashing the walk.
+const MAX_BINARY_SCAN_DEPTH = 100;
+
+export function isBinaryData(
+  value: unknown,
+): value is ArrayBuffer | ArrayBufferView {
+  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+
+function isWorkerBufferJson(data: object): boolean {
   if (!("data" in data) || !("type" in data)) {
     return false;
   }
   return data.type === "Buffer" && Array.isArray(data.data);
 }
 
+function containsBinary(
+  data: unknown,
+  seen: WeakSet<object>,
+  depth = 0,
+): boolean {
+  if (typeof data !== "object" || data === null) return false;
+  if (isBinaryData(data) || isWorkerBufferJson(data)) return true;
+  if (seen.has(data)) return false;
+  if (depth >= MAX_BINARY_SCAN_DEPTH) {
+    throw new RangeError(`binary scan exceeded depth ${MAX_BINARY_SCAN_DEPTH}`);
+  }
+  seen.add(data);
+  if (Array.isArray(data)) {
+    return data.some((item) => containsBinary(item, seen, depth + 1));
+  }
+  if (data instanceof Map) {
+    return (
+      [...data.keys()].some((key) => containsBinary(key, seen, depth + 1)) ||
+      [...data.values()].some((value) => containsBinary(value, seen, depth + 1))
+    );
+  }
+  if (data instanceof Set) {
+    return [...data.values()].some((value) =>
+      containsBinary(value, seen, depth + 1),
+    );
+  }
+  return Object.keys(data).some((key) =>
+    containsBinary(Reflect.get(data, key), seen, depth + 1),
+  );
+}
+
+/**
+ * Key path to the first value inside `data` — including `data` itself —
+ * that satisfies `isBinary`, walking into plain objects, arrays, Map keys
+ * and values, and Set values. Shares `containsBinary`'s cycle guard and
+ * depth cap; a chain deeper than `MAX_BINARY_SCAN_DEPTH` throws the same
+ * way.
+ */
+export function findBinaryDataPath(
+  data: unknown,
+  isBinary: (value: object) => boolean,
+): (string | number)[] | undefined {
+  return findBinaryDataPathIn(data, isBinary, [], new WeakSet(), 0);
+}
+
+function findBinaryDataPathIn(
+  data: unknown,
+  isBinary: (value: object) => boolean,
+  path: (string | number)[],
+  seen: WeakSet<object>,
+  depth: number,
+): (string | number)[] | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  if (isBinary(data)) return path;
+  if (seen.has(data)) return undefined;
+  if (depth >= MAX_BINARY_SCAN_DEPTH) {
+    throw new RangeError(`binary scan exceeded depth ${MAX_BINARY_SCAN_DEPTH}`);
+  }
+  seen.add(data);
+  if (Array.isArray(data)) {
+    for (let index = 0; index < data.length; index++) {
+      const found = findBinaryDataPathIn(
+        data[index],
+        isBinary,
+        [...path, index],
+        seen,
+        depth + 1,
+      );
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+  if (data instanceof Map) {
+    for (const [key, value] of data) {
+      const keyFound = findBinaryDataPathIn(
+        key,
+        isBinary,
+        [...path, "<map-key>"],
+        seen,
+        depth + 1,
+      );
+      if (keyFound !== undefined) return keyFound;
+      const valueFound = findBinaryDataPathIn(
+        value,
+        isBinary,
+        [...path, "<map-value>"],
+        seen,
+        depth + 1,
+      );
+      if (valueFound !== undefined) return valueFound;
+    }
+    return undefined;
+  }
+  if (data instanceof Set) {
+    let index = 0;
+    for (const value of data) {
+      const found = findBinaryDataPathIn(
+        value,
+        isBinary,
+        [...path, index],
+        seen,
+        depth + 1,
+      );
+      if (found !== undefined) return found;
+      index++;
+    }
+    return undefined;
+  }
+  for (const key of Object.keys(data)) {
+    const found = findBinaryDataPathIn(
+      Reflect.get(data, key),
+      isBinary,
+      [...path, key],
+      seen,
+      depth + 1,
+    );
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+// `invalid_literal` is the only issue whose `received` is the raw input
+// (`unknown`); `invalid_type`/`invalid_enum_value` only ever carry a type
+// name or a string|number enum member, never bytes. `invalid_union` nests a
+// full ZodError per attempted branch. `custom` issues carry an arbitrary
+// caller-defined `params` bag from `ctx.addIssue`, which a hand-written
+// `bodySchema.superRefine()` can populate with anything, including bytes.
+// Either can carry the same binary payloads `containsBinary` detects in
+// `data`, so any message or zodError callers derive from an issue list must
+// be scrubbed the same way.
+function sanitizeZodIssue(issue: z.ZodIssue): z.ZodIssue {
+  if (
+    issue.code === z.ZodIssueCode.invalid_literal &&
+    safeContainsBinary(issue.received)
+  ) {
+    return { ...issue, received: REDACTED_BINARY_RESPONSE_DATA };
+  }
+  if (
+    issue.code === z.ZodIssueCode.custom &&
+    issue.params !== undefined &&
+    safeContainsBinary(issue.params)
+  ) {
+    return { ...issue, params: REDACTED_BINARY_RESPONSE_DATA };
+  }
+  if (issue.code === z.ZodIssueCode.invalid_union) {
+    return {
+      ...issue,
+      unionErrors: issue.unionErrors.map(redactBinaryFromZodError),
+    };
+  }
+  if (issue.code === z.ZodIssueCode.invalid_arguments) {
+    return {
+      ...issue,
+      argumentsError: redactBinaryFromZodError(issue.argumentsError),
+    };
+  }
+  if (issue.code === z.ZodIssueCode.invalid_return_type) {
+    return {
+      ...issue,
+      returnTypeError: redactBinaryFromZodError(issue.returnTypeError),
+    };
+  }
+  return issue;
+}
+
+/**
+ * Returns a ZodError whose issues never expose binary bytes, so the
+ * returned error's own `.message` (JSON.stringify of the issues) is safe
+ * to embed in a caller-built error string. Callers must build their
+ * message from this return value, not the original `zodError` argument;
+ * `restApiValidationErrorFromZodError` does this for `RestApiValidationError`.
+ */
+export function redactBinaryFromZodError(zodError: z.ZodError): z.ZodError {
+  return new z.ZodError(zodError.issues.map(sanitizeZodIssue));
+}
+
+// A walk that cannot finish (a throwing getter, an unusual structure) fails
+// closed: treat it as binary so every caller redacts rather than risks
+// leaking bytes. Shared by data and zodError redaction so both paths fail
+// the same way.
+function safeContainsBinary(data: unknown): boolean {
+  try {
+    return containsBinary(data, new WeakSet());
+  } catch {
+    return true;
+  }
+}
+
+// Binary can arrive at the top level (binary responses, binary request bodies)
+// or nested inside a multipart body's { value, filename } parts. Only the
+// binary leaf is replaced, not the whole payload, so sibling fields (e.g. a
+// multipart part's `filename`, or an unrelated field in the same body) stay
+// visible for debugging. `seen` maps each visited object to its output
+// container, registered *before* that container is filled in, so a repeat
+// reference to the same object - a second, non-cyclic pointer (one
+// multipart part reused under two keys) or a genuine cycle's back-edge -
+// always resolves to the redacted copy being built, never to the raw
+// original. Only called once `redactBinaryValidationData` has confirmed the
+// payload contains binary somewhere, so every container along the way is
+// rebuilt; reference identity for the no-binary-anywhere case is handled by
+// that caller instead.
+function redactBinaryDeep(
+  data: unknown,
+  seen: Map<object, unknown>,
+  depth: number,
+): unknown {
+  if (typeof data !== "object" || data === null) return data;
+  if (isBinaryData(data) || isWorkerBufferJson(data)) {
+    return REDACTED_BINARY_RESPONSE_DATA;
+  }
+  if (seen.has(data)) return seen.get(data);
+  if (depth >= MAX_BINARY_SCAN_DEPTH) {
+    throw new RangeError(`binary scan exceeded depth ${MAX_BINARY_SCAN_DEPTH}`);
+  }
+  if (Array.isArray(data)) {
+    const next: unknown[] = [];
+    seen.set(data, next);
+    for (const item of data) {
+      next.push(redactBinaryDeep(item, seen, depth + 1));
+    }
+    return next;
+  }
+  if (data instanceof Map) {
+    const next = new Map<unknown, unknown>();
+    seen.set(data, next);
+    for (const [key, value] of data) {
+      next.set(
+        redactBinaryDeep(key, seen, depth + 1),
+        redactBinaryDeep(value, seen, depth + 1),
+      );
+    }
+    return next;
+  }
+  if (data instanceof Set) {
+    const next = new Set<unknown>();
+    seen.set(data, next);
+    for (const value of data) {
+      next.add(redactBinaryDeep(value, seen, depth + 1));
+    }
+    return next;
+  }
+  const next: Record<string, unknown> = {};
+  seen.set(data, next);
+  for (const key of Object.keys(data)) {
+    next[key] = redactBinaryDeep(Reflect.get(data, key), seen, depth + 1);
+  }
+  return next;
+}
+
+// A walk that cannot finish (a throwing getter, an unusual structure, or a
+// depth-capped chain) fails closed: redact the whole payload rather than
+// risk leaking bytes from a partially-completed walk. The `containsBinary`
+// check runs first so a payload with no binary anywhere - including a
+// circular one - comes back as the exact same object, matching how the rest
+// of this module treats data with nothing to redact.
 function redactBinaryValidationData(data: unknown): unknown {
-  if (data instanceof Uint8Array || isWorkerBufferJson(data)) {
+  try {
+    if (!containsBinary(data, new WeakSet())) return data;
+    return redactBinaryDeep(data, new Map(), 0);
+  } catch {
     return REDACTED_BINARY_RESPONSE_DATA;
   }
-  return data;
 }
 
 /**
  * Error thrown when REST API response or request body validation fails.
  *
- * Contains the complete Zod error object and the actual data that failed validation,
- * providing full context for debugging schema mismatches.
+ * Contains the actual data that failed validation (redacted when it
+ * contains binary) and a Zod error scrubbed of any binary `received`
+ * values, providing full context for debugging schema mismatches without
+ * leaking bytes into logs or telemetry via `details`.
+ *
+ * The constructor only scrubs `details`; a `message` built from the raw
+ * `ZodError` before construction still carries bytes. Build from a Zod
+ * failure through `restApiValidationErrorFromZodError` so `.message` is
+ * scrubbed too, not just `details.zodError`.
  */
 export class RestApiValidationError extends Error {
   readonly details: {
@@ -49,12 +323,32 @@ export class RestApiValidationError extends Error {
     this.name = "RestApiValidationError";
     this.details = {
       data: redactBinaryValidationData(details.data),
-      zodError: details.zodError,
+      zodError: redactBinaryFromZodError(details.zodError),
     };
     Object.setPrototypeOf(this, RestApiValidationError.prototype);
   }
 }
 
+/**
+ * Builds a `RestApiValidationError` from a Zod validation failure. Redacts
+ * `zodError` before composing `message`, so the thrown error's `message`
+ * can never carry bytes that `details.zodError` already scrubs. This is
+ * the only site that needs to reason about redaction order; every caller
+ * with a `ZodError` from a `safeParse` failure should use this instead of
+ * constructing `RestApiValidationError` directly.
+ */
+export function restApiValidationErrorFromZodError(
+  prefix: string,
+  zodError: z.ZodError,
+  data: unknown,
+): RestApiValidationError {
+  const sanitized = redactBinaryFromZodError(zodError);
+  return new RestApiValidationError(`${prefix}: ${sanitized.message}`, {
+    zodError: sanitized,
+    data,
+  });
+}
+
 /**
  * Error thrown when query results fail schema validation.
  *

package/src/integrations/base/decode-worker-binary-response.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 import {
   REDACTED_BINARY_RESPONSE_DATA,
-  RestApiValidationError,
+  restApiValidationErrorFromZodError,
 } from "../../errors.js";
 
 export { REDACTED_BINARY_RESPONSE_DATA };
@@ -50,12 +50,10 @@ const workerBinaryResponseSchema = z.union([
 export function decodeWorkerBinaryResponse(value: unknown): Uint8Array {
   const result = workerBinaryResponseSchema.safeParse(value);
   if (!result.success) {
-    throw new RestApiValidationError(
-      `Binary response is malformed: ${result.error.message}`,
-      {
-        data: REDACTED_BINARY_RESPONSE_DATA,
-        zodError: result.error,
-      },
+    throw restApiValidationErrorFromZodError(
+      "Binary response is malformed",
+      result.error,
+      REDACTED_BINARY_RESPONSE_DATA,
     );
   }
   return result.data;

package/src/integrations/base/index.ts

@@ -6,9 +6,12 @@ export { RestApiClientBase } from "./rest-api-client-base.js";
 export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
 export type { RestApiRequest } from "./rest-api-client-base.js";
 export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
+export { REST_API_BODY_TYPES } from "./types.js";
 export type {
   ApiRequestOptions,
   ApiRequestSchema,
+  BinaryApiRequestSchema,
+  RestApiBodyType,
   RestApiResponseType,
   SupportsApiRequest,
 } from "./types.js";