@db3.ai/app 0.1.0-beta.1 → 0.1.0-beta.4

package/src/apps/contracts/InstalledApps.ts

@@ -0,0 +1,2 @@
+/** Generated declaration merging target. Properties are optional because installation is runtime state. */
+export interface InstalledApps {}

package/src/apps/contracts/index.ts

@@ -0,0 +1,11 @@
+export type { AppManifest, AppMenuItem } from './AppManifest';
+export type { AppDefinition, AppDefinitions, AppServices, AppStartContext } from './AppDefinition';
+export type { AppRoute, AppRouteContext } from './AppRoute';
+export type { AppDescription, AppInstallationState, AppClientDefinition } from './AppDescription';
+export type { DiscoveredApp } from './DiscoveredApp';
+export type { InstalledApps } from './InstalledApps';
+export type { AppAction } from './AppAction';
+export type { AppNavigation } from './AppNavigation';
+export type { AppNavigationBadge } from './AppNavigationBadge';
+export type { AppNavigationContext } from './AppNavigationContext';
+export type { AppNavigationResult } from './AppNavigationResult';

package/src/apps/defineApp.ts

@@ -0,0 +1,10 @@
+import type { AppDefinition } from './contracts';
+
+/**
+ * Defines an app without installing, connecting or registering it globally.
+ * @param definition - Public service, metadata and app-owned contributions.
+ * @returns Definition preserving the inferred public service type.
+ */
+export function defineApp<TService>(definition: AppDefinition<TService>): AppDefinition<TService> {
+	return definition;
+}

package/src/apps/discoverApps.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import type { DiscoveredApp } from './contracts';
+import { validateAppDefinitions } from './validateAppDefinitions';
+
+/** Discovers local apps and opted-in direct npm dependencies without executing their code. */
+export function discoverApps(directory: string): DiscoveredApp[] {
+	const found: DiscoveredApp[] = [];
+	const root = join(directory, 'apps');
+	if (existsSync(root)) {
+		for (const item of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+			if (item.isDirectory() && existsSync(join(root, item.name, 'manifest.json'))) found.push(readApp(join(root, item.name), item.name));
+		}
+	}
+	const packageFile = join(directory, 'package.json');
+	if (existsSync(packageFile)) {
+		const host = JSON.parse(readFileSync(packageFile, 'utf8'));
+		const require = createRequire(packageFile);
+		for (const name of Object.keys({ ...host.dependencies, ...host.optionalDependencies }).sort()) {
+			let file: string;
+			try { file = require.resolve(`${name}/package.json`); }
+			catch { continue; } // Packages must export package.json to opt into metadata-only discovery.
+			const metadata = JSON.parse(readFileSync(file, 'utf8'));
+			if (metadata.db3?.app !== true) continue;
+			found.push(readApp(dirname(file), basename(name), name, metadata.db3));
+		}
+	}
+	const definitions: Record<string, any> = Object.create(null);
+	for (const app of found) {
+		const id = app.manifest.id;
+		if (Object.hasOwn(definitions, id)) throw new Error(`Duplicate app "${id}". Keep either the local folder or the npm package.`);
+		definitions[id] = { manifest: app.manifest, create: () => undefined };
+	}
+	validateAppDefinitions(definitions, [...Object.getOwnPropertyNames(Object.prototype), 'then', 'toJSON']);
+	return found;
+}
+
+/** Reads one conventional root manifest and resolves entries contained in that app's directory. */
+function readApp(directory: string, id: string, packageName?: string, entries?: { entry?: string; client?: string }): DiscoveredApp {
+	const manifest = JSON.parse(readFileSync(join(directory, 'manifest.json'), 'utf8'));
+	if (manifest.id !== undefined && manifest.id !== id) throw new Error(`App folder "${id}" disagrees with manifest identifier "${manifest.id}".`);
+	const entry = containedEntry(directory, entries?.entry ?? 'App.ts');
+	const clientPath = entries?.client ?? 'client/index.ts';
+	const client = containedEntry(directory, clientPath);
+	return { manifest: { ...manifest, id }, directory, entry, ...(existsSync(client) ? { client } : {}), ...(packageName ? { packageName } : {}) };
+}
+
+/** Rejects entry paths that escape the package or local app root. */
+function containedEntry(directory: string, entry: string): string {
+	if (typeof entry !== 'string' || isAbsolute(entry)) throw new Error('App entries must be relative paths.');
+	const target = resolve(directory, entry);
+	const path = relative(directory, target);
+	if (!path || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) throw new Error('App entries must remain inside their app directory.');
+	return target;
+}

package/src/apps/fastify.ts

@@ -0,0 +1 @@
+export { registerAppRoutes } from './registerAppRoutes';

package/src/apps/index.ts

@@ -0,0 +1,7 @@
+export * from './contracts';
+export { defineApp } from './defineApp';
+export { Apps } from './Apps';
+export { AppRouteError } from './AppRouteError';
+export { AppService } from './AppService';
+export { discoverApps } from './discoverApps';
+export { writeAppTypes } from './writeAppTypes';

package/src/apps/normalizeAppNavigation.ts

@@ -0,0 +1,29 @@
+import type * as apps from './contracts';
+
+/** Validates a contribution and copies only supported, browser-safe fields into the response. */
+export function normalizeAppNavigation(value: apps.AppNavigation): apps.AppNavigation {
+	if (!value || !Array.isArray(value.items)) throw new Error('Navigation must provide an items array.');
+	const ids = new Set<string>();
+	return {
+		...details(value),
+		items: value.items.map(item => {
+			if (!item || typeof item.id !== 'string' || !item.id.trim() || ids.has(item.id) || typeof item.label !== 'string' || !item.label.trim() || typeof item.path !== 'string' || !/^(?:[a-z0-9-]+(?:\/[a-z0-9-]+)*)?$/.test(item.path)) throw new Error('Invalid or duplicate navigation item.');
+			ids.add(item.id);
+			return { id: item.id, label: item.label, path: item.path, ...details(item) };
+		}),
+	};
+}
+
+/** Copies optional display information without passing through arbitrary provider data. */
+function details(value: { description?: string; badge?: apps.AppNavigationBadge }): Pick<apps.AppNavigation, 'description' | 'badge'> {
+	const result: Pick<apps.AppNavigation, 'description' | 'badge'> = {};
+	if (value.description !== undefined) {
+		if (typeof value.description !== 'string') throw new Error('Navigation descriptions must be plain text.');
+		result.description = value.description;
+	}
+	if (value.badge !== undefined) {
+		if (!value.badge || !Number.isSafeInteger(value.badge.count) || value.badge.count < 0 || typeof value.badge.label !== 'string' || !value.badge.label.trim()) throw new Error('Navigation badges require a non-negative integer count and an accessible label.');
+		result.badge = { count: value.badge.count, label: value.badge.label };
+	}
+	return result;
+}

package/src/apps/registerAppRoutes.ts

@@ -0,0 +1,48 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { Apps } from './Apps';
+import { AppRouteError } from './AppRouteError';
+
+/** Mounts dynamic app routes behind mandatory host authorization; newly installed apps become reachable immediately. */
+export function registerAppRoutes(server: FastifyInstance, apps: Apps<any>, authorize: (request: FastifyRequest, appId: string) => Promise<{ id: string }>): void {
+	for (const url of ['/api/apps/:appId', '/api/apps/:appId/*']) {
+		server.route({
+			method: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'], url,
+			/** Drains in-flight requests before lifecycle changes and passes only a verified actor to app code. */
+			handler: async (request, reply) => {
+				try {
+					return await apps.run(async () => {
+						const { appId, '*': suffix = '' } = request.params as Record<string, string>;
+						const service = apps.get(appId);
+						if (service === undefined) return reply.code(404).send({ message: 'App is unavailable.' });
+						const candidates = apps.routes().filter(item => item.appId === appId && item.route.method === request.method).sort((a, b) => (a.route.path.match(/:/g)?.length ?? 0) - (b.route.path.match(/:/g)?.length ?? 0));
+						for (const { route } of candidates) {
+							const params = matchPath(route.path, `/${suffix}`);
+							if (!params) continue;
+							const actor = await authorize(request, appId);
+							if (!actor?.id) throw new AppRouteError(401, 'Please sign in.');
+							const result = await route.handle({ service, actor, body: request.body, params, query: request.query as Record<string, unknown> });
+							return reply.code(route.status ?? 200).send(result);
+						}
+						return reply.code(404).send({ message: 'App route not found.' });
+					});
+				} catch (error) {
+					if (error instanceof AppRouteError) return reply.code(error.statusCode).send({ message: error.message });
+					throw error;
+				}
+			},
+		});
+	}
+}
+
+/** Matches validated route segments and captures named parameters without evaluating arbitrary regular expressions. */
+function matchPath(pattern: string, path: string): Record<string, string> | undefined {
+	const expected = pattern.split('/');
+	const actual = path.split('/');
+	if (expected.length !== actual.length) return;
+	const params: Record<string, string> = Object.create(null);
+	for (let index = 0; index < expected.length; index++) {
+		if (expected[index].startsWith(':') && actual[index]) params[expected[index].slice(1)] = actual[index];
+		else if (expected[index] !== actual[index]) return;
+	}
+	return params;
+}

package/src/apps/validateAppDefinitions.ts

@@ -0,0 +1,52 @@
+import type * as apps from './contracts';
+import { normalizeAppNavigation } from './normalizeAppNavigation';
+import { isQueueableJobClass, queueableJobName } from '../queue';
+
+/** Validates names, contribution ownership and dependency order before any app code is started. */
+export function validateAppDefinitions(definitions: apps.AppDefinitions, reserved: readonly string[]): string[] {
+	const ids = Object.keys(definitions);
+	const tables = new Set<string>();
+	for (const id of ids) {
+		const definition = definitions[id];
+		const manifest = definition.manifest;
+		if (!/^[a-z][a-z0-9_]{0,39}$/.test(id) || /^db3(?:_|$)/.test(id) || reserved.includes(id) || manifest.id !== id) throw new Error(`Invalid or reserved app identifier "${id}".`);
+		if (!manifest.name?.trim() || !/^\d+\.\d+\.\d+$/.test(manifest.version) || !Number.isSafeInteger(manifest.apiVersion ?? 1) || (manifest.apiVersion ?? 1) < 1) throw new Error(`Invalid app manifest for "${id}"; use a stable x.y.z release and a positive API generation.`);
+		if (typeof definition.create !== 'function') throw new Error(`App "${id}" must create a public service.`);
+		const jobs = new Set<string>();
+		for (const Job of definition.jobs ?? []) {
+			if (!isQueueableJobClass(Job) || !Job.jobName?.startsWith(`${id}.`) || jobs.has(queueableJobName(Job))) throw new Error(`Invalid or duplicate job in "${id}"; declare a stable ${id}. jobName.`);
+			jobs.add(queueableJobName(Job));
+		}
+		for (const Model of definition.database?.models ?? []) {
+			if (!Model.table.startsWith(`${id}_`) || tables.has(Model.table)) throw new Error(`App "${id}" cannot own table "${Model.table}".`);
+			tables.add(Model.table);
+		}
+		const paths = new Set<string>();
+		for (const route of definition.routes ?? []) {
+			const key = `${route.method} ${route.path}`;
+			if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(route.method) || !/^\/(?:[a-zA-Z0-9_:-]+(?:\/[a-zA-Z0-9_:-]+)*)?$/.test(route.path) || paths.has(key) || typeof route.handle !== 'function') throw new Error(`Invalid or duplicate route "${key}" in "${id}".`);
+			paths.add(key);
+		}
+		try { normalizeAppNavigation({ items: manifest.navigation ?? [] }); }
+		catch { throw new Error(`Invalid navigation in "${id}".`); }
+		for (const [dependency, generation] of Object.entries({ ...manifest.requires, ...manifest.optional })) {
+			if (!/^[a-z][a-z0-9_]{0,39}$/.test(dependency) || reserved.includes(dependency) || dependency === id || !Number.isSafeInteger(generation) || generation < 1) throw new Error(`Invalid dependency "${dependency}" in "${id}".`);
+			if (manifest.requires?.[dependency] !== undefined && manifest.optional?.[dependency] !== undefined) throw new Error(`Dependency "${dependency}" is both required and optional in "${id}".`);
+		}
+	}
+	const visiting = new Set<string>();
+	const ordered = new Set<string>();
+	/** Topologically orders available dependencies and rejects composition cycles. */
+	function visit(id: string): void {
+		if (ordered.has(id)) return;
+		if (visiting.has(id)) throw new Error(`App dependency cycle at "${id}".`);
+		visiting.add(id);
+		for (const dependency of Object.keys({ ...definitions[id].manifest.requires, ...definitions[id].manifest.optional })) {
+			if (definitions[dependency]) visit(dependency);
+		}
+		visiting.delete(id);
+		ordered.add(id);
+	}
+	ids.forEach(visit);
+	return [...ordered];
+}

package/src/apps/vite.ts

@@ -0,0 +1 @@
+export { appsPlugin } from './appsPlugin';

package/src/apps/writeAppTypes.ts

@@ -0,0 +1,14 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { discoverApps } from './discoverApps';
+
+/** Regenerates optional app().social types from discovery during development and builds, without loading server code. */
+export async function writeAppTypes(directory: string): Promise<void> {
+	const target = join(directory, '.db3/apps.d.ts');
+	const properties = discoverApps(directory).map(app => {
+		const specifier = app.packageName ?? `./${relative(dirname(target), app.entry).replaceAll('\\', '/').replace(/\.ts$/, '.js')}`;
+		return `\t\treadonly ${app.manifest.id}?: InstanceType<typeof import(${JSON.stringify(specifier)}).default>;`;
+	});
+	await mkdir(dirname(target), { recursive: true });
+	await writeFile(target, `// Generated by DB3 app discovery. Do not edit.\nimport '@db3.ai/app/apps/contracts';\ndeclare module '@db3.ai/app/apps/contracts' {\n\tinterface InstalledApps {\n${properties.join('\n')}\n\t}\n}\n`);
+}

package/src/auth/Auth.ts

@@ -1,4 +1,5 @@
 import { ActiveRecord, type Database } from '../db';
+import type { Knex } from 'knex';
 import { isPromiseLike } from '@db3.ai/pure';
 import type { Config } from '../config';
 import { AuthProvider, PASSWORD_AUTH_PROVIDER } from './AuthProvider';
@@ -649,6 +650,8 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 
 	/**
 	 * Changes a user's password provider after verifying the current password.
+	 * Password replacement, recovery-link invalidation and revocation of every
+	 * bearer session (including the current session) commit together.
 	 *
 	 * @param user - User whose password should change.
 	 * @param currentPassword - Current plaintext password for verification.
@@ -660,13 +663,19 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 		currentPassword: string,
 		nextPassword: string,
 	): Promise<boolean> {
-		return ActiveRecord.withDb(this.db.knex, () => {
-			return this.passwordProvider().changePassword(
-				user,
-				currentPassword,
-				nextPassword,
-			);
-		});
+		const userId = this.userPrimaryKey(user);
+		if (!userId) return false;
+
+		const changed = await this.db.knex.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+			const lockedUser = await this.#lockIdentity(userId, transaction);
+			if (!lockedUser) return false;
+			if (!await this.passwordProvider().changePassword(lockedUser, currentPassword, nextPassword)) return false;
+			await this.#invalidatePasswordRecovery(userId, transaction);
+			return true;
+		}));
+
+		if (changed) this.#forgetRevokedUser(userId);
+		return changed;
 	}
 
 	/**
@@ -762,6 +771,8 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 
 	/**
 	 * Resets the password provider using a valid password reset token.
+	 * Serializes recovery for an account and atomically invalidates every existing
+	 * session and recovery link. Failed validation leaves credentials unchanged.
 	 *
 	 * @param input - Reset token, new password, and optional identity value.
 	 * @returns Identity whose password changed, or null when redemption fails.
@@ -782,25 +793,57 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 			return null;
 		}
 
-		const user = await this.IdentityModel.findByPk(
-			tokenRecord.userId,
-			this.db.knex,
-		);
-
-		if (!user) {
-			return null;
+		if (!tokenRecord.userId) return null;
+		const user = await this.db.knex.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+			const lockedUser = await this.#lockIdentity(tokenRecord.userId!, transaction);
+			if (!lockedUser) return null;
+
+			// A locking read sees a competing redemption's committed state after
+			// waiting for the account lock, including under repeatable-read SQL.
+			const row = await this.PasswordResetTokenModel.query(transaction)
+				.where('id', tokenRecord.id).toKnex().forUpdate().first();
+			const current = row ? this.PasswordResetTokenModel.fromDb(row, transaction) : null;
+			if (!current?.isUsable() || !await this.passwordResetIdentityMatches(input, lockedUser)) return null;
+
+			await this.passwordProvider().recoverPassword(lockedUser, input.password);
+			await this.#invalidatePasswordRecovery(tokenRecord.userId!, transaction);
+			return lockedUser;
+		}));
+
+		if (user) {
+			user.setDb(this.db.knex);
+			this.#forgetRevokedUser(this.userPrimaryKey(user)!);
 		}
+		return user;
+	}
 
-		if (!await this.passwordResetIdentityMatches(input, user)) {
-			return null;
-		}
+	/** Locks the account row to serialize concurrent password replacements. */
+	async #lockIdentity(userId: string, transaction: Knex.Transaction): Promise<TIdentity | null> {
+		const row = await this.IdentityModel.query(transaction)
+			.where(this.IdentityModel.primaryKey, userId).toKnex().forUpdate().first();
+		return row ? this.IdentityModel.fromDb(row, transaction) as TIdentity : null;
+	}
 
-		await this.setPasswordProvider(user, input.password);
+	/** Invalidates recovery links and sessions within the password transaction. */
+	async #invalidatePasswordRecovery(userId: string, transaction: Knex.Transaction): Promise<void> {
+		await this.PasswordResetTokenModel.query(transaction)
+			.where('userId', userId).whereNull('usedAt').patch({ usedAt: new Date() });
+		await this.#revokeTokens(userId, transaction);
+	}
 
-		tokenRecord.markUsed();
-		await tokenRecord.save();
+	/** Applies session revocation on the owning connection or password transaction. */
+	async #revokeTokens(userId: string, connection: Knex): Promise<number> {
+		return this.TokenModel.query(connection)
+			.where('userId', userId).whereNull('revokedAt').patch({ revokedAt: new Date() });
+	}
 
-		return user;
+	/** Discards cached bearer authentication after committed account revocation. */
+	#forgetRevokedUser(userId: string): void {
+		if (this.requestContext?.active) {
+			const key = `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}.revision`;
+			this.requestContext.set(key, (this.requestContext.get<number>(key) ?? 0) + 1);
+		}
+		if (this.user && this.userPrimaryKey(this.user) === userId) this.logout();
 	}
 
 	/**
@@ -897,6 +940,26 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 		return tokens.filter(token => token.isActive());
 	}
 
+	/**
+	 * Revokes all bearer sessions for an account, including the current device.
+	 *
+	 * Apps must authorize the supplied account before calling this method. Tokens
+	 * are rejected on subsequent requests; already-running requests can finish.
+	 * Revoked rows are retained for audit. New sign-ins remain possible.
+	 *
+	 * @param user - Authorized account whose sessions should end.
+	 * @returns Number of previously unrevoked token rows changed, including expired rows.
+	 * @example
+	 * await app.auth.revokeAllTokens(authenticatedUser);
+	 */
+	async revokeAllTokens(user: TIdentity): Promise<number> {
+		const userId = this.userPrimaryKey(user);
+		if (!userId) return 0;
+		const count = await this.#revokeTokens(userId, this.db.knex);
+		this.#forgetRevokedUser(userId);
+		return count;
+	}
+
 	/**
 	 * Revokes one bearer session owned by a user.
 	 *
@@ -947,7 +1010,9 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 	 * @returns Request-context cache key.
 	 */
 	private tokenContextKey(tokenHash: string): string {
-		return `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}.${tokenHash}`;
+		const prefix = `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}`;
+		const revision = this.requestContext?.get<number>(`${prefix}.revision`) ?? 0;
+		return `${prefix}.${revision}.${tokenHash}`;
 	}
 
 	/**
@@ -1299,7 +1364,8 @@ export class Auth<TIdentity extends UserIdentity = UserIdentity> {
 			return true;
 		}
 
-		const inputUser = await this.findIdentity(input);
+		const inputUser = await this.IdentityModel.query()
+			.where(identityField, inputIdentity).first();
 
 		return inputUser?.get(this.IdentityModel.primaryKey) === user.get(this.IdentityModel.primaryKey);
 	}

package/src/auth/PasswordLoginAttempt.ts

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import { ActiveRecord, type FieldBuilder } from '../db';
+
+/**
+ * Durable failed-password state for any submitted identity, known or unknown.
+ *
+ * The unique normalized identity digest provides a database-wide serialization
+ * point without requiring an account. The normalized submitted email is also
+ * retained so operators can investigate attempts against known or unknown users.
+ * This table is intentionally independent of users and authentication providers.
+ */
+export class PasswordLoginAttempt extends ActiveRecord {
+	static override table = 'auth_password_login_attempts';
+
+	/** Defines the identity key, failure counter and persistent suspension. */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+			identityHash: field.string({ column: 'identity_hash', required: true, unique: true, length: 64, maxLength: 64, comment: 'SHA-256 of the normalized submitted identity; not tied to account existence.' }),
+			identity: field.string({ length: 255, maxLength: 255, comment: 'Normalized submitted email or configured identity; null for legacy digest-only rows until their next attempt.' }),
+			failedAttempts: field.integer({ column: 'failed_attempts', required: true, unsigned: true, min: 0, default: 0, comment: 'Consecutive wrong passwords for this identity.' }),
+			suspendedAt: field.timestamp({ column: 'suspended_at', comment: 'When password recovery became required; no automatic expiry.' }),
+			suspensionId: field.string({ column: 'suspension_id', length: 36, maxLength: 36, comment: 'Unique suspension occurrence; prevents delayed recovery notices from referring to a later suspension.' }),
+			createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+			updatedAt: field.timestamp({ column: 'updated_at', auto: 'both', index: true, comment: 'Latest password sign-in or recovery activity, including refused suspended attempts.' }),
+		};
+	}
+
+	declare id: string | null;
+	declare identityHash: string;
+	/** Readable submitted identity, populated on the next attempt for legacy rows. */
+	declare identity: string | null;
+	declare failedAttempts: number;
+	declare suspendedAt: Date | null;
+	/** Unique occurrence identifier, cleared only by verified password recovery. */
+	declare suspensionId: string | null;
+
+	/**
+	 * Derives an exact stable key unaffected by the database's email collation.
+	 * @param identity - Submitted email or configured password identity.
+	 * @returns SHA-256 of the trimmed, lowercase identity.
+	 */
+	static identityKey(identity: string): string {
+		return createHash('sha256').update(identity.trim().toLowerCase()).digest('hex');
+	}
+
+	/**
+	 * Serializes one verification or recovery with every operation for this identity.
+	 *
+	 * The unique-key upsert handles concurrent first attempts. Locking reads see
+	 * the latest committed state, including under repeatable-read isolation.
+	 * Nested use during recovery participates through a transaction savepoint.
+	 *
+	 * Records the normalized identity and latest activity even when already suspended.
+	 * @param identity - Password identity, whether or not registered.
+	 * @param callback - Operation that may update and save the locked attempt row.
+	 * @returns Callback result after its state commits.
+	 */
+	static async withIdentityLock<TResult>(identity: string, callback: (attempt: PasswordLoginAttempt) => Promise<TResult>): Promise<TResult> {
+		return this.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+			const identityHash = this.identityKey(identity);
+			const candidate = this.create({ identityHash, identity: identity.trim().toLowerCase() });
+			// Framework-level upsert requires Knex; the fields still own every value
+			// and column conversion. Updating activity takes an exclusive key lock;
+			// INSERT IGNORE would take shared locks and can deadlock on FOR UPDATE.
+			await transaction(this.table).insert(await candidate.getDataForDb()).onConflict(this.getFields().identityHash!.column).merge([this.getFields().identity!.column, this.getFields().updatedAt!.column]);
+			const attempt = await this.where('identityHash', identityHash).forUpdate().first() as PasswordLoginAttempt | null;
+			if (!attempt) throw new Error('Unable to lock password login state.');
+			return callback(attempt);
+		}));
+	}
+}

package/src/auth/PasswordSuspendedError.ts

@@ -0,0 +1,13 @@
+import type { PasswordSuspension } from './contracts';
+
+/**
+ * Password sign-in for the submitted identity requires email recovery.
+ * The same error is used for existing and unknown emails, with no account data.
+ */
+export class PasswordSuspendedError extends Error {
+	/** Creates a generic refusal, optionally carrying a newly committed transition for server use. */
+	constructor(readonly suspension: PasswordSuspension | null = null) {
+		super('Too many sign-in attempts. Use password recovery to continue.');
+		this.name = 'PasswordSuspendedError';
+	}
+}

package/src/auth/README.md

@@ -162,6 +162,81 @@ Password-reset routes should find the user without revealing whether the email
 exists, call `createPasswordResetToken(user)`, send the plaintext token once,
 and later redeem it with `resetPassword(...)`.
 
+Successful `resetPassword(...)` and `changePasswordProvider(...)` calls replace
+the password, invalidate all outstanding password-reset links, and revoke every
+bearer session in one database transaction. This includes the current device;
+the app should clear its browser credentials and return to sign-in after a
+successful password change. Account-row locks serialize concurrent password
+replacements so two recovery links cannot both succeed. Invalid input or a
+database failure rolls back the complete operation.
+
+`setPasswordProvider(...)` is the low-level credential setup operation. Use the
+reset/change methods for account recovery and authenticated password changes.
+
+### Failed-password suspension
+
+Register `PasswordLoginAttempt` alongside `AuthProvider`, `AuthToken` and
+`PasswordResetToken` in the application's model registry and committed migrations.
+The `auth_password_login_attempts` table keeps one unique normalized-identity
+SHA-256 key, readable normalized `identity` (email), consecutive failure count and
+nullable `suspendedAt`. It has no user foreign key and records attempts for unknown
+emails exactly as for existing ones. `createdAt` records when the identity was
+first seen; `updatedAt` records the latest password sign-in or recovery activity,
+including refused attempts after suspension. Passwords are never recorded here.
+The digest remains the exact unique key independently of SQL text collation;
+it does not conceal the email. Legacy digest-only rows gain their readable
+identity on the next attempt without clearing their failure count or suspension.
+
+After 20 failures by default, password sign-in for that email requires recovery.
+There is no timed unlock and a correct password cannot clear suspension. Before
+suspension, successful verification resets consecutive failures. A completed,
+identity-matched password reset clears the state in the same transaction as the
+credential replacement and session revocation. Asking for a reset or submitting
+an invalid/expired reset link does not clear it. Google sign-in remains available.
+
+```ts
+password: {
+	driver: 'password',
+	suspension: { maxFailedAttempts: 20 }, // or suspension: false
+},
+```
+
+Known and unknown identities receive the same `PasswordSuspendedError` and public
+message. Unknown identities also perform password-hash verification with the
+configured hasher (default-cost scrypt by default) before recording failure.
+No account ID, timestamp, automatic retry deadline or
+account-existence flag belongs in the response. An HTTP adapter can map this error
+to `429 too_many_attempts`, with no `Retry-After` because recovery is required.
+The public message is "Too many sign-in attempts. Use password recovery to continue."
+
+Only the error that first commits a suspension carries a `suspension` value:
+`{ attemptId, suspensionId }`. Later blocked requests carry `null`. These opaque
+identifiers exist equally for registered and unknown identities and are for
+server-side work only; serialize the public code/message, not the whole error.
+An application can enqueue one recovery-notice job after catching this transition.
+The worker should find the attempt, confirm its `suspensionId` is still current,
+resolve an exactly matching account and send that owner a secure link from
+`Auth.createPasswordResetToken`. Never email unregistered submitted addresses.
+Templates, queueing and delivery policy remain application-owned. A reset clears
+the occurrence ID; a later suspension receives a new ID, so delayed jobs can be
+discarded without confusing separate suspension periods.
+
+Verification, failure counting and suspension share a per-identity SQL row lock.
+Concurrent first attempts use a unique-key upsert, and each verifier sees committed
+state before checking a password. Recovery takes the same lock. An attempt already
+verified before a later suspension is ordered before it; a verifier waiting behind
+the threshold-reaching failure cannot authenticate or clear the suspension.
+
+Keep IP-based limits and explicit trusted-proxy configuration: suspension does not
+prevent password spraying across many identities or intentional denial of password
+sign-in for an email. Records are retained without automatic deletion so operators
+can inspect targeted emails and recent activity. This is current suspension state,
+not a per-attempt event history: successful verification resets the counter before
+suspension, and verified recovery clears suspension. Operational logs may supplement
+investigations but do not replace this transactional state. A later manual cleanup
+or retention job should exclude rows with `suspendedAt` set; deleting those rows
+would remove the reset requirement. An email in this table is not proof of an account.
+
 ## Google Provider
 
 The built-in Google driver accepts a Google Identity Services ID token. It
@@ -336,6 +411,7 @@ List and revoke active sessions through the authenticated account:
 const sessions = await app.auth.tokensFor(user);
 await app.auth.revokeToken(user, sessionId);
 await app.auth.revokeCurrentToken();
+await app.auth.revokeAllTokens(user);
 ```
 
 Revocation sets `revokedAt`; the next bearer-token authentication rejects the
@@ -343,12 +419,25 @@ session before loading its user. `tokensFor(...)` excludes revoked and expired
 sessions. The current authenticated token is available as `app.auth.token`
 inside the request context so an app can mark the current browser session.
 
+`revokeAllTokens(user)` implements **Log out all devices**. The app must authorize
+the supplied account first; never accept a user id from the request as authority.
+It revokes all previously unrevoked tokens, including expired rows, and returns
+the number of rows changed. Revoked rows remain available for audit. Authentication
+cached in the calling request is invalidated and the current user is cleared
+when that account is logged out. Other requests already in progress may finish;
+subsequent authentication rejects the old tokens. A new sign-in can create a new
+session. This does not disconnect existing application-owned streams or revoke
+external provider credentials. Show failures and retain browser state if the
+all-devices request fails; clear browser credentials after successful confirmation.
+
 ## Security Responsibilities
 
 The auth package validates credentials and tokens, but the application still
 owns HTTP security controls:
 
 - Rate-limit public sign-in, sign-up, provider, forgot-password, and reset routes.
+  The password provider's per-identity suspension complements, and does not replace,
+  these IP limits.
 - Use generic invalid-credential and forgot-password responses to reduce account
   enumeration.
 - Accept bearer tokens only over HTTPS in production.
@@ -383,10 +472,11 @@ dedicated test account allowed to create/drop `db3_app_test_*` databases.
 It creates a unique database and removes it in `finally`; no email is sent and
 no token is logged. It is not a public HTTP auth endpoint.
 
-The lab does not establish race-safety for concurrent registration or reset
-redemption. Resetting a password does not automatically revoke existing bearer
-sessions; the application must choose and enforce that policy. The website's
-Auth page includes the exact test to copy into an independent application.
+The lab verifies account-wide logout and automatic revocation after password
+reset. The service's SQL regression tests additionally cover concurrent reset
+redemption, transaction rollback and cross-account isolation. Concurrent
+registration is a separate workflow. The website's Auth page includes the
+exact lab test to copy into an independent application.
 
 Run the auth package tests from the repository root: