@lunora/auth 1.0.0-alpha.22 → 1.0.0-alpha.220

package/dist/cimd-node.d.ts

@@ -0,0 +1 @@
+export { fetchClientMetadataResource as default } from '@better-auth/cimd/node';

package/dist/cimd-node.mjs

@@ -0,0 +1 @@
+import{fetchClientMetadataResource as a}from"@better-auth/cimd/node";export{a as default};

package/dist/cimd-workers.d.mts

@@ -0,0 +1,32 @@
+import { ClientMetadataResourceFetch } from '@better-auth/oauth-provider';
+/**
+ * Build the `fetchClientMetadataResource` transport for `cimd()` on Cloudflare
+ * Workers.
+ *
+ * ```ts
+ * import { cimd, jwt, mcp } from "@lunora/auth/plugins";
+ * import workersCimdFetch from "@lunora/auth/cimd/workers";
+ *
+ * plugins: [
+ *     jwt(),
+ *     mcp({ … }),
+ *     cimd({
+ *         fetchClientMetadataResource: workersCimdFetch(),
+ *         metadataProfile: "mcp-2026-07-28",
+ *         isMetadataDocumentUrlAllowed: (url) => new URL(url).origin === "https://claude.ai",
+ *         // The allowlist gates only the `client_id` fetch; bind `jwks_uri` to it too.
+ *         originBoundFields: ["post_logout_redirect_uris", "client_uri", "jwks_uri"],
+ *     }),
+ * ];
+ * ```
+ *
+ * The returned transport only issues `GET` / `HEAD` to `https:` URLs without
+ * credentials, and never follows a redirect: it fetches with `redirect: "manual"`
+ * (workerd does not implement `"error"`) and throws on any redirect status, which
+ * cimd reports as `invalid_client`. A `304` from a conditional revalidation passes
+ * through.
+ * @throws LunoraError `AUTH_CIMD_FETCH_NOT_PUBLIC` when the Worker runs without the
+ * `global_fetch_strictly_public` compatibility flag.
+ */
+declare const workersCimdFetch: () => ClientMetadataResourceFetch;
+export { workersCimdFetch as default };

package/dist/cimd-workers.d.ts

@@ -0,0 +1,32 @@
+import { ClientMetadataResourceFetch } from '@better-auth/oauth-provider';
+/**
+ * Build the `fetchClientMetadataResource` transport for `cimd()` on Cloudflare
+ * Workers.
+ *
+ * ```ts
+ * import { cimd, jwt, mcp } from "@lunora/auth/plugins";
+ * import workersCimdFetch from "@lunora/auth/cimd/workers";
+ *
+ * plugins: [
+ *     jwt(),
+ *     mcp({ … }),
+ *     cimd({
+ *         fetchClientMetadataResource: workersCimdFetch(),
+ *         metadataProfile: "mcp-2026-07-28",
+ *         isMetadataDocumentUrlAllowed: (url) => new URL(url).origin === "https://claude.ai",
+ *         // The allowlist gates only the `client_id` fetch; bind `jwks_uri` to it too.
+ *         originBoundFields: ["post_logout_redirect_uris", "client_uri", "jwks_uri"],
+ *     }),
+ * ];
+ * ```
+ *
+ * The returned transport only issues `GET` / `HEAD` to `https:` URLs without
+ * credentials, and never follows a redirect: it fetches with `redirect: "manual"`
+ * (workerd does not implement `"error"`) and throws on any redirect status, which
+ * cimd reports as `invalid_client`. A `304` from a conditional revalidation passes
+ * through.
+ * @throws LunoraError `AUTH_CIMD_FETCH_NOT_PUBLIC` when the Worker runs without the
+ * `global_fetch_strictly_public` compatibility flag.
+ */
+declare const workersCimdFetch: () => ClientMetadataResourceFetch;
+export { workersCimdFetch as default };

package/dist/cimd-workers.mjs

@@ -0,0 +1 @@
+import{LunoraError as c}from"@lunora/errors";const a="global_fetch_strictly_public",i=()=>{const{Cloudflare:t}=globalThis;return t?.compatibilityFlags?.[a]===!0},n=new Set([301,302,303,307,308]),l=t=>n.has(t.status)||t.type==="opaqueredirect",d=()=>{if(!i())throw new c("AUTH_CIMD_FETCH_NOT_PUBLIC",`CIMD needs the "${a}" compatibility flag, so metadata fetches cannot reach private addresses. Add it to "compatibility_flags" in wrangler.jsonc.`);return async(t,s)=>{const e=new Request(t,{...s,redirect:"manual"}),r=new URL(e.url);if(r.protocol!=="https:")throw new TypeError(`refusing to fetch a client metadata resource over ${r.protocol}`);if(r.username!==""||r.password!=="")throw new TypeError("refusing to fetch a client metadata resource URL that carries credentials");if(e.method!=="GET"&&e.method!=="HEAD")throw new TypeError(`refusing to ${e.method} a client metadata resource`);const o=await fetch(e);if(l(o))throw new TypeError("client metadata resource fetches must not follow redirects");return o}};export{d as default};

package/dist/email-guard.d.mts

@@ -0,0 +1,143 @@
+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>;
+  /**
+   * Which built-in lists {@link assertEmailAllowed} loads (both by default, so the
+   * returned class is complete). The disposable list is ~2.7 MB and the free list
+   * ~143 KB of bundle; `emailGateMiddleware` and `emailGateDatabaseHooks` set this
+   * for you: the free list loads only with `onClassify`, the disposable list only
+   * with `blockDisposable !== false` or `onClassify`.
+   */
+  lists?: {
+    disposable?: boolean;
+    free?: 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 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 domain lists into the lookup packages, once each. 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, loading only what the config needs.
+ * Both lists (~2.7 MB disposable, ~143 KB free) load by default; pass
+ * `{ free: false }` or `{ disposable: false }` to skip one. Idempotent — repeat
+ * calls share one load per list.
+ */
+declare const loadEmailDomainLists: ({ disposable, free }?: {
+  disposable?: boolean;
+  free?: boolean;
+}) => 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,143 @@
+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>;
+  /**
+   * Which built-in lists {@link assertEmailAllowed} loads (both by default, so the
+   * returned class is complete). The disposable list is ~2.7 MB and the free list
+   * ~143 KB of bundle; `emailGateMiddleware` and `emailGateDatabaseHooks` set this
+   * for you: the free list loads only with `onClassify`, the disposable list only
+   * with `blockDisposable !== false` or `onClassify`.
+   */
+  lists?: {
+    disposable?: boolean;
+    free?: 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 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 domain lists into the lookup packages, once each. 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, loading only what the config needs.
+ * Both lists (~2.7 MB disposable, ~143 KB free) load by default; pass
+ * `{ free: false }` or `{ disposable: false }` to skip one. Idempotent — repeat
+ * calls share one load per list.
+ */
+declare const loadEmailDomainLists: ({ disposable, free }?: {
+  disposable?: boolean;
+  free?: boolean;
+}) => 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 l}from"@lunora/errors";import{assertListLoaded as D,isDisposableDomain as v,setDomains as y}from"@visulima/disposable-email-domains";import{extractDomain as w,assertListLoaded as L,setDomains as b,isFreeDomain as p}from"@visulima/free-email-domains";const c=a=>{const s=a.default??a;return Array.isArray(s)?s:[]};let r,n,d=!1;const u=(a,s,t)=>{if(a)return a;const e=s();return e.catch(t),e},E=async({disposable:a=!0,free:s=!0}={})=>{a&&(r=u(r,async()=>{y(c(await import("@visulima/disposable-email-domains/domains")))},()=>{r=void 0})),s&&(n=u(n,async()=>{b(c(await import("@visulima/free-email-domains/domains"))),d=!0},()=>{n=void 0})),await Promise.all([a?r:void 0,s?n:void 0])},m=a=>{try{return new URL(`https://${a}`).hostname}catch{return a.toLowerCase()}},f=a=>a&&a.length>0?new Set(a.map(s=>m(s))):void 0,A=(a,s={})=>{const t=w(a);if(t===void 0)return{domain:void 0,emailClass:"business"};try{D(),d&&L()}catch(i){throw new Error("@lunora/auth: the email domain lists are not loaded; `await loadEmailDomainLists()` before calling classifyEmail (assertEmailAllowed does this for you).",{cause:i})}const e=m(t),o=f(s.allowDomains);return v(e,{allowDomains:o,customDomains:f(s.denyDomains)})?{domain:e,emailClass:"disposable"}:d&&p(e,{allowDomains:o})?{domain:e,emailClass:"free"}:{domain:e,emailClass:"business"}},C=async a=>{const{checkMxRecords:s}=await import("@visulima/email-verifier/checks/mx"),t=await s(a);return t.valid||t.deferred===!0},M=async(a,s={})=>{if(s.requireValidSyntax!==!1){const{validateSyntax:h}=await import("@visulima/email-verifier/checks/syntax");if(!h(a))throw new l("VALIDATION_ERROR",`@lunora/auth: "${a}" is not a valid email address.`)}const t=s.lists??{},e=t.disposable!==!1;await E({disposable:e,free:t.free!==!1});const o=w(a),i=e?A(a,s):{domain:o===void 0?void 0:m(o),emailClass:"business"};if(i.emailClass==="disposable"&&s.blockDisposable!==!1)throw new l("EMAIL_DOMAIN_BLOCKED",`@lunora/auth: signups from the disposable/throwaway domain "${i.domain??a}" are not allowed.`);if(s.mx===!0&&i.domain!==void 0&&!await C(i.domain))throw new l("EMAIL_UNDELIVERABLE",`@lunora/auth: the domain "${i.domain}" publishes no MX records, so mail to it cannot be delivered.`);return i},O=a=>async({ctx:s,next:t})=>{const e=a.email(s);if(e===void 0||e==="")throw new l("VALIDATION_ERROR","@lunora/auth: emailGateMiddleware received no email to check.");const o=a.onClassify!==void 0,i=await M(e,{...a,lists:{disposable:a.blockDisposable!==!1||o,free:o}});return a.onClassify?.(i,s),t()};export{M as assertEmailAllowed,A as classifyEmail,O as emailGateMiddleware,E as loadEmailDomainLists};