Skip to content

README.md

Latest commit

 

History

History
156 lines (116 loc) · 4.47 KB

README.md

File metadata and controls

156 lines (116 loc) · 4.47 KB

npm version License: EUPL-1.2

@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