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

package/src/auth/contracts/PasswordAuthProviderOptions.ts

@@ -0,0 +1,30 @@
+import type { AuthProvider } from '../AuthProvider';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity';
+import type { PasswordHash } from '../passwordHash';
+import type { PasswordSuspensionOptions } from './PasswordSuspensionOptions';
+
+/**
+ * Construction options for the password auth provider.
+ */
+export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = UserIdentity> {
+	/**
+	 * User identity model configured for the host app.
+	 */
+	identityModel: UserIdentityModel<TIdentity>;
+
+	/**
+	 * Provider-link model configured for the auth service.
+	 */
+	providerModel?: typeof AuthProvider;
+
+	/**
+	 * Password hashing service used to verify stored hashes.
+	 */
+	passwordHash?: PasswordHash;
+
+	/**
+	 * Failed-password suspension by normalized identity, including unknown identities.
+	 * Enabled after 20 attempts by default; `false` disables it.
+	 */
+	suspension?: PasswordSuspensionOptions | false;
+}

package/src/auth/contracts/PasswordSuspension.ts

@@ -0,0 +1,7 @@
+/** Identifies a newly committed suspension so an application can enqueue recovery notices. */
+export interface PasswordSuspension {
+	/** Attempt-state record, equally available for registered and unknown identities. */
+	attemptId: string;
+	/** Unique suspension occurrence; changes after recovery and a later suspension. */
+	suspensionId: string;
+}

package/src/auth/contracts/PasswordSuspensionOptions.ts

@@ -0,0 +1,10 @@
+/**
+ * Persistent suspension policy for submitted password identities.
+ *
+ * Known and unknown emails share the same threshold. Only completed password
+ * recovery clears suspension; this policy deliberately has no timed unlock.
+ */
+export interface PasswordSuspensionOptions {
+	/** Consecutive failures before recovery is required. Defaults to 20. */
+	maxFailedAttempts?: number;
+}

package/src/auth/contracts/index.ts

@@ -1 +1,4 @@
 export * from './AuthProviderDriver';
+export * from './PasswordSuspensionOptions';
+export * from './PasswordSuspension';
+export * from './PasswordAuthProviderOptions';

package/src/auth/examples/runPasswordAuth.ts

@@ -1,5 +1,5 @@
 import { pathToFileURL } from 'node:url';
-import { AuthProvider, AuthToken, PasswordResetToken, UserIdentity, PASSWORD_AUTH_PROVIDER } from '@db3.ai/app/auth';
+import { AuthProvider, PasswordLoginAttempt, AuthToken, PasswordResetToken, UserIdentity, PASSWORD_AUTH_PROVIDER } from '@db3.ai/app/auth';
 import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
 import { App } from '@db3.ai/app/server';
 
@@ -17,7 +17,7 @@ export async function runPasswordAuth() {
 	const application = new App({ db: database.db, config: { auth: { providers: { password: true } } } });
 	try {
 		// Lab-only schema setup. Use committed migrations in an application.
-		await application.db.install(UserIdentity, AuthProvider, AuthToken, PasswordResetToken);
+		await application.db.install(UserIdentity, AuthProvider, PasswordLoginAttempt, AuthToken, PasswordResetToken);
 		const credentials = { name: 'Ada', email: 'ada@example.test', password: 'example-only-password-123' };
 		const issued = await application.auth.registerWithPassword(credentials, { expiresInMs: 60 * 60 * 1000 });
 		const wrongPasswordRejected = await application.auth.issueTokenForProvider(PASSWORD_AUTH_PROVIDER, { ...credentials, password: 'wrong-password' }) === null;
@@ -27,14 +27,14 @@ export async function runPasswordAuth() {
 			return user?.id === issued.user.id;
 		});
 		const reset = await application.auth.createPasswordResetToken(issued.user);
+		const allDevicesRevoked = await application.auth.revokeAllTokens(issued.user) === 2;
+		const freshSession = await application.auth.createToken(issued.user);
 		const replacement = { token: reset.token, password: 'replacement-example-password-456' };
 		const passwordChanged = Boolean(await application.auth.resetPassword(replacement));
 		const usedResetRejected = await application.auth.resetPassword(replacement) === null;
 		const oldPasswordRejected = await application.auth.issueTokenForProvider(PASSWORD_AUTH_PROVIDER, credentials) === null;
-		const sessions = await application.auth.tokensFor(issued.user);
-		for (const session of sessions) await application.auth.revokeToken(issued.user, session.id!);
-		const revokedTokenRejected = await application.requestContext.run(async () => await application.auth.authenticateToken(issued.token) === null);
-		return { authenticated, signedIn: Boolean(signedIn), wrongPasswordRejected, passwordChanged, usedResetRejected, oldPasswordRejected, revokedTokenRejected };
+		const revokedTokenRejected = await application.requestContext.run(async () => await application.auth.authenticateToken(freshSession.token) === null);
+		return { authenticated, signedIn: Boolean(signedIn), wrongPasswordRejected, allDevicesRevoked, passwordChanged, usedResetRejected, oldPasswordRejected, revokedTokenRejected };
 	} finally {
 		try { await application.close(); } finally { await database.destroy(); }
 	}

package/src/auth/index.ts

@@ -2,6 +2,8 @@ export * from './Auth';
 export * from './AuthProvider';
 export * from './AuthToken';
 export * from './contracts';
+export * from './PasswordSuspendedError';
+export * from './PasswordLoginAttempt';
 export * from './PasswordResetToken';
 export * from './passwordHash';
 export * from './providers';

package/src/auth/providers/PasswordAuthProvider.ts

@@ -1,28 +1,15 @@
+import { randomBytes, randomUUID } from 'node:crypto';
 import { AuthProvider, PASSWORD_AUTH_PROVIDER } from '../AuthProvider';
 import type * as auth from '../contracts';
 import type { PasswordCredentials } from '../Auth';
 import type { UserIdentity, UserIdentityModel } from '../UserIdentity';
 import { defaultPasswordHash, type PasswordHash } from '../passwordHash';
+import { PasswordSuspendedError } from '../PasswordSuspendedError';
+import { PasswordLoginAttempt } from '../PasswordLoginAttempt';
 
-/**
- * Construction options for the password auth provider.
- */
-export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = UserIdentity> {
-	/**
-	 * User identity model configured for the host app.
-	 */
-	identityModel: UserIdentityModel<TIdentity>;
-
-	/**
-	 * Provider-link model configured for the auth service.
-	 */
-	providerModel?: typeof AuthProvider;
-
-	/**
-	 * Password hashing service used to verify stored hashes.
-	 */
-	passwordHash?: PasswordHash;
-}
+const DEFAULT_MAX_FAILED_ATTEMPTS = 20;
+/** Valid default-cost scrypt value used only for unknown-identity timing parity. */
+const DUMMY_PASSWORD_HASH = 'scrypt$1$16384$8$1$64$0123456789abcdef0123456789abcdef$' + '00'.repeat(64);
 
 /**
  * Provider driver for first-party email and password authentication.
@@ -36,37 +23,102 @@ export class PasswordAuthProvider<TIdentity extends UserIdentity = UserIdentity>
 	private readonly IdentityModel: UserIdentityModel<TIdentity>;
 	private readonly ProviderModel: typeof AuthProvider;
 	private readonly passwordHash: PasswordHash;
+	readonly #suspension: Required<auth.PasswordSuspensionOptions> | null;
+	#dummyHash: Promise<string> | undefined;
 
 	/**
 	 * Creates a password auth provider.
 	 *
 	 * @param options - Password provider dependencies configured at app startup.
 	 */
-	constructor(options: PasswordAuthProviderOptions<TIdentity>) {
+	constructor(options: auth.PasswordAuthProviderOptions<TIdentity>) {
 		this.IdentityModel = options.identityModel;
 		this.ProviderModel = options.providerModel ?? AuthProvider;
 		this.passwordHash = options.passwordHash ?? defaultPasswordHash;
+		this.#suspension = resolveSuspension(options.suspension);
 	}
 
 	/**
-	 * Verifies submitted password credentials against the stored provider row.
+	 * Verifies credentials under the identity's durable attempt lock.
 	 *
-	 * @param input - Submitted password credential payload.
-	 * @returns Normalized password provider profile, or null when verification fails.
+	 * Unknown identities receive the same failed-attempt accounting and password
+	 * hashing work as existing accounts. Suspension persists until verified
+	 * password recovery; a correct password cannot clear a suspended identity.
+	 *
+	 * @param input - Submitted password credentials.
+	 * @returns Verified provider profile, or null for an invalid password.
+	 * @throws {PasswordSuspendedError} When this identity needs password recovery.
 	 */
 	async verify(input: PasswordCredentials): Promise<auth.AuthProviderProfile | null> {
 		if (!isPasswordCredentials(input)) return null;
-
 		const identity = normalizeIdentity(input[this.IdentityModel.identityField]);
+		if (!identity || identity.length > 255) return null;
+
+		if (!this.#suspension) return this.#verifyPassword(identity, input.password);
+
+		// Return the refusal from the transaction so the threshold update commits
+		// before the public error is thrown.
+		const result = await PasswordLoginAttempt.withIdentityLock(identity, async attempt => {
+			if (attempt.suspendedAt) return new PasswordSuspendedError();
+			const profile = await this.#verifyPassword(identity, input.password);
+			if (profile) {
+				attempt.failedAttempts = 0;
+			} else {
+				attempt.failedAttempts += 1;
+				if (attempt.failedAttempts >= this.#suspension!.maxFailedAttempts) {
+					attempt.suspendedAt = new Date();
+					attempt.suspensionId = randomUUID();
+				}
+			}
+			await attempt.save();
+			return attempt.suspendedAt ? new PasswordSuspendedError({ attemptId: String(attempt.id), suspensionId: attempt.suspensionId! }) : profile;
+		});
+
+		if (result instanceof PasswordSuspendedError) throw result;
+		return result;
+	}
 
-		if (!identity) return null;
-
+	/**
+	 * Performs equivalent hashing work for known and unknown identities.
+	 * @param identity - Normalized submitted identity.
+	 * @param password - Submitted plaintext password, never persisted.
+	 * @returns Profile only when an existing password credential matches.
+	 */
+	async #verifyPassword(identity: string, password: string): Promise<auth.AuthProviderProfile | null> {
 		const provider = await this.findProvider(identity);
+		// SQL collations may match distinct identities (for example accented text).
+		// Only our exact normalized key may reach the credential verification path.
+		if (!provider || normalizeIdentity(provider.providerUserId) !== identity) {
+			const dummy = this.passwordHash === defaultPasswordHash
+				? DUMMY_PASSWORD_HASH
+				: await (this.#dummyHash ??= this.passwordHash.hash(randomBytes(32).toString('hex')).catch(error => {
+					this.#dummyHash = undefined;
+					throw error;
+				}));
+			await this.passwordHash.verify(password, dummy);
+			return null;
+		}
+		return await provider.verifyPassword(password, this.passwordHash) ? profileFromProvider(provider) : null;
+	}
 
-		if (!provider) return null;
-		if (!await provider.verifyPassword(input.password, this.passwordHash)) return null;
-
-		return profileFromProvider(provider);
+	/**
+	 * Replaces a verified owner's password and clears suspension atomically.
+	 * Called by Auth only after a usable, identity-matched recovery token is locked.
+	 * @param user - Account whose email recovery proof was verified.
+	 * @param password - Replacement plaintext password.
+	 * @returns Saved password provider.
+	 */
+	async recoverPassword(user: TIdentity, password: string): Promise<AuthProvider> {
+		const identity = this.userIdentityValue(user);
+		if (!identity) throw new Error('Cannot recover a password without an identity.');
+		return PasswordLoginAttempt.withIdentityLock(identity, async attempt => {
+			const provider = await this.setPassword(user, password);
+			attempt.failedAttempts = 0;
+			attempt.suspendedAt = null;
+			attempt.suspensionId = null;
+			await attempt.save();
+			return provider;
+		});
 	}
 
 	/**
@@ -254,3 +306,17 @@ function profileFromProvider(provider: AuthProvider): auth.AuthProviderProfile {
 		profile: provider.profile,
 	};
 }
+
+/**
+ * Resolves the failed-attempt threshold and rejects invalid startup config.
+ * @param options - Identity suspension policy, or false to disable accounting.
+ * @returns Validated threshold, or null when disabled.
+ */
+function resolveSuspension(options: auth.PasswordSuspensionOptions | false | undefined): Required<auth.PasswordSuspensionOptions> | null {
+	if (options === false) return null;
+	const maxFailedAttempts = options?.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS;
+	if (!Number.isSafeInteger(maxFailedAttempts) || maxFailedAttempts < 1 || maxFailedAttempts > 1_000_000) {
+		throw new Error('Password suspension maxFailedAttempts must be an integer between 1 and 1000000.');
+	}
+	return { maxFailedAttempts };
+}

package/src/auth/providers/resolveAuthProviders.ts

@@ -81,6 +81,7 @@ function resolveAuthProvider<TIdentity extends UserIdentity>(
 				identityModel: factoryOptions.identityModel,
 				providerModel: factoryOptions.providerModel,
 				passwordHash: factoryOptions.passwordHash,
+				suspension: options.suspension as auth.PasswordSuspensionOptions | false | undefined,
 			}) as auth.AuthProviderDriver<unknown, TIdentity>;
 
 		case GOOGLE_AUTH_PROVIDER:

package/src/cli/Cli.ts

@@ -34,6 +34,15 @@ export class Cli {
 		}
 	}
 
+	/** Returns detached metadata without booting the app or exposing executable handlers. */
+	commands(): cli.CliCommandInfo[] {
+		return [...this.#commands.values()].map(command => ({
+			name: command.name, description: command.description,
+			arguments: (command.arguments ?? []).map(argument => ({ ...argument })),
+			interactive: command.interactive ?? false,
+		}));
+	}
+
 	/**
 	 * Runs one invocation, printing help without app startup and closing a created app on failure too.
 	 * @param argv - Arguments after the executable name.

package/src/cli/README.md

@@ -162,3 +162,22 @@ failure cleanup and the real executable's TypeScript configuration loading.
 Database command tests live under the DB service and use disposable MariaDB
 databases. Release verification installs the packed framework into a generated
 app, then generates, applies and checks actual migrations through `db3`.
+
+## Visual command discovery
+
+`listDb3Commands({ directory })` returns serializable `CliCommandInfo` records
+for the same built-in and app-registered commands as `runDb3`. Each record has
+`name`, `description`, ordered `arguments`, and `interactive`. Discovery imports
+registration without calling `createApp`, validates duplicate/invalid definitions,
+and releases its scoped TypeScript loader. Invalid configuration rejects the
+promise. `new Cli(config).commands()` exposes the same metadata for an already
+registered runner, with detached argument declarations.
+
+Set `interactive: true` on a custom `CliCommand` when it requires a terminal
+session. The built-in REPL does this. Visual one-shot runners must exclude these
+commands from execution. Registration and discovery do not grant HTTP access.
+
+The separate `@db3.ai/dev` panel uses discovery for its Commands tab and runs the
+ordinary CLI in isolated local processes. It captures the same output and exit
+status without adding endpoints to consuming applications. Structured service
+results remain available by calling the underlying action directly.

package/src/cli/commands/repl.ts

@@ -10,7 +10,8 @@ import type { CliCommand, CliOptions } from '../contracts';
  */
 export function createReplCommand(loadModels: () => Promise<Record<string, unknown>>, options: CliOptions): CliCommand {
 	return {
-		name: 'repl', description: 'Explore the application and its models in an interactive terminal.',
+		name: 'repl',
+		interactive: true, description: 'Explore the application and its models in an interactive terminal.',
 		/** Boots the app without an HTTP listener and keeps it alive until REPL exit. */
 		async run(context) {
 			const application = await context.app();

package/src/cli/contracts/CliCommand.ts

@@ -28,6 +28,8 @@ export interface CliCommand {
 	description: string;
 	/** Positional argument declarations used for validation and help. */
 	arguments?: readonly CliArgument[];
+	/** Requires an interactive terminal session; visual one-shot runners must exclude it. */
+	interactive?: boolean;
 	/** Executes the operation; return a nonzero status for a reported failure. */
 	run(context: CliCommandContext): number | void | Promise<number | void>;
 }

package/src/cli/contracts/CliCommandInfo.ts

@@ -0,0 +1,13 @@
+import type { CliArgument } from './CliCommand';
+
+/** Serializable command metadata for explorers; never includes executable handlers or configuration. */
+export interface CliCommandInfo {
+	/** Unique registered command name. */
+	name: string;
+	/** Human-readable purpose shown in help and visual explorers. */
+	description: string;
+	/** Ordered positional inputs accepted by the CLI. */
+	arguments: readonly CliArgument[];
+	/** Interactive commands require a terminal session instead of a one-shot form. */
+	interactive: boolean;
+}

package/src/cli/contracts/index.ts

@@ -3,3 +3,4 @@ export type * from './CliConfig';
 export type * from './CliOptions';
 export type * from './CommandDefinition';
 export type * from './ReplOptions';
+export type * from './CliCommandInfo';

package/src/cli/index.ts

@@ -3,3 +3,4 @@ export * from './Cli';
 export * from './runDb3';
 export * from './defineCommand';
 export * from './runRepl';
+export * from './listDb3Commands';

package/src/cli/listDb3Commands.ts

@@ -0,0 +1,12 @@
+import { withDb3Cli } from './withDb3Cli';
+import type * as cli from './contracts';
+
+/**
+ * Discovers registered and built-in commands without creating the application.
+ * Configuration imports must remain free of startup side effects, as for CLI help.
+ * @param options - App root containing server/cli.config.ts, .mjs or .js.
+ * @returns Serializable command descriptions, including terminal-only capabilities.
+ */
+export async function listDb3Commands(options: Pick<cli.CliOptions, 'directory'> = {}): Promise<cli.CliCommandInfo[]> {
+	return withDb3Cli(options, async runner => runner.commands());
+}

package/src/cli/runDb3.ts

@@ -1,63 +1,17 @@
-import { access } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { register, type ScopedImport } from 'tsx/esm/api';
-import { Cli } from './Cli';
-import { createReplCommand } from './commands/repl';
+import { withDb3Cli } from './withDb3Cli';
 import type * as cli from './contracts';
 
 /**
- * Loads app registration and runs the framework CLI from source or an installed package.
- *
- * TypeScript config loading supports the same extensionless imports as the starter.
- * No HTTP listener is started. Help and queue:make-job do not create the app.
+ * Runs registered framework commands with app-owned startup and cleanup.
  * @param argv - Arguments after db3.
- * @param options - Application root and optional output adapters.
- * @returns Exit status to assign to process.exitCode.
+ * @param options - Application root and terminal adapters.
+ * @returns Process-compatible exit status without exiting the process.
  */
 export async function runDb3(argv: readonly string[], options: cli.CliOptions = {}): Promise<number> {
-	const loader = register({ namespace: `db3-cli-${randomUUID()}` });
 	try {
-		const { queueCommands } = await import('../queue/commands');
-		const directory = resolve(options.directory ?? process.cwd());
-		const configModule = await loadAppModule(directory, 'server/cli.config', loader.import);
-		const config: cli.CliConfig = configModule ? configModule.default : { commands: [] };
-		// Validate app config before combining it with commands that need no app bootstrap.
-		if (!config || !Array.isArray(config.commands)) throw new Error('CLI configuration must export a commands array.');
-		const repl = createReplCommand(async () => loadReplModels(directory, loader.import), options);
-		return await new Cli({ ...config, commands: [repl, ...queueCommands, ...config.commands] }, { ...options, directory }).run(argv);
+		return await withDb3Cli(options, runner => runner.run(argv));
 	} catch (error) {
 		(options.writeError ?? console.error)(error instanceof Error ? error.message : 'Unable to load CLI configuration.');
 		return 1;
-	} finally {
-		await loader.unregister();
 	}
 }
-
-/** Loads an optional conventional app module without hiding errors from its imports. */
-async function loadAppModule(directory: string, path: string, importModule: ScopedImport): Promise<Record<string, any> | undefined> {
-	for (const extension of ['ts', 'mjs', 'js']) {
-		const file = resolve(directory, `${path}.${extension}`);
-		try { await access(file); } catch (error) {
-			if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
-			throw error;
-		}
-		return importModule(pathToFileURL(file).href, import.meta.url);
-	}
-	return undefined;
-}
-
-/** Exposes named model constructors from the same registry used by app migrations. */
-async function loadReplModels(directory: string, importModule: ScopedImport): Promise<Record<string, unknown>> {
-	const module = await loadAppModule(directory, 'server/database/models', importModule);
-	if (!module) return {};
-	if (!Array.isArray(module.models)) throw new Error('server/database/models must export a models array for the REPL.');
-	const models: Record<string, unknown> = Object.create(null);
-	for (const model of module.models) {
-		if (typeof model !== 'function' || !/^[A-Za-z_$][\w$]*$/.test(model.name)) throw new Error('REPL models must be named constructors.');
-		if (['app', 'models', '__proto__', 'constructor', 'prototype'].includes(model.name) || Object.hasOwn(models, model.name)) throw new Error(`Duplicate or reserved REPL model name: ${model.name}`);
-		models[model.name] = model;
-	}
-	return models;
-}

package/src/cli/withDb3Cli.ts

@@ -0,0 +1,55 @@
+import { access } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register, type ScopedImport } from 'tsx/esm/api';
+import { Cli } from './Cli';
+import { createReplCommand } from './commands/repl';
+import type * as cli from './contracts';
+
+// Cache the import before scoped loaders alter hooks; avoid the CLI/Queue barrel cycle.
+let queueModule: Promise<typeof import('../queue/commands')> | undefined;
+
+/** Loads one app's command registry and releases its TypeScript loader after use. */
+export async function withDb3Cli<T>(options: cli.CliOptions, use: (runner: Cli) => Promise<T>): Promise<T> {
+	const { queueCommands } = await (queueModule ??= import('../queue/commands'));
+	const loader = register({ namespace: `db3-cli-${randomUUID()}` });
+	try {
+		const directory = resolve(options.directory ?? process.cwd());
+		const configModule = await loadAppModule(directory, 'server/cli.config', loader.import);
+		const config: cli.CliConfig = configModule ? configModule.default : { commands: [] };
+		// Validate app config before combining it with commands that need no app bootstrap.
+		if (!config || !Array.isArray(config.commands)) throw new Error('CLI configuration must export a commands array.');
+		const repl = createReplCommand(async () => loadReplModels(directory, loader.import), options);
+		return await use(new Cli({ ...config, commands: [repl, ...queueCommands, ...config.commands] }, { ...options, directory }));
+	} finally {
+		await loader.unregister();
+	}
+}
+
+/** Loads an optional conventional app module without hiding errors from its imports. */
+async function loadAppModule(directory: string, path: string, importModule: ScopedImport): Promise<Record<string, any> | undefined> {
+	for (const extension of ['ts', 'mjs', 'js']) {
+		const file = resolve(directory, `${path}.${extension}`);
+		try { await access(file); } catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+			throw error;
+		}
+		return importModule(pathToFileURL(file).href, import.meta.url);
+	}
+	return undefined;
+}
+
+/** Exposes named model constructors from the same registry used by app migrations. */
+async function loadReplModels(directory: string, importModule: ScopedImport): Promise<Record<string, unknown>> {
+	const module = await loadAppModule(directory, 'server/database/models', importModule);
+	if (!module) return {};
+	if (!Array.isArray(module.models)) throw new Error('server/database/models must export a models array for the REPL.');
+	const models: Record<string, unknown> = Object.create(null);
+	for (const model of module.models) {
+		if (typeof model !== 'function' || !/^[A-Za-z_$][\w$]*$/.test(model.name)) throw new Error('REPL models must be named constructors.');
+		if (['app', 'models', '__proto__', 'constructor', 'prototype'].includes(model.name) || Object.hasOwn(models, model.name)) throw new Error(`Duplicate or reserved REPL model name: ${model.name}`);
+		models[model.name] = model;
+	}
+	return models;
+}

package/src/db/ActiveQueryBuilder.ts

@@ -317,6 +317,18 @@ export class ActiveQueryBuilder<TRecord extends ActiveRecord> {
 		return this;
 	}
 
+	/**
+	 * Adds SELECT ... FOR UPDATE while retaining typed ActiveRecord results.
+	 * Execute inside a transaction; locks are released on commit or rollback.
+	 * This delegates to Knex and does not start or finish a transaction.
+	 * @returns This query for further filtering or execution.
+	 * @example await app().db.transaction(async () => { const user = await User.where('id', id).forUpdate().first(); });
+	 */
+	forUpdate(): this {
+		this.qb.forUpdate();
+		return this;
+	}
+
 	/**
 	 * Limits the number of returned records.
 	 */

package/src/db/ActiveRecord.ts

@@ -397,6 +397,15 @@ export abstract class ActiveRecord {
 			?? defaultDb();
 	}
 
+	/**
+	 * Returns the explicit transaction/database scope, without resolving model or app defaults.
+	 * Infrastructure adapters use this to participate in an application's atomic outbox writes.
+	 * @returns Current scoped connection, or undefined outside withDb().
+	 */
+	static getScopedDb(): Knex | undefined {
+		return scopedDb.getStore();
+	}
+
 	/**
 	 * Runs work with a temporary database connection for all ActiveRecord statics.
 	 */

package/src/db/README.md

@@ -7,7 +7,7 @@ data.
 
 ## Define an inferred model
 
-Use `ActiveRecord.define()` to declare fields once and infer model properties
+Prefer `ActiveRecord.define()` for new models. Declare fields once and infer model properties
 and constructor/`create()` inputs. Extend the returned class with ordinary
 instance and static methods. The [user example](examples/DefinedUser.ts) is a
 complete model with an inferred email property and a domain method.
@@ -506,3 +506,47 @@ class:
 Prefer normalising invalid input into a stable internal value and reporting
 problems through validation errors. Throw from parsing only for programmer
 errors or truly unrecoverable input.
+
+## Lock a row during a transaction
+
+Use `forUpdate()` when a read and subsequent update must exclude competing
+writers. It delegates to Knex's `forUpdate()` while keeping typed model results:
+
+```ts
+await app().db.transaction(async () => {
+	const user = await User.where('id', userId).forUpdate().firstOrFail();
+	// Read and update protected state here, then save the model.
+	await user.save();
+});
+```
+
+Create the query inside the transaction. `forUpdate()` adds the SQL lock clause;
+it does not open a transaction itself. The database releases locks on commit or
+rollback, including rollback when the callback throws. A terminated database
+connection also rolls back its transaction. Without an explicit transaction,
+autocommitted queries do not keep a useful lock across separate operations.
+Keep transactions short and avoid email, network requests or user input while
+holding locks. Ordinary consistent reads can still read committed state; locks
+coordinate competing writes and locking reads, not every reader. Actual lock
+scope and supported options depend on the database engine and indexes.
+
+`ActiveRecord.getScopedDb()` exposes only the explicit `withDb` connection, or
+`undefined`. It is an infrastructure-adapter seam for transaction participation;
+normal model/application code should continue using model APIs and `getDb()`.
+
+## UTC timestamp contract
+
+`TimestampField` uses Date values in memory and ISO UTC strings in JSON. ISO/SQL
+datetimes without an offset are interpreted as UTC, independent of the Node
+process timezone. Invalid/locale date strings normalize to null and required
+field validation still applies. Explicit offsets are honored. This does not
+interpret a user's local scheduling form; resolve its timezone before assigning.
+
+The default `db()` connection forces MySQL/MariaDB driver conversion to UTC and
+initializes every SQL session to UTC, including DATABASE_URL connections.
+PostgreSQL sessions use UTC and their per-client timestamp-without-timezone
+parser follows the same UTC convention. Timestamp fields write UTC calendar
+components to PostgreSQL timestamp columns, avoiding local Date serialization. Custom/injected Knex connections remain
+caller-owned: configure both driver conversion and the SQL session for UTC.
+Changing that contract does not repair historical incorrectly encoded values;
+inspect and migrate those separately before adopting it in an existing app.

package/src/db/connection.ts

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import knex, { type Knex } from 'knex';
+import { utcDate } from '@db3.ai/pure/dates';
 import {
 	rememberDatabaseDialect,
 	resolveDatabaseDialect,
@@ -25,9 +26,14 @@ function requiredEnv(name: string): string {
  * Builds a Knex connection value from the current process environment.
  */
 function databaseConnection(dialect: DatabaseDialect): Knex.Config['connection'] {
-	if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
+	if (process.env.DATABASE_URL) {
+		const url = new URL(process.env.DATABASE_URL);
+		if (dialect.name !== 'postgres') url.searchParams.set('timezone', 'Z');
+		return url.toString();
+	}
 
 	return {
+		...(dialect.name !== 'postgres' ? { timezone: 'Z' } : {}),
 		host: process.env.DB_HOST || '127.0.0.1',
 		port: Number(process.env.DB_PORT || dialect.defaultPort),
 		user: process.env.DB_USER || 'root',
@@ -47,6 +53,11 @@ export function db(): Knex {
 			client: dialect.knexClient,
 			connection: databaseConnection(dialect),
 			pool: {
+				/** Initializes SQL functions and TIMESTAMP conversion in UTC on every pooled connection. */
+				afterCreate(connection: { setTypeParser?: (oid: number, parser: (value: string) => Date | null) => void; query: (sql: string, callback: (error: Error | null) => void) => void }, done: (error: Error | null, connection: unknown) => void) {
+					if (dialect.name === 'postgres') connection.setTypeParser?.(1114, utcDate);
+					connection.query(dialect.name === 'postgres' ? "SET TIME ZONE 'UTC'" : "SET time_zone = '+00:00'", error => done(error, connection));
+				},
 				min: Number(process.env.DB_POOL_MIN || 0),
 				max: Number(process.env.DB_POOL_MAX || 10),
 			},