@unchainedshop/core-users 4.8.29 → 5.0.0-alpha.10

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/db/UsersCollection.d.ts

@@ -45,6 +45,8 @@ export type User = {
     pushSubscriptions: PushSubscriptionObject[];
     username?: string;
     meta?: any;
+    tokenVersion?: number;
+    oidcLogoutAt?: Date;
 } & TimestampFields;
 export interface UserQuery {
     includeGuests?: boolean;

package/lib/module/configureUsersModule.d.ts

@@ -130,6 +130,10 @@ export declare const configureUsersModule: (moduleInput: ModuleInput<UserSetting
     updateLastBillingAddress: (_id: string, lastBillingAddress: Address) => Promise<mongodb.WithId<User> | null>;
     updateLastContact: (_id: string, lastContact: Contact) => Promise<mongodb.WithId<User> | null>;
     updateRoles: (_id: string, roles: string[]) => Promise<mongodb.WithId<User> | null>;
+    incrementTokenVersion: (userId: string) => Promise<{
+        tokenVersion: number;
+    } | null>;
+    updateOidcLogoutAt: (userId: string, date: Date) => Promise<User | null>;
     updateTags: (_id: string, tags: string[]) => Promise<mongodb.WithId<User> | null>;
     updateUser: (selector: mongodb.Filter<User>, modifier: mongodb.UpdateFilter<User>, updateOptions?: mongodb.FindOneAndUpdateOptions) => Promise<mongodb.WithId<User> | null>;
     addPushSubscription: (userId: string, subscription: any, subscriptionOptions?: {
@@ -138,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

@@ -1,8 +1,8 @@
 import * as bcrypt from 'bcryptjs';
-import { generateDbFilterById, buildSortOptions, generateDbObjectId, insensitiveTrimmedRegexOperator, escapeRegexString, } from '@unchainedshop/mongodb';
+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";
@@ -97,6 +97,36 @@ export const configureUsersModule = async (moduleInput) => {
         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) {
@@ -616,9 +646,7 @@ export const configureUsersModule = async (moduleInput) => {
         },
         markDeleted: async (userId) => {
             await assertAnotherActiveAdminExists(userId);
-            await db.collection('sessions').deleteMany({
-                session: { $regex: `"user(Id)?":"${escapeRegexString(userId)}"` },
-            });
+            await Users.updateOne({ _id: userId }, { $inc: { tokenVersion: 1 } });
             const user = await Users.findOneAndUpdate({ _id: userId }, {
                 $set: {
                     username: `deleted-${Date.now()}`,
@@ -761,38 +789,27 @@ export const configureUsersModule = async (moduleInput) => {
             });
             return updatedUser;
         },
-        updateRoles: async (_id, roles) => {
-            if (!roles.includes(ADMIN_ROLE))
-                await assertAnotherActiveAdminExists(_id);
-            const user = await Users.findOneAndUpdate(generateDbFilterById(_id), {
-                $set: {
-                    updated: new Date(),
-                    roles,
-                },
+        updateRoles: updateUserRoles,
+        incrementTokenVersion: async (userId) => {
+            const user = await Users.findOneAndUpdate(generateDbFilterById(userId), {
+                $inc: { tokenVersion: 1 },
+                $set: { updated: new Date() },
             }, { returnDocument: 'after' });
             if (!user)
                 return null;
-            await emit('USER_UPDATE_ROLE', {
-                user: removeConfidentialServiceHashes(user),
-            });
-            return user;
+            return { tokenVersion: user.tokenVersion ?? 0 };
         },
-        updateTags: async (_id, tags) => {
-            const user = await Users.findOneAndUpdate(generateDbFilterById(_id), {
+        updateOidcLogoutAt: async (userId, date) => {
+            const user = await Users.findOneAndUpdate(generateDbFilterById(userId), {
                 $set: {
+                    oidcLogoutAt: date,
                     updated: new Date(),
-                    tags,
                 },
-            }, {
-                returnDocument: 'after',
-            });
-            if (!user)
-                return null;
-            await emit('USER_UPDATE_TAGS', {
-                user: removeConfidentialServiceHashes(user),
-            });
+                $inc: { tokenVersion: 1 },
+            }, { returnDocument: 'after' });
             return user;
         },
+        updateTags: updateUserTags,
         updateUser: async (selector, modifier, updateOptions) => {
             const user = await Users.findOneAndUpdate(selector, modifier, {
                 ...updateOptions,
@@ -836,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,10 @@
 {
   "name": "@unchainedshop/core-users",
   "description": "User management module for the Unchained Engine with authentication support",
-  "version": "4.8.29",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "main": "lib/users-index.js",
   "types": "lib/users-index.d.ts",
   "type": "module",
@@ -36,10 +39,10 @@
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
     "@passwordless-id/webauthn": "^2.3.1",
-    "@unchainedshop/events": "^4.8.27",
-    "@unchainedshop/logger": "^4.8.27",
-    "@unchainedshop/mongodb": "^4.8.27",
-    "@unchainedshop/utils": "^4.8.27",
+    "@unchainedshop/events": "^5.0.0-alpha.10",
+    "@unchainedshop/logger": "^5.0.0-alpha.10",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.10",
+    "@unchainedshop/utils": "^5.0.0-alpha.10",
     "bcryptjs": "^3.0.2"
   },
   "peerDependencies": {
@@ -58,6 +61,6 @@
     "@noble/curves": "^2.0.0",
     "@noble/hashes": "^2.0.0",
     "@types/node": "^26.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   }
 }