@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/auth/ensure-tables.ts

@@ -1,7 +1,10 @@
 import { sql } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { logger } from "@rebasepro/server";
+import { revokeInternalTableAccess } from "@rebasepro/common";
 import type { CollectionConfig } from "@rebasepro/types";
+import { AUTH_USERS_COLUMNS, authUsersColumnSql } from "../schema/auth-users-columns";
+import { RLS_BOOTSTRAP_STATEMENTS } from "../schema/rls-bootstrap-sql";
 import {
     AuthSchemaVersionError,
     assertAuthSchemaCompatible,
@@ -44,13 +47,23 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 ? `"${resolvedTable}"`
                 : `"${usersSchema}"."${resolvedTable}"`;
 
-            // Derive ID column type from collection properties
+            // Derive ID column type from collection properties.
+            //
+            // `"increment"`, not `"autoincrement"`. The latter was tested for
+            // here and exists nowhere in the type system — the union is
+            // `boolean | "manual" | "increment" | string` — so the INTEGER branch
+            // was unreachable and an integer-keyed auth collection fell through
+            // to TEXT. Introspection below hid it whenever the table already
+            // existed; on a database where it did not, this created
+            // `id TEXT DEFAULT gen_random_uuid()::text` for a collection that
+            // declares a number, and every `uid` foreign key was typed to match
+            // the wrong thing.
             const idProp = collection.properties?.id;
             if (idProp) {
                 const isId = ("isId" in idProp) ? (idProp as unknown as Record<string, unknown>).isId : undefined;
                 if (isId === "uuid") {
                     userIdType = "UUID";
-                } else if (isId === "autoincrement") {
+                } else if (isId === "increment") {
                     userIdType = "INTEGER";
                 }
                 // Otherwise keep TEXT as default
@@ -129,22 +142,24 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // and long signed URLs that OAuth providers hand back. A limit worth
         // having is a CHECK — alterable without a table rewrite, unlike a type
         // modifier — which is why `email` has one and nothing else does.
+        //
+        // The column list comes from AUTH_USERS_COLUMNS rather than being spelled
+        // out here, because this is not the only place that creates this table:
+        // `db push` and the boot-time collection ensure do too, and when the
+        // three lists were maintained separately they disagreed and boot order
+        // silently decided which shape the database got. The `email` CHECK is
+        // appended rather than listed there — it is a named constraint the
+        // migration below has to be able to add separately, `NOT VALID`, to a
+        // table that already holds rows.
+        const usersColumnDdl = AUTH_USERS_COLUMNS
+            .map((spec) => spec.column === "email"
+                ? `${spec.column} ${authUsersColumnSql(spec)} CONSTRAINT ${emailLengthConstraint} CHECK (length(email) <= 320)`
+                : `${spec.column} ${authUsersColumnSql(spec)}`)
+            .join(",\n                ");
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(usersTableName)} (
                 id ${sql.raw(userIdType)} PRIMARY KEY ${sql.raw(idDefault)},
-                email TEXT NOT NULL CONSTRAINT ${sql.raw(emailLengthConstraint)} CHECK (length(email) <= 320),
-                display_name TEXT,
-                photo_url TEXT,
-                roles TEXT[] DEFAULT '{}' NOT NULL,
-                password_hash TEXT,
-                email_verified BOOLEAN DEFAULT FALSE NOT NULL,
-                email_verification_token TEXT,
-                email_verification_sent_at TIMESTAMP WITH TIME ZONE,
-                is_anonymous BOOLEAN DEFAULT FALSE NOT NULL,
-                metadata JSONB DEFAULT '{}' NOT NULL,
-                tokens_valid_after TIMESTAMP WITH TIME ZONE,
-                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
-                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+                ${sql.raw(usersColumnDdl)}
             )
         `);
 
@@ -164,26 +179,51 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // column once no old backend remains (phase 2, contract).
         //
         // Idempotent throughout: every step is guarded on catalogue state.
-        await db.execute(sql`
-            CREATE OR REPLACE FUNCTION ${sql.raw(`"${authSchema}"`)}.sync_uid_user_id() RETURNS trigger AS $$
-            BEGIN
-                IF NEW.uid IS NULL AND NEW.user_id IS NOT NULL THEN
-                    NEW.uid := NEW.user_id;
-                ELSIF NEW.user_id IS NULL AND NEW.uid IS NOT NULL THEN
-                    NEW.user_id := NEW.uid;
-                END IF;
-                RETURN NEW;
-            END $$ LANGUAGE plpgsql
-        `);
-
-        for (const authTable of [
+        const legacyFkTables = [
             "user_identities",
             "refresh_tokens",
             "password_reset_tokens",
             "magic_link_tokens",
             "mfa_factors",
             "recovery_codes"
-        ]) {
+        ];
+
+        // Only on a database that actually carries the legacy column. This whole
+        // block is a 0.x compatibility shim, and it used to run unconditionally —
+        // so every brand-new database was provisioned with a trigger function
+        // written to reconcile a column it can never have, permanently, as part
+        // of its first boot. A fresh install should not ship someone else's
+        // migration history.
+        // The table list is inlined rather than bound: drizzle expands a JS
+        // array into a parameter TUPLE — `ANY(($2, $3, …))` — which Postgres
+        // rejects, and the thrown error is swallowed by the catch around this
+        // whole function, so auth would silently stop provisioning. These are
+        // module-level constants, not input.
+        const legacyFkTableList = legacyFkTables.map(t => `'${t}'`).join(", ");
+        const legacyUserIdPresent = await db.execute(sql`
+            SELECT 1
+            FROM information_schema.columns
+            WHERE table_schema = ${authSchema}
+              AND table_name IN (${sql.raw(legacyFkTableList)})
+              AND column_name = 'user_id'
+            LIMIT 1
+        `);
+
+        if (legacyUserIdPresent.rows.length > 0) {
+            await db.execute(sql`
+                CREATE OR REPLACE FUNCTION ${sql.raw(`"${authSchema}"`)}.sync_uid_user_id() RETURNS trigger AS $$
+                BEGIN
+                    IF NEW.uid IS NULL AND NEW.user_id IS NOT NULL THEN
+                        NEW.uid := NEW.user_id;
+                    ELSIF NEW.user_id IS NULL AND NEW.uid IS NOT NULL THEN
+                        NEW.user_id := NEW.uid;
+                    END IF;
+                    RETURN NEW;
+                END $$ LANGUAGE plpgsql
+            `);
+        }
+
+        for (const authTable of legacyUserIdPresent.rows.length > 0 ? legacyFkTables : []) {
             const qualified = `"${authSchema}"."${authTable}"`;
             await db.execute(sql`
                 DO $$
@@ -335,39 +375,21 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             )
         `);
 
-        // Create the `auth` schema with PostgreSQL RLS helper functions.
-        await db.execute(sql`CREATE SCHEMA IF NOT EXISTS auth`);
-
-        // Use an advisory transaction lock to serialize function recreation during HMR
+        // The RLS helper functions every generated policy calls. They live in
+        // `rebase`, alongside the tables above — Rebase creates exactly one
+        // schema in a user's database. Advisory-locked so concurrent HMR
+        // reloads cannot race on `CREATE OR REPLACE`.
+        //
+        // The same statements the migration preamble carries, from the same
+        // constant — these definitions being identical across the boot path and
+        // the migration stream is the whole point of having them in one place.
+        // One call per statement: this handle speaks the extended query
+        // protocol, which rejects multi-command strings.
         await db.transaction(async (tx) => {
             await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext('rebase_auth_functions_init'))`);
-
-            // Falls back to the pre-rename `app.user_id` so a database that has
-            // taken the new schema but is still served by an older backend keeps
-            // resolving the principal. Keep in sync with AUTH_BOOTSTRAP_SQL.
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$
-                    SELECT COALESCE(
-                        NULLIF(current_setting('app.uid', true), ''),
-                        NULLIF(current_setting('app.user_id', true), '')
-                    );
-                $$ LANGUAGE sql STABLE
-            `);
-
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$
-                    SELECT COALESCE(
-                        NULLIF(current_setting('app.jwt', true), ''),
-                        '{}'
-                    )::jsonb;
-                $$ LANGUAGE sql STABLE
-            `);
-
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$
-                    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');
-                $$ LANGUAGE sql STABLE
-            `);
+            for (const statement of RLS_BOOTSTRAP_STATEMENTS) {
+                await tx.execute(sql.raw(statement));
+            }
         });
 
         // Seed default roles if none exist
@@ -378,26 +400,16 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // database provisioned by an older framework era is missing every
         // column added since. Each column the auth services read or write must
         // be back-filled here, or upgraded deployments break on the first
-        // statement that references it. `email` is deliberately absent: it has
-        // existed since the first era and cannot be added NOT NULL safely.
-        const userColumnBackfills = [
-            "display_name TEXT",
-            "photo_url TEXT",
-            "roles TEXT[] DEFAULT '{}' NOT NULL",
-            "password_hash TEXT",
-            "email_verified BOOLEAN DEFAULT FALSE NOT NULL",
-            "email_verification_token TEXT",
-            "email_verification_sent_at TIMESTAMP WITH TIME ZONE",
-            "is_anonymous BOOLEAN DEFAULT FALSE NOT NULL",
-            "metadata JSONB DEFAULT '{}' NOT NULL",
-            "tokens_valid_after TIMESTAMP WITH TIME ZONE",
-            "created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL",
-            "updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL"
-        ];
-        for (const columnDef of userColumnBackfills) {
+        // statement that references it.
+        //
+        // `email` is skipped: it has existed since the first era, so it is never
+        // the missing one, and `ADD COLUMN … NOT NULL` with no default fails on
+        // a table with rows.
+        for (const spec of AUTH_USERS_COLUMNS) {
+            if (spec.column === "email") continue;
             await db.execute(sql`
                 ALTER TABLE ${sql.raw(usersTableName)}
-                ADD COLUMN IF NOT EXISTS ${sql.raw(columnDef)}
+                ADD COLUMN IF NOT EXISTS ${sql.raw(`${spec.column} ${authUsersColumnSql(spec)}`)}
             `);
         }
 
@@ -407,14 +419,69 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // statement past this point has to tolerate that rather than abort the
         // whole migration block.
         const usersColumns = await db.execute(sql`
-            SELECT column_name, data_type
+            SELECT column_name, data_type, is_nullable, column_default
             FROM information_schema.columns
             WHERE table_schema = ${usersSchema} AND table_name = ${resolvedTable}
         `);
-        const usersColumnTypes = new Map(
-            (usersColumns.rows as { column_name: string; data_type: string }[])
-                .map(row => [row.column_name, row.data_type])
-        );
+        type UsersColumnRow = {
+            column_name: string;
+            data_type: string;
+            is_nullable: "YES" | "NO";
+            column_default: string | null;
+        };
+        const usersColumnRows = usersColumns.rows as UsersColumnRow[];
+        const usersColumnTypes = new Map(usersColumnRows.map(row => [row.column_name, row.data_type]));
+        const usersColumnState = new Map(usersColumnRows.map(row => [row.column_name, row]));
+
+        // ── Migration: restore defaults and NOT NULL that another creator dropped ──
+        // `ADD COLUMN IF NOT EXISTS` above only creates what is MISSING. A column
+        // that exists with the wrong shape stays wrong forever — and until
+        // AUTH_USERS_COLUMNS became the single source, that was the normal
+        // outcome rather than an edge case: whichever of `db push`, boot-ensure
+        // and this function reached the table first decided its constraints, so
+        // a managed deploy ended up with a nullable `email`, a `roles` with no
+        // `'{}'` default, and an `email_verified` that could be NULL.
+        //
+        // Ordered DEFAULT → back-fill → SET NOT NULL, because SET NOT NULL is
+        // checked against existing rows: without the back-fill it throws on the
+        // very databases that need it. `email` can carry no default, so a NULL
+        // there is not repairable automatically — say so and leave the column
+        // alone rather than inventing an address.
+        for (const spec of AUTH_USERS_COLUMNS) {
+            const state = usersColumnState.get(spec.column);
+            if (!state) continue;
+
+            if (spec.default !== undefined && state.column_default === null) {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ALTER COLUMN ${sql.raw(`"${spec.column}"`)} SET DEFAULT ${sql.raw(spec.default)}
+                `);
+                logger.info(`🔧 Restored the default on ${usersTableName}.${spec.column}`);
+            }
+
+            if (!spec.notNull || state.is_nullable !== "YES") continue;
+
+            if (spec.default !== undefined) {
+                await db.execute(sql`
+                    UPDATE ${sql.raw(usersTableName)}
+                    SET ${sql.raw(`"${spec.column}"`)} = ${sql.raw(spec.default)}
+                    WHERE ${sql.raw(`"${spec.column}"`)} IS NULL
+                `);
+            }
+            try {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ALTER COLUMN ${sql.raw(`"${spec.column}"`)} SET NOT NULL
+                `);
+                logger.info(`🔧 Restored NOT NULL on ${usersTableName}.${spec.column}`);
+            } catch (err) {
+                logger.warn(
+                    `⚠️ ${usersTableName}.${spec.column} should be NOT NULL but still holds NULLs, so the ` +
+                    "constraint was not applied. Fill or remove those rows and restart: " +
+                    (err instanceof Error ? err.message : String(err))
+                );
+            }
+        }
 
         // ── Migration: VARCHAR(n) → TEXT on the users string columns ────────
         // Tables created before the widths came off still carry them. Postgres
@@ -574,6 +641,12 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                     await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS revoked BOOLEAN DEFAULT FALSE NOT NULL`);
                     await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS rotated_at TIMESTAMP WITH TIME ZONE`);
                     await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS session_started_at TIMESTAMP WITH TIME ZONE`);
+                    // Nullable with no default and no back-fill: a row written
+                    // before this column existed says nothing about whether a
+                    // second factor was presented, and the reader treats "says
+                    // nothing" as `aal1` — the restrictive answer. Stamping
+                    // every existing row would be inventing evidence.
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS aal TEXT`);
 
                     // One session per pre-existing row: under the old model a row
                     // WAS a device session, and there is no record of which rows
@@ -663,6 +736,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 secret_encrypted TEXT NOT NULL,
                 friendly_name TEXT,
                 verified BOOLEAN DEFAULT FALSE,
+                last_used_counter BIGINT,
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
             )
@@ -682,6 +756,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 verified_at TIMESTAMP WITH TIME ZONE,
                 ip_address TEXT,
+                attempts INTEGER NOT NULL DEFAULT 0,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL
             )
         `);
@@ -692,6 +767,20 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             ON ${sql.raw(mfaChallengesTableName)}(factor_id)
         `);
 
+        // ── Migration: replay and brute-force state on the MFA tables ───────
+        // Both are additive and nullable-or-defaulted, so a runtime that
+        // predates them reads the tables unchanged. `last_used_counter` records
+        // the TOTP step a factor has already spent (RFC 6238 §5.2); `attempts`
+        // bounds how many guesses one challenge will take before it is dead.
+        // Without them the code paths degrade to "no replay protection, rate
+        // limiters only" rather than failing, which is why this is a warn.
+        try {
+            await db.execute(sql`ALTER TABLE ${sql.raw(mfaFactorsTableName)} ADD COLUMN IF NOT EXISTS last_used_counter BIGINT`);
+            await db.execute(sql`ALTER TABLE ${sql.raw(mfaChallengesTableName)} ADD COLUMN IF NOT EXISTS attempts INTEGER NOT NULL DEFAULT 0`);
+        } catch (mfaMigrationError: unknown) {
+            logger.warn(`⚠️  MFA hardening columns skipped: ${mfaMigrationError instanceof Error ? mfaMigrationError.message : String(mfaMigrationError)}`);
+        }
+
         // Create recovery_codes table
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(recoveryCodesTableName)} (
@@ -717,15 +806,22 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // registration after an upgrade fails with SQLSTATE 42501. Reconcile
         // on boot; only tables actually flagged get the ALTER (and its lock).
         try {
+            // Every table this function creates, not a subset. `magic_link_tokens`
+            // and `schema_meta` were missing here while their six siblings were
+            // listed — so on a database carrying FORCE from the older RLS model,
+            // magic-link sign-in kept failing 42501 after the upgrade that was
+            // supposed to fix exactly that, and only for the one auth method.
             const authTablePairs: [string, string][] = [
                 [usersSchema, resolvedTable],
                 [authSchema, "user_identities"],
                 [authSchema, "refresh_tokens"],
                 [authSchema, "password_reset_tokens"],
+                [authSchema, "magic_link_tokens"],
                 [authSchema, "app_config"],
                 [authSchema, "mfa_factors"],
                 [authSchema, "mfa_challenges"],
-                [authSchema, "recovery_codes"]
+                [authSchema, "recovery_codes"],
+                [authSchema, "schema_meta"]
             ];
             for (const [schemaName, tableName] of authTablePairs) {
                 const forced = await db.execute(sql`
@@ -756,10 +852,35 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             );
         }
 
-        // Stamped last, so a boot that died partway through the migrations above
-        // leaves the older stamp in place and the next boot runs them again.
+        // Stamped last of the MIGRATIONS, so a boot that died partway through
+        // the ones above leaves the older stamp in place and the next boot runs
+        // them again.
         await stampAuthSchemaVersion(db, authSchema);
 
+        // ── Keep the end-user role out of auth's tables ─────────────────────
+        // These carry session token hashes, TOTP secrets and recovery codes, and
+        // none of them has RLS — they are not collections, so nothing ever
+        // compiled a policy for them. Meanwhile the role provisioning grants
+        // `rebase_user` DML on every table in this schema, and its
+        // ALTER DEFAULT PRIVILEGES reaches the ones created right here, after it
+        // ran. So the grant has to come back off; see `revokeInternalTableSql`
+        // for why a revoke rather than an empty RLS policy set.
+        //
+        // After the stamp deliberately: `schema_meta` is created BY the stamp,
+        // so revoking first would leave the one table holding this database's
+        // schema version writable by every signed-in user until the next boot.
+        // Nothing below re-runs the migrations, so the stamp's guarantee holds.
+        await revokeInternalTableAccess(
+            async (text) => { await db.execute(sql.raw(text)); },
+            authSchema,
+            {
+                onError: (table, err) => logger.warn(
+                    `🔐 Could not revoke authenticated-role access to "${authSchema}"."${table}": ` +
+                    (err instanceof Error ? err.message : String(err))
+                )
+            }
+        );
+
         logger.info("✅ Auth tables ready");
     } catch (error) {
         // The one failure that must not be survived. Continuing here is what

package/src/auth/services.ts

@@ -25,6 +25,7 @@ import {
     RoleData as Role
 } from "@rebasepro/server";
 import { toSnakeCase, camelCase } from "@rebasepro/utils";
+import { escapeLikePattern } from "../utils/drizzle-conditions";
 
 export type { Role };
 
@@ -368,7 +369,11 @@ export class UserService implements UserRepository {
             conditions.push(sql`${roleId} = ANY(${sql.raw(usersTableName)}.roles)`);
         }
         if (search) {
-            const pattern = `%${search}%`;
+            // `search` is a substring search over the admin user list, not a
+            // pattern the caller writes: the same reasoning as the collection
+            // search path, so it shares that path's helper rather than growing
+            // a second copy that can drift. See `escapeLikePattern`.
+            const pattern = `%${escapeLikePattern(search)}%`;
             conditions.push(sql`(${sql.raw(usersTableName)}.${sql.raw(emailColumn)} ILIKE ${pattern} OR ${sql.raw(usersTableName)}.${sql.raw(displayNameColumn)} ILIKE ${pattern})`);
         }
 
@@ -591,7 +596,7 @@ export class RefreshTokenService {
             userAgent: this.refreshTokensTable.userAgent,
             ipAddress: this.refreshTokensTable.ipAddress
         } as unknown as Record<string, never>;
-        for (const optional of ["sessionId", "rotatedAt", "revoked", "sessionStartedAt"]) {
+        for (const optional of ["sessionId", "rotatedAt", "revoked", "sessionStartedAt", "aal"]) {
             if (this.has(optional)) selection[optional] = this.col(optional);
         }
         return selection;
@@ -624,6 +629,11 @@ export class RefreshTokenService {
         };
         if (session && this.has("sessionId")) values.sessionId = session.id;
         if (session && this.has("sessionStartedAt")) values.sessionStartedAt = session.startedAt;
+        // Written on every token of the session, including the ones rotation
+        // mints, because refresh reads the level off whichever row was
+        // presented. A table without the column degrades to `aal1` on read,
+        // which is the restrictive answer rather than a bypass.
+        if (session?.aal && this.has("aal")) values.aal = session.aal;
 
         await this.db.insert(this.refreshTokensTable).values(values);
     }
@@ -1297,6 +1307,14 @@ collectionPermissions: null }
     async hasVerifiedMfaFactors(uid: string): Promise<boolean> {
         return this.getMfaService().hasVerifiedMfaFactors(uid);
     }
+
+    async claimMfaFactorCounter(factorId: string, counter: number): Promise<boolean> {
+        return this.getMfaService().claimMfaFactorCounter(factorId, counter);
+    }
+
+    async recordMfaChallengeAttempt(challengeId: string): Promise<number> {
+        return this.getMfaService().recordMfaChallengeAttempt(challengeId);
+    }
 }
 
 // =============================================================================
@@ -1362,7 +1380,7 @@ export class MfaService implements MfaRepository {
     async getMfaFactorById(factorId: string): Promise<(MfaFactor & { secretEncrypted: string }) | null> {
         const tableName = this.qualify("mfa_factors");
         const result = await this.db.execute(sql`
-            SELECT id, uid, factor_type, secret_encrypted, friendly_name, verified, created_at, updated_at
+            SELECT id, uid, factor_type, secret_encrypted, friendly_name, verified, last_used_counter, created_at, updated_at
             FROM ${sql.raw(tableName)}
             WHERE id = ${factorId}
         `);
@@ -1377,11 +1395,36 @@ export class MfaService implements MfaRepository {
             secretEncrypted: row.secret_encrypted as string,
             friendlyName: (row.friendly_name as string | null) ?? undefined,
             verified: row.verified as boolean,
+            // BIGINT comes back as a string from node-postgres.
+            lastUsedCounter: row.last_used_counter === null || row.last_used_counter === undefined
+                ? null
+                : Number(row.last_used_counter),
             createdAt: new Date(row.created_at as string),
             updatedAt: new Date(row.updated_at as string)
         };
     }
 
+    /**
+     * Spend a TOTP time step, once and only once.
+     *
+     * One statement: the `WHERE` is the check, the `UPDATE` is the act, and
+     * `RETURNING` reports which of two concurrent requests carrying the same
+     * six digits won. Reading the counter and then writing it would let both
+     * pass — the exact replay this closes.
+     */
+    async claimMfaFactorCounter(factorId: string, counter: number): Promise<boolean> {
+        const tableName = this.qualify("mfa_factors");
+        const result = await this.db.execute(sql`
+            UPDATE ${sql.raw(tableName)}
+            SET last_used_counter = ${counter}, updated_at = NOW()
+            WHERE id = ${factorId}
+              AND (last_used_counter IS NULL OR last_used_counter < ${counter})
+            RETURNING id
+        `);
+
+        return result.rows.length > 0;
+    }
+
     async verifyMfaFactor(factorId: string): Promise<void> {
         const tableName = this.qualify("mfa_factors");
         await this.db.execute(sql`
@@ -1422,7 +1465,7 @@ export class MfaService implements MfaRepository {
     async getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null> {
         const tableName = this.qualify("mfa_challenges");
         const result = await this.db.execute(sql`
-            SELECT id, factor_id, created_at, verified_at, ip_address, expires_at
+            SELECT id, factor_id, created_at, verified_at, ip_address, attempts, expires_at
             FROM ${sql.raw(tableName)}
             WHERE id = ${challengeId} AND expires_at > NOW() AND verified_at IS NULL
         `);
@@ -1435,10 +1478,31 @@ export class MfaService implements MfaRepository {
             factorId: row.factor_id as string,
             createdAt: new Date(row.created_at as string),
             verifiedAt: row.verified_at ? new Date(row.verified_at as string) : undefined,
-            ipAddress: (row.ip_address as string | null) ?? undefined
+            ipAddress: (row.ip_address as string | null) ?? undefined,
+            attempts: Number(row.attempts ?? 0)
         };
     }
 
+    /**
+     * Count one failed guess against a challenge and report the new total.
+     *
+     * Incremented in the database rather than in the route so that guesses
+     * arriving in parallel — the shape any real brute-force takes — cannot
+     * share a single increment.
+     */
+    async recordMfaChallengeAttempt(challengeId: string): Promise<number> {
+        const tableName = this.qualify("mfa_challenges");
+        const result = await this.db.execute(sql`
+            UPDATE ${sql.raw(tableName)}
+            SET attempts = attempts + 1
+            WHERE id = ${challengeId}
+            RETURNING attempts
+        `);
+
+        if (result.rows.length === 0) return 0;
+        return Number((result.rows[0] as { attempts: number | string }).attempts);
+    }
+
     async verifyMfaChallenge(challengeId: string): Promise<void> {
         const tableName = this.qualify("mfa_challenges");
         await this.db.execute(sql`