@aptos-labs/ts-sdk 7.0.0 → 7.1.0

package/src/core/crypto/secp256k1.ts

@@ -12,6 +12,7 @@ import { PrivateKey } from "./privateKey.js";
 import { PublicKey } from "./publicKey.js";
 import { Signature } from "./signature.js";
 import { convertSigningMessage } from "./utils.js";
+import { TEXT_ENCODER } from "../../utils/const.js";
 import { AptosConfig } from "../../api/aptosConfig.js";
 
 /**
@@ -62,10 +63,54 @@ export class Secp256k1PublicKey extends PublicKey {
   }
 
   // region PublicKey
+  /**
+   * Verifies a signature against the exact bytes of `message`. This is the
+   * unambiguous form — the input is interpreted as raw bytes regardless of
+   * what they encode. Pair with {@link Secp256k1PrivateKey.signBytes}.
+   *
+   * The message is SHA3-256 hashed before verification (matching the
+   * Aptos-side Secp256k1 signing convention), and the signature is required
+   * to be in canonical low-S form for malleability resistance.
+   *
+   * @param args - The arguments for verification.
+   * @param args.message - The exact bytes that were signed.
+   * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifyBytes(args: { message: Uint8Array; signature: Secp256k1Signature }): boolean {
+    const { message, signature } = args;
+    const messageSha3Bytes = sha3_256(message);
+    return secp256k1.verify(signature.toUint8Array(), messageSha3Bytes, this.key.toUint8Array(), {
+      lowS: true,
+      prehash: false,
+    });
+  }
+
+  /**
+   * Verifies a signature against the UTF-8 encoding of `message`. The input
+   * is always treated as text — there is no hex/text heuristic. Pair with
+   * {@link Secp256k1PrivateKey.signText}.
+   *
+   * @param args - The arguments for verification.
+   * @param args.message - The text that was signed.
+   * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifyText(args: { message: string; signature: Secp256k1Signature }): boolean {
+    return this.verifyBytes({ message: TEXT_ENCODER.encode(args.message), signature: args.signature });
+  }
+
   /**
    * Verifies a Secp256k1 signature against the public key.
    *
-   * This function checks the validity of a signature for a given message, ensuring that the signature is canonical as a malleability check.
+   * @deprecated The polymorphic `message: HexInput` input is ambiguous — a
+   * bare even-length string of hex characters (e.g., `"cafe"`) is verified
+   * against the 2 bytes `[0xCA, 0xFE]`, not 4 UTF-8 text bytes. Use
+   * {@link verifyBytes} for `Uint8Array` input or {@link verifyText} for
+   * `string` input; both are unambiguous. See
+   * {@link convertSigningMessage} for the full legacy rule.
    *
    * @param args - The arguments for verifying the signature.
    * @param args.message - The message that was signed.
@@ -77,9 +122,7 @@ export class Secp256k1PublicKey extends PublicKey {
     const { message, signature } = args;
     const messageToVerify = convertSigningMessage(message);
     const messageBytes = Hex.fromHexInput(messageToVerify).toUint8Array();
-    const messageSha3Bytes = sha3_256(messageBytes);
-    const signatureBytes = signature.toUint8Array();
-    return secp256k1.verify(signatureBytes, messageSha3Bytes, this.key.toUint8Array(), { lowS: true, prehash: false });
+    return this.verifyBytes({ message: messageBytes, signature });
   }
 
   /**
@@ -308,11 +351,42 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   }
 
   /**
-   * Clears the private key from memory by overwriting it with random bytes.
-   * After calling this method, the private key can no longer be used for signing or deriving public keys.
+   * Overwrites the underlying private-key byte buffer with random bytes and
+   * then zeros. After calling this method the key can no longer sign or
+   * derive a public key.
+   *
+   * SECURITY: This is a best-effort window-narrowing tool, NOT a true
+   * zeroization guarantee. In JavaScript, four classes of copies cannot be
+   * reached from user code and so survive `clear()`:
+   *
+   *   1. **JS string copies.** Any value previously produced by `toString()`,
+   *      `toHexString()`, or `bcsToHex().toString()` is an immutable string
+   *      in the heap. The language provides no API to overwrite string
+   *      memory; it is reclaimed only when GC collects it.
+   *   2. **noble-curves internals.** The sign path inside `@noble/curves`
+   *      expands the private key into scalar `BigInt` field elements, which
+   *      are also immutable. Even if noble explicitly zeroed its own byte
+   *      copies after use, the `BigInt` intermediates persist.
+   *   3. **JIT register / stack residue.** The engine may have held key
+   *      bytes in CPU registers or on the engine stack during a sign call.
+   *      There is no JS-visible way to scrub those.
+   *   4. **GC-relocated copies.** Generational GCs (V8, JSC) copy live
+   *      objects between heap regions during minor/major collections. The
+   *      `Uint8Array` we zeroed may have stale copies sitting in survivor
+   *      space until the next cycle reclaims them.
    *
-   * Note: Due to JavaScript's memory management, this cannot guarantee complete removal of
-   * sensitive data from memory, but it significantly reduces the window of exposure.
+   * This method zeros the SDK's own `Uint8Array` (the most reachable
+   * copy), but downstream consumers should treat it as a hardening signal,
+   * not a guarantee. If you need real key-material hygiene, prefer a
+   * WASM-backed secp256k1 implementation that exposes explicit
+   * `memzero`, or hardware-backed keys (HSM / TPM / secure enclave).
+   * Note that `crypto.subtle` does NOT support secp256k1 on any major
+   * runtime, so non-extractable WebCrypto keys are not available for
+   * this curve.
+   *
+   * To minimize the size of the unreachable-copy set, avoid calling
+   * `toString()` / `toHexString()` on private keys at all in long-lived
+   * processes — the byte form is what gets cleared.
    *
    * @group Implementation
    * @category Serialization
@@ -344,10 +418,54 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
     return this.cleared;
   }
 
+  /**
+   * Sign exactly the bytes of `message`. The input is interpreted as raw
+   * bytes regardless of what they encode. Pair with
+   * {@link Secp256k1PublicKey.verifyBytes}.
+   *
+   * The message is SHA3-256 hashed before signing (matching the Aptos-side
+   * Secp256k1 signing convention), and the produced signature is in
+   * canonical low-S form for malleability resistance.
+   *
+   * @param message - The exact bytes to sign.
+   * @returns The generated signature for the provided bytes.
+   * @throws Error if the private key has been cleared from memory.
+   * @group Implementation
+   * @category Serialization
+   */
+  signBytes(message: Uint8Array): Secp256k1Signature {
+    this.ensureNotCleared();
+    const messageHashBytes = sha3_256(message);
+    const signature = secp256k1.sign(messageHashBytes, this.key.toUint8Array(), { lowS: true, prehash: false });
+    return new Secp256k1Signature(signature);
+  }
+
+  /**
+   * Sign the UTF-8 encoding of `message`. The input is always treated as
+   * text — there is no hex/text heuristic. Pair with
+   * {@link Secp256k1PublicKey.verifyText}.
+   *
+   * @param message - The text to sign.
+   * @returns The generated signature for the UTF-8 bytes of the provided text.
+   * @throws Error if the private key has been cleared from memory.
+   * @group Implementation
+   * @category Serialization
+   */
+  signText(message: string): Secp256k1Signature {
+    return this.signBytes(TEXT_ENCODER.encode(message));
+  }
+
   /**
    * Sign the given message with the private key.
    * This function generates a cryptographic signature for the provided message, ensuring the signature is canonical and non-malleable.
    *
+   * @deprecated The polymorphic `message: HexInput` input is ambiguous — a
+   * bare even-length string of hex characters (e.g., `"cafe"`) is signed
+   * as the 2 bytes `[0xCA, 0xFE]`, not 4 UTF-8 text bytes. Use
+   * {@link signBytes} for `Uint8Array` input or {@link signText} for
+   * `string` input; both are unambiguous. See
+   * {@link convertSigningMessage} for the full legacy rule.
+   *
    * @param message - A message in HexInput format to be signed.
    * @returns Signature - The generated signature for the provided message.
    * @throws Error if the private key has been cleared from memory.
@@ -355,12 +473,9 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @category Serialization
    */
   sign(message: HexInput): Secp256k1Signature {
-    this.ensureNotCleared();
     const messageToSign = convertSigningMessage(message);
-    const messageBytes = Hex.fromHexInput(messageToSign);
-    const messageHashBytes = sha3_256(messageBytes.toUint8Array());
-    const signature = secp256k1.sign(messageHashBytes, this.key.toUint8Array(), { lowS: true, prehash: false });
-    return new Secp256k1Signature(signature);
+    const messageBytes = Hex.fromHexInput(messageToSign).toUint8Array();
+    return this.signBytes(messageBytes);
   }
 
   /**
@@ -393,6 +508,13 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Get the private key as a string representation.
    *
+   * SECURITY: This produces an immutable JS string containing the key
+   * material in hex. Strings cannot be zeroed by `clear()` (see the
+   * `clear()` JSDoc for the four classes of unreachable copies). Avoid
+   * calling this method on long-lived `Secp256k1PrivateKey` instances in
+   * processes where memory hygiene matters; prefer `toUint8Array()`,
+   * which returns a clearable `Uint8Array`.
+   *
    * @returns string representation of the private key
    * @throws Error if the private key has been cleared from memory.
    * @group Implementation
@@ -406,6 +528,9 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Get the private key as a hex string with the 0x prefix.
    *
+   * SECURITY: Same caveat as `toString()` — the returned string is an
+   * immutable JS heap allocation that `clear()` cannot zero.
+   *
    * @returns string representation of the private key.
    * @throws Error if the private key has been cleared from memory.
    */
@@ -419,6 +544,9 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    *
    * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
    *
+   * SECURITY: Same caveat as `toString()` — produces an immutable JS string
+   * containing the key material; cannot be zeroed by `clear()`.
+   *
    * @returns AIP-80 compliant string representation of the private key.
    * @throws Error if the private key has been cleared from memory.
    */

package/src/core/crypto/secp256r1.ts

@@ -15,6 +15,8 @@ import { PublicKey, VerifySignatureAsyncArgs } from "./publicKey.js";
 import { PrivateKey } from "./privateKey.js";
 import { Signature } from "./signature.js";
 import { AuthenticationKey } from "../authenticationKey.js";
+import { convertSigningMessage } from "./utils.js";
+import { TEXT_ENCODER } from "../../utils/const.js";
 
 /**
  * Represents a Secp256r1 ECDSA public key.
@@ -101,10 +103,51 @@ export class Secp256r1PublicKey extends PublicKey {
     return serializer.toUint8Array();
   }
 
+  /**
+   * Verifies a signature against the exact bytes of `message`. This is the
+   * unambiguous form — the input is interpreted as raw bytes regardless of
+   * what they encode. Pair with {@link Secp256r1PrivateKey.signBytes}.
+   *
+   * The message is SHA3-256 hashed before verification (matching the
+   * Aptos-side Secp256r1 signing convention), and the signature is required
+   * to be in canonical low-S form for malleability resistance.
+   *
+   * @param args - The arguments for verification.
+   * @param args.message - The exact bytes that were signed.
+   * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifyBytes(args: { message: Uint8Array; signature: Signature }): boolean {
+    const { message, signature } = args;
+    const sha3Message = sha3_256(message);
+    return p256.verify(signature.toUint8Array(), sha3Message, this.toUint8Array(), { prehash: false, lowS: true });
+  }
+
+  /**
+   * Verifies a signature against the UTF-8 encoding of `message`. The input
+   * is always treated as text — there is no hex/text heuristic. Pair with
+   * {@link Secp256r1PrivateKey.signText}.
+   *
+   * @param args - The arguments for verification.
+   * @param args.message - The text that was signed.
+   * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifyText(args: { message: string; signature: Signature }): boolean {
+    return this.verifyBytes({ message: TEXT_ENCODER.encode(args.message), signature: args.signature });
+  }
+
   /**
    * Verifies a Secp256r1 signature against the public key.
    *
-   * This function checks the validity of a signature for a given message.
+   * @deprecated The polymorphic `message: HexInput` input is ambiguous — a
+   * bare even-length string of hex characters (e.g., `"cafe"`) is verified
+   * against the 2 bytes `[0xCA, 0xFE]`, not 4 UTF-8 text bytes. Use
+   * {@link verifyBytes} for `Uint8Array` input or {@link verifyText} for
+   * `string` input; both are unambiguous. See
+   * {@link convertSigningMessage} for the full legacy rule.
    *
    * @param args - The arguments for verifying the signature.
    * @param args.message - The message that was signed.
@@ -114,12 +157,9 @@ export class Secp256r1PublicKey extends PublicKey {
    */
   verifySignature(args: { message: HexInput; signature: Signature }): boolean {
     const { message, signature } = args;
-
-    const msgHex = Hex.fromHexInput(message).toUint8Array();
-    const sha3Message = sha3_256(msgHex);
-    const rawSignature = signature.toUint8Array();
-
-    return p256.verify(rawSignature, sha3Message, this.toUint8Array(), { prehash: false });
+    const messageToVerify = convertSigningMessage(message);
+    const msgBytes = Hex.fromHexInput(messageToVerify).toUint8Array();
+    return this.verifyBytes({ message: msgBytes, signature });
   }
 
   /**
@@ -242,6 +282,12 @@ export class Secp256r1PrivateKey extends PrivateKey {
    */
   private readonly key: Hex;
 
+  /**
+   * Whether the key has been cleared from memory.
+   * @private
+   */
+  private cleared: boolean = false;
+
   /**
    * Create a new PrivateKey instance from a Uint8Array or String.
    *
@@ -268,47 +314,106 @@ export class Secp256r1PrivateKey extends PrivateKey {
    * Get the private key in bytes (Uint8Array).
    *
    * @returns
+   * @throws Error if the private key has been cleared from memory.
    * @group Implementation
    * @category Serialization
    */
   toUint8Array(): Uint8Array {
+    this.ensureNotCleared();
     return this.key.toUint8Array();
   }
 
   /**
    * Get the private key as a string representation.
    *
+   * SECURITY: This produces an immutable JS string containing the key
+   * material. Strings cannot be zeroed by `clear()` (see the `clear()`
+   * JSDoc for the four classes of unreachable copies). Avoid calling this
+   * method on long-lived `Secp256r1PrivateKey` instances in processes
+   * where memory hygiene matters; prefer `toUint8Array()`, which returns
+   * a clearable `Uint8Array`.
+   *
    * @returns string representation of the private key
+   * @throws Error if the private key has been cleared from memory.
    * @group Implementation
    * @category Serialization
    */
   toString(): string {
+    this.ensureNotCleared();
     return PrivateKey.formatPrivateKey(this.key.toString(), PrivateKeyVariants.Secp256r1);
   }
 
   /**
    * Get the private key as a hex string with the 0x prefix.
    *
+   * SECURITY: Same caveat as `toString()` — produces an immutable JS string
+   * containing the key material; cannot be zeroed by `clear()`.
+   *
    * @returns string representation of the private key.
+   * @throws Error if the private key has been cleared from memory.
    */
   toHexString(): string {
+    this.ensureNotCleared();
     return this.key.toString();
   }
 
+  /**
+   * Sign exactly the bytes of `message`. The input is interpreted as raw
+   * bytes regardless of what they encode. Pair with
+   * {@link Secp256r1PublicKey.verifyBytes}.
+   *
+   * The message is SHA3-256 hashed before signing (matching the Aptos-side
+   * Secp256r1 signing convention).
+   *
+   * @param message - The exact bytes to sign.
+   * @returns The generated signature for the provided bytes.
+   * @throws Error if the private key has been cleared from memory.
+   * @group Implementation
+   * @category Serialization
+   */
+  signBytes(message: Uint8Array): Secp256r1Signature {
+    this.ensureNotCleared();
+    const sha3Message = sha3_256(message);
+    const signature = p256.sign(sha3Message, this.key.toUint8Array(), { prehash: false });
+    return new Secp256r1Signature(signature);
+  }
+
+  /**
+   * Sign the UTF-8 encoding of `message`. The input is always treated as
+   * text — there is no hex/text heuristic. Pair with
+   * {@link Secp256r1PublicKey.verifyText}.
+   *
+   * @param message - The text to sign.
+   * @returns The generated signature for the UTF-8 bytes of the provided text.
+   * @throws Error if the private key has been cleared from memory.
+   * @group Implementation
+   * @category Serialization
+   */
+  signText(message: string): Secp256r1Signature {
+    return this.signBytes(TEXT_ENCODER.encode(message));
+  }
+
   /**
    * Sign the given message with the private key.
    * This function generates a cryptographic signature for the provided message.
    *
+   * @deprecated The polymorphic `message: HexInput` input is ambiguous — a
+   * bare even-length string of hex characters (e.g., `"cafe"`) is signed
+   * as the 2 bytes `[0xCA, 0xFE]`, not 4 UTF-8 text bytes. Use
+   * {@link signBytes} for `Uint8Array` input or {@link signText} for
+   * `string` input; both are unambiguous. See
+   * {@link convertSigningMessage} for the full legacy rule.
+   *
    * @param message - A message in HexInput format to be signed.
    * @returns Signature - The generated signature for the provided message.
+   * @throws Error if the private key has been cleared from memory.
    * @group Implementation
    * @category Serialization
    */
   sign(message: HexInput): Secp256r1Signature {
-    const msgHex = Hex.fromHexInput(message);
-    const sha3Message = sha3_256(msgHex.toUint8Array());
-    const signature = p256.sign(sha3Message, this.key.toUint8Array(), { prehash: false });
-    return new Secp256r1Signature(signature);
+    const messageToSign = convertSigningMessage(message);
+    const msgBytes = Hex.fromHexInput(messageToSign).toUint8Array();
+    return this.signBytes(msgBytes);
   }
 
   /**
@@ -352,13 +457,61 @@ export class Secp256r1PrivateKey extends PrivateKey {
    * Derive the Secp256r1PublicKey from this private key.
    *
    * @returns Secp256r1PublicKey The derived public key.
+   * @throws Error if the private key has been cleared from memory.
    * @group Implementation
    * @category Serialization
    */
   publicKey(): Secp256r1PublicKey {
+    this.ensureNotCleared();
     const bytes = p256.getPublicKey(this.key.toUint8Array(), false);
     return new Secp256r1PublicKey(bytes);
   }
+
+  /**
+   * Throws if the key has already been cleared.
+   * @private
+   */
+  private ensureNotCleared(): void {
+    if (this.cleared) {
+      throw new Error("Private key has been cleared from memory and can no longer be used");
+    }
+  }
+
+  /**
+   * Overwrites the underlying private-key byte buffer with random bytes and
+   * then zeros. After calling this method the key can no longer sign or
+   * derive a public key.
+   *
+   * SECURITY: This is a best-effort window-narrowing tool, NOT a true
+   * zeroization guarantee. See `Ed25519PrivateKey.clear()` for the full
+   * enumeration of JavaScript-level limits (immutable string copies, noble
+   * `BigInt` intermediates, JIT register/stack residue, GC-relocated
+   * copies). For Secp256r1 specifically, non-extractable `crypto.subtle`
+   * P-256 keys are universally supported across modern runtimes and are
+   * the architecturally-correct path for callers who need real memory
+   * hygiene; consider that alternative for new code.
+   *
+   * @group Implementation
+   * @category Serialization
+   */
+  clear(): void {
+    if (!this.cleared) {
+      const keyBytes = this.key.toUint8Array();
+      // Multiple overwrite passes for consistency with the other private-key classes.
+      crypto.getRandomValues(keyBytes);
+      keyBytes.fill(0xff);
+      crypto.getRandomValues(keyBytes);
+      keyBytes.fill(0);
+      this.cleared = true;
+    }
+  }
+
+  /**
+   * Returns whether `clear()` has been called.
+   */
+  isCleared(): boolean {
+    return this.cleared;
+  }
 }
 
 export class WebAuthnSignature extends Signature {

package/src/core/crypto/utils.ts

@@ -10,7 +10,34 @@ import { BaseAccountPublicKey } from "./types.js";
 import { detectPublicKeyVariant } from "./anyKeyRegistry.js";
 
 /**
- * Helper function to convert a message to sign or to verify to a valid message input
+ * Normalizes a sign/verify message into a {@link HexInput} that downstream
+ * callers can pass to `Hex.fromHexInput()`.
+ *
+ * Behavior — be aware before passing a string:
+ * - `Uint8Array` → returned as-is (used as raw bytes).
+ * - String that parses as hex via `Hex.isValid()` (with or without a `0x`
+ *   prefix) → returned as the original hex string, which downstream
+ *   `Hex.fromHexInput()` decodes to its byte form.
+ * - Any other string → returned as the UTF-8 byte encoding of the string.
+ *
+ * **AMBIGUITY**: a bare even-length string of hex characters is *always*
+ * interpreted as hex, even when the caller intended it as text. For example:
+ *
+ * ```ts
+ * sign("cafe")       // signs 2 bytes: [0xCA, 0xFE]
+ * sign("decade")     // signs 3 bytes: [0xDE, 0xCA, 0xDE]
+ * sign("0xcafe")     // signs 2 bytes: [0xCA, 0xFE]   (explicit hex)
+ * sign("hello")      // signs 5 bytes: UTF-8 "hello"  (not valid hex)
+ * sign(new TextEncoder().encode("cafe"))  // signs 4 bytes: UTF-8 "cafe"
+ * ```
+ *
+ * If you mean *text*, pass `TextEncoder.encode(text)` or any `Uint8Array`.
+ * If you mean *hex bytes*, the most explicit form is also a `Uint8Array`
+ * (`Hex.fromHexInput("0x...").toUint8Array()`), or a string prefixed with
+ * `0x` for clarity. The heuristic is preserved as-is for backwards
+ * compatibility — changing it would silently re-interpret bytes signed by
+ * existing dApps and wallets — but new code should treat string inputs to
+ * `sign()` / `verifySignature()` as untyped and prefer `Uint8Array`.
  *
  * @param message a message as a string or Uint8Array
  *

package/src/errors/index.ts

@@ -361,6 +361,15 @@ type AptosApiErrorOpts = {
  * @param statusText - The message associated with the response status.
  * @param data - The response data returned from the API.
  * @param request - The original AptosRequest that triggered the error.
+ *
+ * SECURITY: `Error.message` is sanitized for `AptosApiType.PEPPER` and
+ * `AptosApiType.PROVER` so that response bodies (which can contain JWT claims
+ * or pepper-derived material) don't leak into default log/crash sinks. The
+ * `data` field, however, ALWAYS holds the raw response body — including for
+ * those sensitive API types — so callers that log or serialize
+ * `AptosApiError.data` (e.g., `JSON.stringify(error)`, Sentry's automatic
+ * field capture, custom structured loggers) must treat it accordingly. If
+ * you only need a human-readable summary, prefer `error.message`.
  */
 export class AptosApiError extends Error {
   readonly url: string;
@@ -369,6 +378,16 @@ export class AptosApiError extends Error {
 
   readonly statusText: string;
 
+  /**
+   * The raw response body returned by the API.
+   *
+   * SECURITY: For `AptosApiType.PEPPER` and `AptosApiType.PROVER`, this can
+   * contain sensitive keyless-flow material (JWT claims, pepper-derived
+   * state). It is NOT redacted here — only `Error.message` is. Treat
+   * `error.data` as sensitive when handling errors from those API types,
+   * especially before passing the error to a structured logger or crash
+   * reporter.
+   */
   readonly data: any;
 
   readonly request: AptosRequest;
@@ -404,6 +423,13 @@ export class AptosApiError extends Error {
  * @param {AptosRequest} opts.aptosRequest - The original request made to the Aptos API.
  * @param {AptosResponse} opts.aptosResponse - The response received from the Aptos API.
  */
+// API types whose response bodies may contain keyless-account material (JWT
+// claims, pepper-derived state). For these we exclude the body from the error
+// message — including from the structured-error branch — so nothing about
+// the response payload reaches the default Error.message sink. Callers that
+// need the full body can still read it from `AptosApiError.data`.
+const SENSITIVE_BODY_API_TYPES: ReadonlySet<AptosApiType> = new Set([AptosApiType.PEPPER, AptosApiType.PROVER]);
+
 function deriveErrorMessage({ apiType, aptosRequest, aptosResponse }: AptosApiErrorOpts): string {
   // extract the W3C trace_id from the response headers if it exists. Some services set this in the response, and it's useful for debugging.
   // See https://www.w3.org/TR/trace-context/#relationship-between-the-headers .
@@ -414,6 +440,17 @@ function deriveErrorMessage({ apiType, aptosRequest, aptosResponse }: AptosApiEr
     aptosResponse.url ?? aptosRequest.url
   } ${traceIdString}failed with`;
 
+  // For sensitive API types, redact the response body in every branch below.
+  // Doing this up-front rather than per-branch ensures a Pepper/Prover
+  // response that happens to match the `{ message, error_code }` shape (or
+  // some future well-known shape) can't slip a payload through into
+  // Error.message. The full body remains on AptosApiError.data for callers
+  // that explicitly need it.
+  const isSensitive = SENSITIVE_BODY_API_TYPES.has(apiType);
+  if (isSensitive) {
+    return `${errorPrelude} status: ${aptosResponse.statusText}(code:${aptosResponse.status}) (response body redacted for ${apiType})`;
+  }
+
   // handle graphql responses from indexer api and extract the error message of the first error
   if (apiType === AptosApiType.INDEXER && aptosResponse.data?.errors?.[0]?.message != null) {
     return `${errorPrelude}: ${aptosResponse.data.errors[0].message}`;