@push.rocks/smartmta 8.2.1 → 9.1.0

package/ts/mail/routing/functions.routing.validation.ts

@@ -1,3 +1,123 @@
+import type { ISmtpAuthAccount, ISmtpScramVerifier } from './interfaces.js';
+
+/**
+ * PBKDF2 iteration bounds for SCRAM verifiers. The lower bound is the RFC
+ * 5802 recommended minimum; the upper bound caps per-attempt CPU so a single
+ * AUTH cannot exhaust the Rust bridge's 5s callback window.
+ */
+export const SCRAM_MIN_ITERATIONS = 4096;
+export const SCRAM_MAX_ITERATIONS = 1_000_000;
+
+const isBase64OfLength = (value: unknown, byteLength?: number): boolean => {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  try {
+    const decoded = Buffer.from(value, 'base64');
+    if (decoded.length === 0) return false;
+    // Reject strings that silently drop invalid characters on decode.
+    if (decoded.toString('base64').replace(/=+$/, '') !== value.replace(/=+$/, '')) {
+      return false;
+    }
+    return byteLength === undefined || decoded.length === byteLength;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Loudly reject unusable SMTP auth account configurations. Every failure
+ * mode here would otherwise degrade into a silent deny-all (empty scope
+ * patterns) or a silent authentication failure (malformed verifier keys).
+ */
+export function assertValidAuthAccounts(
+  accounts: ISmtpAuthAccount[] | undefined,
+): void {
+  if (accounts === undefined) return;
+  if (!Array.isArray(accounts)) {
+    throw new Error('auth.accounts must be an array');
+  }
+  const usernames = new Set<string>();
+  for (const account of accounts) {
+    const username = account?.username;
+    if (typeof username !== 'string' || !username.trim()) {
+      throw new Error('auth.accounts entries require a non-empty username');
+    }
+    const owner = `auth account ${username}`;
+    if (usernames.has(username)) {
+      throw new Error(`${owner} is configured more than once`);
+    }
+    usernames.add(username);
+
+    const credential = account.credential as
+      | { verifier?: unknown; password?: unknown }
+      | undefined;
+    const hasVerifier = credential?.verifier !== undefined;
+    const hasPassword = credential?.password !== undefined;
+    if (hasVerifier === hasPassword) {
+      throw new Error(
+        `${owner} credential must contain exactly one of verifier or password`,
+      );
+    }
+    if (hasPassword && typeof credential!.password !== 'string') {
+      throw new Error(`${owner} credential.password must be a string`);
+    }
+    if (hasVerifier) {
+      const verifier = credential!.verifier as Partial<ISmtpScramVerifier>;
+      if (verifier?.algorithm !== 'SCRAM-SHA-256') {
+        throw new Error(`${owner} verifier.algorithm must be SCRAM-SHA-256`);
+      }
+      if (
+        !Number.isInteger(verifier.iterations)
+        || verifier.iterations! < SCRAM_MIN_ITERATIONS
+        || verifier.iterations! > SCRAM_MAX_ITERATIONS
+      ) {
+        throw new Error(
+          `${owner} verifier.iterations must be an integer between ${SCRAM_MIN_ITERATIONS} and ${SCRAM_MAX_ITERATIONS}`,
+        );
+      }
+      if (!isBase64OfLength(verifier.salt)) {
+        throw new Error(`${owner} verifier.salt must be non-empty base64`);
+      }
+      if (!isBase64OfLength(verifier.storedKey, 32)) {
+        throw new Error(`${owner} verifier.storedKey must be base64 of a 32-byte key`);
+      }
+      if (!isBase64OfLength(verifier.serverKey, 32)) {
+        throw new Error(`${owner} verifier.serverKey must be base64 of a 32-byte key`);
+      }
+    }
+
+    const scope = account.scope;
+    if (scope === undefined) continue;
+    if (
+      !Array.isArray(scope.senders)
+      || scope.senders.length === 0
+      || scope.senders.some((pattern) => typeof pattern !== 'string' || !pattern.trim())
+    ) {
+      throw new Error(
+        `${owner} scope.senders must be a non-empty array of address patterns`,
+      );
+    }
+    if (scope.recipients !== undefined) {
+      if (scope.recipients.mode !== 'any' && scope.recipients.mode !== 'patterns') {
+        throw new Error(`${owner} scope.recipients.mode must be any or patterns`);
+      }
+      if (
+        scope.recipients.mode === 'patterns'
+        && (
+          !Array.isArray(scope.recipients.patterns)
+          || scope.recipients.patterns.length === 0
+          || scope.recipients.patterns.some(
+            (pattern) => typeof pattern !== 'string' || !pattern.trim(),
+          )
+        )
+      ) {
+        throw new Error(
+          `${owner} scope.recipients.patterns must be a non-empty array when mode is patterns`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Reject retention values that cannot be represented and scheduled reliably.
  */

package/ts/mail/routing/interfaces.ts

@@ -27,6 +27,11 @@ export interface IEmailMatch {
   clientIp?: string | string[];
   /** Require authentication status */
   authenticated?: boolean;
+  /**
+   * Require the session to be authenticated as this exact username (or one
+   * of these usernames). Unauthenticated sessions never match such routes.
+   */
+  authenticatedUser?: string | string[];
   
   // Optional advanced matching
   /** Headers to match */
@@ -43,9 +48,21 @@ export interface IEmailMatch {
  * Action to take when route matches
  */
 export interface IEmailAction {
-  /** Type of action to perform */
+  /**
+   * Type of action to perform.
+   * - `forward`: relay to a configured SMTP host.
+   * - `process`: queue for scanning and outbound MX delivery.
+   * - `deliver`: terminal local delivery through the durable
+   *   `hooks.onAcceptEnvelope` acceptance path. Never relays.
+   * - `store`: terminal local delivery like `deliver`, with explicit
+   *   retention configuration.
+   * - `reject`: refuse with a configurable SMTP error.
+   */
   type: 'forward' | 'deliver' | 'reject' | 'process' | 'store';
-  /** Explicitly permits this route to relay to non-local recipients. */
+  /**
+   * Explicitly permits this route to relay to non-local recipients.
+   * Ignored for `deliver` actions, which are local-only and never relay.
+   */
   allowRelay?: boolean;
   
   /** Forward action configuration */
@@ -124,7 +141,7 @@ export interface IEmailAction {
     }>;
   };
   
-  /** Delivery options (applies to forward/process/deliver) */
+  /** Delivery options (applies to the queue-backed forward/process actions) */
   delivery?: {
     /** Rate limit (messages per minute) */
     rateLimit?: number;
@@ -133,6 +150,59 @@ export interface IEmailAction {
   };
 }
 
+/**
+ * Precomputed SCRAM-SHA-256 verifier for an SMTP auth account. Only derived
+ * key material is stored — the plaintext password never has to be persisted.
+ *
+ * Derivation (RFC 5802): SaltedPassword = PBKDF2-HMAC-SHA256(password, salt,
+ * iterations, 32); StoredKey = SHA256(HMAC-SHA256(SaltedPassword, 'Client Key'));
+ * ServerKey = HMAC-SHA256(SaltedPassword, 'Server Key').
+ */
+export interface ISmtpScramVerifier {
+  algorithm: 'SCRAM-SHA-256';
+  /** Base64-encoded PBKDF2 salt. */
+  salt: string;
+  /** PBKDF2 iteration count (4096 to 1000000, validated at configuration time). */
+  iterations: number;
+  /** Base64-encoded StoredKey. */
+  storedKey: string;
+  /** Base64-encoded ServerKey. */
+  serverKey: string;
+}
+
+/**
+ * Send-authorization scope for an authenticated SMTP account.
+ */
+export interface ISmtpAuthAccountScope {
+  /**
+   * Address patterns ('a@b.com' | '*@b.com') the account may send AS.
+   * Enforced against both the SMTP MAIL FROM envelope sender and the parsed
+   * message header From address.
+   */
+  senders: string[];
+  /** Recipient scope ("send TO who"). Absent or mode 'any' = unrestricted. */
+  recipients?: {
+    mode: 'any' | 'patterns';
+    /** Address patterns enforced for every RCPT TO when mode is 'patterns'. */
+    patterns?: string[];
+  };
+}
+
+/**
+ * Authenticated SMTP account with hashed credentials and send scopes.
+ */
+export interface ISmtpAuthAccount {
+  username: string;
+  /** Disabled accounts always fail authentication (default: enabled). */
+  enabled?: boolean;
+  /**
+   * Hashed SCRAM-SHA-256 verifier (preferred) or legacy plaintext password.
+   */
+  credential: { verifier: ISmtpScramVerifier } | { password: string };
+  /** Absent scope = unrestricted (backwards compatible). */
+  scope?: ISmtpAuthAccountScope;
+}
+
 /**
  * Context for route evaluation
  */