MFA & notifications

Summarized from IDENTITY-MFA-NOTIFICATIONS-AND-BRANDING.md. Canonical auth spec — phases P1–P4 done, P5 partial, P6 done (MVP).

Locked decisions

Topic	Decision
Email verification	Required at signup (all human accounts)
MFA enrollment	TOTP (authenticator app) required after grace period
MFA at login	User may complete challenge via TOTP, SMS OTP, or email OTP (configurable preference)
MFA grace period	7 days after signup before MFA is mandatory
Remember device	Allowed (~30 days), then full MFA again
TE platform billing brand	TenancyEngine (billing.tenancyengine.com, @tenancyengine.com email)
TenaBill-only merchants	TenaBill default brand; org may configure custom domain
SendGrid	Subaccount per TenaBill merchant; send from merchant subdomain by default
Human auth UI	account.tenancyengine.com (and env variants)
OIDC issuer (machine)	auth.saasruntime.com — unchanged in SDKs and APIs
Dev notifications	Mailpit SMTP; dev SMS via API log lines

Domain map (human-facing)

Surface	Production host	Audience
TE marketing	tenancyengine.com	Public
TE console	console.tenancyengine.com	ISV / platform operators
Account / MFA / security	account.tenancyengine.com	All OIDC users
TE billing portal	billing.tenancyengine.com	ISVs paying for TE
TenaBill merchant console	console.tenabill.com	TenaBill merchants
TenaBill customer portal	portal.tenabill.com or merchant CNAME	End customers

Signup & MFA flows

Signup methods

• Email + password (with email verification before full access)
• Email magic link
• Google / Microsoft (social)
• SMS-assisted signup optional later

Post-signup

1. User has 7-day grace — can use product with verified email only.
2. Before grace ends (or on day 8), user must enroll TOTP on account.tenancyengine.com.
3. User sets preferred login challenge: TOTP (default), SMS, or email OTP.
4. Optional: enroll SMS phone and/or backup codes.

Every login (after MFA enrolled)

1. Primary auth (password, magic link, or social).
2. MFA challenge via preferred method (TOTP / SMS / email OTP).
3. Optional "remember this device" (30 days).
4. Redirect to originating client (console.tenancyengine.com, app, console.tenabill.com, etc.).

Audit events

Log email.verified, mfa.enrolled, mfa.challenge, login.success, login.failed, social.linked, device.remembered.

Security UI by surface

Surface	Security capabilities
Account hub	Email verification, TOTP QR enrollment, SMS phone, preferred MFA method, backup codes, linked social accounts, active sessions, change password
TE console	Settings → Security (deep-link to account hub); Billing → billing.tenancyengine.com
TenaBill merchant console	Settings → Security; branding → custom domain / SendGrid subaccount status
TE billing portal	Invoices, payment methods; step-up MFA for payment changes

Email & SendGrid branding

Platform (TenancyEngine merchant on TenaBill)

• From: [email protected], [email protected], [email protected]
• Portal: billing.tenancyengine.com (white-label theme)
• No "Powered by TenaBill" footer

TenaBill standalone merchant

1. Create TenaBill Merchant on signup
2. Provision SendGrid subaccount (API) for merchant
3. Default sending domain: {merchant-slug}.mail.tenabill.com
4. Merchant console → Branding: logo, colors, optional custom domain
5. Show "Powered by TenaBill" only when no custom domain and merchant is not a platform white-label merchant

Implementation phases

Phase	Deliverable	Status
P1	TenancyPlatform.Notifications — IEmailSender, ISmsVerifier; Mailpit dev	Done
P2	Email verification, account hub, TOTP enrollment, 7-day grace	Done
P3	SMS + email OTP challenge providers (Twilio + SendGrid)	Done (MVP)
P4	Google + Microsoft external login + post-login MFA	Done (MVP)
P5	OIDC clients: TE console, TenaBill console; account proxy	Partial
P6	TenaBill SendGrid subaccount on merchant signup	Done (MVP)
P7	White-label billing.tenancyengine.com + TE SendGrid templates	Planned
P8	Customer portal magic link via merchant-branded SendGrid	Planned

Local testing

See Local development for Mailpit, MFA enrollment URLs, and OIDC test flows.