@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/dist/auth/methods.d.ts

@@ -0,0 +1,717 @@
+/** Sign-in methods to Better Auth options: providers, email plugins, the bootstrap owner rule, trusted origins, paths and cookies. */
+import { oauthProvider } from "@better-auth/oauth-provider";
+import type { BetterAuthOptions } from "better-auth";
+import { type GenericOAuthConfig } from "better-auth/plugins";
+import type { AuthMethodConfig, BootstrapOwnerRule, OAuthProviderConfig } from "./types.js";
+export declare function normalizeAuthBasePath(basePath: string | undefined): string;
+/** @internal exported for unit tests; not part of the public API. */
+export declare function resolveClientIpHeaders(headers: ReadonlyArray<string> | undefined): readonly string[];
+export declare function normalizeAuthErrorURL(errorURL: string | undefined, baseURL: string): string;
+export declare function normalizeAuthResponseCookies(response: Response): Response;
+export declare function buildSocialProviders(methods: ReadonlyArray<AuthMethodConfig>): BetterAuthOptions["socialProviders"];
+export declare function buildGenericOAuthProviders(methods: ReadonlyArray<AuthMethodConfig>): GenericOAuthConfig[];
+/**
+ * First tag off `Accept-Language`, quality values ignored. Locale
+ * contract lives in `EmailSender.ts`.
+ */
+export declare function pickLocale(req: Request | undefined, fallback: string): string;
+export declare function buildMagicLinkPlugin(method: Extract<AuthMethodConfig, {
+    kind: "magic-link";
+}>): {
+    id: "magic-link";
+    version: string;
+    endpoints: {
+        signInMagicLink: import("better-auth").StrictEndpoint<"/sign-in/magic-link", {
+            method: "POST";
+            requireHeaders: true;
+            use: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>[];
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodEmail;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                callbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+                newUserCallbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+                errorCallbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+                metadata: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodAny>>;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            status: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            status: boolean;
+        }>;
+        magicLinkVerify: import("better-auth").StrictEndpoint<"/magic-link/verify", {
+            method: "GET";
+            query: import("zod").ZodObject<{
+                token: import("zod").ZodString;
+                callbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+                errorCallbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+                newUserCallbackURL: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>;
+            use: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>[];
+            requireHeaders: true;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            session: {
+                                                $ref: string;
+                                            };
+                                            user: {
+                                                $ref: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            token: string;
+            user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+            };
+            session: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                userId: string;
+                expiresAt: Date;
+                token: string;
+                ipAddress?: string | null | undefined;
+                userAgent?: string | null | undefined;
+            };
+        }>;
+    };
+    rateLimit: {
+        pathMatcher(path: string): boolean;
+        window: number;
+        max: number;
+    }[];
+    options: import("better-auth/plugins").MagicLinkOptions;
+};
+export declare function buildEmailOTPPlugin(method: Extract<AuthMethodConfig, {
+    kind: "email-otp";
+}>, secret: string): {
+    id: "email-otp";
+    version: string;
+    init(ctx: import("better-auth").AuthContext): {
+        options: {
+            emailVerification: {
+                sendVerificationEmail(data: {
+                    user: import("better-auth").User;
+                    url: string;
+                    token: string;
+                }, request: Request | undefined): Promise<void>;
+            };
+        };
+    } | undefined;
+    endpoints: {
+        sendVerificationOTP: import("better-auth").StrictEndpoint<"/email-otp/send-verification-otp", {
+            method: "POST";
+            use: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>[];
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                type: import("zod").ZodEnum<{
+                    "sign-in": "sign-in";
+                    "change-email": "change-email";
+                    "email-verification": "email-verification";
+                    "forget-password": "forget-password";
+                }>;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        createVerificationOTP: import("better-auth").StrictEndpoint<string, {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                type: import("zod").ZodEnum<{
+                    "sign-in": "sign-in";
+                    "change-email": "change-email";
+                    "email-verification": "email-verification";
+                    "forget-password": "forget-password";
+                }>;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "string";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, string>;
+        getVerificationOTP: import("better-auth").StrictEndpoint<string, {
+            method: "GET";
+            query: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                type: import("zod").ZodEnum<{
+                    "sign-in": "sign-in";
+                    "change-email": "change-email";
+                    "email-verification": "email-verification";
+                    "forget-password": "forget-password";
+                }>;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        "200": {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            otp: {
+                                                type: string;
+                                                nullable: boolean;
+                                                description: string;
+                                            };
+                                        };
+                                        required: string[];
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            otp: null;
+        } | {
+            otp: string;
+        }>;
+        checkVerificationOTP: import("better-auth").StrictEndpoint<"/email-otp/check-verification-otp", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                type: import("zod").ZodEnum<{
+                    "sign-in": "sign-in";
+                    "change-email": "change-email";
+                    "email-verification": "email-verification";
+                    "forget-password": "forget-password";
+                }>;
+                otp: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        verifyEmailOTP: import("better-auth").StrictEndpoint<"/email-otp/verify-email", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                otp: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            status: {
+                                                type: string;
+                                                description: string;
+                                                enum: boolean[];
+                                            };
+                                            token: {
+                                                type: string;
+                                                nullable: boolean;
+                                                description: string;
+                                            };
+                                            user: {
+                                                $ref: string;
+                                            };
+                                        };
+                                        required: string[];
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            status: boolean;
+            token: string;
+            user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+            } & Record<string, any>;
+        } | {
+            status: boolean;
+            token: null;
+            user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+            } & Record<string, any>;
+        }>;
+        signInEmailOTP: import("better-auth").StrictEndpoint<"/sign-in/email-otp", {
+            method: "POST";
+            body: import("zod").ZodIntersection<import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                otp: import("zod").ZodString;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                image: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodAny>>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            token: {
+                                                type: string;
+                                                description: string;
+                                            };
+                                            user: {
+                                                $ref: string;
+                                            };
+                                        };
+                                        required: string[];
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            token: string;
+            user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+            };
+        }>;
+        requestPasswordResetEmailOTP: import("better-auth").StrictEndpoint<"/email-otp/request-password-reset", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                                description: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        forgetPasswordEmailOTP: import("better-auth").StrictEndpoint<"/forget-password/email-otp", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                                description: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        resetPasswordEmailOTP: import("better-auth").StrictEndpoint<"/email-otp/reset-password", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                email: import("zod").ZodString;
+                otp: import("zod").ZodString;
+                password: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        requestEmailChangeEmailOTP: import("better-auth").StrictEndpoint<"/email-otp/request-email-change", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                newEmail: import("zod").ZodString;
+                otp: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>;
+            use: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+                session: {
+                    session: Record<string, any> & {
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        userId: string;
+                        expiresAt: Date;
+                        token: string;
+                        ipAddress?: string | null | undefined;
+                        userAgent?: string | null | undefined;
+                    };
+                    user: Record<string, any> & {
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        email: string;
+                        emailVerified: boolean;
+                        name: string;
+                        image?: string | null | undefined;
+                    };
+                };
+            }>>[];
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+        changeEmailEmailOTP: import("better-auth").StrictEndpoint<"/email-otp/change-email", {
+            method: "POST";
+            body: import("zod").ZodObject<{
+                newEmail: import("zod").ZodString;
+                otp: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            use: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+                session: {
+                    session: Record<string, any> & {
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        userId: string;
+                        expiresAt: Date;
+                        token: string;
+                        ipAddress?: string | null | undefined;
+                        userAgent?: string | null | undefined;
+                    };
+                    user: Record<string, any> & {
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        email: string;
+                        emailVerified: boolean;
+                        name: string;
+                        image?: string | null | undefined;
+                    };
+                };
+            }>>[];
+            metadata: {
+                openapi: {
+                    operationId: string;
+                    description: string;
+                    responses: {
+                        200: {
+                            description: string;
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object";
+                                        properties: {
+                                            success: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        }, {
+            success: boolean;
+        }>;
+    };
+    hooks: {
+        after: {
+            matcher(context: import("better-auth").HookEndpointContext): boolean;
+            handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+        }[];
+    };
+    rateLimit: ({
+        pathMatcher(path: string): path is "/email-otp/send-verification-otp";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/check-verification-otp";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/verify-email";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/sign-in/email-otp";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/request-password-reset";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/reset-password";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/forget-password/email-otp";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/request-email-change";
+        window: number;
+        max: number;
+    } | {
+        pathMatcher(path: string): path is "/email-otp/change-email";
+        window: number;
+        max: number;
+    })[];
+    options: import("better-auth/plugins").EmailOTPOptions;
+    $ERROR_CODES: {
+        OTP_EXPIRED: import("better-auth").RawError<"OTP_EXPIRED">;
+        INVALID_OTP: import("better-auth").RawError<"INVALID_OTP">;
+        TOO_MANY_ATTEMPTS: import("better-auth").RawError<"TOO_MANY_ATTEMPTS">;
+    };
+};
+/** Exported for the adapters' unit tests; not part of the supported API. */
+export declare function hasEmailAuthSurface(methods: ReadonlyArray<AuthMethodConfig>, plugins?: ReadonlyArray<{
+    readonly id: string;
+}>): boolean;
+/** HMAC-SHA-256(secret, otp) as unpadded base64url. Exported for tests only. */
+export declare function hashEmailOtp(secret: string, otp: string): Promise<string>;
+/**
+ * Cross-check bootstrap rule against registered methods. Catches the
+ * silent-no-op case where the rule's discriminator can never match
+ * any signal a registered method actually produces — e.g.
+ * `match: "github-login"` with no `github` provider registered. Throws
+ * at construction so vibe-coders see the mistake before the first
+ * sign-in attempt.
+ *
+ * `match: "email"` is permissive — every Better Auth method that
+ * creates a user populates `email`, including GitHub (via the
+ * upstream profile). No registration constraint to enforce.
+ */
+export declare function validateBootstrap(rule: BootstrapOwnerRule, methods: ReadonlyArray<AuthMethodConfig>): void;
+export declare function shouldPromoteToOwner(rule: BootstrapOwnerRule, user: {
+    readonly email?: string | null;
+    readonly githubLogin?: string | null;
+}): boolean;
+export type AuthHookContext = {
+    readonly path: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+} | null;
+/** Keep provider-owned GitHub logins off user-controlled auth paths. */
+export declare function guardGithubLoginProfile(user: Readonly<Record<string, unknown>>, context: AuthHookContext, methods: ReadonlyArray<AuthMethodConfig>): {
+    readonly data: {
+        readonly githubLogin: null;
+    };
+} | undefined;
+/**
+ * Find the at-most-one method of `kind`. Throws when adopters register
+ * the same kind twice — Better Auth's plugin layer accepts duplicates
+ * silently, which would mask the intent at boot. One helper covers
+ * every singleton-shaped method (email-otp, magic-link, future ones).
+ */
+export declare function pickSingleton<K extends AuthMethodConfig["kind"]>(methods: ReadonlyArray<AuthMethodConfig>, kind: K): Extract<AuthMethodConfig, {
+    kind: K;
+}> | undefined;
+export declare function buildTrustedOriginsFor(methods: ReadonlyArray<AuthMethodConfig>, configured?: ReadonlyArray<string>): string[];
+/**
+ * Apple uses `response_mode=form_post` — Apple POSTs cross-site to
+ * our callback. The OAuth state cookie must have `sameSite: "none"`
+ * (and `secure: true`, which browsers require alongside) or the
+ * cookie won't ride the POST and Better Auth raises a state mismatch.
+ * Other providers don't need this. We only auto-set when Apple is
+ * registered AND the adopter hasn't already specified
+ * `defaultCookieAttributes.sameSite` themselves.
+ */
+export declare function methodsRequireSameSiteNone(methods: ReadonlyArray<AuthMethodConfig>): boolean;
+export declare function buildOAuthProviderOptions(config: OAuthProviderConfig): Parameters<typeof oauthProvider>[0];
+//# sourceMappingURL=methods.d.ts.map