@push.rocks/smartmta 9.5.0 → 9.6.0

package/dist_ts/mail/routing/interfaces.d.ts

@@ -195,6 +195,47 @@ export interface ISmtpAuthAccount {
     /** Absent scope = unrestricted (backwards compatible). */
     scope?: ISmtpAuthAccountScope;
 }
+/**
+ * Context handed to `hooks.onAuthenticate` for a PLAIN/LOGIN attempt whose
+ * username is not declared in `auth.accounts` or `auth.users`.
+ */
+export interface ISmtpAuthenticateContext {
+    /** Username exactly as supplied by the client. */
+    username: string;
+    /** Password exactly as supplied by the client. */
+    password: string;
+    /** SMTP session the attempt belongs to. */
+    sessionId: string;
+    /** Remote peer address of the SMTP connection. */
+    remoteAddress: string;
+    /** Aborted when the hook exceeds `smtp.authenticationTimeoutMs`. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result of an `hooks.onAuthenticate` credential verification.
+ */
+export interface ISmtpAuthenticateDecision {
+    /** Whether the supplied credential is valid. */
+    accepted: boolean;
+    /**
+     * Reason for a rejection, recorded in the server log.
+     *
+     * It is deliberately NOT sent to the client: the SMTP listener answers every
+     * failed authentication with the same `535 5.7.8 Authentication credentials
+     * invalid`, so a caller cannot probe which usernames exist. Use this to make
+     * an operator's log say why a binding was refused.
+     */
+    message?: string;
+    /**
+     * Send-authorization scope for the resulting session, enforced identically
+     * to a configured account's scope for the lifetime of that session.
+     *
+     * Absent scope = unrestricted, matching `ISmtpAuthAccount.scope`. A hook
+     * that authenticates tenants MUST return a scope; without one the session
+     * may send as any sender to any recipient.
+     */
+    scope?: ISmtpAuthAccountScope;
+}
 /**
  * Context for route evaluation
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "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.",
   "keywords": [
     "mta",
@@ -31,12 +31,12 @@
     ".": "./dist_ts/index.js"
   },
   "devDependencies": {
-    "@git.zone/cli": "^3.0.1",
-    "@git.zone/tsbuild": "4.4.2",
-    "@git.zone/tsrust": "^1.7.0",
-    "@git.zone/tstest": "^3.6.7",
+    "@git.zone/cli": "^6.13.2",
+    "@git.zone/tsbuild": "4.4.3",
+    "@git.zone/tsrust": "^1.13.0",
+    "@git.zone/tstest": "^6.0.0",
     "@types/mailparser": "^3.4.6",
-    "@types/node": "^26.1.1",
+    "@types/node": "26.5.0",
     "tsx": "^4.23.1"
   },
   "dependencies": {

package/readme.md

@@ -171,6 +171,11 @@ const emailServer = new UnifiedEmailServer(dcRouterRef, {
     securePort: 465,
     recipientValidationTimeoutMs: 5000,
 
+    // Timeout for hooks.onAuthenticate before failing the attempt closed.
+    // Defaults to 4000. The SMTP listener abandons the AUTH round trip after a
+    // fixed 5000 ms, so larger values are clamped to 4500 with a warning.
+    authenticationTimeoutMs: 4000,
+
     // Timeout for hooks.onMessageData and hooks.onAcceptEnvelope before
     // returning a temporary SMTP failure.
     messageAcceptanceTimeoutMs: 30000,
@@ -183,6 +188,20 @@ const emailServer = new UnifiedEmailServer(dcRouterRef, {
   },
 
   hooks: {
+    async onAuthenticate(context) {
+      // Only reached for usernames auth.accounts and auth.users do not declare.
+      // Verify the credential however the application stores it, and return the
+      // send scope the resulting session must be held to.
+      const binding = await credentialStore.verify(context.username, context.password);
+      if (!binding) {
+        // message is logged server-side; the client always sees a plain 535.
+        return { accepted: false, message: 'Unknown binding' };
+      }
+      return {
+        accepted: true,
+        scope: { senders: [`*@${binding.domain}`] },
+      };
+    },
     async onRcptTo(context) {
       if (context.abortSignal?.aborted) {
         return { accepted: false, smtpCode: 451, smtpMessage: 'Recipient policy timeout' };
@@ -330,6 +349,8 @@ A submission route grants an authenticated client permission to relay. It does n
 
 Without this, an authenticated submission addressed to a domain this server hosts is accepted with `250`, relayed to that domain's MX, and destroyed by the self-MX loop guard. Everything else keeps today's behaviour: recipient-scoped `process` routes still win (consumers use them for local addresses handled by their own acceptance pipeline), `store`/`deliver`/`forward`/`reject` actions always win, and a domain registered for outbound identity only — no `inboundPolicy`, or the send-only `defaultAction: 'reject'` — keeps relaying because its real MX lives elsewhere. Encoding recipient intent in `match.headers` is not recognised for this purpose.
 
+`hooks.onAuthenticate` lets the embedding application own SMTP credentials that no static configuration can express — a per-tenant binding store, a remote authority, an opaque hash such as argon2id. See [Dynamic credentials](#dynamic-credentials-hooksonauthenticate).
+
 `hooks.onRcptTo`, `hooks.onMessageData`, and `hooks.onAcceptEnvelope` are awaited asynchronously. If a hook throws or times out, SmartMTA returns a temporary SMTP failure. The hook context includes `abortSignal`; long-running consumers should observe it and stop work promptly. A custom `onRcptTo` hook may accept local recipients using application-specific lookup, but external relay is still blocked unless a matched route explicitly sets `allowRelay: true`.
 
 `hooks.onMessageData` runs after `DATA` and before the final SMTP response — but only for envelopes with **no** resolved `store` or `deliver` action; terminal local deliveries go through `hooks.onAcceptEnvelope` instead and never invoke `onMessageData`. Return `{ accepted: true }` only after your application has accepted responsibility for the message, such as after durable persistence. Set `continueProcessing: false` when the consumer owns all downstream processing.
@@ -413,7 +434,7 @@ Enforcement semantics:
 - **Recipient scope ("send TO who")** — with `recipients.mode: 'patterns'`, every `RCPT TO` matching no pattern is refused with `550`. `mode: 'any'` or an absent `recipients` block leaves recipients unrestricted.
 - **Patterns** are exact addresses (`a@b.com`) or glob patterns (`*@b.com`), matched case-insensitively with identical semantics to route matching. A scoped account sending with an empty `MAIL FROM <>` (null sender) is refused unless a pattern explicitly matches — `senders: ['*']` is the documented escape hatch.
 - **Route binding** — a route with `match.authenticatedUser: 'newsletter-service'` (or an array of usernames) matches only sessions authenticated as that account (exact, case-sensitive username comparison), so dedicated processing or relay routes can be attached per account. Unauthenticated sessions never match such routes.
-- **Rejections** surface through `onRecipientRejected` with the reasons `sender-scope`, `recipient-scope`, and `account-disabled`.
+- **Rejections** surface through `onRecipientRejected` with the reasons `sender-scope`, `recipient-scope`, `account-disabled`, and `auth-scope-expired`.
 - **Live enablement** — when a configuration update transitions between zero and one-or-more accounts/users, `updateOptions` restarts only the Rust SMTP listener so the `AUTH` capability appears or disappears without a process restart. A failed listener restart logs loudly, emits `smtpListenerRestartFailed`, and leaves `isSmtpListenerActive()` false — surface that next to `getBridgeState()` in health endpoints.
 - An account without a `scope` is authenticated but unrestricted — identical to legacy `auth.users` behavior, which itself is unchanged.
 
@@ -423,6 +444,28 @@ Deriving verifiers: `deriveScramVerifier(password, iterations?)` is the canonica
 
 Compatibility probe: `smartMtaCapabilities.smtpAuthAccountsAndScopes`.
 
+### Dynamic credentials (`hooks.onAuthenticate`)
+
+`auth.accounts` is a static list. An embedding application that mints SMTP credentials at runtime — one per tenant, per service, per binding — cannot express them that way, and cannot store them as SCRAM verifiers if its credential store is an opaque hash such as argon2id. `hooks.onAuthenticate` hands those attempts to the application instead:
+
+```ts
+hooks: {
+  async onAuthenticate({ username, password, sessionId, remoteAddress, abortSignal }) {
+    const binding = await credentialStore.verify(username, password, { signal: abortSignal });
+    if (!binding) return { accepted: false, message: 'Unknown binding' };
+    return { accepted: true, scope: { senders: [`*@${binding.domain}`] } };
+  },
+}
+```
+
+- **Configuration always wins.** The hook is consulted only for usernames that neither `auth.accounts` nor `auth.users` declares. A hook can never override, weaken or second-guess a credential an operator configured — a configured username that fails its password fails, full stop. Ownership is matched **case-insensitively** while credential verification itself stays exact, so `Tenant-A` cannot slip past a configured (or deliberately `enabled: false`) `tenant-a` by changing case: it matches no exact credential, and it never reaches the hook either.
+- **A configured hook enables `AUTH` on its own.** `isAuthConfigured` counts it alongside `auth.required`, `auth.users` and `auth.accounts`, so a server whose credentials are entirely dynamic still advertises `AUTH` with an empty account list. The same listener-restart behaviour applies when the hook is added or removed through `updateOptions`.
+- **The returned `scope` is enforced identically to an account scope** — both the `RCPT TO` envelope check and the `DATA` header-`From` alignment check — for the lifetime of the session that authenticated. An absent `scope` is unrestricted, matching `ISmtpAuthAccount.scope`; **a hook that authenticates tenants must return one.**
+- **Grants are session-bound.** They are keyed by the SMTP session that authenticated, so one session cannot inherit another's scope, and they are bounded by a hard cap of 4096 (oldest-first eviction) and a one-hour TTL. Because the listener reports no session-close event, a session may outlive its grant: that case is refused with a temporary `451` and `onRecipientRejected` reason `auth-scope-expired`, never silently treated as unrestricted. Both enforcement points refuse independently, so neither relies on the other having run first. Note the capacity edge: above 4096 concurrent hook-authenticated sessions, eviction reaches live grants, and an affected client must reconnect and authenticate again rather than being able to recover in place.
+- **Failure is closed.** A throw, a `smtp.authenticationTimeoutMs` timeout, or a non-object return rejects the attempt. The client always receives the listener's standard `535 5.7.8 Authentication credentials invalid`; a `message` on the decision is recorded in the server log, never sent to the client, so a caller cannot use it to probe which usernames exist.
+- **`PLAIN`/`LOGIN` only.** SCRAM requires the server to hold the salt, iteration count, stored key and server key; a hook that verifies an opaque credential cannot produce them. SCRAM credential lookups for hook-owned usernames report not-found, which is why the hook receives the password directly. Offer SCRAM only for usernames configured as `auth.accounts` verifiers.
+- The hook sits on the SMTP auth path: keep it fast, and keep expensive derivation bounded. `abortSignal` fires on timeout — observe it.
+
 ### 📧 Sending Emails (Automatic MX Discovery)
 
 The recommended way to send email is `sendEmail()`. It defaults to **MTA mode**, which automatically resolves MX records for each recipient domain via DNS — you don't need to know the destination mail server:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 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.'
 }

package/ts/index.ts

@@ -17,4 +17,5 @@ export const smartMtaCapabilities = Object.freeze({
   terminalLocalDeliverActions: true,
   smtpAuthAccountsAndScopes: true,
   durableRawOutboundQueue: true,
+  dynamicSmtpAuthenticationHook: true,
 } as const);