docs(authentication): document email restrictions

apps/web/content/docs/modules/authentication.mdx

@@ -55,6 +55,7 @@ Apps need sign-up, login, token lifecycle, and optional multi-tenant membership
     "User profile extension fields",
     "Anonymous users (optional)",
     "Account linking (same email across providers)",
+    "Email restrictions (disposable domains, plus-addressing, allow/block lists)",
   ]}
 />
 
@@ -114,6 +115,15 @@ Patch module config via MCP `patch_config_authentication`:
 | `twoFa.backUpCodes.enabled` | true | Expose backup-code generate/recover routes |
 | `magic_link.enabled` | false | Passwordless email login |
 | `anonymousUsers.enabled` | false | Anonymous user registration |
+| `emailRestrictions.enabled` | false | Master switch |
+| `emailRestrictions.blockDisposableEmails` | true | Bundled disposable-domain list (when enabled) |
+| `emailRestrictions.blockPlusAddressing` | true | Reject any `+` in the local part (`user+tag@domain`) |
+| `emailRestrictions.blockedAddresses` | [] | Exact emails |
+| `emailRestrictions.allowedAddresses` | [] | Exact allowlist (wins, except reserved `@anonymous.com`) |
+| `emailRestrictions.blockedDomains` | [] | Custom domains; suffix match (`evil.com` blocks `mail.evil.com`; not a bare TLD) |
+| `emailRestrictions.allowedDomains` | [] | Domain allowlist, suffix match (wins, except reserved `@anonymous.com`) |
+
+Email restrictions apply when a new or changed email is accepted — local register, change-email, OAuth new accounts and anonymous upgrade, admin create/patch, gRPC `userCreate`, and team invites — not on login, forgot-password, or magic-link for existing users. Blocked addresses return `EMAIL_NOT_ALLOWED` (*This email address is not allowed*). Plus-addressing blocks any `+` in the local part; domain allowlists and blocklists use suffix matching (allowlists win, except reserved `@anonymous.com`). The disposable-domain list is bundled — no runtime network fetch. `@anonymous.com` and its subdomains are always reserved for Conduit anonymous users. Change-email verification links are not rechecked when redeemed.
 
 OAuth providers need `clientId` + `clientSecret` per provider under `config.{provider}.enabled`.
 
@@ -149,7 +159,7 @@ Enable with `?modules=authentication` in your MCP server URL.
 | `post_authentication_users` | Create user (admin) |
 | `get_authentication_teams` | List teams |
 | `post_authentication_teams` | Create team |
-| `patch_config_authentication` | Token, OAuth, team, and 2FA settings |
+| `patch_config_authentication` | Token, OAuth, team, 2FA, and email restriction settings |
 
 For operator automation, prefer `cdt_` API tokens over legacy service-account config. See [MCP setup](/docs/getting-started/mcp-setup).
 

documentation/versioned_docs/version-v0.16/modules/authentication/config.mdx

@@ -50,4 +50,8 @@ Account linking is also supported, but only works for accounts using the same em
 
 Enable the Magic Link authentication strategy and specify the redirect URI to which the user will be redirected after signing in.
 
-![Magic Link Configuration](/v0.16/modules/authentication/tutorials/enable_magic_link.png)
+![Magic Link Configuration](/v0.16/modules/authentication/tutorials/enable_magic_link.png)
+
+## Email Restrictions
+
+See [Configuration](./configuration#email-restrictions) for email allow/deny lists and disposable-domain blocking.

documentation/versioned_docs/version-v0.16/modules/authentication/configuration.mdx

@@ -72,6 +72,24 @@ When enabled, users authenticating with the same email across different provider
 | Redirect URI | Where to send users after verification |
 | Link Expiry | How long magic links remain valid |
 
+## Email Restrictions
+
+Block or allow email addresses when they are accepted: local registration, change-email, OAuth new accounts and anonymous upgrade, admin create/patch, gRPC `userCreate`, and team invites. Not enforced on login, forgot-password, or magic-link flows for existing users. Off by default.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Enabled | `false` | Master switch |
+| Block Disposable Emails | `true` | Reject addresses on the bundled disposable-domain list |
+| Block Plus Addressing | `true` | Reject `+` in the local part (`user+tag@domain`) |
+| Blocked Addresses | `[]` | Exact email denylist |
+| Blocked Domains | `[]` | Domain denylist; suffix match (`evil.com` also blocks `mail.evil.com`; not a bare TLD) |
+| Allowed Addresses | `[]` | Exact allowlist; overrides blocks, not reserved `@anonymous.com` |
+| Allowed Domains | `[]` | Domain allowlist; suffix match; overrides blocks, not reserved `@anonymous.com` |
+
+Rejected requests return `This email address is not allowed` (`EMAIL_NOT_ALLOWED`). The disposable list is bundled (~8k domains and wildcards); no runtime network fetch.
+
+`@anonymous.com` and its subdomains are always reserved for Conduit-created anonymous users and cannot be registered or invited. Change-email verification links are not rechecked when redeemed, so a token issued before restrictions were enabled still completes.
+
 ## Token Configuration
 
 ### Access Tokens

documentation/versioned_docs/version-v0.16/modules/authentication/index.mdx

@@ -11,6 +11,7 @@ The Authentication module provides user identity management for your application
 ## Features
 
 - **Local Authentication** - Email/password with optional verification
+- **Email Restrictions** - Block disposable domains, plus-addressing, or custom deny/allow lists when emails are accepted
 - **OAuth Providers** - 13+ social login integrations
 - **Two-Factor Auth** - Phone OTP and authenticator app support
 - **Magic Links** - Passwordless login via email