cognito-srp-helper
Version:
A helper for SRP authentication in AWS Cognito
247 lines (246 loc) • 12.1 kB
TypeScript
declare module "utils" {
/*!
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0
*/
import { Buffer } from "buffer/index.js";
import { BigInteger } from "jsbn";
/**
* Calculate a hash from a bitArray
*
* @param buf Value to hash.
* @returns Hex-encoded hash.
*/
export const hash: (buf: Buffer | string) => string;
/**
* Calculate a hash from a hex string
*
* @param hexStr Value to hash.
* @returns Hex-encoded hash.
*/
export const hexHash: (hexStr: string) => string;
/**
* Returns an unambiguous, even-length hex string of the two's complement
* encoding of an integer.
*
* It is compatible with the hex encoding of Java's BigInteger's toByteArray(),
* which returns a byte array containing the two's-complement representation of
* a BigInteger. The array contains the minimum number of bytes required to
* represent the BigInteger, including at least one sign bit.
*
* Examples showing how ambiguity is avoided by left padding with:
* "00" (for positive values where the most-significant-bit is set)
* "FF" (for negative values where the most-significant-bit is set)
*
* padHex(bigInteger.fromInt(-236)) === "FF14"
* padHex(bigInteger.fromInt(20)) === "14"
*
* padHex(bigInteger.fromInt(-200)) === "FF38"
* padHex(bigInteger.fromInt(56)) === "38"
*
* padHex(bigInteger.fromInt(-20)) === "EC"
* padHex(bigInteger.fromInt(236)) === "00EC"
*
* padHex(bigInteger.fromInt(-56)) === "C8"
* padHex(bigInteger.fromInt(200)) === "00C8"
*
* @param bigInt Number to encode.
* @returns Even-length hex string of the two's complement encoding.
*/
export const padHex: (bigInt: BigInteger) => string;
/**
* Returns a Buffer with a sequence of random nBytes
*
* @param nBytes
* @returns Fixed-length sequence of random bytes
*/
export const randomBytes: (nBytes: number) => Buffer;
/**
* Converts a hexadecimal encoded string to a Uint8Array of bytes.
*
* @param encoded The hexadecimal encoded string
*/
export const getBytesFromHex: (encoded: string) => Uint8Array;
}
declare module "constants" {
import { Buffer } from "buffer/index.js";
import { BigInteger } from "jsbn";
export const INFO_BITS: Buffer;
export const G: BigInteger;
export const N: BigInteger;
export const K: BigInteger;
export const HEX_TO_SHORT: Record<string, number>;
}
declare module "errors" {
export class SignSrpSessionError extends Error {
constructor(message?: string);
}
export class MissingChallengeResponsesError extends SignSrpSessionError {
constructor(message?: string);
}
export class MissingSaltError extends SignSrpSessionError {
constructor(message?: string);
}
export class MissingSecretError extends SignSrpSessionError {
constructor(message?: string);
}
export class MissingLargeBError extends SignSrpSessionError {
constructor(message?: string);
}
export class MissingUserIdForSrpBError extends SignSrpSessionError {
constructor(message?: string);
}
export class MissingDeviceKeyError extends SignSrpSessionError {
constructor(message?: string);
}
export class AbortOnZeroSrpError extends Error {
constructor(message?: string);
}
export class AbortOnZeroASrpError extends AbortOnZeroSrpError {
constructor(message?: string);
}
export class AbortOnZeroBSrpError extends AbortOnZeroSrpError {
constructor(message?: string);
}
export class AbortOnZeroUSrpError extends AbortOnZeroSrpError {
constructor(message?: string);
}
}
declare module "types" {
import type { AdminInitiateAuthRequest, AdminInitiateAuthResponse, AdminRespondToAuthChallengeRequest, AdminRespondToAuthChallengeResponse, AuthFlowType, ChallengeNameType, DeviceSecretVerifierConfigType, InitiateAuthRequest as ClientInitiateAuthRequest, InitiateAuthResponse as ClientInitiateAuthResponse, RespondToAuthChallengeRequest as ClientRespondToAuthChallengeRequest, RespondToAuthChallengeResponse as ClientRespondToAuthChallengeResponse } from "@aws-sdk/client-cognito-identity-provider";
/**
* Either InitiateAuthRequest or AdminInitiateAuthRequest from `@aws-sdk/client-cognito-identity-provider`. Should be compatible with SDK v2 and Command forms of the request
*/
export type InitiateAuthRequest = (Omit<ClientInitiateAuthRequest, "AuthFlow"> & {
AuthFlow?: AuthFlowType | string;
}) | (Omit<AdminInitiateAuthRequest, "AuthFlow"> & {
AuthFlow?: AuthFlowType | string;
});
/**
* Either InitiateAuthResponse or AdminInitiateAuthResponse from `@aws-sdk/client-cognito-identity-provider`. Should be compatible with SDK v2 and Command forms of the request
*/
export type InitiateAuthResponse = (Omit<ClientInitiateAuthResponse, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
}) | (Omit<AdminInitiateAuthResponse, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
});
/**
* Either RespondToAuthChallengeRequest or AdminRespondToAuthChallengeRequest from `@aws-sdk/client-cognito-identity-provider`. Should be compatible with SDK v2 and Command forms of the request
*/
export type RespondToAuthChallengeRequest = (Omit<ClientRespondToAuthChallengeRequest, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
}) | (Omit<AdminRespondToAuthChallengeRequest, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
});
/**
* Either RespondToAuthChallengeResponse or AdminRespondToAuthChallengeResponse from `@aws-sdk/client-cognito-identity-provider`. Should be compatible with SDK v2 and Command forms of the response
*/
export type RespondToAuthChallengeResponse = (Omit<ClientRespondToAuthChallengeResponse, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
}) | (Omit<AdminRespondToAuthChallengeResponse, "ChallengeName"> & {
ChallengeName?: ChallengeNameType | string;
});
/**
* Credentials needed for SRP authentication
*/
export type Credentials = {
sub: string;
username: string;
email: string;
phone: string;
password: string;
poolId: string;
clientId: string;
secretId: string;
secretHash: string;
passwordHash: string;
};
/**
* SRP session object. This object contains the user's credentials, public and
* private keys. Using these details we can initiate an SRP request to verify
* the user's password via AWS Cognito
*/
export type SrpSession = {
/** Username of the user. It is stored here for convenience when passing parameters into `computePasswordSignature` */
username: string;
/** Password used for authentication */
password: string;
/** Flag indicating whether the password has already been hashed */
isHashed: boolean;
/** Full un-abbreviated ID of the Cognito Userpool. Here it is the full ID that's used e.g. 'eu-west-2_abc123' */
poolId: string;
/** Abbreviated ID of the Cognito Userpool. Here it is just the succeeding ID that's used e.g. 'eu-west-2_abc123' becomes 'abc123' */
poolIdAbbr: string;
/** Timestamp captured in the format requiree for Cogntio */
timestamp: string;
/** Client's private session key */
smallA: string;
/** Client's public session key */
largeA: string;
};
/**
* Cognito SRP session object. After initiating SRP authentication with AWS
* Cognito using the data provided by `ClientSrpSession`, Cognito will return
* these three values that we can use to compute the signature for our password
*/
export type SrpSessionSigned = SrpSession & {
/** Server's public session key */
largeB: string;
/** Server's session salt */
salt: string;
/** Server's session secret */
secret: string;
/** The signatire used to verify the user's password */
passwordSignature: string;
};
/**
* An object containing the DeviceSecretVerifierConfig required for the ConfirmDeviceCommand step,
* and DeviceRandomPassword used for to generate the signature for the DEVICE_PASSWORD_VERIFIER step
*/
export type DeviceVerifier = {
/** The random password associated with a device. Used to generate the password signature for DEVICE_PASSWORD_VERIFIER */
DeviceRandomPassword: string;
/** The device verifier used to confirm the device in ConfirmDeviceCommand */
DeviceSecretVerifierConfig: DeviceSecretVerifierConfigType;
};
}
declare module "cognito-srp-helper" {
import { DeviceVerifier, InitiateAuthRequest, InitiateAuthResponse, RespondToAuthChallengeRequest, RespondToAuthChallengeResponse, SrpSession, SrpSessionSigned } from "types";
export const createSecretHash: (userId: string, clientId: string, secretId: string) => string;
export const createPasswordHash: (userId: string, password: string, poolId: string) => string;
export const createDeviceVerifier: (deviceKey: string, deviceGroupKey: string) => DeviceVerifier;
export const createSrpSession: (username: string, password: string, poolId: string, isHashed?: boolean) => SrpSession;
export const signSrpSession: (session: SrpSession, response: InitiateAuthResponse) => SrpSessionSigned;
export const signSrpSessionWithDevice: (session: SrpSession, response: RespondToAuthChallengeResponse, deviceGroupKey: string, deviceRandomPassword: string) => SrpSessionSigned;
export const wrapInitiateAuth: <T extends InitiateAuthRequest>(session: SrpSession, request: T) => T;
export const wrapAuthChallenge: <T extends RespondToAuthChallengeRequest>(session: SrpSessionSigned, request: T) => T;
}
declare module "index" {
import * as Errors from "errors";
import * as Types from "types";
export * from "cognito-srp-helper";
export * from "errors";
export * from "types";
const _default: {
SignSrpSessionError: typeof Errors.SignSrpSessionError;
MissingChallengeResponsesError: typeof Errors.MissingChallengeResponsesError;
MissingSaltError: typeof Errors.MissingSaltError;
MissingSecretError: typeof Errors.MissingSecretError;
MissingLargeBError: typeof Errors.MissingLargeBError;
MissingUserIdForSrpBError: typeof Errors.MissingUserIdForSrpBError;
MissingDeviceKeyError: typeof Errors.MissingDeviceKeyError;
AbortOnZeroSrpError: typeof Errors.AbortOnZeroSrpError;
AbortOnZeroASrpError: typeof Errors.AbortOnZeroASrpError;
AbortOnZeroBSrpError: typeof Errors.AbortOnZeroBSrpError;
AbortOnZeroUSrpError: typeof Errors.AbortOnZeroUSrpError;
createSecretHash: (userId: string, clientId: string, secretId: string) => string;
createPasswordHash: (userId: string, password: string, poolId: string) => string;
createDeviceVerifier: (deviceKey: string, deviceGroupKey: string) => Types.DeviceVerifier;
createSrpSession: (username: string, password: string, poolId: string, isHashed?: boolean) => Types.SrpSession;
signSrpSession: (session: Types.SrpSession, response: Types.InitiateAuthResponse) => Types.SrpSessionSigned;
signSrpSessionWithDevice: (session: Types.SrpSession, response: Types.RespondToAuthChallengeResponse, deviceGroupKey: string, deviceRandomPassword: string) => Types.SrpSessionSigned;
wrapInitiateAuth: <T extends Types.InitiateAuthRequest>(session: Types.SrpSession, request: T) => T;
wrapAuthChallenge: <T_1 extends Types.RespondToAuthChallengeRequest>(session: Types.SrpSessionSigned, request: T_1) => T_1;
};
export default _default;
}