age-encryption/dist/index.d.ts

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/FiloSottile/age/blob/main/logo/logo_white.svg"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/FiloSottile/a

import { Stanza } from "./format.js";
export * as armor from "./armor.js";
export * as webauthn from "./webauthn.js";
export { Stanza };
/**
 * An identity that can be used to decrypt a file key.
 *
 * This is a low-level interface that can be used to implement custom identity
 * types, such as plugins or remote APIs and secrets managers. Most users won't
 * need to interact with this directly, and should instead pass a string encoding
 * of a standard identity (`AGE-SECRET-KEY-1...`) to {@link Decrypter.addIdentity}.
 */
export interface Identity {
    /**
     * Decrypt a file key, if possible, using this identity. This function is
     * called during {@link Decrypter.decrypt}, once for each file.
     *
     * @param stanzas - All stanzas from the encrypted file's header. It is the
     * identity's responsibility to identify the stanzas it's expecting, if any.
     *
     * @returns The random file key, if this identity can decrypt it, or `null`
     * if none of the stanzas matched this identity.
     *
     * @throws `unwrapFileKey` must throw only if it identifies a stanza that
     * matches this identity, but the stanza is malformed or invalid, or
     * decryption fails due to external factors (e.g. network errors). For
     * example, it must return `null`, not throw, if the file is encrypted with
     * a different e.g. key.
     */
    unwrapFileKey(stanzas: Stanza[]): Uint8Array | null | Promise<Uint8Array | null>;
}
/**
 * A recipient that can be used to encrypt a file key.
 *
 * This is a low-level interface that can be used to implement custom recipient
 * types. Most users won't need to interact with this directly, and should
 * instead pass a string encoding of a standard recipient (`age1...`) to
 * {@link Encrypter.addRecipient}.
 */
export interface Recipient {
    /**
     * Encrypt a file key for this recipient. This function is called during
     * {@link Encrypter.encrypt}, once for each file.
     *
     * @param fileKey - The random file key to encrypt.
     *
     * @returns One or more stanzas that will be included (unencrypted) in the
     * encrypted file's header. The corresponding identity (which may be the
     * built-in post-quantum hybrid, X25519, or scrypt identity, or a custom
     * {@link Identity}) must be able to identify these stanzas, and use them to
     * decrypt the file key.
     */
    wrapFileKey(fileKey: Uint8Array): Stanza[] | Promise<Stanza[]>;
}
/**
 * A ReadableStream that can also report the expected output size based on the
 * input size.
 */
export interface ReadableStreamWithSize extends ReadableStream<Uint8Array> {
    /**
     * Calculate the expected plaintext size from the given ciphertext size, or
     * vice versa.
     *
     * @param sourceSize - The size of the ciphertext or plaintext to calculate
     * the expected output size for.
     *
     * @returns The expected plaintext size if the input is a ciphertext, or the
     * expected ciphertext size if the input is a plaintext.
     *
     * @throws Only if the input is a ciphertext, and the ciphertext size is
     * too small or invalid. There are no invalid plaintext sizes.
     */
    size(sourceSize: number): number;
}
export { generateIdentity, generateHybridIdentity, generateX25519Identity, identityToRecipient } from "./recipients.js";
/**
 * Encrypts a file using the given passphrase or recipients.
 *
 * First, call {@link Encrypter.setPassphrase} to set a passphrase for symmetric
 * encryption, or {@link Encrypter.addRecipient} to specify one or more
 * recipients. Then, call {@link Encrypter.encrypt} one or more times to encrypt
 * files using the configured passphrase or recipients.
 */
export declare class Encrypter {
    private passphrase;
    private scryptWorkFactor;
    private recipients;
    /**
     * Set the passphrase to encrypt the file(s) with. This method can only be
     * called once, and can't be called if {@link Encrypter.addRecipient} has
     * been called.
     *
     * The passphrase is passed through the scrypt key derivation function, but
     * it needs to have enough entropy to resist offline brute-force attacks.
     * You should use at least 8-10 random alphanumeric characters, or 4-5
     * random words from a list of at least 2000 words.
     *
     * @param s - The passphrase to encrypt the file with.
     */
    setPassphrase(s: string): void;
    /**
     * Set the scrypt work factor to use when encrypting the file(s) with a
     * passphrase. The default is 18. Using a lower value will require stronger
     * passphrases to resist offline brute-force attacks.
     *
     * @param logN - The base-2 logarithm of the scrypt work factor.
     */
    setScryptWorkFactor(logN: number): void;
    /**
     * Add a recipient to encrypt the file(s) for. This method can be called
     * multiple times to encrypt the file(s) for multiple recipients.
     *
     * This version supports native X25519 recipients (`age1...`), hybrid
     * post-quantum recipients (`age1pq1...`), tag recipients (`age1tag1...`),
     * and hybrid tag recipients (`age1tagpq1...`).
     *
     * @param s - The recipient to encrypt the file for. Either a string
     * beginning with `age1...` or an object implementing the {@link Recipient}
     * interface.
     */
    addRecipient(s: string | Recipient): void;
    /**
     * Encrypt a file using the configured passphrase or recipients.
     *
     * @param file - The file to encrypt. If a string is passed, it will be
     * encoded as UTF-8.
     *
     * @returns A promise that resolves to the encrypted file as a Uint8Array,
     * or as a {@link ReadableStreamWithSize} if the input was a stream.
     */
    encrypt(file: Uint8Array | string): Promise<Uint8Array>;
    encrypt(file: ReadableStream<Uint8Array>): Promise<ReadableStreamWithSize>;
}
/**
 * Decrypts a file using the given identities.
 *
 * First, call {@link Decrypter.addPassphrase} to set a passphrase for symmetric
 * decryption, and/or {@link Decrypter.addIdentity} to specify one or more
 * identities. All passphrases and/or identities are tried in parallel for each
 * file. Then, call {@link Decrypter.decrypt} one or more times to decrypt files
 * using the configured passphrase and/or identities.
 */
export declare class Decrypter {
    private identities;
    /**
     * Add a passphrase to decrypt password-encrypted file(s) with. This method
     * can be called multiple times to try multiple passphrases.
     *
     * @param s - The passphrase to decrypt the file with.
     */
    addPassphrase(s: string): void;
    /**
     * Add an identity to decrypt file(s) with. This method can be called
     * multiple times to try multiple identities.
     *
     * @param s - The identity to decrypt the file with. Either a string
     * beginning with `AGE-SECRET-KEY-PQ-1...` or `AGE-SECRET-KEY-1...`, an
     * X25519 private
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey | CryptoKey}
     * object, or an object implementing the {@link Identity} interface.
     *
     * A CryptoKey object must have
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/type | type}
     * `private`,
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/algorithm | algorithm}
     * `{name: 'X25519'}`, and
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/usages | usages}
     * `["deriveBits"]`. For example:
     * ```js
     * const keyPair = await crypto.subtle.generateKey({ name: "X25519" }, false, ["deriveBits"])
     * decrypter.addIdentity(key.privateKey)
     * ```
     */
    addIdentity(s: string | CryptoKey | Identity): void;
    /**
     * Decrypt a file using the configured passphrases and/or identities.
     *
     * @param file - The file to decrypt.
     * @param outputFormat - The format to return the decrypted file in. If
     * `"text"` is passed, the file's plaintext will be decoded as UTF-8 and
     * returned as a string. Optional. It defaults to `"uint8array"`.
     * Ignored if the input is a stream.
     *
     * @returns A promise that resolves to the decrypted file, or to a
     * {@link ReadableStreamWithSize} of the decrypted file if the input was a
     * stream. The header is processed before the promise resolves.
     */
    decrypt(file: Uint8Array, outputFormat?: "uint8array"): Promise<Uint8Array>;
    decrypt(file: Uint8Array, outputFormat: "text"): Promise<string>;
    decrypt(file: ReadableStream<Uint8Array>): Promise<ReadableStreamWithSize>;
    /**
     * Decrypt the file key from a detached header. This is a low-level
     * function that can be used to implement delegated decryption logic.
     * Most users won't need this.
     *
     * It is the caller's responsibility to keep track of what file the
     * returned file key decrypts, and to ensure the file key is not used
     * for any other purpose.
     *
     * @param header - The file's textual header, including the MAC.
     *
     * @returns The file key used to encrypt the file.
     */
    decryptHeader(header: Uint8Array): Promise<Uint8Array>;
    private decryptHeaderInternal;
    private unwrapFileKey;
}