@vardario/cognito-client 2.0.0 → 2.1.0

package/lib/cognito-client.d.ts

@@ -1,7 +1,158 @@
+export interface CognitoBaseRequest {
+    ClientId: string;
+    ClientMetadata?: Record<string, string>;
+    AnalyticsMetadata?: {
+        AnalyticsEndpointId: string;
+    };
+    UserContextData?: {
+        EncodedData?: string;
+        IpAddress?: string;
+    };
+}
+export interface AuthIntiUserSrpRequest extends CognitoBaseRequest {
+    AuthFlow: 'USER_SRP_AUTH';
+    AuthParameters: {
+        USERNAME: string;
+        SRP_A: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface AuthIntiUserPasswordRequest extends CognitoBaseRequest {
+    AuthFlow: 'USER_PASSWORD_AUTH';
+    AuthParameters: {
+        USERNAME: string;
+        PASSWORD: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface AuthIntiRefreshTokenRequest extends CognitoBaseRequest {
+    AuthFlow: 'REFRESH_TOKEN_AUTH';
+    AuthParameters: {
+        REFRESH_TOKEN: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface AuthIntiCustomAuthRequest extends CognitoBaseRequest {
+    AuthFlow: 'CUSTOM_AUTH';
+    AuthParameters: {
+        USERNAME: string;
+        SECRET_HASH?: string;
+    };
+}
+export type AuthIntiRequest = AuthIntiUserSrpRequest | AuthIntiRefreshTokenRequest | AuthIntiCustomAuthRequest | AuthIntiUserPasswordRequest;
+export interface RespondToAuthChallengeBaseRequest extends CognitoBaseRequest {
+    Session?: string;
+}
+export interface RespondToAuthChallengePasswordVerifierRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'PASSWORD_VERIFIER';
+    ChallengeResponses: {
+        USERNAME: string;
+        PASSWORD_CLAIM_SECRET_BLOCK: string;
+        PASSWORD_CLAIM_SIGNATURE: string;
+        TIMESTAMP: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeSmsMfaRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'SMS_MFA';
+    ChallengeResponses: {
+        USERNAME: string;
+        SMS_MFA_CODE: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeCustomChallengeNameRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'CUSTOM_CHALLENGE';
+    ChallengeResponses: {
+        USERNAME: string;
+        ANSWER: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeNewPasswordRequiredRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'NEW_PASSWORD_REQUIRED';
+    ChallengeResponses: {
+        USERNAME: string;
+        NEW_PASSWORD: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeSoftwareTokenMfaRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'SOFTWARE_TOKEN_MFA';
+    ChallengeResponses: {
+        USERNAME: string;
+        SOFTWARE_TOKEN_MFA_CODE: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeDeviceSrpAuthRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'DEVICE_SRP_AUTH';
+    ChallengeResponses: {
+        USERNAME: string;
+        SRP_A: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeDevicePasswordVerifierRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'DEVICE_PASSWORD_VERIFIER';
+    ChallengeResponses: {
+        USERNAME: string;
+        PASSWORD_CLAIM_SECRET_BLOCK: string;
+        PASSWORD_CLAIM_SIGNATURE: string;
+        TIMESTAMP: string;
+        DEVICE_KEY: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeMfaSetupRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'MFA_SETUP';
+    ChallengeResponses: {
+        USERNAME: string;
+        SMS_MFA_CODE?: string;
+        SOFTWARE_TOKEN_MFA_CODE?: string;
+        SECRET_HASH?: string;
+    };
+}
+export interface RespondToAuthChallengeSelectMfaTypeRequest extends RespondToAuthChallengeBaseRequest {
+    ChallengeName: 'SELECT_MFA_TYPE';
+    ChallengeResponses: {
+        USERNAME: string;
+        SOFTWARE_TOKEN_MFA_CODE?: string;
+        SECRET_HASH?: string;
+    };
+}
+export type RespondToAuthChallengeRequest = RespondToAuthChallengePasswordVerifierRequest | RespondToAuthChallengeSmsMfaRequest | RespondToAuthChallengeCustomChallengeNameRequest | RespondToAuthChallengeNewPasswordRequiredRequest | RespondToAuthChallengeSoftwareTokenMfaRequest | RespondToAuthChallengeDeviceSrpAuthRequest | RespondToAuthChallengeDevicePasswordVerifierRequest | RespondToAuthChallengeMfaSetupRequest | RespondToAuthChallengeSelectMfaTypeRequest;
 export interface UserAttribute {
     Name: string;
     Value: string;
 }
+export interface ConfirmForgotPasswordRequest extends CognitoBaseRequest {
+    ConfirmationCode: string;
+    Password: string;
+    Username: string;
+    SecretHash?: string;
+}
+export interface ConfirmSignUpRequest extends CognitoBaseRequest {
+    ConfirmationCode: string;
+    Username: string;
+    SecretHash?: string;
+    ForceAliasCreation?: boolean;
+}
+export interface ForgotPasswordRequest extends CognitoBaseRequest {
+    Username: string;
+    SecretHash?: string;
+}
+export interface SignUpRequest extends CognitoBaseRequest {
+    Username: string;
+    Password: string;
+    SecretHash?: string;
+    UserAttributes?: UserAttribute[];
+    ValidationData?: UserAttribute[];
+}
+export interface ResendConfirmationCodeRequest extends CognitoBaseRequest {
+    Username: string;
+    SecretHash?: string;
+}
 /**
  * Cognito related OAuth props.
  */
@@ -43,6 +194,10 @@ export interface CognitoClientProps {
      * Cognito OAuth related options. See @see OAuthProps .
      */
     oAuth2?: OAuth2Props;
+    /**
+     * Optional Cognito User Pool Client Secret.
+     */
+    clientSecret?: string;
 }
 /**
  * Cognito User Session
@@ -159,7 +314,8 @@ export declare class CognitoClient {
     private readonly cognitoPoolName;
     private readonly userPoolClientId;
     private readonly oAuth?;
-    constructor({ userPoolId, userPoolClientId, endpoint, oAuth2: oAuth }: CognitoClientProps);
+    private readonly clientSecret?;
+    constructor({ userPoolId, userPoolClientId, endpoint, oAuth2: oAuth, clientSecret }: CognitoClientProps);
     static getDecodedTokenFromSession(session: Session): DecodedTokens;
     /**
      *
@@ -186,10 +342,11 @@ export declare class CognitoClient {
      * Returns a new session based on the given refresh token.
      *
      * @param refreshToken
+     * @param username
      * @returns @see Session
      * @throws {InitiateAuthException}
      */
-    refreshSession(refreshToken: string): Promise<Session>;
+    refreshSession(refreshToken: string, username?: string): Promise<Session>;
     /**
      *
      * @param username Username

package/lib/cognito-client.js

@@ -2,7 +2,7 @@ import hashJs from 'hash.js';
 import { BigInteger } from 'jsbn';
 import { Buffer } from 'buffer';
 import { CognitoCommonException, CognitoError } from './error.js';
-import { calculateSignature, calculateU, decodeJwt, generateA, generateSmallA, getPasswordAuthenticationKey, randomBytes } from './utils.js';
+import { calculateSecretHash, calculateSignature, calculateU, decodeJwt, generateA, generateSmallA, getPasswordAuthenticationKey, randomBytes } from './utils.js';
 /**
  * List of used and supported Cognito API calls.
  * @see https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_Operations.html for more details
@@ -79,12 +79,13 @@ export async function cognitoRequest(body, serviceTarget, cognitoEndpoint) {
  * Lightweight AWS Cogito client without any AWS SDK dependencies.
  */
 export class CognitoClient {
-    constructor({ userPoolId, userPoolClientId, endpoint, oAuth2: oAuth }) {
+    constructor({ userPoolId, userPoolClientId, endpoint, oAuth2: oAuth, clientSecret }) {
         const [cognitoPoolRegion, cognitoPoolName] = userPoolId.split('_');
         this.cognitoEndpoint = (endpoint || `https://cognito-idp.${cognitoPoolRegion}.amazonaws.com`).replace(/\/$/, '');
         this.cognitoPoolName = cognitoPoolName;
         this.userPoolClientId = userPoolClientId;
         this.oAuth = oAuth;
+        this.clientSecret = clientSecret;
     }
     static getDecodedTokenFromSession(session) {
         const { payload: idToken } = decodeJwt(session.idToken);
@@ -112,7 +113,8 @@ export class CognitoClient {
             ClientId: this.userPoolClientId,
             AuthParameters: {
                 USERNAME: username,
-                SRP_A: A.toString(16)
+                SRP_A: A.toString(16),
+                SECRET_HASH: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
             },
             ClientMetadata: {}
         };
@@ -122,18 +124,20 @@ export class CognitoClient {
         const U = calculateU(A, B);
         const hkdf = getPasswordAuthenticationKey(this.cognitoPoolName, challenge.ChallengeParameters.USER_ID_FOR_SRP, password, B, U, smallA, salt);
         const { signature, timeStamp } = calculateSignature(this.cognitoPoolName, challenge.ChallengeParameters.USER_ID_FOR_SRP, challenge.ChallengeParameters.SECRET_BLOCK, hkdf);
-        const respondToAuthChallengePayload = {
+        const respondToAuthChallengeRequest = {
             ChallengeName: 'PASSWORD_VERIFIER',
             ClientId: this.userPoolClientId,
             ChallengeResponses: {
                 PASSWORD_CLAIM_SECRET_BLOCK: challenge.ChallengeParameters.SECRET_BLOCK,
                 PASSWORD_CLAIM_SIGNATURE: signature,
                 USERNAME: challenge.ChallengeParameters.USER_ID_FOR_SRP,
-                TIMESTAMP: timeStamp
+                TIMESTAMP: timeStamp,
+                SECRET_HASH: this.clientSecret &&
+                    calculateSecretHash(this.clientSecret, this.userPoolClientId, challenge.ChallengeParameters.USER_ID_FOR_SRP)
             },
             ClientMetadata: {}
         };
-        const { AuthenticationResult } = await cognitoRequest(respondToAuthChallengePayload, CognitoServiceTarget.RespondToAuthChallenge, this.cognitoEndpoint);
+        const { AuthenticationResult } = await cognitoRequest(respondToAuthChallengeRequest, CognitoServiceTarget.RespondToAuthChallenge, this.cognitoEndpoint);
         return authResultToSession(AuthenticationResult);
     }
     /**
@@ -151,7 +155,8 @@ export class CognitoClient {
             ClientId: this.userPoolClientId,
             AuthParameters: {
                 USERNAME: username,
-                PASSWORD: password
+                PASSWORD: password,
+                SECRET_HASH: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
             },
             ClientMetadata: {}
         };
@@ -163,15 +168,17 @@ export class CognitoClient {
      * Returns a new session based on the given refresh token.
      *
      * @param refreshToken
+     * @param username
      * @returns @see Session
      * @throws {InitiateAuthException}
      */
-    async refreshSession(refreshToken) {
+    async refreshSession(refreshToken, username) {
         const refreshTokenPayload = {
             AuthFlow: 'REFRESH_TOKEN_AUTH',
             ClientId: this.userPoolClientId,
             AuthParameters: {
-                REFRESH_TOKEN: refreshToken
+                REFRESH_TOKEN: refreshToken,
+                SECRET_HASH: this.clientSecret && username && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
             },
             ClientMetadata: {}
         };
@@ -189,13 +196,14 @@ export class CognitoClient {
      * @throws {SignUpException}
      */
     async signUp(username, password, userAttributes) {
-        const signUpPayload = {
+        const signUpRequest = {
             ClientId: this.userPoolClientId,
             Username: username,
             Password: password,
-            UserAttributes: userAttributes
+            UserAttributes: userAttributes,
+            SecretHash: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
         };
-        const data = await cognitoRequest(signUpPayload, CognitoServiceTarget.SignUp, this.cognitoEndpoint);
+        const data = await cognitoRequest(signUpRequest, CognitoServiceTarget.SignUp, this.cognitoEndpoint);
         return {
             id: data.UserSub,
             confirmed: data.UserConfirmed
@@ -210,12 +218,13 @@ export class CognitoClient {
      * @throws {ConfirmSignUpException}
      */
     async confirmSignUp(username, code) {
-        const confirmSignUpPayload = {
+        const confirmSignUpRequest = {
             ClientId: this.userPoolClientId,
             ConfirmationCode: code,
-            Username: username
+            Username: username,
+            SecretHash: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
         };
-        await cognitoRequest(confirmSignUpPayload, CognitoServiceTarget.ConfirmSignUp, this.cognitoEndpoint);
+        await cognitoRequest(confirmSignUpRequest, CognitoServiceTarget.ConfirmSignUp, this.cognitoEndpoint);
     }
     /**
      *
@@ -283,11 +292,12 @@ export class CognitoClient {
      * @throws {ForgotPasswordException}
      */
     async forgotPassword(username) {
-        const forgotPasswordPayload = {
+        const forgotPasswordRequest = {
             ClientId: this.userPoolClientId,
-            Username: username
+            Username: username,
+            SecretHash: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
         };
-        await cognitoRequest(forgotPasswordPayload, CognitoServiceTarget.ForgotPassword, this.cognitoEndpoint);
+        await cognitoRequest(forgotPasswordRequest, CognitoServiceTarget.ForgotPassword, this.cognitoEndpoint);
     }
     /**
      * Confirms the new password via the given code send via cognito triggered by @see forgotPassword .
@@ -299,13 +309,14 @@ export class CognitoClient {
      * @throws {ConfirmForgotPasswordException}
      */
     async confirmForgotPassword(username, newPassword, confirmationCode) {
-        const confirmForgotPasswordPayload = {
+        const confirmForgotPasswordRequest = {
             ClientId: this.userPoolClientId,
             Username: username,
             ConfirmationCode: confirmationCode,
-            Password: newPassword
+            Password: newPassword,
+            SecretHash: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
         };
-        await cognitoRequest(confirmForgotPasswordPayload, CognitoServiceTarget.ConfirmForgotPassword, this.cognitoEndpoint);
+        await cognitoRequest(confirmForgotPasswordRequest, CognitoServiceTarget.ConfirmForgotPassword, this.cognitoEndpoint);
     }
     /**
      * Triggers cognito to resend the confirmation code
@@ -314,11 +325,12 @@ export class CognitoClient {
      * @throws {ResendConfirmationCodeException}
      */
     async resendConfirmationCode(username) {
-        const resendConfirmationCodePayLoad = {
+        const resendConfirmationCodeRequest = {
             ClientId: this.userPoolClientId,
-            Username: username
+            Username: username,
+            SecretHash: this.clientSecret && calculateSecretHash(this.clientSecret, this.userPoolClientId, username)
         };
-        await cognitoRequest(resendConfirmationCodePayLoad, CognitoServiceTarget.ResendConfirmationCode, this.cognitoEndpoint);
+        await cognitoRequest(resendConfirmationCodeRequest, CognitoServiceTarget.ResendConfirmationCode, this.cognitoEndpoint);
     }
     /**
      * Returns a link to Cognito`s Hosted UI for OAuth2 authentication.

package/lib/utils.d.ts

@@ -21,3 +21,4 @@ export declare function decodeJwt<T = unknown>(jwt: string): {
 };
 export declare function randomBytes(num: number): Promise<Buffer>;
 export declare function formatTimestamp(date: Date): string;
+export declare function calculateSecretHash(clientSecret: string, userPoolClientId: string, username: string): string;

package/lib/utils.js

@@ -123,3 +123,11 @@ export async function randomBytes(num) {
 export function formatTimestamp(date) {
     return formatInTimeZone(date, 'UTC', "EEE MMM d HH:mm:ss 'UTC' yyyy");
 }
+export function calculateSecretHash(clientSecret, userPoolClientId, username) {
+    const message = `${username}${userPoolClientId}`;
+    const hash = Buffer.from(hashJs
+        .hmac(hashJs.sha256, clientSecret)
+        .update(message)
+        .digest()).toString('base64');
+    return hash;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vardario/cognito-client",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "",
   "license": "MIT",
   "author": "Sahin Vardar",