@gatwech/auth 1.0.0-beta.18 → 1.0.0-beta.19

package/dist/src/plugins/sentinel/index.d.ts

@@ -0,0 +1,326 @@
+import type { AuthContext, GenericEndpointContext } from "@gatwech/core";
+import type { User } from "../../types";
+import { SENTINEL_ERROR_CODES } from "./actions";
+import { schema } from "./schema";
+import type { GeoLocation, SecurityAction, SentinelOptions } from "./types";
+export { normalizeEmail } from "./email";
+export { haversineDistanceKm } from "./geo";
+export * from "./pow";
+export type * from "./types";
+export { SENTINEL_ERROR_CODES };
+export declare const sentinel: (options?: SentinelOptions | undefined) => {
+    id: "sentinel";
+    init(ctx: AuthContext<import("@gatwech/core").PayvoAuthOptions>): {
+        options: {
+            databaseHooks: {
+                user: {
+                    create: {
+                        before(user: {
+                            id: string;
+                            createdAt: Date;
+                            updatedAt: Date;
+                            email: string;
+                            emailVerified: boolean;
+                            name: string;
+                            image?: string | null | undefined;
+                        } & Record<string, unknown>, context: GenericEndpointContext<import("@gatwech/core").PayvoAuthOptions> | undefined): Promise<{
+                            data: {
+                                normalizedEmail: string;
+                                id: string;
+                                createdAt: Date;
+                                updatedAt: Date;
+                                email: string;
+                                emailVerified: boolean;
+                                name: string;
+                                image?: string | null | undefined;
+                            };
+                        } | undefined>;
+                        after(user: {
+                            id: string;
+                            createdAt: Date;
+                            updatedAt: Date;
+                            email: string;
+                            emailVerified: boolean;
+                            name: string;
+                            image?: string | null | undefined;
+                        } & Record<string, unknown>, context: GenericEndpointContext<import("@gatwech/core").PayvoAuthOptions> | undefined): Promise<void>;
+                    };
+                    update: {
+                        before(data: Partial<{
+                            id: string;
+                            createdAt: Date;
+                            updatedAt: Date;
+                            email: string;
+                            emailVerified: boolean;
+                            name: string;
+                            image?: string | null | undefined;
+                        }> & Record<string, unknown>): Promise<{
+                            data: {
+                                normalizedEmail: string;
+                                id?: string | undefined;
+                                createdAt?: Date | undefined;
+                                updatedAt?: Date | undefined;
+                                email?: string | undefined;
+                                emailVerified?: boolean | undefined;
+                                name?: string | undefined;
+                                image?: string | null | undefined;
+                            };
+                        } | undefined>;
+                    };
+                };
+            };
+        };
+    } | undefined;
+    onRequest(request: Request, ctx: AuthContext<import("@gatwech/core").PayvoAuthOptions>): Promise<{
+        response: Response;
+    } | undefined>;
+    hooks: {
+        before: ({
+            matcher(context: import("@gatwech/core").HookEndpointContext): boolean;
+            handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<{
+                context: {
+                    body: any;
+                };
+            } | undefined>;
+        } | {
+            matcher(context: import("@gatwech/core").HookEndpointContext): boolean;
+            handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>;
+        })[];
+        after: ({
+            matcher(context: import("@gatwech/core").HookEndpointContext): boolean;
+            handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>;
+        } | {
+            matcher(context: import("@gatwech/core").HookEndpointContext): boolean;
+            handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<({
+                status: ("OK" | "CREATED" | "ACCEPTED" | "NO_CONTENT" | "MULTIPLE_CHOICES" | "MOVED_PERMANENTLY" | "FOUND" | "SEE_OTHER" | "NOT_MODIFIED" | "TEMPORARY_REDIRECT" | "BAD_REQUEST" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "PROXY_AUTHENTICATION_REQUIRED" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "LENGTH_REQUIRED" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "URI_TOO_LONG" | "UNSUPPORTED_MEDIA_TYPE" | "RANGE_NOT_SATISFIABLE" | "EXPECTATION_FAILED" | "I'M_A_TEAPOT" | "MISDIRECTED_REQUEST" | "UNPROCESSABLE_ENTITY" | "LOCKED" | "FAILED_DEPENDENCY" | "TOO_EARLY" | "UPGRADE_REQUIRED" | "PRECONDITION_REQUIRED" | "TOO_MANY_REQUESTS" | "REQUEST_HEADER_FIELDS_TOO_LARGE" | "UNAVAILABLE_FOR_LEGAL_REASONS" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "HTTP_VERSION_NOT_SUPPORTED" | "VARIANT_ALSO_NEGOTIATES" | "INSUFFICIENT_STORAGE" | "LOOP_DETECTED" | "NOT_EXTENDED" | "NETWORK_AUTHENTICATION_REQUIRED") | import("better-call").Status;
+                body: ({
+                    message?: string;
+                    code?: string;
+                    cause?: unknown;
+                } & Record<string, any>) | undefined;
+                headers: HeadersInit;
+                statusCode: number;
+                name: string;
+                message: string;
+                stack?: string;
+                cause?: unknown;
+            } & {
+                errorStack: string | undefined;
+            }) | undefined>;
+        })[];
+    };
+    schema: {
+        sentinelCounter: {
+            fields: {
+                key: {
+                    type: "string";
+                    required: true;
+                    unique: true;
+                };
+                count: {
+                    type: "number";
+                    required: true;
+                };
+                expiresAt: {
+                    type: "date";
+                    required: true;
+                };
+            };
+        };
+        sentinelSignIn: {
+            fields: {
+                userId: {
+                    type: "string";
+                    required: true;
+                    references: {
+                        model: string;
+                        field: string;
+                        onDelete: "cascade";
+                    };
+                };
+                ipAddress: {
+                    type: "string";
+                    required: false;
+                };
+                visitorId: {
+                    type: "string";
+                    required: false;
+                };
+                userAgent: {
+                    type: "string";
+                    required: false;
+                };
+                country: {
+                    type: "string";
+                    required: false;
+                };
+                city: {
+                    type: "string";
+                    required: false;
+                };
+                latitude: {
+                    type: "number";
+                    required: false;
+                };
+                longitude: {
+                    type: "number";
+                    required: false;
+                };
+                createdAt: {
+                    type: "date";
+                    required: true;
+                };
+            };
+        };
+        powChallenge: {
+            fields: {
+                nonce: {
+                    type: "string";
+                    required: true;
+                    unique: true;
+                };
+                difficulty: {
+                    type: "number";
+                    required: true;
+                };
+                reason: {
+                    type: "string";
+                    required: true;
+                };
+                ipAddress: {
+                    type: "string";
+                    required: false;
+                };
+                visitorId: {
+                    type: "string";
+                    required: false;
+                };
+                expiresAt: {
+                    type: "date";
+                    required: true;
+                };
+                createdAt: {
+                    type: "date";
+                    required: true;
+                };
+            };
+        };
+    };
+    $ERROR_CODES: {
+        readonly POW_CHALLENGE_REQUIRED: "Challenge required";
+        readonly SECURITY_BLOCKED: "Request blocked for security reasons";
+    };
+    options: {
+        failOpen: boolean;
+        apiUrl?: string | undefined;
+        apiKey?: string | undefined;
+        kvUrl?: string | undefined;
+        kvOptions?: {
+            timeout?: number | undefined;
+            retry?: {
+                attempts?: number | undefined;
+                baseDelay?: number | undefined;
+                maxDelay?: number | undefined;
+            } | undefined;
+            headers?: Record<string, string> | undefined;
+        } | undefined;
+        apiOptions?: {
+            timeout?: number | undefined;
+            headers?: Record<string, string> | undefined;
+        } | undefined;
+        providers?: {
+            getClientIp?: ((request: Request | Headers) => string | null) | undefined;
+            isSuspiciousIp?: ((ip: string) => boolean | Promise<boolean>) | undefined;
+            isBot?: ((request: Request) => boolean | Promise<boolean>) | undefined;
+            resolveGeo?: ((ip: string) => GeoLocation | null | Promise<GeoLocation | null>) | undefined;
+        } | undefined;
+        sendNotification?: ((notification: {
+            type: "unknown-device" | "stale-account";
+            recipient: "user" | "admin";
+            email: string;
+            user: User;
+            signIn: {
+                at: Date;
+                ipAddress: string | null;
+                userAgent: string | null;
+                location: string | null;
+            };
+            daysInactive?: number | undefined;
+        }) => void | Promise<void>) | undefined;
+        security?: {
+            credentialStuffing?: {
+                enabled: boolean;
+                action?: SecurityAction | undefined;
+                thresholds?: {
+                    challenge: number;
+                    block: number;
+                } | undefined;
+                windowSeconds?: number | undefined;
+                cooldownSeconds?: number | undefined;
+            } | undefined;
+            velocity?: {
+                enabled: boolean;
+                thresholds?: {
+                    challenge: number;
+                    block: number;
+                } | undefined;
+                maxSignupsPerVisitor?: number | undefined;
+                maxPasswordResetsPerIp?: number | undefined;
+                maxSignInsPerIp?: number | undefined;
+                windowSeconds?: number | undefined;
+                action?: SecurityAction | undefined;
+            } | undefined;
+            freeTrialAbuse?: {
+                enabled: boolean;
+                thresholds?: {
+                    challenge: number;
+                    block: number;
+                } | undefined;
+                maxAccountsPerVisitor?: number | undefined;
+                retentionSeconds?: number | undefined;
+                action?: SecurityAction | undefined;
+            } | undefined;
+            botBlocking?: (boolean | {
+                action: SecurityAction;
+            }) | undefined;
+            suspiciousIpBlocking?: (boolean | {
+                action: SecurityAction;
+            }) | undefined;
+            unknownDeviceNotification?: boolean | undefined;
+            impossibleTravel?: {
+                enabled: boolean;
+                maxSpeedKmh?: number | undefined;
+                action?: SecurityAction | undefined;
+            } | undefined;
+            geoBlocking?: {
+                allowList?: string[] | undefined;
+                denyList?: string[] | undefined;
+                action?: Exclude<SecurityAction, "log"> | undefined;
+            } | undefined;
+            compromisedPassword?: {
+                enabled: boolean;
+                action?: SecurityAction | undefined;
+                minBreachCount?: number | undefined;
+            } | undefined;
+            emailValidation?: {
+                enabled: boolean;
+                strictness?: ("low" | "medium" | "high") | undefined;
+                action?: SecurityAction | undefined;
+                domainAllowlist?: string[] | undefined;
+            } | undefined;
+            emailNormalization?: {
+                enabled?: boolean | undefined;
+            } | undefined;
+            staleUsers?: {
+                enabled: boolean;
+                staleDays?: number | undefined;
+                action?: SecurityAction | undefined;
+                notifyUser?: boolean | undefined;
+                notifyAdmin?: boolean | undefined;
+                adminEmail?: string | undefined;
+            } | undefined;
+            challengeDifficulty?: number | undefined;
+        } | undefined;
+        schema?: import("..").InferOptionSchema<typeof schema> | undefined;
+    };
+};

package/dist/src/plugins/sentinel/intel.d.ts

@@ -0,0 +1,45 @@
+import type { AuthContext } from "@gatwech/core";
+import type { GeoLocation, SentinelOptions } from "./types";
+/**
+ * Local bot heuristics, used when neither a provider nor the hosted backend
+ * gives a verdict
+ */
+export declare function looksLikeBot(request: Request): boolean;
+type RequestIntel = {
+    suspiciousIp: boolean | null;
+    bot: boolean | null;
+    geo: GeoLocation | null;
+};
+/**
+ * Asks the hosted backend about a request's IP address and client. Verdicts
+ * are cached in secondary storage for as long as the backend allows.
+ * Returns null verdicts when the backend isn't configured or can't answer.
+ */
+export declare function createIntelClient(options: SentinelOptions): {
+    configured: boolean;
+    /** Visitor ids are checked with the identification service */
+    verifiesVisitors: boolean;
+    /**
+     * A backend URL is set without a key, or a key without a URL, so
+     * checks that need the backend fall back to allow mode
+     */
+    misconfigured: boolean;
+    /**
+     * Checks a client-sent visitor id with the identification service.
+     * Returns the canonical visitor id (or the one sent, when no
+     * identification service is configured), null when it isn't genuine, or
+     * undefined when the check failed.
+     */
+    verifyVisitor(auth: AuthContext, request: {
+        visitorId: string;
+        ip: string | null;
+        userAgent: string | null;
+    }): Promise<string | null | undefined>;
+    lookup(auth: AuthContext, request: {
+        ip: string | null;
+        visitorId: string | null;
+        userAgent: string | null;
+        acceptLanguage: string | null;
+    }): Promise<RequestIntel>;
+};
+export {};

package/dist/src/plugins/sentinel/pow.d.ts

@@ -0,0 +1,21 @@
+export declare const POW_CHALLENGE_HEADER = "x-pow-challenge";
+export declare const POW_REASON_HEADER = "x-pow-reason";
+export declare const POW_SOLUTION_HEADER = "x-pow-solution";
+export declare function createNonce(): string;
+/** Whether a hash starts with at least `difficulty` zero bits */
+export declare function hasLeadingZeroBits(hash: Uint8Array, difficulty: number): boolean;
+/**
+ * Whether `sha256("<nonce>:<solution>")` has at least `difficulty` leading
+ * zero bits
+ */
+export declare function verifySolution(nonce: string, solution: string, difficulty: number): Promise<boolean>;
+/**
+ * Find a solution for a challenge by trying incrementing counters. Yields to
+ * the event loop between batches, so solving doesn't block the page.
+ */
+export declare function solveChallenge(nonce: string, difficulty: number): Promise<string>;
+/** Parses `<nonce>:<value>` header values */
+export declare function parsePowHeader(value: string | null | undefined): {
+    nonce: string;
+    value: string;
+} | null;

package/dist/src/plugins/sentinel/schema.d.ts

@@ -0,0 +1,110 @@
+/** Added to users when `emailNormalization` is enabled */
+export declare const normalizedEmailSchema: {
+    user: {
+        fields: {
+            normalizedEmail: {
+                type: "string";
+                required: false;
+                input: false;
+                returned: false;
+            };
+        };
+    };
+};
+export declare const schema: {
+    sentinelCounter: {
+        fields: {
+            key: {
+                type: "string";
+                required: true;
+                unique: true;
+            };
+            count: {
+                type: "number";
+                required: true;
+            };
+            expiresAt: {
+                type: "date";
+                required: true;
+            };
+        };
+    };
+    sentinelSignIn: {
+        fields: {
+            userId: {
+                type: "string";
+                required: true;
+                references: {
+                    model: string;
+                    field: string;
+                    onDelete: "cascade";
+                };
+            };
+            ipAddress: {
+                type: "string";
+                required: false;
+            };
+            visitorId: {
+                type: "string";
+                required: false;
+            };
+            userAgent: {
+                type: "string";
+                required: false;
+            };
+            country: {
+                type: "string";
+                required: false;
+            };
+            city: {
+                type: "string";
+                required: false;
+            };
+            latitude: {
+                type: "number";
+                required: false;
+            };
+            longitude: {
+                type: "number";
+                required: false;
+            };
+            createdAt: {
+                type: "date";
+                required: true;
+            };
+        };
+    };
+    powChallenge: {
+        fields: {
+            nonce: {
+                type: "string";
+                required: true;
+                unique: true;
+            };
+            difficulty: {
+                type: "number";
+                required: true;
+            };
+            reason: {
+                type: "string";
+                required: true;
+            };
+            ipAddress: {
+                type: "string";
+                required: false;
+            };
+            visitorId: {
+                type: "string";
+                required: false;
+            };
+            expiresAt: {
+                type: "date";
+                required: true;
+            };
+            createdAt: {
+                type: "date";
+                required: true;
+            };
+        };
+    };
+};

package/dist/src/plugins/sentinel/store.d.ts

@@ -0,0 +1,37 @@
+import type { AuthContext } from "@gatwech/core";
+type StoredChallenge = {
+    nonce: string;
+    difficulty: number;
+    reason: string;
+    ipAddress: string | null;
+    visitorId: string | null;
+    expiresAt: Date;
+};
+/**
+ * Counters and challenges, kept in secondary storage when it's configured
+ * and in the database otherwise
+ */
+export declare function createSentinelStore(auth: AuthContext): {
+    /**
+     * Increments a counter that expires a fixed window after it was created,
+     * and returns the new count
+     */
+    increment(name: string, ttlSeconds: number, options?: {
+        /**
+         * Restart the expiry on every increment instead of keeping a fixed
+         * window
+         */
+        sliding?: boolean;
+    }): Promise<number>;
+    /** Returns a counter's current value, or 0 when it's missing or expired */
+    get(name: string): Promise<number>;
+    reset(name: string): Promise<void>;
+    saveChallenge(challenge: StoredChallenge): Promise<void>;
+    /**
+     * Returns a challenge and removes it, so it can only be used once.
+     * Returns null when it doesn't exist, was already used or expired.
+     */
+    consumeChallenge(nonce: string): Promise<StoredChallenge | null>;
+};
+export type SentinelStore = ReturnType<typeof createSentinelStore>;
+export {};