Meow Cognito Passwordless Auth (Client)


A client-side library for implementing passwordless authentication with Amazon Cognito. This package provides the frontend implementation for various secure passwordless authentication methods:

- FIDO2: aka WebAuthn, i.e. sign in with Face, Touch, YubiKey, etc. This includes support for Passkeys (i.e. usernameless authentication).
- Device Authentication: allow users to authenticate with trusted devices after initial verification.
- TOTP MFA: support for Time-Based One-Time Password multi-factor authentication.

This is an opinionated fork of the original Amazon Cognito Passwordless Auth solution, maintained by @joinmeow. Unlike the original library, this fork focuses exclusively on secure authentication methods and eliminates less secure options, creating a more streamlined and security-focused implementation. This client-only version is intended for use with an already configured backend.

Installation

This package is published on npm and can be installed directly:

``shell
npm install @joinmeow/cognito-passwordless-auth
`

Or with Yarn:

`shell
yarn add @joinmeow/cognito-passwordless-auth
`

Usage

This library provides implementations for different frontend frameworks:

$3

`javascript
import {
configure,
initialize,
signUp,
confirmSignUp,
prepareFido2SignIn,
authenticateWithFido2,
authenticateWithSRP,
} from "@joinmeow/cognito-passwordless-auth";

// Configure the client
configure({
userPoolId: "us-east-1_example",
clientId: "abcdefghijklmnopqrstuvwxyz",
// Other configuration parameters as needed
});

// Initialize (handles things like redirects)
initialize();

// Sign up a new user
await signUp({
username: "user@example.com",
password: "securePassword123",
userAttributes: [
{ name: "email", value: "user@example.com" },
{ name: "name", value: "Jane Doe" },
],
});

// Confirm sign up with verification code
await confirmSignUp({
username: "user@example.com",
confirmationCode: "123456",
});

// Optionally pre-fetch the WebAuthn assertion (e.g. for conditional mediation)
const prepared = await prepareFido2SignIn({
username: "user@example.com",
});

// Start the sign-in process with FIDO2. Pass the prepared bundle to skip
// re-triggering navigator.credentials.get(). If you omit prepared, the
// helper will prompt the user as usual.
const { signedIn } = await authenticateWithFido2({ prepared });

// Wait for the sign-in process to complete
await signedIn;

// Sign-in with SRP without MFA (no rememberDevice callback needed)
const { signedIn } = await authenticateWithSRP({
username: "user@example.com",
password: "password123",
});

// If your user pool enforces an OTP second factor, provide the callback so it can
// ask the user after they enter the OTP:
const { signedIn: signedInWithOtp } = await authenticateWithSRP({
username: "user@example.com",
password: "password123",
rememberDevice: async () => {
return window.confirm("Remember this device?");
},
});

// Sign out
await signOut();
`

$3

`jsx
import React, { useState, useEffect } from "react";
import {
PasswordlessContextProvider,
usePasswordless,
useTotpMfa,
} from "@joinmeow/cognito-passwordless-auth/react";

function App() {
return (



);
}

function YourApp() {
const {
signInStatus,
prepareFido2SignIn,
authenticateWithFido2,
authenticateWithSRP,
tokens,
updateDeviceStatus,
} = usePasswordless();
const [showRememberDevice, setShowRememberDevice] = useState(false);

// Check if we need to ask the user about remembering this device
useEffect(() => {
if (tokens?.userConfirmationNecessary) {
setShowRememberDevice(true);
}
}, [tokens]);

// Handle user's choice about remembering the device
const handleRememberDevice = async (remember) => {
if (tokens?.deviceKey && tokens?.accessToken) {
await updateDeviceStatus({
deviceKey: tokens.deviceKey,
deviceRememberedStatus: remember ? "remembered" : "not_remembered",
});
setShowRememberDevice(false);
}
};

// For TOTP MFA setup
const { setupStatus, secretCode, qrCodeUrl, beginSetup, verifySetup } =
useTotpMfa();

if (signInStatus === "SIGNED_IN") {
return (


When you call signInWithGoogle(), the library builds the Google OAuth2 authorization URL (including client ID, PKCE challenge, state, scopes, etc.) and redirects the browser. After the user signs in, Google redirects back to your registered redirectUri with ?code=...&state=....

On your callback page, call handleGoogleCallback() from @joinmeow/cognito-passwordless-auth/client/google to complete the flow:

Plain-JS / Multi-Page Example:

`html


`

React Single-Page App Example:

`jsx
// GoogleCallback.jsx
import { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { handleGoogleCallback } from "@joinmeow/cognito-passwordless-auth/client/google";

export function GoogleCallback() {
const navigate = useNavigate();

useEffect(() => {
(async () => {
try {
await handleGoogleCallback();
navigate("/dashboard");
} catch (err) {
console.error("Google callback error", err);
navigate("/login?error=oauth");
}
})();
}, [navigate]);

return

1. Configure Google OAuth in configure({ google: { clientId, redirectUri, scopes } }).
2. Initiate sign-in:

`js
import { signInWithGoogle } from "@joinmeow/cognito-passwordless-auth/client/google";
signInWithGoogle()}>Sign in with Google;
`

3. After redirect, your callback page or component calls handleGoogleCallback() to exchange the code, store tokens, clean up the URL, and return the tokens.
4. Redirect users to your protected routes (e.g. /dashboard).

Advanced Features

$3

The complete sign-up flow consists of:

`javascript
// 1. Register a new user
await signUp({
username: "user@example.com",
password: "securePassword123",
userAttributes: [{ name: "email", value: "user@example.com" }],
});

// 2. If an error occurs during sign-up, you can resend the confirmation code
await resendConfirmationCode({ username: "user@example.com" });

// 3. Confirm the sign-up with the verification code that was sent to the user
await confirmSignUp({
username: "user@example.com",
confirmationCode: "123456", // Code received via email or SMS
});

// 4. After sign-up confirmation, the user can sign in
const { signedIn } = await authenticateWithSRP({
username: "user@example.com",
password: "securePassword123",
rememberDevice: async () => {
return window.confirm("Remember this device?");
},
});
`

$3

Device authentication allows users to bypass MFA on subsequent sign-ins from the same device. The library handles most of this automatically:

`javascript
// 1. User signs in with SRP or another method
const { signedIn } = await authenticateWithSRP({
username: "user@example.com",
password: "securePassword123",
rememberDevice: async () => {
return window.confirm("Remember this device?");
},
});

// 2. Wait for the sign-in to complete - including any "remember device" decisions
const tokens = await signedIn;

// 3. The signedIn promise won't resolve until:
// - User explicitly said "don't remember", or
// - The UpdateDeviceStatus call has completed, or
// - No rememberDevice callback was supplied
`

How device authentication works:

1. Device Confirmation (automatic): When a user signs in with MFA on a new device, the library automatically registers the device with Cognito.

2. Device Remembering (user choice): When userConfirmationNecessary is true, your app's rememberDevice callback is invoked, giving you control over when and how to ask the user.

3. Atomic Authentication Flow: The signedIn promise doesn't resolve until the entire flow (including device status updates) is complete.

4. Subsequent Sign-ins: On remembered devices, users bypass MFA automatically.

Important: The rememberDevice callback is only invoked after successful MFA authentication (like TOTP or SMS). For users without MFA enabled, or for sign-ins that don't trigger an MFA step, the callback will never be invoked and device remembering is not possible.

$3

Set up Time-Based One-Time Password MFA for a user:

`javascript
// Configure the TOTP issuer (defaults to "YourApp")
configure({
// ... other configuration
totp: {
issuer: "YourCompany", // The name shown in authenticator apps
},
});

// In a React component
const { setupStatus, secretCode, qrCodeUrl, beginSetup, verifySetup } =
useTotpMfa();

// Start setup
await beginSetup();

// Show QR code to user (qrCodeUrl contains the otpauth:// URL)
// The QR code will show "YourCompany:username" in authenticator apps
// ...

// Verify the code from the user's authenticator app
await verifySetup(userEnteredCode, "My Authenticator");
`

> Note: TOTP MFA setup requires proper configuration. The issuer setting controls what name appears in authenticator apps like Google Authenticator or Authy.

$3

The library provides comprehensive device management capabilities for trusted device authentication:

#### React Hook Usage

`jsx
import React, { useState } from "react";
import { usePasswordless } from "@joinmeow/cognito-passwordless-auth/react";

function DeviceManager() {
const {
deviceKey,
confirmDevice,
updateDeviceStatus,
forgetDevice,
clearDeviceKey,
tokens,
} = usePasswordless();
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

const handleConfirmDevice = async () => {
if (!deviceKey) return;

try {
setLoading(true);
setError(null);
await confirmDevice("My Laptop");
console.log("Device confirmed successfully");
} catch (error) {
console.error("Failed to confirm device:", error);
setError(error.message);
} finally {
setLoading(false);
}
};

const handleRememberDevice = async (remember: boolean) => {
if (!deviceKey) return;

try {
setLoading(true);
setError(null);
await updateDeviceStatus({
deviceKey,
deviceRememberedStatus: remember ? "remembered" : "not_remembered",
});
} catch (error) {
console.error("Failed to update device status:", error);
setError(error.message);
} finally {
setLoading(false);
}
};

const handleForgetDevice = async () => {
try {
setLoading(true);
setError(null);
await forgetDevice(); // Forgets current device
// Or forget a specific device: await forgetDevice(specificDeviceKey);
} catch (error) {
console.error("Failed to forget device:", error);
setError(error.message);
} finally {
setLoading(false);
}
};

return (


`javascript
// 1. After successful authentication with MFA, a device key is available
const { signedIn } = await authenticateWithSRP({
username: "user@example.com",
password: "password123",
rememberDevice: async () => {
// This callback is called when userConfirmationNecessary is true
return window.confirm("Remember this device for future sign-ins?");
},
});

// 2. The device is automatically confirmed and optionally remembered
const tokens = await signedIn;

// 3. Manually manage device status later
if (tokens.deviceKey) {
// Update device status
await updateDeviceStatus({
deviceKey: tokens.deviceKey,
deviceRememberedStatus: "remembered",
});

// Or forget the device entirely
await forgetDevice(tokens.deviceKey);
}
`

$3

Manage WebAuthn/FIDO2 credentials for passwordless authentication:

#### React Hook Usage

`jsx
import React, { useState } from "react";
import { usePasswordless } from "@joinmeow/cognito-passwordless-auth/react";

function FIDO2Manager() {
const {
fido2Credentials,
creatingCredential,
fido2CreateCredential,
userVerifyingPlatformAuthenticatorAvailable,
} = usePasswordless();
const [error, setError] = useState(null);

const handleCreateCredential = async () => {
try {
setError(null);
await fido2CreateCredential({
friendlyName: "My Face ID",
});
console.log("FIDO2 credential created successfully");
} catch (error) {
console.error("Failed to create FIDO2 credential:", error);
setError(error.message);
}
};

const handleUpdateCredential = async (credential, newName) => {
try {
setError(null);
await credential.update({ friendlyName: newName });
console.log("Credential updated successfully");
} catch (error) {
console.error("Failed to update credential:", error);
setError(error.message);
}
};

const handleDeleteCredential = async (credential) => {
if (!window.confirm("Are you sure you want to delete this credential?")) {
return;
}

try {
setError(null);
await credential.delete();
console.log("Credential deleted successfully");
} catch (error) {
console.error("Failed to delete credential:", error);
setError(error.message);
}
};

return (