feat(webapp): add a configurable email-domain block list for sign-in

Adds a `BLOCKED_EMAIL_DOMAINS` setting for self-hosted instances. It
takes a comma-separated list of email domains, including their
subdomains, that can't sign in or sign up. A magic-link request for a
blocked address shows the usual "check your email" page, but no email is
sent. GitHub, Google and SSO sign-in, magic-link clicks, and email
changes to a blocked address are refused. It's empty by default, so
nothing changes unless you set it.

Mono-RevId: 817556233067e86f51a3daef4cb429ce69244c37

Author: ericallam

.server-changes/blocked-email-domains.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Self-hosted instances can block sign-in and sign-up from specific email domains with the new `BLOCKED_EMAIL_DOMAINS` setting.

apps/webapp/app/env.server.ts

@@ -402,6 +402,7 @@ const EnvironmentSchema = z
       .string()
       .refine(isValidRegex, "WHITELISTED_EMAILS must be a valid regex.")
       .optional(),
+    BLOCKED_EMAIL_DOMAINS: z.string().optional(),
     ADMIN_EMAILS: z.string().refine(isValidRegex, "ADMIN_EMAILS must be a valid regex.").optional(),
     // Instance-level kill switch for the admin dashboard and user impersonation.
     ADMIN_DASHBOARD_ENABLED: BoolEnv.default(true),

apps/webapp/app/services/email.server.ts

@@ -6,7 +6,7 @@ import { env } from "~/env.server";
 import type { AuthUser } from "./authUser";
 import { logger } from "./logger.server";
 import { singleton } from "~/utils/singleton";
-import { assertEmailAllowed } from "~/utils/email";
+import { assertEmailAllowed, isEmailDomainBlocked } from "~/utils/email";
 
 const client = singleton(
   "email-client",
@@ -66,6 +66,11 @@ function buildTransportOptions(alerts?: boolean): MailTransportOptions {
 }
 
 export async function sendMagicLinkEmail(options: SendEmailOptions<AuthUser>): Promise<void> {
+  if (isEmailDomainBlocked(options.emailAddress)) {
+    logger.info("Magic link not sent: email domain is blocked");
+    return;
+  }
+
   assertEmailAllowed(options.emailAddress);
 
   // Auto redirect when in development mode

apps/webapp/app/utils/email.ts

@@ -1,7 +1,20 @@
 import { env } from "~/env.server";
+import { emailDomainIsListed } from "./emailDomainList";
 import { emailMatchesPattern } from "./emailPattern";
 
+export function isEmailDomainBlocked(email: string): boolean {
+  if (!env.BLOCKED_EMAIL_DOMAINS) {
+    return false;
+  }
+
+  return emailDomainIsListed(env.BLOCKED_EMAIL_DOMAINS, email);
+}
+
 export function assertEmailAllowed(email: string) {
+  if (isEmailDomainBlocked(email)) {
+    throw new Error("This email address isn't allowed to sign in on this instance.");
+  }
+
   if (!env.WHITELISTED_EMAILS) {
     return;
   }

apps/webapp/app/utils/emailDomainList.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether an email's domain is in an operator-supplied list of domains
+ * (BLOCKED_EMAIL_DOMAINS). The list is comma or whitespace separated, and an
+ * entry matches its own domain and every subdomain of it, case-insensitively.
+ *
+ * Dependency-free so it can be tested directly; callers pass the list from `env`.
+ */
+export function emailDomainIsListed(domainList: string, email: string): boolean {
+  const domain = normalizeDomain(email.slice(email.lastIndexOf("@") + 1));
+  if (!domain) {
+    return false;
+  }
+
+  return parseDomainList(domainList).some(
+    (entry) => domain === entry || domain.endsWith(`.${entry}`)
+  );
+}
+
+function parseDomainList(domainList: string): string[] {
+  return domainList
+    .split(/[\s,]+/)
+    .map((entry) => normalizeDomain(entry.replace(/^[@.]+/, "")))
+    .filter((entry) => entry.length > 0);
+}
+
+function normalizeDomain(domain: string): string {
+  return domain.trim().toLowerCase().replace(/\.+$/, "");
+}

apps/webapp/test/emailDomainList.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { emailDomainIsListed } from "../app/utils/emailDomainList.js";
+
+describe("emailDomainIsListed", () => {
+  it("matches an address at a listed domain", () => {
+    expect(emailDomainIsListed("blocked.example", "bot@blocked.example")).toBe(true);
+  });
+
+  it("matches subdomains of a listed domain", () => {
+    expect(emailDomainIsListed("blocked.example", "bot@mail.blocked.example")).toBe(true);
+    expect(emailDomainIsListed("blocked.example", "bot@a.b.blocked.example")).toBe(true);
+  });
+
+  it("ignores case and surrounding whitespace in both the list and the address", () => {
+    expect(emailDomainIsListed("  Blocked.Example  ", "Bot@BLOCKED.example")).toBe(true);
+  });
+
+  it("accepts comma and whitespace separated lists", () => {
+    const list = "one.example, two.example\nthree.example  four.example";
+    expect(emailDomainIsListed(list, "a@one.example")).toBe(true);
+    expect(emailDomainIsListed(list, "a@two.example")).toBe(true);
+    expect(emailDomainIsListed(list, "a@three.example")).toBe(true);
+    expect(emailDomainIsListed(list, "a@four.example")).toBe(true);
+    expect(emailDomainIsListed(list, "a@five.example")).toBe(false);
+  });
+
+  it("accepts entries written with a leading @ or dot", () => {
+    expect(emailDomainIsListed("@blocked.example", "bot@blocked.example")).toBe(true);
+    expect(emailDomainIsListed(".blocked.example", "bot@sub.blocked.example")).toBe(true);
+  });
+
+  it("matches a fully qualified domain with a trailing dot", () => {
+    expect(emailDomainIsListed("blocked.example", "bot@blocked.example.")).toBe(true);
+  });
+
+  it("does not match look-alike domains", () => {
+    expect(emailDomainIsListed("blocked.example", "user@notblocked.example")).toBe(false);
+    expect(emailDomainIsListed("blocked.example", "user@blocked.example.attacker.example")).toBe(
+      false
+    );
+    expect(emailDomainIsListed("blocked.example", "blocked.example@other.example")).toBe(false);
+  });
+
+  it("does not let a listed domain block its parent", () => {
+    expect(emailDomainIsListed("mail.company.example", "user@company.example")).toBe(false);
+  });
+
+  it("matches nothing when the list is empty or only separators", () => {
+    expect(emailDomainIsListed("", "user@company.example")).toBe(false);
+    expect(emailDomainIsListed(" , ,", "user@company.example")).toBe(false);
+  });
+
+  it("matches nothing for an address without a domain", () => {
+    expect(emailDomainIsListed("blocked.example", "user@")).toBe(false);
+  });
+});

docs/self-hosting/env/webapp.mdx

@@ -42,6 +42,7 @@ mode: "wide"
 | `REDIS_TLS_DISABLED`                             | No       | —                     | Disable Redis TLS.                                                                                                 |
 | **Auth**                                         |          |                       |                                                                                                                    |
 | `WHITELISTED_EMAILS`                             | No       | —                     | Whitelisted emails regex.                                                                                          |
+| `BLOCKED_EMAIL_DOMAINS`                          | No       | —                     | Comma-separated email domains that can't sign in or sign up, including their subdomains.                           |
 | `LOGIN_RATE_LIMITS_ENABLED`                      | No       | true                  | Enable rate limiting on magic-link login.                                                                          |
 | `AUTH_GITHUB_CLIENT_ID`                          | No       | —                     | GitHub client ID.                                                                                                  |
 | `AUTH_GITHUB_CLIENT_SECRET`                      | No       | —                     | GitHub client secret.                                                                                              |

hosting/docker/webapp/docker-compose.yml

@@ -58,6 +58,7 @@ services:
       DIRECT_URL: ${DIRECT_URL:-postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/main?schema=public&sslmode=disable}
       SESSION_SECRET: ${SESSION_SECRET}
       MAGIC_LINK_SECRET: ${MAGIC_LINK_SECRET}
+      BLOCKED_EMAIL_DOMAINS: ${BLOCKED_EMAIL_DOMAINS:-}
       ENCRYPTION_KEY: ${ENCRYPTION_KEY}
       PROVIDER_SECRET: ${PROVIDER_SECRET}
       COORDINATOR_SECRET: ${COORDINATOR_SECRET}