identityuser
Advanced tools
A lightweight and ready-to-use User Authentication Starter Kit for Next.js applications. IdentityUser helps you quickly scaffold a fully functional authentication system into your project — including models, validation schemas, services, utilities, and optional NextAuth integration.
Perfect for developers who want a clean, modular, and production-ready user system with minimal setup.
IdentityUser v0.4.0 introduces major improvements to authentication flows, password policies, and session handling — making it suitable for production-grade and enterprise-level applications.
IdentityUser now supports four secure login methods:
Each method is fully isolated, rate-limited, and hardened against brute-force attacks.
Remember This Device
Fallback Login
Session behavior is now smarter and configurable:
JWT & Session configuration:
jwt.maxAge: 7 dayssession.maxAge: 1 daysession.updateAge: 30 minutesHere are all related resources for the IdentityUser package:
https://www.npmjs.com/package/identityuser
https://github.com/SadeghShojayefard/identityuser
A full working Next.js project demonstrating how to use the package:
https://github.com/SadeghShojayefard/identityusers_sample
Complete setup guide and technical explanation: https://github.com/SadeghShojayefard/identityusers_sample/blob/main/IdentityUser_Documentation.pdf
Run the following command inside your Next.js project:
npm install identityuser
IdentityUser includes a CLI tool that copies the entire src/identityUser folder into your project.
Run:
npx identityuser
After running this command, a folder like this will appear inside your project:
Note: If a folder named src/identityUser already exists in your project, the CLI will not overwrite it. Instead it will create a new folder with a numeric suffix (identityUser-2, identityUser-3, …) to avoid conflicts. You may need to adjust imports or merge files manually after running the CLI.
src/
└── identityUser/
├── api/
├── components/
├── helper/
├── lib/
├── providers/
├── Type/
└── validation/
IdentityUser relies on several peer dependencies that must be installed manually (npm does not auto-install peerDependencies).
Install all required packages with:
npm install next-auth bcrypt mongoose zod @conform-to/zod @conform-to/react resend @upstash/ratelimit @upstash/redis otplib qrcode
🔹 If you're using TypeScript, also install to get the bycrypt and :
npm install -D @types/bcrypt @types/qrcode
If you are using Zod v4, the required_error field has been removed.
So instead of:
z.string({ required_error: "Please fill the Username field first" })
Use:
z.string({ error: "Please fill the Username field first" })
Or use .min() / .email() / .max() validation messages directly.
IdentityUser’s internal schemas follow Zod v4 syntax.
A full authentication starter pack will be added to:
src/identityUser/
Including: app folder
📦src
┣ 📂app
┃ ┗ 📂api
┃ ┃ ┣ 📂auth
┃ ┃ ┃ ┗ 📂[...nextauth]
┃ ┃ ┃ ┃ ┗ 📜route.ts
┃ ┃ ┗ 📂session
┃ ┃ ┃ ┗ 📂update
┃ ┃ ┃ ┃ ┗ 📜route.ts
identityUser folder
📦src
┗ 📂identityUser
┃ ┣ 📂api
┃ ┃ ┗ 📂auth
┃ ┃ ┃ ┗ 📂[...nextauth]
┃ ┃ ┃ ┃ ┣ 📜authHelpers.ts
┃ ┃ ┃ ┃ ┗ 📜options.ts
┃ ┣ 📂components
┃ ┃ ┗ 📂sessionWatcher
┃ ┃ ┃ ┗ 📜SessionWatcher.tsx
┃ ┣ 📂helper
┃ ┃ ┣ 📜claimsAction.ts
┃ ┃ ┣ 📜roleAction.ts
┃ ┃ ┣ 📜sharedFunction.ts
┃ ┃ ┣ 📜signInAction.ts
┃ ┃ ┣ 📜signUpformAction.ts
┃ ┃ ┗ 📜userAction.ts
┃ ┣ 📂lib
┃ ┃ ┣ 📂models
┃ ┃ ┃ ┣ 📜identityUser_claims.ts
┃ ┃ ┃ ┣ 📜identityUser_passwordHistory.ts
┃ ┃ ┃ ┣ 📜identityUser_roleClaims.ts
┃ ┃ ┃ ┣ 📜identityUser_roles.ts
┃ ┃ ┃ ┣ 📜identityUser_Tokens.ts
┃ ┃ ┃ ┣ 📜identityUser_userClaims.ts
┃ ┃ ┃ ┣ 📜identityUser_userRoles.ts
┃ ┃ ┃ ┗ 📜identityUser_users.ts
┃ ┃ ┣ 📂utils
┃ ┃ ┃ ┗ 📜rateLimit.ts
┃ ┃ ┣ 📜authGuard.ts
┃ ┃ ┣ 📜db.ts
┃ ┃ ┗ 📜session.ts
┃ ┣ 📂providers
┃ ┃ ┗ 📜SessionProvider.tsx
┃ ┣ 📂Type
┃ ┃ ┗ 📜next-auth.d.ts
┃ ┗ 📂validation
┃ ┃ ┣ 📜addUserValidation.ts
┃ ┃ ┣ 📜changeEmailValidation.ts
┃ ┃ ┣ 📜changeNameValidation.ts
┃ ┃ ┣ 📜changePassword.ts
┃ ┃ ┣ 📜ChangePasswordUserValidation.ts
┃ ┃ ┣ 📜changePhoneNumebrValidation.ts
┃ ┃ ┣ 📜changeUserNameValidation.ts
┃ ┃ ┣ 📜claimsValidation.ts
┃ ┃ ┣ 📜deleteValidation.ts
┃ ┃ ┣ 📜emailVerifyValidation.ts
┃ ┃ ┣ 📜fallbackValidation.ts
┃ ┃ ┣ 📜forgetPasswordValidation.ts
┃ ┃ ┣ 📜otpValidation.ts
┃ ┃ ┣ 📜phoneVerifyValidation.ts
┃ ┃ ┣ 📜resetPasswordValidation.ts
┃ ┃ ┣ 📜signInOTPValidation.ts
┃ ┃ ┣ 📜signInValidation.ts
┃ ┃ ┣ 📜signUpValidation.ts
┃ ┃ ┣ 📜twoStepEnableValidation.ts
┃ ┃ ┣ 📜updateClaimsValidation.ts
┃ ┃ ┣ 📜userRoleUpdateValidation.ts
┃ ┃ ┣ 📜userRoleValidation.ts
┃ ┃ ┣ 📜usersAddValidation.ts
┃ ┃ ┣ 📜usersEditValidation.ts
┃ ┃ ┣ 📜verify2FAValidation.ts
┃ ┃ ┗ 📜verify2StepValidation.ts
export async function getRolesForAddUserAction() {
try {
await dbConnect();
const roles = await IdentityUser_Roles.find({}, `name`)
.lean<{ _id: mongoose.Types.ObjectId; name: string }[]>()
.exec();
return {
status: "success",
payload: roles.map((role) => ({
id: role._id.toString(),
name: role.name,
})),
} as const;
} catch (error) {
console.error('Error fetching roles:', error);
return {
status: 'error',
payload: [],
} as const;
}
}
export const hashPassword = async (password: string) => {
const salt = await bcrypt.genSalt(10);
const hash = await bcrypt.hash(password, salt);
return hash;
}
export async function addClaimAction(prevState: unknown, formData: FormData) {
if (!(await hasClaim("add-Claims"))) {
return {
status: 'error',
payload: {
message: 'no access for this action',
},
} as const;
}
const subMission = parseWithZod(formData, {
schema: claimsSchema(),
});
if (subMission.status !== "success") {
return subMission.reply();
}
try {
// connect to database
await dbConnect();
// Create new claim and save to database
const { claimType, claimValue, description } = subMission.value;
await IdentityUser_Claims.create({
claimType,
claimValue,
description
});
// Revalidate the page
revalidatePath('/cmsClaims');
return {
status: 'success',
payload: {
message: '',
},
} as const;
} catch (error) {
console.error('Error saving contact form:', error);
return {
status: 'error',
payload: {
message: '',
},
} as const;
}
}
IdentityUser supports:
Tested with Next.js 15 and 16.
If you want to upgrade an older Next 15 project, run:
npm install next@latest react@latest react-dom@latest
Then update your tsconfig.json or next.config.js if needed.
I can guide you step-by-step — just ask when ready.
Contributions, issues, and feature requests are welcome.
Sadegh Shojayefard
Release Date: 2025-12-13
This release significantly enhances authentication security, session handling, and password management.
IdentityUser is now suitable for complex real-world authentication scenarios.
Release Date: 2025-12-05
This release introduces the most advanced security features added to IdentityUser so far.
A complete verification system is now available, including password recovery, email/phone verification, and full TOTP-based two-factor authentication.
| Feature | Description |
|---|---|
| Forgot Password | Reset password via email or phone OTP |
| Email Verification | Verify user email with a sending token to email |
| Phone Verification | Verify phone number with OTP |
| OTP Login | Two-step login with TOTP 2FA |
| TOTP 2FA | Authenticator app support (Google Authenticator, Authy, etc.) |
| Recovery Codes | Backup codes for emergency login |
forgotPasswordRequestActioncreateEmailPasswordResetTokenActionsendPasswordResetEmailresetForgetPasswordActioncreatePhonePasswordResetTokenActionverifyOtpActioncreateEmailVerificationTokensendVerifyTokenForEmailverifyEmailTokencreatPhoneVerificationOTPverifyPhoneActiongenerate2FASecretActiongenerateQRCodeActionverify2FAActionverifyLogin2FAActionverifyRecoveryCodeActiontwoFactorSecretrecoveryCodesidentityUser_TokensNone.
Version 0.3.0 introduces multiple new features but does not break backwards compatibility with version 0.2.0.
0.2.0 – Major Action Updates, Bug Fixes
Release date: 2025-11-26
The installer is now fully smart and collision-safe:
✔ If the identityuser folder already exists, a new version is automatically created: identityuser, identityuser-2, identityuser-3, ...
✔ All internal imports are automatically rewritten: from @/identityuser/... to @/identityuser-2/... (or the correct version)
✔ The NextAuth route file is always rewritten with the correct import path.
Result: multiple installations without conflicts, no broken imports, and no accidental file overwrites.
This update improves naming consistency, fixes several bugs, adds new helper methods, and introduces multiple new user-related actions.
For better readability and consistency:
| Old Name | New Name |
|---|---|
| changePasswordAction | resetPasswordAction |
| changePasswordProfileAction | changePasswordAction |
| checkEmailExistAction | checkUserExistByEmailAction |
These actions help verify whether a user exists based on ID, email, or phone number:
Shared logic has been moved into a reusable helper:
Note: Phone-number checks should only be used when your project requires phone numbers to be unique.
Bug fixes & improved filtering logic:
Newly added:
Shared helper added:
Note: Phone-number lookup should only be enabled when the phone number must remain unique.
Two new actions were added for updating user fields:
Manually lock or unlock a user:
Manually reset the security stamp:
The version was updated from:
0.1.8 → 0.2.0
Because:
This package follows responsible security practices.
Minimum supported versions:
MIT License — free for personal and commercial use.
If you like this package, don't forget to star the GitHub repo.
FAQs
Identity & Claims system for Next.js (CLI + Copyable template)
The npm package identityuser receives a total of 1 weekly downloads. As such, identityuser popularity was classified as not popular.
We found that identityuser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.