@vardario/cognito-client 2.0.0 → 3.0.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
@@ -117,7 +272,8 @@ export declare enum CognitoServiceTarget {
     ConfirmForgotPassword = "ConfirmForgotPassword",
     ResendConfirmationCode = "ResendConfirmationCode",
     UpdateUserAttributes = "UpdateUserAttributes",
-    VerifyUserAttribute = "VerifyUserAttribute"
+    VerifyUserAttribute = "VerifyUserAttribute",
+    GlobalSignOut = "GlobalSignOut"
 }
 /**
  * Cognito supported federated identities public providers.
@@ -159,7 +315,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;
     /**
      *
@@ -185,11 +342,12 @@ export declare class CognitoClient {
     /**
      * Returns a new session based on the given refresh token.
      *
-     * @param refreshToken
+     * @param refreshToken  Refresh token from a previous session.
+     * @param username Username is required when using a client secret and needs to be the cognito user id.
      * @returns @see Session
      * @throws {InitiateAuthException}
      */
-    refreshSession(refreshToken: string): Promise<Session>;
+    refreshSession(refreshToken: string, username?: string): Promise<Session>;
     /**
      *
      * @param username Username
@@ -238,11 +396,13 @@ export declare class CognitoClient {
      */
     verifyUserAttribute(attributeName: string, code: string, accessToken: string): Promise<void>;
     /**
-     * Sign out the user and remove the current user session.
+     * Revokes all of the access tokens generated by, and at the same time as, the specified refresh token. After a token is revoked, you can't use the revoked token to access Amazon Cognito user APIs, or to authorize access to your resource server.
      *
+     * @param refreshToken Refresh token from a previous session.
+     * @param username Username is required when using a client secret and needs to be the cognito user id.
      * @throws {RevokeTokenException}
      */
-    signOut(refreshToken: string): Promise<void>;
+    revokeToken(refreshToken: string): Promise<void>;
     /**
      * Request forgot password.
      * @param username Username
@@ -293,4 +453,9 @@ export declare class CognitoClient {
      * @throws {Error}
      */
     handleCodeFlow(returnUrl: string, pkce: string): Promise<Session>;
+    /**
+     * Invalidates the identity, access, and refresh tokens that Amazon Cognito issued to a user. Call this operation when your user signs out of your app. This results in the following behavior.
+     * @param accessToken Access token of the current user.
+     */
+    globalSignOut(accessToken: string): Promise<void>;
 }

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
@@ -20,6 +20,7 @@ export var CognitoServiceTarget;
     CognitoServiceTarget["ResendConfirmationCode"] = "ResendConfirmationCode";
     CognitoServiceTarget["UpdateUserAttributes"] = "UpdateUserAttributes";
     CognitoServiceTarget["VerifyUserAttribute"] = "VerifyUserAttribute";
+    CognitoServiceTarget["GlobalSignOut"] = "GlobalSignOut";
 })(CognitoServiceTarget || (CognitoServiceTarget = {}));
 /**
  * Cognito supported federated identities public providers.
@@ -79,12 +80,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 +114,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 +125,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 +156,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: {}
         };
@@ -162,16 +168,18 @@ export class CognitoClient {
     /**
      * Returns a new session based on the given refresh token.
      *
-     * @param refreshToken
+     * @param refreshToken  Refresh token from a previous session.
+     * @param username Username is required when using a client secret and needs to be the cognito user id.
      * @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 +197,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 +219,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);
     }
     /**
      *
@@ -265,14 +275,17 @@ export class CognitoClient {
         await cognitoRequest(verifyUserAttributePayload, CognitoServiceTarget.VerifyUserAttribute, this.cognitoEndpoint);
     }
     /**
-     * Sign out the user and remove the current user session.
+     * Revokes all of the access tokens generated by, and at the same time as, the specified refresh token. After a token is revoked, you can't use the revoked token to access Amazon Cognito user APIs, or to authorize access to your resource server.
      *
+     * @param refreshToken Refresh token from a previous session.
+     * @param username Username is required when using a client secret and needs to be the cognito user id.
      * @throws {RevokeTokenException}
      */
-    async signOut(refreshToken) {
+    async revokeToken(refreshToken) {
         const revokeTokenPayload = {
             Token: refreshToken,
-            ClientId: this.userPoolClientId
+            ClientId: this.userPoolClientId,
+            ClientSecret: this.clientSecret
         };
         await cognitoRequest(revokeTokenPayload, CognitoServiceTarget.RevokeToken, this.cognitoEndpoint);
     }
@@ -283,11 +296,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 +313,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 +329,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.
@@ -402,4 +418,14 @@ export class CognitoClient {
         });
         return session;
     }
+    /**
+     * Invalidates the identity, access, and refresh tokens that Amazon Cognito issued to a user. Call this operation when your user signs out of your app. This results in the following behavior.
+     * @param accessToken Access token of the current user.
+     */
+    async globalSignOut(accessToken) {
+        const globalSignOutPayload = {
+            AccessToken: accessToken
+        };
+        await cognitoRequest(globalSignOutPayload, CognitoServiceTarget.GlobalSignOut, this.cognitoEndpoint);
+    }
 }

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": "3.0.0",
   "description": "",
   "license": "MIT",
   "author": "Sahin Vardar",
@@ -16,8 +16,9 @@
   "scripts": {
     "build": "tsc --build",
     "format": "prettier --plugin-search-dir . --write . && prettier-package-json --write && eslint --fix .",
+    "integration-test": "vitest run integration",
     "prepare": "husky install",
-    "test": "vitest run",
+    "test": "vitest run unit",
     "watch": "tsc --build --watch"
   },
   "dependencies": {
@@ -27,7 +28,7 @@
     "jsbn": "^1.1.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-cognito-identity-provider": "^3.454.0",
+    "@aws-sdk/client-cognito-identity-provider": "^3.465.0",
     "@types/jsbn": "^1.2.33",
     "@types/jsdom": "^21.1.5",
     "@types/randombytes": "^2.0.3",