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

package/dist/src/plugins/audit-log/index.d.ts

@@ -3,12 +3,10 @@ import * as z from "zod";
 import { type AuditEventType } from "./events";
 import { schema } from "./schema";
 import type { AuditEvent, AuditLogOptions } from "./types";
+export * from "./error-codes";
 export * from "./events";
+export { verifyAuditEvent } from "./integrity";
 export type * from "./types";
-export declare const AUDIT_LOG_ERROR_CODES: {
-    readonly AUDIT_LOG_ACCESS_DENIED: "You don't have access to these audit logs";
-    readonly AUDIT_LOG_UNAVAILABLE: "Audit logs are temporarily unavailable";
-};
 export declare const auditLog: (options?: AuditLogOptions | undefined) => {
     id: "audit-log";
     init(ctx: AuthContext<import("@gatwech/core").PayvoAuthOptions>): {
@@ -115,6 +113,7 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                     offset?: string | number | undefined;
                     eventType?: string | undefined;
                     identifier?: string | undefined;
+                    traceId?: string | undefined;
                     organizationId?: string | undefined;
                     userId?: string | undefined;
                     startDate?: string | undefined;
@@ -178,6 +177,7 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                     offset: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
                     eventType: z.ZodOptional<z.ZodString>;
                     identifier: z.ZodOptional<z.ZodString>;
+                    traceId: z.ZodOptional<z.ZodString>;
                     organizationId: z.ZodOptional<z.ZodString>;
                     userId: z.ZodOptional<z.ZodString>;
                     startDate: z.ZodOptional<z.ZodString>;
@@ -242,6 +242,30 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                                                                 type: string;
                                                                 nullable: boolean;
                                                             };
+                                                            traceId: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            requestId: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            actorType: {
+                                                                type: string;
+                                                                enum: string[];
+                                                            };
+                                                            severity: {
+                                                                type: string;
+                                                                enum: string[];
+                                                            };
+                                                            signature: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            verified: {
+                                                                type: string;
+                                                                description: string;
+                                                            };
                                                             createdAt: {
                                                                 type: string;
                                                                 format: string;
@@ -283,6 +307,7 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                     offset?: string | number | undefined;
                     eventType?: string | undefined;
                     identifier?: string | undefined;
+                    traceId?: string | undefined;
                     organizationId?: string | undefined;
                     userId?: string | undefined;
                     startDate?: string | undefined;
@@ -305,13 +330,17 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
             }) | undefined): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
                 headers: Headers;
                 response: {
-                    events: AuditEvent[];
+                    events: (AuditEvent & {
+                        verified?: boolean | undefined;
+                    })[];
                     total: number;
                     limit: number;
                     offset: number;
                 };
             } : {
-                events: AuditEvent[];
+                events: (AuditEvent & {
+                    verified?: boolean | undefined;
+                })[];
                 total: number;
                 limit: number;
                 offset: number;
@@ -346,6 +375,7 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                     offset: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
                     eventType: z.ZodOptional<z.ZodString>;
                     identifier: z.ZodOptional<z.ZodString>;
+                    traceId: z.ZodOptional<z.ZodString>;
                     organizationId: z.ZodOptional<z.ZodString>;
                     userId: z.ZodOptional<z.ZodString>;
                     startDate: z.ZodOptional<z.ZodString>;
@@ -410,6 +440,30 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                                                                 type: string;
                                                                 nullable: boolean;
                                                             };
+                                                            traceId: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            requestId: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            actorType: {
+                                                                type: string;
+                                                                enum: string[];
+                                                            };
+                                                            severity: {
+                                                                type: string;
+                                                                enum: string[];
+                                                            };
+                                                            signature: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            verified: {
+                                                                type: string;
+                                                                description: string;
+                                                            };
                                                             createdAt: {
                                                                 type: string;
                                                                 format: string;
@@ -566,6 +620,29 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                 metadata: {
                     SERVER_ONLY: true;
                     client: boolean;
+                    openapi: {
+                        operationId: string;
+                        summary: string;
+                        description: string;
+                        responses: {
+                            200: {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                deleted: {
+                                                    type: string;
+                                                };
+                                            };
+                                            required: string[];
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
                 };
             } & {
                 use: any[];
@@ -616,6 +693,26 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
                     type: "json";
                     required: false;
                 };
+                traceId: {
+                    type: "string";
+                    required: false;
+                };
+                requestId: {
+                    type: "string";
+                    required: false;
+                };
+                actorType: {
+                    type: "string";
+                    required: false;
+                };
+                severity: {
+                    type: "string";
+                    required: false;
+                };
+                signature: {
+                    type: "string";
+                    required: false;
+                };
                 createdAt: {
                     type: "date";
                     required: true;
@@ -625,11 +722,12 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
     };
     $ERROR_CODES: {
         readonly AUDIT_LOG_ACCESS_DENIED: "You don't have access to these audit logs";
+        readonly AUDIT_CANNOT_BE_DISABLED: "Core audit events and the local audit store can't be turned off";
         readonly AUDIT_LOG_UNAVAILABLE: "Audit logs are temporarily unavailable";
+        readonly AUDIT_RETENTION_TOO_SHORT: "Audit events can't be deleted before the retention minimum has passed";
+        readonly AUDIT_SIGNING_SECRET_MISSING: "Audit events must be signed in production: set integrity.secret or PAYVO_AUDIT_SIGNING_SECRET";
     };
     options: {
-        database: boolean;
-        trackFailedSignIns: boolean;
         adminRoles: string[];
         organizationAdminRoles: string[];
         showAttemptsOnOwnAccount: boolean;
@@ -644,6 +742,14 @@ export declare const auditLog: (options?: AuditLogOptions | undefined) => {
             } | undefined;
         } | false | undefined;
         onEvent?: ((event: AuditEvent) => void | Promise<void>) | undefined;
+        retention?: {
+            minimumDays?: number | undefined;
+        } | undefined;
+        integrity?: {
+            secret?: string | undefined;
+            secrets?: Record<string, string> | undefined;
+        } | undefined;
+        sensitiveKeys?: string[] | undefined;
         exclude?: AuditEventType[] | undefined;
         schema?: import("..").InferOptionSchema<typeof schema> | undefined;
     };

package/dist/src/plugins/audit-log/integrity.d.ts

@@ -0,0 +1,20 @@
+import type { AuditEvent, AuditLogOptions } from "./types";
+/** Signs an event's fields, as `signAuditPayload` does the string */
+export declare function signAuditEvent(event: Omit<AuditEvent, "signature">, secret: string): Promise<string>;
+/**
+ * Whether an event's signature matches its fields, so a row that was changed
+ * after it was recorded doesn't verify.
+ *
+ * `integrity.secret` verifies signatures made with the current key, and
+ * `integrity.secrets` maps an older version to its key, so keys can be
+ * rotated without signing old rows again. An event without a signature, or
+ * with a version that has no key, doesn't verify.
+ *
+ * @example
+ * ```ts
+ * const events = await auth.api.getAllAuditLogs({ headers });
+ * events.events.every((event) => event.verified);
+ * await verifyAuditEvent(event, { secret: process.env.PAYVO_AUDIT_SIGNING_SECRET });
+ * ```
+ */
+export declare function verifyAuditEvent(event: AuditEvent, integrity: NonNullable<AuditLogOptions["integrity"]>): Promise<boolean>;

package/dist/src/plugins/audit-log/redact.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Replaces the value of every sensitive key with `"[REDACTED]"`, at any depth
+ * and through arrays. The key stays, so the shape of the data is still
+ * visible.
+ *
+ * A key is sensitive when its name, in lower case and without `-` or `_`,
+ * is in the built-in list (passwords, tokens, OTPs, secrets, authorization
+ * and cookie headers, card data) or in `sensitiveKeys`. The input isn't
+ * changed. Only plain objects and arrays are walked; other values are
+ * returned as they are.
+ *
+ * @example
+ * ```ts
+ * redactAuditData({ user: { id: "1", Access_Token: "abc" } }, [])
+ * // { user: { id: "1", Access_Token: "[REDACTED]" } }
+ * ```
+ */
+export declare function redactAuditData<Value>(value: Value, sensitiveKeys?: readonly string[]): Value;

package/dist/src/plugins/audit-log/remote.d.ts

@@ -5,6 +5,7 @@ export type RemoteQuery = {
     offset: number;
     eventType?: string | undefined;
     identifier?: string | undefined;
+    traceId?: string | undefined;
     userId?: string | undefined;
     organizationId?: string | undefined;
     startDate?: string | undefined;

package/dist/src/plugins/audit-log/schema.d.ts

@@ -41,6 +41,31 @@ export declare const schema: {
                 type: "json";
                 required: false;
             };
+            /** The request chain the event belongs to, shared with other services */
+            traceId: {
+                type: "string";
+                required: false;
+            };
+            /** The single request within the chain */
+            requestId: {
+                type: "string";
+                required: false;
+            };
+            /** `user`, `admin` or `system` */
+            actorType: {
+                type: "string";
+                required: false;
+            };
+            /** `info`, `warning` or `critical` */
+            severity: {
+                type: "string";
+                required: false;
+            };
+            /** `v1:<HMAC-SHA256>` of the event's fields, when signing is configured */
+            signature: {
+                type: "string";
+                required: false;
+            };
             createdAt: {
                 type: "date";
                 required: true;

package/dist/src/plugins/audit-log/types.d.ts

@@ -29,11 +29,41 @@ export interface AuditEvent {
      * Never contains passwords, tokens or OTPs
      */
     eventData: Record<string, unknown> | null;
+    /**
+     * The request chain the event belongs to, from the `Trace-Id` or
+     * `traceparent` header, or minted for the request. Other services
+     * record the same id, so their events can be joined with these.
+     *
+     * Null for events recorded outside a request.
+     */
+    traceId: string | null;
+    /**
+     * The single request within the chain, from the `Request-Id` header, or
+     * minted for the request
+     */
+    requestId: string | null;
+    /**
+     * Who acted: `user` for the signed-in or signing-in user, `admin` for an
+     * admin acting on someone else or impersonating them, `system` without a
+     * request
+     */
+    actorType: "user" | "admin" | "system";
+    /**
+     * How much the event matters, from the event type and its status
+     */
+    severity: "info" | "warning" | "critical";
+    /**
+     * `v1:<HMAC-SHA256>` over the event's other fields, which shows whether
+     * the row was changed after it was recorded (see `verifyAuditEvent`)
+     *
+     * Null when no signing secret was configured.
+     */
+    signature: string | null;
     createdAt: Date;
 }
 export interface AuditLogOptions {
     /**
-     * Send events to the hosted backend
+     * Send events to the hosted backend, in addition to the `auditLog` table
      *
      * Enabled when an API key and URL are configured, either here or through
      * `PAYVO_INFRA_API_KEY` and `PAYVO_INFRA_API_URL`. Set to `false` to
@@ -84,12 +114,6 @@ export interface AuditLogOptions {
             flushIntervalMs?: number | undefined;
         } | undefined;
     } | false | undefined;
-    /**
-     * Write events to the `auditLog` table
-     *
-     * @default true
-     */
-    database?: boolean | undefined;
     /**
      * Called for every recorded event, e.g. to publish it to a message broker
      *
@@ -97,16 +121,52 @@ export interface AuditLogOptions {
      */
     onEvent?: ((event: AuditEvent) => void | Promise<void>) | undefined;
     /**
-     * Event types that should not be recorded
+     * How long events are kept at least. Deleting events with
+     * `deleteOldEvents` refuses a period shorter than `minimumDays`, and
+     * every deletion is recorded as an `audit_events_deleted` event.
+     *
+     * `minimumDays` is a whole number of at least 1. The right value is a
+     * compliance decision, so set it to what your regulator requires.
+     *
+     * @default { minimumDays: 365 }
      */
-    exclude?: AuditEventType[] | undefined;
+    retention?: {
+        minimumDays?: number | undefined;
+    } | undefined;
     /**
-     * Record `user_sign_in_failed` events for failed sign-in attempts, and
-     * `verification_failed` events for wrong one-time codes and tokens
+     * Signs every event with HMAC-SHA256, so a row that is changed after it
+     * is recorded no longer verifies
      *
-     * @default true
+     * `secret` signs and verifies; `secrets` maps an older key version to its
+     * secret, so keys can be rotated without signing old rows again. Without
+     * a secret events aren't signed, and the plugin refuses to start when
+     * `NODE_ENV` is `production`.
+     *
+     * @default { secret: process.env.PAYVO_AUDIT_SIGNING_SECRET }
      */
-    trackFailedSignIns?: boolean | undefined;
+    integrity?: {
+        secret?: string | undefined;
+        secrets?: Record<string, string> | undefined;
+    } | undefined;
+    /**
+     * Keys whose values are replaced with `"[REDACTED]"` in an event's
+     * `eventData`, at any depth, before it is stored or sent anywhere
+     *
+     * Passwords, tokens, one-time codes, secrets, authorization and cookie
+     * headers and card data are always redacted. Keys are compared in lower
+     * case, without `-` or `_`.
+     *
+     * @default []
+     */
+    sensitiveKeys?: string[] | undefined;
+    /**
+     * Event types that should not be recorded
+     *
+     * The events in `CORE_EVENT_TYPES` can't be excluded, and `auditLog`
+     * refuses to start when one is listed here. Events are always written to
+     * the `auditLog` table, whatever else `remote` and `onEvent` do with them.
+     */
+    exclude?: AuditEventType[] | undefined;
     /**
      * Roles allowed to read every audit event through
      * `/audit-log/get-all-audit-logs`

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

@@ -36,12 +36,6 @@ export declare function executeAction(params: {
     difficulty: number;
     metadata?: Record<string, unknown> | undefined;
 }): Promise<Decision>;
-export declare const SENTINEL_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";
-};
 /** The error for a decision, or null when the request is allowed */
 export declare function errorForDecision(decision: Decision): ({
     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;

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

@@ -64,4 +64,7 @@ export declare const sentinelClient: (options?: {
             onResponse({ response, request }: import("@better-fetch/fetch").ResponseContext): Promise<Response | undefined>;
         };
     }[];
+    pathMethods: {
+        "/sentinel/list-blocks": "GET";
+    };
 };

package/dist/src/plugins/sentinel/error-codes.d.ts

@@ -0,0 +1,6 @@
+export declare const SENTINEL_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";
+};

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

@@ -1,14 +1,13 @@
 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";
 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 * from "./error-codes";
 export declare const sentinel: (options?: SentinelOptions | undefined) => {
     id: "sentinel";
     init(ctx: AuthContext<import("@gatwech/core").PayvoAuthOptions>): {
@@ -335,12 +334,72 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
                         operationId: string;
                         summary: string;
                         description: string;
+                        responses: {
+                            200: {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                blocks: {
+                                                    type: string;
+                                                    items: {
+                                                        type: string;
+                                                        properties: {
+                                                            id: {
+                                                                type: string;
+                                                            };
+                                                            key: {
+                                                                type: string;
+                                                            };
+                                                            feature: {
+                                                                type: string;
+                                                            };
+                                                            kind: {
+                                                                type: string;
+                                                                enum: string[];
+                                                            };
+                                                            identifier: {
+                                                                type: string;
+                                                            };
+                                                            account: {
+                                                                type: string;
+                                                                nullable: boolean;
+                                                            };
+                                                            blockedUntil: {
+                                                                type: string;
+                                                                format: string;
+                                                            };
+                                                            createdAt: {
+                                                                type: string;
+                                                                format: string;
+                                                            };
+                                                        };
+                                                    };
+                                                };
+                                                total: {
+                                                    type: string;
+                                                };
+                                                limit: {
+                                                    type: string;
+                                                };
+                                                offset: {
+                                                    type: string;
+                                                };
+                                            };
+                                            required: string[];
+                                        };
+                                    };
+                                };
+                            };
+                        };
                     };
                 };
             } & {
                 use: any[];
             };
-            path: "/sentinel/blocks";
+            path: "/sentinel/list-blocks";
         };
         unblock: {
             <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
@@ -406,6 +465,24 @@ export declare const sentinel: (options?: SentinelOptions | undefined) => {
                         operationId: string;
                         summary: string;
                         description: string;
+                        responses: {
+                            200: {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                success: {
+                                                    type: string;
+                                                };
+                                            };
+                                            required: string[];
+                                        };
+                                    };
+                                };
+                            };
+                        };
                     };
                 };
             } & {

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

@@ -109,7 +109,7 @@ export interface SentinelOptions {
         resolveGeo?: ((ip: string) => GeoLocation | null | Promise<GeoLocation | null>) | undefined;
     } | undefined;
     /**
-     * Roles allowed to list and lift blocks through `/sentinel/blocks` and
+     * Roles allowed to list and lift blocks through `/sentinel/list-blocks` and
      * `/sentinel/unblock`
      *
      * @default ["admin"]