@unchainedshop/core-users 5.0.0-alpha.4 → 5.0.0-alpha.7

package/README.md

@@ -13,143 +13,22 @@ npm install @unchainedshop/core-users
 
 ## Usage
 
-```typescript
-import { configureUsersModule } from '@unchainedshop/core-users';
-
-const usersModule = await configureUsersModule({ db });
-
-// Find users
-const users = await usersModule.findUsers({
-  includeGuests: false,
-  limit: 50,
-});
+The platform initializes this module as `platform.unchainedAPI.modules.users`.
 
-// Create a user
-const userId = await usersModule.createUser({
-  email: 'user@example.com',
-  password: 'securePassword',
-});
+```typescript
+const { users } = platform.unchainedAPI.modules;
+const customers = await users.findUsers({ includeGuests: false, limit: 50 });
 
-// Update profile
-await usersModule.updateProfile(userId, {
-  displayName: 'John Doe',
+await users.updateProfile('user-123', {
+  profile: { displayName: 'Jane 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
+`updateProfile` accepts an object containing `profile` and optional `meta`. Account creation uses `createUser`; account deletion uses `markDeleted` or `deletePermanently`. Authentication flows and permissions are coordinated by the API layer.
 
-- 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 the [module settings](https://docs.unchained.shop/platform-configuration/modules/users), [authentication guide](https://docs.unchained.shop/concepts/authentication), [public exports](src/users-index.ts), and [module implementation](src/module/configureUsersModule.ts).
 
-See [SECURITY.md](../../SECURITY.md) for complete security documentation.
+For security reporting and the implementation's security properties, see [SECURITY.md](../../SECURITY.md).
 
 ## License
 

package/lib/module/configureUsersModule.d.ts

@@ -142,5 +142,16 @@ export declare const configureUsersModule: (moduleInput: ModuleInput<UserSetting
     }) => Promise<void>;
     removePushSubscription: (userId: string, p256dh: string) => Promise<void>;
     existingTags: () => Promise<string[]>;
+    bulkUpdateTags: (userIds: string[], { add, remove }: {
+        add?: string[];
+        remove?: string[];
+    }) => Promise<{
+        successIds: string[];
+        failedIds: string[];
+    }>;
+    bulkUpdateRoles: (userIds: string[], roles: string[]) => Promise<{
+        successIds: string[];
+        failedIds: string[];
+    }>;
 }>;
 export type UsersModule = Awaited<ReturnType<typeof configureUsersModule>>;

package/lib/module/configureUsersModule.js

@@ -2,7 +2,7 @@ import * as bcrypt from 'bcryptjs';
 import { generateDbFilterById, buildSortOptions, generateDbObjectId, insensitiveTrimmedRegexOperator, } from '@unchainedshop/mongodb';
 import { UsersCollection, } from "../db/UsersCollection.js";
 import { emit, registerEvents } from '@unchainedshop/events';
-import { systemLocale, SortDirection, sha256, normalizePhoneNumber, } from '@unchainedshop/utils';
+import { executeBulkOperation, systemLocale, SortDirection, sha256, normalizePhoneNumber, } from '@unchainedshop/utils';
 import { UserAccountAction, userSettings, } from "../users-settings.js";
 import { configureUsersWebAuthnModule } from "./configureUsersWebAuthnModule.js";
 import * as pbkdf2 from "./pbkdf2.js";
@@ -27,6 +27,7 @@ const USER_EVENTS = [
     'USER_UPDATE_WEB3_ADDRESS',
     'USER_REMOVE',
 ];
+const ADMIN_ROLE = 'admin';
 export const removeConfidentialServiceHashes = (rawUser) => {
     const user = { ...rawUser };
     delete user?.services;
@@ -88,6 +89,44 @@ export const configureUsersModule = async (moduleInput) => {
     registerEvents(USER_EVENTS);
     const Users = await UsersCollection(db);
     const webAuthn = await configureUsersWebAuthnModule(moduleInput);
+    const assertAnotherActiveAdminExists = async (userId) => {
+        const user = await Users.findOne({ _id: userId, deleted: null });
+        if (!user?.roles?.includes(ADMIN_ROLE))
+            return;
+        const activeAdminCount = await Users.countDocuments({ deleted: null, roles: ADMIN_ROLE }, { limit: 2 });
+        if (activeAdminCount <= 1)
+            throw new Error('At least one active administrator is required. Assign another administrator before removing this account or revoking its admin role.', { cause: 'LAST_ADMIN' });
+    };
+    const updateUserRoles = async (_id, roles) => {
+        if (!roles.includes(ADMIN_ROLE))
+            await assertAnotherActiveAdminExists(_id);
+        const user = await Users.findOneAndUpdate(generateDbFilterById(_id), {
+            $set: {
+                updated: new Date(),
+                roles,
+            },
+        }, { returnDocument: 'after' });
+        if (!user)
+            return null;
+        await emit('USER_UPDATE_ROLE', {
+            user: removeConfidentialServiceHashes(user),
+        });
+        return user;
+    };
+    const updateUserTags = async (_id, tags) => {
+        const user = await Users.findOneAndUpdate(generateDbFilterById(_id), {
+            $set: {
+                updated: new Date(),
+                tags,
+            },
+        }, { returnDocument: 'after' });
+        if (!user)
+            return null;
+        await emit('USER_UPDATE_TAGS', {
+            user: removeConfidentialServiceHashes(user),
+        });
+        return user;
+    };
     return {
         webAuthn,
         async count(query) {
@@ -606,6 +645,7 @@ export const configureUsersModule = async (moduleInput) => {
             return user;
         },
         markDeleted: async (userId) => {
+            await assertAnotherActiveAdminExists(userId);
             await Users.updateOne({ _id: userId }, { $inc: { tokenVersion: 1 } });
             const user = await Users.findOneAndUpdate({ _id: userId }, {
                 $set: {
@@ -633,6 +673,7 @@ export const configureUsersModule = async (moduleInput) => {
             return user;
         },
         deletePermanently: async ({ userId }) => {
+            await assertAnotherActiveAdminExists(userId);
             return Users.findOneAndDelete({ _id: userId });
         },
         updateProfile: async (userId, updatedData) => {
@@ -748,23 +789,7 @@ export const configureUsersModule = async (moduleInput) => {
             });
             return updatedUser;
         },
-        updateRoles: async (_id, roles) => {
-            const modifier = {
-                $set: {
-                    updated: new Date(),
-                    roles,
-                },
-            };
-            const user = await Users.findOneAndUpdate(generateDbFilterById(_id), modifier, {
-                returnDocument: 'after',
-            });
-            if (!user)
-                return null;
-            await emit('USER_UPDATE_ROLE', {
-                user: removeConfidentialServiceHashes(user),
-            });
-            return user;
-        },
+        updateRoles: updateUserRoles,
         incrementTokenVersion: async (userId) => {
             const user = await Users.findOneAndUpdate(generateDbFilterById(userId), {
                 $inc: { tokenVersion: 1 },
@@ -784,22 +809,7 @@ export const configureUsersModule = async (moduleInput) => {
             }, { returnDocument: 'after' });
             return user;
         },
-        updateTags: async (_id, tags) => {
-            const user = await Users.findOneAndUpdate(generateDbFilterById(_id), {
-                $set: {
-                    updated: new Date(),
-                    tags,
-                },
-            }, {
-                returnDocument: 'after',
-            });
-            if (!user)
-                return null;
-            await emit('USER_UPDATE_TAGS', {
-                user: removeConfidentialServiceHashes(user),
-            });
-            return user;
-        },
+        updateTags: updateUserTags,
         updateUser: async (selector, modifier, updateOptions) => {
             const user = await Users.findOneAndUpdate(selector, modifier, {
                 ...updateOptions,
@@ -843,5 +853,25 @@ export const configureUsersModule = async (moduleInput) => {
             }));
             return tags.filter(Boolean).toSorted();
         },
+        bulkUpdateTags: async (userIds, { add = [], remove = [] }) => {
+            const tagsToRemove = new Set(remove);
+            return executeBulkOperation(userIds, async (userId) => {
+                const user = await Users.findOne({ _id: userId, deleted: null }, {});
+                if (!user)
+                    throw new Error('not-found');
+                const tags = (user.tags || []).filter((tag) => !tagsToRemove.has(tag));
+                for (const tag of add) {
+                    if (!tags.includes(tag))
+                        tags.push(tag);
+                }
+                await updateUserTags(userId, tags);
+            });
+        },
+        bulkUpdateRoles: async (userIds, roles) => executeBulkOperation(userIds, async (userId) => {
+            const user = await Users.findOne({ _id: userId, deleted: null }, { projection: { _id: 1 } });
+            if (!user)
+                throw new Error('not-found');
+            await updateUserRoles(userId, roles);
+        }),
     };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unchainedshop/core-users",
   "description": "User management module for the Unchained Engine with authentication support",
-  "version": "5.0.0-alpha.4",
+  "version": "5.0.0-alpha.7",
   "main": "lib/users-index.js",
   "types": "lib/users-index.d.ts",
   "type": "module",
@@ -36,10 +36,10 @@
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
     "@passwordless-id/webauthn": "^2.3.1",
-    "@unchainedshop/events": "^5.0.0-alpha.1",
-    "@unchainedshop/logger": "^5.0.0-alpha.1",
-    "@unchainedshop/mongodb": "^5.0.0-alpha.1",
-    "@unchainedshop/utils": "^5.0.0-alpha.1",
+    "@unchainedshop/events": "^5.0.0-alpha.7",
+    "@unchainedshop/logger": "^5.0.0-alpha.7",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.7",
+    "@unchainedshop/utils": "^5.0.0-alpha.7",
     "bcryptjs": "^3.0.2"
   },
   "peerDependencies": {