@flowdular/sdk 0.2.4 → 0.3.1

package/modules/auth/src/services/database-repository.ts

@@ -1,4 +1,5 @@
 import {
+	integer,
 	runDatabaseMigrations,
 	type DatabaseHandle,
 	type DatabaseParameter,
@@ -9,23 +10,30 @@ import type {
 	ActorKind,
 	ModuleSettingRecord,
 	ModuleSettingValue,
+	UserActor,
 } from '@flowdular/sdk/kernel';
+import { keysetWhere } from '@flowdular/sdk/server';
 import { BUILTIN_ROLES } from '../acl/scopes.ts';
 import type {
 	ApiTokenRecord,
+	AuditEvent,
 	AuditQuery,
 	AuthPrincipal,
 	AuthSession,
 	AuthTenantAccess,
+	IdentityProviderStatus,
+	MembershipStatus,
 	SessionSummary,
 	TenantRole,
 } from '../domain/types.ts';
 import { databaseMigrations } from './migration.ts';
 import {
 	DuplicateAccountError,
+	DuplicateProviderKeyError,
 	DuplicateRoleKeyError,
 	DuplicateTenantSlugError,
 	type AccountCredential,
+	type AccountIdentity,
 	type AuditActorEvent,
 	type AuditRecord,
 	type AuthRepository,
@@ -35,13 +43,22 @@ import {
 	type CreateRoleRecord,
 	type CreateSessionRecord,
 	type CreateTenantMembershipRecord,
+	type ExternalIdentityBinding,
+	type ExternalIdentityRecord,
+	type IdentityProviderPatch,
+	type IdentityProviderRecord,
 	type MfaChallengeRecord,
 	type PasswordResetTokenRecord,
+	type SessionExportRecord,
 	type SignInFailureRecord,
 	type TenantInvitationRecord,
 	type TenantMember,
+	type TenantMemberSort,
+	type TenantMemberSortedPage,
+	type TenantMemberSortedRead,
 	type TenantSummary,
 } from './repository.ts';
+import type { SealedMfaSecret } from './totp.ts';
 
 /**
  * The tenant context an identity table is read and written under. Accounts,
@@ -52,6 +69,14 @@ import {
  */
 export const IDENTITY_TENANT_CONTEXT = 'auth.core:identity';
 
+/**
+ * Rows one expired-session delete removes. The sweep walks a backlog of
+ * unknown size, and a single delete over it would hold the table for as long as
+ * it takes; a bounded batch keeps every statement short and leaves the rest to
+ * the next batch.
+ */
+export const EXPIRED_SESSION_SWEEP_BATCH = 1_000;
+
 /**
  * Storage tenant of a platform-scoped setting. The kernel addresses it as the
  * empty string, which is not a tenant id a policy can be bound to, so the row
@@ -84,6 +109,7 @@ interface AccountRow {
 	role: string;
 	role_id: string | null;
 	status: 'active' | 'disabled';
+	membership_status: MembershipStatus;
 	password_change_required: number | bigint | string;
 }
 
@@ -105,11 +131,38 @@ interface TenantMemberRow {
 	role: string;
 	role_id: string | null;
 	status: 'active' | 'disabled';
+	membership_status: MembershipStatus;
 	password_change_required: number | bigint | string;
 	scopes: string | null;
 	created_at: number | bigint | string;
 }
 
+interface SortedTenantMemberRow extends TenantMemberRow {
+	sort_value: string;
+}
+
+interface IdentityProviderRow {
+	id: string;
+	tenant_id: string;
+	key: string;
+	label: string;
+	issuer: string;
+	authorization_endpoint: string;
+	token_endpoint: string;
+	user_info_endpoint: string;
+	client_id: string;
+	client_secret_ciphertext: string;
+	client_secret_key_id: string;
+	client_secret_fingerprint: string;
+	scopes_json: string;
+	jit_enabled: number | bigint | string;
+	allowed_domains_json: string;
+	jit_role: string;
+	status: IdentityProviderStatus;
+	created_at: number | bigint | string;
+	updated_at: number | bigint | string;
+}
+
 interface SessionRow extends AccountRow {
 	session_id: string;
 	csrf_token: string;
@@ -138,6 +191,15 @@ interface RoleRow {
 	updated_at: number | bigint | string;
 }
 
+interface SessionExportRow {
+	id: string;
+	tenant_id: string;
+	account_id: string;
+	created_at: number | bigint | string;
+	expires_at: number | bigint | string;
+	last_seen_at: number | bigint | string;
+}
+
 interface AuditRow {
 	id: number | bigint | string;
 	tenant_id: string;
@@ -145,6 +207,7 @@ interface AuditRow {
 	actor_label: string;
 	actor_kind: ActorKind;
 	actor_run_id: string | null;
+	configured_by_json: string | null;
 	action: string;
 	subject_type: string;
 	subject_id: string;
@@ -162,26 +225,128 @@ interface CountRow {
 	total: number | bigint | string;
 }
 
-/* PostgreSQL returns BIGINT as a string, and every timestamp, expiry and
-   counter here is one. An unnormalized read would compare and serialize as
-   text: a session would never look expired and a role would never look
-   built in. */
-function integer(value: number | bigint | string): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized)) {
-		throw new Error('The auth database returned an invalid integer.');
-	}
-	return normalized;
-}
-
 function optionalInteger(
 	value: number | bigint | string | null,
+	field: string,
 ): number | null {
-	return value === null ? null : integer(value);
+	return value === null ? null : integer(value, field);
 }
 
 const ACCOUNT_COLUMNS = `a.id AS account_id, m.tenant_id, a.email, a.display_name,
-	 a.password_hash, m.role, m.role_id, a.status, a.password_change_required`;
+	 a.password_hash, m.role, m.role_id, a.status,
+	 m.status AS membership_status, a.password_change_required`;
+
+/* One projection for the whole roll and for a single member, so the two reads
+   can never disagree about what a member is. */
+const TENANT_MEMBER_COLUMNS = `a.id AS account_id, a.email, a.display_name,
+	 m.role, m.role_id, a.status, m.status AS membership_status,
+	 a.password_change_required, m.created_at,
+	 (SELECT string_agg(s.scope, ' ' ORDER BY s.scope)
+	    FROM auth_membership_scopes s
+	    WHERE s.account_id = m.account_id AND s.tenant_id = m.tenant_id) AS scopes`;
+
+/**
+ * The member search statement, exported so a plan assertion explains the
+ * statement the repository runs rather than a copy of it that can drift away
+ * from the indexes it was written for.
+ */
+export const TENANT_MEMBER_SEARCH_SQL = `SELECT ${TENANT_MEMBER_COLUMNS}
+       FROM auth_memberships m
+       JOIN auth_accounts a ON a.id = m.account_id
+       WHERE m.tenant_id = $1
+         AND (lower(a.display_name) LIKE $2 ESCAPE '\\'
+              OR a.email_normalized LIKE $2 ESCAPE '\\')
+       ORDER BY lower(a.display_name), a.id
+       LIMIT $3`;
+
+const TENANT_MEMBER_SORT_COLUMNS: Readonly<Record<TenantMemberSort, string>> = {
+	displayName: 'lower(a.display_name)',
+	email: 'a.email_normalized',
+};
+
+/**
+ * The sorted member page statement, exported for the same plan assertion as
+ * the search. The sort column is projected once, so the keyset predicate names
+ * a plain identifier and the ORDER BY the same expression the index carries.
+ */
+export function tenantMemberSortedStatement(
+	tenantId: string,
+	read: TenantMemberSortedRead,
+): DatabaseStatement {
+	const parameters: DatabaseParameter[] = [tenantId];
+	const filters = ['m.tenant_id = $1'];
+	if (read.membershipStatus !== null) {
+		parameters.push(read.membershipStatus);
+		filters.push(`m.status = $${parameters.length}`);
+	}
+	if (read.term !== null) {
+		parameters.push(`${read.term}%`);
+		filters.push(
+			`(lower(a.display_name) LIKE $${parameters.length} ESCAPE '\\'
+	          OR a.email_normalized LIKE $${parameters.length} ESCAPE '\\')`,
+		);
+	}
+	let keyset = '';
+	if (read.after !== null) {
+		const predicate = keysetWhere(
+			['sort_value', 'account_id'],
+			[read.after.sortValue, read.after.accountId],
+			{ direction: read.direction, parameterOffset: parameters.length },
+		);
+		parameters.push(...predicate.parameters);
+		keyset = `WHERE ${predicate.text}`;
+	}
+	parameters.push(read.limit);
+	const order = read.direction === 'asc' ? 'ASC' : 'DESC';
+	return {
+		text: `SELECT * FROM (
+	         SELECT ${TENANT_MEMBER_COLUMNS},
+	                ${TENANT_MEMBER_SORT_COLUMNS[read.sort]} AS sort_value
+	         FROM auth_memberships m
+	         JOIN auth_accounts a ON a.id = m.account_id
+	         WHERE ${filters.join(' AND ')}
+	       ) members
+	       ${keyset}
+	       ORDER BY sort_value ${order}, account_id ${order}
+	       LIMIT $${parameters.length}`,
+		parameters,
+	};
+}
+
+/**
+ * One PostgreSQL `text[]` literal. A bound parameter carries no array type, so
+ * a list travels as this literal and the statement casts it back. Every element
+ * is quoted with its backslashes and quotes escaped, so no element can close
+ * the literal early or add one of its own.
+ */
+export function textArrayLiteral(values: readonly string[]): string {
+	return `{${values
+		.map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`)
+		.join(',')}}`;
+}
+
+interface ExternalIdentityBindingRow {
+	account_id: string;
+	provider: string;
+	subject: string;
+	created_at: number | bigint | string;
+}
+
+function tenantMemberFrom(row: TenantMemberRow): TenantMember {
+	return {
+		accountId: row.account_id,
+		email: row.email,
+		displayName: row.display_name,
+		role: row.role,
+		roleId: row.role_id,
+		status: row.status,
+		membershipStatus: row.membership_status,
+		scopes: row.scopes ? row.scopes.split(' ') : [],
+		passwordChangeRequired:
+			integer(row.password_change_required, 'password_change_required') === 1,
+		createdAt: integer(row.created_at, 'created_at'),
+	};
+}
 
 export function builtinRoleId(tenantId: string, key: string): string {
 	return `${tenantId}:${key}`;
@@ -196,10 +361,10 @@ function fromApiTokenRow(row: ApiTokenRow): ApiTokenRecord {
 		prefix: row.prefix,
 		scopes: JSON.parse(row.scopes_json) as readonly string[],
 		createdBy: row.created_by,
-		createdAt: integer(row.created_at),
-		expiresAt: optionalInteger(row.expires_at),
-		lastUsedAt: optionalInteger(row.last_used_at),
-		revokedAt: optionalInteger(row.revoked_at),
+		createdAt: integer(row.created_at, 'created_at'),
+		expiresAt: optionalInteger(row.expires_at, 'expires_at'),
+		lastUsedAt: optionalInteger(row.last_used_at, 'last_used_at'),
+		revokedAt: optionalInteger(row.revoked_at, 'revoked_at'),
 		revokedBy: row.revoked_by,
 	};
 }
@@ -212,9 +377,35 @@ function fromRoleRow(row: RoleRow): TenantRole {
 		name: row.name,
 		description: row.description,
 		scopes: JSON.parse(row.scopes_json) as readonly string[],
-		builtin: integer(row.builtin) === 1,
-		createdAt: integer(row.created_at),
-		updatedAt: integer(row.updated_at),
+		builtin: integer(row.builtin, 'builtin') === 1,
+		createdAt: integer(row.created_at, 'created_at'),
+		updatedAt: integer(row.updated_at, 'updated_at'),
+	};
+}
+
+function fromIdentityProviderRow(
+	row: IdentityProviderRow,
+): IdentityProviderRecord {
+	return {
+		id: row.id,
+		tenantId: row.tenant_id,
+		key: row.key,
+		label: row.label,
+		issuer: row.issuer,
+		authorizationEndpoint: row.authorization_endpoint,
+		tokenEndpoint: row.token_endpoint,
+		userInfoEndpoint: row.user_info_endpoint,
+		clientId: row.client_id,
+		secretCiphertext: row.client_secret_ciphertext,
+		secretKeyId: row.client_secret_key_id,
+		secretFingerprint: row.client_secret_fingerprint,
+		scopes: JSON.parse(row.scopes_json) as readonly string[],
+		jitEnabled: integer(row.jit_enabled, 'jit_enabled') === 1,
+		allowedDomains: JSON.parse(row.allowed_domains_json) as readonly string[],
+		jitRole: row.jit_role,
+		status: row.status,
+		createdAt: integer(row.created_at, 'created_at'),
+		updatedAt: integer(row.updated_at, 'updated_at'),
 	};
 }
 
@@ -225,11 +416,16 @@ function tenantSummary(row: TenantRow): TenantSummary {
 /* A unique violation arrives as the driver's own error. The constraint name is
    the only stable part of it, so the duplicate a caller can act on is
    recognized by name and everything else is rethrown untouched. */
-function duplicate(error: unknown): 'email' | 'role-key' | 'slug' | null {
+function duplicate(
+	error: unknown,
+): 'email' | 'role-key' | 'slug' | 'provider-key' | null {
 	const text = String(error);
 	if (text.includes('auth_accounts_email_normalized_key')) return 'email';
 	if (text.includes('auth_tenants_slug_idx')) return 'slug';
 	if (text.includes('auth_roles_tenant_id_key_key')) return 'role-key';
+	if (text.includes('auth_identity_providers_tenant_id_key_key')) {
+		return 'provider-key';
+	}
 	return null;
 }
 
@@ -318,9 +514,12 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return result.rows;
 	}
 
+	/* A disabled membership answers for nothing: it must not be the workspace a
+	   session cookie, a bearer token or a sign-in resolves to. */
 	async #tenantOfAccount(accountId: string): Promise<string | null> {
 		const rows = await this.#route<RoutedTenantRow>({
-			text: `SELECT tenant_id FROM auth_memberships WHERE account_id = $1
+			text: `SELECT tenant_id FROM auth_memberships
+			       WHERE account_id = $1 AND status = 'active'
 			       ORDER BY created_at, tenant_id LIMIT 1`,
 			parameters: [accountId],
 		});
@@ -353,7 +552,9 @@ export class DatabaseAuthRepository implements AuthRepository {
 			role: row.role,
 			roleId: row.role_id,
 			status: row.status,
-			passwordChangeRequired: integer(row.password_change_required) === 1,
+			membershipStatus: row.membership_status,
+			passwordChangeRequired:
+				integer(row.password_change_required, 'password_change_required') === 1,
 			scopes: await this.#scopes(transaction, row.account_id, row.tenant_id),
 		};
 	}
@@ -501,6 +702,30 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return accountId ? this.findAccountCredentialById(accountId) : null;
 	}
 
+	async findAccountIdentity(
+		normalizedEmail: string,
+	): Promise<AccountIdentity | null> {
+		const rows = await this.#query<{
+			id: string;
+			email: string;
+			display_name: string;
+			status: 'active' | 'disabled';
+		}>(IDENTITY_TENANT_CONTEXT, {
+			text: `SELECT id, email, display_name, status FROM auth_accounts
+			       WHERE email_normalized = $1`,
+			parameters: [normalizedEmail],
+		});
+		const row = rows[0];
+		return row
+			? {
+					accountId: row.id,
+					email: row.email,
+					displayName: row.display_name,
+					status: row.status,
+				}
+			: null;
+	}
+
 	async findAccountCredentialById(
 		accountId: string,
 	): Promise<AccountCredential | null> {
@@ -611,7 +836,7 @@ export class DatabaseAuthRepository implements AuthRepository {
 			text: 'SELECT count(*) AS total FROM auth_memberships WHERE account_id = $1',
 			parameters: [accountId],
 		});
-		return rows[0] ? integer(rows[0].total) : 0;
+		return rows[0] ? integer(rows[0].total, 'total') : 0;
 	}
 
 	/* The account row is the identity. Its memberships, sessions and tokens go
@@ -628,10 +853,11 @@ export class DatabaseAuthRepository implements AuthRepository {
 		const rows = await this.#query<CountRow>(tenantId, {
 			text: `SELECT count(*) AS total FROM auth_memberships m
 			       JOIN auth_accounts a ON a.id = m.account_id
-			       WHERE m.tenant_id = $1 AND m.role = 'owner' AND a.status = 'active'`,
+			       WHERE m.tenant_id = $1 AND m.role = 'owner'
+			         AND a.status = 'active' AND m.status = 'active'`,
 			parameters: [tenantId],
 		});
-		return rows[0] ? integer(rows[0].total) : 0;
+		return rows[0] ? integer(rows[0].total, 'total') : 0;
 	}
 
 	/* Which workspaces an account may enter is the one question that spans
@@ -643,7 +869,7 @@ export class DatabaseAuthRepository implements AuthRepository {
 			text: `SELECT t.id AS tenant_id, t.name, t.slug, m.role
 			       FROM auth_memberships m
 			       JOIN auth_tenants t ON t.id = m.tenant_id
-			       WHERE m.account_id = $1
+			       WHERE m.account_id = $1 AND m.status = 'active'
 			       ORDER BY m.created_at, t.id`,
 			parameters: [accountId],
 		});
@@ -657,28 +883,103 @@ export class DatabaseAuthRepository implements AuthRepository {
 
 	async listTenantMembers(tenantId: string): Promise<readonly TenantMember[]> {
 		const rows = await this.#query<TenantMemberRow>(tenantId, {
-			text: `SELECT a.id AS account_id, a.email, a.display_name, m.role, m.role_id,
-			       a.status, a.password_change_required, m.created_at,
-			       (SELECT string_agg(s.scope, ' ' ORDER BY s.scope)
-			          FROM auth_membership_scopes s
-			          WHERE s.account_id = m.account_id AND s.tenant_id = m.tenant_id) AS scopes
+			text: `SELECT ${TENANT_MEMBER_COLUMNS}
 			       FROM auth_memberships m
 			       JOIN auth_accounts a ON a.id = m.account_id
 			       WHERE m.tenant_id = $1
 			       ORDER BY lower(a.display_name), a.id`,
 			parameters: [tenantId],
 		});
-		return rows.map((row) => ({
-			accountId: row.account_id,
-			email: row.email,
-			displayName: row.display_name,
-			role: row.role,
-			roleId: row.role_id,
-			status: row.status,
-			scopes: row.scopes ? row.scopes.split(' ') : [],
-			passwordChangeRequired: integer(row.password_change_required) === 1,
-			createdAt: integer(row.created_at),
-		}));
+		return rows.map(tenantMemberFrom);
+	}
+
+	/* Keyset by account id, which migration 0030 indexes behind the workspace,
+	   so a page is an index range scan of exactly the rows it returns rather
+	   than a walk over every workspace's memberships after the cursor. */
+	async listTenantMembersPage(
+		tenantId: string,
+		afterAccountId: string,
+		limit: number,
+	): Promise<readonly TenantMember[]> {
+		const rows = await this.#query<TenantMemberRow>(tenantId, {
+			text: `SELECT ${TENANT_MEMBER_COLUMNS}
+			       FROM auth_memberships m
+			       JOIN auth_accounts a ON a.id = m.account_id
+			       WHERE m.tenant_id = $1 AND m.account_id > $2
+			       ORDER BY m.account_id
+			       LIMIT $3`,
+			parameters: [tenantId, afterAccountId, limit],
+		});
+		return rows.map(tenantMemberFrom);
+	}
+
+	async listTenantMembersSorted(
+		tenantId: string,
+		read: TenantMemberSortedRead,
+	): Promise<TenantMemberSortedPage> {
+		const rows = await this.#query<SortedTenantMemberRow>(
+			tenantId,
+			tenantMemberSortedStatement(tenantId, read),
+		);
+		const last = rows[rows.length - 1];
+		return {
+			members: rows.map(tenantMemberFrom),
+			next:
+				last && rows.length === read.limit
+					? { sortValue: last.sort_value, accountId: last.account_id }
+					: null,
+		};
+	}
+
+	async countTenantMembers(tenantId: string): Promise<number> {
+		const rows = await this.#query<CountRow>(tenantId, {
+			text: 'SELECT count(*) AS total FROM auth_memberships WHERE tenant_id = $1',
+			parameters: [tenantId],
+		});
+		return rows[0] ? integer(rows[0].total, 'total') : 0;
+	}
+
+	async findTenantMember(
+		tenantId: string,
+		accountId: string,
+	): Promise<TenantMember | null> {
+		const rows = await this.#query<TenantMemberRow>(tenantId, {
+			text: `SELECT ${TENANT_MEMBER_COLUMNS}
+			       FROM auth_memberships m
+			       JOIN auth_accounts a ON a.id = m.account_id
+			       WHERE m.tenant_id = $1 AND m.account_id = $2`,
+			parameters: [tenantId, accountId],
+		});
+		const row = rows[0];
+		return row ? tenantMemberFrom(row) : null;
+	}
+
+	async findTenantMembersByEmail(
+		tenantId: string,
+		normalizedEmails: readonly string[],
+	): Promise<readonly TenantMember[]> {
+		if (normalizedEmails.length === 0) return [];
+		const rows = await this.#query<TenantMemberRow>(tenantId, {
+			text: `SELECT ${TENANT_MEMBER_COLUMNS}
+			       FROM auth_memberships m
+			       JOIN auth_accounts a ON a.id = m.account_id
+			       WHERE m.tenant_id = $1 AND a.email_normalized = ANY($2::text[])
+			       ORDER BY lower(a.display_name), a.id`,
+			parameters: [tenantId, textArrayLiteral(normalizedEmails)],
+		});
+		return rows.map(tenantMemberFrom);
+	}
+
+	async searchTenantMembers(
+		tenantId: string,
+		term: string,
+		limit: number,
+	): Promise<readonly TenantMember[]> {
+		const rows = await this.#query<TenantMemberRow>(tenantId, {
+			text: TENANT_MEMBER_SEARCH_SQL,
+			parameters: [tenantId, `${term}%`, limit],
+		});
+		return rows.map(tenantMemberFrom);
 	}
 
 	async listTenantScopes(tenantId: string): Promise<readonly string[]> {
@@ -1139,12 +1440,13 @@ export class DatabaseAuthRepository implements AuthRepository {
 				       JOIN auth_accounts a ON a.id = s.account_id
 				       JOIN auth_memberships m
 				         ON m.account_id = s.account_id AND m.tenant_id = s.tenant_id
-				       WHERE s.token_hash = $1 AND s.expires_at > $2 AND a.status = 'active'`,
+				       WHERE s.token_hash = $1 AND s.expires_at > $2 AND a.status = 'active'
+				         AND m.status = 'active'`,
 				parameters: [tokenHash, now],
 			});
 			const row = result.rows[0];
 			if (!row) return null;
-			const lastSeenAt = integer(row.last_seen_at);
+			const lastSeenAt = integer(row.last_seen_at, 'last_seen_at');
 			if (now - lastSeenAt > idleMs) {
 				await transaction.execute({
 					text: 'DELETE FROM auth_sessions WHERE token_hash = $1',
@@ -1176,10 +1478,13 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return {
 			principal,
 			csrfToken: session.row.csrf_token,
-			expiresAt: integer(session.row.expires_at),
+			expiresAt: integer(session.row.expires_at, 'expires_at'),
 			sessionId: session.row.session_id,
 			passwordChangeRequired:
-				integer(session.row.password_change_required) === 1,
+				integer(
+					session.row.password_change_required,
+					'password_change_required',
+				) === 1,
 		};
 	}
 
@@ -1209,9 +1514,9 @@ export class DatabaseAuthRepository implements AuthRepository {
 					id: row.id,
 					tenantId: row.tenant_id,
 					tenantName: row.tenant_name,
-					createdAt: integer(row.created_at),
-					lastSeenAt: integer(row.last_seen_at),
-					expiresAt: integer(row.expires_at),
+					createdAt: integer(row.created_at, 'created_at'),
+					lastSeenAt: integer(row.last_seen_at, 'last_seen_at'),
+					expiresAt: integer(row.expires_at, 'expires_at'),
 				});
 			}
 		}
@@ -1249,17 +1554,38 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return affected > 0;
 	}
 
-	async deleteExpiredSessions(now: number): Promise<number> {
+	/**
+	 * Removes sessions that expired before `now` in batches of
+	 * EXPIRED_SESSION_SWEEP_BATCH, at most `maxBatches` of them, and answers how
+	 * many rows went. A backlog of unknown size must not become one delete that
+	 * holds the table for the length of it, and what the bound leaves behind is
+	 * the next pass's work. Row security scopes a delete to one workspace, so
+	 * the rows are routed first and removed per tenant.
+	 */
+	async deleteExpiredSessions(
+		now: number,
+		maxBatches: number = Number.POSITIVE_INFINITY,
+	): Promise<number> {
 		const tenants = await this.#route<RoutedTenantRow>({
 			text: 'SELECT DISTINCT tenant_id FROM auth_sessions WHERE expires_at <= $1',
 			parameters: [now],
 		});
 		let removed = 0;
+		let batches = 0;
 		for (const tenant of tenants) {
-			removed += await this.#exec(tenant.tenant_id, {
-				text: 'DELETE FROM auth_sessions WHERE expires_at <= $1',
-				parameters: [now],
-			});
+			while (batches < maxBatches) {
+				batches += 1;
+				const gone = await this.#exec(tenant.tenant_id, {
+					text: `DELETE FROM auth_sessions
+					       WHERE id IN (SELECT id FROM auth_sessions
+					                    WHERE expires_at <= $1
+					                    LIMIT $2)`,
+					parameters: [now, EXPIRED_SESSION_SWEEP_BATCH],
+				});
+				removed += gone;
+				/* A short batch is the proof this workspace is drained. */
+				if (gone < EXPIRED_SESSION_SWEEP_BATCH) break;
+			}
 		}
 		return removed;
 	}
@@ -1287,6 +1613,24 @@ export class DatabaseAuthRepository implements AuthRepository {
 		});
 	}
 
+	/* Reads the account a live link names so the password policy can run on the
+	   full account before anything spends the token. Claiming it stays the job
+	   of consumePasswordResetToken below. */
+	async findPasswordResetTokenAccount(
+		tokenHash: string,
+		now: number,
+	): Promise<string | null> {
+		const rows = await this.#query<{ account_id: string }>(
+			IDENTITY_TENANT_CONTEXT,
+			{
+				text: `SELECT account_id FROM auth_password_reset_tokens
+				       WHERE token_hash = $1 AND used_at IS NULL AND expires_at > $2`,
+				parameters: [tokenHash, now],
+			},
+		);
+		return rows[0]?.account_id ?? null;
+	}
+
 	/* One statement claims the token: a second caller with the same link finds
 	   used_at already set and gets nothing. */
 	async consumePasswordResetToken(
@@ -1378,30 +1722,33 @@ export class DatabaseAuthRepository implements AuthRepository {
 
 	async upsertMfaTotp(
 		accountId: string,
-		secretCiphertext: string,
+		secret: SealedMfaSecret,
 		createdAt: number,
 	): Promise<void> {
 		await this.#exec(IDENTITY_TENANT_CONTEXT, {
 			text: `INSERT INTO auth_mfa_totp
-			       (account_id, secret_ciphertext, confirmed_at, created_at)
-			       VALUES ($1, $2, NULL, $3)
+			       (account_id, secret_ciphertext, key_id, confirmed_at, created_at)
+			       VALUES ($1, $2, $3, NULL, $4)
 			       ON CONFLICT (account_id) DO UPDATE SET
 			         secret_ciphertext = excluded.secret_ciphertext,
+			         key_id = excluded.key_id,
 			         confirmed_at = NULL,
 			         created_at = excluded.created_at`,
-			parameters: [accountId, secretCiphertext, createdAt],
+			parameters: [accountId, secret.ciphertext, secret.keyId, createdAt],
 		});
 	}
 
 	async findMfaTotp(accountId: string): Promise<{
 		readonly secretCiphertext: string;
+		readonly keyId: string | null;
 		readonly confirmedAt: number | null;
 	} | null> {
 		const rows = await this.#query<{
 			secret_ciphertext: string;
+			key_id: string | null;
 			confirmed_at: number | bigint | string | null;
 		}>(IDENTITY_TENANT_CONTEXT, {
-			text: `SELECT secret_ciphertext, confirmed_at FROM auth_mfa_totp
+			text: `SELECT secret_ciphertext, key_id, confirmed_at FROM auth_mfa_totp
 			       WHERE account_id = $1`,
 			parameters: [accountId],
 		});
@@ -1409,11 +1756,24 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return row
 			? {
 					secretCiphertext: row.secret_ciphertext,
-					confirmedAt: optionalInteger(row.confirmed_at),
+					keyId: row.key_id,
+					confirmedAt: optionalInteger(row.confirmed_at, 'confirmed_at'),
 				}
 			: null;
 	}
 
+	async hasConfirmedMfaTotp(accountId: string): Promise<boolean> {
+		const rows = await this.#query<{ account_id: string }>(
+			IDENTITY_TENANT_CONTEXT,
+			{
+				text: `SELECT account_id FROM auth_mfa_totp
+				       WHERE account_id = $1 AND confirmed_at IS NOT NULL`,
+				parameters: [accountId],
+			},
+		);
+		return rows.length > 0;
+	}
+
 	async confirmMfaTotp(accountId: string, confirmedAt: number): Promise<void> {
 		await this.#exec(IDENTITY_TENANT_CONTEXT, {
 			text: 'UPDATE auth_mfa_totp SET confirmed_at = $1 WHERE account_id = $2',
@@ -1421,6 +1781,19 @@ export class DatabaseAuthRepository implements AuthRepository {
 		});
 	}
 
+	async deleteMfaEnrolment(accountId: string): Promise<void> {
+		await this.#tx(IDENTITY_TENANT_CONTEXT, 'write', async (transaction) => {
+			await transaction.execute({
+				text: 'DELETE FROM auth_mfa_totp WHERE account_id = $1',
+				parameters: [accountId],
+			});
+			await transaction.execute({
+				text: 'DELETE FROM auth_mfa_recovery_codes WHERE account_id = $1',
+				parameters: [accountId],
+			});
+		});
+	}
+
 	async replaceMfaRecoveryCodes(
 		accountId: string,
 		codeHashes: readonly string[],
@@ -1504,6 +1877,267 @@ export class DatabaseAuthRepository implements AuthRepository {
 		return row ? { accountId: row.account_id, tenantId: row.tenant_id } : null;
 	}
 
+	/* A binding lives in one space: the platform space, whose rows carry no
+	   workspace and are read under the identity context exactly as before, or
+	   one workspace's space, read and written under that workspace. The policy
+	   on the table enforces the same split. */
+	async findExternalIdentity(
+		provider: string,
+		subject: string,
+		tenantId: string | null = null,
+	): Promise<string | null> {
+		const rows = await this.#query<{ account_id: string }>(
+			tenantId ?? IDENTITY_TENANT_CONTEXT,
+			{
+				text: `SELECT account_id FROM auth_external_identities
+				       WHERE provider = $1 AND subject = $2
+				         AND tenant_id IS NOT DISTINCT FROM $3`,
+				parameters: [provider, subject, tenantId],
+			},
+		);
+		return rows[0]?.account_id ?? null;
+	}
+
+	async findExternalIdentitySubject(
+		provider: string,
+		accountId: string,
+		tenantId: string | null = null,
+	): Promise<string | null> {
+		const rows = await this.#query<{ subject: string }>(
+			tenantId ?? IDENTITY_TENANT_CONTEXT,
+			{
+				text: `SELECT subject FROM auth_external_identities
+				       WHERE account_id = $1 AND provider = $2
+				         AND tenant_id IS NOT DISTINCT FROM $3`,
+				parameters: [accountId, provider, tenantId],
+			},
+		);
+		return rows[0]?.subject ?? null;
+	}
+
+	async linkExternalIdentity(record: ExternalIdentityRecord): Promise<void> {
+		const tenantId = record.tenantId ?? null;
+		await this.#exec(tenantId ?? IDENTITY_TENANT_CONTEXT, {
+			text: tenantId
+				? `INSERT INTO auth_external_identities
+				   (provider, subject, account_id, tenant_id, created_at, last_seen_at)
+				   VALUES ($1, $2, $3, $4, $5, $5)
+				   ON CONFLICT (tenant_id, provider, subject) WHERE tenant_id IS NOT NULL
+				   DO UPDATE SET last_seen_at = excluded.last_seen_at`
+				: `INSERT INTO auth_external_identities
+				   (provider, subject, account_id, tenant_id, created_at, last_seen_at)
+				   VALUES ($1, $2, $3, $4, $5, $5)
+				   ON CONFLICT (provider, subject) WHERE tenant_id IS NULL
+				   DO UPDATE SET last_seen_at = excluded.last_seen_at`,
+			parameters: [
+				record.provider,
+				record.subject,
+				record.accountId,
+				tenantId,
+				record.now,
+			],
+		});
+	}
+
+	/* Keyset by (provider, subject), which the unique workspace index covers in
+	   that order, so a page is the rows it returns. The select list is the
+	   binding and nothing else: no token, ciphertext, fingerprint or reported
+	   address leaves this statement. A platform provider's binding carries no
+	   workspace, so the predicate never reaches one. */
+	async listExternalIdentitiesPage(
+		tenantId: string,
+		after: { readonly provider: string; readonly subject: string },
+		limit: number,
+	): Promise<readonly ExternalIdentityBinding[]> {
+		const rows = await this.#query<ExternalIdentityBindingRow>(tenantId, {
+			text: `SELECT account_id, provider, subject, created_at
+			       FROM auth_external_identities
+			       WHERE tenant_id = $1 AND (provider, subject) > ($2, $3)
+			       ORDER BY provider, subject
+			       LIMIT $4`,
+			parameters: [tenantId, after.provider, after.subject, limit],
+		});
+		return rows.map((row) => ({
+			accountId: row.account_id,
+			provider: row.provider,
+			subject: row.subject,
+			linkedAt: integer(row.created_at, 'created_at'),
+		}));
+	}
+
+	/* A deleted provider takes its workspace's bindings with it; the accounts
+	   stay and keep every other way of signing in. */
+	async deleteExternalIdentitiesOfProvider(
+		tenantId: string,
+		provider: string,
+	): Promise<void> {
+		await this.#exec(tenantId, {
+			text: `DELETE FROM auth_external_identities
+			       WHERE tenant_id = $1 AND provider = $2`,
+			parameters: [tenantId, provider],
+		});
+	}
+
+	async listIdentityProviders(
+		tenantId: string,
+	): Promise<readonly IdentityProviderRecord[]> {
+		const rows = await this.#query<IdentityProviderRow>(tenantId, {
+			text: `SELECT * FROM auth_identity_providers
+			       WHERE tenant_id = $1 ORDER BY key, id`,
+			parameters: [tenantId],
+		});
+		return rows.map(fromIdentityProviderRow);
+	}
+
+	async findIdentityProvider(
+		tenantId: string,
+		id: string,
+	): Promise<IdentityProviderRecord | null> {
+		const rows = await this.#query<IdentityProviderRow>(tenantId, {
+			text: 'SELECT * FROM auth_identity_providers WHERE tenant_id = $1 AND id = $2',
+			parameters: [tenantId, id],
+		});
+		return rows[0] ? fromIdentityProviderRow(rows[0]) : null;
+	}
+
+	async findIdentityProviderByKey(
+		tenantId: string,
+		key: string,
+	): Promise<IdentityProviderRecord | null> {
+		const rows = await this.#query<IdentityProviderRow>(tenantId, {
+			text: 'SELECT * FROM auth_identity_providers WHERE tenant_id = $1 AND key = $2',
+			parameters: [tenantId, key],
+		});
+		return rows[0] ? fromIdentityProviderRow(rows[0]) : null;
+	}
+
+	async createIdentityProvider(
+		record: IdentityProviderRecord,
+	): Promise<IdentityProviderRecord> {
+		try {
+			const rows = await this.#tx(
+				record.tenantId,
+				'write',
+				async (transaction) => {
+					const result = await transaction.query<IdentityProviderRow>({
+						text: `INSERT INTO auth_identity_providers
+						       (id, tenant_id, key, label, issuer, authorization_endpoint,
+						        token_endpoint, user_info_endpoint, client_id,
+						        client_secret_ciphertext, client_secret_key_id,
+						        client_secret_fingerprint, scopes_json, jit_enabled,
+						        allowed_domains_json, jit_role, status, created_at, updated_at)
+						       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13,
+						               $14, $15, $16, $17, $18, $18)
+						       RETURNING *`,
+						parameters: [
+							record.id,
+							record.tenantId,
+							record.key,
+							record.label,
+							record.issuer,
+							record.authorizationEndpoint,
+							record.tokenEndpoint,
+							record.userInfoEndpoint,
+							record.clientId,
+							record.secretCiphertext,
+							record.secretKeyId,
+							record.secretFingerprint,
+							JSON.stringify(record.scopes),
+							record.jitEnabled ? 1 : 0,
+							JSON.stringify(record.allowedDomains),
+							record.jitRole,
+							record.status,
+							record.createdAt,
+						],
+					});
+					return result.rows;
+				},
+			);
+			return fromIdentityProviderRow(rows[0]!);
+		} catch (error) {
+			if (duplicate(error) === 'provider-key') {
+				throw new DuplicateProviderKeyError();
+			}
+			throw error;
+		}
+	}
+
+	async updateIdentityProvider(
+		tenantId: string,
+		id: string,
+		patch: IdentityProviderPatch,
+		updatedAt: number,
+	): Promise<IdentityProviderRecord | null> {
+		const rows = await this.#tx(tenantId, 'write', async (transaction) => {
+			const result = await transaction.query<IdentityProviderRow>({
+				text: `UPDATE auth_identity_providers
+				       SET label = $3, issuer = $4, authorization_endpoint = $5,
+				           token_endpoint = $6, user_info_endpoint = $7, client_id = $8,
+				           client_secret_ciphertext = $9, client_secret_key_id = $10,
+				           client_secret_fingerprint = $11, scopes_json = $12,
+				           jit_enabled = $13, allowed_domains_json = $14, jit_role = $15,
+				           status = $16, updated_at = $17
+				       WHERE tenant_id = $1 AND id = $2
+				       RETURNING *`,
+				parameters: [
+					tenantId,
+					id,
+					patch.label,
+					patch.issuer,
+					patch.authorizationEndpoint,
+					patch.tokenEndpoint,
+					patch.userInfoEndpoint,
+					patch.clientId,
+					patch.secretCiphertext,
+					patch.secretKeyId,
+					patch.secretFingerprint,
+					JSON.stringify(patch.scopes),
+					patch.jitEnabled ? 1 : 0,
+					JSON.stringify(patch.allowedDomains),
+					patch.jitRole,
+					patch.status,
+					updatedAt,
+				],
+			});
+			return result.rows;
+		});
+		return rows[0] ? fromIdentityProviderRow(rows[0]) : null;
+	}
+
+	async deleteIdentityProvider(tenantId: string, id: string): Promise<boolean> {
+		const affected = await this.#exec(tenantId, {
+			text: 'DELETE FROM auth_identity_providers WHERE tenant_id = $1 AND id = $2',
+			parameters: [tenantId, id],
+		});
+		return affected > 0;
+	}
+
+	async revokeMembershipApiTokens(
+		tenantId: string,
+		accountId: string,
+		revokedAt: number,
+		revokedBy: string,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `UPDATE auth_api_tokens SET revoked_at = $1, revoked_by = $2
+			       WHERE tenant_id = $3 AND account_id = $4 AND revoked_at IS NULL`,
+			parameters: [revokedAt, revokedBy, tenantId, accountId],
+		});
+	}
+
+	async setMembershipStatus(
+		accountId: string,
+		tenantId: string,
+		status: MembershipStatus,
+	): Promise<boolean> {
+		const affected = await this.#exec(tenantId, {
+			text: `UPDATE auth_memberships SET status = $1
+			       WHERE account_id = $2 AND tenant_id = $3`,
+			parameters: [status, accountId, tenantId],
+		});
+		return affected > 0;
+	}
+
 	async findSignInFailure(
 		normalizedEmail: string,
 	): Promise<SignInFailureRecord | null> {
@@ -1518,8 +2152,8 @@ export class DatabaseAuthRepository implements AuthRepository {
 		const row = rows[0];
 		return row
 			? {
-					failures: integer(row.failures),
-					lockedUntil: optionalInteger(row.locked_until),
+					failures: integer(row.failures, 'failures'),
+					lockedUntil: optionalInteger(row.locked_until, 'locked_until'),
 				}
 			: null;
 	}
@@ -1550,12 +2184,13 @@ export class DatabaseAuthRepository implements AuthRepository {
 				parameters: [normalizedEmail],
 			});
 			const previous = current.rows[0];
-			const failures = (previous ? integer(previous.failures) : 0) + 1;
+			const failures =
+				(previous ? integer(previous.failures, 'failures') : 0) + 1;
 			const lockedUntil =
 				failures >= lockThreshold
 					? now + lockMs
 					: previous
-						? optionalInteger(previous.locked_until)
+						? optionalInteger(previous.locked_until, 'locked_until')
 						: null;
 			await transaction.execute({
 				text: `INSERT INTO auth_sign_in_failures
@@ -1693,21 +2328,23 @@ export class DatabaseAuthRepository implements AuthRepository {
 			       WHERE tenant_id = $1 AND role_id = $2`,
 			parameters: [tenantId, roleId],
 		});
-		return rows[0] ? integer(rows[0].total) : 0;
+		return rows[0] ? integer(rows[0].total, 'total') : 0;
 	}
 
 	async appendAudit(record: AuditRecord): Promise<void> {
 		await this.#exec(record.tenantId, {
 			text: `INSERT INTO auth_audit
 			       (tenant_id, actor_account_id, actor_label, actor_kind, actor_run_id,
-			        action, subject_type, subject_id, metadata_json, occurred_at)
-			       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+			        configured_by_json, action, subject_type, subject_id, metadata_json,
+			        occurred_at)
+			       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
 			parameters: [
 				record.tenantId,
 				record.actorAccountId,
 				record.actorLabel,
 				record.actorKind,
 				record.actorRunId,
+				record.configuredBy ? JSON.stringify(record.configuredBy) : null,
 				record.action,
 				record.subjectType,
 				record.subjectId,
@@ -1725,6 +2362,16 @@ export class DatabaseAuthRepository implements AuthRepository {
 			return `$${parameters.length}`;
 		};
 		if (query.action) conditions.push(`action = ${marker(query.action)}`);
+		/* The window is inclusive and each end is independent, so a caller asks
+		   for a date range instead of seeding the cursor at its ceiling and
+		   watching every page for the floor. It composes with the filters and the
+		   keyset rather than replacing any of them. */
+		if (query.from !== undefined && query.from !== null) {
+			conditions.push(`occurred_at >= ${marker(query.from)}`);
+		}
+		if (query.to !== undefined && query.to !== null) {
+			conditions.push(`occurred_at <= ${marker(query.to)}`);
+		}
 		if (query.actor) {
 			conditions.push(
 				`(actor_account_id = ${marker(query.actor)} OR actor_label = ${marker(query.actor)})`,
@@ -1744,20 +2391,155 @@ export class DatabaseAuthRepository implements AuthRepository {
 			parameters,
 		});
 		return rows.map((row) => ({
-			id: integer(row.id),
+			id: integer(row.id, 'id'),
 			tenantId: row.tenant_id,
 			actorAccountId: row.actor_account_id,
 			actorLabel: row.actor_label,
 			actorKind: row.actor_kind,
 			actorRunId: row.actor_run_id,
+			configuredBy: row.configured_by_json
+				? (JSON.parse(row.configured_by_json) as UserActor)
+				: null,
+			action: row.action,
+			subjectType: row.subject_type,
+			subjectId: row.subject_id,
+			metadata: JSON.parse(row.metadata_json) as Record<string, unknown>,
+			occurredAt: integer(row.occurred_at, 'occurred_at'),
+		}));
+	}
+
+	async exportSessionsPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly SessionExportRecord[]> {
+		const rows = await this.#query<SessionExportRow>(tenantId, {
+			text: `SELECT id, tenant_id, account_id, created_at, expires_at,
+			       last_seen_at
+			       FROM auth_sessions
+			       WHERE tenant_id = $1 AND id > $2
+			       ORDER BY id LIMIT $3`,
+			parameters: [tenantId, afterId, limit],
+		});
+		return rows.map((row) => ({
+			id: row.id,
+			tenantId: row.tenant_id,
+			accountId: row.account_id,
+			createdAt: integer(row.created_at, 'created_at'),
+			expiresAt: integer(row.expires_at, 'expires_at'),
+			lastSeenAt: integer(row.last_seen_at, 'last_seen_at'),
+		}));
+	}
+
+	async deleteSessionsExpiredBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `DELETE FROM auth_sessions WHERE token_hash IN (
+			         SELECT token_hash FROM auth_sessions
+			         WHERE tenant_id = $1 AND expires_at < $2
+			         ORDER BY expires_at LIMIT $3)`,
+			parameters: [tenantId, before, limit],
+		});
+	}
+
+	async exportApiTokensPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly ApiTokenRecord[]> {
+		const rows = await this.#query<ApiTokenRow>(tenantId, {
+			text: `SELECT * FROM auth_api_tokens
+			       WHERE tenant_id = $1 AND id > $2
+			       ORDER BY id LIMIT $3`,
+			parameters: [tenantId, afterId, limit],
+		});
+		return rows.map(fromApiTokenRow);
+	}
+
+	async deleteApiTokensRetiredBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `DELETE FROM auth_api_tokens WHERE id IN (
+			         SELECT id FROM auth_api_tokens
+			         WHERE tenant_id = $1
+			           AND (revoked_at < $2 OR expires_at < $2)
+			         ORDER BY id LIMIT $3)`,
+			parameters: [tenantId, before, limit],
+		});
+	}
+
+	async exportAuditEventsPage(
+		tenantId: string,
+		afterId: number,
+		limit: number,
+	): Promise<readonly AuditEvent[]> {
+		const rows = await this.#query<AuditRow>(tenantId, {
+			text: `SELECT * FROM auth_audit
+			       WHERE tenant_id = $1 AND id > $2
+			       ORDER BY id LIMIT $3`,
+			parameters: [tenantId, afterId, limit],
+		});
+		return rows.map((row) => ({
+			id: integer(row.id, 'id'),
+			tenantId: row.tenant_id,
+			actorAccountId: row.actor_account_id,
+			actorLabel: row.actor_label,
 			action: row.action,
 			subjectType: row.subject_type,
 			subjectId: row.subject_id,
 			metadata: JSON.parse(row.metadata_json) as Record<string, unknown>,
-			occurredAt: integer(row.occurred_at),
+			occurredAt: integer(row.occurred_at, 'occurred_at'),
 		}));
 	}
 
+	async deleteAuditEventsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `DELETE FROM auth_audit WHERE id IN (
+			         SELECT id FROM auth_audit
+			         WHERE tenant_id = $1 AND occurred_at < $2
+			         ORDER BY occurred_at LIMIT $3)`,
+			parameters: [tenantId, before, limit],
+		});
+	}
+
+	async deleteMembershipSessionsOf(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `DELETE FROM auth_sessions WHERE token_hash IN (
+			         SELECT token_hash FROM auth_sessions
+			         WHERE tenant_id = $1 AND account_id = $2
+			         ORDER BY token_hash LIMIT $3)`,
+			parameters: [tenantId, accountId, limit],
+		});
+	}
+
+	async deleteMembershipApiTokensOf(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number> {
+		return this.#exec(tenantId, {
+			text: `DELETE FROM auth_api_tokens WHERE id IN (
+			         SELECT id FROM auth_api_tokens
+			         WHERE tenant_id = $1 AND account_id = $2
+			         ORDER BY id LIMIT $3)`,
+			parameters: [tenantId, accountId, limit],
+		});
+	}
+
 	async loadSettings(
 		tenantId: string,
 		moduleId: string,