@aooth/user 0.1.2 → 0.1.4

package/dist/atscript-db.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_user_store = require("./user-store-CdWrTeqR.cjs");
+const require_user_store = require("./user-store-BPZVAboN.cjs");
 //#region src/atscript-db/index.ts
 function isConflict(err) {
 	return typeof err === "object" && err !== null && err.code === "CONFLICT";
@@ -34,11 +34,35 @@ var UsersStoreAtscriptDb = class extends require_user_store.UserStore {
 		if (update.set) Object.assign(patch, update.set);
 		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) require_user_store.setAtPath(patch, path, { $inc: amount });
 		if (Object.keys(patch).length <= 1) return true;
+		if (update.expectedVersion !== void 0) patch.$cas = { version: update.expectedVersion };
 		return (await this.table.updateOne(patch)).matchedCount > 0;
 	}
 	async delete(username) {
 		return (await this.table.deleteMany({ username })).deletedCount > 0;
 	}
+	/**
+	* Inline retry loop rather than delegating to @atscript/db's
+	* `withOptimisticRetry`: that helper expects the mutator to always return a
+	* patch object, but our contract lets the mutator return `null` (the
+	* race-loser detects nothing to do — see `UserService.consumeBackupCode`).
+	* Bridging would need a sentinel exception. The version-bump + $cas
+	* atomicity still happen at the atscript-db table layer via the
+	* `expectedVersion` we thread through `update()`.
+	*/
+	async withCas(username, 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 patch = mutator(current);
+			if (patch === null) return;
+			if (await this.update(username, {
+				...patch,
+				expectedVersion: current.version ?? 0
+			})) return;
+		}
+		throw new require_user_store.UserAuthError("CAS_EXHAUSTED");
+	}
 };
 //#endregion
 exports.UsersStoreAtscriptDb = UsersStoreAtscriptDb;

package/dist/atscript-db.d.cts

@@ -1,4 +1,4 @@
-import { C as UserStoreUpdate, t as UserStore, x as UserCredentials } from "./user-store-VJPWNgdp.cjs";
+import { S as UserCredentials, n as WithCasOptions, t as UserStore, w as UserStoreUpdate } from "./user-store-B3EStUfT.cjs";
 
 //#region src/atscript-db/index.d.ts
 /**
@@ -50,6 +50,16 @@ declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends
   create(data: UserCredentials & TUserCustom): Promise<void>;
   update(username: string, update: UserStoreUpdate): Promise<boolean>;
   delete(username: string): Promise<boolean>;
+  /**
+   * Inline retry loop rather than delegating to @atscript/db's
+   * `withOptimisticRetry`: that helper expects the mutator to always return a
+   * patch object, but our contract lets the mutator return `null` (the
+   * race-loser detects nothing to do — see `UserService.consumeBackupCode`).
+   * Bridging would need a sentinel exception. The version-bump + $cas
+   * atomicity still happen at the atscript-db table layer via the
+   * `expectedVersion` we thread through `update()`.
+   */
+  withCas(username: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
 export { AuthUserTable, UserCredentialsRow, UsersStoreAtscriptDb };

package/dist/atscript-db.d.mts

@@ -1,4 +1,4 @@
-import { C as UserStoreUpdate, t as UserStore, x as UserCredentials } from "./user-store-Dbc9unW3.mjs";
+import { S as UserCredentials, n as WithCasOptions, t as UserStore, w as UserStoreUpdate } from "./user-store-C1lxahSB.mjs";
 
 //#region src/atscript-db/index.d.ts
 /**
@@ -50,6 +50,16 @@ declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends
   create(data: UserCredentials & TUserCustom): Promise<void>;
   update(username: string, update: UserStoreUpdate): Promise<boolean>;
   delete(username: string): Promise<boolean>;
+  /**
+   * Inline retry loop rather than delegating to @atscript/db's
+   * `withOptimisticRetry`: that helper expects the mutator to always return a
+   * patch object, but our contract lets the mutator return `null` (the
+   * race-loser detects nothing to do — see `UserService.consumeBackupCode`).
+   * Bridging would need a sentinel exception. The version-bump + $cas
+   * atomicity still happen at the atscript-db table layer via the
+   * `expectedVersion` we thread through `update()`.
+   */
+  withCas(username: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
 export { AuthUserTable, UserCredentialsRow, UsersStoreAtscriptDb };

package/dist/atscript-db.mjs

@@ -1,4 +1,4 @@
-import { c as setAtPath, l as UserAuthError, t as UserStore } from "./user-store-B_l9vqlQ.mjs";
+import { c as setAtPath, l as UserAuthError, t as UserStore } from "./user-store-BaBmH13V.mjs";
 //#region src/atscript-db/index.ts
 function isConflict(err) {
 	return typeof err === "object" && err !== null && err.code === "CONFLICT";
@@ -33,11 +33,35 @@ var UsersStoreAtscriptDb = class extends UserStore {
 		if (update.set) Object.assign(patch, update.set);
 		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) setAtPath(patch, path, { $inc: amount });
 		if (Object.keys(patch).length <= 1) return true;
+		if (update.expectedVersion !== void 0) patch.$cas = { version: update.expectedVersion };
 		return (await this.table.updateOne(patch)).matchedCount > 0;
 	}
 	async delete(username) {
 		return (await this.table.deleteMany({ username })).deletedCount > 0;
 	}
+	/**
+	* Inline retry loop rather than delegating to @atscript/db's
+	* `withOptimisticRetry`: that helper expects the mutator to always return a
+	* patch object, but our contract lets the mutator return `null` (the
+	* race-loser detects nothing to do — see `UserService.consumeBackupCode`).
+	* Bridging would need a sentinel exception. The version-bump + $cas
+	* atomicity still happen at the atscript-db table layer via the
+	* `expectedVersion` we thread through `update()`.
+	*/
+	async withCas(username, mutator, opts) {
+		const maxAttempts = opts?.maxAttempts ?? 2;
+		for (let attempt = 0; attempt < maxAttempts; attempt++) {
+			const current = await this.findByUsername(username);
+			if (!current) throw new UserAuthError("NOT_FOUND");
+			const patch = mutator(current);
+			if (patch === null) return;
+			if (await this.update(username, {
+				...patch,
+				expectedVersion: current.version ?? 0
+			})) return;
+		}
+		throw new UserAuthError("CAS_EXHAUSTED");
+	}
 };
 //#endregion
 export { UsersStoreAtscriptDb };

package/dist/index.cjs

@@ -1,7 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_user_store = require("./user-store-CdWrTeqR.cjs");
+const require_user_store = require("./user-store-BPZVAboN.cjs");
 let node_crypto = require("node:crypto");
-let _prostojs_ftring = require("@prostojs/ftring");
 //#region src/mfa/backup-codes.ts
 /**
 * Custom alphabet for backup codes — uppercase letters and digits with the
@@ -146,6 +145,11 @@ function generateTotpCode(secret, config) {
 	const counter = Math.floor(now / 1e3 / period);
 	return hotpCode(decode(secret), counter, digits);
 }
+/**
+* Returns the matched HOTP counter when `code` is valid within the verification
+* window, otherwise `null`. Returning the counter (not a bool) lets the caller
+* persist `lastUsedWindow` and reject same-window replays (RFC 6238 §5.2 SHOULD).
+*/
 function verifyTotpCode(secret, code, config) {
 	const period = config?.period ?? 30;
 	const digits = config?.digits ?? 6;
@@ -153,14 +157,15 @@ function verifyTotpCode(secret, code, config) {
 	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;
+	if (typeof code !== "string" || code.length !== digits) return null;
 	const submitted = Buffer.from(code, "utf8");
-	let matched = false;
+	let matchedCounter = null;
 	for (let i = -window; i <= window; i++) {
-		const expected = Buffer.from(hotpCode(key, counter + i, digits), "utf8");
-		if (expected.length === submitted.length && (0, node_crypto.timingSafeEqual)(expected, submitted)) matched = true;
+		const stepCounter = counter + i;
+		const expected = Buffer.from(hotpCode(key, stepCounter, digits), "utf8");
+		if (expected.length === submitted.length && (0, node_crypto.timingSafeEqual)(expected, submitted)) matchedCounter = stepCounter;
 	}
-	return matched;
+	return matchedCounter;
 }
 function generateMfaCode(length = 6) {
 	return require_user_store.generateSecureRandom(length, "0123456789");
@@ -269,33 +274,57 @@ var PasswordHasher = class {
 };
 //#endregion
 //#region src/password/policy.ts
-const fnPool = new _prostojs_ftring.FtringsPool();
 function normalizePolicies(policies) {
 	return (policies || []).map((p) => p instanceof PasswordPolicy ? p : new PasswordPolicy(p));
 }
+/**
+* Helper that builds a `PasswordPolicyDef` from a real backend function plus
+* its bound positional arguments. The function runs directly on the server
+* (no sandbox, no eval); `serialized` is auto-derived as
+* `(v) => (${rule.toString()})(v, ${args.map(JSON.stringify).join(', ')})`
+* so the same constraint can ship to the frontend without re-implementing it.
+*
+* Bundler-safe: positional invocation means renamed parameters inside the
+* function body stay consistent — the call site only relies on argument
+* ORDER, not identifier preservation.
+*
+* Constraint on the rule body: it MUST reference only its own parameters.
+* No closures over module imports, no `this`, no helpers from outer scope —
+* `rule.toString()` ships the literal source; any free identifier the
+* frontend cannot resolve breaks transferability. (`String.prototype.match`,
+* regex literals, plain JS globals are fine.)
+*
+* Omit `args` to mark the policy backend-only — `serialized` stays
+* `undefined` and `transferable` is false; frontend pre-validation skips it
+* and only the server check enforces the rule.
+*/
+function definePasswordPolicy(opts) {
+	const { rule, args, description, errorMessage } = opts;
+	const def = { rule: args ? (v) => rule(v, ...args) : (v) => rule(v, ...[]) };
+	if (args) {
+		const argList = args.map((a) => JSON.stringify(a)).join(", ");
+		def.serialized = argList.length > 0 ? `(v) => (${rule.toString()})(v, ${argList})` : `(v) => (${rule.toString()})(v)`;
+	}
+	if (description !== void 0) def.description = description;
+	if (errorMessage !== void 0) def.errorMessage = errorMessage;
+	return def;
+}
 var PasswordPolicy = class {
 	rule;
+	serialized;
 	description;
 	errorMessage;
 	constructor(config) {
 		this.rule = config.rule;
+		if (config.serialized !== void 0) this.serialized = config.serialized;
 		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);
+		return this.rule(password, context);
 	}
 	get transferable() {
-		return typeof this.rule === "string";
+		return this.serialized !== void 0;
 	}
 };
 //#endregion
@@ -339,6 +368,14 @@ var UserService = class {
 		this.hasher = new PasswordHasher(this.config.password);
 	}
 	/**
+	* 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
+	* enumeration, so the failure is silent client-side.
+	*
 	* @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.
@@ -418,7 +455,7 @@ var UserService = class {
 	/**
 	* 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.
+	* 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");
@@ -491,30 +528,32 @@ var UserService = class {
 	}
 	getTransferablePolicies() {
 		return this.config.password.policies.filter((p) => p.transferable).map((p) => ({
-			rule: p.rule,
+			rule: p.serialized,
 			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 } } });
+		await this.store.withCas(username, (user) => {
+			return { set: { mfa: { methods: [...user.mfa.methods.filter((m) => m.name !== method.name), method] } } };
+		});
 	}
 	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;
+		await this.store.withCas(username, (user) => {
+			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 require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
+			return { set: { mfa: { methods } } };
 		});
-		if (!found) throw new require_user_store.UserAuthError("MFA_NOT_CONFIGURED");
-		await this.store.update(username, { set: { mfa: { methods } } });
 	}
 	async removeMfaMethod(username, name) {
 		const user = await this.getUser(username);
@@ -557,24 +596,27 @@ var UserService = class {
 	/**
 	* 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.
+	* 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) {
-		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;
+		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.
@@ -588,12 +630,43 @@ var UserService = class {
 		await this.ensureNotLockedOrThrow(username, 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 (verifyTotpCode(totp.value, code, config)) {
-			if (user.account.failedLoginAttempts > 0) await this.store.update(username, { set: { account: { failedLoginAttempts: 0 } } });
-			return;
+		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) => {
+				const currentTotp = current.mfa.methods.find((m) => m.name === "totp" && m.confirmed);
+				if (currentTotp?.lastUsedWindow !== void 0 && matchedCounter <= currentTotp.lastUsedWindow) {
+					replayDuringCas = true;
+					return null;
+				}
+				const set = { mfa: { methods: current.mfa.methods.map((m) => m.name === "totp" && m.confirmed ? {
+					...m,
+					lastUsedWindow: matchedCounter
+				} : m) } };
+				if (current.account.failedLoginAttempts > 0) set.account = { failedLoginAttempts: 0 };
+				return { set };
+			});
+			if (!replayDuringCas) return;
 		}
 		await this.incrementAndMaybeLock(username, user.account, "MFA_INVALID");
 	}
+	/**
+	* Verify a TOTP code against an UNCONFIRMED `totp` MFA method during initial
+	* enrollment. Differs from `verifyMfa`:
+	*   - Looks up unconfirmed (not confirmed) — confirmed totp uses verifyMfa.
+	*   - Throws MFA_INVALID on bad code; no failed-login counter bump (this is
+	*     pre-activation; lockout doesn't apply).
+	*   - No replay/lastUsedWindow tracking — confirmMfaMethod gates further use.
+	*
+	* 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");
+	}
 	getPasswordHasher() {
 		return this.hasher;
 	}
@@ -623,8 +696,9 @@ var UserService = class {
 	* 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 } });
+		await this.store.withCas(username, (user) => {
+			return { set: { trustedDevices: [...user.trustedDevices ?? [], record] } };
+		});
 	}
 	/**
 	* Returns true when the supplied token (a) signs against the user+ip with
@@ -751,48 +825,72 @@ var UserStoreMemory = class extends require_user_store.UserStore {
 	}
 	async create(data) {
 		if (this.store.has(data.username)) throw new require_user_store.UserAuthError("ALREADY_EXISTS", `User "${data.username}" already exists`);
-		this.store.set(data.username, structuredClone(data));
+		const cloned = structuredClone(data);
+		cloned.version = 0;
+		this.store.set(data.username, cloned);
 	}
 	async update(username, update) {
 		const user = this.store.get(username);
 		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);
+		user.version = (user.version ?? 0) + 1;
 		return true;
 	}
 	async delete(username) {
 		return this.store.delete(username);
 	}
+	async withCas(username, 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 patch = mutator(current);
+			if (patch === null) return;
+			if (await this.update(username, {
+				...patch,
+				expectedVersion: current.version ?? 0
+			})) return;
+		}
+		throw new require_user_store.UserAuthError("CAS_EXHAUSTED");
+	}
 };
 //#endregion
 //#region src/password/policies.ts
-const ppHasMinLength = (min = 8) => ({
-	rule: `v.length >= ${min}`,
+const ppHasMinLength = (min = 8) => definePasswordPolicy({
+	rule: (v, min) => v.length >= min,
+	args: [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}`,
+const ppHasUpperCase = (n = 1) => definePasswordPolicy({
+	rule: (v, n) => (v.match(/[A-Z]/g) || []).length >= n,
+	args: [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}`,
+const ppHasLowerCase = (n = 1) => definePasswordPolicy({
+	rule: (v, n) => (v.match(/[a-z]/g) || []).length >= n,
+	args: [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}`,
+const ppHasNumber = (n = 1) => definePasswordPolicy({
+	rule: (v, n) => (v.match(/\d/g) || []).length >= n,
+	args: [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}`,
+const ppHasSpecialChar = (n = 1) => definePasswordPolicy({
+	rule: (v, n) => (v.match(/[^A-Za-z0-9]/g) || []).length >= n,
+	args: [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`,
+const ppMaxRepeatedChars = (maxRepeated = 2) => definePasswordPolicy({
+	rule: (v, maxRepeated) => !new RegExp(`(.)\\1{${maxRepeated},}`).test(v),
+	args: [maxRepeated],
 	description: `No more than ${maxRepeated} consecutive repeated characters`,
 	errorMessage: `Password must not have more than ${maxRepeated} consecutive repeated characters`
 });
@@ -803,6 +901,7 @@ exports.UserAuthError = require_user_store.UserAuthError;
 exports.UserService = UserService;
 exports.UserStore = require_user_store.UserStore;
 exports.UserStoreMemory = UserStoreMemory;
+exports.definePasswordPolicy = definePasswordPolicy;
 exports.generateBackupCodePlaintext = generateBackupCodePlaintext;
 exports.generateMfaCode = generateMfaCode;
 exports.generateTotpCode = generateTotpCode;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { C as UserStoreUpdate, S as UserServiceConfig, _ as TotpConfig, a as LockoutConfig, b as UserAuthErrorType, c as MfaMethod, d as PasswordData, f as PasswordPolicyContext, g as PolicyCheckResult, h as PasswordPolicyInstance, i as LockStatus, l as MfaMethodInfo, m as PasswordPolicyEvalFn, n as AccountData, o as LoginResult, p as PasswordPolicyDef, r as DeepPartial, s as MfaData, t as UserStore, u as PasswordConfig, v as TransferablePolicy, x as UserCredentials, y as TrustedDeviceRecord } from "./user-store-VJPWNgdp.cjs";
+import { C as UserServiceConfig, S as UserCredentials, _ as PolicyCheckResult, a as LockStatus, b as TrustedDeviceRecord, c as MfaData, d as PasswordConfig, f as PasswordData, g as PasswordPolicyInstance, h as PasswordPolicyEvalFn, i as DeepPartial, l as MfaMethod, m as PasswordPolicyDef, n as WithCasOptions, o as LockoutConfig, p as PasswordPolicyContext, r as AccountData, s as LoginResult, t as UserStore, u as MfaMethodInfo, v as TotpConfig, w as UserStoreUpdate, x as UserAuthErrorType, y as TransferablePolicy } from "./user-store-B3EStUfT.cjs";
 
 //#region src/errors.d.ts
 declare class UserAuthError extends Error {
@@ -23,12 +23,39 @@ declare class PasswordHasher {
 //#endregion
 //#region src/password/policy.d.ts
 declare function normalizePolicies(policies?: (PasswordPolicyDef | PasswordPolicyInstance)[]): PasswordPolicy[];
+/**
+ * Helper that builds a `PasswordPolicyDef` from a real backend function plus
+ * its bound positional arguments. The function runs directly on the server
+ * (no sandbox, no eval); `serialized` is auto-derived as
+ * `(v) => (${rule.toString()})(v, ${args.map(JSON.stringify).join(', ')})`
+ * so the same constraint can ship to the frontend without re-implementing it.
+ *
+ * Bundler-safe: positional invocation means renamed parameters inside the
+ * function body stay consistent — the call site only relies on argument
+ * ORDER, not identifier preservation.
+ *
+ * Constraint on the rule body: it MUST reference only its own parameters.
+ * No closures over module imports, no `this`, no helpers from outer scope —
+ * `rule.toString()` ships the literal source; any free identifier the
+ * frontend cannot resolve breaks transferability. (`String.prototype.match`,
+ * regex literals, plain JS globals are fine.)
+ *
+ * Omit `args` to mark the policy backend-only — `serialized` stays
+ * `undefined` and `transferable` is false; frontend pre-validation skips it
+ * and only the server check enforces the rule.
+ */
+declare function definePasswordPolicy<A extends readonly unknown[]>(opts: {
+  rule: (v: string, ...args: A) => boolean | Promise<boolean>;
+  args?: A;
+  description?: string;
+  errorMessage?: string;
+}): PasswordPolicyDef;
 declare class PasswordPolicy implements PasswordPolicyInstance {
-  readonly rule: string | PasswordPolicyEvalFn;
+  readonly rule: PasswordPolicyEvalFn;
+  readonly serialized?: string;
   readonly description: string;
   readonly errorMessage: string;
   constructor(config: PasswordPolicyDef);
-  protected _evalFn: PasswordPolicyEvalFn;
   evaluate(password: string, context?: PasswordPolicyContext): boolean | Promise<boolean>;
   get transferable(): boolean;
 }
@@ -50,6 +77,14 @@ declare class UserService<T extends object = object> {
   protected readonly hasher: PasswordHasher;
   constructor(store: UserStore<T>, config?: UserServiceConfig);
   /**
+   * 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
+   * enumeration, so the failure is silent client-side.
+   *
    * @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.
@@ -67,7 +102,7 @@ declare class UserService<T extends object = object> {
   /**
    * 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.
+   * invite workflow's `auth/invite/cancel` to revoke a pending invitation.
    */
   deleteUser(username: string): Promise<void>;
   /**
@@ -102,16 +137,13 @@ declare class UserService<T extends object = object> {
   /**
    * 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.
+   * 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.
    */
   consumeBackupCode(username: string, code: string): Promise<boolean>;
   /**
@@ -121,6 +153,18 @@ declare class UserService<T extends object = object> {
    * total tries across BOTH factors, not `2 * threshold`.
    */
   verifyMfa(username: string, code: string, config?: TotpConfig): Promise<void>;
+  /**
+   * Verify a TOTP code against an UNCONFIRMED `totp` MFA method during initial
+   * enrollment. Differs from `verifyMfa`:
+   *   - Looks up unconfirmed (not confirmed) — confirmed totp uses verifyMfa.
+   *   - Throws MFA_INVALID on bad code; no failed-login counter bump (this is
+   *     pre-activation; lockout doesn't apply).
+   *   - No replay/lastUsedWindow tracking — confirmMfaMethod gates further use.
+   *
+   * Throws: NOT_FOUND if user missing; MFA_NOT_CONFIGURED if no unconfirmed
+   * totp method; MFA_INVALID on wrong code.
+   */
+  verifyTotpSetupCode(username: string, code: string, config?: TotpConfig): Promise<void>;
   getPasswordHasher(): PasswordHasher;
   getConfig(): Readonly<ResolvedConfig>;
   /**
@@ -176,6 +220,7 @@ declare class UserStoreMemory<T extends object = object> extends UserStore<T> {
   create(data: UserCredentials & T): Promise<void>;
   update(username: string, update: UserStoreUpdate): Promise<boolean>;
   delete(username: string): Promise<boolean>;
+  withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
 //#region src/password/policies.d.ts
@@ -190,7 +235,12 @@ declare const ppMaxRepeatedChars: (maxRepeated?: number) => PasswordPolicyDef;
 declare function generateTotpSecret(bytes?: number): string;
 declare function generateTotpUri(secret: string, issuer: string, account: string, config?: Pick<TotpConfig, "period" | "digits">): string;
 declare function generateTotpCode(secret: string, config?: TotpConfig): string;
-declare function verifyTotpCode(secret: string, code: string, config?: TotpConfig): boolean;
+/**
+ * Returns the matched HOTP counter when `code` is valid within the verification
+ * window, otherwise `null`. Returning the counter (not a bool) lets the caller
+ * persist `lastUsedWindow` and reject same-window replays (RFC 6238 §5.2 SHOULD).
+ */
+declare function verifyTotpCode(secret: string, code: string, config?: TotpConfig): number | null;
 declare function generateMfaCode(length?: number): string;
 //#endregion
 //#region src/mfa/codes.d.ts
@@ -230,4 +280,4 @@ declare function maskPhone(phone: string): string;
 declare function maskMfaValue(method: MfaMethod): string;
 declare function setAtPath(obj: object, path: string, value: unknown): void;
 //#endregion
-export { type AccountData, type DeepPartial, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { type AccountData, type DeepPartial, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };