@aptos-labs/ts-sdk 7.0.1 → 7.1.0

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}`;

package/src/internal/account.ts

@@ -83,6 +83,7 @@ import { Hex } from "../core/hex.js";
 import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types.js";
 import { getTableItem } from "./table.js";
 import { APTOS_COIN } from "../utils/index.js";
+import { memoizeAsync } from "../utils/memoize.js";
 import { AptosApiError } from "../errors/index.js";
 import { Deserializer, U8, MoveVector } from "../bcs/index.js";
 import { generateTransaction } from "./transactionSubmission.js";
@@ -381,6 +382,45 @@ export async function lookupOriginalAccountAddress(args: {
   }
 }
 
+/**
+ * Fetches the on-chain `authentication_key` for an account address and memoizes it for ~1 hour,
+ * keyed by `(network or fullnode URL, address)`. Used by the encrypted-transaction builder to
+ * derive auth keys when the caller does not pass them explicitly. Callers that just rotated their
+ * key and need an immediate fresh read should pass the auth key explicitly instead of relying on
+ * this cache.
+ *
+ * If the address has no `0x1::account::Account` resource on chain (a brand-new account, or a light
+ * account with balance/objects but no explicit resource), returns the address bytes as the
+ * authentication key — matching the chain's account-creation convention (see
+ * [`doesAccountExistAtAddress`]). This makes encrypted-transaction builds work for not-yet-created
+ * signers (e.g., fee-payer sponsorship of an uncreated sender).
+ */
+export async function fetchAndCacheAuthKeyForAddress(args: {
+  aptosConfig: AptosConfig;
+  accountAddress: AccountAddressInput;
+}): Promise<AuthenticationKey> {
+  const { aptosConfig, accountAddress } = args;
+  const address = AccountAddress.from(accountAddress);
+  const addr = address.toString();
+  const cacheKey = `auth-key-${aptosConfig.fullnode ?? aptosConfig.network}-${addr}`;
+  return memoizeAsync(
+    async () => {
+      try {
+        const info = await getInfoUtil({ aptosConfig, accountAddress: addr });
+        return new AuthenticationKey({ data: info.authentication_key });
+      } catch (err) {
+        if (err instanceof AptosApiError && err.data?.error_code === "account_not_found") {
+          // Chain convention: with no Account resource the auth key is the address itself.
+          return new AuthenticationKey({ data: address.toUint8Array() });
+        }
+        throw err;
+      }
+    },
+    cacheKey,
+    60 * 60 * 1000,
+  )();
+}
+
 /**
  * Retrieves the count of tokens owned by a specific account address.
  *
@@ -958,17 +998,27 @@ async function doesAccountExistAtAddress(args: {
   }
 }
 
-const rotateAuthKeyAbi: EntryFunctionABI = {
-  typeParameters: [],
-  parameters: [
-    new TypeTagU8(),
-    TypeTagVector.u8(),
-    new TypeTagU8(),
-    TypeTagVector.u8(),
-    TypeTagVector.u8(),
-    TypeTagVector.u8(),
-  ],
-};
+// Lazy: instantiating TypeTagU8 at module-init time creates an ESM circular
+// import (structEnumParser → internal/account → transactions/index → typeTag)
+// where TypeTagU8 may not yet be a constructor when this file evaluates.
+// Building the ABI on first use sidesteps the order dependency.
+let _rotateAuthKeyAbi: EntryFunctionABI | undefined;
+function rotateAuthKeyAbi(): EntryFunctionABI {
+  if (!_rotateAuthKeyAbi) {
+    _rotateAuthKeyAbi = {
+      typeParameters: [],
+      parameters: [
+        new TypeTagU8(),
+        TypeTagVector.u8(),
+        new TypeTagU8(),
+        TypeTagVector.u8(),
+        TypeTagVector.u8(),
+        TypeTagVector.u8(),
+      ],
+    };
+  }
+  return _rotateAuthKeyAbi;
+}
 
 /**
  * Rotates the authentication key for a given account.
@@ -1065,16 +1115,22 @@ async function rotateAuthKeyWithChallenge(
         MoveVector.U8(proofSignedByCurrentKey.toUint8Array()),
         MoveVector.U8(proofSignedByNewKey.toUint8Array()),
       ],
-      abi: rotateAuthKeyAbi,
+      abi: rotateAuthKeyAbi(),
     },
     options,
   });
 }
 
-const rotateAuthKeyUnverifiedAbi: EntryFunctionABI = {
-  typeParameters: [],
-  parameters: [new TypeTagU8(), TypeTagVector.u8()],
-};
+let _rotateAuthKeyUnverifiedAbi: EntryFunctionABI | undefined;
+function rotateAuthKeyUnverifiedAbi(): EntryFunctionABI {
+  if (!_rotateAuthKeyUnverifiedAbi) {
+    _rotateAuthKeyUnverifiedAbi = {
+      typeParameters: [],
+      parameters: [new TypeTagU8(), TypeTagVector.u8()],
+    };
+  }
+  return _rotateAuthKeyUnverifiedAbi;
+}
 
 /**
  * Rotates the authentication key for a given account without verifying the new key.
@@ -1105,7 +1161,7 @@ export async function rotateAuthKeyUnverified(args: {
         new U8(accountPublicKeyToSigningScheme(toNewPublicKey)), // to scheme
         MoveVector.U8(accountPublicKeyToBaseAccountPublicKey(toNewPublicKey).toUint8Array()),
       ],
-      abi: rotateAuthKeyUnverifiedAbi,
+      abi: rotateAuthKeyUnverifiedAbi(),
     },
     options,
   });

package/src/internal/keyless.ts

@@ -108,6 +108,12 @@ export async function getProof(args: {
   if (Hex.fromHexInput(pepper).toUint8Array().length !== KeylessAccount.PEPPER_LENGTH) {
     throw new Error(`Pepper needs to be ${KeylessAccount.PEPPER_LENGTH} bytes`);
   }
+  // SECURITY: jwtDecode does NOT verify the JWT signature. The prover service
+  // is the next hop and will reject a tampered JWT, and the on-chain keyless
+  // verifier validates the signature against the JWK set published on-chain.
+  // Callers must still source `jwt` from a trusted IdP redirect flow — accepting
+  // a user-supplied JWT here will produce a useless proof, not a forged one,
+  // but it also leaks the (unverified) claims to the prover.
   const decodedJwt = jwtDecode<JwtPayload>(jwt);
   if (typeof decodedJwt.iat !== "number") {
     throw new Error("iat was not found");
@@ -261,6 +267,28 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     }
   }
 
+  // SSRF guard: require HTTPS. Without this check a caller-supplied `iss` or
+  // `jwksUrl` could redirect the fetch to plaintext HTTP, cloud-metadata
+  // endpoints (e.g., `http://169.254.169.254/...`), internal services, or
+  // non-network schemes like `file:` / `data:`. The on-chain JWKS update is
+  // a privileged operation, so we refuse to source key material over an
+  // untrusted transport.
+  let parsedJwksUrl: URL;
+  try {
+    parsedJwksUrl = new URL(jwksUrl);
+  } catch {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: "JWKS URL is not a valid URL",
+    });
+  }
+  if (parsedJwksUrl.protocol !== "https:") {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS URL must use https: (got ${parsedJwksUrl.protocol})`,
+    });
+  }
+
   let response: Response;
 
   try {
@@ -275,13 +303,19 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     } else {
       errorMessage = `error unknown - ${error}`;
     }
+    // Surface only the origin (scheme + host + port) of the JWKS URL in the
+    // user-facing error. The full URL, which may include `iss`-derived path
+    // segments or tenant identifiers from enterprise IdPs, is intentionally
+    // omitted to avoid leaking infrastructure details into logs / crash
+    // reporters.
     throw KeylessError.fromErrorType({
       type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
-      details: `Failed to fetch JWKS at ${jwksUrl}: ${errorMessage}`,
+      details: `Failed to fetch JWKS from ${parsedJwksUrl.origin}: ${errorMessage}`,
     });
   }
 
-  const jwks = (await response.json()) as JWKS;
+  const rawJwks: unknown = await response.json();
+  const jwks = validateJwksResponse(rawJwks, parsedJwksUrl.origin);
   return generateTransaction({
     aptosConfig,
     sender: sender.accountAddress,
@@ -298,3 +332,55 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     options,
   });
 }
+
+/**
+ * Caller can supply any IdP URL, so the JWKS response is untrusted. The shape
+ * isn't enforced by the TS cast above, and `jwks.keys.map(...)` would throw a
+ * confusing `TypeError: Cannot read properties of ... 'map'` on malformed
+ * payloads. Worse, a hostile/buggy IdP could return an unboundedly large
+ * `keys` array and we'd pack the whole thing into the on-chain transaction.
+ *
+ * Validate the four fields we actually use (kid, alg, e, n), cap the key
+ * count, and surface a single descriptive error when anything is off.
+ */
+const MAX_FEDERATED_JWKS_KEYS = 32;
+
+function validateJwksResponse(raw: unknown, originForError: string): JWKS {
+  if (raw === null || typeof raw !== "object" || !Array.isArray((raw as { keys?: unknown }).keys)) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} is missing a 'keys' array`,
+    });
+  }
+  const keys = (raw as { keys: unknown[] }).keys;
+  if (keys.length === 0) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} has an empty 'keys' array`,
+    });
+  }
+  if (keys.length > MAX_FEDERATED_JWKS_KEYS) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} has ${keys.length} keys (max ${MAX_FEDERATED_JWKS_KEYS})`,
+    });
+  }
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i];
+    if (key === null || typeof key !== "object") {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+        details: `JWKS response from ${originForError}: key at index ${i} is not an object`,
+      });
+    }
+    for (const field of ["kid", "alg", "e", "n"] as const) {
+      if (typeof (key as Record<string, unknown>)[field] !== "string") {
+        throw KeylessError.fromErrorType({
+          type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+          details: `JWKS response from ${originForError}: key at index ${i} is missing string field '${field}'`,
+        });
+      }
+    }
+  }
+  return raw as JWKS;
+}

package/src/internal/transaction.ts

@@ -200,6 +200,16 @@ export async function waitForTransaction(args: {
   let backoffIntervalMs = 200;
   const backoffMultiplier = 1.5;
 
+  // A response is "settled" when the fullnode has populated the execution result.
+  // There is a window where `type` flips to a committed variant (e.g. User) before
+  // `success`/`vm_status` are filled in — during that window we must keep polling,
+  // not treat the partial response as a failure.
+  function isUnsettled(txn: TransactionResponse | undefined): boolean {
+    if (txn === undefined) return true;
+    if (txn.type === TransactionResponseType.Pending) return true;
+    return (txn as { success?: boolean }).success === undefined;
+  }
+
   /**
    * Handles API errors by throwing the last error or a timeout error for a failed transaction.
    *
@@ -223,7 +233,7 @@ export async function waitForTransaction(args: {
   // check to see if the txn is already on the blockchain
   try {
     lastTxn = await getTransactionByHash({ aptosConfig, transactionHash });
-    isPending = lastTxn.type === TransactionResponseType.Pending;
+    isPending = isUnsettled(lastTxn);
   } catch (e) {
     handleAPIError(e);
   }
@@ -233,7 +243,7 @@ export async function waitForTransaction(args: {
     const startTime = Date.now();
     try {
       lastTxn = await longWaitForTransaction({ aptosConfig, transactionHash });
-      isPending = lastTxn.type === TransactionResponseType.Pending;
+      isPending = isUnsettled(lastTxn);
     } catch (e) {
       handleAPIError(e);
     }
@@ -248,7 +258,7 @@ export async function waitForTransaction(args: {
     try {
       lastTxn = await getTransactionByHash({ aptosConfig, transactionHash });
 
-      isPending = lastTxn.type === TransactionResponseType.Pending;
+      isPending = isUnsettled(lastTxn);
 
       if (!isPending) {
         break;
@@ -280,6 +290,15 @@ export async function waitForTransaction(args: {
       lastTxn,
     );
   }
+  // If we exited the loop with a committed-shaped response that hasn't been
+  // fully populated yet (success/vm_status still undefined), this is the
+  // indexer-lag race — surface it as a timeout, not as a failed transaction.
+  if ((lastTxn as { success?: boolean }).success === undefined) {
+    throw new WaitForTransactionError(
+      `Transaction ${transactionHash} did not finish indexing within ${timeoutSecs} seconds`,
+      lastTxn,
+    );
+  }
   if (!checkSuccess) {
     return lastTxn;
   }