@provablehq/sdk/dist/testnet/keys/keystore/file.d.ts

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

import { FunctionKeyPair } from "../../models/keyPair.js";
import { KeyFingerprint } from "../verifier/interface.js";
import { KeyLocator, KeyStore, ProvingKeyLocator, VerifyingKeyLocator } from "./interface.js";
import { ProvingKey, VerifyingKey } from "../../wasm.js";
export declare class LocalFileKeyStore implements KeyStore {
    private directory;
    private readonly keyVerifier;
    /**
     * Creates a new directory at the given path or CURRENTDIR/.aleo if none is provided to store keys.
     * If a custom directory is passed and its last path segment is not ".aleo", ".aleo" is appended
     * so keys are stored under that subdirectory (e.g. /home/project → /home/project/.aleo).
     *
     * @param {string} [directory] - Optional custom directory path for key storage. Defaults to ".aleo" in current working directory.
     * @throws {Error} If directory creation fails.
     */
    constructor(directory?: string);
    /**
     * Validates a single locator component for unsafe filesystem characters.
     *
     * @private
     * @param {string} value - The component value to validate.
     * @param {string} label - Label for error messages (e.g. "program", "functionName").
     * @throws {InvalidLocatorError} If the value is empty, contains traversal sequences, path separators, or null bytes.
     */
    private validateComponent;
    /**
     * Validates that a numeric locator field is not negative.
     *
     * @private
     * @param {number} value - The numeric value to validate.
     * @param {string} label - Label for error messages (e.g. "edition", "amendment").
     * @throws {InvalidLocatorError} If the value is negative.
     */
    private validateNonNegative;
    /**
     * Serializes a {@link KeyLocator} to a filesystem-safe flat string, validating components first.
     *
     * For prover/verifier keys: `{program}.{functionName}.e{edition}.a{amendment}.{network}.{keyType}`
     * For translation keys: `{program}.{functionName}.e{edition}.a{amendment}.{network}.translation.{recordName}.{recordInputPosition}`
     *
     * Note: The optional `checksum` field is excluded — it is used for integrity verification only
     * (via {@link checksumToFingerprint}) and is not part of the key identity.
     *
     * @private
     * @param {KeyLocator} locator - The key locator.
     * @returns {string} A dot-delimited string safe for use as a filename.
     * @throws {InvalidLocatorError} If any component contains unsafe characters.
     */
    private serializeLocator;
    /**
     * Converts an optional checksum string from a locator into a KeyFingerprint
     * suitable for the key verifier, using the actual key byte length for size.
     *
     * @private
     */
    private checksumToFingerprint;
    /**
     * Generates the path for a key metadata file based on the locator.
     *
     * @private
     * @param {string} locator - Unique identifier for the key.
     * @returns {string} Full filesystem path to the metadata file.
     */
    private metadataPath;
    /**
     * Reads and parses the key fingerprint metadata from storage.
     *
     * @private
     * @param {string} locator - Unique identifier for the key.
     * @returns {Promise<KeyFingerprint | null>} The key fingerprint if found, null if file doesn't exist.
     * @throws {Error} If file read fails for any reason other than not found.
     */
    private readKeyMetadata;
    /**
     * Writes key fingerprint metadata to storage.
     *
     * @private
     * @param {string} locator - Unique identifier for the key.
     * @param {KeyFingerprint} metadata - Key fingerprint metadata to store.
     * @returns {Promise<void>}
     * @throws {Error} If directory creation or file write fails.
     */
    private writeKeyMetadata;
    private readFileOptional;
    /**
     * Atomically writes data to a file, ensuring the parent directories exist.
     *
     * @private
     * @param {string} filepath - Full path to the file to write
     * @param {Uint8Array} data - Binary data to write to the file
     * @returns {Promise<void>} Resolves when write is complete
     * @throws {Error} If directory creation or file write fails
     */
    private writeFileAtomic;
    /**
     * Recursively removes all files and subdirectories under the given directory, then removes the directory itself.
     * Uses fs.rm with recursive: true and force: true so that symbolic links are removed without following them,
     * avoiding deletion of content outside the keystore.
     *
     * @private
     * @param {string} dir - Directory path to clear
     * @returns {Promise<void>} Resolves when clearing is complete
     * @throws {Error} If directory removal fails for reasons other than non-existence
     */
    private clearDirectory;
    /**
     * Retrieves the key bytes from storage and optionally verifies them.
     *
     * @param {KeyLocator} locator - The key locator with optional checksum for verification.
     * @returns {Promise<Uint8Array | null>} The key bytes if found and verified, null if not found.
     * @throws {KeyVerificationError} If verification fails.
     */
    getKeyBytes(locator: KeyLocator): Promise<Uint8Array | null>;
    /**
     * Retrieves and verifies a proving key from storage.
     *
     * @param {ProvingKeyLocator} locator - The proving key locator.
     * @returns {Promise<ProvingKey | null>} The proving key if found and verified, null if not found.
     * @throws {KeyVerificationError} If verification fails.
     * @throws {Error} If key bytes cannot be parsed into a valid ProvingKey.
     */
    getProvingKey(locator: ProvingKeyLocator): Promise<ProvingKey | null>;
    /**
     * Retrieves and verifies a verifying key from storage.
     *
     * @param {VerifyingKeyLocator} locator - The verifying key locator.
     * @returns {Promise<VerifyingKey | null>} The verifying key if found and verified, null if not found.
     * @throws {KeyVerificationError} If verification fails.
     * @throws {Error} If key bytes cannot be parsed into a valid VerifyingKey.
     */
    getVerifyingKey(locator: VerifyingKeyLocator): Promise<VerifyingKey | null>;
    /**
     * Stores proving and verifying keys in key storage.
     *
     * @param {ProvingKeyLocator} proverLocator The locator for the proving key.
     * @param {VerifyingKeyLocator} verifierLocator The locator for the verifying key.
     * @param {FunctionKeyPair} keys The proving and verifying keys.
     */
    setKeys(proverLocator: ProvingKeyLocator, verifierLocator: VerifyingKeyLocator, keys: FunctionKeyPair): Promise<void>;
    /**
     * Store a raw key in storage along with its fingerprint metadata for future verification.
     *
     * @param {Uint8Array} keyBytes The raw key bytes.
     * @param {KeyLocator} locator The unique locator for the key.
     * @returns {Promise<void>}
     * @throws {Error} If computing key metadata or writing to storage fails
     */
    setKeyBytes(keyBytes: Uint8Array, locator: KeyLocator): Promise<void>;
    /**
     * Returns stored metadata for a key, if any.
     *
     * @param {KeyLocator} locator The unique locator for the key.
     * @returns {Promise<KeyFingerprint | null>} The stored fingerprint metadata, or null if none exists.
     */
    getKeyMetadata(locator: KeyLocator): Promise<KeyFingerprint | null>;
    /**
     * Checks if a key exists for the given locator.
     *
     * @param {KeyLocator} locator - The unique key locator.
     * @returns {Promise<boolean>} True if key exists, false otherwise.
     */
    has(locator: KeyLocator): Promise<boolean>;
    /**
     * Deletes a key and its associated metadata from storage. Silently ignores errors if files don't exist.
     *
     * @param {KeyLocator} locator - The unique key locator.
     * @returns {Promise<void>}
     */
    delete(locator: KeyLocator): Promise<void>;
    /**
     * Clears the key storage directory by recursively removing all files and subdirectories under it, then removes the keystore directory itself.
     *
     * @returns {Promise<void>}
     * @throws {Error} If directory listing fails for reasons other than non-existence.
     */
    clear(): Promise<void>;
}