@rapidrest/auth 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Jean-Philippe Steinmetz <caskater47@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# RapidREST: Authentication Library
+
+A library for implementing a complete authentication server with [RapidREST](https://rapidrest.dev). It
+provides the data models, persistence adapters, and HTTP routes needed to register and authenticate users via
+password, TOTP, OTP (email/SMS), WebAuthn passkeys, FIDO2 hardware security keys, multi-factor authentication, and
+OpenID Connect / OAuth 2.0. Using this library you can stand up a fully featured authorization server by writing
+configuration and a handful of one-line route classes.
+
+## Features
+
+### Authentication Strategies:
+
+* `BasicStrategy` - Simple id and password authentication
+* `FIDO2Strategy` - FIDO2/WebAuthn hardware based authentication (e.g. YubiKey)
+* `MFAStrategy` - Simple id and password + 2FA authentication [fido2|otp|totp]
+* `OIDCStrategy` - OAuth 2.0 & OpenID Connect authentication
+* `OTPStrategy` - One-Time Password (OTP) authentication (e.g. email, sms)
+* `PasskeyStrategy` - WebAuthn based passkey authentication
+* `TOTPStrategy` - RFC 6238 Time-Based One Time Password authentication (e.g. Google Authenticator, etc.)
+
+### Data Models
+
+This library provides variants of each of the following data models that can be used against a MongoDB or SQL database. Classes are post-fixed
+with either `Mongo` or `SQL` at the end of the name (e.g. `Alias` becomes `AliasMongo` for MongoDB, `AliasSQL` for SQL).
+
+* `User` - Describes a single user account
+* `Alias` - Describes an alternate identifying name (aka: alias) for a user account (e.g. email, phone, third-party OAuth ID)
+* `Secret` - Stores secrets used to authenticate user accounts (e.g. `fido2`, `passkey`, `password`, `totp` secrets)
+* `Profile` - Stores additional, personally identifying, information about a user (e.g. birthdate, legal name, verified contacts, preferences)
+
+### Route Handlers
+
+This library provides variants of each of the following routes that can be used against a MongoDB or SQL database. Classes are post-fixed
+with either `Mongo` or `SQL` at the end of the name (e.g. `BaseAliasRoute` becomes `BaseAliasRouteMongo` for MongoDB, `BaseAliasRouteSQL` for SQL).
+
+#### Data Models
+
+* `BaseAliasRoute` - Provides full CRUD operations for the `Alias` data model
+* `BaseProfileRoute` - Provides full CRUD operations for the `Profile` data model
+* `BaseSecretRoute` - Provides full CRUD operations for the `Secret` data model. Additionally includes endpoints for registration of 
+`fido2`, `passkey` and `totp` secrets.
+* `BaseUserRoute` - Provides full CRUD operations for the `User` data model
+
+#### Authentication Strategies
+
+* `BaseAuthBasicRoute` - Implements the `BasicStrategy` authentication strategy
+* `BaseAuthFIDO2Route` - Implements the `FIDO2Strategy` authentication strategy
+* `BaseAuthMFARoute` - Implements the `MFAStrategy` authentication strategy
+* `BaseAuthOIDCRoute` - Implements the `OIDCStrategy` authentication strategy
+* `BaseAuthOTPRoute` - Implements the `OTPStrategy` authentication strategy
+* `BaseAuthPasskeyRoute` - Implements the `PasskeyStrategy` authentication strategy
+* `BaseAuthTOTPRoute` - Implements the `TOTPStrategy` authentication strategy
+
+## Requirements
+
+This package targets Node.js `>=24.0.0` and is published as an ESM-only package.
+
+It declares `@rapidrest/core` and `@rapidrest/service-core` as required peer dependencies. The remaining peer
+dependencies are optional and only need to be installed if you use the corresponding feature:
+
+| Peer dependency | Required for |
+| --- | --- |
+| `@rapidrest/core` | Always |
+| `@rapidrest/service-core` | Always |
+| `argon2` | Password (`Basic`, `MFA`) secrets — password hashing |
+| `otplib` | `TOTP`, `OTP`, and `MFA` secrets/strategies |
+| `@simplewebauthn/server` | `Passkey` and `FIDO2` strategies |
+| `jwks-rsa` | Verifying `OIDC` providers that publish a JWKS endpoint |
+
+Strategies dynamically `import()` their optional dependency the first time they're used and throw a descriptive
+error (naming the missing package) if it isn't installed, rather than failing at package install time.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/lib/auth/BasicStrategy.js

@@ -0,0 +1,82 @@
+import { getRequestData } from "./shared.js";
+/**
+ * Describes the configuration options that can be used to initialize BasicStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class BasicStrategyOptions {
+    constructor() {
+        /** The name of the header to look for when performing header based authentication. Default value is `Authorization`. */
+        this.headerKey = "authorization";
+        /** The authorization scheme type when using header based authentication. Default value is `jwt`. */
+        this.headerScheme = "basic";
+        /** The name of the request query parameter to retrieve the token from when using query based authentication. Default value is `auth_basic`. */
+        this.queryKey = "auth_basic";
+        /**
+         * Set to `true` to allow credentials to be supplied via the `queryKey` URL parameter.
+         * Disabled by default — query parameters appear in server logs, browser history, and
+         * Referer headers, which permanently exposes credentials outside the application.
+         */
+        this.allowQueryParam = false;
+    }
+    /** Override this function to handle asynchronous (non-blocking) verification of the login info. */
+    verify(uid, secret) {
+        throw new Error("Did you forget to override BasicStrategyOptions.verify?");
+    }
+    /** Override this function to handle synchronous (blocking) verification of the login info. */
+    verifySync(uid, secret) {
+        throw new Error("Did you forget to override BasicStrategyOptions.verifySync?");
+    }
+}
+/**
+ * Implements an authentication strategy that performs basic id and password authentication. This strategy requires an
+ * existing user account to have already registered a valid password that will be validated. The strategy does not
+ * implement how that password is to be validated or stored.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export class BasicStrategy {
+    constructor(options = new BasicStrategyOptions()) {
+        this.name = "basic";
+        this.options = options;
+    }
+    async authenticate(req, res, required) {
+        let { data, payload } = getRequestData(req);
+        // If the login info has been found, verify it.
+        if (payload.id && payload.password) {
+            const user = await this.options.verify(payload.id, payload.password);
+            if (user) {
+                return {
+                    data,
+                    method: this.name,
+                    payload,
+                    user,
+                };
+            }
+        }
+        if (required) {
+            throw new Error("Invalid authorization request.");
+        }
+        return undefined;
+    }
+    authenticateSync(req, res, required) {
+        let { data, payload } = getRequestData(req);
+        // If the login info has been found, verify it.
+        if (payload.id && payload.password) {
+            const user = this.options.verifySync(payload.id, payload.password);
+            if (user) {
+                return {
+                    data,
+                    method: this.name,
+                    payload,
+                    user,
+                };
+            }
+        }
+        if (required) {
+            throw new Error("Invalid authorization request.");
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=BasicStrategy.js.map

package/dist/lib/auth/BasicStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicStrategy.js","sourceRoot":"","sources":["../../../src/auth/BasicStrategy.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IAAjC;QACI,wHAAwH;QACjH,cAAS,GAAW,eAAe,CAAC;QAC3C,oGAAoG;QAC7F,iBAAY,GAAW,OAAO,CAAC;QACtC,+IAA+I;QACxI,aAAQ,GAAW,YAAY,CAAC;QACvC;;;;WAIG;QACI,oBAAe,GAAY,KAAK,CAAC;IAS5C,CAAC;IARG,mGAAmG;IAC5F,MAAM,CAAC,GAAW,EAAE,MAAc;QACrC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC/E,CAAC;IACD,8FAA8F;IACvF,UAAU,CAAC,GAAW,EAAE,MAAc;QACzC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACnF,CAAC;CACJ;AAED;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IAItB,YAAY,UAAgC,IAAI,oBAAoB,EAAE;QAHtD,SAAI,GAAW,OAAO,CAAC;QAInC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAEM,KAAK,CAAC,YAAY,CACrB,GAAgB,EAChB,GAAiB,EACjB,QAAkB;QAElB,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QAE5C,+CAA+C;QAC/C,IAAI,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,GAAwB,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC1F,IAAI,IAAI,EAAE,CAAC;gBACP,OAAO;oBACH,IAAI;oBACJ,MAAM,EAAE,IAAI,CAAC,IAAI;oBACjB,OAAO;oBACP,IAAI;iBACP,CAAC;YACN,CAAC;QACL,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC;IAEM,gBAAgB,CAAC,GAAgB,EAAE,GAAiB,EAAE,QAAkB;QAC3E,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QAE5C,+CAA+C;QAC/C,IAAI,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,GAAwB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YACxF,IAAI,IAAI,EAAE,CAAC;gBACP,OAAO;oBACH,IAAI;oBACJ,MAAM,EAAE,IAAI,CAAC,IAAI;oBACjB,OAAO;oBACP,IAAI;iBACP,CAAC;YACN,CAAC;QACL,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ"}

package/dist/lib/auth/FIDO2Strategy.js

@@ -0,0 +1,179 @@
+import { generatePasskeyChallenge, isPasskeyResponse, verifyPasskeyChallenge } from "./shared.js";
+/**
+ * Describes the configuration options that can be used to initialize FIDO2Strategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class FIDO2StrategyOptions {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Retrieves a previously-registered credential by its ID. Returns `undefined` if no credential
+     * with that ID is known.
+     * NOTE: You must override this function when using this strategy.
+     */
+    async getCredentialById(credentialId) {
+        throw new Error("Did you forget to override FIDO2StrategyOptions.getCredentialById?");
+    }
+    /**
+     * Retrieves all credentials registered for the given user. Used to build the `allowCredentials`
+     * list when a login ceremony is started with a known user hint.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique identifier of the user or alias.
+     */
+    async getCredentials(id) {
+        throw new Error("Did you forget to override FIDO2StrategyOptions.getCredentials?");
+    }
+    /**
+     * Persists the updated signature counter for the given credential after a successful
+     * authentication. Must be called on every successful login to guard against cloned authenticators.
+     * NOTE: You must override this function when using this strategy.
+     */
+    async updateCredentialCounter(credentialId, newCounter) {
+        throw new Error("Did you forget to override FIDO2StrategyOptions.updateCredentialCounter?");
+    }
+    /**
+     * Retrieves the user data for the given unique identifier after authentication has completed successfully.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique identifier of the user that has been successfully authenticated.
+     */
+    getUser(uid) {
+        throw new Error("Did you forget to override FIDO2StrategyOptions.getUser?");
+    }
+}
+/**
+ * Implements an authentication strategy for performing FIDO2 hardware security key (e.g. YubiKey)
+ * login via WebAuthn/CTAP2. Functionally this is the same WebAuthn protocol used by `PasskeyStrategy`
+ * — the distinction is one of intent and configuration (see `PasskeyConfig.authenticatorAttachment`/
+ * `residentKey`): a FIDO2 hardware key is typically registered as a `"cross-platform"`, non-discoverable
+ * credential tied to a known account, rather than a discoverable, possibly-synced passkey.
+ *
+ * The login flow has two phases:
+ *
+ * 1. Challenge - The client requests a challenge. A random challenge is generated and stored in the
+ * session, and the resulting options are returned for use with
+ * `navigator.credentials.get()`.
+ * 2. Verify - The client submits the signed assertion response. The response is verified against the
+ * stored challenge and the credential's public key, the credential's signature counter is updated,
+ * and the associated user is resolved via `verify()`.
+ *
+ * NOTE: Requires session support!
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export class FIDO2Strategy {
+    constructor(options) {
+        this.name = "fido2";
+        this.options = options;
+    }
+    async authenticate(req, res, required) {
+        if (req.body?.id || req.body?.response) {
+            return await this.verify(req, required);
+        }
+        else {
+            return await this.challenge(req, res);
+        }
+    }
+    authenticateSync(req, res, required) {
+        throw new Error("Not supported. This auth strategy must be used asynchronously.");
+    }
+    /**
+     * Begins a login ceremony: generates a challenge, stores it in the session, and writes the
+     * resulting options directly to the response for the client to pass to `navigator.credentials.get()`.
+     *
+     * @param req The source HTTP request. May optionally carry a `uid` query parameter to scope the
+     * allowed credentials to a known user; omitted entirely for a discoverable/"usernameless" flow.
+     * @param res The response to write the generated options to.
+     */
+    async challenge(req, res) {
+        if (!req.session) {
+            throw new Error("FIDO2Strategy requires session support. Configure the `session` config block so the " +
+                "session middleware is registered.");
+        }
+        if (!res) {
+            throw new Error("FIDO2Strategy requires a response object to begin a ceremony.");
+        }
+        // If a uid hint is given, scope allowCredentials to that user's registered credentials. If
+        // the hint resolves to zero credentials, allowCredentials is left undefined (same as the
+        // no-hint case) rather than sent as an empty list. Otherwise the response shape would leak
+        // whether a given uid has any passkeys registered, a user-enumeration side channel.
+        const uidHint = req.query?.uid;
+        let allowCredentials = undefined;
+        if (uidHint) {
+            const credentials = await this.options.getCredentials(uidHint);
+            if (credentials.length > 0) {
+                allowCredentials = credentials.map((c) => ({ id: c.id, transports: c.transports }));
+            }
+        }
+        const result = await generatePasskeyChallenge(this.options.config, req, allowCredentials);
+        res.status(200);
+        res.json(result);
+        return undefined;
+    }
+    /**
+     * Finishes a login ceremony: verifies the client-submitted assertion response against the
+     * stored challenge and credential, updates the credential's signature counter, and resolves the
+     * associated user.
+     *
+     * @param req The source HTTP request, carrying the assertion response in its body.
+     * @param required Set to `true` if authentication is required to pass, otherwise set to `false`.
+     */
+    async verify(req, required) {
+        if (!req.session) {
+            throw new Error("FIDO2Strategy requires session support. Configure the `session` config block so the " +
+                "session middleware is registered.");
+        }
+        if (!req.session.challenge) {
+            throw new Error("No FIDO2 ceremony in progress for this session.");
+        }
+        // The challenge is single-use regardless of outcome — cleared as soon as it's read, before
+        // verification is even attempted, rather than only on the success path.
+        const expectedChallenge = req.session.challenge;
+        delete req.session.challenge;
+        // Strict shape validation before touching storage or SimpleWebAuthn — a malformed finish
+        // attempt should fail with a clean, actionable error rather than crashing deep inside the
+        // verification library with a confusing low-level error. This alone doesn't reveal whether
+        // any particular account/credential exists, so it's kept distinct from the generic failure
+        // message below.
+        if (!isPasskeyResponse(req.body)) {
+            throw new Error("Malformed FIDO2 authentication response.");
+        }
+        // Every failure from here on is reported with the same generic message, regardless of
+        // whether the credential ID is unknown, the signature failed to verify, the counter
+        // regressed, or the resolved user was rejected by verify() — distinguishing between these
+        // would let a caller enumerate which credential IDs/accounts are registered on this server.
+        const genericFailure = () => new Error("FIDO2 authentication failed.");
+        const credential = await this.options.getCredentialById(req.body.id);
+        if (!credential) {
+            throw genericFailure();
+        }
+        const result = await verifyPasskeyChallenge(credential, this.options.config, expectedChallenge, req.body);
+        if (!result.verified) {
+            throw genericFailure();
+        }
+        // Counter regression check. SimpleWebAuthn deliberately does not enforce counter monotonicity
+        // itself — the signal of a cloned authenticator per the WebAuthn spec's guidance is a
+        // non-zero counter that fails to exceed the stored value (many FIDO2 authenticators always
+        // report a strictly incrementing counter, unlike some multi-device passkeys which report 0).
+        const newCounter = result.authenticationInfo.newCounter;
+        if (newCounter !== 0 && newCounter <= credential.counter) {
+            throw genericFailure();
+        }
+        await this.options.updateCredentialCounter(credential.id, newCounter);
+        const user = await this.options.getUser(credential.uid);
+        if (user) {
+            return {
+                data: req.body,
+                method: this.name,
+                payload: result.authenticationInfo,
+                user,
+            };
+        }
+        if (required) {
+            throw genericFailure();
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=FIDO2Strategy.js.map

package/dist/lib/auth/FIDO2Strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FIDO2Strategy.js","sourceRoot":"","sources":["../../../src/auth/FIDO2Strategy.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/MFAStrategy.js

@@ -0,0 +1,219 @@
+import { generateOTP, generatePasskeyChallenge, getBasicData, getRequestData, isOTPResponse, isPasskeyResponse, verifyOTP, } from "./shared.js";
+/**
+ * The different types of secondary authentication methods.
+ */
+export var MFAMethodType;
+(function (MFAMethodType) {
+    MFAMethodType["FIDO2"] = "fido2";
+    MFAMethodType["OTP"] = "otp";
+    MFAMethodType["TOTP"] = "totp";
+})(MFAMethodType || (MFAMethodType = {}));
+/**
+ * Describes the configuration options that can be used to initialize MFAStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class MFAStrategyOptions {
+    constructor() {
+        /** The name of the header to look for when performing header based authentication. Default value is `Authorization`. */
+        this.headerKey = "authorization";
+        /** The authorization scheme type when using header based authentication. Default value is `basic`. */
+        this.headerScheme = "basic";
+        /**
+         * Set to `true` to require that user's must provide secondary authentication to succeed, otherwise set to
+         * `false`. Default is `true`.
+         */
+        this.require2FA = true;
+    }
+    /**
+     * Retrieves the user's secondary authentication method for a given id.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique id of the secondary auth method to retrieve.
+     */
+    getMethod(id) {
+        throw new Error("Did you forget to override MFAStrategyOptions.getContact?");
+    }
+    /**
+     * Retrieves the list of secondary authentication methods for the user with the given id.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique id of the user.
+     */
+    getMethods(id) {
+        throw new Error("Did you forget to override MFAStrategyOptions.getContacts?");
+    }
+    /**
+     * Retrieves the user data for the given unique identifier after authentication has completed successfully.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique identifier of the user that has been successfully authenticated.
+     */
+    getUser(uid) {
+        throw new Error("Did you forget to override MFAStrategyOptions.getUsers?");
+    }
+    /**
+     * Sends a notification to the specified contact with the provided MFA code.
+     * NOTE: You must override this function when using this strategy.
+     * @param contact The contact to send the MFA code to.
+     * @param totp The MFA code to send to the user.
+     */
+    notifyContact(contact, totp) {
+        throw new Error("Did you forget to override MFAStrategyOptions.notify?");
+    }
+    /**
+     * Called to verify the provided user's id and password.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique id of the user whose password must be verified.
+     * @param password The password of the user to verify.
+     * @returns The successfully verified user data, otherwise `undefined`.
+     */
+    verify(id, password) {
+        throw new Error("Did you forget to override MFAStrategyOptions.verify?");
+    }
+}
+/**
+ * Implements a multi-factory authentication (MFA) strategy that performs basic id and password verification, followed
+ * by a secondary authentication. This strategy requires an existing user account to have already registered a valid
+ * password that will be validated as well as at least one secondary authentication method.
+ *
+ * Supported secondary authentication (2FA) methods:
+ *
+ * * `FIDO2` - A hardware-based key challenge exchange that the user has access to (e.g. Yubikey, Passkey, etc).
+ * * `OTP` - A One Time Password (OTP) sent to one of the user's verified contacts.
+ * * `TOTP` - A Time-Based One Time Password (TOTP) configured on a device the user owns or has access to.
+ *
+ * The login flow has three phases:
+ *
+ * 1. Verify Basic - The client sends a request with `Authorization` header containing the user's id and password. The
+ * server returns with a list of available secondary authentication methods.
+ * 2. Challenge - The client requests a selected 2FA challenge. If a `TOTP` 2FA method is chosen, the request is
+ * processed as phase 3. For all others, a challenge is generated and stored in the session. If `OTP` is selected,
+ * a notification containing the challenge token is sent to the selected verified contact.
+ * 3. Verify - The client submits the completed 2FA challenge. The challenge is verified against the one stored in the
+ * session, and the associated user is resolved using the `getUser()` callback.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export class MFAStrategy {
+    constructor(options) {
+        this.name = "mfa";
+        this.options = options;
+    }
+    async authenticate(req, res, required) {
+        const { data, payload } = getRequestData(req);
+        if (isOTPResponse(payload)) {
+            const user = await this.verifyOTP(payload, req, res);
+            if (user) {
+                return {
+                    data,
+                    method: this.name,
+                    payload,
+                    user,
+                };
+            }
+        }
+        else if (isPasskeyResponse(payload)) {
+            const user = await this.verifyFIDO(payload, req, res);
+            if (user) {
+                return {
+                    data,
+                    method: this.name,
+                    payload,
+                    user,
+                };
+            }
+        }
+        else if (payload.id && payload.password) {
+            const user = await this.verifyBasic(req, res);
+            if (user) {
+                return {
+                    data,
+                    method: this.name,
+                    payload,
+                    user,
+                };
+            }
+        }
+        else if (payload.id && payload.methodId) {
+            await this.challenge(payload, req, res);
+            return undefined;
+        }
+        if (required) {
+            throw new Error("Invalid authentication request.");
+        }
+        return undefined;
+    }
+    authenticateSync(req, res, required) {
+        throw new Error("Not supported. This auth strategy must be used asynchronously.");
+    }
+    async challenge(payload, req, res) {
+        if (!req.session) {
+            throw new Error("MFAStrategy requires session support. Configure the `session` config block so the " +
+                "session middleware is registered.");
+        }
+        const method = await this.options.getMethod(payload.methodId);
+        if (!method) {
+            throw new Error("Invalid secondary authentication method.");
+        }
+        // Store the method ID used in the session
+        req.session.methodId = method.id;
+        switch (method.type) {
+            case MFAMethodType.FIDO2:
+                {
+                    if (!this.options.fidoConfig) {
+                        throw new Error("No configuration exists for MFA method: FIDO2");
+                    }
+                    const result = await generatePasskeyChallenge(this.options.fidoConfig, req);
+                    res.status(200);
+                    res.json(result);
+                }
+                break;
+            case MFAMethodType.OTP:
+                {
+                    const totp = await generateOTP(req, payload);
+                    await this.options.notifyContact(method.data, totp);
+                    res.status(200);
+                    res.json({});
+                }
+                break;
+            default:
+                throw new Error("Unsupported MFA method: " + method.type);
+        }
+    }
+    async verifyBasic(req, res) {
+        const requestData = getBasicData(req);
+        if (!requestData || !requestData.id || !requestData.password) {
+            throw new Error("Invalid user id or password.");
+        }
+        // Verify the id and password
+        const user = await this.options.verify(requestData.id, requestData.password);
+        if (user) {
+            // Now retrieve the user's list of available 2FA methods
+            const methods = await this.options.getMethods(user.uid);
+            if (methods.length > 0) {
+                // Send the list of 2FA methods back to the client to select from
+                res.status(200);
+                res.json(methods);
+                return undefined;
+            }
+            else if (this.options.require2FA) {
+                throw new Error("No secondary authentication methods available.");
+            }
+            return user;
+        }
+        else {
+            throw new Error("Invalid user id or password.");
+        }
+    }
+    async verifyFIDO(payload, req, res) {
+        throw new Error("Not implemented");
+    }
+    async verifyOTP(payload, req, res) {
+        if (!(await verifyOTP(req, payload))) {
+            return undefined;
+        }
+        return await this.options.getUser(payload.id);
+    }
+    async verifyTOTP(payload, req, res) {
+        throw new Error("Not implemented");
+    }
+}
+//# sourceMappingURL=MFAStrategy.js.map

package/dist/lib/auth/MFAStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MFAStrategy.js","sourceRoot":"","sources":["../../../src/auth/MFAStrategy.ts"],"names":[],"mappings":"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"}