{"id":24485621,"url":"https://github.com/ilittlebig/easy-auth","last_synced_at":"2026-02-12T21:31:51.356Z","repository":{"id":259270952,"uuid":"877164169","full_name":"ilittlebig/easy-auth","owner":"ilittlebig","description":"AWS Cognito authentication library using AWS SDK with SRP-based login.","archived":false,"fork":false,"pushed_at":"2024-11-26T18:34:19.000Z","size":447,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-04T08:49:46.695Z","etag":null,"topics":["aws","cognito","javascript","library","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ilittlebig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-23T07:43:36.000Z","updated_at":"2024-11-26T18:34:23.000Z","dependencies_parsed_at":"2024-11-04T08:24:29.400Z","dependency_job_id":"ea81b0c4-49c3-440d-b9cc-041b32fcdc19","html_url":"https://github.com/ilittlebig/easy-auth","commit_stats":null,"previous_names":["ilittlebig/aws-cognito-auth-lib","ilittlebig/easy-auth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ilittlebig/easy-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilittlebig%2Feasy-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilittlebig%2Feasy-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilittlebig%2Feasy-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilittlebig%2Feasy-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ilittlebig","download_url":"https://codeload.github.com/ilittlebig/easy-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilittlebig%2Feasy-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29381761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T20:34:40.886Z","status":"ssl_error","status_checked_at":"2026-02-12T20:23:00.490Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cognito","javascript","library","typescript"],"created_at":"2025-01-21T14:19:14.899Z","updated_at":"2026-02-12T21:31:51.335Z","avatar_url":"https://github.com/ilittlebig.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Cognito Authentication Library\nA simple, no-fuss authentication library using AWS SDK with SRP-based login. Designed to make AWS Cognito integration straightforward and secure.\n\n\u003e **Note:** The implementation of this library is inspired by AWS Amplify.\n\n### Features\n-\t🔒 Secure Authentication: Uses SRP (Secure Remote Password) for safe user logins.\n- ⚙️ AWS SDK Integration: Works seamlessly with AWS Cognito.\n- 👤 User Management: Easily handle user registration, login, and password resets.\n-\t✅ Unit Tests: Fully tested to ensure everything works smoothly.\n\n### Table of Contents\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Configuration](#configuration)\n  - [Sign In](#sign-in)\n  - [Reset Password](#reset-password)\n  - [Get Current Session](#get-current-session)\n  - [Get Current User](#get-current-user)\n  - [Sign Out](#sign-out)\n  - [Update Password](#update-password)\n  - [Update MFA Preference](#update-mfa-preference)\n  - [Get MFA Preference](#get-mfa-preference)\n  - [Get Devices](#get-devices)\n  - [Get User Attributes](#get-user-attributes)\n  - [Verify TOTP](#verify-totp)\n  - [Sign Up](#sign-up)\n  - [Confirm Sign Up](#confirm-sign-up)\n  - [Resend Sign Up Code](#resend-sign-up-code)\n  - [Delete User](#delete-user)\n  - [Change Storage Provider](#change-storage-provider)\n- [Running Tests](#running-tests)\n- [References](#references)\n\n### Installation\n1. Run this command:\n```bash\nnpm install @ilittlebig/easy-auth\n```\n\n### Usage\n#### Configuration\nBefore using the authentication functions, configure EasyAuth with your AWS Cognito credentials:\n```ts\nEasyAuth.configure({\n  Auth: {\n    Cognito: {\n      userPoolId: \"your-user-pool-id\",\n      userPoolClientId: \"your-user-pool-client-id\"\n    },\n  }\n});\n```\n\n#### Sign In\nTo sign in a user, pass the username and password:\n```ts\nimport { signIn } from \"easy-auth\";\n\nconst result = await signIn({\n  username: \"email@domain.com\",\n  password: \"LongPassword123!!\"\n});\n```\nThe `signIn` function may return a `nextStep` if further action is needed (e.g., setting a new password or entering an MFA code). You can handle each step based on the `nextStep.signInStep` value:\n```ts\nimport { confirmSignIn } from \"easy-auth\";\n\nif (result.nextStep.signInStep === \"CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED\") {\n  // Handle new password requirement\n  await confirmSignIn({ challengeResponse: \"newPassword123\" });\n}\n```\nWhen all steps are completed, `nextStep.signInStep` will return `DONE`, indicating a successful sign-in.\n\n#### Reset Password\nTo start the password reset flow, provide the username:\n```ts\nimport { resetPassword } from \"easy-auth\";\nawait resetPassword({ username: \"email@domain.com\" });\n```\nIf a confirmation code is required, confirm the password reset:\n```ts\nimport { confirmResetPassword } from \"easy-auth\";\n\nawait confirmResetPassword({\n  username: \"email@domain.com\",\n  confirmationCode: \"123456\",\n  newPassword: \"LongPassword123!!\",\n});\n```\n\n#### Get Current Session\nRetrieve the current session tokens, including the access and ID tokens, along with the user ID (sub). These tokens may contain user information, roles, and expiration details.\n```ts\nimport { getCurrentSession } from \"easy-auth\";\nconst { tokens, sub } = await getCurrentSession();\n```\n\n\n#### Get Current User\nRetrieve the current session tokens and user ID (sub) for ongoing authentication or session management needs.\n```ts\nimport { getCurrentUser } from \"easy-auth\";\nconst { username, userId } = await getCurrentUser();\n```\n\n#### Sign Out\nTo sign out a user, use the `signOut` function. You can pass an optional parameter `{ isGlobal: true | false }` to determine whether the sign-out should be global (across all devices) or just on the current client.\n```ts\nimport { signOut } from \"easy-auth\";\n\n// Sign out from all devices\nawait signOut({ isGlobal: true });\n\n// Sign out only from the current device\nawait signOut({ isGlobal: false });\n```\n\n#### Update Password\nUse the `updatePassword` function to update the password for an authenticated user. This function requires the current (previous) password and the new (proposed) password.\n```ts\nimport { updatePassword } from \"easy-auth\";\n\nawait updatePassword({\n  previousPassword: \"oldPassword123\",\n  proposedPassword: \"newPassword321\"\n});\n```\n\n#### Update MFA Preference\nUse the `updateMFAPreference` function to configure the Multi-Factor Authentication (MFA) preferences for an authenticated user. You can set preferences for both `totp` (Time-based One-Time Password) and `sms` (SMS-based) MFA methods.\n\nBoth `totp` and `sms` preferences are optional and can be set to the following values:\n- `\"PREFERRED\"`: Sets MFA as the preferred authentication method.\n- `\"ENABLED\"`: Enables MFA but does not make it preferred.\n- `\"DISABLED\"`: Disables MFA for this method.\n- `\"NOT_PREFERRED\"`: Sets MFA as non-preferred.\n\n```ts\nimport { updateMFAPreference } from \"easy-auth\";\n\nawait updateMFAPreference({\n  totp: \"PREFERRED\",\n  sms: \"NOT_PREFERRED\"\n});\n```\n\n#### Get MFA Preference\nUse the `getMFAPreference` function to retrieve the current Multi-Factor Authentication (MFA) preferences for an authenticated user. This function provides the user’s preferred MFA method and a list of all enabled MFA settings.\n\nThe response object includes:\n- `preferredMFASetting`: The preferred MFA method, such as `\"TOTP\"`.\n- `userMFASettingList`: An array of enabled MFA methods, like `[\"TOTP\",\"SMS\"]`.\n\n```ts\nimport { getMFAPreference } from \"easy-auth\";\nconst result = await getMFAPreference();\n```\n\n#### Get Devices\nUse the `getDevices` function to retrieve a list of remembered devices associated with the authenticated user. This list includes devices that the user has previously chosen to remember during the login process.\n\n```ts\nimport { getDevices } from \"easy-auth\";\nconst devices = await getDevices();\n```\n\n#### Get User Attributes\nRetrieves key profile details for the authenticated user from AWS Cognito. This data often includes information such as the user's email, verification status, and unique user identifier (sub), among other attributes configured in your Cognito setup.\n\n```ts\nimport { getUserAttributes } from \"easy-auth\";\nconst attributes = await getUserAttributes();\n```\n\n#### Verify TOTP\nVerifies a Time-based One-Time Password (TOTP) code, typically used for Multi-Factor Authentication (MFA). Checks the code provided by the user and returns a result indicating whether the verification was successful or not.\n\nThe result object includes:\n- `status`: `\"SUCCESS\"` if the verification was successful, or `\"ERROR\"` if it failed.\n- `session`: An optional session token included if a session is available.\n\n```ts\nimport { verifyTOTP } from \"easy-auth\";\nconst result = await verifyTOTP();\n```\n\n#### Sign Up\nRegisters a new user with AWS Cognito. To create a user, provide a `username` and `password`. You can also pass optional user attributes to customize the user's profile. AWS Cognito supports the following standard attributes:\n\n- `name`\n- `family_name`\n- `given_name`\n- `middle_name`\n- `nickname`\n- `preferred_username`\n- `profile`\n- `picture`\n- `website`\n- `gender`\n- `birthdate`\n- `zoneinfo`\n- `locale`\n- `updated_at`\n- `address`\n- `email`\n- `phone_number`\n- `sub`\n\nExample:\n```ts\nimport { signUp } from \"easy-auth\";\n\nconst result = await signUp({\n  username: \"email@domain.com\",\n  password: \"LongPassword123!!\",\n  options: {\n    userAttributes: {\n      gender: \"Male\",\n      nickname: \"Olof\"\n    }\n  }\n});\n```\n\n#### Confirm Sign Up\nAfter signing up, the user must confirm their account, typically by entering a confirmation code sent to their email. Use the confirmSignUp function to verify the code and complete the registration process.\n\n```ts\nimport { confirmSignUp } from \"easy-auth\";\n\nlet signUpCode = \"123456\";\n\nconst result = await confirmSignUp({\n  username: \"email@domain.com\",\n  confirmationCode: signUpCode\n});\n```\n\n#### Resend Sign Up Code\nAllows you to resend the confirmation code to a user who is in the process of signing up but hasn’t yet confirmed their account. This is useful if the user didn’t receive the original code or needs a new one.\n\n```ts\nimport { resendSignUpCode } from \"easy-auth\";\n\nconst codeDeliveryDetails = await resendSignUpCode({\n  username: \"email@domain.com\",\n});\n```\n\n#### Delete User\nPermanently deletes the authenticated user's account from AWS Cognito. This action is irreversible and removes all associated user data. It’s typically used when a user wants to close their account.\n\n```ts\nimport { deleteUser } from \"easy-auth\";\nawait deleteUser();\n```\n\n#### Change Storage Provider\nSelect the default storage provider for managing token storage, such as `localStorage` or `inMemoryStorage`, which are stored locally, or opt for `cookieStorage`, where tokens are stored in cookies.\n\n```ts\n// Store tokens in cookies\nimport { EasyAuth, CookieStorage } from \"easy-auth\";\nEasyAuth.setKeyValueStorage(new CookieStorage());\n\n// Store tokens in memory\nimport { EasyAuth, InMemoryStorage } from \"easy-auth\";\nEasyAuth.setKeyValueStorage(new InMemoryStorage());\n```\n\n## Running Tests\nTo run the included unit tests:\n```bash\nnpm test\n```\n\n## References\n- [AWS Amplify](https://github.com/aws-amplify/amplify-js/tree/main)\n- [AWS Cognito](https://aws.amazon.com/pm/cognito/?gclid=Cj0KCQjw4Oe4BhCcARIsADQ0csmmQYKFkPMoXc-u8_XjXmrA8zBWbYHqGLd3a-bxTEeROm9PqxHGvWoaAtF1EALw_wcB\u0026trk=d4ed1ec2-fa74-4450-ad36-bdbfda7b0575\u0026sc_channel=ps\u0026ef_id=Cj0KCQjw4Oe4BhCcARIsADQ0csmmQYKFkPMoXc-u8_XjXmrA8zBWbYHqGLd3a-bxTEeROm9PqxHGvWoaAtF1EALw_wcB:G:s\u0026s_kwcid=AL!4422!3!689494568877!e!!g!!amazon%20cognito!20987280941!164069379011)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filittlebig%2Feasy-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filittlebig%2Feasy-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filittlebig%2Feasy-auth/lists"}