@unchainedshop/core-users 4.5.0 → 4.6.1

package/README.md

@@ -120,6 +120,37 @@ await usersModule.updateProfile(userId, {
 | `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](../../SECURITY.md) for complete security documentation.
+
 ## License
 
 EUPL-1.2

package/lib/db/UsersCollection.d.ts

@@ -30,7 +30,7 @@ export interface Email {
 }
 export type User = {
     _id: string;
-    deleted?: Date;
+    deleted?: Date | null;
     avatarId?: string;
     emails: Email[];
     guest: boolean;
@@ -55,6 +55,8 @@ export interface UserQuery {
     tags?: string[];
     userIds?: string[];
     username?: string;
+    usernames?: string[];
+    emails?: string[];
     web3Verified?: boolean;
 }
 export declare const UsersCollection: (db: mongodb.Db) => Promise<mongodb.Collection<User>>;

package/lib/db/WebAuthnCredentialsCreationRequestsCollection.d.ts

@@ -6,7 +6,7 @@ export interface WebAuthnCredentialsCreationRequest {
     factor: 'first' | 'second' | 'either';
 }
 type Collection = WebAuthnCredentialsCreationRequest & {
-    _id: number;
+    _id: string;
 };
 export declare const WebAuthnCredentialsCreationRequestsCollection: (db: mongodb.Db) => Promise<mongodb.Collection<Collection>>;
 export {};

package/lib/module/configureUsersModule.d.ts

@@ -3,7 +3,7 @@ import { type User, type UserQuery, type Email, type UserLastLogin, type UserPro
 import { type SortOption } from '@unchainedshop/utils';
 import { type UserRegistrationData, type UserSettingsOptions } from '../users-settings.ts';
 export declare const removeConfidentialServiceHashes: (rawUser: User) => User;
-export declare const buildFindSelector: ({ includeGuests, includeDeleted, queryString, emailVerified, lastLogin, tags, userIds, username, web3Verified, }: UserQuery) => mongodb.Filter<User>;
+export declare const buildFindSelector: ({ includeGuests, includeDeleted, queryString, emailVerified, lastLogin, tags, userIds, username, usernames, emails, web3Verified, }: UserQuery) => mongodb.Filter<User>;
 export declare const configureUsersModule: (moduleInput: ModuleInput<UserSettingsOptions>) => Promise<{
     webAuthn: {
         findMDSMetadataForAAGUID: (aaguid: string) => Promise<{
@@ -33,7 +33,7 @@ export declare const configureUsersModule: (moduleInput: ModuleInput<UserSetting
             counter?: number;
             transports?: import("@passwordless-id/webauthn/dist/esm/types.js").ExtendedAuthenticatorTransport[];
         }[], username: string, credentials: import("@passwordless-id/webauthn/dist/esm/types.js").AuthenticationJSON & {
-            requestId: number;
+            requestId: string;
         }) => Promise<{
             userHandle: string;
             counter: number;
@@ -95,6 +95,10 @@ export declare const configureUsersModule: (moduleInput: ModuleInput<UserSetting
         created: Date;
     }): Promise<User | null>;
     removeWebAuthnCredential(userId: string, credentialsId: string): Promise<User | null>;
+    createAccessToken(username: string): Promise<{
+        user: User;
+        token: string;
+    } | null>;
     setAccessToken(username: string, plainSecret: string): Promise<User | null>;
     verifyWeb3SignatureAndUpdate(user: User, credentials: {
         address: string;

package/lib/module/configureUsersModule.js

@@ -31,7 +31,7 @@ export const removeConfidentialServiceHashes = (rawUser) => {
     delete user?.services;
     return user;
 };
-export const buildFindSelector = ({ includeGuests, includeDeleted, queryString, emailVerified, lastLogin, tags, userIds, username, web3Verified, }) => {
+export const buildFindSelector = ({ includeGuests, includeDeleted, queryString, emailVerified, lastLogin, tags, userIds, username, usernames, emails, web3Verified, }) => {
     const selector = {};
     if (!includeDeleted)
         selector.deleted = null;
@@ -43,6 +43,16 @@ export const buildFindSelector = ({ includeGuests, includeDeleted, queryString,
     if (username) {
         selector.username = insensitiveTrimmedRegexOperator(username);
     }
+    if (usernames?.length) {
+        selector.username = {
+            $in: usernames.map((u) => insensitiveTrimmedRegexOperator(u)),
+        };
+    }
+    if (emails?.length) {
+        selector['emails.address'] = {
+            $in: emails.map((e) => insensitiveTrimmedRegexOperator(e)),
+        };
+    }
     if (emailVerified === true) {
         selector['emails.verified'] = true;
     }
@@ -189,7 +199,7 @@ export const configureUsersModule = async (moduleInput) => {
             }).toArray();
         },
         async userExists({ userId }) {
-            const userCount = await Users.countDocuments({ _id: userId, deleted: { $exists: false } }, { limit: 1 });
+            const userCount = await Users.countDocuments({ _id: userId, deleted: null }, { limit: 1 });
             return userCount === 1;
         },
         primaryEmail(user) {
@@ -311,7 +321,7 @@ export const configureUsersModule = async (moduleInput) => {
             const existingEntry = user.services?.web3?.find((service) => service.address.toLowerCase() === address.toLowerCase());
             if (existingEntry)
                 return user;
-            const nonce = Math.floor(Math.random() * 1000000).toString();
+            const nonce = crypto.randomUUID();
             const updatedUser = await Users.findOneAndUpdate(generateDbFilterById(userId), {
                 $push: {
                     'services.web3': {
@@ -369,8 +379,20 @@ export const configureUsersModule = async (moduleInput) => {
             }, { returnDocument: 'after' });
             return updatedUser;
         },
+        async createAccessToken(username) {
+            const plainToken = crypto.randomUUID();
+            const secret = await sha256(plainToken);
+            const updatedUser = await Users.findOneAndUpdate({ username: insensitiveTrimmedRegexOperator(username) }, {
+                $set: {
+                    'services.token': { secret },
+                },
+            }, { returnDocument: 'after' });
+            if (!updatedUser)
+                return null;
+            return { user: updatedUser, token: plainToken };
+        },
         async setAccessToken(username, plainSecret) {
-            const secret = await sha256(`${username}:${plainSecret}`);
+            const secret = await sha256(plainSecret);
             const updatedUser = await Users.findOneAndUpdate({ username: insensitiveTrimmedRegexOperator(username) }, {
                 $set: {
                     'services.token': { secret },
@@ -756,7 +778,7 @@ export const configureUsersModule = async (moduleInput) => {
         existingTags: async () => {
             const tags = (await Users.distinct('tags', {
                 tags: { $exists: true },
-                deleted: { $exists: false },
+                deleted: null,
             }));
             return tags.filter(Boolean).toSorted();
         },

package/lib/module/configureUsersWebAuthnModule.d.ts

@@ -1,11 +1,11 @@
-import type { ModuleInput } from '@unchainedshop/mongodb';
+import { type ModuleInput } from '@unchainedshop/mongodb';
 import type { RegistrationJSON, AuthenticationJSON, CredentialInfo, NamedAlgo, ExtendedAuthenticatorTransport } from '@passwordless-id/webauthn/dist/esm/types.js';
 export type { RegistrationJSON, AuthenticationJSON, CredentialInfo, NamedAlgo, ExtendedAuthenticatorTransport, };
 export declare function toArrayBuffer(buffer: Buffer): ArrayBuffer;
 export declare function buf2hex(buffer: ArrayBuffer): string;
 export interface WebAuthnCredentialCreationOptions {
     challenge: string;
-    requestId: number;
+    requestId: string;
     rp: {
         id: string;
         name: string;
@@ -29,7 +29,7 @@ export interface WebAuthnCredentialCreationOptions {
 }
 export interface WebAuthnCredentialRequestOptions {
     challenge: string;
-    requestId: number;
+    requestId: string;
     rpId: string;
     timeout: number;
     userVerification?: 'required' | 'preferred' | 'discouraged';
@@ -75,10 +75,11 @@ export declare const configureUsersWebAuthnModule: ({ db }: ModuleInput<Record<s
         counter?: number;
         transports?: ExtendedAuthenticatorTransport[];
     }[], username: string, credentials: AuthenticationJSON & {
-        requestId: number;
+        requestId: string;
     }) => Promise<{
         userHandle: string;
         counter: number;
     } | null>;
     deleteUserWebAuthnCredentials: (username: string) => Promise<number>;
 }>;
+export type UsersWebAuthnModule = Awaited<ReturnType<typeof configureUsersWebAuthnModule>>;

package/lib/module/configureUsersWebAuthnModule.js

@@ -1,3 +1,4 @@
+import { generateDbObjectId } from '@unchainedshop/mongodb';
 import { createLogger } from '@unchainedshop/logger';
 import pMemoize from 'p-memoize';
 import ExpiryMap from 'expiry-map';
@@ -5,7 +6,6 @@ import { server as webauthnServer } from '@passwordless-id/webauthn';
 import { WebAuthnCredentialsCreationRequestsCollection } from "../db/WebAuthnCredentialsCreationRequestsCollection.js";
 const logger = createLogger('unchained:core-users');
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
-const { ROOT_URL = 'http://localhost:4010', EMAIL_WEBSITE_NAME = 'Unchained' } = process.env;
 async function fetchMDSEntriesImpl() {
     const cache = new Map();
     try {
@@ -48,6 +48,7 @@ export function buf2hex(buffer) {
         .join('');
 }
 export const configureUsersWebAuthnModule = async ({ db }) => {
+    const { ROOT_URL = 'http://localhost:4010', EMAIL_WEBSITE_NAME = 'Unchained' } = process.env;
     const WebAuthnCredentialsCreationRequests = await WebAuthnCredentialsCreationRequestsCollection(db);
     const thisDomain = new URL(ROOT_URL).hostname;
     const thisOrigin = new URL(ROOT_URL).origin;
@@ -60,7 +61,7 @@ export const configureUsersWebAuthnModule = async ({ db }) => {
         createCredentialCreationOptions: async (origin, username, extensionOptions) => {
             const challenge = webauthnServer.randomChallenge();
             const { insertedId } = await WebAuthnCredentialsCreationRequests.insertOne({
-                _id: new Date().getTime(),
+                _id: generateDbObjectId(),
                 challenge,
                 origin,
                 factor: 'either',
@@ -92,7 +93,7 @@ export const configureUsersWebAuthnModule = async ({ db }) => {
         createCredentialRequestOptions: async (origin, username, extensionOptions) => {
             const challenge = webauthnServer.randomChallenge();
             const { insertedId } = await WebAuthnCredentialsCreationRequests.insertOne({
-                _id: new Date().getTime(),
+                _id: generateDbObjectId(),
                 challenge,
                 origin,
                 factor: 'either',

package/lib/module/pbkdf2.js

@@ -1,3 +1,4 @@
+import { timingSafeStringEqual } from '@unchainedshop/utils';
 const PBKDF2_ITERATIONS = 300000;
 const PBKDF2_KEY_LENGTH = 256;
 const PBKDF2_SALT_LENGTH = 16;
@@ -26,5 +27,5 @@ export async function getDerivedKey(salt, password, iterations = PBKDF2_ITERATIO
 }
 export async function compare(password, hash, salt) {
     const comparableHash = await getDerivedKey(salt, password);
-    return comparableHash === hash;
+    return timingSafeStringEqual(comparableHash, hash);
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@unchainedshop/core-users",
-  "version": "4.5.0",
+  "description": "User management module for the Unchained Engine with authentication support",
+  "version": "4.6.1",
   "main": "lib/users-index.js",
   "types": "lib/users-index.d.ts",
   "type": "module",
@@ -35,12 +36,12 @@
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
     "@passwordless-id/webauthn": "^2.3.1",
-    "@unchainedshop/events": "^4.5.0",
-    "@unchainedshop/file-upload": "^4.5.0",
-    "@unchainedshop/logger": "^4.5.0",
-    "@unchainedshop/mongodb": "^4.5.0",
-    "@unchainedshop/roles": "^4.5.0",
-    "@unchainedshop/utils": "^4.5.0",
+    "@unchainedshop/events": "^4.6.0",
+    "@unchainedshop/file-upload": "^4.6.0",
+    "@unchainedshop/logger": "^4.6.0",
+    "@unchainedshop/mongodb": "^4.6.0",
+    "@unchainedshop/roles": "^4.6.0",
+    "@unchainedshop/utils": "^4.6.0",
     "bcryptjs": "^3.0.2",
     "expiry-map": "^2.0.0",
     "p-memoize": "^8.0.0"