@portaidentity/server 1.7.0

package/dist/users/service.d.ts

@@ -0,0 +1,299 @@
+/**
+ * User service — business logic orchestrator.
+ *
+ * Composes the repository, cache, password utilities, and audit log
+ * to provide the complete user management API. All write operations
+ * follow the pattern:
+ *   1. Validate inputs
+ *   2. Perform DB operation (via repository)
+ *   3. Invalidate + re-cache (via cache)
+ *   4. Write audit log (fire-and-forget)
+ *
+ * Read operations check cache first (by ID), fall back to DB on miss.
+ * Email lookups always hit the DB (not cached — see cache design decision).
+ *
+ * Status lifecycle rules:
+ *   - deactivate: active → inactive
+ *   - reactivate: inactive → active
+ *   - suspend: active → suspended
+ *   - unsuspend: suspended → active
+ *   - lock: active → locked (with reason and timestamp)
+ *   - unlock: locked → active (clears reason and timestamp)
+ */
+import type { CursorPaginatedResult } from '../lib/cursor.js';
+import { invalidateUserCache } from './cache.js';
+import { ensureDummyPasswordHash, verifyPassword } from './password.js';
+import type { ListUsersCursorOptions } from './repository.js';
+import { getPasswordHash, recordEligiblePasswordFailure } from './repository.js';
+import type { CreateUserInput, PaginatedResult, UpdateUserInput, User, UserListOptions } from './types.js';
+/** Production boundaries used by fixed-shape password verification. */
+export interface LoginPasswordVerificationDependencies {
+    /** Load an eligible account hash without exposing it to the route. */
+    readonly loadAccountHash: typeof getPasswordHash;
+    /** Load the process-owned non-authoritative hash. */
+    readonly loadDummyHash: typeof ensureDummyPasswordHash;
+    /** Execute the password-hash verification algorithm. */
+    readonly verifyHash: typeof verifyPassword;
+}
+/** Production boundaries used by fixed-shape failed-login accounting. */
+export interface PasswordFailureDependencies {
+    /** Execute the conditional database update for an eligible account identifier. */
+    readonly recordEligibleFailure: typeof recordEligiblePasswordFailure;
+    /** Invalidate the selected account cache key after the database operation. */
+    readonly invalidateCache: typeof invalidateUserCache;
+}
+/**
+ * Create a new user in an organization.
+ *
+ * 1. Validates email uniqueness within the organization
+ * 2. Validates and hashes password if provided
+ * 3. Inserts user via repository
+ * 4. Caches the new user
+ * 5. Writes audit log entry
+ *
+ * @param input - User creation data (password is plaintext, will be hashed)
+ * @param actorId - UUID of the user performing the action (for audit)
+ * @returns Created user
+ * @throws UserValidationError if email exists or password invalid
+ */
+export declare function createUser(input: CreateUserInput, actorId?: string): Promise<User>;
+/**
+ * Find a user by ID.
+ * Checks Redis cache first, falls back to database on miss.
+ *
+ * @param id - User UUID
+ * @returns User or null if not found
+ */
+export declare function getUserById(id: string): Promise<User | null>;
+/**
+ * Find a user by email within an organization.
+ * Always hits the database (email lookups are not cached).
+ *
+ * @param orgId - Organization UUID
+ * @param email - User email address (case-insensitive)
+ * @returns User or null if not found
+ */
+export declare function getUserByEmail(orgId: string, email: string): Promise<User | null>;
+/**
+ * Update a user's profile fields.
+ *
+ * Builds an update data object from the input, checking for email
+ * uniqueness if the email is being changed. Address fields are
+ * flattened from the nested AddressInput to individual columns.
+ *
+ * @param id - User UUID
+ * @param input - Fields to update
+ * @param actorId - UUID of the user performing the action
+ * @returns Updated user
+ * @throws UserNotFoundError if user not found
+ * @throws UserValidationError if new email already exists in org
+ */
+export declare function updateUser(id: string, input: UpdateUserInput, actorId?: string): Promise<User>;
+/**
+ * List users within an organization with pagination and filtering.
+ * Delegates directly to the repository.
+ *
+ * @param options - Pagination, filter, and sort options (orgId required)
+ * @returns Paginated result
+ */
+export declare function listUsersByOrganization(options: UserListOptions): Promise<PaginatedResult<User>>;
+/**
+ * List users with cursor-based keyset pagination.
+ * Supports all existing filters (org scope, status, search, sort).
+ *
+ * @param options - Cursor, limit, filter, and sort options (orgId required)
+ * @returns Cursor-paginated result with nextCursor/hasMore
+ */
+export declare function listUsersCursor(options: ListUsersCursorOptions): Promise<CursorPaginatedResult<User>>;
+/**
+ * Deactivate a user (active → inactive).
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently active
+ */
+export declare function deactivateUser(id: string, actorId?: string): Promise<void>;
+/**
+ * Reactivate a user (inactive → active).
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently inactive
+ */
+export declare function reactivateUser(id: string, actorId?: string): Promise<void>;
+/**
+ * Suspend a user (active → suspended).
+ *
+ * @param id - User UUID
+ * @param reason - Optional reason for suspension
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently active
+ */
+export declare function suspendUser(id: string, reason?: string, actorId?: string): Promise<void>;
+/**
+ * Unsuspend a user (suspended → active).
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently suspended
+ */
+export declare function unsuspendUser(id: string, actorId?: string): Promise<void>;
+/**
+ * Lock a user (active → locked).
+ *
+ * Sets the locked_at timestamp and locked_reason. Locked users
+ * cannot authenticate (getPasswordHash only returns for active users).
+ *
+ * @param id - User UUID
+ * @param reason - Reason for locking the account
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently active
+ */
+export declare function lockUser(id: string, reason: string, actorId?: string): Promise<void>;
+/**
+ * Unlock a user (locked → active).
+ *
+ * Clears the locked_at timestamp and locked_reason.
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws UserNotFoundError if not found
+ * @throws UserValidationError if not currently locked
+ */
+export declare function unlockUser(id: string, actorId?: string): Promise<void>;
+/**
+ * Set a user's password.
+ *
+ * Validates the password, hashes it with Argon2id, and stores the hash.
+ * Also sets password_changed_at to the current timestamp.
+ *
+ * @param id - User UUID
+ * @param password - New plaintext password
+ * @param actorId - UUID of the user performing the action
+ * @throws UserValidationError if password fails validation
+ */
+export declare function setUserPassword(id: string, password: string, actorId?: string): Promise<void>;
+/**
+ * Verify a user's password.
+ *
+ * Returns false if the user has no password (passwordless), is not
+ * active, or if the password doesn't match. No audit log is written —
+ * login tracking is handled separately by recordLogin().
+ *
+ * @param id - User UUID
+ * @param password - Plaintext password to verify
+ * @returns true if the password matches
+ */
+export declare function verifyUserPassword(id: string, password: string): Promise<boolean>;
+/**
+ * Verify exactly one account or dummy Argon2id hash for an admitted login attempt.
+ *
+ * @param id - Eligible active account UUID, or null for every non-eligible identity state.
+ * @param password - Submitted plaintext password.
+ * @param dependencies - Production hash boundaries, replaceable by pass-through observers.
+ * @returns True only when an eligible account hash matched.
+ */
+export declare function verifyLoginPassword(id: string | null, password: string, dependencies?: LoginPasswordVerificationDependencies): Promise<boolean>;
+/**
+ * Resolve the password-login account through a fixed sequence of database and cache operations.
+ *
+ * The initial lookup identifies a possible elapsed automatic lock. The conditional update and
+ * cache invalidation execute for every admitted identity, using a non-account UUID when absent.
+ * A second lookup then observes the post-cooldown state without an identity-dependent branch.
+ *
+ * @param organizationId - Resolved tenant authority.
+ * @param email - Normalized login address.
+ * @returns Current account state, or null when no account exists.
+ */
+export declare function prepareUserForPasswordLogin(organizationId: string, email: string): Promise<User | null>;
+/**
+ * Clear a user's password (convert to passwordless-only).
+ *
+ * Sets password_hash to NULL and clears password_changed_at.
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ */
+export declare function clearUserPassword(id: string, actorId?: string): Promise<void>;
+/**
+ * Mark a user's email as verified.
+ *
+ * @param id - User UUID
+ * @param actorId - UUID of the user performing the action
+ */
+export declare function markEmailVerified(id: string, actorId?: string): Promise<void>;
+/**
+ * Mark a user's email as unverified.
+ * Typically called when the email address changes.
+ *
+ * @param id - User UUID
+ */
+export declare function markEmailUnverified(id: string): Promise<void>;
+/**
+ * Record a successful login for a user.
+ *
+ * Increments login_count and sets last_login_at. Also resets
+ * failed_login_count and last_failed_login_at. Invalidates cache
+ * because the login stats have changed.
+ *
+ * @param id - User UUID
+ */
+export declare function recordLogin(id: string): Promise<void>;
+/**
+ * Record a failed login attempt and auto-lock if threshold exceeded.
+ *
+ * Uses an atomic SQL UPDATE to increment the counter and conditionally
+ * flip status to 'locked' with reason 'auto_lockout' in a single query.
+ * Returns whether the account was just locked so the caller can show
+ * an appropriate message and write an audit event.
+ *
+ * The threshold comes from system_config `max_failed_logins` (default 5).
+ *
+ * @param user - The user whose login failed
+ * @returns Object with `locked: true` if the account was just auto-locked
+ */
+export declare function recordFailedLogin(user: User): Promise<{
+    locked: boolean;
+    failedCount: number;
+}>;
+/**
+ * Execute one fixed-shape failure-accounting operation for an admitted password rejection.
+ *
+ * @param user - Eligible active account, or null for every other identity state.
+ * @param dependencies - Production persistence/cache boundaries, replaceable by pass-through observers.
+ * @returns Neutral or real account-lock result without disclosing identity publicly.
+ */
+export declare function recordPasswordFailure(user: User | null, dependencies?: PasswordFailureDependencies): Promise<{
+    locked: boolean;
+    failedCount: number;
+}>;
+/**
+ * Check whether an auto-locked account should be unlocked (cooldown elapsed).
+ *
+ * Only applies to users with `status = 'locked'` and
+ * `lockedReason = 'auto_lockout'`. Manual locks are never auto-unlocked.
+ *
+ * The cooldown duration comes from system_config `lockout_duration_seconds`
+ * (default 900 = 15 minutes).
+ *
+ * @param user - User to check
+ * @returns `true` if the account was auto-unlocked
+ */
+export declare function checkAutoUnlock(user: User): Promise<boolean>;
+/**
+ * Find a user for OIDC token/userinfo operations.
+ *
+ * Returns the user only if their status is 'active'. Non-active users
+ * should not be able to obtain tokens or access the userinfo endpoint.
+ * Used by the upgraded account-finder.ts.
+ *
+ * @param sub - Subject identifier (user UUID)
+ * @returns Active user or null
+ */
+export declare function findUserForOidc(sub: string): Promise<User | null>;
+//# sourceMappingURL=service.d.ts.map

package/dist/users/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/users/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAgC,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EACL,uBAAuB,EAGvB,cAAc,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAEL,eAAe,EASf,6BAA6B,EAG9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,eAAe,EACf,IAAI,EACJ,eAAe,EAChB,MAAM,YAAY,CAAC;AAKpB,uEAAuE;AACvE,MAAM,WAAW,qCAAqC;IACpD,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,OAAO,eAAe,CAAC;IACjD,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,OAAO,uBAAuB,CAAC;IACvD,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC;CAC5C;AAED,yEAAyE;AACzE,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,QAAQ,CAAC,qBAAqB,EAAE,OAAO,6BAA6B,CAAC;IACrE,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,OAAO,mBAAmB,CAAC;CACtD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAMD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAEvF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmEf;AAMD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAEhC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAEtC;AAgBD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhF;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhF;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9F;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB5E;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIvF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,qCAAqC,GACnD,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAqBtB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAanF;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAMD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,GACT,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBnD;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,YAAY,CAAC,EAAE,2BAA2B,GACzC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CA2BlE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAQvE"}