@lunora/auth 1.0.0-alpha.14 → 1.0.0-alpha.141

package/dist/email-guard.d.mts

@@ -0,0 +1,127 @@
+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>;
+  /**
+   * 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 off `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so the email
+   * travels in the function `args` — which the builder surfaces to middleware
+   * as `ctx.args` (validated, frozen). Mirrors `verifyTurnstileMiddleware`'s
+   * `token` selector:
+   *
+   * ```ts
+   * export const signUp = mutation
+   *     .input({ email: v.string() })
+   *     .use(emailGateMiddleware({ email: (ctx) => ctx.args.email }))
+   *     .mutation(async ({ args, ctx }) => { … });
+   * ```
+   */
+  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).
+ *
+ * The returned/compared domain is IDNA-normalized (see {@link toAsciiDomain}) so
+ * a Unicode-form internationalized domain matches its `xn--` blocklist entry.
+ */
+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 (declare it with
+ * `.input(...)` and read it back as `ctx.args.email`)
+ * 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,127 @@
+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>;
+  /**
+   * 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 off `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so the email
+   * travels in the function `args` — which the builder surfaces to middleware
+   * as `ctx.args` (validated, frozen). Mirrors `verifyTurnstileMiddleware`'s
+   * `token` selector:
+   *
+   * ```ts
+   * export const signUp = mutation
+   *     .input({ email: v.string() })
+   *     .use(emailGateMiddleware({ email: (ctx) => ctx.args.email }))
+   *     .mutation(async ({ args, ctx }) => { … });
+   * ```
+   */
+  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).
+ *
+ * The returned/compared domain is IDNA-normalized (see {@link toAsciiDomain}) so
+ * a Unicode-form internationalized domain matches its `xn--` blocklist entry.
+ */
+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 (declare it with
+ * `.input(...)` and read it back as `ctx.args.email`)
+ * 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 r}from"@lunora/errors";import{isDisposableDomain as c,setDomains as d}from"@visulima/disposable-email-domains";import{extractDomain as u,isFreeDomain as w,setDomains as h}from"@visulima/free-email-domains";const n=a=>{const s=a.default??a;return Array.isArray(s)?s:[]};let o;const D=async()=>{if(o)return o;const a=(async()=>{const[s,t]=await Promise.all([import("@visulima/disposable-email-domains/domains"),import("@visulima/free-email-domains/domains",{with:{type:"json"}})]);d(n(s)),h(n(t))})();return o=a,a.catch(()=>{o=void 0}),a},m=a=>{try{return new URL(`https://${a}`).hostname}catch{return a.toLowerCase()}},l=a=>a&&a.length>0?new Set(a.map(s=>m(s))):void 0,f=(a,s={})=>{const t=u(a);if(t===void 0)return{domain:void 0,emailClass:"business"};const e=m(t),i=l(s.allowDomains);return c(e,{allowDomains:i,customDomains:l(s.denyDomains)})?{domain:e,emailClass:"disposable"}:w(e,{allowDomains:i})?{domain:e,emailClass:"free"}:{domain:e,emailClass:"business"}},p=async a=>{const{checkMxRecords:s}=await import("@visulima/email-verifier/checks/mx");return(await s(a)).valid},y=async(a,s={})=>{if(s.requireValidSyntax!==!1){const{validateSyntax:e}=await import("@visulima/email-verifier/checks/syntax");if(!e(a))throw new r("VALIDATION_ERROR",`@lunora/auth: "${a}" is not a valid email address.`)}await D();const t=f(a,s);if(t.emailClass==="disposable"&&s.blockDisposable!==!1)throw new r("EMAIL_DOMAIN_BLOCKED",`@lunora/auth: signups from the disposable/throwaway domain "${t.domain??a}" are not allowed.`);if(s.mx===!0&&t.domain!==void 0&&!await p(t.domain))throw new r("EMAIL_UNDELIVERABLE",`@lunora/auth: the domain "${t.domain}" publishes no MX records, so mail to it cannot be delivered.`);return t},b=a=>async({ctx:s,next:t})=>{const e=a.email(s);if(e===void 0||e==="")throw new r("VALIDATION_ERROR","@lunora/auth: emailGateMiddleware received no email to check.");const i=await y(e,a);return a.onClassify?.(i,s),t()};export{y as assertEmailAllowed,f as classifyEmail,b as emailGateMiddleware,D as loadEmailDomainLists};