@aooth/user 0.1.1

package/dist/index.mjs

@@ -0,0 +1,799 @@
+import { a as maskEmail, c as setAtPath, i as incrementAtPath, l as UserAuthError, n as deepMerge, o as maskMfaValue, r as generateSecureRandom, s as maskPhone, t as UserStore } from "./user-store-B_l9vqlQ.mjs";
+import { createHash, createHmac, randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { FtringsPool } from "@prostojs/ftring";
+//#region src/mfa/backup-codes.ts
+/**
+* Custom alphabet for backup codes — uppercase letters and digits with the
+* easily-confused characters (I, O, L, 0, 1) removed (31 chars).
+*/
+const BACKUP_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+const RAW_LENGTH = 10;
+const GROUP_SIZE = 4;
+/**
+* Generate `count` cryptographically-random backup codes (default 10).
+*
+* Format: 10 characters from the 31-char safe alphabet (uppercase letters +
+* digits, omitting I/O/L/0/1), grouped as `XXXX-XXXX-XX`.
+*
+* Returns plaintext codes for the caller to deliver to the user — these
+* should be hashed via {@link hashMfaCode} before persistence and never
+* shown to the user again.
+*/
+function generateBackupCodePlaintext(count = 10) {
+	const codes = [];
+	for (let i = 0; i < count; i++) codes.push(formatCode(generateSecureRandom(RAW_LENGTH, BACKUP_CODE_ALPHABET)));
+	return codes;
+}
+function formatCode(raw) {
+	const parts = [];
+	for (let i = 0; i < raw.length; i += GROUP_SIZE) parts.push(raw.slice(i, i + GROUP_SIZE));
+	return parts.join("-");
+}
+//#endregion
+//#region src/mfa/codes.ts
+/**
+* SHA-256 hash of an MFA code (e.g. one-time email/SMS code or backup code).
+*
+* Hex-encoded for stable, comparable output regardless of input case/format.
+* Use {@link verifyMfaCode} to compare a submitted plaintext code against the
+* stored hash in constant time.
+*/
+function hashMfaCode(code) {
+	return createHash("sha256").update(code).digest("hex");
+}
+/**
+* Constant-time comparison of a submitted plaintext code against an
+* expected SHA-256 hex hash (as produced by {@link hashMfaCode}).
+*
+* Returns false for malformed/empty expected hashes (timingSafeEqual
+* requires equal-length, non-empty buffers).
+*/
+function verifyMfaCode(submitted, expectedHash) {
+	if (!expectedHash) return false;
+	const a = Buffer.from(hashMfaCode(submitted), "hex");
+	const b = Buffer.from(expectedHash, "hex");
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+//#endregion
+//#region src/base-x/base32.ts
+/**
+* Partially copied from "thirty-two" library, all credits to Chris Umbel.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the "Software"), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included in
+* all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+* THE SOFTWARE.
+*/
+const charTable = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function quintetCount(buff) {
+	const quintets = Math.floor(buff.length / 5);
+	return buff.length % 5 === 0 ? quintets : quintets + 1;
+}
+const encode = function(plain) {
+	if (!Buffer.isBuffer(plain) && typeof plain !== "string") throw new TypeError("base32.encode only takes Buffer or string as parameter");
+	if (!Buffer.isBuffer(plain)) plain = Buffer.from(plain);
+	let i = 0;
+	let j = 0;
+	let shiftIndex = 0;
+	let digit = 0;
+	const encoded = Buffer.alloc(quintetCount(plain) * 8);
+	while (i < plain.length) {
+		const current = plain[i];
+		if (shiftIndex > 3) {
+			digit = current & 255 >> shiftIndex;
+			shiftIndex = (shiftIndex + 5) % 8;
+			digit = digit << shiftIndex | (i + 1 < plain.length ? plain[i + 1] : 0) >> 8 - shiftIndex;
+			i++;
+		} else {
+			digit = current >> 8 - (shiftIndex + 5) & 31;
+			shiftIndex = (shiftIndex + 5) % 8;
+			if (shiftIndex === 0) i++;
+		}
+		encoded[j] = charTable.charCodeAt(digit);
+		j++;
+	}
+	for (i = j; i < encoded.length; i++) encoded[i] = 61;
+	return encoded;
+};
+function decode(input) {
+	const cleaned = input.toUpperCase().replace(/=+$/, "");
+	let bits = 0;
+	let value = 0;
+	let index = 0;
+	const output = Buffer.alloc(Math.floor(cleaned.length * 5 / 8));
+	for (const ch of cleaned) {
+		const val = charTable.indexOf(ch);
+		if (val === -1) continue;
+		value = value << 5 | val;
+		bits += 5;
+		if (bits >= 8) {
+			output[index++] = value >>> bits - 8 & 255;
+			bits -= 8;
+		}
+	}
+	return output.subarray(0, index);
+}
+//#endregion
+//#region src/mfa/totp.ts
+function generateTotpSecret(bytes = 20) {
+	return encode(randomBytes(bytes)).toString().replace(/=+$/, "").toUpperCase();
+}
+function generateTotpUri(secret, issuer, account, config) {
+	const period = config?.period ?? 30;
+	const digits = config?.digits ?? 6;
+	const encodedIssuer = encodeURIComponent(issuer);
+	return `otpauth://totp/${encodedIssuer}:${encodeURIComponent(account)}?secret=${secret}&issuer=${encodedIssuer}&algorithm=SHA1&digits=${digits}&period=${period}`;
+}
+function generateTotpCode(secret, config) {
+	const period = config?.period ?? 30;
+	const digits = config?.digits ?? 6;
+	const now = (config?.clock ?? Date.now)();
+	const counter = Math.floor(now / 1e3 / period);
+	return hotpCode(decode(secret), counter, digits);
+}
+function verifyTotpCode(secret, code, config) {
+	const period = config?.period ?? 30;
+	const digits = config?.digits ?? 6;
+	const window = config?.window ?? 1;
+	const now = (config?.clock ?? Date.now)();
+	const counter = Math.floor(now / 1e3 / period);
+	const key = decode(secret);
+	if (typeof code !== "string" || code.length !== digits) return false;
+	const submitted = Buffer.from(code, "utf8");
+	let matched = false;
+	for (let i = -window; i <= window; i++) {
+		const expected = Buffer.from(hotpCode(key, counter + i, digits), "utf8");
+		if (expected.length === submitted.length && timingSafeEqual(expected, submitted)) matched = true;
+	}
+	return matched;
+}
+function generateMfaCode(length = 6) {
+	return generateSecureRandom(length, "0123456789");
+}
+function hotpCode(key, counter, digits) {
+	const counterBuf = Buffer.alloc(8);
+	counterBuf.writeUInt32BE(Math.floor(counter / 4294967296), 0);
+	counterBuf.writeUInt32BE(counter >>> 0, 4);
+	const hmac = createHmac("sha1", key);
+	hmac.update(counterBuf);
+	const hmacResult = hmac.digest();
+	const offset = hmacResult[hmacResult.length - 1] & 15;
+	return (((hmacResult[offset] & 127) << 24 | (hmacResult[offset + 1] & 255) << 16 | (hmacResult[offset + 2] & 255) << 8 | hmacResult[offset + 3] & 255) % 10 ** digits).toString().padStart(digits, "0");
+}
+//#endregion
+//#region src/password/hasher.ts
+const DEFAULTS = {
+	N: 16384,
+	r: 8,
+	p: 1,
+	keyLength: 64,
+	saltLength: 32
+};
+const PREFIX = "$scrypt$";
+function scryptAsync(password, salt, keyLength, options) {
+	return new Promise((resolve, reject) => {
+		scrypt(password, salt, keyLength, options, (err, derived) => {
+			if (err) reject(err);
+			else resolve(derived);
+		});
+	});
+}
+function parseHash(encoded) {
+	if (!encoded.startsWith(PREFIX)) return null;
+	const parts = encoded.slice(8).split("$");
+	if (parts.length !== 3) return null;
+	const params = {};
+	for (const kv of parts[0].split(",")) {
+		const [k, v] = kv.split("=");
+		params[k] = Number(v);
+	}
+	if (!params.N || !params.r || !params.p || !params.l) return null;
+	return {
+		N: params.N,
+		r: params.r,
+		p: params.p,
+		keyLength: params.l,
+		salt: Buffer.from(parts[1], "base64url"),
+		hash: Buffer.from(parts[2], "base64url")
+	};
+}
+var PasswordHasher = class {
+	pepper;
+	N;
+	r;
+	p;
+	keyLength;
+	constructor(config) {
+		this.pepper = config?.pepper ?? "";
+		this.N = config?.scryptN ?? DEFAULTS.N;
+		this.r = config?.scryptR ?? DEFAULTS.r;
+		this.p = config?.scryptP ?? DEFAULTS.p;
+		this.keyLength = config?.keyLength ?? DEFAULTS.keyLength;
+	}
+	async hash(password) {
+		const salt = randomBytes(DEFAULTS.saltLength);
+		const derived = await scryptAsync(this.pepper + password, salt, this.keyLength, {
+			N: this.N,
+			r: this.r,
+			p: this.p
+		});
+		return `${PREFIX}${`N=${this.N},r=${this.r},p=${this.p},l=${this.keyLength}`}$${salt.toString("base64url")}$${derived.toString("base64url")}`;
+	}
+	async verify(password, encoded) {
+		const parsed = parseHash(encoded);
+		if (!parsed) return false;
+		const derived = await scryptAsync(this.pepper + password, parsed.salt, parsed.keyLength, {
+			N: parsed.N,
+			r: parsed.r,
+			p: parsed.p
+		});
+		if (derived.length !== parsed.hash.length) return false;
+		return timingSafeEqual(derived, parsed.hash);
+	}
+	generatePassword(length = 16) {
+		const minLen = Math.max(length, 8);
+		const lower = "abcdefghijklmnopqrstuvwxyz";
+		const upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+		const digits = "0123456789";
+		const special = "!@#$%^&*()-_=+";
+		const all = lower + upper + digits + special;
+		const bytes = randomBytes(minLen);
+		const result = Array.from({ length: minLen });
+		result[0] = lower[bytes[0] % 26];
+		result[1] = upper[bytes[1] % 26];
+		result[2] = digits[bytes[2] % 10];
+		result[3] = special[bytes[3] % 14];
+		for (let i = 4; i < minLen; i++) result[i] = all[bytes[i] % all.length];
+		const shuffleBytes = randomBytes(minLen);
+		for (let i = minLen - 1; i > 0; i--) {
+			const j = shuffleBytes[i] % (i + 1);
+			[result[i], result[j]] = [result[j], result[i]];
+		}
+		return result.join("");
+	}
+};
+//#endregion
+//#region src/password/policy.ts
+const fnPool = new FtringsPool();
+function normalizePolicies(policies) {
+	return (policies || []).map((p) => p instanceof PasswordPolicy ? p : new PasswordPolicy(p));
+}
+var PasswordPolicy = class {
+	rule;
+	description;
+	errorMessage;
+	constructor(config) {
+		this.rule = config.rule;
+		this.description = config.description || "";
+		this.errorMessage = config.errorMessage || "";
+	}
+	_evalFn;
+	evaluate(password, context) {
+		if (!this._evalFn) if (typeof this.rule === "function") this._evalFn = this.rule;
+		else if (typeof this.rule === "string" && this.rule) {
+			const fn = fnPool.getFn(this.rule);
+			this._evalFn = (v, ctx) => fn({
+				v,
+				context: ctx
+			});
+		} else this._evalFn = () => true;
+		return this._evalFn(password, context);
+	}
+	get transferable() {
+		return typeof this.rule === "string";
+	}
+};
+//#endregion
+//#region src/user-service.ts
+function resolveConfig(config) {
+	return {
+		password: {
+			pepper: config?.password?.pepper ?? "",
+			historyLength: config?.password?.historyLength ?? 0,
+			scryptN: config?.password?.scryptN ?? 16384,
+			scryptR: config?.password?.scryptR ?? 8,
+			scryptP: config?.password?.scryptP ?? 1,
+			keyLength: config?.password?.keyLength ?? 64,
+			policies: normalizePolicies(config?.password?.policies)
+		},
+		lockout: {
+			threshold: config?.lockout?.threshold ?? 0,
+			duration: config?.lockout?.duration ?? 0
+		},
+		clock: config?.clock ?? Date.now,
+		...config?.deviceTrust && { deviceTrust: config.deviceTrust }
+	};
+}
+const DEVICE_TRUST_TOKEN_BYTES = 32;
+const DEVICE_TRUST_SEPARATOR = ".";
+function signDeviceTrust(secret, payload) {
+	return createHmac("sha256", secret).update(payload).digest("hex");
+}
+function deviceTrustSafeEqual(a, b) {
+	const ab = Buffer.from(a);
+	const bb = Buffer.from(b);
+	if (ab.length !== bb.length) return false;
+	return timingSafeEqual(ab, bb);
+}
+var UserService = class {
+	config;
+	hasher;
+	constructor(store, config) {
+		this.store = store;
+		this.config = resolveConfig(config);
+		this.hasher = new PasswordHasher(this.config.password);
+	}
+	/**
+	* @param extras Optional partial user fields merged AFTER the base
+	*   `UserCredentials` shape, so callers can populate consumer-specific
+	*   required fields (e.g. `tenantId`) without subclassing the store.
+	*   Because the merge is shallow and extras win, overlapping top-level
+	*   keys (`id`, `account`, `mfa`, ...) replace the defaults entirely —
+	*   pass nested objects with all required sub-fields if you intend to
+	*   override them.
+	*/
+	async createUser(username, password, extras) {
+		const pw = password ?? this.hasher.generatePassword();
+		const userData = {
+			username,
+			password: {
+				hash: await this.hasher.hash(pw),
+				history: [],
+				lastChanged: this.config.clock(),
+				isInitial: !password
+			},
+			account: {
+				active: false,
+				locked: false,
+				lockReason: "",
+				lockEnds: 0,
+				failedLoginAttempts: 0,
+				lastLogin: 0
+			},
+			mfa: {
+				methods: [],
+				defaultMethod: "",
+				autoSend: false
+			},
+			...extras
+		};
+		await this.store.create(userData);
+		return userData;
+	}
+	async getUser(username) {
+		const user = await this.store.findByUsername(username);
+		if (!user) throw new UserAuthError("NOT_FOUND");
+		return user;
+	}
+	async login(username, password) {
+		const user = await this.store.findByUsername(username);
+		if (!user) throw new UserAuthError("NOT_FOUND");
+		if (!user.account.active) throw new UserAuthError("INACTIVE");
+		await this.ensureNotLockedOrThrow(username, user.account);
+		if (await this.hasher.verify(password, user.password.hash)) {
+			const now = this.config.clock();
+			await this.store.update(username, { set: { account: {
+				lastLogin: now,
+				failedLoginAttempts: 0
+			} } });
+			user.account.lastLogin = now;
+			user.account.failedLoginAttempts = 0;
+			return {
+				user,
+				mfaRequired: this.hasConfirmedMfaMethods(user.mfa)
+			};
+		}
+		return this.incrementAndMaybeLock(username, user.account, "INVALID_CREDENTIALS");
+	}
+	async verifyPassword(username, password) {
+		const user = await this.store.findByUsername(username);
+		if (!user) throw new UserAuthError("NOT_FOUND");
+		return this.hasher.verify(password, user.password.hash);
+	}
+	async changePassword(username, currentPassword, newPassword, repeatPassword) {
+		if (repeatPassword !== void 0 && newPassword !== repeatPassword) throw new UserAuthError("PASSWORDS_MISMATCH");
+		const user = await this.getUser(username);
+		if (!await this.hasher.verify(currentPassword, user.password.hash)) throw new UserAuthError("INVALID_CREDENTIALS");
+		await this.applyPasswordChange(username, user, newPassword);
+	}
+	async setPassword(username, newPassword) {
+		const user = await this.getUser(username);
+		await this.applyPasswordChange(username, user, newPassword);
+	}
+	/**
+	* Hard-delete the user row. Returns nothing on success. Throws
+	* `UserAuthError("NOT_FOUND")` when no row matches `username`. Used by the
+	* invite workflow's `auth.cancelInvite` to revoke a pending invitation.
+	*/
+	async deleteUser(username) {
+		if (!await this.store.delete(username)) throw new UserAuthError("NOT_FOUND");
+	}
+	/**
+	* Deep-merge `patch` into the user record (top-level fields are shallow-
+	* merged; `account` / `mfa` / `password` are merged per their
+	* `@db.patch.strategy 'merge'` declaration). Returns the patched record.
+	* Used by the invite workflow's `applyProfile` default fallback.
+	*/
+	async update(username, patch) {
+		if (!await this.store.update(username, { set: patch })) throw new UserAuthError("NOT_FOUND");
+		return this.getUser(username);
+	}
+	async activateAccount(username) {
+		if (!await this.store.update(username, { set: { account: { active: true } } })) throw new UserAuthError("NOT_FOUND");
+	}
+	async deactivateAccount(username) {
+		if (!await this.store.update(username, { set: { account: { active: false } } })) throw new UserAuthError("NOT_FOUND");
+	}
+	async lockAccount(username, reason, duration) {
+		const lockEnds = duration ? this.config.clock() + duration : 0;
+		if (!await this.store.update(username, { set: { account: {
+			locked: true,
+			lockReason: reason,
+			lockEnds
+		} } })) throw new UserAuthError("NOT_FOUND");
+	}
+	async unlockAccount(username) {
+		if (!await this.store.update(username, { set: { account: {
+			locked: false,
+			lockReason: "",
+			lockEnds: 0,
+			failedLoginAttempts: 0
+		} } })) throw new UserAuthError("NOT_FOUND");
+	}
+	getLockStatus(account) {
+		if (!account.locked) return {
+			locked: false,
+			expired: false,
+			reason: "",
+			lockEnds: 0
+		};
+		return {
+			locked: true,
+			expired: account.lockEnds > 0 && account.lockEnds < this.config.clock(),
+			reason: account.lockReason,
+			lockEnds: account.lockEnds
+		};
+	}
+	async checkPolicies(password, passwordData) {
+		const result = {
+			passed: true,
+			policies: [],
+			errors: []
+		};
+		for (const policy of this.config.password.policies) {
+			const passed = await policy.evaluate(password, {
+				passwordData,
+				passwordConfig: this.config.password
+			});
+			result.passed = result.passed && passed;
+			result.policies.push({
+				description: policy.description,
+				passed
+			});
+			if (!passed) result.errors.push(policy.errorMessage);
+		}
+		return result;
+	}
+	getTransferablePolicies() {
+		return this.config.password.policies.filter((p) => p.transferable).map((p) => ({
+			rule: p.rule,
+			description: p.description,
+			errorMessage: p.errorMessage
+		}));
+	}
+	async addMfaMethod(username, method) {
+		const methods = [...(await this.getUser(username)).mfa.methods.filter((m) => m.name !== method.name), method];
+		await this.store.update(username, { set: { mfa: { methods } } });
+	}
+	async confirmMfaMethod(username, name) {
+		const user = await this.getUser(username);
+		let found = false;
+		const methods = user.mfa.methods.map((m) => {
+			if (m.name === name) {
+				found = true;
+				return {
+					...m,
+					confirmed: true
+				};
+			}
+			return m;
+		});
+		if (!found) throw new UserAuthError("MFA_NOT_CONFIGURED");
+		await this.store.update(username, { set: { mfa: { methods } } });
+	}
+	async removeMfaMethod(username, name) {
+		const user = await this.getUser(username);
+		const update = { mfa: { methods: user.mfa.methods.filter((m) => m.name !== name) } };
+		if (user.mfa.defaultMethod === name) update.mfa.defaultMethod = "";
+		await this.store.update(username, { set: update });
+	}
+	async setDefaultMfaMethod(username, name) {
+		const user = await this.getUser(username);
+		if (name && !user.mfa.methods.some((m) => m.name === name)) throw new UserAuthError("MFA_NOT_CONFIGURED");
+		await this.store.update(username, { set: { mfa: {
+			defaultMethod: name,
+			autoSend: false
+		} } });
+	}
+	async setMfaAutoSend(username, value) {
+		if (!await this.store.update(username, { set: { mfa: { autoSend: value } } })) throw new UserAuthError("NOT_FOUND");
+	}
+	getAvailableMfaMethods(mfa) {
+		return mfa.methods.filter((m) => m.confirmed).map((m) => ({
+			name: m.name,
+			isDefault: mfa.defaultMethod === m.name,
+			masked: maskMfaValue(m)
+		}));
+	}
+	/**
+	* Generate `count` plaintext backup codes (default 10), persist their
+	* hashes (replacing any existing batch), and return the plaintext codes
+	* once for the caller to deliver to the user. Plaintext is never
+	* recoverable after this call returns.
+	*
+	* Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
+	*/
+	async generateBackupCodes(username, count = 10) {
+		const codes = generateBackupCodePlaintext(count);
+		const hashes = codes.map(hashMfaCode);
+		if (!await this.store.update(username, { set: { backupCodes: hashes } })) throw new UserAuthError("NOT_FOUND");
+		return codes;
+	}
+	/**
+	* Consume a backup code: returns `true` and removes the matching hash
+	* from storage if `code` matches a stored backup code; returns `false`
+	* if no match (without modifying storage).
+	*
+	* Read-then-write is not atomic at this layer: two concurrent consumes
+	* of the same code may both succeed, with the last write winning. The
+	* underlying store API does not expose an atomic match-and-remove, so
+	* this is acceptable at the intended scale (backup codes are a fallback
+	* path, not a hot one). Wrap in your store's transaction primitive if a
+	* stricter guarantee is required.
+	*
+	* Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
+	*/
+	async consumeBackupCode(username, code) {
+		const hashes = (await this.getUser(username)).backupCodes ?? [];
+		const idx = hashes.findIndex((h) => verifyMfaCode(code, h));
+		if (idx < 0) return false;
+		const remaining = hashes.filter((_, i) => i !== idx);
+		await this.store.update(username, { set: { backupCodes: remaining } });
+		return true;
+	}
+	/**
+	* Verify a TOTP code against the user's confirmed `totp` MFA method.
+	* Failures bump the same `failedLoginAttempts` counter as `login` so an
+	* attacker who knows the password but not the TOTP gets `lockout.threshold`
+	* total tries across BOTH factors, not `2 * threshold`.
+	*/
+	async verifyMfa(username, code, config) {
+		const user = await this.getUser(username);
+		if (!user.account.active) throw new UserAuthError("INACTIVE");
+		await this.ensureNotLockedOrThrow(username, user.account);
+		const totp = user.mfa.methods.find((m) => m.name === "totp" && m.confirmed);
+		if (!totp) throw new UserAuthError("MFA_NOT_CONFIGURED");
+		if (verifyTotpCode(totp.value, code, config)) {
+			if (user.account.failedLoginAttempts > 0) await this.store.update(username, { set: { account: { failedLoginAttempts: 0 } } });
+			return;
+		}
+		await this.incrementAndMaybeLock(username, user.account, "MFA_INVALID");
+	}
+	getPasswordHasher() {
+		return this.hasher;
+	}
+	getConfig() {
+		return this.config;
+	}
+	/**
+	* Mint a freshly-signed trust record (does NOT persist — pair with
+	* `addTrustedDevice`). Throws when `deviceTrust.secret` is unset.
+	*/
+	issueTrustedDevice(userId, opts) {
+		const secret = this.requireDeviceTrustSecret();
+		const raw = randomBytes(DEVICE_TRUST_TOKEN_BYTES).toString("hex");
+		const sig = signDeviceTrust(secret, `${userId}|${raw}|${opts.ip ?? ""}`);
+		const now = this.config.clock();
+		return {
+			token: `${raw}${DEVICE_TRUST_SEPARATOR}${sig}`,
+			...opts.ip !== void 0 && { ip: opts.ip },
+			issuedAt: now,
+			expiresAt: now + opts.ttlMs,
+			...opts.name !== void 0 && { name: opts.name }
+		};
+	}
+	/**
+	* Append a trust record to the user's `trustedDevices` list. Read-modify-
+	* write — the array shape is preserved end-to-end so DB adapters with a
+	* merge strategy replace the whole array.
+	*/
+	async addTrustedDevice(username, record) {
+		const next = [...(await this.getUser(username)).trustedDevices ?? [], record];
+		await this.store.update(username, { set: { trustedDevices: next } });
+	}
+	/**
+	* Returns true when the supplied token (a) signs against the user+ip with
+	* the configured secret, AND (b) matches a persisted record that is still
+	* within its expiry window and whose bound IP (if any) matches.
+	*/
+	async verifyTrustedDevice(username, token, ip) {
+		const secret = this.requireDeviceTrustSecret();
+		const sepIdx = token.lastIndexOf(DEVICE_TRUST_SEPARATOR);
+		if (sepIdx <= 0) return false;
+		const raw = token.slice(0, sepIdx);
+		if (!deviceTrustSafeEqual(token.slice(sepIdx + 1), signDeviceTrust(secret, `${username}|${raw}|${ip ?? ""}`))) return false;
+		const user = await this.store.findByUsername(username);
+		if (!user) return false;
+		const list = user.trustedDevices ?? [];
+		const now = this.config.clock();
+		const found = list.find((r) => r.token === token && r.expiresAt > now);
+		if (!found) return false;
+		if (found.ip !== void 0 && found.ip !== ip) return false;
+		return true;
+	}
+	/**
+	* Remove a specific trust record from the user. No-op when the record is
+	* absent — mirrors the legacy `DeviceTrustStore.revoke` semantics.
+	*/
+	async revokeTrustedDevice(username, token) {
+		const user = await this.store.findByUsername(username);
+		if (!user) return;
+		const list = user.trustedDevices ?? [];
+		const next = list.filter((r) => r.token !== token);
+		if (next.length === list.length) return;
+		await this.store.update(username, { set: { trustedDevices: next } });
+	}
+	async listTrustedDevices(username) {
+		return (await this.getUser(username)).trustedDevices ?? [];
+	}
+	requireDeviceTrustSecret() {
+		const secret = this.config.deviceTrust?.secret;
+		if (!secret) throw new Error("UserService: deviceTrust.secret is required to use trusted-device APIs");
+		return secret;
+	}
+	async applyPasswordChange(username, user, newPassword) {
+		const policyResult = await this.checkPolicies(newPassword, user.password);
+		if (!policyResult.passed) throw new UserAuthError("POLICY_VIOLATION", policyResult.errors.join("; "), { policies: policyResult.policies });
+		const hashesToCheck = [user.password.hash, ...user.password.history].filter(Boolean);
+		if (hashesToCheck.length > 0) {
+			if ((await Promise.all(hashesToCheck.map((h) => this.hasher.verify(newPassword, h)))).some(Boolean)) throw new UserAuthError("PASSWORD_IN_HISTORY");
+		}
+		const newHash = await this.hasher.hash(newPassword);
+		const limit = this.config.password.historyLength;
+		const newHistory = limit > 0 ? [user.password.hash, ...user.password.history].filter(Boolean).slice(0, limit) : [];
+		await this.store.update(username, { set: { password: {
+			hash: newHash,
+			history: newHistory,
+			lastChanged: this.config.clock(),
+			isInitial: false
+		} } });
+	}
+	hasConfirmedMfaMethods(mfa) {
+		return mfa.methods.some((m) => m.confirmed);
+	}
+	/**
+	* If `account.locked`: auto-unlock when the lock has expired (mutating
+	* `account` in place), or throw `LOCKED` otherwise.
+	*/
+	async ensureNotLockedOrThrow(username, account) {
+		const lockStatus = this.getLockStatus(account);
+		if (!lockStatus.locked) return;
+		if (lockStatus.expired) {
+			await this.store.update(username, { set: { account: {
+				locked: false,
+				lockReason: "",
+				lockEnds: 0
+			} } });
+			account.locked = false;
+			account.lockEnds = 0;
+			account.lockReason = "";
+			return;
+		}
+		throw new UserAuthError("LOCKED", void 0, {
+			reason: account.lockReason,
+			lockEnds: account.lockEnds
+		});
+	}
+	/**
+	* Bump `failedLoginAttempts`, locking the account when threshold is hit,
+	* and always throw `errorCode` (with `details.lockEnds` when the lockout
+	* just tripped). Used by both `login` and `verifyMfa` so the two factors
+	* share one counter.
+	*/
+	async incrementAndMaybeLock(username, account, errorCode) {
+		const newAttempts = account.failedLoginAttempts + 1;
+		const { threshold, duration } = this.config.lockout;
+		if (threshold > 0 && newAttempts >= threshold) {
+			const lockEnds = duration ? this.config.clock() + duration : 0;
+			await this.store.update(username, {
+				inc: { "account.failedLoginAttempts": 1 },
+				set: { account: {
+					locked: true,
+					lockReason: "Too many login attempts",
+					lockEnds
+				} }
+			});
+			throw new UserAuthError(errorCode, void 0, { lockEnds });
+		}
+		await this.store.update(username, { inc: { "account.failedLoginAttempts": 1 } });
+		throw new UserAuthError(errorCode);
+	}
+};
+//#endregion
+//#region src/store/memory.ts
+var UserStoreMemory = class extends UserStore {
+	store = /* @__PURE__ */ new Map();
+	constructor(seed) {
+		super();
+		if (seed) for (const [key, value] of Object.entries(seed)) this.store.set(key, structuredClone(value));
+	}
+	async exists(username) {
+		return this.store.has(username);
+	}
+	async findByUsername(username) {
+		const user = this.store.get(username);
+		return user ? structuredClone(user) : null;
+	}
+	async create(data) {
+		if (this.store.has(data.username)) throw new UserAuthError("ALREADY_EXISTS", `User "${data.username}" already exists`);
+		this.store.set(data.username, structuredClone(data));
+	}
+	async update(username, update) {
+		const user = this.store.get(username);
+		if (!user) return false;
+		if (update.set) deepMerge(user, update.set);
+		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) incrementAtPath(user, path, amount);
+		return true;
+	}
+	async delete(username) {
+		return this.store.delete(username);
+	}
+};
+//#endregion
+//#region src/password/policies.ts
+const ppHasMinLength = (min = 8) => ({
+	rule: `v.length >= ${min}`,
+	description: `Minimum length ${min}`,
+	errorMessage: `Password must be at least ${min} characters long`
+});
+const ppHasUpperCase = (n = 1) => ({
+	rule: `(v.match(/[A-Z]/g) || []).length >= ${n}`,
+	description: `At least ${n} uppercase character${n === 1 ? "" : "s"}`,
+	errorMessage: `Password must include at least ${n} uppercase character${n === 1 ? "" : "s"}`
+});
+const ppHasLowerCase = (n = 1) => ({
+	rule: `(v.match(/[a-z]/g) || []).length >= ${n}`,
+	description: `At least ${n} lowercase character${n === 1 ? "" : "s"}`,
+	errorMessage: `Password must include at least ${n} lowercase character${n === 1 ? "" : "s"}`
+});
+const ppHasNumber = (n = 1) => ({
+	rule: `(v.match(/\\d/g) || []).length >= ${n}`,
+	description: `At least ${n} number${n === 1 ? "" : "s"}`,
+	errorMessage: `Password must include at least ${n} number${n === 1 ? "" : "s"}`
+});
+const ppHasSpecialChar = (n = 1) => ({
+	rule: `(v.match(/[^A-Za-z0-9]/g) || []).length >= ${n}`,
+	description: `At least ${n} special character${n === 1 ? "" : "s"}`,
+	errorMessage: `Password must include at least ${n} special character${n === 1 ? "" : "s"}`
+});
+const ppMaxRepeatedChars = (maxRepeated = 2) => ({
+	rule: `/(.)\\1{${maxRepeated},}/.test(v) === false`,
+	description: `No more than ${maxRepeated} consecutive repeated characters`,
+	errorMessage: `Password must not have more than ${maxRepeated} consecutive repeated characters`
+});
+//#endregion
+export { PasswordHasher, PasswordPolicy, UserAuthError, UserService, UserStore, UserStoreMemory, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };