@aptos-labs/ts-sdk 7.0.1 → 7.1.0

package/src/cli/localNode.ts

@@ -3,6 +3,7 @@ import kill from "tree-kill";
 import { platform } from "node:os";
 
 import { sleep } from "../utils/helpers.js";
+import { assertSafeCliArgs } from "./spawnArgs.js";
 
 /**
  * Represents a local node for running a localnet environment.
@@ -86,6 +87,12 @@ export class LocalNode {
    * @category CLI
    */
   start(): void {
+    // Reject shell-metacharacter-bearing extras up front. On Windows we have
+    // to spawn with `shell: true` (npx is a .cmd shim and Node refuses to
+    // spawn .cmd/.bat without the shell since CVE-2024-27980), so unsafe
+    // characters in extraArgs would otherwise be interpreted by cmd.exe.
+    assertSafeCliArgs(this.extraArgs);
+
     const cliCommand = "npx";
     const cliArgs = [
       "aptos",

package/src/cli/move.ts

@@ -3,6 +3,7 @@ import { platform } from "node:os";
 
 import { AccountAddress } from "../core/index.js";
 import { Network } from "../utils/index.js";
+import { assertSafeCliArgs } from "./spawnArgs.js";
 
 /**
  * Class representing a Move package management utility for the Aptos blockchain.
@@ -355,6 +356,14 @@ export class Move {
    */
 
   private async runCommand(args: Array<string>, showStdout: boolean = true): Promise<{ result?: any; output: string }> {
+    // Reject shell-metacharacter-bearing args up front. On Windows we have to
+    // spawn with `shell: true` (npx is a .cmd shim and Node refuses to spawn
+    // .cmd/.bat without the shell since CVE-2024-27980), so unsafe characters
+    // in args would otherwise be interpreted by cmd.exe. We validate on all
+    // platforms for consistency — extraArguments shouldn't contain shell
+    // metacharacters regardless of OS.
+    assertSafeCliArgs(args);
+
     return new Promise((resolve, reject) => {
       const isWindows = platform() === "win32";
       const spawnOptions = isWindows ? { shell: true } : undefined;

package/src/cli/spawnArgs.ts

@@ -0,0 +1,55 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shell metacharacters that enable command injection when passed through
+ * `spawn(..., { shell: true })`. We have to keep `shell: true` on Windows
+ * because Node.js 18.20.2+ / 20.12.2+ refuses to spawn `.cmd`/`.bat` shims
+ * (like `npx.cmd`) without it (CVE-2024-27980 mitigation), so the next-best
+ * mitigation is to reject argument strings that contain characters the shell
+ * would interpret.
+ *
+ * - cmd.exe metacharacters: `& | < > ^ ( ) " ' % !` plus newlines
+ *   (`%` triggers environment-variable expansion like `%USERPROFILE%`;
+ *   `!` triggers delayed expansion).
+ * - /bin/sh metacharacters: `& | ; < > ` $ ( ) "` `'` plus newlines.
+ *
+ * Backslash is intentionally NOT in the blocklist even though it's a
+ * /bin/sh escape character — Windows paths (`C:\Program Files\...`) and
+ * Windows-style flag values rely on it, and disallowing it would break
+ * legitimate `extraArgs` usage on every Move/LocalNode call from a Windows
+ * developer machine. The trade-off: on POSIX a caller passing `"a\b"` will
+ * have the backslash interpreted by `/bin/sh`, but our spawn call uses
+ * `shell: false` on POSIX anyway, so this doesn't materially matter.
+ *
+ * Common, legitimate CLI argument characters (letters, digits, `-`, `_`,
+ * `=`, `.`, `,`, `:`, `/`, `\`, space) are unaffected.
+ */
+const UNSAFE_SHELL_CHARS = /[&|;<>`$()"'\n\r^!*?%]/;
+
+/**
+ * Validates that a CLI argument does not contain shell metacharacters that
+ * could be interpreted by the shell when passed via `spawn(..., { shell: true })`.
+ *
+ * @throws Error if `arg` contains any unsafe shell character.
+ */
+export function assertSafeCliArg(arg: string): void {
+  if (typeof arg !== "string") {
+    throw new Error(`CLI argument must be a string, received ${typeof arg}`);
+  }
+  if (UNSAFE_SHELL_CHARS.test(arg)) {
+    throw new Error(
+      `CLI argument contains characters that could be interpreted by the shell: ${JSON.stringify(arg)}. ` +
+        "Remove shell metacharacters (& | ; < > \" ' ` $ ( ) ^ ! * ? % newlines).",
+    );
+  }
+}
+
+/**
+ * Validates every element of an args array. See {@link assertSafeCliArg}.
+ */
+export function assertSafeCliArgs(args: ReadonlyArray<string>): void {
+  for (const arg of args) {
+    assertSafeCliArg(arg);
+  }
+}

package/src/core/crypto/ed25519.ts

@@ -11,6 +11,7 @@ import { CKDPriv, deriveKey, HARDENED_OFFSET, isValidHardenedPath, mnemonicToSee
 import { PrivateKey } from "./privateKey.js";
 import { AccountPublicKey, PublicKey, VerifySignatureArgs, VerifySignatureAsyncArgs } from "./publicKey.js";
 import { Signature } from "./signature.js";
+import { TEXT_ENCODER } from "../../utils/const.js";
 import { convertSigningMessage } from "./utils.js";
 
 /**
@@ -98,26 +99,63 @@ export class Ed25519PublicKey extends AccountPublicKey {
   // region AccountPublicKey
 
   /**
-   * Verifies a signed message using a public key.
+   * 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 Ed25519PrivateKey.signBytes}.
+   *
+   * Performs an Ed25519 malleability check (rejects non-canonical S values)
+   * before delegating to the underlying curve verifier.
    *
    * @param args - The arguments for verification.
-   * @param args.message - A signed message as a Hex string or Uint8Array.
-   * @param args.signature - The signature of the message.
+   * @param args.message - The exact bytes that were signed.
+   * @param args.signature - The signature to verify.
    * @group Implementation
    * @category Serialization
    */
-  verifySignature(args: VerifySignatureArgs): boolean {
+  verifyBytes(args: { message: Uint8Array; signature: Signature }): boolean {
     const { message, signature } = args;
-    // Verify malleability
     if (!isCanonicalEd25519Signature(signature)) {
       return false;
     }
+    return ed25519.verify(signature.toUint8Array(), message, this.key.toUint8Array());
+  }
+
+  /**
+   * 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 Ed25519PrivateKey.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 signed message using a public key.
+   *
+   * @deprecated The polymorphic `message: HexInput` input is ambiguous — a
+   * bare even-length string of hex characters (e.g., `"cafe"`) is
+   * interpreted as the 2 bytes `[0xCA, 0xFE]`, not as 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 verification.
+   * @param args.message - A signed message as a Hex string or Uint8Array.
+   * @param args.signature - The signature of the message.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifySignature(args: VerifySignatureArgs): boolean {
+    const { message, signature } = args;
     const messageToVerify = convertSigningMessage(message);
     const messageBytes = Hex.fromHexInput(messageToVerify).toUint8Array();
-    const signatureBytes = signature.toUint8Array();
-    const publicKeyBytes = this.key.toUint8Array();
-    return ed25519.verify(signatureBytes, messageBytes, publicKeyBytes);
+    return this.verifyBytes({ message: messageBytes, signature });
   }
 
   /**
@@ -362,11 +400,40 @@ export class Ed25519PrivateKey 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()`:
    *
-   * 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.
+   *   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 in V8/JSC/Hermes. 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.
+   *
+   * 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
+   * non-extractable `crypto.subtle` keys (where the underlying algorithm
+   * is supported by the host runtime), a WASM-backed crypto library, or
+   * hardware-backed keys (passkeys / secure enclave / HSM).
+   *
+   * 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
@@ -412,10 +479,49 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
     return new Ed25519PublicKey(bytes);
   }
 
+  /**
+   * Sign exactly the bytes of `message`. The input is interpreted as raw
+   * bytes regardless of what they encode. Pair with
+   * {@link Ed25519PublicKey.verifyBytes}.
+   *
+   * @param message - The exact bytes to sign.
+   * @returns A digital signature for the provided bytes.
+   * @throws Error if the private key has been cleared from memory.
+   * @group Implementation
+   * @category Serialization
+   */
+  signBytes(message: Uint8Array): Ed25519Signature {
+    this.ensureNotCleared();
+    const signatureBytes = ed25519.sign(message, this.signingKey.toUint8Array());
+    return new Ed25519Signature(signatureBytes);
+  }
+
+  /**
+   * Sign the UTF-8 encoding of `message`. The input is always treated as
+   * text — there is no hex/text heuristic. Pair with
+   * {@link Ed25519PublicKey.verifyText}.
+   *
+   * @param message - The text to sign.
+   * @returns A digital 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): Ed25519Signature {
+    return this.signBytes(TEXT_ENCODER.encode(message));
+  }
+
   /**
    * Sign the given message with the private key.
    * This function generates a digital signature for the specified message, ensuring its authenticity and integrity.
    *
+   * @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 as 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 as a string or Uint8Array in HexInput format.
    * @returns A digital signature for the provided message.
    * @throws Error if the private key has been cleared from memory.
@@ -423,11 +529,9 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * @category Serialization
    */
   sign(message: HexInput): Ed25519Signature {
-    this.ensureNotCleared();
     const messageToSign = convertSigningMessage(message);
     const messageBytes = Hex.fromHexInput(messageToSign).toUint8Array();
-    const signatureBytes = ed25519.sign(messageBytes, this.signingKey.toUint8Array());
-    return new Ed25519Signature(signatureBytes);
+    return this.signBytes(messageBytes);
   }
 
   /**
@@ -446,6 +550,13 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
   /**
    * Get the private key as a hex string with the 0x prefix.
    *
+   * 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 `Ed25519PrivateKey` 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
@@ -459,6 +570,9 @@ export class Ed25519PrivateKey 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.
    */
@@ -472,6 +586,9 @@ export class Ed25519PrivateKey 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/keyless.ts

@@ -28,6 +28,7 @@ import {
   PatchedJWKsResponse,
 } from "../../types/keyless.js";
 import { AptosConfig } from "../../api/aptosConfig.js";
+import { u64ToNumberSafe } from "../../utils/helpers.js";
 import { getAptosFullNode } from "../../client/index.js";
 import { memoizeAsync } from "../../utils/memoize.js";
 import { AccountAddress, AccountAddressInput } from "../accountAddress.js";
@@ -295,6 +296,14 @@ export class KeylessPublicKey extends AccountPublicKey {
    * Creates a KeylessPublicKey instance from a JWT and a pepper value.
    * This function is useful for generating a public key that can be used for authentication based on the provided JWT claims and pepper.
    *
+   * SECURITY: `jwtDecode` is a decode-only library — it does NOT verify the
+   * JWT signature. The cryptographic binding between the JWT and the user's
+   * identity is enforced on-chain by the keyless verifier (which validates
+   * the JWT signature against the JWK set published on-chain). Callers MUST
+   * therefore obtain `jwt` directly from a trusted IdP redirect/OAuth flow;
+   * do not accept arbitrary user-supplied JWT strings here, since a tampered
+   * JWT will derive a different account address than the chain expects.
+   *
    * @param args - The arguments for creating the KeylessPublicKey.
    * @param args.jwt - The JSON Web Token to decode.
    * @param args.pepper - The pepper value used in the key creation process.
@@ -305,6 +314,7 @@ export class KeylessPublicKey extends AccountPublicKey {
    */
   static fromJwtAndPepper(args: { jwt: string; pepper: HexInput; uidKey?: string }): KeylessPublicKey {
     const { jwt, pepper, uidKey = "sub" } = args;
+    // SECURITY: signature is not verified here — see method-level JSDoc.
     const jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
     if (typeof jwtPayload.iss !== "string") {
       throw new Error("iss was not found");
@@ -652,7 +662,7 @@ export class KeylessSignature extends Signature {
     const ephemeralSignature = EphemeralSignature.deserialize(deserializer);
     return new KeylessSignature({
       jwtHeader,
-      expiryDateSecs: Number(expiryDateSecs),
+      expiryDateSecs: u64ToNumberSafe(expiryDateSecs, "KeylessSignature.expiryDateSecs"),
       ephemeralCertificate,
       ephemeralPublicKey,
       ephemeralSignature,
@@ -1116,7 +1126,7 @@ export class ZeroKnowledgeSig extends Signature {
 
   static deserialize(deserializer: Deserializer): ZeroKnowledgeSig {
     const proof = ZkProof.deserialize(deserializer);
-    const expHorizonSecs = Number(deserializer.deserializeU64());
+    const expHorizonSecs = u64ToNumberSafe(deserializer.deserializeU64(), "ZeroKnowledgeSig.expHorizonSecs");
     const extraField = deserializer.deserializeOption("string");
     const overrideAudVal = deserializer.deserializeOption("string");
     const trainingWheelsSignature = deserializer.deserializeOption(EphemeralSignature);
@@ -1228,7 +1238,9 @@ export class KeylessConfiguration {
         gammaAbcG1: res.gamma_abc_g1,
         gammaG2: res.gamma_g2,
       }),
-      maxExpHorizonSecs: Number(config.max_exp_horizon_secs),
+      // Chain config returns u64 as a decimal string; widen → safe-narrow so
+      // a malformed/exotic value throws rather than silently truncates.
+      maxExpHorizonSecs: u64ToNumberSafe(BigInt(config.max_exp_horizon_secs), "KeylessConfiguration.maxExpHorizonSecs"),
       trainingWheelsPubkey: config.training_wheels_pubkey.vec[0],
       maxExtraFieldBytes: config.max_extra_field_bytes,
       maxJwtHeaderB64Bytes: config.max_jwt_header_b64_bytes,
@@ -1457,6 +1469,12 @@ export async function getKeylessConfig(args: {
 /**
  * Parses a JWT and returns the 'iss', 'aud', and 'uid' values.
  *
+ * SECURITY: This function decodes claims without verifying the JWT signature.
+ * The keyless on-chain verifier is the authority that binds a JWT to its IdP;
+ * the SDK only uses these claims to derive the keyless account address and
+ * package the JWT for the prover service. Callers must source `jwt` from a
+ * trusted IdP redirect flow.
+ *
  * @param args - The arguments for parsing the JWT.
  * @param args.jwt - The JWT to parse.
  * @param args.uidKey - The key to use for the 'uid' value; defaults to 'sub'.
@@ -1470,6 +1488,7 @@ export function getIssAudAndUidVal(args: { jwt: string; uidKey?: string }): {
   const { jwt, uidKey = "sub" } = args;
   let jwtPayload: JwtPayload & { [key: string]: string };
   try {
+    // SECURITY: signature is not verified here — see function-level JSDoc.
     jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
   } catch {
     throw KeylessError.fromErrorType({

package/src/core/crypto/poseidon.ts

@@ -68,7 +68,7 @@ export function hashStrToField(str: string, maxSizeBytes: number): bigint {
  */
 function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint {
   if (bytes.length > maxSizeBytes) {
-    throw new Error(`Inputted bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+    throw new Error(`Input bytes of length ${bytes.length} is longer than ${maxSizeBytes}`);
   }
   const packed = padAndPackBytesWithLen(bytes, maxSizeBytes);
   return poseidonHash(packed);
@@ -86,7 +86,7 @@ function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint {
  */
 function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
   if (bytes.length > maxSizeBytes) {
-    throw new Error(`Input bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+    throw new Error(`Input bytes of length ${bytes.length} is longer than ${maxSizeBytes}`);
   }
   const paddedStrBytes = padUint8ArrayWithZeros(bytes, maxSizeBytes);
   return packBytes(paddedStrBytes);
@@ -106,7 +106,7 @@ function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[]
  */
 export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
   if (bytes.length > maxSizeBytes) {
-    throw new Error(`Input bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+    throw new Error(`Input bytes of length ${bytes.length} is longer than ${maxSizeBytes}`);
   }
   return padAndPackBytesNoLen(bytes, maxSizeBytes).concat([BigInt(bytes.length)]);
 }
@@ -221,9 +221,9 @@ function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uin
  * @category Serialization
  */
 export function poseidonHash(inputs: (number | bigint | string)[]): bigint {
-  if (inputs.length > numInputsToPoseidonFunc.length) {
+  if (inputs.length === 0 || inputs.length > numInputsToPoseidonFunc.length) {
     throw new Error(
-      `Unable to hash input of length ${inputs.length}.  Max input length is ${numInputsToPoseidonFunc.length}`,
+      `poseidonHash requires between 1 and ${numInputsToPoseidonFunc.length} inputs, got ${inputs.length}`,
     );
   }
   return numInputsToPoseidonFunc[inputs.length - 1](inputs);

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.
    */