email-alias-core/dist/index.d.ts

A zero-dependency library to create and verify secure email aliases for custom domains.

/**
 * @license MIT
 * @copyright 2025 karteekiitg
 */
/**
 * Options for the {@link generateEmailAlias} function.
 * @public
 */
interface GenerateOptions {
    /**
     * The master secret key for HMAC generation.
     */
    secretKey: string;
    /**
     * An array of strings to form the identifiable part of the alias.
     * These will be joined by a hyphen.
     * @example `['shop', 'amazon']`
     */
    aliasParts: string[];
    /**
     * The custom domain for the alias.
     * @example `example.com`
     */
    domain: string;
    /**
     * The desired length of the hexadecimal hash signature.
     * @defaultValue 8
     */
    hashLength?: number;
}
/**
 * Options for the {@link validateEmailAlias} function.
 * @public
 */
interface ValidateOptions {
    /**
     * The keysRecipientMap is a map of key to recipient emails which is used for validation.
     */
    keysRecipientMap: Record<string, string>;
    /**
     * The full email alias to validate.
     * @example `shop-amazon-a1b2c3d4@example.com`
     */
    fullAlias: string;
    /**
     * The length of the hash used in the alias. Must match the length used during generation.
     * @defaultValue 8
     */
    hashLength?: number;
}
/**
 * Generates a verifiable, HMAC-based email alias for a custom domain.
 *
 * @remarks
 * This function is deterministic. Given the same inputs, it will always produce
 * the same output. It is safe to use in any modern JavaScript environment that
 * supports the Web Crypto API.
 *
 * @param options - The options object for generating the alias. See {@link GenerateOptions}.
 * @returns A promise that resolves to the full, generated email alias.
 * @throws An error if `aliasParts` is an empty array.
 *
 * @public
 */
export declare function generateEmailAlias({ secretKey, aliasParts, domain, hashLength, }: GenerateOptions): Promise<string>;
/**
 * Validates a verifiable email alias against a secret key.
 *
 * @remarks
 * This function performs the same HMAC signature generation as `generateEmailAlias`
 * and compares the result to the hash in the provided alias.
 * It will gracefully return `false` for any malformed alias string.
 *
 * @param options - The options object for validating the alias. See {@link ValidateOptions}.
 * @returns A promise that resolves to `true` if the alias is valid, and `false` otherwise.
 *
 * @public
 */
export declare function validateEmailAlias({ keysRecipientMap, fullAlias, hashLength, }: ValidateOptions): Promise<string>;
/**
 * Generates a cryptographically secure, URL-safe random string.
 *
 * @remarks
 * This function works in browser, Node.js, and Cloudflare Workers environments.
 * It generates random bytes and encodes them as a URL-safe base64 string.
 *
 * @param length - The desired length of the random string in characters.
 * @returns A random URL-safe string.
 * @throws An error if `length` is not a positive integer or if the crypto API is unavailable.
 *
 * @public
 */
export declare function generateSecureRandomString(length: number): string;
export {};
//# sourceMappingURL=index.d.ts.map