@joinmeow/cognito-passwordless-auth/cognito-api.d.ts

Passwordless authentication with Amazon Cognito: FIDO2 (WebAuthn, support for Passkeys)

import { MinimalResponse } from "./config.js";
import { DeviceSrpAuthResult } from "./device.js";
interface ErrorResponse {
    __type: string;
    message: string;
}
export type Session = string;
type ChallengeName = "CUSTOM_CHALLENGE" | "PASSWORD_VERIFIER" | "SMS_MFA" | "NEW_PASSWORD_REQUIRED" | "SOFTWARE_TOKEN_MFA" | "DEVICE_SRP_AUTH" | "DEVICE_PASSWORD_VERIFIER";
interface ChallengeResponse {
    ChallengeName: ChallengeName;
    ChallengeParameters: Record<string, string>;
    Session: Session;
}
interface AuthenticatedResponse {
    AuthenticationResult: {
        AccessToken: string;
        IdToken: string;
        RefreshToken: string;
        ExpiresIn: number;
        TokenType: string;
        NewDeviceMetadata?: {
            DeviceKey: string;
            DeviceGroupKey: string;
        };
    };
    ChallengeParameters: Record<string, string>;
}
interface RefreshResponse {
    AuthenticationResult: {
        AccessToken: string;
        IdToken: string;
        /** Optional refresh token from InitiateAuth with REFRESH_TOKEN flow */
        RefreshToken?: string;
        ExpiresIn: number;
        TokenType: string;
    };
    ChallengeParameters: Record<string, string>;
}
interface GetIdResponse {
    IdentityId: string;
}
interface GetCredentialsForIdentityResponse {
    Credentials: {
        AccessKeyId: string;
        Expiration: number;
        SecretKey: string;
        SessionToken: string;
    };
    IdentityId: string;
}
interface GetUserResponse {
    MFAOptions: {
        AttributeName: string;
        DeliveryMedium: string;
    }[];
    PreferredMfaSetting: string;
    UserAttributes: {
        Name: string;
        Value: string;
    }[];
    UserMFASettingList: string[];
    Username: string;
}
interface GetTokensFromRefreshTokenResponse {
    AuthenticationResult: {
        AccessToken: string;
        IdToken: string;
        RefreshToken?: string;
        ExpiresIn: number;
        TokenType: string;
        NewDeviceMetadata?: {
            DeviceKey: string;
            DeviceGroupKey: string;
        };
    };
}
export declare function isErrorResponse(obj: unknown): obj is ErrorResponse;
export declare function assertIsNotErrorResponse<T>(obj: T | ErrorResponse): asserts obj is T;
export declare function assertIsNotChallengeResponse<T>(obj: T | ChallengeResponse): asserts obj is T;
export declare function assertIsNotAuthenticatedResponse<T>(obj: T | AuthenticatedResponse): asserts obj is T;
export declare function isChallengeResponse(obj: unknown): obj is ChallengeResponse;
export declare function assertIsChallengeResponse(obj: unknown): asserts obj is ChallengeResponse;
export declare function isAuthenticatedResponse(obj: unknown): obj is AuthenticatedResponse;
export declare function assertIsAuthenticatedResponse(obj: unknown): asserts obj is AuthenticatedResponse;
export declare function assertIsSignInResponse(obj: unknown): asserts obj is AuthenticatedResponse | ChallengeResponse;
export declare function initiateAuth<T extends "CUSTOM_AUTH" | "REFRESH_TOKEN" | "USER_SRP_AUTH" | "USER_PASSWORD_AUTH">({ authflow, authParameters, clientMetadata, deviceKey, abort, }: {
    authflow: T;
    authParameters: Record<string, string>;
    clientMetadata?: Record<string, string>;
    deviceKey?: string;
    abort?: AbortSignal;
}): Promise<T extends "REFRESH_TOKEN" ? RefreshResponse : AuthenticatedResponse | ChallengeResponse>;
export declare function respondToAuthChallenge({ challengeName, challengeResponses, session, clientMetadata, abort, }: {
    challengeName: ChallengeName;
    challengeResponses: Record<string, string>;
    session?: Session;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<AuthenticatedResponse | ChallengeResponse>;
/**
 * Confirms the sign-up of a user in Amazon Cognito.
 * Automatically collects and includes threat protection data when available.
 *
 * @param params - The parameters for confirming the sign-up.
 * @param params.username - The username or alias (e-mail, phone number) of the user.
 * @param params.confirmationCode - The confirmation code received by the user.
 * @param [params.clientMetadata] - Additional metadata to be passed to the server.
 * @param [params.forceAliasCreation] - When true, forces user confirmation despite existing aliases.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response of the confirmation request.
 */
export declare function confirmSignUp({ username, confirmationCode, clientMetadata, forceAliasCreation, abort, }: {
    username: string;
    confirmationCode: string;
    clientMetadata?: Record<string, string>;
    forceAliasCreation?: boolean;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
export declare function revokeToken({ refreshToken, abort, }: {
    refreshToken: string;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
export declare function getTokensFromRefreshToken({ refreshToken, deviceKey, clientMetadata, abort, }: {
    refreshToken: string;
    deviceKey?: string;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<GetTokensFromRefreshTokenResponse>;
export declare function getId({ identityPoolId, abort, }: {
    identityPoolId: string;
    abort?: AbortSignal;
}): Promise<ErrorResponse | GetIdResponse>;
/**
 * Retrieves the user attributes from the Cognito Identity Provider.
 *
 * @param abort - An optional `AbortSignal` object that can be used to abort the request.
 * @returns A promise that resolves to an array of user attributes, where each attribute is represented by an object with `Name` and `Value` properties.
 */
export declare function getUser({ abort, accessToken, }: {
    abort?: AbortSignal;
    accessToken?: string;
}): Promise<ErrorResponse | GetUserResponse>;
export declare function getCredentialsForIdentity({ identityId, abort, }: {
    identityId: string;
    abort?: AbortSignal;
}): Promise<ErrorResponse | GetCredentialsForIdentityResponse>;
export declare function signUp({ username, password, userAttributes, clientMetadata, validationData, abort, }: {
    /**
     * Username, or alias (e-mail, phone number)
     */
    username: string;
    password: string;
    userAttributes?: {
        name: string;
        value: string;
    }[];
    clientMetadata?: Record<string, string>;
    validationData?: {
        name: string;
        value: string;
    }[];
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
export declare function updateUserAttributes({ clientMetadata, userAttributes, abort, accessToken, }: {
    userAttributes: {
        name: string;
        value: string;
    }[];
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
    accessToken?: string;
}): Promise<void>;
export declare function getUserAttributeVerificationCode({ attributeName, clientMetadata, abort, accessToken, }: {
    attributeName: string;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
    accessToken?: string;
}): Promise<void>;
export declare function verifyUserAttribute({ attributeName, code, abort, accessToken, }: {
    attributeName: string;
    code: string;
    abort?: AbortSignal;
    accessToken?: string;
}): Promise<void>;
export declare function setUserMFAPreference({ smsMfaSettings, softwareTokenMfaSettings, abort, accessToken, }: {
    smsMfaSettings?: {
        enabled?: boolean;
        preferred?: boolean;
    };
    softwareTokenMfaSettings?: {
        enabled?: boolean;
        preferred?: boolean;
    };
    abort?: AbortSignal;
    accessToken?: string;
}): Promise<void>;
export declare function handleAuthResponse({ authResponse, username, smsMfaCode, otpMfaCode, newPassword, customChallengeAnswer, deviceHandler, clientMetadata, abort, }: {
    authResponse: ChallengeResponse | AuthenticatedResponse;
    /**
     * Username (not alias)
     */
    username: string;
    smsMfaCode?: () => Promise<string>;
    otpMfaCode?: () => Promise<string>;
    newPassword?: () => Promise<string>;
    customChallengeAnswer?: () => Promise<string>;
    /**
     * Handler for device authentication challenges (DEVICE_SRP_AUTH and DEVICE_PASSWORD_VERIFIER)
     */
    deviceHandler?: {
        deviceKey: string;
        generateStep1: () => Promise<{
            srpAHex: string;
        }>;
        generateStep2: (srpB: string, secretBlock: string, salt?: string) => Promise<DeviceSrpAuthResult>;
    };
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<{
    idToken: string;
    accessToken: string;
    expireAt: Date;
    refreshToken: string;
    username: string;
    newDeviceMetadata: {
        deviceKey: string;
        deviceGroupKey: string;
    } | undefined;
    deviceKey: string | undefined;
}>;
declare global {
    interface Window {
        AmazonCognitoAdvancedSecurityData?: {
            getData: (username: string, userPoolId: string, clientId: string) => string;
        };
    }
}
/**
 * Resends the confirmation code to a user who has signed up but not confirmed their account.
 * Automatically collects and includes threat protection data when available.
 *
 * @param params - The parameters for resending the confirmation code.
 * @param params.username - The username or alias (e-mail, phone number) of the user.
 * @param [params.clientMetadata] - Additional metadata to be passed to the server.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing code delivery details.
 */
export declare function resendConfirmationCode({ username, clientMetadata, abort, }: {
    username: string;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Sends a password-reset confirmation code to the user.
 * Automatically collects and includes threat protection data when available.
 *
 * @param params - The parameters for the forgot password request.
 * @param params.username - The username or alias (e-mail, phone number) of the user.
 * @param [params.clientMetadata] - Additional metadata to be passed to the server.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing code delivery details.
 */
export declare function forgotPassword({ username, clientMetadata, abort, }: {
    username: string;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Completes the password reset process by validating the confirmation code and setting a new password.
 * Automatically collects and includes threat protection data when available.
 *
 * @param params - The parameters for confirming the forgot password request.
 * @param params.username - The username or alias (e-mail, phone number) of the user.
 * @param params.confirmationCode - The confirmation code sent to the user.
 * @param params.password - The new password for the user.
 * @param [params.clientMetadata] - Additional metadata to be passed to the server.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves when the password has been successfully reset.
 */
export declare function confirmForgotPassword({ username, confirmationCode, password, clientMetadata, abort, }: {
    username: string;
    confirmationCode: string;
    password: string;
    clientMetadata?: Record<string, string>;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
/**
 * Changes the password for a signed-in user.
 * Requires a valid access token from the signed-in user.
 *
 * @param params - The parameters for changing the password.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param params.previousPassword - The user's current password.
 * @param params.proposedPassword - The new password.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves when the password has been successfully changed.
 */
export declare function changePassword({ accessToken, previousPassword, proposedPassword, abort, }: {
    accessToken: string;
    previousPassword: string;
    proposedPassword: string;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
/**
 * Changes the password for the currently signed-in user, using the stored access token.
 * This is a convenience method that automatically uses the access token from storage.
 *
 * @param params - The parameters for changing the password.
 * @param params.previousPassword - The user's current password.
 * @param params.proposedPassword - The new password.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves when the password has been successfully changed.
 */
export declare function changePasswordForCurrentUser({ previousPassword, proposedPassword, abort, }: {
    previousPassword: string;
    proposedPassword: string;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
/**
 * Begins setup of time-based one-time password (TOTP) multi-factor authentication (MFA) for a user.
 * Returns a unique private key that can be used with authenticator apps like Google Authenticator or Authy.
 *
 * @param params - The parameters for associating a software token.
 * @param [params.accessToken] - A valid access token for the signed-in user. Required if session is not provided.
 * @param [params.session] - A session string from a challenge response. Required if accessToken is not provided.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing the secret code and session.
 */
export declare function associateSoftwareToken({ accessToken, session, abort, }: {
    accessToken?: string;
    session?: string;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Verifies the time-based one-time password (TOTP) multi-factor authentication (MFA) setup for a user.
 * This should be called after associateSoftwareToken to complete the MFA setup.
 *
 * @param params - The parameters for verifying a software token.
 * @param params.userCode - The time-based one-time password that the user provides from their authenticator app.
 * @param [params.accessToken] - A valid access token for the signed-in user. Required if session is not provided.
 * @param [params.session] - A session string from associateSoftwareToken or a challenge response. Required if accessToken is not provided.
 * @param [params.friendlyDeviceName] - A friendly name for the device that will be generating TOTP codes.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing the status of the verification.
 */
export declare function verifySoftwareToken({ userCode, accessToken, session, friendlyDeviceName, abort, }: {
    userCode: string;
    accessToken?: string;
    session?: string;
    friendlyDeviceName?: string;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Convenience method for beginning TOTP MFA setup for the currently signed-in user.
 * Automatically uses the stored access token.
 *
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing the secret code.
 */
export declare function associateSoftwareTokenForCurrentUser({ abort, }?: {
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Convenience method for verifying TOTP MFA setup for the currently signed-in user.
 * Automatically uses the stored access token.
 *
 * @param params.userCode - The time-based one-time password that the user provides from their authenticator app.
 * @param [params.friendlyDeviceName] - A friendly name for the device that will be generating TOTP codes.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response containing the status of the verification.
 */
export declare function verifySoftwareTokenForCurrentUser({ userCode, friendlyDeviceName, abort, }: {
    userCode: string;
    friendlyDeviceName?: string;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Confirms a device to be tracked for a user. This allows for "Remember this device" functionality.
 * For remembered devices, MFA challenges can be skipped on subsequent sign-ins.
 *
 * @param params - The parameters for confirming a device.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param params.deviceKey - The device key returned during authentication.
 * @param params.deviceName - A friendly name for the device.
 * @param params.deviceSecretVerifierConfig - The SRP configuration for the device.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the response indicating if user confirmation is necessary.
 */
export declare function confirmDevice({ accessToken, deviceKey, deviceName, deviceSecretVerifierConfig, abort, }: {
    accessToken: string;
    deviceKey: string;
    deviceName?: string;
    deviceSecretVerifierConfig: {
        passwordVerifier: string;
        salt: string;
    };
    abort?: AbortSignal;
}): Promise<{
    UserConfirmationNecessary?: boolean | undefined;
}>;
/**
 * Updates the device status for a user's device.
 * This is typically called after confirmDevice if the user is prompted to remember the device.
 *
 * @param params - The parameters for updating device status.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param params.deviceKey - The device key returned during authentication.
 * @param params.deviceRememberedStatus - The remembered status of the device (remembered or not_remembered).
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves when the device status has been updated.
 */
export declare function updateDeviceStatus({ accessToken, deviceKey, deviceRememberedStatus, abort, }: {
    accessToken: string;
    deviceKey: string;
    deviceRememberedStatus: "remembered" | "not_remembered";
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
/**
 * Lists all devices for the currently authenticated user.
 *
 * @param params - The parameters for listing devices.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param [params.limit] - The maximum number of devices to list.
 * @param [params.paginationToken] - The pagination token from a previous list operation.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the list of devices.
 */
export declare function listDevices({ accessToken, limit, paginationToken, abort, }: {
    accessToken: string;
    limit?: number;
    paginationToken?: string;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Gets the device information for a specific device.
 *
 * @param params - The parameters for getting device information.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param params.deviceKey - The device key for the device to get information about.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves to the device information.
 */
export declare function getDevice({ accessToken, deviceKey, abort, }: {
    accessToken: string;
    deviceKey: string;
    abort?: AbortSignal;
}): Promise<unknown>;
/**
 * Removes the specified device from the user's account.
 *
 * @param params - The parameters for forgetting a device.
 * @param params.accessToken - A valid access token for the signed-in user.
 * @param params.deviceKey - The device key for the device to forget.
 * @param [params.abort] - An optional AbortSignal object that can be used to abort the request.
 * @returns A promise that resolves when the device has been forgotten.
 */
export declare function forgetDevice({ accessToken, deviceKey, abort, }: {
    accessToken: string;
    deviceKey: string;
    abort?: AbortSignal;
}): Promise<MinimalResponse>;
export {};