@rapidrest/auth 1.0.0-beta.1

package/dist/types/auth/MFAStrategy.d.ts

@@ -0,0 +1,110 @@
+import type { JWTUser } from "@rapidrest/core";
+import { AuthStrategy, HttpRequest, HttpResponse, AuthResult } from "@rapidrest/service-core";
+import { OTPContact, PasskeyConfig } from "./types.js";
+/**
+ * The different types of secondary authentication methods.
+ */
+export declare enum MFAMethodType {
+    FIDO2 = "fido2",
+    OTP = "otp",
+    TOTP = "totp"
+}
+/**
+ * Describes a method for performing the secondary authentication.
+ */
+export interface MFAMethod {
+    /** The unique id of the secondary authentication method. */
+    id: string;
+    /** The method specific data required to perform secondary authentication. */
+    data: any;
+    /** The method type of contact (e.g. email, fido2, sms). */
+    type: MFAMethodType;
+}
+/**
+ * Describes the configuration options that can be used to initialize MFAStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MFAStrategyOptions {
+    /** The name of the header to look for when performing header based authentication. Default value is `Authorization`. */
+    headerKey: string;
+    /** The authorization scheme type when using header based authentication. Default value is `basic`. */
+    headerScheme: string;
+    /**
+     * The FIDO2/Passkey configuration to use when a FIDO2 secondary auth is used.
+     */
+    fidoConfig?: PasskeyConfig;
+    /**
+     * Set to `true` to require that user's must provide secondary authentication to succeed, otherwise set to
+     * `false`. Default is `true`.
+     */
+    require2FA: boolean;
+    /**
+     * 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: string): Promise<MFAMethod | undefined>;
+    /**
+     * 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: string): Promise<MFAMethod[]>;
+    /**
+     * 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: string): Promise<JWTUser | undefined>;
+    /**
+     * 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: OTPContact, totp: string): Promise<void>;
+    /**
+     * 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: string, password: string): Promise<JWTUser | undefined>;
+}
+/**
+ * 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 declare class MFAStrategy implements AuthStrategy {
+    readonly name: string;
+    private options;
+    constructor(options: MFAStrategyOptions);
+    authenticate(req: HttpRequest, res: HttpResponse, required?: boolean): Promise<AuthResult | undefined>;
+    authenticateSync(req: HttpRequest, res: HttpResponse, required?: boolean): AuthResult | undefined;
+    protected challenge(payload: any, req: HttpRequest, res: HttpResponse): Promise<void>;
+    protected verifyBasic(req: HttpRequest, res: HttpResponse): Promise<JWTUser | undefined>;
+    protected verifyFIDO(payload: any, req: HttpRequest, res: HttpResponse): Promise<JWTUser | undefined>;
+    protected verifyOTP(payload: any, req: HttpRequest, res: HttpResponse): Promise<JWTUser | undefined>;
+    protected verifyTOTP(payload: any, req: HttpRequest, res: HttpResponse): Promise<JWTUser | undefined>;
+}

package/dist/types/auth/OIDCStrategy.d.ts

@@ -0,0 +1,188 @@
+import type { JWTUser } from "@rapidrest/core";
+import { AuthStrategy, HttpRequest, HttpResponse, AuthResult } from "@rapidrest/service-core";
+export declare const Protocol: {
+    readonly OAUTH2: "oauth2";
+    readonly OPENID: "openid";
+};
+/**
+ * Describes an authenticated user profile as converted by an OAuth/OpenID provider that is ready to be
+ * used by the system to create a local User and/or Profile.
+ */
+export interface OIDCProfile {
+    /** The unique identifier of the user as registered with the provider. */
+    id: string;
+    /** The unique name of the provider. */
+    provider: string;
+    /** The alias or display name of the user. */
+    alias?: string;
+    /** The URL of the user's avatar image. */
+    avatar?: string;
+    /** The birthdate of the user. */
+    birthdate?: string;
+    /** The email address that the user registered their account with the provider. */
+    email?: string;
+    /** Indicates if the user email address has been verified by the provider. */
+    email_verified?: boolean;
+    /** The real surname name of the user. */
+    familyName?: string;
+    /** The real given name of the user. */
+    givenName?: string;
+    /** The user's chosen language option. */
+    locale?: string;
+    /** The phone number that the user registered their account with the provider. */
+    phone?: string;
+    /** Indicates if the user phone number has been verified by the provider. */
+    phone_verified?: boolean;
+    /** The unique name of the user. */
+    username?: string;
+}
+/** The two PKCE code challenge methods registered by RFC 7636 / the IANA PKCE registry. */
+export type PkceMethod = "S256" | "plain";
+export interface OIDCProvider {
+    /** The unique name of the provider that can be used for authentication. */
+    name: string;
+    /** The URL of the provider's API that will be used to perform authorization requests. */
+    authorizationURL: string;
+    /** The unique identifier that has been provided by the OIDC provider. */
+    clientID: string;
+    /** The shared secret that has been provided by the OIDC provider. */
+    clientSecret: string;
+    /**
+     * Indicates whether PKCE is required by the OIDC provider. Set to `true` to allow either
+     * `S256` or `plain` (the client may choose), or set to `"S256"`/`"plain"` to require that
+     * specific method regardless of what the client requests.
+     */
+    pkce?: boolean | PkceMethod;
+    /**
+     * The default transformation map to use to convert the third-party profile data to an `OIDCProfile`.
+     * Default is `DEFAULT_PROFILE_MAP`.
+     * */
+    profileMap?: any;
+    /** The URL of the provider's API that the user profile can be retrieved from. */
+    profileURL?: string;
+    /** The authentication protocol to use (e.g. OIDC 2.0 or Open ID). */
+    protocol: string;
+    /**
+     * The callback URI (or list of allowed callback URIs) that have been registered with the OIDC
+     * provider. A caller may request a specific `redirect_uri` via query parameter, but only a value
+     * that exactly matches one of these is honored — anything else is rejected.
+     */
+    redirectURI: string | string[];
+    /** The list of scopes to request during the authentication process. Default is `none`. */
+    scope?: string[];
+    /** The URL of the provider's API that will perform token exchange. */
+    tokenURL: string;
+    /**
+     * The provider's JWKS endpoint, used to verify ID token signatures. Required when `protocol`
+     * is `openid` and the provider returns an `id_token`.
+     */
+    jwksURI?: string;
+    /**
+     * The expected `iss` claim of ID tokens from this provider. Required when `protocol` is
+     * `openid` and the provider returns an `id_token`.
+     */
+    issuer?: string;
+}
+/**
+ * Describes the configuration options that can be used to initialize OIDCStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class OIDCStrategyOptions {
+    /** The unique name of the auth strategy instance. */
+    name: string;
+    /**
+     * The configuration of the OIDC/OpenID provider.
+     */
+    provider: OIDCProvider;
+    /**
+     * 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 token The user's authenticated access token to the third-party provider.
+     * @param profile The user's profile data associated with the third-party provider.
+     */
+    getUser(token: string, profile: OIDCProfile): Promise<JWTUser | undefined>;
+    constructor(name: string, provider: OIDCProvider);
+}
+export declare const DEFAULT_PROFILE_MAP: any;
+/**
+ * Implements an authentication strategy for performing OIDC 2.0 or OpenID Connect (OIDC) authorization with a
+ * third-party provider. This strategy does not require that require an account already be registered. When using
+ * this strategy, ensure to allow for account creation to occur after a successful login.
+ *
+ * The authorization flow has the following steps:
+ *
+ * 1. Client initiates a request for an Authorization Request URI. Builds the Authorization Request URI and returns it
+ * to the client.
+ * 2. The client should automatically redirect the user to the Authorization Request URI obtained in step 1.
+ * 3. Once the user has approved the authorization request with the third-party provider the client will be
+ * redirected to the application's registered callback URL with a single query parameter containing an
+ * Authorization Code. The client initiates a request to a route handler, containing the code, and then
+ * calls `authenticate()`.
+ *
+ * NOTE: Requires session support!
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class OIDCStrategy implements AuthStrategy {
+    readonly name: string;
+    private options;
+    /** Cached `jwks-rsa` clients, keyed by JWKS URI, so keys are cached across requests. */
+    private jwksClients;
+    constructor(options: OIDCStrategyOptions);
+    /**
+     * Resolves the effective PKCE code challenge method to use, given what the provider requires
+     * (if anything specific) and what the client requested. Throws if the client requests an
+     * invalid value, or a value that conflicts with a provider-mandated method.
+     *
+     * @param clientMethod The `code_challenge_method` requested by the client, if any.
+     */
+    protected resolvePkceMethod(clientMethod?: string): PkceMethod;
+    /**
+     * Creates and returns the Authorization Request URI for the configured OIDC provider.
+     *
+     * @param req The source HTTP request.
+     * @param redirectURI The source URI to redirect the user to once authentication is complete.
+     */
+    protected buildAuthorizationURI(req: HttpRequest, redirectURI?: string): string;
+    authenticate(req: HttpRequest, res: HttpResponse, required?: boolean): Promise<AuthResult | undefined>;
+    authenticateSync(req: HttpRequest, res: HttpResponse, required?: boolean): AuthResult | undefined;
+    /**
+     * Performs a request against the OIDC provider to exchange the given authorization code for an access token.
+     *
+     * @param req The request data to use in the exchange exchange.
+     * @param provider The OIDC provider to perform the exchange with.
+     */
+    protected exchangeOIDCCode(req: HttpRequest): Promise<any>;
+    /**
+     * Converts the given user profile obtained from the specified OAuth provider into an OIDCProfile object.
+     *
+     * @param profile The profile to convert.
+     * @param provider The OAuth provider that the profile was obtained from.
+     */
+    protected convertProfile(profile: any): OIDCProfile;
+    /**
+     * Retrieves the user profile from the specified OIDC provider using the given access token.
+     * @param token The access token to use to retrieve the user profile.
+     * @param req The source HTTP request, used to validate the id_token's nonce claim.
+     */
+    protected retrieveUserProfile(token: any, req: HttpRequest): Promise<OIDCProfile | undefined>;
+    /**
+     * Dynamically imports the given optional peer dependency, throwing a helpful error if it is not installed.
+     *
+     * @param pkg The name of the package to import.
+     */
+    private importOptionalDependency;
+    /**
+     * Returns a (cached) `jwks-rsa` client for the given JWKS URI.
+     * @param jwksURI The JWKS endpoint to fetch signing keys from.
+     */
+    private getJwksClient;
+    /**
+     * Verifies the signature, issuer, audience, and nonce of the given ID token.
+     *
+     * @param idToken The compact JWT id_token to verify.
+     * @param req The source HTTP request, used to validate the nonce against the stored session value.
+     */
+    private verifyIdToken;
+}

package/dist/types/auth/OTPStrategy.d.ts

@@ -0,0 +1,88 @@
+import type { JWTUser } from "@rapidrest/core";
+import { AuthStrategy, HttpRequest, HttpResponse, AuthResult } from "@rapidrest/service-core";
+import { OTPContact } from "./types.js";
+/**
+ * Describes the configuration options that can be used to initialize OTPStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class OTPStrategyOptions {
+    /**
+     * Set to `true` to enable discovery of a user's aliases. Default is `false`.
+     *
+     * Be careful enabling this as it can be used as a way for an attacker to discover sensitive information.
+     */
+    allowDiscovery?: boolean;
+    /** The name of the header to look for when performing header based authentication. Default value is `Authorization`. */
+    headerKey: string;
+    /** The authorization scheme type when using header based authentication. Default value is `otp`. */
+    headerScheme: string;
+    /**
+     * Retrieves the user's contact information for a given id.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique id of the contact to retrieve.
+     */
+    getContact(id: string): Promise<OTPContact | undefined>;
+    /**
+     * Retrieves the list of available contacts 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.
+     */
+    getContacts(id: string): Promise<OTPContact[]>;
+    /**
+     * 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: string): Promise<JWTUser | undefined>;
+    /**
+     * Sends a notification to the specified contact with the provided OTP token.
+     * NOTE: You must override this function when using this strategy.
+     * @param contact The contact to send the OTP token to.
+     * @param token The OTP token to send to the user.
+     */
+    notifyContact(contact: OTPContact, token: string): Promise<void>;
+}
+/**
+ * Implements an strategy for authenticating a user with a One Time Password (OTP) that is sent to one of the user's
+ * verified contact methods. This allows for implementation of a password-less login flow. This strategy requires that
+ * an existing user account has already been registered with at least one verified contact method.
+ *
+ * This strategy should not to be confused with Time-Based One Time Password (TOTP) authentication which uses a
+ * pre-shared security key, often stored on the user's device (e.g. authenticator app) or digital vault (e.g. 1Password,
+ * Bitwarden, etc.). For TOTP authentication, see `TOTPStrategy`.
+ *
+ * The login flow has three phases:
+ *
+ * 1. Discovery - The client requests a list of contacts for a given user id. The `getContacts()` callback is used to
+ * return the list of contacts.
+ * 2. Challenge - The client requests a OTP token to be sent to the contact with a specified id. The
+ * OTP token is generated and sent to the contact using the `notify()` callback and stored in the session.
+ * 3. Verify - The client submits the OTP token and contact id. The OTP token is verified against the one stored in the
+ * session, and the associated user is resolved using the `getUser()` callback.
+ *
+ * The client sends request data either in the `Authorization` header or the request body in standard form-data format
+ * (e.g. `id=<id>&token=<otp>`). For example, the initial challenge request (step 2) can be sent as
+ * `Authorization: otp id=<contact_id>`. The final verification request (step 3) is then sent as
+ * `Authorization: otp id=<contact_id>&token=<otp>`.
+ *
+ * WARNING: Allowing discovery (setting `OTPStrategyOptions.allowDiscovery` to `true`) is a potential side-channel
+ * attack allowing anyone to discover or gather partial contact information about a given user. For improved security,
+ * the returned list of contacts is partially obfuscated. However, enough information is still provided that an
+ * attacker may be able to harvest information anyway. For example, a phone number will be obfuscated from
+ * `818-867-5309` to `****5309`. An email address will be obfuscated from `john.smith@gmail.com` to
+ * `j****th@gmail.com`.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class OTPStrategy implements AuthStrategy {
+    readonly name: string;
+    private options;
+    private regexHeaderScheme;
+    constructor(options: OTPStrategyOptions);
+    authenticate(req: HttpRequest, res: HttpResponse, required?: boolean): Promise<AuthResult | undefined>;
+    authenticateSync(req: HttpRequest, res: HttpResponse, required?: boolean): AuthResult | undefined;
+    protected discovery(req: HttpRequest, res: HttpResponse): Promise<any>;
+    protected challenge(payload: any, req: HttpRequest, res: HttpResponse): Promise<any>;
+    protected verify(payload: any, req: HttpRequest, res: HttpResponse): Promise<JWTUser | undefined>;
+}

package/dist/types/auth/PasskeyStrategy.d.ts

@@ -0,0 +1,81 @@
+import type { JWTUser } from "@rapidrest/core";
+import { AuthResult, AuthStrategy, HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { PasskeyConfig, StoredPasskeyCredential } from "./types.js";
+/**
+ * Describes the configuration options that can be used to initialize PasskeyStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class PasskeyStrategyOptions {
+    /**
+     * The relying party configuration to use for this strategy.
+     */
+    config: PasskeyConfig;
+    constructor(config: PasskeyConfig);
+    /**
+     * 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.
+     */
+    getCredentialById(credentialId: string): Promise<StoredPasskeyCredential | undefined>;
+    /**
+     * 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.
+     */
+    getCredentials(id: string): Promise<StoredPasskeyCredential[]>;
+    /**
+     * 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.
+     */
+    updateCredentialCounter(credentialId: string, newCounter: number): Promise<void>;
+    /**
+     * 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: string): Promise<JWTUser | undefined>;
+}
+/**
+ * Implements an authentication strategy for performing WebAuthn/Passkey (FIDO2) login.
+ *
+ * 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 declare class PasskeyStrategy implements AuthStrategy {
+    readonly name: string;
+    private options;
+    constructor(options: PasskeyStrategyOptions);
+    authenticate(req: HttpRequest, res: HttpResponse, required?: boolean): Promise<AuthResult | undefined>;
+    authenticateSync(req: HttpRequest, res: HttpResponse, required?: boolean): AuthResult | undefined;
+    /**
+     * 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.
+     */
+    protected challenge(req: HttpRequest, res: HttpResponse): Promise<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`.
+     */
+    protected verify(req: HttpRequest, required?: boolean): Promise<AuthResult | undefined>;
+}

package/dist/types/auth/TOTPStrategy.d.ts

@@ -0,0 +1,49 @@
+import type { JWTUser } from "@rapidrest/core";
+import { AuthResult, AuthStrategy, HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { TOTPSecret } from "./types.js";
+/**
+ * Describes the configuration options that can be used to initialize TOTPStrategy.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class TOTPStrategyOptions {
+    /** The name of the header to look for when performing header based authentication. Default value is `Authorization`. */
+    headerKey: string;
+    /** The authorization scheme type when using header based authentication. Default value is `jwt`. */
+    headerScheme: string;
+    /** The name of the request query parameter to retrieve the token from when using query based authentication. Default value is `auth_totp`. */
+    queryKey: string;
+    /**
+     * 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.
+     */
+    allowQueryParam: boolean;
+    /**
+     * Retrieves the stored TOTP secrets for the user with the given unique identifier.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique identifier of the user.
+     */
+    getSecrets(uid: string): Promise<TOTPSecret[]>;
+    /**
+     * Retrieves the user data for the given unique identifier.
+     * NOTE: You must override this function when using this strategy.
+     * @param id The unique id of the user that has been successfully authenticated.
+     */
+    getUser(id: string): Promise<JWTUser | undefined>;
+}
+/**
+ * Implements an authentication strategy that performs Time-Based One Time Password authentication. This strategy
+ * requires an existing user account to have already registered a TOTP secret that will be validated. The strategy does
+ * not implement how that secret is to be stored.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class TOTPStrategy implements AuthStrategy {
+    readonly name: string;
+    private options;
+    constructor(options?: TOTPStrategyOptions);
+    authenticate(req: HttpRequest, res: HttpResponse, required?: boolean): Promise<AuthResult | undefined>;
+    authenticateSync(req: HttpRequest, res: HttpResponse, required?: boolean): AuthResult | undefined;
+    protected verify(payload: any): Promise<JWTUser | undefined>;
+}

package/dist/types/auth/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./shared.js";
+export * from "./types.js";
+export * from "./BasicStrategy.js";
+export * from "./FIDO2Strategy.js";
+export * from "./MFAStrategy.js";
+export * from "./OIDCStrategy.js";
+export * from "./OTPStrategy.js";
+export * from "./PasskeyStrategy.js";
+export * from "./TOTPStrategy.js";

package/dist/types/auth/shared.d.ts

@@ -0,0 +1,136 @@
+import { HttpRequest } from "@rapidrest/service-core";
+import { OTPContactType, PasskeyConfig, PasskeyTransport, StoredPasskeyCredential, TOTPConfig, TOTPSecret } from "./types.js";
+/**
+ * Attempts to decode the request for authentication Basic request data
+ * (e.g. `Authorization: basic base64("<id>:<password>")).
+ *
+ * @param req The request to return auth request data for.
+ * @param headerKey The name of a header to look for request data in. Set to an empty string to skip
+ * the header search entirely — passing `undefined` has no effect, since that just triggers the
+ * default value. Default is 'Authorization'.
+ * @param headerScheme The header scheme to look for. Default is 'basic'.
+ * @returns An object with format `{id: <username>, password: <password> }, otherwise `undefined`.
+ */
+export declare const getBasicData: (req: HttpRequest, headerKey?: string, headerScheme?: string) => any;
+/**
+ * Attempts to decode the request for authentication request data. The auth request data may be in a header, a query
+ * parameter or the request body itself. It may either be JSON encoded or form-data encoded. We want to return a
+ * regular object.
+ *
+ * @param req The request to return auth request data for.
+ * @param headerKey The name of a header to look for request data in. Set to an empty string to skip
+ * the header search entirely — passing `undefined` has no effect, since that just triggers the
+ * default value. Default is 'Authorization'.
+ * @param headerScheme The header scheme to look for. Default is 'basic'.
+ * @returns The found request data and its decoded payload object.
+ */
+export declare const getRequestData: (req: HttpRequest, headerKey?: string | undefined, headerScheme?: string) => {
+    data: any;
+    payload: any;
+};
+export declare const isOTPResponse: (response: any) => boolean;
+export declare const isPasskeyResponse: (response: any) => boolean;
+/**
+ * Determines if the given value has the shape of a WebAuthn `RegistrationResponseJSON`, as produced by
+ * `navigator.credentials.create()` and submitted to finish a passkey registration ceremony.
+ *
+ * @param response The value to check.
+ */
+export declare const isPasskeyRegistrationResponse: (response: any) => boolean;
+/**
+ * Obfuscates the given contact and returns the obfuscated value.
+ * @param contact The contact to obfuscate.
+ */
+export declare const obfuscateContact: (contact: string, type: OTPContactType) => string;
+/**
+ * Generates and returns a new OTP token for authentication. This function stores relevant data for
+ * validation of the OTP token in the request's session.
+ * @param req The HTTP request to use for storing session data.
+ * @returns The generated OTP token.
+ */
+export declare const generateOTP: (req: HttpRequest, requestData?: any) => Promise<string>;
+/**
+ * Validates the provided token against the data stored in the request session.
+ * @param token The OTP token to validate.
+ * @param req The HTTP request with OTP session data.
+ */
+export declare const verifyOTP: (req: HttpRequest, payload?: any) => Promise<boolean>;
+export declare const generatePasskeyChallenge: (config: PasskeyConfig, req: HttpRequest, allowCredentials?: any) => Promise<any>;
+export declare const verifyPasskeyChallenge: (credential: StoredPasskeyCredential, config: PasskeyConfig, expectedChallenge: string, payload: any) => Promise<any>;
+/**
+ * Begins a registration ceremony: generates a set of `PublicKeyCredentialCreationOptions` and stores the
+ * challenge in the session for later verification. The result is meant to be returned directly to the
+ * client for use with `navigator.credentials.create()`.
+ *
+ * @param config The relying party configuration to use for this ceremony.
+ * @param req The source HTTP request. Used to persist the generated challenge in the session.
+ * @param user The user the new credential will be associated with.
+ * @param excludeCredentials The user's already-registered credentials, if any, so that the authenticator
+ * can avoid creating a duplicate credential for one it already holds.
+ */
+export declare const generatePasskeyRegistrationOptions: (config: PasskeyConfig, req: HttpRequest, user: {
+    id: string;
+    name: string;
+    displayName?: string;
+}, excludeCredentials?: {
+    id: string;
+    transports?: PasskeyTransport[];
+}[]) => Promise<any>;
+/**
+ * Finishes a registration ceremony: verifies the client-submitted attestation response against the
+ * stored challenge and relying party configuration.
+ *
+ * @param config The relying party configuration to verify the response against.
+ * @param expectedChallenge The challenge previously stored in the session by
+ * `generatePasskeyRegistrationOptions()`.
+ * @param payload The client-submitted `RegistrationResponseJSON`.
+ */
+export declare const verifyPasskeyRegistrationResponse: (config: PasskeyConfig, expectedChallenge: string, payload: any) => Promise<any>;
+/**
+ * Generates and returns a new OTP token for authentication. This function stores relevant data for
+ * validation of the OTP token in the request's session.
+ * @param req The HTTP request to use for storing session data.
+ * @returns The generated OTP token.
+ */
+export declare const generateTOTP: (req: HttpRequest, requestData?: any) => Promise<string>;
+/**
+ * Validates the provided token against the specified TOTP secret.
+ * @param token The OTP token to validate.
+ * @param secret The stored TOTP secret to validate the token against.
+ * @returns The otplib verification result if successful, otherwise `undefined`.
+ */
+export declare const verifyTOTP: (token: string, secret: TOTPSecret | TOTPSecret[]) => Promise<any>;
+/**
+ * Determines if the given value is usable as a TOTP secret: a Base32-encoded string decoding to at
+ * least 128 bits, the minimum shared secret length mandated by RFC 4226 §4 (R6) (which RFC 6238
+ * TOTP secrets must also satisfy, per RFC 6238 §5.1).
+ *
+ * @param secret The value to check.
+ */
+export declare const isValidTOTPSecret: (secret: any) => Promise<boolean>;
+/**
+ * Generates an `otpauth://` provisioning URI for the given TOTP secret — the "Key URI Format"
+ * convention (https://github.com/google/google-authenticator/wiki/Key-Uri-Format) that, while not
+ * itself an RFC, is the de facto standard virtually every TOTP authenticator app (Google
+ * Authenticator, Authy, 1Password, etc.) relies on to enroll a secret via QR code or manual entry.
+ *
+ * @param config The relying party configuration to generate the URI for.
+ * @param label The account label to embed in the URI (typically a username or email).
+ * @param secret The TOTP secret to encode into the URI.
+ */
+export declare const generateTOTPURI: (config: TOTPConfig, label: string, secret: TOTPSecret) => Promise<string>;
+/**
+ * Dynamically imports the optional peer dependency `argon2`, throwing a helpful
+ * error if it is not installed.
+ */
+export declare const importArgon2: () => Promise<any>;
+/**
+ * Dynamically imports the optional peer dependency `otplib`, throwing a helpful
+ * error if it is not installed.
+ */
+export declare const importOTPLib: () => Promise<any>;
+/**
+ * Dynamically imports the optional peer dependency `@simplewebauthn/server`, throwing a helpful
+ * error if it is not installed.
+ */
+export declare const importSimpleWebAuthn: () => Promise<any>;