@aooth/user 0.1.6 → 0.1.8

package/dist/index.cjs

@@ -1,61 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_user_store = require("./user-store-BPZVAboN.cjs");
+const require_federated_identity_store = require("./federated-identity-store-oRjhnR5l.cjs");
 let node_crypto = require("node:crypto");
-//#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(require_user_store.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 (0, node_crypto.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 (0, node_crypto.timingSafeEqual)(a, b);
-}
-//#endregion
 //#region src/base-x/base32.ts
 /**
 * Partially copied from "thirty-two" library, all credits to Chris Umbel.
@@ -168,7 +113,7 @@ function verifyTotpCode(secret, code, config) {
 	return matchedCounter;
 }
 function generateMfaCode(length = 6) {
-	return require_user_store.generateSecureRandom(length, "0123456789");
+	return require_federated_identity_store.generateSecureRandom(length, "0123456789");
 }
 function hotpCode(key, counter, digits) {
 	const counterBuf = Buffer.alloc(8);
@@ -256,14 +201,14 @@ var PasswordHasher = class {
 		const upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 		const digits = "0123456789";
 		const special = "!@#$%^&*()-_=+";
-		const all = lower + upper + digits + special;
+		const all = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*()-_=+";
 		const bytes = (0, node_crypto.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];
+		for (let i = 4; i < minLen; i++) result[i] = all[bytes[i] % 76];
 		const shuffleBytes = (0, node_crypto.randomBytes)(minLen);
 		for (let i = minLen - 1; i > 0; i--) {
 			const j = shuffleBytes[i] % (i + 1);
@@ -338,7 +283,8 @@ function resolveConfig(config) {
 			scryptR: config?.password?.scryptR ?? 8,
 			scryptP: config?.password?.scryptP ?? 1,
 			keyLength: config?.password?.keyLength ?? 64,
-			policies: normalizePolicies(config?.password?.policies)
+			policies: normalizePolicies(config?.password?.policies),
+			maxAgeMs: config?.password?.maxAgeMs ?? 0
 		},
 		lockout: {
 			threshold: config?.lockout?.threshold ?? 0,
@@ -359,7 +305,17 @@ function deviceTrustSafeEqual(a, b) {
 	if (ab.length !== bb.length) return false;
 	return (0, node_crypto.timingSafeEqual)(ab, bb);
 }
+/**
+* Orchestrates user credentials over a pluggable {@link UserStore}.
+*
+* Identity model: the stable surrogate **`id`** is the token subject. `getUser`
+* and every mutation/admin method are keyed by `id` (the value carried in the
+* session and returned by `useAuth().getUserId()`); only `login` (and other
+* handle-driven entry points) take a `username`/`email` login handle, resolved
+* via `UserStore.findByHandle`.
+*/
 var UserService = class {
+	store;
 	config;
 	hasher;
 	constructor(store, config) {
@@ -371,25 +327,31 @@ var UserService = class {
 	* Creates a user with `account.active: false`. The invite workflow relies
 	* on this default (see `InviteWorkflow.acceptInvite` — pending invitees stay
 	* inactive until they accept). For setup scripts / seeders / tests that
-	* don't go through invite, follow up with `activateAccount(username)` or
-	* `login()` will throw `UserAuthError("INACTIVE")` — which the login
-	* workflow deliberately re-maps to `"Invalid credentials"` to avoid account
+	* don't go through invite, follow up with `activateAccount(id)` or `login()`
+	* will throw `UserAuthError("INACTIVE")` — which the login workflow
+	* deliberately re-maps to `"Invalid credentials"` to avoid account
 	* enumeration, so the failure is silent client-side.
 	*
+	* A stable `id` is minted here (server-managed surrogate, also the token
+	* subject) and returned on the record, so callers can `auth.issue(user.id)`
+	* without a re-read. Pass `id` via `extras` to override it.
+	*
 	* @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.
+	*   keys (`id`, `email`, `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 hash = await this.hasher.hash(pw);
 		const userData = {
+			id: (0, node_crypto.randomUUID)(),
 			username,
 			password: {
-				hash: await this.hasher.hash(pw),
+				hash,
 				history: [],
 				lastChanged: this.config.clock(),
 				isInitial: !password
@@ -412,19 +374,36 @@ var UserService = class {
 		await this.store.create(userData);
 		return userData;
 	}
-	async getUser(username) {
-		const user = await this.store.findByUsername(username);
-		if (!user) throw new require_user_store.UserAuthError("NOT_FOUND");
+	/** Read by the stable `id` (the token subject). */
+	async getUser(id) {
+		const user = await this.store.findById(id);
+		if (!user) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 		return user;
 	}
-	async login(username, password) {
-		const user = await this.store.findByUsername(username);
-		if (!user) throw new require_user_store.UserAuthError("NOT_FOUND");
-		if (!user.account.active) throw new require_user_store.UserAuthError("INACTIVE");
-		await this.ensureNotLockedOrThrow(username, user.account);
+	/**
+	* Deterministic handle resolver — `username` exact, then `email` exact.
+	* Returns `null` when nothing matches. Maps a login/recovery handle to a row;
+	* `login` uses the same resolution.
+	*/
+	async findByHandle(handle) {
+		return this.store.findByHandle(handle);
+	}
+	/**
+	* Permissive lookup — `id`, then `username`, then `email` (ordered, first
+	* match). For internal / admin / recovery callers that may hold either an id
+	* or a handle. NOT for the login path (use {@link login}/{@link findByHandle}).
+	*/
+	async findByIdentifier(value) {
+		return this.store.findByIdentifier(value);
+	}
+	async login(handle, password, lockoutOverride) {
+		const user = await this.store.findByHandle(handle);
+		if (!user) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
+		if (!user.account.active) throw new require_federated_identity_store.UserAuthError("INACTIVE");
+		await this.ensureNotLockedOrThrow(user.id, user.account);
 		if (await this.hasher.verify(password, user.password.hash)) {
 			const now = this.config.clock();
-			await this.store.update(username, { set: { account: {
+			await this.store.update(user.id, { set: { account: {
 				lastLogin: now,
 				failedLoginAttempts: 0
 			} } });
@@ -435,30 +414,30 @@ var UserService = class {
 				mfaRequired: this.hasConfirmedMfaMethods(user.mfa)
 			};
 		}
-		return this.incrementAndMaybeLock(username, user.account, "INVALID_CREDENTIALS");
+		return this.incrementAndMaybeLock(user.id, user.account, "INVALID_CREDENTIALS", lockoutOverride);
 	}
-	async verifyPassword(username, password) {
-		const user = await this.store.findByUsername(username);
-		if (!user) throw new require_user_store.UserAuthError("NOT_FOUND");
+	async verifyPassword(id, password) {
+		const user = await this.store.findById(id);
+		if (!user) throw new require_federated_identity_store.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 require_user_store.UserAuthError("PASSWORDS_MISMATCH");
-		const user = await this.getUser(username);
-		if (!await this.hasher.verify(currentPassword, user.password.hash)) throw new require_user_store.UserAuthError("INVALID_CREDENTIALS");
-		await this.applyPasswordChange(username, user, newPassword);
+	async changePassword(id, currentPassword, newPassword, repeatPassword) {
+		if (repeatPassword !== void 0 && newPassword !== repeatPassword) throw new require_federated_identity_store.UserAuthError("PASSWORDS_MISMATCH");
+		const user = await this.getUser(id);
+		if (!await this.hasher.verify(currentPassword, user.password.hash)) throw new require_federated_identity_store.UserAuthError("INVALID_CREDENTIALS");
+		await this.applyPasswordChange(id, user, newPassword);
 	}
-	async setPassword(username, newPassword) {
-		const user = await this.getUser(username);
-		await this.applyPasswordChange(username, user, newPassword);
+	async setPassword(id, newPassword) {
+		const user = await this.getUser(id);
+		await this.applyPasswordChange(id, 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/invite/cancel` to revoke a pending invitation.
+	* Hard-delete the user row by `id`. Returns nothing on success. Throws
+	* `UserAuthError("NOT_FOUND")` when no row matches. Used by the invite
+	* workflow's `auth/invite/cancel` to revoke a pending invitation.
 	*/
-	async deleteUser(username) {
-		if (!await this.store.delete(username)) throw new require_user_store.UserAuthError("NOT_FOUND");
+	async deleteUser(id) {
+		if (!await this.store.delete(id)) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
 	/**
 	* Deep-merge `patch` into the user record (top-level fields are shallow-
@@ -466,31 +445,31 @@ var UserService = class {
 	* `@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 require_user_store.UserAuthError("NOT_FOUND");
-		return this.getUser(username);
+	async update(id, patch) {
+		if (!await this.store.update(id, { set: patch })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
+		return this.getUser(id);
 	}
-	async activateAccount(username) {
-		if (!await this.store.update(username, { set: { account: { active: true } } })) throw new require_user_store.UserAuthError("NOT_FOUND");
+	async activateAccount(id) {
+		if (!await this.store.update(id, { set: { account: { active: true } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
-	async deactivateAccount(username) {
-		if (!await this.store.update(username, { set: { account: { active: false } } })) throw new require_user_store.UserAuthError("NOT_FOUND");
+	async deactivateAccount(id) {
+		if (!await this.store.update(id, { set: { account: { active: false } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
-	async lockAccount(username, reason, duration) {
+	async lockAccount(id, reason, duration) {
 		const lockEnds = duration ? this.config.clock() + duration : 0;
-		if (!await this.store.update(username, { set: { account: {
+		if (!await this.store.update(id, { set: { account: {
 			locked: true,
 			lockReason: reason,
 			lockEnds
-		} } })) throw new require_user_store.UserAuthError("NOT_FOUND");
+		} } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
-	async unlockAccount(username) {
-		if (!await this.store.update(username, { set: { account: {
+	async unlockAccount(id) {
+		if (!await this.store.update(id, { set: { account: {
 			locked: false,
 			lockReason: "",
 			lockEnds: 0,
 			failedLoginAttempts: 0
-		} } })) throw new require_user_store.UserAuthError("NOT_FOUND");
+		} } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
 	getLockStatus(account) {
 		if (!account.locked) return {
@@ -506,6 +485,24 @@ var UserService = class {
 			lockEnds: account.lockEnds
 		};
 	}
+	/**
+	* Returns `true` when the user's password is older than
+	* `config.password.maxAgeMs`. Returns `false` when:
+	* - `maxAgeMs` is unset or `0` (expiry disabled)
+	* - `password.lastChanged` is `0` / falsy (no recorded change — never
+	*   expire a user whose timestamp wasn't captured, since that would
+	*   force-loop on every login)
+	*
+	* Consulted by `@aooth/auth-moost` `LoginWorkflow`'s `credentials`
+	* step to set `ctx.isPasswordExpired` when `guards.passwordExpiry`
+	* is true (the default).
+	*/
+	isPasswordExpired(user, now = this.config.clock()) {
+		const maxAgeMs = this.config.password.maxAgeMs;
+		const lastChanged = user.password.lastChanged;
+		if (!maxAgeMs || !lastChanged) return false;
+		return now - lastChanged > maxAgeMs;
+	}
 	async checkPolicies(password, passwordData) {
 		const result = {
 			passed: true,
@@ -533,13 +530,13 @@ var UserService = class {
 			errorMessage: p.errorMessage
 		}));
 	}
-	async addMfaMethod(username, method) {
-		await this.store.withCas(username, (user) => {
+	async addMfaMethod(id, method) {
+		await this.store.withCas(id, (user) => {
 			return { set: { mfa: { methods: [...user.mfa.methods.filter((m) => m.name !== method.name), method] } } };
 		});
 	}
-	async confirmMfaMethod(username, name) {
-		await this.store.withCas(username, (user) => {
+	async confirmMfaMethod(id, name) {
+		await this.store.withCas(id, (user) => {
 			let found = false;
 			const methods = user.mfa.methods.map((m) => {
 				if (m.name === name) {
@@ -551,90 +548,51 @@ var UserService = class {
 				}
 				return m;
 			});
-			if (!found) throw new require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
+			if (!found) throw new require_federated_identity_store.UserAuthError("MFA_NOT_CONFIGURED");
 			return { set: { mfa: { methods } } };
 		});
 	}
-	async removeMfaMethod(username, name) {
-		const user = await this.getUser(username);
+	async removeMfaMethod(id, name) {
+		const user = await this.getUser(id);
 		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 });
+		await this.store.update(id, { set: update });
 	}
-	async setDefaultMfaMethod(username, name) {
-		const user = await this.getUser(username);
-		if (name && !user.mfa.methods.some((m) => m.name === name)) throw new require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
-		await this.store.update(username, { set: { mfa: {
+	async setDefaultMfaMethod(id, name) {
+		const user = await this.getUser(id);
+		if (name && !user.mfa.methods.some((m) => m.name === name)) throw new require_federated_identity_store.UserAuthError("MFA_NOT_CONFIGURED");
+		await this.store.update(id, { set: { mfa: {
 			defaultMethod: name,
 			autoSend: false
 		} } });
 	}
-	async setMfaAutoSend(username, value) {
-		if (!await this.store.update(username, { set: { mfa: { autoSend: value } } })) throw new require_user_store.UserAuthError("NOT_FOUND");
+	async setMfaAutoSend(id, value) {
+		if (!await this.store.update(id, { set: { mfa: { autoSend: value } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
 	getAvailableMfaMethods(mfa) {
 		return mfa.methods.filter((m) => m.confirmed).map((m) => ({
 			name: m.name,
 			isDefault: mfa.defaultMethod === m.name,
-			masked: require_user_store.maskMfaValue(m)
+			masked: require_federated_identity_store.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 require_user_store.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). Single-use is enforced by
-	* optimistic-concurrency CAS on the version column — concurrent consumes
-	* of the same code race fairly and only one wins; the loser re-reads,
-	* finds the hash already removed, and returns `false`.
-	*
-	* Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
-	* Throws `UserAuthError("CAS_EXHAUSTED")` if retries are saturated.
-	*/
-	async consumeBackupCode(username, code) {
-		let consumed = false;
-		await this.store.withCas(username, (user) => {
-			const hashes = user.backupCodes ?? [];
-			const idx = hashes.findIndex((h) => verifyMfaCode(code, h));
-			if (idx < 0) {
-				consumed = false;
-				return null;
-			}
-			consumed = true;
-			return { set: { backupCodes: hashes.filter((_, i) => i !== idx) } };
-		});
-		return consumed;
-	}
-	/**
 	* 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 require_user_store.UserAuthError("INACTIVE");
-		await this.ensureNotLockedOrThrow(username, user.account);
+	async verifyMfa(id, code, config, lockoutOverride) {
+		const user = await this.getUser(id);
+		if (!user.account.active) throw new require_federated_identity_store.UserAuthError("INACTIVE");
+		await this.ensureNotLockedOrThrow(id, user.account);
 		const totp = user.mfa.methods.find((m) => m.name === "totp" && m.confirmed);
-		if (!totp) throw new require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
+		if (!totp) throw new require_federated_identity_store.UserAuthError("MFA_NOT_CONFIGURED");
 		const matchedCounter = verifyTotpCode(totp.value, code, config);
 		const isReplay = matchedCounter !== null && totp.lastUsedWindow !== void 0 && matchedCounter <= totp.lastUsedWindow;
 		if (matchedCounter !== null && !isReplay) {
 			let replayDuringCas = false;
-			await this.store.withCas(username, (current) => {
+			await this.store.withCas(id, (current) => {
 				const currentTotp = current.mfa.methods.find((m) => m.name === "totp" && m.confirmed);
 				if (currentTotp?.lastUsedWindow !== void 0 && matchedCounter <= currentTotp.lastUsedWindow) {
 					replayDuringCas = true;
@@ -649,7 +607,7 @@ var UserService = class {
 			});
 			if (!replayDuringCas) return;
 		}
-		await this.incrementAndMaybeLock(username, user.account, "MFA_INVALID");
+		await this.incrementAndMaybeLock(id, user.account, "MFA_INVALID", lockoutOverride);
 	}
 	/**
 	* Verify a TOTP code against an UNCONFIRMED `totp` MFA method during initial
@@ -662,10 +620,10 @@ var UserService = class {
 	* Throws: NOT_FOUND if user missing; MFA_NOT_CONFIGURED if no unconfirmed
 	* totp method; MFA_INVALID on wrong code.
 	*/
-	async verifyTotpSetupCode(username, code, config) {
-		const totp = (await this.getUser(username)).mfa.methods.find((m) => m.name === "totp" && !m.confirmed);
-		if (!totp) throw new require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
-		if (verifyTotpCode(totp.value, code, config) === null) throw new require_user_store.UserAuthError("MFA_INVALID");
+	async verifyTotpSetupCode(id, code, config) {
+		const totp = (await this.getUser(id)).mfa.methods.find((m) => m.name === "totp" && !m.confirmed);
+		if (!totp) throw new require_federated_identity_store.UserAuthError("MFA_NOT_CONFIGURED");
+		if (verifyTotpCode(totp.value, code, config) === null) throw new require_federated_identity_store.UserAuthError("MFA_INVALID");
 	}
 	getPasswordHasher() {
 		return this.hasher;
@@ -695,8 +653,8 @@ var UserService = class {
 	* write — the array shape is preserved end-to-end so DB adapters with a
 	* merge strategy replace the whole array.
 	*/
-	async addTrustedDevice(username, record) {
-		await this.store.withCas(username, (user) => {
+	async addTrustedDevice(id, record) {
+		await this.store.withCas(id, (user) => {
 			return { set: { trustedDevices: [...user.trustedDevices ?? [], record] } };
 		});
 	}
@@ -705,13 +663,13 @@ var UserService = class {
 	* 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) {
+	async verifyTrustedDevice(userId, 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 (!deviceTrustSafeEqual(token.slice(sepIdx + 1), signDeviceTrust(secret, `${userId}|${raw}|${ip ?? ""}`))) return false;
+		const user = await this.store.findById(userId);
 		if (!user) return false;
 		const list = user.trustedDevices ?? [];
 		const now = this.config.clock();
@@ -724,33 +682,33 @@ var UserService = class {
 	* 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);
+	async revokeTrustedDevice(id, token) {
+		const user = await this.store.findById(id);
 		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 } });
+		await this.store.update(id, { set: { trustedDevices: next } });
 	}
-	async listTrustedDevices(username) {
-		return (await this.getUser(username)).trustedDevices ?? [];
+	async listTrustedDevices(id) {
+		return (await this.getUser(id)).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) {
+	async applyPasswordChange(id, user, newPassword) {
 		const policyResult = await this.checkPolicies(newPassword, user.password);
-		if (!policyResult.passed) throw new require_user_store.UserAuthError("POLICY_VIOLATION", policyResult.errors.join("; "), { policies: policyResult.policies });
+		if (!policyResult.passed) throw new require_federated_identity_store.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 require_user_store.UserAuthError("PASSWORD_IN_HISTORY");
+			if ((await Promise.all(hashesToCheck.map((h) => this.hasher.verify(newPassword, h)))).some(Boolean)) throw new require_federated_identity_store.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: {
+		await this.store.update(id, { set: { password: {
 			hash: newHash,
 			history: newHistory,
 			lastChanged: this.config.clock(),
@@ -764,11 +722,11 @@ var UserService = class {
 	* If `account.locked`: auto-unlock when the lock has expired (mutating
 	* `account` in place), or throw `LOCKED` otherwise.
 	*/
-	async ensureNotLockedOrThrow(username, account) {
+	async ensureNotLockedOrThrow(id, account) {
 		const lockStatus = this.getLockStatus(account);
 		if (!lockStatus.locked) return;
 		if (lockStatus.expired) {
-			await this.store.update(username, { set: { account: {
+			await this.store.update(id, { set: { account: {
 				locked: false,
 				lockReason: "",
 				lockEnds: 0
@@ -778,7 +736,7 @@ var UserService = class {
 			account.lockReason = "";
 			return;
 		}
-		throw new require_user_store.UserAuthError("LOCKED", void 0, {
+		throw new require_federated_identity_store.UserAuthError("LOCKED", void 0, {
 			reason: account.lockReason,
 			lockEnds: account.lockEnds
 		});
@@ -788,13 +746,21 @@ var UserService = class {
 	* 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.
+	*
+	* `lockoutOverride` lets a caller (e.g. a workflow policy resolver) force a
+	* different posture for THIS lock — notably `{ duration: 0 }` to make the
+	* lock permanent (admin-/recovery-lift only) instead of timed. Unset fields
+	* fall back to `this.config.lockout`.
 	*/
-	async incrementAndMaybeLock(username, account, errorCode) {
+	async incrementAndMaybeLock(id, account, errorCode, lockoutOverride) {
 		const newAttempts = account.failedLoginAttempts + 1;
-		const { threshold, duration } = this.config.lockout;
+		const { threshold, duration } = {
+			...this.config.lockout,
+			...lockoutOverride
+		};
 		if (threshold > 0 && newAttempts >= threshold) {
 			const lockEnds = duration ? this.config.clock() + duration : 0;
-			await this.store.update(username, {
+			await this.store.update(id, {
 				inc: { "account.failedLoginAttempts": 1 },
 				set: { account: {
 					locked: true,
@@ -802,61 +768,148 @@ var UserService = class {
 					lockEnds
 				} }
 			});
-			throw new require_user_store.UserAuthError(errorCode, void 0, { lockEnds });
+			throw new require_federated_identity_store.UserAuthError(errorCode, void 0, { lockEnds });
 		}
-		await this.store.update(username, { inc: { "account.failedLoginAttempts": 1 } });
-		throw new require_user_store.UserAuthError(errorCode);
+		await this.store.update(id, { inc: { "account.failedLoginAttempts": 1 } });
+		throw new require_federated_identity_store.UserAuthError(errorCode);
 	}
 };
 //#endregion
 //#region src/store/memory.ts
-var UserStoreMemory = class extends require_user_store.UserStore {
+var UserStoreMemory = class extends require_federated_identity_store.UserStore {
+	/** Keyed by the stable surrogate `id` (the token subject). */
 	store = /* @__PURE__ */ new Map();
+	/**
+	* Optional seed. The map is keyed by each record's `id`; a record missing an
+	* `id` gets one minted (mirrors the DB `@db.default.uuid`). The seed object's
+	* keys are ignored — identity is the record's `id`.
+	*/
 	constructor(seed) {
 		super();
-		if (seed) for (const [key, value] of Object.entries(seed)) this.store.set(key, structuredClone(value));
+		if (seed) for (const value of Object.values(seed)) {
+			const cloned = structuredClone(value);
+			if (!cloned.id) cloned.id = (0, node_crypto.randomUUID)();
+			this.store.set(cloned.id, cloned);
+		}
 	}
-	async exists(username) {
-		return this.store.has(username);
+	async exists(handle) {
+		for (const u of this.store.values()) if (u.username === handle) return true;
+		return false;
 	}
-	async findByUsername(username) {
-		const user = this.store.get(username);
+	async findById(id) {
+		const user = this.store.get(id);
 		return user ? structuredClone(user) : null;
 	}
+	async findByHandle(handle) {
+		let byEmail = null;
+		for (const u of this.store.values()) {
+			if (u.username === handle) return structuredClone(u);
+			if (byEmail === null && u.email !== void 0 && u.email === handle) byEmail = u;
+		}
+		return byEmail ? structuredClone(byEmail) : null;
+	}
+	async findByIdentifier(value) {
+		const byId = this.store.get(value);
+		if (byId) return structuredClone(byId);
+		return this.findByHandle(value);
+	}
 	async create(data) {
-		if (this.store.has(data.username)) throw new require_user_store.UserAuthError("ALREADY_EXISTS", `User "${data.username}" already exists`);
 		const cloned = structuredClone(data);
+		if (!cloned.id) cloned.id = (0, node_crypto.randomUUID)();
+		for (const u of this.store.values()) {
+			if (u.username === cloned.username) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", `User "${cloned.username}" already exists`);
+			if (cloned.email !== void 0 && u.email === cloned.email) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", `Email "${cloned.email}" already exists`);
+		}
 		cloned.version = 0;
-		this.store.set(data.username, cloned);
+		this.store.set(cloned.id, cloned);
 	}
-	async update(username, update) {
-		const user = this.store.get(username);
+	async update(id, update) {
+		const user = this.store.get(id);
 		if (!user) return false;
 		if (update.expectedVersion !== void 0 && (user.version ?? 0) !== update.expectedVersion) return false;
-		if (update.set) require_user_store.deepMerge(user, update.set);
-		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) require_user_store.incrementAtPath(user, path, amount);
+		if (update.set) require_federated_identity_store.deepMerge(user, update.set);
+		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) require_federated_identity_store.incrementAtPath(user, path, amount);
 		user.version = (user.version ?? 0) + 1;
 		return true;
 	}
-	async delete(username) {
-		return this.store.delete(username);
+	async delete(id) {
+		return this.store.delete(id);
 	}
-	async withCas(username, mutator, opts) {
+	async withCas(id, mutator, opts) {
 		const maxAttempts = opts?.maxAttempts ?? 2;
 		for (let attempt = 0; attempt < maxAttempts; attempt++) {
-			const current = await this.findByUsername(username);
-			if (!current) throw new require_user_store.UserAuthError("NOT_FOUND");
+			const current = await this.findById(id);
+			if (!current) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 			const patch = mutator(current);
 			if (patch === null) return;
-			if (await this.update(username, {
+			if (await this.update(id, {
 				...patch,
 				expectedVersion: current.version ?? 0
 			})) return;
 		}
-		throw new require_user_store.UserAuthError("CAS_EXHAUSTED");
+		throw new require_federated_identity_store.UserAuthError("CAS_EXHAUSTED");
 	}
 };
 //#endregion
+//#region src/store/federated-identity-store-memory.ts
+/**
+* In-memory {@link FederatedIdentityStore} — the offline-testable reference
+* impl (RFC IDP.md §9). Keyed by the composite `(provider, subject)`;
+* `structuredClone` on every read/write isolates callers from later mutation
+* (mirrors `UserStoreMemory`).
+*/
+var FederatedIdentityStoreMemory = class extends require_federated_identity_store.FederatedIdentityStore {
+	/** Keyed by `compositeKey(provider, subject)`. */
+	store = /* @__PURE__ */ new Map();
+	clock;
+	constructor(opts) {
+		super();
+		this.clock = opts?.clock ?? Date.now;
+	}
+	async find(provider, subject) {
+		const row = this.store.get(compositeKey(provider, subject));
+		return row ? structuredClone(row) : null;
+	}
+	async listForUser(userId) {
+		return [...this.store.values()].filter((row) => row.userId === userId).toSorted((a, b) => a.linkedAt - b.linkedAt).map((row) => structuredClone(row));
+	}
+	async link(rec) {
+		const key = compositeKey(rec.provider, rec.subject);
+		if (this.store.has(key)) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", `Provider account "${rec.provider}:${rec.subject}" is already linked`);
+		const row = {
+			id: (0, node_crypto.randomUUID)(),
+			provider: rec.provider,
+			subject: rec.subject,
+			userId: rec.userId,
+			...require_federated_identity_store.pickDefinedProfile(rec),
+			linkedAt: this.clock()
+		};
+		this.store.set(key, structuredClone(row));
+		return structuredClone(row);
+	}
+	async unlink(provider, subject) {
+		return this.store.delete(compositeKey(provider, subject));
+	}
+	async touchLogin(provider, subject, profile) {
+		const row = this.store.get(compositeKey(provider, subject));
+		if (!row) return;
+		row.lastLoginAt = this.clock();
+		if (profile) Object.assign(row, require_federated_identity_store.pickDefinedProfile(profile));
+	}
+	async deleteAllForUser(userId) {
+		let removed = 0;
+		for (const [key, row] of this.store) if (row.userId === userId) {
+			this.store.delete(key);
+			removed++;
+		}
+		return removed;
+	}
+};
+/** Null-byte separator can't appear in a provider id / IdP subject, so the join is unambiguous. */
+function compositeKey(provider, subject) {
+	return `${provider}${subject}`;
+}
+//#endregion
 //#region src/password/policies.ts
 const ppHasMinLength = (min = 8) => definePasswordPolicy({
 	rule: (v, min) => v.length >= min,
@@ -895,29 +948,57 @@ const ppMaxRepeatedChars = (maxRepeated = 2) => definePasswordPolicy({
 	errorMessage: `Password must not have more than ${maxRepeated} consecutive repeated characters`
 });
 //#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 (0, node_crypto.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 (0, node_crypto.timingSafeEqual)(a, b);
+}
+//#endregion
+exports.FederatedIdentityStore = require_federated_identity_store.FederatedIdentityStore;
+exports.FederatedIdentityStoreMemory = FederatedIdentityStoreMemory;
 exports.PasswordHasher = PasswordHasher;
 exports.PasswordPolicy = PasswordPolicy;
-exports.UserAuthError = require_user_store.UserAuthError;
+exports.UserAuthError = require_federated_identity_store.UserAuthError;
 exports.UserService = UserService;
-exports.UserStore = require_user_store.UserStore;
+exports.UserStore = require_federated_identity_store.UserStore;
 exports.UserStoreMemory = UserStoreMemory;
 exports.definePasswordPolicy = definePasswordPolicy;
-exports.generateBackupCodePlaintext = generateBackupCodePlaintext;
 exports.generateMfaCode = generateMfaCode;
 exports.generateTotpCode = generateTotpCode;
 exports.generateTotpSecret = generateTotpSecret;
 exports.generateTotpUri = generateTotpUri;
 exports.hashMfaCode = hashMfaCode;
-exports.maskEmail = require_user_store.maskEmail;
-exports.maskMfaValue = require_user_store.maskMfaValue;
-exports.maskPhone = require_user_store.maskPhone;
+exports.maskEmail = require_federated_identity_store.maskEmail;
+exports.maskMfaValue = require_federated_identity_store.maskMfaValue;
+exports.maskPhone = require_federated_identity_store.maskPhone;
 exports.normalizePolicies = normalizePolicies;
+exports.pickDefinedProfile = require_federated_identity_store.pickDefinedProfile;
 exports.ppHasLowerCase = ppHasLowerCase;
 exports.ppHasMinLength = ppHasMinLength;
 exports.ppHasNumber = ppHasNumber;
 exports.ppHasSpecialChar = ppHasSpecialChar;
 exports.ppHasUpperCase = ppHasUpperCase;
 exports.ppMaxRepeatedChars = ppMaxRepeatedChars;
-exports.setAtPath = require_user_store.setAtPath;
+exports.setAtPath = require_federated_identity_store.setAtPath;
 exports.verifyMfaCode = verifyMfaCode;
 exports.verifyTotpCode = verifyTotpCode;