@lunora/auth 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/email-guard.d.mts

@@ -0,0 +1,122 @@
+import { Middleware } from '@lunora/server';
+/**
+ * The resolved trust class of an email address' domain: `disposable` (a
+ * throwaway/temporary provider, or a caller `denyDomains` hit), `free` (a free
+ * consumer provider like Gmail — deliverable but not B2B), or `business`
+ * (anything else — a custom/company domain, or an `allowDomains` hit).
+ */
+type EmailClass = "business" | "disposable" | "free";
+/** Result of {@link classifyEmail} — the resolved class plus the normalized domain. */
+interface EmailClassification {
+  /** The normalized (lowercased, trimmed) domain, or `undefined` for a structurally invalid address. */
+  domain: string | undefined;
+  /** The resolved trust class. A structurally invalid address resolves to `business` with `domain: undefined`. */
+  emailClass: EmailClass;
+}
+/** Configuration for {@link classifyEmail} / {@link assertEmailAllowed} / {@link emailGateMiddleware}. */
+interface EmailGateConfig {
+  /**
+   * Domains that are always allowed and always classified `business`, even if
+   * they appear on the disposable or free lists. Wildcard/subdomain aware
+   * (`example.com` also allows `mail.example.com`). Your own hosted domains go
+   * here.
+   */
+  allowDomains?: ReadonlyArray<string>;
+  /**
+   * Reject disposable/throwaway signups. Defaults to `true` — the whole point
+   * of the gate. Set `false` to classify-only (surface `emailClass` without
+   * blocking).
+   */
+  blockDisposable?: boolean;
+  /**
+   * Extra domains to treat as disposable (blocked when `blockDisposable`), on
+   * top of the built-in list. Wildcard/subdomain aware.
+   */
+  denyDomains?: ReadonlyArray<string>;
+  /**
+   * Reserved for callers that branch on free-vs-business (e.g. gate a feature
+   * behind a business email). Purely advisory — {@link EmailClassification}'s
+   * `emailClass` already reports `free`, so this flag exists for symmetry/intent
+   * and never blocks. Defaults to `false`.
+   */
+  flagFreeEmail?: boolean;
+  /**
+   * Opt-in MX deliverability verification. Off by default because it needs DNS
+   * (`@visulima/email-verifier/checks/mx` → `node:dns`), which is not available
+   * on the default workerd path. When `true`, {@link assertEmailAllowed} rejects
+   * an address whose domain publishes no MX (or fallback A/AAAA) records with
+   * `EMAIL_UNDELIVERABLE`. The check is loaded via a dynamic import, so leaving
+   * this off keeps the DNS module out of the bundle entirely.
+   */
+  mx?: boolean;
+  /**
+   * Reject structurally invalid addresses up front (via
+   * `@visulima/email-verifier/checks/syntax`, pure-data/edge-safe). Defaults to
+   * `true`. When `false`, an unparseable address classifies as `business` with
+   * `domain: undefined` and is not rejected on syntax alone.
+   */
+  requireValidSyntax?: boolean;
+}
+/** Options for {@link emailGateMiddleware}: the base gate config plus how to read the email from `ctx`. */
+interface EmailGateMiddlewareOptions<Context> extends EmailGateConfig {
+  /**
+   * Selector that pulls the signup email from `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so route the
+   * email through the function `args` and read it out here (mirrors
+   * `verifyTurnstileMiddleware`'s `token` selector).
+   */
+  email: (context: Context) => string | undefined;
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can branch on `free` vs `business` (e.g. gate a plan behind a business
+   * email). Never fires when the gate rejects.
+   */
+  onClassify?: (classification: EmailClassification, context: Context) => void;
+}
+/**
+ * Inject the built-in disposable + free domain lists into the lookup packages,
+ * once. Call this at worker init on workerd (where the packages' `node:fs`
+ * loader is unavailable) so {@link classifyEmail} has data to match against;
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware} await it for you, so
+ * the gating path is always edge-safe. Idempotent — repeat calls share one load.
+ */
+declare const loadEmailDomainLists: () => Promise<void>;
+/**
+ * Classify an email address' domain as `disposable` / `free` / `business`,
+ * pure-data and edge-safe (no DNS, no filesystem). A structurally invalid
+ * address resolves to `{ domain: undefined, emailClass: "business" }` — use
+ * {@link assertEmailAllowed} (which can reject on syntax) for the gating path.
+ * `allowDomains` wins over both lists; `denyDomains` adds to the disposable list.
+ *
+ * The lookup relies on the built-in domain lists being loaded. On Node they
+ * auto-load from disk; on workerd, `await loadEmailDomainLists()` first (or use
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware}, which await it).
+ */
+declare const classifyEmail: (email: string, config?: EmailGateConfig) => EmailClassification;
+/**
+ * Classify `email` and enforce the gate, throwing a coded {@link LunoraError}
+ * when it fails: `VALIDATION_ERROR` (structurally invalid, only when
+ * `requireValidSyntax`, the default), `EMAIL_DOMAIN_BLOCKED` (disposable or
+ * deny-listed, only when `blockDisposable`, the default), or `EMAIL_UNDELIVERABLE`
+ * (no MX records, only when `mx: true`).
+ *
+ * Returns the {@link EmailClassification} on success so callers can branch on
+ * `free` vs `business`. Async only because of the opt-in MX step; with `mx` off
+ * it resolves without any network I/O.
+ */
+declare const assertEmailAllowed: (email: string, config?: EmailGateConfig) => Promise<EmailClassification>;
+/**
+ * Lunora procedure middleware that gates a non-auth, signup-shaped
+ * `mutation`/`action` on the email-domain policy. Attach it with `.use()`; it
+ * reads the email from `ctx` via the `email` selector (route it through `args`)
+ * and runs {@link assertEmailAllowed}, which throws a coded {@link LunoraError}
+ * (`EMAIL_DOMAIN_BLOCKED` / `EMAIL_UNDELIVERABLE` / `VALIDATION_ERROR`) the
+ * runtime maps to the matching status.
+ *
+ * To gate better-auth's native `/sign-up/email` endpoint instead, use
+ * `emailGateDatabaseHooks` / `withEmailGate` from `@lunora/auth` — those hook
+ * better-auth's own user-create path. The `Middleware` import is type-only, so
+ * this stays free of any runtime `@lunora/server` dependency.
+ */
+declare const emailGateMiddleware: <Context>(options: EmailGateMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type EmailClass, type EmailClassification, type EmailGateConfig, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists };

package/dist/email-guard.d.ts

@@ -0,0 +1,122 @@
+import { Middleware } from '@lunora/server';
+/**
+ * The resolved trust class of an email address' domain: `disposable` (a
+ * throwaway/temporary provider, or a caller `denyDomains` hit), `free` (a free
+ * consumer provider like Gmail — deliverable but not B2B), or `business`
+ * (anything else — a custom/company domain, or an `allowDomains` hit).
+ */
+type EmailClass = "business" | "disposable" | "free";
+/** Result of {@link classifyEmail} — the resolved class plus the normalized domain. */
+interface EmailClassification {
+  /** The normalized (lowercased, trimmed) domain, or `undefined` for a structurally invalid address. */
+  domain: string | undefined;
+  /** The resolved trust class. A structurally invalid address resolves to `business` with `domain: undefined`. */
+  emailClass: EmailClass;
+}
+/** Configuration for {@link classifyEmail} / {@link assertEmailAllowed} / {@link emailGateMiddleware}. */
+interface EmailGateConfig {
+  /**
+   * Domains that are always allowed and always classified `business`, even if
+   * they appear on the disposable or free lists. Wildcard/subdomain aware
+   * (`example.com` also allows `mail.example.com`). Your own hosted domains go
+   * here.
+   */
+  allowDomains?: ReadonlyArray<string>;
+  /**
+   * Reject disposable/throwaway signups. Defaults to `true` — the whole point
+   * of the gate. Set `false` to classify-only (surface `emailClass` without
+   * blocking).
+   */
+  blockDisposable?: boolean;
+  /**
+   * Extra domains to treat as disposable (blocked when `blockDisposable`), on
+   * top of the built-in list. Wildcard/subdomain aware.
+   */
+  denyDomains?: ReadonlyArray<string>;
+  /**
+   * Reserved for callers that branch on free-vs-business (e.g. gate a feature
+   * behind a business email). Purely advisory — {@link EmailClassification}'s
+   * `emailClass` already reports `free`, so this flag exists for symmetry/intent
+   * and never blocks. Defaults to `false`.
+   */
+  flagFreeEmail?: boolean;
+  /**
+   * Opt-in MX deliverability verification. Off by default because it needs DNS
+   * (`@visulima/email-verifier/checks/mx` → `node:dns`), which is not available
+   * on the default workerd path. When `true`, {@link assertEmailAllowed} rejects
+   * an address whose domain publishes no MX (or fallback A/AAAA) records with
+   * `EMAIL_UNDELIVERABLE`. The check is loaded via a dynamic import, so leaving
+   * this off keeps the DNS module out of the bundle entirely.
+   */
+  mx?: boolean;
+  /**
+   * Reject structurally invalid addresses up front (via
+   * `@visulima/email-verifier/checks/syntax`, pure-data/edge-safe). Defaults to
+   * `true`. When `false`, an unparseable address classifies as `business` with
+   * `domain: undefined` and is not rejected on syntax alone.
+   */
+  requireValidSyntax?: boolean;
+}
+/** Options for {@link emailGateMiddleware}: the base gate config plus how to read the email from `ctx`. */
+interface EmailGateMiddlewareOptions<Context> extends EmailGateConfig {
+  /**
+   * Selector that pulls the signup email from `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so route the
+   * email through the function `args` and read it out here (mirrors
+   * `verifyTurnstileMiddleware`'s `token` selector).
+   */
+  email: (context: Context) => string | undefined;
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can branch on `free` vs `business` (e.g. gate a plan behind a business
+   * email). Never fires when the gate rejects.
+   */
+  onClassify?: (classification: EmailClassification, context: Context) => void;
+}
+/**
+ * Inject the built-in disposable + free domain lists into the lookup packages,
+ * once. Call this at worker init on workerd (where the packages' `node:fs`
+ * loader is unavailable) so {@link classifyEmail} has data to match against;
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware} await it for you, so
+ * the gating path is always edge-safe. Idempotent — repeat calls share one load.
+ */
+declare const loadEmailDomainLists: () => Promise<void>;
+/**
+ * Classify an email address' domain as `disposable` / `free` / `business`,
+ * pure-data and edge-safe (no DNS, no filesystem). A structurally invalid
+ * address resolves to `{ domain: undefined, emailClass: "business" }` — use
+ * {@link assertEmailAllowed} (which can reject on syntax) for the gating path.
+ * `allowDomains` wins over both lists; `denyDomains` adds to the disposable list.
+ *
+ * The lookup relies on the built-in domain lists being loaded. On Node they
+ * auto-load from disk; on workerd, `await loadEmailDomainLists()` first (or use
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware}, which await it).
+ */
+declare const classifyEmail: (email: string, config?: EmailGateConfig) => EmailClassification;
+/**
+ * Classify `email` and enforce the gate, throwing a coded {@link LunoraError}
+ * when it fails: `VALIDATION_ERROR` (structurally invalid, only when
+ * `requireValidSyntax`, the default), `EMAIL_DOMAIN_BLOCKED` (disposable or
+ * deny-listed, only when `blockDisposable`, the default), or `EMAIL_UNDELIVERABLE`
+ * (no MX records, only when `mx: true`).
+ *
+ * Returns the {@link EmailClassification} on success so callers can branch on
+ * `free` vs `business`. Async only because of the opt-in MX step; with `mx` off
+ * it resolves without any network I/O.
+ */
+declare const assertEmailAllowed: (email: string, config?: EmailGateConfig) => Promise<EmailClassification>;
+/**
+ * Lunora procedure middleware that gates a non-auth, signup-shaped
+ * `mutation`/`action` on the email-domain policy. Attach it with `.use()`; it
+ * reads the email from `ctx` via the `email` selector (route it through `args`)
+ * and runs {@link assertEmailAllowed}, which throws a coded {@link LunoraError}
+ * (`EMAIL_DOMAIN_BLOCKED` / `EMAIL_UNDELIVERABLE` / `VALIDATION_ERROR`) the
+ * runtime maps to the matching status.
+ *
+ * To gate better-auth's native `/sign-up/email` endpoint instead, use
+ * `emailGateDatabaseHooks` / `withEmailGate` from `@lunora/auth` — those hook
+ * better-auth's own user-create path. The `Middleware` import is type-only, so
+ * this stays free of any runtime `@lunora/server` dependency.
+ */
+declare const emailGateMiddleware: <Context>(options: EmailGateMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type EmailClass, type EmailClassification, type EmailGateConfig, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists };

package/dist/email-guard.mjs

@@ -0,0 +1 @@
+import{LunoraError as e}from"@lunora/errors";import{isDisposableDomain as m,setDomains as d}from"@visulima/disposable-email-domains";import{extractDomain as c,isFreeDomain as w,setDomains as u}from"@visulima/free-email-domains";const t=a=>{const i=a.default??a;return Array.isArray(i)?i:[]};let n;const D=async()=>(n??=(async()=>{const[a,i]=await Promise.all([import("@visulima/disposable-email-domains/domains"),import("@visulima/free-email-domains/domains")]);d(t(a)),u(t(i))})(),n),r=a=>a&&a.length>0?new Set(a.map(i=>i.toLowerCase())):void 0,f=(a,i={})=>{const o=c(a);if(o===void 0)return{domain:void 0,emailClass:"business"};const s=r(i.allowDomains);return m(o,{allowDomains:s,customDomains:r(i.denyDomains)})?{domain:o,emailClass:"disposable"}:w(o,{allowDomains:s})?{domain:o,emailClass:"free"}:{domain:o,emailClass:"business"}},p=async a=>{const{checkMxRecords:i}=await import("@visulima/email-verifier/checks/mx");return(await i(a)).valid},h=async(a,i={})=>{if(i.requireValidSyntax!==!1){const{validateSyntax:s}=await import("@visulima/email-verifier/checks/syntax");if(!s(a))throw new e("VALIDATION_ERROR",`@lunora/auth: "${a}" is not a valid email address.`)}await D();const o=f(a,i);if(o.emailClass==="disposable"&&i.blockDisposable!==!1)throw new e("EMAIL_DOMAIN_BLOCKED",`@lunora/auth: signups from the disposable/throwaway domain "${o.domain??a}" are not allowed.`);if(i.mx===!0&&o.domain!==void 0&&!await p(o.domain))throw new e("EMAIL_UNDELIVERABLE",`@lunora/auth: the domain "${o.domain}" publishes no MX records, so mail to it cannot be delivered.`);return o},b=a=>async({ctx:i,next:o})=>{const s=a.email(i);if(s===void 0||s==="")throw new e("VALIDATION_ERROR","@lunora/auth: emailGateMiddleware received no email to check.");const l=await h(s,a);return a.onClassify?.(l,i),o()};export{h as assertEmailAllowed,f as classifyEmail,b as emailGateMiddleware,D as loadEmailDomainLists};