email-alias-core

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

Core Concept

email-alias-core allows you to generate unique, secure, and verifiable email aliases for your custom domain. Instead of using your real email address for online services, you can generate an alias like [email protected].

Note: The alias format now includes a key prefix for efficient validation: <aliasParts>-<keyPrefix><hash>@domain.com where keyPrefix is the first 2 hex chars of the secret key, and hash is the truncated HMAC signature.

The system is "verifiable" because it uses a secret key and HMAC-SHA256 to generate a cryptographic signature for each alias. This means your email infrastructure (e.g., a Cloudflare Worker) can instantly verify if an incoming email is addressed to a legitimately generated alias, effectively stopping spam and phishing attempts sent to guessed addresses.

This library provides the core functions to generate new aliases, validate existing ones, and generate secure random strings for various use cases.

Why Use This System vs. a Simple Catch-All?

A common way to create aliases is with a "catch-all" address (*@your-domain.com), which forwards all mail to your inbox. While simple, this approach has a major vulnerability: it becomes a magnet for spam. Spammers run dictionary attacks, sending mail to common names like info@, contact@, and billing@ at thousands of domains. With a catch-all, you receive all of this junk mail.

This HMAC-based system solves that problem at the source. An alias is only considered valid if its signature can be cryptographically verified with your secret key. When a spammer sends an email to a guessed address like [email protected], the signature will not match. Your email infrastructure (e.g., a Cloudflare Worker) will reject the email before it ever has a chance to reach your inbox.

This provides the convenience of on-the-fly alias creation without the massive spam vulnerability of a traditional catch-all.

Features

• Secure: Uses HMAC-SHA256 with a secret key you control and cryptographically secure random generation.
• Zero-Dependency: Runs in any modern JavaScript environment (Node.js, Deno, Browsers, Cloudflare Workers) without any external packages.
• Isomorphic: The same code works on the server for validation and on the client for generation.
• Flexible: Allows for categorization of aliases using multiple parts (e.g., ['type', 'service']).
• URL-Safe: Generates URL-safe random strings perfect for tokens, keys, and identifiers.
• MIT Licensed: Free to use for any project, commercial or open source.

Installation

npm install email-alias-core

or

yarn add email-alias-core

or

pnpm install email-alias-core

Usage

The library exports three main functions: generateEmailAlias, validateEmailAlias, and generateSecureRandomString.

import {
  generateEmailAlias,
  validateEmailAlias,
  generateSecureRandomString,
} from "email-alias-core";

const config = {
  secretKey: "a-very-secret-key-that-is-long-enough",
  domain: "example.com",
};

// --- Generating an Alias ---

async function createAlias() {
  const alias = await generateEmailAlias({
    ...config,
    aliasParts: ["shop", "amazon"],
  });
  console.log(alias);
  // Example output: [email protected]
}

// --- Validating an Alias ---
// NOTE: validateEmailAlias now takes a keysRecipientMap object, not a single secretKey.

async function checkAlias(incomingAlias) {
  // You can map multiple keys to recipients if you rotate keys or support multiple users.
  const keysRecipientMap = {
    "a-very-secret-key-that-is-long-enough": "[email protected]",
    // ...add more keys if needed
  };

  const recipient = await validateEmailAlias({
    keysRecipientMap,
    fullAlias: incomingAlias,
    // hashLength is optional, defaults to 8
  });

  if (recipient) {
    console.log(`'${incomingAlias}' is a legitimate alias for: ${recipient}`);
  } else {
    console.log(`'${incomingAlias}' is NOT a valid alias. Rejecting email.`);
  }
}

// --- Generating Secure Random Strings ---

function createRandomStrings() {
  // Generate a random API key
  const apiKey = generateSecureRandomString(32);
  console.log(`API Key: ${apiKey}`);
  // Example output: API Key: a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6

  // Generate a session token
  const sessionToken = generateSecureRandomString(64);
  console.log(`Session Token: ${sessionToken}`);

  // Use in email alias generation
  const randomService = generateSecureRandomString(8);
  // This could be used as a unique identifier for services
}

createAlias();
checkAlias("[email protected]");
checkAlias("[email protected]");
createRandomStrings();

API

generateEmailAlias(options)

Returns a Promise<string> with the full email alias.

• options <Object>
  • secretKey <string>: Required. Your master secret key.
  • aliasParts <string[]>: Required. An array of strings to form the identifiable part of the alias (e.g., ['shop', 'amazon']).
  • domain <string>: Required. Your custom domain (e.g., 'example.com').
  • hashLength <number>: Optional. The length of the HMAC signature (including key prefix). Defaults to 8.

Alias format: <aliasParts>-<keyPrefix><hash>@domain.com where keyPrefix is the first 2 hex chars of the secret key, and hash is the truncated HMAC signature.

validateEmailAlias(options)

Returns a Promise<string> with the recipient value if valid, or an empty string if invalid.

• options <Object>
  • keysRecipientMap <Record<string, string>>: Required. An object mapping secret keys to recipient identifiers (e.g., email addresses or user IDs).
  • fullAlias <string>: Required. The full email alias to validate.
  • hashLength <number>: Optional. The length of the hash in the alias. Defaults to 8. Must match the length used during generation.

Note: This function now supports efficient validation with multiple keys by using the key prefix embedded in the alias.

generateSecureRandomString(length)

Returns a string containing a cryptographically secure, URL-safe random string.

• length <number>: Required. The desired length of the random string in characters.

Features:

• Uses cryptographically secure random number generation (crypto.getRandomValues)
• Produces URL-safe base64 encoded strings (using - and _ instead of + and /)
• No padding characters (=) included
• Works consistently across Node.js, browsers, and Cloudflare Workers
• Perfect for API keys, session tokens, unique identifiers, and secure random components

Example:

// Generate different length strings
const shortId = generateSecureRandomString(8); // e.g., "a1B2c3D4"
const apiKey = generateSecureRandomString(32); // e.g., "a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6"
const sessionToken = generateSecureRandomString(64); // 64-character secure token

// Use in alias generation for unique service identifiers
const uniqueService = generateSecureRandomString(6);
const alias = await generateEmailAlias({
  secretKey: "your-secret-key",
  aliasParts: ["temp", uniqueService],
  domain: "example.com",
});