@push.rocks/smartmta 9.5.0 → 9.6.0

package/changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2026-09-15 - 9.6.0
+
+### Fixes
+
+- release construction-owned timers when the constructor rejects configuration (lifecycle)
+  - `UnifiedEmailServer` constructs `BounceManager` and `UnifiedRateLimiter`, whose constructors arm cleanup intervals, before later steps can still reject the configuration by throwing; a throwing constructor returns no instance, so `stop()` could never release them and the process could not exit. Construction now releases those two owners on failure and rethrows the original error.
+  - Clear the self-MX loop test's inject timer on every path and assert that a rejected construction leaves the active timer count unchanged.
+
+### Features
+
+- add `hooks.onAuthenticate` for embedder-owned dynamic SMTP credentials (auth-hook)
+  - Consult the hook for `PLAIN`/`LOGIN` attempts whose username neither `auth.accounts` nor `auth.users` declares, so an application can own credentials no static list can express (per-tenant bindings, remote authorities, opaque hashes such as argon2id). Configured usernames are never handed to the hook and cannot be overridden or weakened by it.
+  - Enforce a hook-returned `scope` identically to a configured account scope, at both the `RCPT TO` envelope check and the `DATA` header-`From` alignment check, for the lifetime of the authenticating session.
+  - Bind grants to the SMTP session that authenticated so no session inherits another's scope; bound the grant table by a hard cap with oldest-first eviction plus a TTL, and refuse a session whose grant is gone with a temporary `451` and the new `onRecipientRejected` reason `auth-scope-expired` rather than treating it as unrestricted.
+  - Count a configured hook in `isAuthConfigured`, so a server whose credentials are entirely dynamic advertises `AUTH` with an empty account list and keeps the existing listener-restart behaviour when the hook is added or removed.
+  - Fail closed on a throw, a `smtp.authenticationTimeoutMs` timeout (new, default 4000 ms) or a non-object return; report SCRAM credential lookups for hook-owned usernames as not-found, since an opaque verifier cannot produce SCRAM fields.
+  - Match configuration's ownership of a username case-insensitively while leaving credential verification exact, so a casing variant cannot route around a configured — or deliberately disabled — account by reaching the hook instead.
+  - Clamp `smtp.authenticationTimeoutMs` to 4500 ms with a warning, since the SMTP listener abandons the AUTH round trip after a fixed 5000 ms and a larger value could never take effect.
+  - Record a rejection `message` in the server log rather than sending it to the client: every failed authentication answers with the listener's standard `535`, so the field cannot be used to probe which usernames exist.
+  - Refuse a missing grant independently at both the `RCPT TO` and `DATA` enforcement points, so neither depends on the other having run first.
+  - Add the `dynamicSmtpAuthenticationHook` capability probe, `ISmtpAuthenticateContext` and `ISmtpAuthenticateDecision` exports, readme documentation, and 21 regression tests.
+  - Known capacity edge: above 4096 concurrent hook-authenticated sessions, oldest-first eviction reaches live grants, and an affected client must reconnect and authenticate again rather than recovering in place. The durable fix is a listener session-close event, which the Rust connection layer does not currently emit.
+
+### Maintenance
+
+- Update pnpm to 12.4.0, tstest to 6.0.0, tsrust to 1.13.0, tsbuild to 4.4.3, the gitzone CLI to 6.13.2 and Node typings to 26.5.0 for the release; deny the transitive dees-catalog build script.
+
 ## 2026-07-31 - 9.5.0
 
 ### Features

package/dist_rust/mailer-bin_linux_amd64.tsrust-build.json

@@ -0,0 +1,14 @@
+{
+  "format": "tsrust.build-provenance.v2",
+  "binarySha256": "74d10e10644850c92fa7061cbabb4dc9583ef40e8c0cc2bb0024dcbdb8d80470",
+  "buildInfo": {
+    "projectName": "@push.rocks/smartmta",
+    "projectVersion": "9.6.0",
+    "gitCommit": "eac7a76f2d7e0a49006977a34ff678b638700a1f",
+    "gitDirty": false,
+    "builtAt": "2026-09-15T17:08:14.540Z",
+    "tsrustVersion": "1.13.0",
+    "binary": "mailer-bin",
+    "target": "linux_amd64"
+  }
+}

package/dist_rust/mailer-bin_linux_arm64.tsrust-build.json

@@ -0,0 +1,14 @@
+{
+  "format": "tsrust.build-provenance.v2",
+  "binarySha256": "e9372baaab19974f2ab8b353124c88330a99af54c8bc0d17a66359bee6823615",
+  "buildInfo": {
+    "projectName": "@push.rocks/smartmta",
+    "projectVersion": "9.6.0",
+    "gitCommit": "eac7a76f2d7e0a49006977a34ff678b638700a1f",
+    "gitDirty": false,
+    "builtAt": "2026-09-15T17:08:15.103Z",
+    "tsrustVersion": "1.13.0",
+    "binary": "mailer-bin",
+    "target": "linux_arm64"
+  }
+}

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartmta',
-    version: '9.5.0',
+    version: '9.6.0',
     description: 'A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHlIQUF5SDtDQUN2SSxDQUFBIn0=

package/dist_ts/index.d.ts

@@ -16,4 +16,5 @@ export declare const smartMtaCapabilities: Readonly<{
     readonly terminalLocalDeliverActions: true;
     readonly smtpAuthAccountsAndScopes: true;
     readonly durableRawOutboundQueue: true;
+    readonly dynamicSmtpAuthenticationHook: true;
 }>;

package/dist_ts/index.js

@@ -16,5 +16,6 @@ export const smartMtaCapabilities = Object.freeze({
     terminalLocalDeliverActions: true,
     smtpAuthAccountsAndScopes: true,
     durableRawOutboundQueue: true,
+    dynamicSmtpAuthenticationHook: true,
 });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVqRCxNQUFNLENBQUMsTUFBTSxvQkFBb0IsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ2hELDBCQUEwQixFQUFFLElBQUk7SUFDaEMscUJBQXFCLEVBQUUsSUFBSTtJQUMzQiwwQkFBMEIsRUFBRSxJQUFJO0lBQ2hDLHFCQUFxQixFQUFFLElBQUk7SUFDM0Isb0JBQW9CLEVBQUUsSUFBSTtJQUMxQixpQkFBaUIsRUFBRSxJQUFJO0lBQ3ZCLG1CQUFtQixFQUFFLElBQUk7SUFDekIsbUJBQW1CLEVBQUUsSUFBSTtJQUN6Qiw0QkFBNEIsRUFBRSxJQUFJO0lBQ2xDLDZCQUE2QixFQUFFLElBQUk7SUFDbkMsMkJBQTJCLEVBQUUsSUFBSTtJQUNqQyx5QkFBeUIsRUFBRSxJQUFJO0lBQy9CLHVCQUF1QixFQUFFLElBQUk7Q0FDckIsQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVqRCxNQUFNLENBQUMsTUFBTSxvQkFBb0IsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ2hELDBCQUEwQixFQUFFLElBQUk7SUFDaEMscUJBQXFCLEVBQUUsSUFBSTtJQUMzQiwwQkFBMEIsRUFBRSxJQUFJO0lBQ2hDLHFCQUFxQixFQUFFLElBQUk7SUFDM0Isb0JBQW9CLEVBQUUsSUFBSTtJQUMxQixpQkFBaUIsRUFBRSxJQUFJO0lBQ3ZCLG1CQUFtQixFQUFFLElBQUk7SUFDekIsbUJBQW1CLEVBQUUsSUFBSTtJQUN6Qiw0QkFBNEIsRUFBRSxJQUFJO0lBQ2xDLDZCQUE2QixFQUFFLElBQUk7SUFDbkMsMkJBQTJCLEVBQUUsSUFBSTtJQUNqQyx5QkFBeUIsRUFBRSxJQUFJO0lBQy9CLHVCQUF1QixFQUFFLElBQUk7SUFDN0IsNkJBQTZCLEVBQUUsSUFBSTtDQUMzQixDQUFDLENBQUMifQ==

package/dist_ts/mail/routing/classes.unified.email.server.d.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'events';
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
 import type { IStorageManager } from '../interfaces.storage.js';
 import type { IInboundEmailSecurityResult } from '../../security/classes.rustsecuritybridge.js';
-import type { IEmailRoute, IEmailAction, IEmailDomainConfig, ISmtpAuthAccount } from './interfaces.js';
+import type { IEmailRoute, IEmailAction, IEmailDomainConfig, ISmtpAuthAccount, ISmtpAuthenticateContext, ISmtpAuthenticateDecision } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
 import { DomainRegistry } from './classes.domain.registry.js';
 import { BounceType, BounceCategory } from '../core/classes.bouncemanager.js';
@@ -20,7 +20,7 @@ interface DcRouter {
     options?: any;
 }
 export type TRecipientRouteSource = 'explicit-route' | 'domain-policy' | 'no-route';
-export type TRecipientRejectionReason = 'explicit-route' | 'domain-policy' | 'no-route' | 'domain-not-hosted' | 'relay-denied' | 'recipient-hook' | 'policy-error' | 'sender-scope' | 'recipient-scope' | 'account-disabled';
+export type TRecipientRejectionReason = 'explicit-route' | 'domain-policy' | 'no-route' | 'domain-not-hosted' | 'relay-denied' | 'recipient-hook' | 'policy-error' | 'sender-scope' | 'recipient-scope' | 'account-disabled' | 'auth-scope-expired';
 export interface IResolvedRecipientRoute {
     recipient: string;
     localDomain: string | null;
@@ -254,6 +254,8 @@ export interface IUnifiedEmailServerOptions {
         tlsTerminatedPorts?: number[];
         /** Timeout for RCPT policy callbacks. Defaults to 5000 ms. */
         recipientValidationTimeoutMs?: number;
+        /** Timeout for `hooks.onAuthenticate` callbacks. Defaults to 5000 ms. */
+        authenticationTimeoutMs?: number;
         /** Timeout for message acceptance callbacks. Defaults to 30000 ms. */
         messageAcceptanceTimeoutMs?: number;
         /** Maximum complete messages concurrently held across Rust and TypeScript. */
@@ -265,6 +267,24 @@ export interface IUnifiedEmailServerOptions {
         };
     };
     hooks?: {
+        /**
+         * Async credential verification for PLAIN/LOGIN, letting an embedding
+         * application own dynamic SMTP credentials that no static configuration
+         * can express.
+         *
+         * Consulted only for usernames that `auth.accounts` and `auth.users` do
+         * not declare: configuration always owns the usernames it lists, so a
+         * hook can never override or weaken a configured credential. Configuring
+         * the hook enables SMTP AUTH on the listener even with no accounts.
+         *
+         * The returned `scope` is enforced for that session exactly as a
+         * configured account's scope is. A throw or a
+         * `smtp.authenticationTimeoutMs` timeout fails the attempt closed.
+         *
+         * SCRAM cannot be served from this hook — see `onAuthenticate` notes in
+         * the readme. Hook-owned usernames authenticate over PLAIN/LOGIN only.
+         */
+        onAuthenticate?: (context: ISmtpAuthenticateContext) => Promise<ISmtpAuthenticateDecision>;
         /** Async recipient policy hook that may further restrict an accepted built-in decision. */
         onRcptTo?: (context: IRcptToPolicyContext) => Promise<ISmtpDecision>;
         /** Async message acceptance hook for envelopes with no resolved `store` or `deliver` action. */
@@ -385,7 +405,40 @@ export declare class UnifiedEmailServer extends EventEmitter {
     private verifierDerivationWaiters;
     /** Compiled scope patterns; keys are config-supplied, bounded by config size. */
     private scopePatternCache;
+    /**
+     * Scopes granted by `hooks.onAuthenticate`, keyed by the session the
+     * credential authenticated. The SMTP listener reports no session-close
+     * event, so entries are bounded by both a TTL and a hard cap rather than
+     * by session lifetime.
+     *
+     * Losing an entry must never widen a session, so the absence of a grant is
+     * not read as "unrestricted": a session authenticated as a username that
+     * configuration does not declare can only have come from the hook, and is
+     * refused with a temporary failure until it authenticates again.
+     */
+    private hookAuthenticatedSessions;
+    private static readonly hookAuthSessionTtlMs;
+    private static readonly hookAuthSessionMax;
+    private static readonly hookAuthSweepInterval;
+    private hookAuthSweepCountdown;
+    /** The Rust listener's fixed AUTH round-trip deadline. */
+    private static readonly listenerAuthDeadlineMs;
+    /** Leave headroom so a hook answering just in time still beats the listener. */
+    private static readonly authHookMaxTimeoutMs;
+    private static readonly authHookDefaultTimeoutMs;
+    private loggedAuthTimeoutClamp;
     constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions);
+    /**
+     * Hand back every event-loop resource a partially completed construction has
+     * already taken ownership of, so a rejected configuration leaves the process
+     * exactly as it found it.
+     *
+     * Only construction-time owners belong here: the delivery queue and the
+     * delivery system arm their timers in `initialize()` and `start()`, which a
+     * failed construction never reaches, and the Rust bridge is an unstarted
+     * singleton until `start()` spawns it.
+     */
+    private releaseConstructionOwnedResources;
     private assertAcceptingOutboundWork;
     private trackOutboundWork;
     onRecipientRejected(listener: (event: IRecipientRejectedEvent) => Promise<void> | void): this;
@@ -470,7 +523,11 @@ export declare class UnifiedEmailServer extends EventEmitter {
      * rather than degrading silently.
      */
     private resolveTlsTerminatedPorts;
-    /** Whether the current options require SMTP AUTH support on the listener. */
+    /**
+     * Whether the current options require SMTP AUTH support on the listener.
+     * A configured `hooks.onAuthenticate` counts on its own: its whole purpose
+     * is to own credentials that no static account list contains.
+     */
     private isAuthConfigured;
     /**
      * Whether the Rust SMTP listener is currently accepting connections.
@@ -524,6 +581,47 @@ export declare class UnifiedEmailServer extends EventEmitter {
     private getAddressDomain;
     /** Resolve the configured account for a username. Accounts win over legacy users. */
     private findAuthAccount;
+    /** Whether the legacy `auth.users` array declares this username. */
+    private hasLegacyAuthUser;
+    /**
+     * Whether configuration claims this username, for the purpose of deciding
+     * that `hooks.onAuthenticate` must not see it.
+     *
+     * Deliberately case-insensitive, while credential verification itself stays
+     * exact. Otherwise `Tenant-A` would slip past an operator's configured
+     * `tenant-a` — including a `tenant-a` the operator had set `enabled: false`
+     * — and reach a hook that may well resolve names case-insensitively.
+     * Configuration owning a name means owning every casing of it: a casing that
+     * matches no exact credential simply fails, and never reaches the hook.
+     */
+    private declaresUsername;
+    /**
+     * Hook timeout, clamped below the Rust listener's own AUTH deadline.
+     *
+     * The listener waits a fixed 5 s for the TypeScript answer
+     * (`rust/crates/mailer-smtp/src/connection.rs`), so a larger value here
+     * could never take effect: the listener would already have failed the
+     * attempt and reset the session while the hook was still running. Clamping
+     * keeps the configured number meaningful instead of silently unreachable.
+     */
+    private getAuthenticationTimeoutMs;
+    /**
+     * Enforce the hard cap oldest-first, and sweep expired grants periodically.
+     *
+     * The cap is what bounds memory, and it is O(1) amortised because Map
+     * preserves insertion order. The TTL sweep is hygiene on top — expiry is
+     * always enforced on read — so it runs every `hookAuthSweepInterval`
+     * insertions rather than walking the whole table on every authentication.
+     */
+    private pruneHookAuthSessions;
+    /** Record the scope a hook granted, replacing any earlier grant for the session. */
+    private rememberHookAuthGrant;
+    /**
+     * Live hook grant for a session, or undefined when none is held. The
+     * username must match the grant: a session may not present one username to
+     * the listener and inherit another's scope.
+     */
+    private findHookAuthGrant;
     private normalizeScopeAddress;
     /**
      * Glob match ('a@b.com' | '*@b.com') against a normalized address, using
@@ -535,9 +633,35 @@ export declare class UnifiedEmailServer extends EventEmitter {
     /**
      * Envelope-level scope decision for an authenticated session. Returns null
      * when the envelope is permitted (unauthenticated sessions, usernames with
-     * no configured account, and accounts without a scope are unrestricted).
+     * no configured account and no `hooks.onAuthenticate`, and accounts without
+     * a scope are unrestricted).
      */
     private resolveAuthAccountScopeDecision;
+    /**
+     * Envelope-level scope decision for a session authenticated by
+     * `hooks.onAuthenticate`. Reached only for usernames no configured account
+     * declares, so when a hook is configured the session must hold a live
+     * grant; a missing grant is refused temporarily rather than treated as
+     * unrestricted. With no hook configured the pre-existing behaviour stands:
+     * legacy users and unknown usernames are unscoped.
+     */
+    private resolveHookAuthScopeDecision;
+    /** Temporary refusal for a session whose hook grant is not available. */
+    private static authScopeUnavailableDecision;
+    /**
+     * Shared sender/recipient scope enforcement. An absent scope is
+     * unrestricted, matching `ISmtpAuthAccount.scope`.
+     */
+    private applyScopeToEnvelope;
+    /**
+     * Sender scope in force for a session.
+     *
+     * The three outcomes are kept distinct on purpose. Collapsing `refused` into
+     * "no scope" would make a session whose hook grant is gone look unrestricted
+     * to any caller that only asks "is there a scope?", which is the opposite of
+     * what a missing grant means.
+     */
+    private resolveSessionSenderScope;
     /**
      * Extract every mailbox address from the parsed From header. The Email
      * abstraction keeps only the first From mailbox, which is not sufficient
@@ -622,10 +746,22 @@ export declare class UnifiedEmailServer extends EventEmitter {
      * always fail.
      */
     private handleRustAuthRequest;
+    /**
+     * Run `hooks.onAuthenticate` under the configured timeout. Any throw, any
+     * timeout and any non-object result fail the attempt closed — an embedder
+     * that cannot answer must never widen access.
+     */
+    private runHookAuthentication;
     /**
      * Handle a SCRAM credential request from the Rust SMTP server.
      * Verifier accounts return their stored fields directly; plaintext
      * credentials (accounts or legacy users) derive fields on the fly.
+     *
+     * Usernames owned by `hooks.onAuthenticate` fall through to `found: false`:
+     * SCRAM requires the server to hold the salt, iteration count, stored key
+     * and server key, and a hook that verifies an opaque credential (argon2id,
+     * a remote authority) cannot produce them. Those usernames authenticate
+     * over PLAIN/LOGIN only, which is why the hook receives the password.
      */
     private handleScramCredentialRequest;
     /**