@navette-js/panels 1.0.0-beta.3 → 1.0.0-beta.5

package/lib/multi-factor.d.ts

@@ -0,0 +1,348 @@
+import { Action } from '@navette-js/actions';
+import { Field, OneTimeCodeInput } from '@navette-js/forms';
+import { Component, type ComponentContext } from '@navette-js/schemas';
+import { Throttle } from './throttle.ts';
+import { type TotpAlgorithm } from './totp.ts';
+import { type UserVerification } from './webauthn.ts';
+import type { AuthProvider, Panel, User } from './index.ts';
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A way to prove one's identity after the password. Register providers with `panel.multiFactorAuthentication([...])`.
+ * Each provider's state lives under its id: the challenge form fields under `data.multiFactor.<id>`.
+ */
+export interface MultiFactorAuthenticationProvider {
+    /** Unique id, used as the state path of its components (`app`, `security-keys`…). Letters, digits, `-` and `_`. */
+    getId(): string;
+    /** Label of the provider in the picker shown when a user has several. */
+    getLoginFormLabel(): string;
+    /** Whether the user has set this provider up. */
+    isEnabled(user: User, panel: Panel): MaybePromise<boolean>;
+    /** Components shown on the profile page (and the required setup page): status and actions to set up or disable. */
+    getManagementSchemaComponents(user: User, panel: Panel): Component[];
+    /** Fields of the login challenge. Their validation rules decide whether the challenge passes. */
+    getChallengeFormComponents(user: User, panel: Panel): Component[];
+    /** Runs when the challenge is shown, or when the user picks this provider (send a code by SMS…). */
+    beforeChallenge?(user: User, panel: Panel): MaybePromise<void>;
+    /** Called when the panel router is built: throw if something the provider needs is missing (its storage…). */
+    checkConfiguration?(panel: Panel): void;
+}
+/** Short-lived values: used codes (replay protection) and pending WebAuthn challenges. */
+export interface MultiFactorCacheStore {
+    get(key: string): MaybePromise<unknown>;
+    put(key: string, value: unknown, ttlSeconds: number): MaybePromise<void>;
+    forget(key: string): MaybePromise<void>;
+}
+/** In-memory store: fine for a single process. When running several, use a shared store (Redis…) with `cacheStore()`. */
+export declare class MemoryCacheStore implements MultiFactorCacheStore {
+    private entries;
+    private max;
+    constructor(max?: number);
+    get(key: string): unknown;
+    put(key: string, value: unknown, ttlSeconds: number): void;
+    forget(key: string): void;
+}
+/** Store used by the providers that do not set their own `cacheStore()`. */
+export declare const useMultiFactorCacheStore: (store: MultiFactorCacheStore) => void;
+/** The store of short-lived values shared by authentication features (multi-factor codes, email change blocks). */
+export declare const getDefaultCacheStore: () => MultiFactorCacheStore;
+/** The login challenge: enabled providers, the picker, rate limiting. */
+export declare class MultiFactorChallenge {
+    /** Attempts per user and per minute. */
+    static maxAttempts: number;
+    private static throttle;
+    private panel;
+    constructor(panel: Panel);
+    static make(panel: Panel): MultiFactorChallenge;
+    getProviders(): MultiFactorAuthenticationProvider[];
+    getEnabledProviders(user: User): Promise<MultiFactorAuthenticationProvider[]>;
+    hasEnabledProviders(user: User): Promise<boolean>;
+    beforeChallenge(user: User, provider?: MultiFactorAuthenticationProvider): Promise<void>;
+    /**
+     * Challenge fields for these enabled providers: a picker when there are several, then each provider's fields under its id
+     * (only the picked provider's are shown and validated).
+     */
+    getFormComponents(user: User, enabled: MultiFactorAuthenticationProvider[]): Component[];
+    private static limiter;
+    /** Records an attempt; returns 0 if allowed, otherwise the seconds to wait. */
+    hitRateLimiter(user: User): number;
+    clearRateLimiter(user: User): void;
+}
+/** Where app authentication data is kept; by default, the panel's auth provider (`knexAuthProvider` stores it in the users table). */
+export type AppAuthenticationStore = Required<Pick<AuthProvider, 'getAppAuthenticationSecret' | 'saveAppAuthenticationSecret'>> & Partial<Pick<AuthProvider, 'getAppAuthenticationRecoveryCodes' | 'saveAppAuthenticationRecoveryCodes'>>;
+/** Encrypts a TOTP secret at rest (AES-256-GCM, with a key derived from the panel key). */
+export declare function encryptSecret(panel: Panel, secret: string): string;
+/** Decrypts a stored secret; a value without the prefix is returned as is (secrets stored in clear by your own code). `null` when it cannot be read. */
+export declare function decryptSecret(panel: Panel, stored: string): string | null;
+/**
+ * Authentication with a code from an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password…):
+ * time-based one-time passwords (RFC 6238). `recoverable()` adds single-use recovery codes.
+ */
+export declare class AppAuthentication implements MultiFactorAuthenticationProvider {
+    protected _id: string;
+    protected _recoverable: boolean;
+    protected _regenerableRecoveryCodes: boolean;
+    protected _recoveryCodeCount: number;
+    protected _brandName: string | null;
+    protected _codeWindow: number;
+    protected _digits: number;
+    protected _period: number;
+    protected _algorithm: TotpAlgorithm;
+    protected _store: AppAuthenticationStore | null;
+    protected _cacheStore: MultiFactorCacheStore | null;
+    protected _confirmsPassword: boolean;
+    protected _generateRecoveryCodes: (() => string[]) | null;
+    protected setupThrottle: Throttle;
+    protected managementThrottle: Throttle;
+    static make(): AppAuthentication;
+    getId(): string;
+    /** Changes the id (to register two app providers with different settings). */
+    id(id: string): this;
+    getLoginFormLabel(): string;
+    /** Single-use recovery codes, shown once at setup, to sign in without the app. Needs `get`/`saveAppAuthenticationRecoveryCodes` on the store. */
+    recoverable(condition?: boolean): this;
+    isRecoverable(): boolean;
+    /** `false`: users cannot regenerate their recovery codes. */
+    regenerableRecoveryCodes(condition?: boolean): this;
+    canRegenerateRecoveryCodes(): boolean;
+    recoveryCodeCount(count: number): this;
+    getRecoveryCodeCount(): number;
+    /** Generates the recovery codes (by default, `xxxxxxxxxx-xxxxxxxxxx` from 62 characters). */
+    generateRecoveryCodesUsing(callback: (() => string[]) | null): this;
+    /** Name shown in the app, next to the account (the panel's brand name by default). */
+    brandName(name: string | null): this;
+    getBrandName(panel: Panel): string;
+    /** Codes accepted before and after the current one, to allow for clock drift (1 by default: ±30 seconds). */
+    codeWindow(window: number): this;
+    getCodeWindow(): number;
+    /** Code settings. Most apps only support the defaults (6 digits, 30 seconds, SHA-1). */
+    codeOptions(options: {
+        digits?: number;
+        period?: number;
+        algorithm?: TotpAlgorithm;
+    }): this;
+    /** Where secrets and recovery codes are stored (the panel's auth provider by default). */
+    store(store: AppAuthenticationStore | null): this;
+    /** Where used codes are remembered (replay protection). */
+    cacheStore(store: MultiFactorCacheStore | null): this;
+    /** `false`: setting up and turning off do not ask for the current password (accounts without one). */
+    confirmsPassword(condition?: boolean): this;
+    protected getStore(panel: Panel): AppAuthenticationStore;
+    protected codeOptionsOf(): {
+        digits: number;
+        period: number;
+        algorithm: TotpAlgorithm;
+    };
+    checkConfiguration(panel: Panel): void;
+    isEnabled(user: User, panel: Panel): Promise<boolean>;
+    /** The user's secret, decrypted; `null` when none is set or it cannot be decrypted (the panel key changed). */
+    getSecret(user: User, panel: Panel): Promise<string | null>;
+    saveSecret(user: User, panel: Panel, secret: string | null): Promise<void>;
+    generateSecret(): string;
+    generateRecoveryCodes(): string[];
+    /** Saves recovery codes (hashed): `null` removes them. */
+    saveRecoveryCodes(user: User, panel: Panel, codes: string[] | null): Promise<void>;
+    /** `otpauth://` URI of a secret, for the QR code. */
+    getUri(user: User, panel: Panel, secret: string): string;
+    /** QR code of a secret, as a `data:` URI. */
+    generateQrCodeDataUri(user: User, panel: Panel, secret: string): string;
+    /**
+     * Checks a code. With `preventReuse` (sign-in and sensitive actions), a code is accepted once: the time step of the last
+     * accepted code is remembered, and that code and every earlier one are refused (RFC 6238 §5.2).
+     */
+    verifyCode(code: unknown, secret: string, options?: {
+        preventReuse?: boolean;
+    }): Promise<boolean>;
+    /** Checks a recovery code and removes it: each one works once. */
+    verifyRecoveryCode(code: unknown, user: User, panel: Panel): Promise<boolean>;
+    getChallengeFormComponents(user: User, panel: Panel): Component[];
+    getManagementSchemaComponents(user: User, panel: Panel): Component[];
+    getActions(user: User, panel: Panel): Action[];
+    /** Setup modal: QR code and secret, a code from the app (and the password), then the recovery codes. */
+    setUpAction(panel: Panel): Action;
+    /** Recovery codes, with "copy" and "download" links. */
+    protected recoveryCodesContent(codes: (ctx: ComponentContext) => string[], instruction: string): Component[];
+    /** Fields confirming a sensitive action: a code from the app (or a recovery code) and, optionally, the password. */
+    protected confirmationFields(panel: Panel, group: string, options: {
+        recoveryCodes: boolean;
+    }): Component[];
+    /** Turns app authentication off, after a code (or a recovery code) and the password. */
+    disableAction(panel: Panel): Action;
+    /** Replaces the recovery codes, after a code from the app and the password; the new codes are shown once. */
+    regenerateRecoveryCodesAction(panel: Panel): Action;
+    /** Shows recovery codes just generated; only opened by `regenerateRecoveryCodesAction()`. */
+    showNewRecoveryCodesAction(panel: Panel): Action;
+}
+/** A registered security key or passkey. */
+export type SecurityKey = {
+    id: string | number;
+    name: string;
+    credentialId: string;
+    publicKey: string;
+    algorithm: number;
+    signCount: number;
+    transports: string[];
+    createdAt: string | null;
+    lastUsedAt: string | null;
+};
+/** Where security keys are kept; by default, the panel's auth provider (`knexAuthProvider` uses a `security_keys` table). */
+export type SecurityKeyStore = Required<Pick<AuthProvider, 'getSecurityKeys' | 'createSecurityKey' | 'updateSecurityKey' | 'deleteSecurityKey'>>;
+/** Field running a WebAuthn ceremony in the browser; its state is the credential (JSON) the browser returns. */
+export declare class SecurityKeyInput extends Field {
+    protected _mode: 'register' | 'authenticate';
+    protected _optionsUsing: ((field: SecurityKeyInput) => MaybePromise<Record<string, unknown> | null>) | null;
+    protected _submitOnSuccess: boolean;
+    protected _autoStart: boolean;
+    protected _buttonLabel: string | null;
+    static make(name: string): SecurityKeyInput;
+    /** `register`: adds a key (`navigator.credentials.create()`); `authenticate`: uses one (`navigator.credentials.get()`). */
+    mode(mode: 'register' | 'authenticate'): this;
+    /** Options of the ceremony, asked for by the browser when the user clicks the button. */
+    optionsUsing(callback: (field: SecurityKeyInput) => MaybePromise<Record<string, unknown> | null>): this;
+    /** Submits the form as soon as the key answered. */
+    submitOnSuccess(condition?: boolean): this;
+    /** Starts the ceremony when the field appears (browsers may still require a click). */
+    autoStart(condition?: boolean): this;
+    buttonLabel(label: string | null): this;
+    getExposedMethods(): string[];
+    getPublicKeyOptions(): Promise<Record<string, unknown> | null>;
+    hydrateState(value: unknown): unknown;
+    toHtml(): Promise<string>;
+}
+/**
+ * Authentication with a security key: a hardware key (YubiKey, Titan…) or a passkey stored by the device or a password
+ * manager (WebAuthn). Users can register several keys. Needs a secure context: HTTPS, or `localhost` in development.
+ */
+export declare class SecurityKeyAuthentication implements MultiFactorAuthenticationProvider {
+    protected _id: string;
+    protected _rpId: string | null;
+    protected _rpName: string | null;
+    protected _origins: string[] | null;
+    protected _userVerification: UserVerification;
+    protected _authenticatorAttachment: 'platform' | 'cross-platform' | null;
+    protected _residentKey: 'required' | 'preferred' | 'discouraged';
+    protected _timeout: number;
+    protected _maxKeys: number;
+    protected _store: SecurityKeyStore | null;
+    protected _cacheStore: MultiFactorCacheStore | null;
+    protected _confirmsPassword: boolean;
+    protected throttle: Throttle;
+    static make(): SecurityKeyAuthentication;
+    getId(): string;
+    id(id: string): this;
+    getLoginFormLabel(): string;
+    /** Relying party id: the domain the keys are bound to (by default, the host of `panel.appUrl()` or of the request). */
+    relyingPartyId(id: string | null): this;
+    /** Name shown by the browser while registering a key (the panel's brand name by default). */
+    relyingPartyName(name: string | null): this;
+    /** Origins allowed to use the keys (`https://admin.example.com`); by default, the origin of `panel.appUrl()` or of the request. */
+    origins(origins: string[] | null): this;
+    /** `required`: the key must check a PIN or biometrics; `preferred` (default): when it can. */
+    userVerification(requirement: UserVerification): this;
+    /** Restricts registration to keys built into the device (`platform`) or to removable ones (`cross-platform`). */
+    authenticatorAttachment(attachment: 'platform' | 'cross-platform' | null): this;
+    /** Asks for a discoverable credential (passkey) when registering. */
+    residentKey(requirement: 'required' | 'preferred' | 'discouraged'): this;
+    /** Milliseconds the browser waits for the key (2 minutes by default). */
+    timeout(milliseconds: number): this;
+    /** Keys a user may register (10 by default). */
+    maxKeys(count: number): this;
+    store(store: SecurityKeyStore | null): this;
+    /** Where pending challenges are kept between the two requests of a ceremony. */
+    cacheStore(store: MultiFactorCacheStore | null): this;
+    /** `false`: adding and removing keys do not ask for the current password. */
+    confirmsPassword(condition?: boolean): this;
+    protected getStore(panel: Panel): SecurityKeyStore;
+    checkConfiguration(panel: Panel): void;
+    getKeys(user: User, panel: Panel): Promise<SecurityKey[]>;
+    isEnabled(user: User, panel: Panel): Promise<boolean>;
+    /** Relying party of a request: its id (domain) and allowed origins. */
+    getRelyingParty(panel: Panel, req: {
+        protocol?: string;
+        hostname?: string;
+        get?: (name: string) => string | undefined;
+    } | undefined): {
+        id: string;
+        name: string;
+        origins: string[];
+    };
+    private cache;
+    /** A new challenge, remembered for this user and purpose until it is used or expires. */
+    protected issueChallenge(user: User, panel: Panel, purpose: 'register' | 'authenticate'): Promise<string>;
+    /** The challenge a response answers, if it was issued for this user and purpose; it is consumed (single use). */
+    protected consumeChallenge(response: any, user: User, panel: Panel, purpose: 'register' | 'authenticate'): Promise<string | null>;
+    protected requestOf(field: {
+        livewire: unknown;
+    }): any;
+    /** Checks an assertion from the browser against the user's keys; updates the key's counter. */
+    verifyAssertion(value: unknown, user: User, panel: Panel, req: any): Promise<boolean>;
+    getChallengeFormComponents(user: User, panel: Panel): Component[];
+    getManagementSchemaComponents(user: User, panel: Panel): Component[];
+    /** Adds a key: a name, the ceremony in the browser, and the password. */
+    registerAction(panel: Panel): Action;
+    /** Removes one of the user's keys, after the password. */
+    removeAction(panel: Panel): Action;
+}
+/** Where the email authentication flag is kept; by default, the panel's auth provider (`knexAuthProvider`: `has_email_authentication`). */
+export type EmailAuthenticationStore = Required<Pick<AuthProvider, 'hasEmailAuthentication' | 'saveEmailAuthentication'>>;
+/** One-time code field with a "Send a new code by email" link, which asks the server for another code. */
+export declare class EmailCodeInput extends OneTimeCodeInput {
+    protected _resend: ((field: EmailCodeInput) => MaybePromise<void>) | null;
+    protected _resendLabel: string;
+    static make(name: string): EmailCodeInput;
+    /** What the link does (send a new code); without it, there is no link. */
+    resendUsing(callback: ((field: EmailCodeInput) => MaybePromise<void>) | null, label?: string): this;
+    getExposedMethods(): string[];
+    isRenderlessMethod(): boolean;
+    resendCode(): Promise<void>;
+}
+/**
+ * Authentication with a 6-digit code sent to the user's email address, through the panel's `mailer()`.
+ * A code is valid for a few minutes (4 by default) and once; at most two codes are sent per minute.
+ */
+export declare class EmailAuthentication implements MultiFactorAuthenticationProvider {
+    protected _id: string;
+    protected _codeExpiryMinutes: number;
+    protected _generateCode: (() => string) | null;
+    protected _store: EmailAuthenticationStore | null;
+    protected _cacheStore: MultiFactorCacheStore | null;
+    protected _sendCode: ((user: User, code: string, minutes: number, panel: Panel) => MaybePromise<void>) | null;
+    protected sendThrottle: Throttle;
+    protected managementThrottle: Throttle;
+    static make(): EmailAuthentication;
+    getId(): string;
+    id(id: string): this;
+    getLoginFormLabel(): string;
+    /** Minutes a code stays valid. */
+    codeExpiryMinutes(minutes: number): this;
+    getCodeExpiryMinutes(): number;
+    /** Generates the codes (6 random digits by default). */
+    generateCodeUsing(callback: (() => string) | null): this;
+    generateCode(): string;
+    /** Sends the code yourself (SMS gateway, your own email template…) instead of the panel's mailer. */
+    sendCodeUsing(callback: ((user: User, code: string, minutes: number, panel: Panel) => MaybePromise<void>) | null): this;
+    store(store: EmailAuthenticationStore | null): this;
+    /** Where pending codes are kept until they are used or expire. */
+    cacheStore(store: MultiFactorCacheStore | null): this;
+    protected getStore(panel: Panel): EmailAuthenticationStore;
+    checkConfiguration(panel: Panel): void;
+    isEnabled(user: User, panel: Panel): Promise<boolean>;
+    setEnabled(user: User, panel: Panel, enabled: boolean): Promise<void>;
+    private cache;
+    private codeKey;
+    /** Sends a new code (the previous one stops working). Returns `false` when two codes were already sent this minute. */
+    sendCode(user: User, panel: Panel): Promise<boolean>;
+    /** Checks a code against the last one sent; a valid code is consumed. */
+    verifyCode(code: unknown, user: User, panel: Panel): Promise<boolean>;
+    beforeChallenge(user: User, panel: Panel): Promise<void>;
+    /** Sends a new code and tells the user (or that they must wait). */
+    protected resend(user: User, panel: Panel, group: string): Promise<void>;
+    getChallengeFormComponents(user: User, panel: Panel): Component[];
+    /** Code field of the setup and disable modals: the signed-in user's code, rate limited. */
+    protected modalCodeInput(panel: Panel, group: string): EmailCodeInput;
+    getManagementSchemaComponents(user: User, panel: Panel): Component[];
+    /** Sends a code when the modal opens; entering it turns email codes on. */
+    setUpAction(panel: Panel): Action;
+    /** Sends a code when the modal opens; entering it turns email codes off. */
+    disableAction(panel: Panel): Action;
+}
+export {};