feat(email): carry the tenant on the port, and ship a default provider

[msalvatti]

What

Reaches parity with nest-auth's #88, #95 and #96 — the functional changes it took since the last alignment (#134 here, #74 there).

An audit of the full delta found four functional PRs on that side; two were real gaps here, and two were the other side catching up:

nest-auth	rust-auth before	Action
#95 tenant on every IEmailProvider method	port carried no tenant at all	ported
#96 DefaultAuthEmailProvider	only NoOpEmailProvider	ported
#88 optional tenantId	DTOs required tenantId	ported (the half that applied)
#94 AuthRevocationService	already at parity, and ahead	none
#89 absoluteSessionLifetimeDays = 30	already 30	none

Two of those deserve their reasoning stated, because the headline is misleading:

• #88 on nest-auth was fixing a bug this side never had. password-reset.service.ts resolved the tenant and then went on reading dto.tenantId, so with a resolver configured the reset flow ran under the tenant the caller asked for. This side already rebound the input to the resolved tenant on every flow. What was missing here was the other half: tenantId was required, so a deployment with a TenantIdResolver had to send a value the server discards.
• #94 this side was already ahead. nest-auth published the service to de-duplicate three copies of the same two Redis reads across its guards; this side never had the duplication — verify_access / verify_platform_access consult rv:{jti} and the epoch in one place, and verify_access_token is already public for a host bridging a realtime transport.

Changes

The email port carries the tenant. Every EmailProvider method now takes the account's tenant_id first, so a multi-tenant delivery channel can attribute and route each message rather than guessing from the recipient. A platform admin is cross-tenant and carries no tenant of its own, so MFA notices on that plane arrive under the reserved PLATFORM_EMAIL_TENANT ("platform"), held byte-identical to nest-auth's constant and pinned by a test.

Important

Breaking for a hand-written EmailProvider — and that is the outcome to want here. nest-auth documented that in TypeScript an implementation with fewer parameters stays assignable, so an old provider keeps compiling while passing the recipient where the tenant now goes. Rust refuses to compile it. Nothing is published on crates.io or npm yet, so no released consumer breaks.

DefaultAuthEmailProvider. Sends through AuthEmailSink, a one-method delivery port, so a deployment does not hand-write ten methods to send a verification code. It ships the policy each of those hand-written providers would otherwise have to get right independently:

• HTML escaping on a body path that carries caller-chosen text (an inviter's display name, a tenant's name, the address an account moved to);
• CR/LF stripping on the subject, so that text cannot inject an extra header into a channel that builds them by concatenation;
• the NIST SP 800-63B §4.6 notification catalogue;
• a swallow-and-log delivery-failure policy, so a down channel never turns "enable MFA" into a failed request. DeliveryErrorPolicy::Rethrow restores the error for the two flows that react to one.

The copy is fully replaceable through AuthEmailCatalogue (ten renderers, each with a secure default). The escaping, the subject sanitization and the failure policy are not — a catalogue chooses words, never behaviour.

Both message types redact their bodies in Debug. A rendered body is where the reset token, the verification OTP and the invitation token actually sit in the clear. A sink logging its input at debug — which is what one does while wiring a new adapter — would otherwise put every one of them into a log pipeline. OutgoingEmail and AuthEmailMessage redact both bodies and mask the recipient, with a test.

tenantId is optional wherever a TenantIdResolver can supply it. A configured resolver already ignores the body's value, so a client under one may now omit the field entirely. With no resolver the body is the only thing that can scope the request, and one naming no tenant is refused with auth.validation naming the field rather than defaulted: inventing a tenant name would silently gather into one scope every account a misconfigured deployment created, and that scope keys the user lookup, the Redis records and the HMAC identifiers built from it.

The reset helpers take the resolved tenant as an argument instead of reading it back off the input struct. With both values in scope, reading the wrong one is a one-character mistake no test would notice — and it is exactly the mistake nest-auth had to fix on this same flow. Not carrying the unresolved value is what makes it unwritable rather than merely unlikely.

Verification

Gate	Result
cargo fmt --all --check	pass
cargo clippy --workspace --all-targets --all-features -- -D warnings	pass
Full suite, including the Docker-backed Redis e2e tier	pass
llvm-cov lines	100.00% (0 missed of 27 101)
llvm-cov functions	100.00% (0 missed of 3 044)
llvm-cov regions	96.57% repo-wide; default_email.rs, email.rs and dto.rs are at 100%
ts-rs export drift	none
cargo mutants --in-diff	78 mutants → 59 caught, 15 unviable, 0 survivors

Two coverage misses appeared on the first run — both the repo's known multi-line else { return; } trap, and both caused by these edits pushing rustfmt to wrap those lines. Rewritten to the single-line-else idiom.

Of the four initial mutation survivors: two were dead code (a "defensive" tenant_id: None nobody read) and were deleted rather than excluded in mutants.toml; two were real, pre-existing test gaps — nothing asserted the NIST §4.6 "your password changed" notice was ever sent — and are now covered, each confirmed by a red-check.

PLATFORM_EMAIL_TENANT is deliberately not added to conformance/wire-contract.json: that file is byte-identical between the two repos and nest-auth did not add it. It is pinned by a unit test instead, and adding it to both is a follow-up for the nest-auth side.

[Copilot]

Pull request overview

Adds tenant-aware email delivery, a secure default email provider, and optional tenant inputs when a resolver is configured.

Changes:

• Passes resolved tenant IDs through all email operations.
• Adds configurable email rendering, sanitization, redaction, and error handling.
• Makes tenant inputs optional and refactors reset flows around resolved tenants.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
README.md	Documents email and tenant APIs.
docs/technical_specification.md	Updates behavioral specification.
crates/bymax-auth-redis/tests/redis_stores.rs	Adapts Redis tests to optional tenants.
crates/bymax-auth-redis/tests/mfa_lifecycle_e2e.rs	Updates MFA E2E inputs.
crates/bymax-auth-core/tests/engine_assembly.rs	Updates assembly tests.
crates/bymax-auth-core/src/traits/mod.rs	Exports new email APIs.
crates/bymax-auth-core/src/traits/email.rs	Adds tenant-aware email methods.
crates/bymax-auth-core/src/traits/default_email.rs	Implements the default email provider.
crates/bymax-auth-core/src/services/platform.rs	Updates platform tests.
crates/bymax-auth-core/src/services/oauth.rs	Accepts optional tenant input.
crates/bymax-auth-core/src/services/mfa/tests.rs	Tests tenant-attributed MFA notices.
crates/bymax-auth-core/src/services/mfa/setup.rs	Forwards tenant on MFA enablement.
crates/bymax-auth-core/src/services/mfa/mod.rs	Resolves MFA email attribution.
crates/bymax-auth-core/src/services/mfa/manage.rs	Forwards tenant on MFA disablement.
crates/bymax-auth-core/src/services/auth/session_ops.rs	Updates optional-tenant fixtures.
crates/bymax-auth-core/src/services/auth/register.rs	Resolves optional registration tenants.
crates/bymax-auth-core/src/services/auth/password_reset.rs	Refactors reset tenant handling.
crates/bymax-auth-core/src/services/auth/mod.rs	Implements optional tenant resolution.
crates/bymax-auth-core/src/services/auth/login.rs	Resolves optional login tenants.
crates/bymax-auth-core/src/services/auth/invitation.rs	Attributes invitations to tenants.
crates/bymax-auth-core/src/services/auth/email_verification.rs	Supports resolver-supplied tenants.
crates/bymax-auth-core/src/services/auth/email_change.rs	Attributes email-change messages.
crates/bymax-auth-core/src/services/auth/detached.rs	Forwards tenants through email tasks.
crates/bymax-auth-core/src/services/adapter_api.rs	Updates adapter tests.
crates/bymax-auth-axum/src/validation.rs	Tests optional OAuth tenants.
crates/bymax-auth-axum/src/routes/oauth.rs	Forwards optional OAuth tenants.
crates/bymax-auth-axum/src/routes/auth.rs	Forwards optional verification tenants.
crates/bymax-auth-axum/src/dto.rs	Makes resolver-compatible tenant fields optional.
CHANGELOG.md	Records new and breaking behavior.
.cargo/mutants.toml	Expands equivalent-mutant exclusions.

Suppressed comments (1)

crates/bymax-auth-axum/src/dto.rs:210

• The existing resend_otp handler discards every engine error, including the new missing-tenant AuthError::Validation. Thus omitting this now-optional field without a resolver returns a successful 200 but cannot send an OTP, despite the documented refusal. Surface validation failures while retaining the uniform anti-enumeration response for account-dependent outcomes.

    pub tenant_id: Option<String>,

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

crates/bymax-auth-axum/src/dto.rs:52

• The server now accepts an omitted tenantId, but both shipped clients still make it mandatory (crates/bymax-auth-client/src/lib.rs:109,120,146,304 and packages/rust-auth/src/client/index.ts:269,281,289,323). The React wrapper also substitutes "default" at packages/rust-auth/src/react/index.ts:186,210, so it keeps inventing a tenant instead of allowing resolver-backed omission. Update the client request types/serialization and remove that fallback so this new contract is usable through the first-party clients.

    /// The tenant scope. Optional: a deployment that configures a `TenantIdResolver`
    /// ignores this value, so a client there may omit it. With no resolver configured it is
    /// the only thing that can scope the request, and omitting it is refused rather than
    /// defaulted (`auth.validation`) — see `AuthEngine::resolve_tenant`.

README.md:240

• The preceding sentence says the library passes structured data and “never rendered HTML,” but this newly documented default path renders the message and passes html/text to AuthEmailSink. Qualify the statement by port so readers do not implement the sink expecting tokens/OTPs as structured fields.

**Most deployments should not write this trait by hand.** `DefaultAuthEmailProvider` already implements all ten methods over a one-method delivery port, with the escaping, header sanitization and failure policy described below:

docs/technical_specification.md:3714

• This new built-in rendering section leaves the specification internally contradictory: §10's introduction (lines 3535–3540) still says rendering and copy are entirely adapter-owned, while §22.2 (lines 6942–6943) says the library ships only NoOp/recording implementations and that rendered HTML is out of scope. Update those sections to distinguish EmailProvider's structured event port from DefaultAuthEmailProvider/AuthEmailSink.