@provablehq/sdk/dist/mainnet/security.d.ts

A Software Development Kit (SDK) for Zero-Knowledge Transactions

import { ViewKey, Authorization, ProvingRequest } from "./wasm.js";
/**
 * Encrypt an authorization with a cryptobox X25519 public key (libsodium-compatible wire format).
 *
 * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
 * @param {Authorization} authorization the authorization to encrypt.
 *
 * @returns {string} the encrypted authorization in RFC 4648 standard Base64.
 */
export declare function encryptAuthorization(publicKey: string, authorization: Authorization): string;
/**
 * Encrypt a ProvingRequest with a cryptobox X25519 public key (libsodium-compatible wire format).
 *
 * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
 * @param {ProvingRequest} provingRequest the ProvingRequest to encrypt.
 *
 * @returns {string} the encrypted ProvingRequest in RFC 4648 standard Base64.
 */
export declare function encryptProvingRequest(publicKey: string, provingRequest: ProvingRequest): string;
/**
 * Serialize a ProvingRequest for later encryption with
 * `encryptSerializedProvingRequest`.
 *
 * Useful when the request may have to be encrypted more than once: the
 * delegated proving service's one-time keys are single-use, so a client that
 * needs to resend a request (e.g. after the service rejected a spent or
 * unknown `key_id`) can keep the serialized form and re-encrypt it for a
 * fresh key instead of rebuilding and re-signing the request.
 *
 * The returned buffer contains the plaintext request (including the signed
 * authorization and its inputs) and is owned by the caller: keep it only as
 * long as a resend may still be needed, then overwrite it with
 * `zeroizeBytes(serialized)`. Zeroization in JavaScript is best-effort (see
 * `zeroizeBytes`), and transient copies made inside the wasm boundary by
 * `toBytesLe` are outside its reach.
 *
 * @param {ProvingRequest} provingRequest the ProvingRequest to serialize.
 *
 * @returns {Uint8Array} the serialized ProvingRequest bytes.
 */
export declare function serializeProvingRequest(provingRequest: ProvingRequest): Uint8Array;
/**
 * Encrypt an already-serialized ProvingRequest (as produced by
 * `serializeProvingRequest`) with a cryptobox X25519 public key
 * (libsodium-compatible wire format).
 *
 * Produces exactly the same ciphertext format as `encryptProvingRequest` —
 * `encryptSerializedProvingRequest(pk, serializeProvingRequest(req))` and
 * `encryptProvingRequest(pk, req)` are interchangeable from the proving
 * service's point of view.
 *
 * The input buffer is not mutated and deliberately not zeroized here: the
 * caller keeps ownership so the same bytes can be re-encrypted for another
 * one-time key (retry). Call `zeroizeBytes(serializedProvingRequest)` once
 * no resend can be needed anymore.
 *
 * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
 * @param {Uint8Array} serializedProvingRequest the serialized ProvingRequest bytes.
 *
 * @returns {string} the encrypted ProvingRequest in RFC 4648 standard Base64.
 */
export declare function encryptSerializedProvingRequest(publicKey: string, serializedProvingRequest: Uint8Array): string;
/**
 * Encrypt a view key with a cryptobox X25519 public key (libsodium-compatible wire format).
 *
 * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
 * @param {ViewKey} viewKey the view key to encrypt.
 *
 * @returns {string} the encrypted view key in RFC 4648 standard Base64.
 */
export declare function encryptViewKey(publicKey: string, viewKey: ViewKey): string;
/**
 * Encrypt a record scanner registration request.
 *
 * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
 * @param {ViewKey} viewKey the view key to encrypt.
 * @param {number} start the start height of the registration request.
 *
 * @returns {string} the encrypted view key in RFC 4648 standard Base64.
 */
export declare function encryptRegistrationRequest(publicKey: string, viewKey: ViewKey, start: number): string;
/**
 * Best-effort zeroization of a byte array by overwriting all bytes with zeros.
 * Use this to clear sensitive data (e.g., key bytes) from memory when working
 * with Uint8Array representations of keys or other secrets.
 *
 * This is best-effort in JavaScript — the JIT compiler could theoretically
 * elide the fill if the array is never read again (though current engines
 * do not). For deterministic zeroization of key material, use
 * `Account.destroy()` or call `.free()` on key objects (PrivateKey, ViewKey,
 * ComputeKey, GraphKey) whose Rust Drop implementations zeroize memory
 * before deallocation.
 *
 * Note: This cannot zeroize JavaScript strings, which are immutable and managed
 * by the garbage collector. Prefer using byte array representations of sensitive
 * data over strings whenever possible.
 *
 * @param {Uint8Array} bytes The byte array to zeroize
 *
 * @example
 * const keyBytes = privateKey.toBytesLe();
 * // ... use keyBytes ...
 * zeroizeBytes(keyBytes); // Overwrite with zeros when done
 */
export declare function zeroizeBytes(bytes: Uint8Array): void;