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

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

@@ -0,0 +1,412 @@
+import type { User } from "../../types";
+import type { InferOptionSchema } from "../../types/plugins";
+import type { schema } from "./schema";
+/**
+ * The action to take when a security check fails
+ *
+ * - `log`: record the event and let the request through
+ * - `challenge`: respond with `423` and a proof-of-work challenge
+ * - `block`: respond with `403`
+ */
+export type SecurityAction = "log" | "challenge" | "block";
+export type GeoLocation = {
+    /**
+     * ISO 3166-1 alpha-2 country code, e.g. "US"
+     */
+    country: string | null;
+    city?: string | null | undefined;
+    latitude?: number | null | undefined;
+    longitude?: number | null | undefined;
+};
+export interface SentinelOptions {
+    /**
+     * The hosted backend API URL
+     *
+     * @default process.env.PAYVO_INFRA_API_URL
+     */
+    apiUrl?: string | undefined;
+    /**
+     * The hosted backend API key
+     *
+     * @default process.env.PAYVO_INFRA_API_KEY
+     */
+    apiKey?: string | undefined;
+    /**
+     * The hosted identification service URL, used to check that visitor ids
+     * sent by clients are genuine
+     *
+     * @default process.env.PAYVO_INFRA_KV_URL
+     */
+    kvUrl?: string | undefined;
+    /**
+     * Identification service HTTP options
+     */
+    kvOptions?: {
+        /**
+         * Request timeout in milliseconds
+         *
+         * @default 1000
+         */
+        timeout?: number | undefined;
+        /**
+         * Retries after a failed request, with exponential backoff
+         *
+         * @default { attempts: 2, baseDelay: 400, maxDelay: 600 }
+         */
+        retry?: {
+            attempts?: number | undefined;
+            baseDelay?: number | undefined;
+            maxDelay?: number | undefined;
+        } | undefined;
+        /**
+         * Additional headers sent with every request
+         */
+        headers?: Record<string, string> | undefined;
+    } | undefined;
+    /**
+     * Hosted backend HTTP options
+     */
+    apiOptions?: {
+        /**
+         * Request timeout in milliseconds
+         *
+         * @default 3000
+         */
+        timeout?: number | undefined;
+        /**
+         * Additional headers sent with every request
+         */
+        headers?: Record<string, string> | undefined;
+    } | undefined;
+    /**
+     * Allow requests through when a check can't complete, e.g. the hosted
+     * backend or secondary storage is unavailable
+     *
+     * @default true
+     */
+    failOpen?: boolean | undefined;
+    /**
+     * Local providers that replace the hosted backend
+     */
+    providers?: {
+        /**
+         * Resolve the client IP of a request
+         *
+         * By default the IP is read from the configured IP address headers
+         */
+        getClientIp?: ((request: Request | Headers) => string | null) | undefined;
+        /**
+         * Whether an IP address is known to be malicious
+         */
+        isSuspiciousIp?: ((ip: string) => boolean | Promise<boolean>) | undefined;
+        /**
+         * Whether a request comes from an automated client
+         */
+        isBot?: ((request: Request) => boolean | Promise<boolean>) | undefined;
+        /**
+         * Resolve the location of an IP address
+         */
+        resolveGeo?: ((ip: string) => GeoLocation | null | Promise<GeoLocation | null>) | undefined;
+    } | undefined;
+    /**
+     * Send a security notification, e.g. by email. Required for
+     * `unknownDeviceNotification` and the stale account notifications.
+     */
+    sendNotification?: ((notification: {
+        type: "unknown-device" | "stale-account";
+        /**
+         * Who the notification is for
+         */
+        recipient: "user" | "admin";
+        /**
+         * The address to send the notification to
+         */
+        email: string;
+        user: User;
+        signIn: {
+            at: Date;
+            ipAddress: string | null;
+            userAgent: string | null;
+            /**
+             * City and country, when known, e.g. "Berlin, DE"
+             */
+            location: string | null;
+        };
+        /**
+         * Days since the account was last active, for stale accounts
+         */
+        daysInactive?: number | undefined;
+    }) => void | Promise<void>) | undefined;
+    security?: {
+        /**
+         * Detect credential stuffing by tracking failed sign-in attempts per
+         * visitor, falling back to the IP address
+         */
+        credentialStuffing?: {
+            enabled: boolean;
+            /**
+             * Set to `log` to only record attempts. Otherwise the thresholds
+             * decide between a challenge and a block.
+             *
+             * @default "challenge"
+             */
+            action?: SecurityAction | undefined;
+            /**
+             * Number of failed attempts before a challenge or a block
+             *
+             * @default { challenge: 3, block: 5 }
+             */
+            thresholds?: {
+                challenge: number;
+                block: number;
+            } | undefined;
+            /**
+             * Window in seconds in which failed attempts are counted
+             *
+             * @default 3600
+             */
+            windowSeconds?: number | undefined;
+            /**
+             * Seconds a visitor stays blocked after reaching the block
+             * threshold
+             *
+             * @default 900
+             */
+            cooldownSeconds?: number | undefined;
+        } | undefined;
+        /**
+         * Limit how often authentication operations can be performed
+         */
+        velocity?: {
+            enabled: boolean;
+            /**
+             * Number of authentication requests per visitor in the window
+             * before a challenge or a block
+             *
+             * @default { challenge: 10, block: 20 }
+             */
+            thresholds?: {
+                challenge: number;
+                block: number;
+            } | undefined;
+            /**
+             * Maximum sign-ups per visitor in the window
+             *
+             * @default 5
+             */
+            maxSignupsPerVisitor?: number | undefined;
+            /**
+             * Maximum password reset requests per IP address in the window
+             *
+             * @default 10
+             */
+            maxPasswordResetsPerIp?: number | undefined;
+            /**
+             * Maximum sign-in attempts per IP address in the window
+             *
+             * @default 50
+             */
+            maxSignInsPerIp?: number | undefined;
+            /**
+             * Window in seconds
+             *
+             * @default 3600
+             */
+            windowSeconds?: number | undefined;
+            /**
+             * Action when a `max*` limit is exceeded
+             *
+             * @default "challenge"
+             */
+            action?: SecurityAction | undefined;
+        } | undefined;
+        /**
+         * Limit how many accounts a visitor can create
+         */
+        freeTrialAbuse?: {
+            enabled: boolean;
+            /**
+             * Number of accounts a visitor already created before a
+             * challenge or a block. Takes precedence over
+             * `maxAccountsPerVisitor`.
+             */
+            thresholds?: {
+                challenge: number;
+                block: number;
+            } | undefined;
+            /**
+             * Maximum accounts per visitor
+             *
+             * @default 3
+             */
+            maxAccountsPerVisitor?: number | undefined;
+            /**
+             * How long sign-ups are remembered per visitor, in seconds.
+             * Clamped to between 1 and 365 days.
+             *
+             * @default 7776000 (90 days)
+             */
+            retentionSeconds?: number | undefined;
+            /**
+             * Action when `maxAccountsPerVisitor` is reached
+             *
+             * @default "block"
+             */
+            action?: SecurityAction | undefined;
+        } | undefined;
+        /**
+         * Detect automated clients. `true` challenges them.
+         */
+        botBlocking?: (boolean | {
+            action: SecurityAction;
+        }) | undefined;
+        /**
+         * Detect requests from IP addresses known to be malicious. `true`
+         * blocks them.
+         */
+        suspiciousIpBlocking?: (boolean | {
+            action: SecurityAction;
+        }) | undefined;
+        /**
+         * Proof-of-work difficulty, in leading zero bits of the solution hash
+         *
+         * @default 18
+         */
+        /**
+         * Notify users when they sign in from a device they haven't used
+         * before, identified by the visitor id
+         *
+         * @default false
+         */
+        unknownDeviceNotification?: boolean | undefined;
+        /**
+         * Detect sign-ins from locations too far apart to travel between in
+         * the time since the previous sign-in. Checked once the credentials
+         * are verified; a challenge blocks sign-ins that can't be repeated,
+         * like magic links and one-time codes.
+         */
+        impossibleTravel?: {
+            enabled: boolean;
+            /**
+             * Fastest realistic travel speed, in km/h
+             *
+             * @default 1000
+             */
+            maxSpeedKmh?: number | undefined;
+            /**
+             * @default "challenge"
+             */
+            action?: SecurityAction | undefined;
+        } | undefined;
+        /**
+         * Challenge or block requests by country. Use either `allowList`
+         * or `denyList`.
+         */
+        geoBlocking?: {
+            /**
+             * Only allow these countries (ISO 3166-1 alpha-2)
+             */
+            allowList?: string[] | undefined;
+            /**
+             * Block these countries (ISO 3166-1 alpha-2)
+             */
+            denyList?: string[] | undefined;
+            /**
+             * @default "block"
+             */
+            action?: Exclude<SecurityAction, "log"> | undefined;
+        } | undefined;
+        /**
+         * Check new passwords against known breaches. Only the first 5
+         * characters of the password's SHA-1 hash are sent.
+         */
+        compromisedPassword?: {
+            enabled: boolean;
+            /**
+             * @default "block"
+             */
+            action?: SecurityAction | undefined;
+            /**
+             * Minimum number of breaches a password must appear in
+             *
+             * @default 1
+             */
+            minBreachCount?: number | undefined;
+        } | undefined;
+        /**
+         * Reject disposable email addresses and invalid email domains on
+         * sign-up and email changes
+         */
+        emailValidation?: {
+            enabled: boolean;
+            /**
+             * - `low`: block known disposable domains
+             * - `medium`: also require MX records
+             * - `high`: also reject addresses that look generated
+             *
+             * @default "medium"
+             */
+            strictness?: ("low" | "medium" | "high") | undefined;
+            /**
+             * @default "block"
+             */
+            action?: SecurityAction | undefined;
+            /**
+             * Domains that skip every check (exact match)
+             */
+            domainAllowlist?: string[] | undefined;
+        } | undefined;
+        /**
+         * Match aliases of the same mailbox, e.g. `j.doe+news@gmail.com` and
+         * `jdoe@gmail.com`. Addresses are kept as typed; an alias of an
+         * existing account signs in to it and can't be used for a new one.
+         * Adds a `normalizedEmail` field to users, set for existing users on
+         * their next sign-in.
+         */
+        emailNormalization?: {
+            /**
+             * @default false
+             */
+            enabled?: boolean | undefined;
+        } | undefined;
+        /**
+         * Detect sign-ins to accounts that haven't been used for a long time.
+         * Checked once the credentials are verified. Accounts are tracked
+         * from their first sign-in after sentinel is enabled.
+         */
+        staleUsers?: {
+            enabled: boolean;
+            /**
+             * Days of inactivity after which an account is stale
+             *
+             * @default 90
+             */
+            staleDays?: number | undefined;
+            /**
+             * @default "log"
+             */
+            action?: SecurityAction | undefined;
+            /**
+             * Notify the user through `sendNotification`
+             *
+             * @default false
+             */
+            notifyUser?: boolean | undefined;
+            /**
+             * Notify `adminEmail` through `sendNotification`
+             *
+             * @default false
+             */
+            notifyAdmin?: boolean | undefined;
+            /**
+             * Required when `notifyAdmin` is true
+             */
+            adminEmail?: string | undefined;
+        } | undefined;
+        challengeDifficulty?: number | undefined;
+    } | undefined;
+    /**
+     * Custom schema for the sentinel plugin
+     */
+    schema?: InferOptionSchema<typeof schema> | undefined;
+}

package/dist/src/test-utils/memory-secondary-storage.d.ts

@@ -0,0 +1,16 @@
+import type { SecondaryStorage } from "@gatwech/core/db";
+/**
+ * In-memory secondary storage for tests. Expiry follows `Date.now()`, so it
+ * works with faked timers. The atomic operations are optional, to test both
+ * code paths.
+ */
+export declare function createMemorySecondaryStorage(options?: {
+    increment?: boolean;
+    getAndDelete?: boolean;
+}): {
+    storage: SecondaryStorage;
+    /** Keys that currently hold a value */
+    keys: () => string[];
+    /** The TTL, in seconds, a key was last written with */
+    ttl: (key: string) => number | undefined;
+};

package/dist/src/test-utils/password.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Password hashing without key derivation, for tests that sign in many times
+ * and don't test hashing itself. Each real hash takes a few hundred
+ * milliseconds, which adds up when test files run in parallel.
+ */
+export declare const fastPasswordHashing: {
+    hash(password: string): Promise<string>;
+    verify({ hash, password }: {
+        hash: string;
+        password: string;
+    }): Promise<boolean>;
+};

package/dist/src/test-utils/test-instance.d.ts

@@ -2721,8 +2721,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                 returnHeaders?: ReturnHeaders | undefined;
             }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                 headers: Headers;
-                response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-            } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+            } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
             options: {
                 method: "POST";
                 body: import("zod").ZodObject<{
@@ -2896,11 +2896,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
             }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                 headers: Headers;
                 response: {
-                    user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                    user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                     data: Record<string, any>;
                 } | null;
             } : {
-                user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                 data: Record<string, any>;
             } | null>;
             options: {
@@ -5633,8 +5633,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                 returnHeaders?: ReturnHeaders | undefined;
             }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                 headers: Headers;
-                response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-            } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+            } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
             options: {
                 method: "POST";
                 body: import("zod").ZodObject<{
@@ -5808,11 +5808,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
             }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                 headers: Headers;
                 response: {
-                    user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                    user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                     data: Record<string, any>;
                 } | null;
             } : {
-                user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                 data: Record<string, any>;
             } | null>;
             options: {
@@ -8620,8 +8620,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                         returnHeaders?: ReturnHeaders | undefined;
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
-                        response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-                    } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                        response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+                    } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
                     options: {
                         method: "POST";
                         body: import("zod").ZodObject<{
@@ -8795,11 +8795,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
                         response: {
-                            user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                            user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                             data: Record<string, any>;
                         } | null;
                     } : {
-                        user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                        user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                         data: Record<string, any>;
                     } | null>;
                     options: {
@@ -11532,8 +11532,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                         returnHeaders?: ReturnHeaders | undefined;
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
-                        response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-                    } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                        response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+                    } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
                     options: {
                         method: "POST";
                         body: import("zod").ZodObject<{
@@ -11707,11 +11707,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
                         response: {
-                            user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                            user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                             data: Record<string, any>;
                         } | null;
                     } : {
-                        user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                        user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                         data: Record<string, any>;
                     } | null>;
                     options: {
@@ -14591,8 +14591,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                         returnHeaders?: ReturnHeaders | undefined;
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
-                        response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-                    } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                        response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+                    } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
                     options: {
                         method: "POST";
                         body: import("zod").ZodObject<{
@@ -14766,11 +14766,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
                         response: {
-                            user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                            user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                             data: Record<string, any>;
                         } | null;
                     } : {
-                        user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                        user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                         data: Record<string, any>;
                     } | null>;
                     options: {
@@ -17503,8 +17503,8 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                         returnHeaders?: ReturnHeaders | undefined;
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
-                        response: import("packages/core/dist/index-65G5U5DB.mjs").X;
-                    } : import("packages/core/dist/index-65G5U5DB.mjs").X>;
+                        response: import("packages/core/dist/index-Df0KhQRf.mjs").X;
+                    } : import("packages/core/dist/index-Df0KhQRf.mjs").X>;
                     options: {
                         method: "POST";
                         body: import("zod").ZodObject<{
@@ -17678,11 +17678,11 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
                     }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                         headers: Headers;
                         response: {
-                            user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                            user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                             data: Record<string, any>;
                         } | null;
                     } : {
-                        user: import("packages/core/dist/index-65G5U5DB.mjs").Z;
+                        user: import("packages/core/dist/index-Df0KhQRf.mjs").Z;
                         data: Record<string, any>;
                     } | null>;
                     options: {
@@ -17844,6 +17844,6 @@ export declare function getTestInstance<O extends Partial<PayvoAuthOptions>, C e
     cookieSetter: typeof setCookieToHeader;
     customFetchImpl: (url: string | URL | Request, init?: RequestInit | undefined) => Promise<Response>;
     sessionSetter: (headers: Headers) => (context: SuccessContext) => void;
-    db: import("packages/core/dist/index-65G5U5DB.mjs").nt<PayvoAuthOptions>;
+    db: import("packages/core/dist/index-Df0KhQRf.mjs").nt<PayvoAuthOptions>;
     runWithUser: (email: string, password: string, fn: (headers: Headers) => Promise<void> | void) => Promise<void>;
 }>;