@aooth/user 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -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-Dbc9unW3.mjs";
+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-C1lxahSB.mjs";
 
 //#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 };

package/dist/index.mjs

@@ -1,6 +1,5 @@
-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 { 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-BaBmH13V.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
@@ -145,6 +144,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;
@@ -152,14 +156,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 && timingSafeEqual(expected, submitted)) matched = true;
+		const stepCounter = counter + i;
+		const expected = Buffer.from(hotpCode(key, stepCounter, digits), "utf8");
+		if (expected.length === submitted.length && timingSafeEqual(expected, submitted)) matchedCounter = stepCounter;
 	}
-	return matched;
+	return matchedCounter;
 }
 function generateMfaCode(length = 6) {
 	return generateSecureRandom(length, "0123456789");
@@ -268,33 +273,57 @@ var PasswordHasher = class {
 };
 //#endregion
 //#region src/password/policy.ts
-const fnPool = new 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
@@ -338,6 +367,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.
@@ -417,7 +454,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 UserAuthError("NOT_FOUND");
@@ -490,30 +527,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 UserAuthError("MFA_NOT_CONFIGURED");
+			return { set: { mfa: { methods } } };
 		});
-		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);
@@ -556,24 +595,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.
@@ -587,12 +629,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 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 UserAuthError("MFA_NOT_CONFIGURED");
+		if (verifyTotpCode(totp.value, code, config) === null) throw new UserAuthError("MFA_INVALID");
+	}
 	getPasswordHasher() {
 		return this.hasher;
 	}
@@ -622,8 +695,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
@@ -750,50 +824,74 @@ var UserStoreMemory = class extends UserStore {
 	}
 	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));
+		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) deepMerge(user, update.set);
 		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) 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 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
 //#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`
 });
 //#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 };
+export { PasswordHasher, PasswordPolicy, UserAuthError, UserService, UserStore, UserStoreMemory, definePasswordPolicy, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };

package/dist/{user-store-Dbc9unW3.d.mts → user-store-B3EStUfT.d.cts}

@@ -2,6 +2,14 @@
 interface UserCredentials {
   id: string;
   username: string;
+  /**
+   * Server-managed optimistic-concurrency counter. Bumped by `UserStore.update`
+   * on every successful write; checked against `UserStoreUpdate.expectedVersion`
+   * for CAS. Callers MUST NOT write it directly — atscript-db rejects direct
+   * writes with `DbError("VERSION_COLUMN_WRITE")`. Optional in TS so pre-OCC
+   * fixtures keep compiling; the store seeds `0` on insert.
+   */
+  version?: number;
   password: PasswordData;
   account: AccountData;
   mfa: MfaData;
@@ -49,8 +57,8 @@ interface AccountData {
    * True while the user record exists from an admin-issued invite but the
    * invitee has not yet accepted (set password + activate). Used by
    * `InviteWorkflow` to gate the accept tail, reject duplicate invites, and
-   * power `auth.reInvite` / `auth.cancelInvite`. Absent / `false` once the
-   * invite has been accepted.
+   * power `auth/invite/resend` / `auth/invite/cancel`. Absent / `false` once
+   * the invite has been accepted.
    */
   pendingInvitation?: boolean;
 }
@@ -69,6 +77,12 @@ interface MfaMethod {
   confirmed: boolean;
   /** The method's value: email address, phone number, or TOTP secret */
   value: string;
+  /**
+   * Last HOTP counter accepted for this method (TOTP only). Server-managed
+   * replay guard — `verifyMfa` rejects any code whose matched counter is
+   * `<= lastUsedWindow`. Never written from user-facing input.
+   */
+  lastUsedWindow?: number;
 }
 interface UserServiceConfig {
   password?: PasswordConfig;
@@ -107,7 +121,23 @@ interface LockoutConfig {
   duration?: number;
 }
 interface PasswordPolicyDef {
-  rule: string | PasswordPolicyEvalFn;
+  /**
+   * Backend evaluator. Function only — executed directly with no sandbox.
+   * String rules were removed: `@prostojs/ftring`'s sandbox does NOT block
+   * prototype-chain escapes (`constructor.constructor("return process")()`,
+   * `__proto__.x = ...`), so accepting strings was an RCE vector. Authors
+   * use `definePasswordPolicy({ rule, args })` to get both this fn AND the
+   * serialized form for free.
+   */
+  rule: PasswordPolicyEvalFn;
+  /**
+   * Pre-baked function-literal text shipped to clients for cross-tier
+   * validation via `getTransferablePolicies()`. Authored as
+   * `(v) => (${ruleSource})(v, ${args.map(JSON.stringify).join(', ')})` by
+   * `definePasswordPolicy`. Absent → the policy is backend-only (frontend
+   * skips it; server-side check remains authoritative).
+   */
+  serialized?: string;
   description?: string;
   errorMessage?: string;
 }
@@ -127,8 +157,15 @@ interface UserStoreUpdate {
   set?: DeepPartial<UserCredentials>;
   /** Dot-paths to atomically increment: e.g. {'account.failedLoginAttempts': 1} */
   inc?: Record<string, number>;
+  /**
+   * Optimistic concurrency control: when supplied, the store applies the
+   * update iff the row's current `version` equals this value. On mismatch
+   * the store returns `false` (same shape as "not found") and does NOT
+   * mutate. Service callers treat both states as "stale read, retry".
+   */
+  expectedVersion?: number;
 }
-type UserAuthErrorType = "NOT_FOUND" | "ALREADY_EXISTS" | "LOCKED" | "INACTIVE" | "INVALID_CREDENTIALS" | "POLICY_VIOLATION" | "PASSWORDS_MISMATCH" | "PASSWORD_IN_HISTORY" | "MFA_REQUIRED" | "MFA_INVALID" | "MFA_NOT_CONFIGURED";
+type UserAuthErrorType = "NOT_FOUND" | "ALREADY_EXISTS" | "LOCKED" | "INACTIVE" | "INVALID_CREDENTIALS" | "POLICY_VIOLATION" | "PASSWORDS_MISMATCH" | "PASSWORD_IN_HISTORY" | "MFA_REQUIRED" | "MFA_INVALID" | "MFA_NOT_CONFIGURED" | "CAS_EXHAUSTED";
 interface LoginResult<T extends object = object> {
   user: UserCredentials & T;
   /** Whether MFA verification is required before granting full access */
@@ -171,6 +208,15 @@ interface TotpConfig {
 }
 //#endregion
 //#region src/store/user-store.d.ts
+interface WithCasOptions {
+  /**
+   * Total attempts (1 initial + retries). Default `2` = one retry. Each
+   * attempt re-reads the row so the mutator runs against fresh state — that
+   * is the whole point of retry under OCC. Bump for high-contention writers
+   * (bulk admin scripts); leave at default for normal per-user request flow.
+   */
+  maxAttempts?: number;
+}
 declare abstract class UserStore<T extends object = object> {
   abstract exists(username: string): Promise<boolean>;
   abstract findByUsername(username: string): Promise<(UserCredentials & T) | null>;
@@ -179,9 +225,22 @@ declare abstract class UserStore<T extends object = object> {
   /**
    * Hard-delete the row. Returns `true` when a row was removed, `false` when
    * the username was not found. Used by `UserService.deleteUser` (and in turn
-   * by the invite workflow's `auth.cancelInvite` step).
+   * by the invite workflow's `auth/invite/cancel` step).
    */
   abstract delete(username: string): Promise<boolean>;
+  /**
+   * Run a read-modify-write cycle under optimistic concurrency. Each attempt
+   * fetches the current row, calls `mutator` with it, and applies the returned
+   * patch under CAS (`expectedVersion = current.version`). On CAS miss the
+   * cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null` to
+   * exit early without writing — used for "race-loser detects nothing left to
+   * do" paths (e.g. the backup code was already consumed by the winner).
+   *
+   * Throws `UserAuthError("NOT_FOUND")` when no row matches `username`, or
+   * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors
+   * thrown from inside `mutator` propagate immediately without retry.
+   */
+  abstract withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
-export { UserStoreUpdate as C, UserServiceConfig as S, TotpConfig as _, LockoutConfig as a, UserAuthErrorType as b, MfaMethod as c, PasswordData as d, PasswordPolicyContext as f, PolicyCheckResult as g, PasswordPolicyInstance as h, LockStatus as i, MfaMethodInfo as l, PasswordPolicyEvalFn as m, AccountData as n, LoginResult as o, PasswordPolicyDef as p, DeepPartial as r, MfaData as s, UserStore as t, PasswordConfig as u, TransferablePolicy as v, UserCredentials as x, TrustedDeviceRecord as y };
+export { UserServiceConfig as C, UserCredentials as S, PolicyCheckResult as _, LockStatus as a, TrustedDeviceRecord as b, MfaData as c, PasswordConfig as d, PasswordData as f, PasswordPolicyInstance as g, PasswordPolicyEvalFn as h, DeepPartial as i, MfaMethod as l, PasswordPolicyDef as m, WithCasOptions as n, LockoutConfig as o, PasswordPolicyContext as p, AccountData as r, LoginResult as s, UserStore as t, MfaMethodInfo as u, TotpConfig as v, UserStoreUpdate as w, UserAuthErrorType as x, TransferablePolicy as y };

package/dist/{user-store-CdWrTeqR.cjs → user-store-BPZVAboN.cjs}

@@ -11,7 +11,8 @@ const defaultMessages = {
 	PASSWORD_IN_HISTORY: "Password was recently used",
 	MFA_REQUIRED: "Multi-factor authentication is required",
 	MFA_INVALID: "Invalid MFA code",
-	MFA_NOT_CONFIGURED: "MFA method is not configured"
+	MFA_NOT_CONFIGURED: "MFA method is not configured",
+	CAS_EXHAUSTED: "Update conflict — please retry"
 };
 var UserAuthError = class extends Error {
 	name = "UserAuthError";

package/dist/{user-store-B_l9vqlQ.mjs → user-store-BaBmH13V.mjs}

@@ -11,7 +11,8 @@ const defaultMessages = {
 	PASSWORD_IN_HISTORY: "Password was recently used",
 	MFA_REQUIRED: "Multi-factor authentication is required",
 	MFA_INVALID: "Invalid MFA code",
-	MFA_NOT_CONFIGURED: "MFA method is not configured"
+	MFA_NOT_CONFIGURED: "MFA method is not configured",
+	CAS_EXHAUSTED: "Update conflict — please retry"
 };
 var UserAuthError = class extends Error {
 	name = "UserAuthError";