@unchainedshop/core-users

User management module for the Unchained Engine. Handles user accounts, authentication, profiles, and WebAuthn support.

Installation

npm install @unchainedshop/core-users

Usage

import { configureUsersModule } from '@unchainedshop/core-users';

const usersModule = await configureUsersModule({ db });

// Find users
const users = await usersModule.findUsers({
  includeGuests: false,
  limit: 50,
});

// Create a user
const userId = await usersModule.createUser({
  email: 'user@example.com',
  password: 'securePassword',
});

// Update profile
await usersModule.updateProfile(userId, {
  displayName: 'John Doe',
});

API Overview

Module Configuration

Export	Description
configureUsersModule	Configure and return the users module
configureUsersWebAuthnModule	Configure WebAuthn submodule

Queries

Method	Description
findUser	Find user by ID, email, or username
findUsers	Find users with filtering, sorting, and pagination
count	Count users matching query
userExists	Check if a user exists

Mutations

Method	Description
createUser	Create a new user account
updateUser	Update user data
updateProfile	Update user profile
updateRoles	Update user roles
updateTags	Update user tags
updateAvatar	Set user avatar
updateBillingAddress	Update billing address
updatePassword	Change user password
updateUsername	Change username
delete	Soft delete a user
replaceUserId	Migrate data between users

Authentication

Method	Description
verifyPassword	Verify password against stored hash
hashPassword	Hash a password for storage
addEmail	Add email address to user
removeEmail	Remove email address
verifyEmail	Mark email as verified
updateHeartbeat	Update last activity timestamp
updateLastLogin	Record login event

WebAuthn Submodule

Method	Description
webAuthn.findCredentials	Find WebAuthn credentials for user
webAuthn.createCredential	Register new WebAuthn credential
webAuthn.removeCredential	Remove WebAuthn credential

Settings

Export	Description
userSettings	Access user module settings
UserAccountAction	Account action types enum

Types

Export	Description
User	User document type
UserQuery	Query parameters type
UserProfile	User profile type
Email	Email address type
UsersModule	Module interface type
UserSettingsOptions	Configuration options type

Events

Event	Description
USER_CREATE	User created
USER_UPDATE	User updated
USER_REMOVE	User deleted
USER_UPDATE_PROFILE	Profile updated
USER_UPDATE_PASSWORD	Password changed
USER_UPDATE_ROLES	Roles changed
USER_ACCOUNT_ACTION	Account action triggered

Security

This module implements security best practices for user authentication and data protection.

Password Security

• Algorithm: PBKDF2 with SHA-512
• Iterations: 300,000 (exceeds OWASP recommendation)
• Salt: 16 bytes, cryptographically random per password
• Key Length: 256 bytes
• FIPS 140-3: Compatible when running on FIPS-enabled Node.js

Token Security

• Generation: crypto.randomUUID() (CSPRNG-based)
• Storage: SHA-256 hashed before database storage
• Expiration: Time-limited (configurable, default 1 hour)
• Single-use: Tokens invalidated after verification

WebAuthn/FIDO2

Full support for passwordless authentication via hardware security keys and platform authenticators, providing phishing-resistant authentication.

Data Protection

• Sensitive data (password hashes, tokens) stripped from event emissions via removeConfidentialServiceHashes()
• Soft delete preserves audit trail while removing PII
• Email addresses and profile data access-controlled via RBAC

See SECURITY.md for complete security documentation.

License

EUPL-1.2