@aptos-labs/ts-sdk
Version:
Aptos TypeScript SDK
424 lines • 16.6 kB
TypeScript
import { Deserializer, Serializer } from "../../bcs/index.js";
import { Hex } from "../hex.js";
import { HexInput } from "../../types/index.js";
import { PublicKey, VerifySignatureAsyncArgs } from "./publicKey.js";
import { PrivateKey } from "./privateKey.js";
import { Signature } from "./signature.js";
import { AuthenticationKey } from "../authenticationKey.js";
/**
* Represents a Secp256r1 ECDSA public key.
*
* @extends PublicKey
* @property LENGTH - The length of the Secp256r1 public key in bytes.
* @group Implementation
* @category Serialization
*/
export declare class Secp256r1PublicKey extends PublicKey {
static readonly LENGTH: number;
static readonly COMPRESSED_LENGTH: number;
private readonly key;
readonly keyType: string;
/**
* Create a new PublicKey instance from a HexInput, which can be a string or Uint8Array.
* This constructor validates the length of the provided public key data.
*
* @param hexInput - A HexInput (string or Uint8Array) representing the public key data.
* @throws Error if the length of the public key data is not equal to Secp256r1PublicKey.LENGTH or COMPRESSED_LENGTH.
* @group Implementation
* @category Serialization
*/
constructor(hexInput: HexInput);
/**
* Get the data as a Uint8Array representation.
*
* @returns Uint8Array representation of the data.
* @group Implementation
* @category Serialization
*/
toUint8Array(): Uint8Array;
/**
* Get the public key as a hex string with the 0x prefix.
*
* @returns string representation of the public key.
* @group Implementation
* @category Serialization
*/
toString(): string;
/**
* Converts the public key to BCS (Binary Canonical Serialization) bytes.
* This function serializes the public key data into a byte array format suitable for transmission or storage.
*
* @returns Uint8Array representation of the serialized public key.
* @group Implementation
* @category Serialization
*/
bcsToBytes(): Uint8Array<ArrayBufferLike>;
/**
* 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;
/**
* 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;
/**
* Verifies a Secp256r1 signature against the public key.
*
* @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.
* @param args.signature - The signature to verify against the public key.
* @group Implementation
* @category Serialization
*/
verifySignature(args: {
message: HexInput;
signature: Signature;
}): boolean;
/**
* Note: Secp256r1Signatures can be verified synchronously.
*
* Verifies the provided signature against the given message.
* This function helps ensure the integrity and authenticity of the message by confirming that the signature is valid.
*
* @param args - The arguments for signature verification.
* @param args.message - The message that was signed.
* @param args.signature - The signature to verify, which must be an instance of Secp256r1Signature.
* @returns A boolean indicating whether the signature is valid for the given message.
* @group Implementation
* @category Serialization
*/
verifySignatureAsync(args: VerifySignatureAsyncArgs): Promise<boolean>;
/**
* Serializes the data into a byte array using the provided serializer.
* This function is essential for converting data into a format suitable for transmission or storage.
*
* @param serializer - The serializer instance used to convert the data.
* @group Implementation
* @category Serialization
*/
serialize(serializer: Serializer): void;
/**
* Deserializes a Secp256r1PublicKey from the provided deserializer.
* This function allows you to reconstruct a Secp256r1PublicKey object from its serialized byte representation.
*
* @param deserializer - The deserializer instance used to read the serialized data.
* @group Implementation
* @category Serialization
*/
static deserialize(deserializer: Deserializer): Secp256r1PublicKey;
/**
* Loads a Secp256r1PublicKey from the provided deserializer.
*
* @param deserializer - The deserializer instance used to read the serialized data.
* @group Implementation
* @category Serialization
*/
static load(deserializer: Deserializer): Secp256r1PublicKey;
/**
* Determines if the provided public key is a valid instance of a Secp256r1 public key.
* This function checks for the presence of a "key" property and validates the length of the key data.
*
* @param publicKey - The public key to validate.
* @returns A boolean indicating whether the public key is a valid Secp256r1 public key.
* @group Implementation
* @category Serialization
*/
static isInstance(publicKey: PublicKey): publicKey is Secp256r1PublicKey;
/**
* Generates an authentication key from the public key using the Secp256r1 scheme.
* This function is essential for creating a secure authentication key that can be used for further cryptographic operations.
*
* @returns {AuthenticationKey} The generated authentication key.
* @group Implementation
* @category Serialization
*/
authKey(): AuthenticationKey;
}
/**
* Represents a Secp256r1 ECDSA private key, providing functionality to create, sign messages,
* derive public keys, and serialize/deserialize the key.
* @group Implementation
* @category Serialization
*/
export declare class Secp256r1PrivateKey extends PrivateKey {
/**
* Length of Secp256r1 ecdsa private key
* @group Implementation
* @category Serialization
*/
static readonly LENGTH: number;
/**
* The private key bytes
* @private
* @group Implementation
* @category Serialization
*/
private readonly key;
/**
* Whether the key has been cleared from memory.
* @private
*/
private cleared;
/**
* Create a new PrivateKey instance from a Uint8Array or String.
*
* [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
*
* @param hexInput A HexInput (string or Uint8Array)
* @param strict If true, private key must AIP-80 compliant.
* @group Implementation
* @category Serialization
*/
constructor(hexInput: HexInput, strict?: boolean);
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* Serializes the data into a byte array using the provided serializer.
* This function is essential for converting data into a format suitable for transmission or storage.
*
* @param serializer - The serializer instance used to convert the data.
* @group Implementation
* @category Serialization
*/
serialize(serializer: Serializer): void;
/**
* Deserializes a Secp256r1PrivateKey from the provided deserializer.
* This function allows you to reconstruct a Secp256r1PrivateKey object from its serialized byte representation.
*
* @param deserializer - The deserializer instance used to read the serialized data.
* @group Implementation
* @category Serialization
*/
static deserialize(deserializer: Deserializer): Secp256r1PrivateKey;
/**
* Generate a new random private key.
*
* @returns Secp256r1PrivateKey - A newly generated Secp256r1 private key.
* @group Implementation
* @category Serialization
*/
static generate(): Secp256r1PrivateKey;
/**
* 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;
/**
* Throws if the key has already been cleared.
* @private
*/
private ensureNotCleared;
/**
* 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;
/**
* Returns whether `clear()` has been called.
*/
isCleared(): boolean;
}
export declare class WebAuthnSignature extends Signature {
signature: Hex;
authenticatorData: Hex;
clientDataJSON: Hex;
constructor(signature: HexInput, authenticatorData: HexInput, clientDataJSON: HexInput);
toUint8Array(): Uint8Array<ArrayBufferLike>;
serialize(serializer: Serializer): void;
bcsToBytes(): Uint8Array<ArrayBufferLike>;
bcsToHex(): Hex;
toStringWithoutPrefix(): string;
static deserialize(deserializer: Deserializer): WebAuthnSignature;
}
/**
* Represents a signature of a message signed using a Secp256r1 ECDSA private key.
*
* @group Implementation
* @category Serialization
*/
export declare class Secp256r1Signature extends Signature {
/**
* Secp256r1 ecdsa signatures are 256-bit.
* @group Implementation
* @category Serialization
*/
static readonly LENGTH = 64;
/**
* The signature bytes
* @private
* @group Implementation
* @category Serialization
*/
private readonly data;
/**
* Create a new Signature instance from a Uint8Array or String.
*
* @param hexInput A HexInput (string or Uint8Array)
* @group Implementation
* @category Serialization
*/
constructor(hexInput: HexInput);
/**
* Get the signature in bytes (Uint8Array).
*
* @returns Uint8Array representation of the signature
* @group Implementation
* @category Serialization
*/
toUint8Array(): Uint8Array;
/**
* Get the signature as a hex string with the 0x prefix.
*
* @returns string representation of the signature
* @group Implementation
* @category Serialization
*/
toString(): string;
/**
* Serializes the data into a byte array using the provided serializer.
* This function is essential for converting data into a format suitable for transmission or storage.
*
* @param serializer - The serializer instance used to convert the data.
* @group Implementation
* @category Serialization
*/
serialize(serializer: Serializer): void;
/**
* Deserializes a Secp256r1Signature from the provided deserializer.
* This function allows you to reconstruct a Secp256r1Signature object from its serialized byte representation.
*
* @param deserializer - The deserializer instance used to read the serialized data.
* @group Implementation
* @category Serialization
*/
static deserialize(deserializer: Deserializer): Secp256r1Signature;
}
//# sourceMappingURL=secp256r1.d.ts.map