modelence 0.17.0-dev.0 → 0.17.0

package/dist/server.d.ts

@@ -1,8 +1,8 @@
 import { A as AppServer } from './index-CLpVWWuj.js';
-import { c as ConfigParams, C as ConfigSchema, A as AnyMethodShape, S as ServerChannel, V as ValueType, f as SignupProps, U as UpdateProfileProps, g as AuthSuccessProps, h as AuthErrorProps, i as User, j as OAuthErrorInfo, a as WebsocketServerProvider, R as RoleDefinition, M as MethodDefinition, b as ConfigKey, k as AppConfig, l as Session, m as UserInfo, n as Role } from './types-CTjq1HaP.js';
-export { d as ConfigType } from './types-CTjq1HaP.js';
-import { S as Store, R as RouteDefinition, C as CronJobInputParams, a as RateLimitRule, E as EmailProvider, I as InferDocumentType, b as RateLimitType, c as EmailPayload } from './types-DNZiaNSs.js';
-export { H as HttpMethod, d as RouteHandler, e as RouteParams, f as RouteResponse, s as schema } from './types-DNZiaNSs.js';
+import { c as ConfigParams, C as ConfigSchema, A as AnyMethodShape, S as ServerChannel, V as ValueType, f as SignupProps, U as UpdateProfileProps, g as AuthSuccessProps, h as AuthErrorProps, i as ConnectionInfo, j as User, k as OAuthErrorInfo, a as WebsocketServerProvider, R as RoleDefinition, M as MethodDefinition, b as ConfigKey, l as AppConfig, m as Session, n as UserInfo, o as Role } from './types-Ba-XOoJD.js';
+export { d as ConfigType } from './types-Ba-XOoJD.js';
+import { S as Store, R as RouteDefinition, C as CronJobInputParams, a as RateLimitRule, E as EmailProvider, b as RateLimitType, I as InferDocumentType, c as EmailPayload } from './types-BrUcinD0.js';
+export { H as HttpMethod, d as RouteHandler, e as RouteParams, f as RouteResponse, s as schema } from './types-BrUcinD0.js';
 import { ObjectId as ObjectId$1 } from 'mongodb';
 export { ObjectId } from 'mongodb';
 import * as zod from 'zod';
@@ -131,15 +131,66 @@ type EmailConfig = {
 };
 
 /**
- * Per-action rate limit overrides for authentication endpoints.
- * Every field is optional — omitting it keeps the built-in default.
+ * A single rate-limit rule for an authentication bucket. The `bucket` is
+ * implied by which auth action you're configuring (e.g. `signup`), so callers
+ * only specify the actor type, window size, and limit.
  *
  * @example
  * ```typescript
+ * import { time } from 'modelence/server';
+ *
+ * const rule: AuthRateLimitOverride = {
+ *   type: 'ip',
+ *   window: time.minutes(15),
+ *   limit: 10,
+ * };
+ * ```
+ */
+type AuthRateLimitOverride = {
+    /** Identifier type of the actor this rule applies to. */
+    type: RateLimitType;
+    /** Time window size in milliseconds. Use `time.minutes(15)` etc. */
+    window: number;
+    /** Maximum allowed hits within the window. */
+    limit: number;
+};
+/**
+ * Per-action rate limit overrides for authentication endpoints.
+ *
+ * Each bucket accepts an array of rules that are merged into the built-in
+ * defaults by `(type, window)` tuple:
+ *   - A rule whose `(type, window)` matches a default replaces that default's
+ *     `limit`.
+ *   - A rule whose `(type, window)` does not match any default is added as
+ *     an extra rule for the bucket.
+ *   - Defaults whose `(type, window)` is not overridden are kept.
+ *
+ * This means you can tighten a single window without accidentally dropping
+ * the other built-in protections for that bucket.
+ *
+ * @example Tighten the 15-minute signup cap; per-day default is preserved.
+ * ```typescript
+ * import { startApp, time } from 'modelence/server';
+ *
  * startApp({
  *   auth: {
  *     rateLimits: {
- *       signup: { perIp15Minutes: 5, perIpPerDay: 50 },
+ *       signup: [
+ *         { type: 'ip', window: time.minutes(15), limit: 5 },
+ *       ],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Add an extra window alongside the defaults.
+ * ```typescript
+ * startApp({
+ *   auth: {
+ *     rateLimits: {
+ *       signup: [
+ *         { type: 'ip', window: time.minutes(1), limit: 2 },
+ *       ],
  *     },
  *   },
  * });
@@ -147,50 +198,38 @@ type EmailConfig = {
  */
 type AuthRateLimitsConfig = {
     /** Per-IP limits for the signup endpoint (successful signups only). */
-    signup?: {
-        /** Max signups per IP in a 15-minute window. @default 20 */
-        perIp15Minutes?: number;
-        /** Max signups per IP per day. @default 200 */
-        perIpPerDay?: number;
-    };
+    signup?: AuthRateLimitOverride[];
     /** Per-IP limits for signup attempts (checked before duplicate detection). */
-    signupAttempt?: {
-        /** Max signup attempts per IP in a 15-minute window. @default 50 */
-        perIp15Minutes?: number;
-        /** Max signup attempts per IP per day. @default 500 */
-        perIpPerDay?: number;
-    };
+    signupAttempt?: AuthRateLimitOverride[];
     /** Per-IP limits for login attempts. */
-    signin?: {
-        /** Max login attempts per IP in a 15-minute window. @default 50 */
-        perIp15Minutes?: number;
-        /** Max login attempts per IP per day. @default 500 */
-        perIpPerDay?: number;
-    };
+    signin?: AuthRateLimitOverride[];
     /** Per-user limits for email verification requests. */
-    verification?: {
-        /** Max verification emails per user per minute. @default 1 */
-        perUserPerMinute?: number;
-        /** Max verification emails per user per day. @default 10 */
-        perUserPerDay?: number;
-    };
+    verification?: AuthRateLimitOverride[];
     /** Rate limits for password reset requests. */
-    passwordReset?: {
-        /** Max password reset requests per IP in a 15-minute window. @default 10 */
-        perIp15Minutes?: number;
-        /** Max password reset requests per IP per day. @default 100 */
-        perIpPerDay?: number;
-        /** Max password reset requests per email address per hour. @default 5 */
-        perEmailPerHour?: number;
-        /** Max password reset requests per email address per day. @default 10 */
-        perEmailPerDay?: number;
-    };
+    passwordReset?: AuthRateLimitOverride[];
 };
 type GenerateHandleProps = {
     email: string;
     firstName?: string;
     lastName?: string;
 };
+/**
+ * Props passed to {@link AuthConfig.onBeforeSignup}.
+ *
+ * The hook fires after validation and the built-in disposable-email check,
+ * but before the user document is inserted. Throwing aborts the signup —
+ * the thrown error is re-thrown to the caller and `onSignupError` fires.
+ */
+type BeforeSignupProps = {
+    /** Lowercased, validated email address. */
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    handle?: string;
+    /** Provider that initiated the signup. Currently only `'email'`. */
+    provider: 'email';
+    connectionInfo?: ConnectionInfo;
+};
 /**
  * Callback options for authentication operations
  */
@@ -240,20 +279,91 @@ type AuthOption = {
  * ```
  */
 type AuthConfig = {
+    /**
+     * Pre-signup validation hook. Runs before a new user is created during
+     * email/password signup, after format checks but before duplicate detection.
+     * Throw to reject the signup — the thrown message is surfaced to the client.
+     *
+     * Receives the raw signup payload (`email`, `password`, and optional
+     * `firstName`, `lastName`, `avatarUrl`, `handle`). May be async.
+     */
     validateSignup?: (props: SignupProps) => void | Promise<void>;
+    /**
+     * Pre-update validation hook. Runs before a user's profile fields
+     * (`firstName`, `lastName`, `avatarUrl`, `handle`) are written.
+     * Throw to reject the update — the thrown message is surfaced to the client.
+     * May be async.
+     */
     validateProfileUpdate?: (props: UpdateProfileProps) => void | Promise<void>;
+    /**
+     * Fires after a successful login (email/password or OAuth) once the session
+     * has been linked to the user. Receives `{ provider, user, session, connectionInfo }`.
+     * Use for analytics, audit logging, or post-login side effects.
+     */
     onAfterLogin?: (props: AuthSuccessProps) => void;
+    /**
+     * Fires when a login attempt fails. Receives `{ provider, error, session, connectionInfo }`.
+     * Use for failure analytics or alerting — does NOT change the response sent to the client.
+     */
     onLoginError?: (props: AuthErrorProps) => void;
+    /**
+     * Hook fired after validation and the built-in disposable-email check, but
+     * before the new user document is inserted. Throwing aborts the signup —
+     * the thrown error is re-thrown to the caller and `onSignupError` fires.
+     *
+     * Use this to plug in a custom domain-policy check (e.g. a tenant-specific
+     * email-domain verification service) without having to disable the built-in
+     * disposable-email check.
+     *
+     * Currently only invoked for `'email'` provider signups. OAuth signups are
+     * not gated because OAuth providers (Google, GitHub, etc.) do not issue
+     * disposable accounts.
+     */
+    onBeforeSignup?: (props: BeforeSignupProps) => void | Promise<void>;
+    /**
+     * Fires after a successful signup once the user record is created and the
+     * session is linked. Receives `{ provider, user, session, connectionInfo }`.
+     * Common uses: send welcome email, create default workspace, track activation.
+     */
     onAfterSignup?: (props: AuthSuccessProps) => void;
+    /**
+     * Fires when a signup attempt fails (validation, duplicate email, etc.).
+     * Receives `{ provider, error, session, connectionInfo }`.
+     * Use for failure analytics — does NOT change the response sent to the client.
+     */
     onSignupError?: (props: AuthErrorProps) => void;
+    /**
+     * Fires after a user's email is successfully verified (via the verification
+     * link or implicitly via password reset). Receives `{ provider, user, session, connectionInfo }`.
+     */
     onAfterEmailVerification?: (props: AuthSuccessProps) => void;
+    /**
+     * Fires when email verification fails (invalid or expired token).
+     * Receives `{ provider, error, session, connectionInfo }`.
+     */
     onEmailVerificationError?: (props: AuthErrorProps) => void;
+    /**
+     * Fires after an OAuth provider is linked to an existing account
+     * (either automatically when `oauthAccountLinking: 'auto'` or via an
+     * explicit link flow). Receives `{ provider, user, session, connectionInfo }`.
+     */
     onAfterOAuthLink?: (props: AuthSuccessProps) => void;
+    /**
+     * Fires when OAuth account linking fails. Receives
+     * `{ provider, error, session, connectionInfo }`.
+     */
     onOAuthLinkError?: (props: AuthErrorProps) => void;
+    /**
+     * Custom handle generator. If provided, overrides the default behavior
+     * (which derives the handle from the email local-part). Receives
+     * `{ email, firstName?, lastName? }` and returns the desired handle
+     * synchronously or as a `Promise<string>`. If the returned handle collides
+     * with an existing one, Modelence appends a numeric suffix automatically.
+     */
     generateHandle?: (props: GenerateHandleProps) => Promise<string> | string;
-    /** deprecated: use onAfterLogin and onLoginError */
+    /** @deprecated Use {@link AuthConfig.onAfterLogin} and {@link AuthConfig.onLoginError} instead. */
     login?: AuthOption;
-    /** deprecated: user onAfterSignup and onSignupError */
+    /** @deprecated Use {@link AuthConfig.onAfterSignup} and {@link AuthConfig.onSignupError} instead. */
     signup?: AuthOption;
     /**
      * Controls how OAuth providers handle existing accounts with matching email.
@@ -262,12 +372,36 @@ type AuthConfig = {
      *   if the provider email is verified.
      */
     oauthAccountLinking?: 'auto' | 'manual';
+    /**
+     * Customizes how OAuth authentication errors are rendered. By default,
+     * OAuth errors are returned as JSON; providing this returns a custom HTML
+     * response instead, which is useful when the OAuth flow runs in a browser
+     * context. Receives `{ error, statusCode }` and returns an HTML string
+     * (or `null`/`undefined` to fall back to the default JSON response).
+     *
+     * Always escape interpolated values to prevent XSS.
+     */
     errorComponent?: (props: OAuthErrorInfo) => string | null | undefined;
     /**
-     * Overrides the built-in rate limits for authentication endpoints.
-     * Only the fields you specify are overridden; all others keep their defaults.
+     * Overrides the built-in rate limits for authentication endpoints. Each rule
+     * you provide is merged into the defaults by `(bucket, type, window)`:
+     * matching tuples replace the default `limit`, new tuples are added, and
+     * unspecified defaults are preserved. See {@link AuthRateLimitsConfig} for
+     * full semantics and examples.
      */
     rateLimits?: AuthRateLimitsConfig;
+    /**
+     * When `true`, the built-in disposable-email check is skipped during signup.
+     * Defaults to `false` (built-in check enforced).
+     *
+     * Set this to `true` when you want to enforce your own domain-policy logic
+     * via {@link onBeforeSignup} — for example, a service that classifies
+     * domains as public/disposable/custom with its own data sources and cache.
+     *
+     * Skipping the built-in check without registering an `onBeforeSignup` hook
+     * means disposable emails will be allowed to sign up.
+     */
+    allowDisposableEmails?: boolean;
 };
 
 /**
@@ -784,4 +918,4 @@ declare function deleteFile(filePath: string): Promise<void>;
 declare function downloadFile(filePath: string): Promise<DownloadFileResult>;
 declare function getFileUrl(filePath: string): Promise<GetFileUrlResult>;
 
-export { type AppOptions, type AuthConfig, type AuthOption, type AuthRateLimitsConfig, type CloudBackendConnectResponse, ConfigSchema, CronJobInputParams, FileVisibility, LiveData, type LiveDataConfig, type LiveQueryCleanup, type LiveQueryPublish, type LiveQueryWatch, Module, RateLimitRule, RateLimitType, RoleDefinition, RouteDefinition, type SecurityConfig, ServerChannel, Store, UserInfo, ValueType, authenticate, consumeRateLimit, createQuery, usersCollection as dbUsers, deleteFile, deleteUser, disableUser, downloadFile, getConfig, getFileUrl, getUploadUrl, sendEmail, startApp };
+export { type AppOptions, type AuthConfig, type AuthOption, type AuthRateLimitOverride, type AuthRateLimitsConfig, type CloudBackendConnectResponse, ConfigSchema, CronJobInputParams, FileVisibility, LiveData, type LiveDataConfig, type LiveQueryCleanup, type LiveQueryPublish, type LiveQueryWatch, Module, RateLimitRule, RateLimitType, RoleDefinition, RouteDefinition, type SecurityConfig, ServerChannel, Store, UserInfo, ValueType, authenticate, consumeRateLimit, createQuery, usersCollection as dbUsers, deleteFile, deleteUser, disableUser, downloadFile, getConfig, getFileUrl, getUploadUrl, sendEmail, startApp };