@gatwech/auth 1.0.0-beta.21 → 1.0.0-beta.23

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

@@ -1,4 +1,5 @@
 import type { AuthContext, GenericEndpointContext } from "@gatwech/core";
+import * as z from "zod";
 import type { User } from "../../types";
 import { SENTINEL_ERROR_CODES } from "./actions";
 import { schema } from "./schema";
@@ -127,6 +128,39 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
                 };
             };
         };
+        sentinelBlock: {
+            fields: {
+                key: {
+                    type: "string";
+                    required: true;
+                    unique: true;
+                };
+                feature: {
+                    type: "string";
+                    required: true;
+                };
+                kind: {
+                    type: "string";
+                    required: true;
+                };
+                identifier: {
+                    type: "string";
+                    required: true;
+                };
+                account: {
+                    type: "string";
+                    required: false;
+                };
+                blockedUntil: {
+                    type: "date";
+                    required: true;
+                };
+                createdAt: {
+                    type: "date";
+                    required: true;
+                };
+            };
+        };
         sentinelSignIn: {
             fields: {
                 userId: {
@@ -210,9 +244,221 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
             };
         };
     };
+    endpoints: {
+        listBlocks: {
+            <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0?: ({
+                body?: undefined;
+            } & {
+                method?: "GET" | undefined;
+            } & {
+                query?: {
+                    limit?: string | number | undefined;
+                    offset?: string | number | undefined;
+                } | undefined;
+            } & {
+                params?: Record<string, any>;
+            } & {
+                request?: Request;
+            } & {
+                headers?: HeadersInit;
+            } & {
+                asResponse?: boolean;
+                returnHeaders?: boolean;
+                use?: import("better-call").Middleware[];
+                path?: string;
+            } & {
+                asResponse?: AsResponse | undefined;
+                returnHeaders?: ReturnHeaders | undefined;
+            }) | undefined): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+                headers: Headers;
+                response: {
+                    blocks: {
+                        id: string;
+                        key: string;
+                        feature: string;
+                        kind: string;
+                        identifier: string;
+                        account: string | null;
+                        blockedUntil: Date;
+                        createdAt: Date;
+                    }[];
+                    total: number;
+                    limit: number;
+                    offset: number;
+                };
+            } : {
+                blocks: {
+                    id: string;
+                    key: string;
+                    feature: string;
+                    kind: string;
+                    identifier: string;
+                    account: string | null;
+                    blockedUntil: Date;
+                    createdAt: Date;
+                }[];
+                total: number;
+                limit: number;
+                offset: number;
+            }>;
+            options: {
+                method: "GET";
+                use: ((inputContext: import("better-call").MiddlewareInputContext<import("better-call").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;
+                        };
+                    };
+                }>)[];
+                query: z.ZodOptional<z.ZodObject<{
+                    limit: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+                    offset: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+                }, z.core.$strip>>;
+                metadata: {
+                    openapi: {
+                        operationId: string;
+                        summary: string;
+                        description: string;
+                    };
+                };
+            } & {
+                use: any[];
+            };
+            path: "/sentinel/blocks";
+        };
+        unblock: {
+            <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+                body: {
+                    id: string;
+                };
+            } & {
+                method?: "POST" | undefined;
+            } & {
+                query?: Record<string, any> | undefined;
+            } & {
+                params?: Record<string, any>;
+            } & {
+                request?: Request;
+            } & {
+                headers?: HeadersInit;
+            } & {
+                asResponse?: boolean;
+                returnHeaders?: boolean;
+                use?: import("better-call").Middleware[];
+                path?: string;
+            } & {
+                asResponse?: AsResponse | undefined;
+                returnHeaders?: ReturnHeaders | undefined;
+            }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+                headers: Headers;
+                response: {
+                    success: boolean;
+                };
+            } : {
+                success: boolean;
+            }>;
+            options: {
+                method: "POST";
+                use: ((inputContext: import("better-call").MiddlewareInputContext<import("better-call").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;
+                        };
+                    };
+                }>)[];
+                body: z.ZodObject<{
+                    id: z.ZodString;
+                }, z.core.$strip>;
+                metadata: {
+                    openapi: {
+                        operationId: string;
+                        summary: string;
+                        description: string;
+                    };
+                };
+            } & {
+                use: any[];
+            };
+            path: "/sentinel/unblock";
+        };
+        deleteExpired: {
+            <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0?: ({
+                body?: undefined;
+            } & {
+                method?: "POST" | undefined;
+            } & {
+                query?: Record<string, any> | undefined;
+            } & {
+                params?: Record<string, any>;
+            } & {
+                request?: Request;
+            } & {
+                headers?: HeadersInit;
+            } & {
+                asResponse?: boolean;
+                returnHeaders?: boolean;
+                use?: import("better-call").Middleware[];
+                path?: string;
+            } & {
+                asResponse?: AsResponse | undefined;
+                returnHeaders?: ReturnHeaders | undefined;
+            }) | undefined): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+                headers: Headers;
+                response: {
+                    success: boolean;
+                };
+            } : {
+                success: boolean;
+            }>;
+            options: {
+                method: "POST";
+                metadata: {
+                    SERVER_ONLY: true;
+                    client: boolean;
+                };
+            } & {
+                use: any[];
+            };
+            path: "/sentinel/delete-expired";
+        };
+    };
     $ERROR_CODES: {
         readonly POW_CHALLENGE_REQUIRED: "Challenge required";
         readonly SECURITY_BLOCKED: "Request blocked for security reasons";
+        readonly SECURITY_ADMIN_REQUIRED: "Only an administrator can manage security blocks";
+        readonly BLOCK_NOT_FOUND: "That block doesn't exist or has ended";
     };
     options: {
         failOpen: boolean;
@@ -238,6 +484,7 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
             isBot?: ((request: Request) => boolean | Promise<boolean>) | undefined;
             resolveGeo?: ((ip: string) => GeoLocation | null | Promise<GeoLocation | null>) | undefined;
         } | undefined;
+        adminRoles?: string[] | undefined;
         sendNotification?: ((notification: {
             type: "unknown-device" | "stale-account";
             recipient: "user" | "admin";
@@ -255,9 +502,7 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
             credentialStuffing?: {
                 enabled: boolean;
                 action?: SecurityAction | undefined;
-                thresholds
-                /** Checked with the identification service, rather than taken as sent */
-                ? /** Checked with the identification service, rather than taken as sent */: {
+                thresholds?: {
                     challenge: number;
                     block: number;
                 } | undefined;

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

@@ -29,6 +29,43 @@ export declare const schema: {
             };
         };
     };
+    /** Active blocks, so an admin can list and lift them */
+    sentinelBlock: {
+        fields: {
+            /** The counter the block is kept under, e.g. `cs:ip:203.0.113.1` */
+            key: {
+                type: "string";
+                required: true;
+                unique: true;
+            };
+            feature: {
+                type: "string";
+                required: true;
+            };
+            /** What was blocked: a visitor id or an IP address */
+            kind: {
+                type: "string";
+                required: true;
+            };
+            identifier: {
+                type: "string";
+                required: true;
+            };
+            /** The account the attempts were on, when the block is for one */
+            account: {
+                type: "string";
+                required: false;
+            };
+            blockedUntil: {
+                type: "date";
+                required: true;
+            };
+            createdAt: {
+                type: "date";
+                required: true;
+            };
+        };
+    };
     sentinelSignIn: {
         fields: {
             userId: {

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

@@ -9,11 +9,26 @@ type StoredChallenge = {
     visitorId: string | null;
     expiresAt: Date;
 };
+type BlockRow = {
+    id: string;
+    key: string;
+    feature: string;
+    kind: string;
+    identifier: string;
+    account: string | null;
+    blockedUntil: Date;
+    createdAt: Date;
+};
 /**
  * Deletes expired counters and challenges from the database, at most every
  * 10 seconds per auth instance. Secondary storage expires them itself.
  */
 export declare function deleteAllExpiredRows(auth: AuthContext, byPassLastCheckTime?: boolean): Promise<void>;
+/**
+ * Deletes blocks that ended a while ago, at most every 10 seconds per auth
+ * instance. Blocks live in the database even with secondary storage.
+ */
+export declare function deleteExpiredBlocks(auth: AuthContext, byPassLastCheckTime?: boolean): Promise<void>;
 /**
  * Counters and challenges, kept in secondary storage when it's configured
  * and in the database otherwise
@@ -32,6 +47,25 @@ export declare function createSentinelStore(auth: AuthContext): {
     }): Promise<number>;
     /** Returns a counter's current value, or 0 when it's missing or expired */
     get(name: string): Promise<number>;
+    /** Records a block, replacing an earlier one for the same counter */
+    recordBlock(block: {
+        key: string;
+        feature: string;
+        kind: string;
+        identifier: string;
+        account: string | null;
+        blockedUntil: Date;
+    }): Promise<void>;
+    /** Blocks that haven't ended, the newest first */
+    listBlocks(page: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        blocks: BlockRow[];
+        total: number;
+    }>;
+    /** Lifts a block. Returns it, or null when there's no active block with this id. */
+    removeBlock(id: string): Promise<BlockRow | null>;
     reset(name: string): Promise<void>;
     saveChallenge(challenge: StoredChallenge): Promise<void>;
     /**

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

@@ -108,6 +108,13 @@ export interface SentinelOptions {
          */
         resolveGeo?: ((ip: string) => GeoLocation | null | Promise<GeoLocation | null>) | undefined;
     } | undefined;
+    /**
+     * Roles allowed to list and lift blocks through `/sentinel/blocks` and
+     * `/sentinel/unblock`
+     *
+     * @default ["admin"]
+     */
+    adminRoles?: string[] | undefined;
     /**
      * Send a security notification, e.g. by email. Required for
      * `unknownDeviceNotification` and the stale account notifications.

package/dist/src/utils/has-role.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a user's role field, a single role or a comma separated list,
+ * includes one of the given roles
+ */
+export declare function hasRole(roleField: unknown, roles: string[]): boolean;