@rebasepro/server-postgres 0.9.1-canary.ff338b5 → 0.10.1-canary.18115ba

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgres",
   "type": "module",
-  "version": "0.9.1-canary.ff338b5",
+  "version": "0.10.1-canary.18115ba",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,30 +29,6 @@
     "backend",
     "rebase"
   ],
-  "jest": {
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
-    "testPathIgnorePatterns": [
-      "/node_modules/",
-      "test/e2e/"
-    ],
-    "moduleFileExtensions": [
-      "ts",
-      "tsx",
-      "js",
-      "jsx",
-      "json",
-      "node"
-    ],
-    "moduleNameMapper": {
-      "^chalk$": "<rootDir>/test/mocks/chalk.cjs",
-      "^\\.{1,2}/module-dir$": "<rootDir>/test/mocks/module-dir.cjs",
-      "^@rebasepro/([a-z0-9-]+)$": "<rootDir>/../$1/src/index.ts",
-      "^(\\.{1,2}/.*)\\.js$": "$1"
-    }
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -71,11 +47,11 @@
     "execa": "^9.6.1",
     "pg": "^8.21.0",
     "ws": "^8.21.0",
-    "@rebasepro/server": "0.9.1-canary.ff338b5",
-    "@rebasepro/types": "0.9.1-canary.ff338b5",
-    "@rebasepro/codegen": "0.9.1-canary.ff338b5",
-    "@rebasepro/common": "0.9.1-canary.ff338b5",
-    "@rebasepro/utils": "0.9.1-canary.ff338b5"
+    "@rebasepro/codegen": "0.10.1-canary.18115ba",
+    "@rebasepro/common": "0.10.1-canary.18115ba",
+    "@rebasepro/utils": "0.10.1-canary.18115ba",
+    "@rebasepro/server": "0.10.1-canary.18115ba",
+    "@rebasepro/types": "0.10.1-canary.18115ba"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.9",
@@ -104,7 +80,7 @@
     "watch": "vite build --watch",
     "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests",
+    "test": "jest",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
     "smoke:baas": "tsx scripts/smoke-baas.ts"

package/src/PostgresBackendDriver.ts

@@ -111,6 +111,7 @@ export class PostgresBackendDriver implements DataDriver {
             executeSql: (...args: Parameters<NonNullable<DatabaseAdmin["executeSql"]>>) => this.executeSql(...args),
             fetchAvailableDatabases: () => this.fetchAvailableDatabases(),
             fetchAvailableRoles: () => this.fetchAvailableRoles(),
+            fetchApplicationRoles: () => this.fetchApplicationRoles(),
             fetchCurrentDatabase: () => this.fetchCurrentDatabase(),
             fetchUnmappedTables: (...args: Parameters<NonNullable<DatabaseAdmin["fetchUnmappedTables"]>>) => this.fetchUnmappedTables(...args),
             fetchTableMetadata: (...args: Parameters<NonNullable<DatabaseAdmin["fetchTableMetadata"]>>) => this.fetchTableMetadata(...args),
@@ -1171,6 +1172,56 @@ export class PostgresBackendDriver implements DataDriver {
         return result.map((r: Record<string, unknown>) => r.rolname as string);
     }
 
+    /**
+     * Application-level roles actually in use in this project.
+     *
+     * Distinct from {@link fetchAvailableRoles}, which returns native
+     * PostgreSQL roles from `pg_roles` (`postgres`, `rebase_user`, …). Those
+     * are the roles the SQL editor can `SET ROLE` to. *These* are the strings
+     * held in the users table's `roles` column, injected per-transaction as
+     * `auth.roles()` and matched by `SecurityRule.roles`. Feeding the pg roles
+     * into a `SecurityRule.roles` field produces a condition no user can ever
+     * satisfy, so the two must not be conflated.
+     *
+     * Roles have no registry table — they were migrated out of
+     * `rebase.user_roles` onto an inline `roles TEXT[]` column — so the live
+     * set is derived from what is assigned. A role that is declared in a policy
+     * but held by nobody yet cannot be discovered here; callers that need it
+     * should union in the roles they already know about.
+     */
+    async fetchApplicationRoles(): Promise<string[]> {
+        // The users table lives in `rebase` for a default (public) setup, but
+        // follows the configured schema otherwise — locate it rather than
+        // assuming. The `roles` ARRAY column is what makes it the auth table.
+        const located = await this.executeSql(`
+            SELECT table_schema, table_name
+            FROM information_schema.columns
+            WHERE column_name = 'roles'
+              AND data_type = 'ARRAY'
+              AND table_name = 'users'
+              AND table_schema NOT IN ('information_schema', 'pg_catalog')
+            ORDER BY (table_schema = 'rebase') DESC, table_schema
+            LIMIT 1;
+        `);
+        if (located.length === 0) return [];
+
+        const schema = located[0].table_schema as string;
+        const table = located[0].table_name as string;
+        // Identifiers come from information_schema, not user input, but they
+        // are still interpolated — quote them so odd-but-legal names survive.
+        const qualified = `"${schema.replace(/"/g, "\"\"")}"."${table.replace(/"/g, "\"\"")}"`;
+
+        const rows = await this.executeSql(`
+            SELECT DISTINCT unnest(roles) AS role
+            FROM ${qualified}
+            WHERE roles IS NOT NULL
+            ORDER BY role;
+        `);
+        return rows
+            .map((r) => r.role as string)
+            .filter((r): r is string => typeof r === "string" && r.length > 0);
+    }
+
     async fetchCurrentDatabase(): Promise<string | undefined> {
         return this.poolManager?.defaultDatabaseName;
     }
@@ -1374,10 +1425,10 @@ export class AuthenticatedPostgresBackendDriver implements DataDriver {
         const pendingNotifications: PostgresBackendDriver["_pendingNotifications"] = [];
 
         const result = await this.delegate.db.transaction(async (tx) => {
-            let userId = this.user?.uid;
-            if (!userId) {
+            let uid = this.user?.uid;
+            if (!uid) {
                 logger.warn("[DataDriver] User ID (uid) is missing for authenticated delegate. Using 'anonymous'. User object", { detail: this.user });
-                userId = "anonymous";
+                uid = "anonymous";
             }
 
             const userRoles = this.user?.roles ?? [];
@@ -1396,7 +1447,7 @@ export class AuthenticatedPostgresBackendDriver implements DataDriver {
             //
             // Fails closed: if the switch cannot be performed, the transaction
             // aborts rather than falling back to an RLS-bypassing connection.
-            await applyAuthContext(tx, { userId, roles: userRoles }, this.delegate.rlsUserRole);
+            await applyAuthContext(tx, { uid, roles: userRoles }, this.delegate.rlsUserRole);
 
             const txEntityService = new DataService(tx, this.delegate.registry);
             const txDelegate = new PostgresBackendDriver(tx, this.delegate.realtimeService, this.delegate.registry, this.user, this.delegate.poolManager, this.delegate.historyService);
@@ -1435,7 +1486,7 @@ export class AuthenticatedPostgresBackendDriver implements DataDriver {
      */
     private injectAuthContext(unsubscribe: () => void): () => void {
         const authContext = {
-            userId: this.user?.uid || "anonymous",
+            uid: this.user?.uid || "anonymous",
             roles: this.user?.roles ?? []
         };
         const entries = Array.from(this.delegate.realtimeService.subscriptions.entries());

package/src/PostgresBootstrapper.ts

@@ -17,7 +17,8 @@ import {
     CollectionConfig,
     type HistoryConfig,
     InitializedDriver,
-    RealtimeProvider
+    RealtimeProvider,
+    type RealtimeChannelsConfig
 } from "@rebasepro/types";
 import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import { RealtimeService } from "./services/realtimeService";
@@ -52,6 +53,12 @@ export interface PostgresDriverConfig {
      * (BaaS mode). Defaults to `public`.
      */
     introspectionSchema?: string;
+    /**
+     * Realtime options. Currently only channel retention, which is opt-in:
+     * without rules here no channel keeps any history and broadcast stays
+     * fire-and-forget. See {@link ChannelRetentionRule}.
+     */
+    realtime?: RealtimeChannelsConfig;
 }
 
 /**
@@ -316,6 +323,16 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                 }
             }
 
+            // ── Channel history ──────────────────────────────────────────────
+            // Opt-in per channel pattern. With no rules this creates no tables
+            // and leaves broadcast on its original fire-and-forget path, so
+            // presence-only apps pay nothing for it.
+            try {
+                await realtimeService.configureChannelHistory(pgConfig.realtime?.channels);
+            } catch (err) {
+                logger.warn("⚠️ Could not initialize channel history tables — retained channels will not replay", { error: err });
+            }
+
             // ── Realtime change source ───────────────────────────────────────
             // Prefer DATABASE_DIRECT_URL to bypass PgBouncer for LISTEN/NOTIFY.
             const directUrl = process.env.DATABASE_DIRECT_URL || pgConfig.connectionString;

package/src/auth/ensure-tables.ts

@@ -107,18 +107,93 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 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
             )
         `);
 
+        // ── Migration: auth FK column user_id → uid, phase 1 (expand) ───────
+        // Must run BEFORE the dependent tables below: CREATE TABLE IF NOT
+        // EXISTS never revisits an existing table, so a database provisioned
+        // before this migration still lacks `uid` — and the
+        // CREATE INDEX ... (uid) statements that follow would fail on it.
+        //
+        // Deliberately NOT a plain RENAME. Both Cloud Run and Kubernetes roll
+        // deploys, so old and new pods serve the same database at the same time,
+        // and a rollback puts old code back in front of a migrated database. A
+        // rename breaks every auth query on whichever side is out of step.
+        // Instead: add `uid`, backfill it, drop the NOT NULL on `user_id`, and
+        // keep the two in sync with a trigger, so a backend of either era can
+        // read and write. `scripts/drop-legacy-auth-user-id.sql` removes the
+        // 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 [
+            "user_identities",
+            "refresh_tokens",
+            "password_reset_tokens",
+            "magic_link_tokens",
+            "mfa_factors",
+            "recovery_codes"
+        ]) {
+            const qualified = `"${authSchema}"."${authTable}"`;
+            await db.execute(sql`
+                DO $$
+                DECLARE
+                    has_legacy boolean;
+                    has_uid    boolean;
+                BEGIN
+                    SELECT
+                        bool_or(column_name = 'user_id'),
+                        bool_or(column_name = 'uid')
+                    INTO has_legacy, has_uid
+                    FROM information_schema.columns
+                    WHERE table_schema = ${sql.raw(`'${authSchema}'`)}
+                      AND table_name = ${sql.raw(`'${authTable}'`)};
+
+                    -- Table absent, or already uid-only (a fresh install, or
+                    -- phase 2 already run): nothing to do.
+                    IF has_legacy IS NOT TRUE THEN
+                        RETURN;
+                    END IF;
+
+                    IF has_uid IS NOT TRUE THEN
+                        EXECUTE ${sql.raw(`'ALTER TABLE ${qualified} ADD COLUMN uid ${userIdType} REFERENCES ${usersTableName}(id) ON DELETE CASCADE'`)};
+                        EXECUTE ${sql.raw(`'UPDATE ${qualified} SET uid = user_id WHERE uid IS NULL'`)};
+                        EXECUTE ${sql.raw(`'CREATE INDEX IF NOT EXISTS idx_${authTable}_uid ON ${qualified}(uid)'`)};
+                    END IF;
+
+                    -- New code inserts uid and never user_id, so the legacy
+                    -- column can no longer be NOT NULL. The trigger below
+                    -- backfills it, but the constraint is checked first.
+                    EXECUTE ${sql.raw(`'ALTER TABLE ${qualified} ALTER COLUMN user_id DROP NOT NULL'`)};
+
+                    EXECUTE ${sql.raw(`'DROP TRIGGER IF EXISTS sync_uid_user_id ON ${qualified}'`)};
+                    EXECUTE ${sql.raw(`'CREATE TRIGGER sync_uid_user_id BEFORE INSERT OR UPDATE ON ${qualified} FOR EACH ROW EXECUTE FUNCTION "${authSchema}".sync_uid_user_id()'`)};
+                END $$
+            `);
+        }
+
         // ── Create dependent auth tables (idempotent) ───────────────────
 
         // Create user_identities table
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(userIdentitiesTable)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 provider TEXT NOT NULL,
                 provider_id TEXT NOT NULL,
                 profile_data JSONB,
@@ -131,21 +206,27 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // Create indexes on user_identities
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_user_identities_user 
-            ON ${sql.raw(userIdentitiesTable)}(user_id)
+            ON ${sql.raw(userIdentitiesTable)}(uid)
         `);
 
 
-        // Create refresh tokens table (includes user_agent, ip_address, and unique constraint)
+        // Create refresh tokens table. One row per TOKEN, grouped into a
+        // sign-in by session_id — deliberately without a uniqueness rule on
+        // (uid, user_agent, ip_address); see the schema module for why that
+        // constraint had to go.
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(refreshTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                session_id TEXT NOT NULL DEFAULT gen_random_uuid()::text,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+                revoked BOOLEAN DEFAULT FALSE NOT NULL,
+                rotated_at TIMESTAMP WITH TIME ZONE,
+                session_started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
                 user_agent TEXT,
                 ip_address TEXT,
-                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                CONSTRAINT unique_device_session UNIQUE (user_id, user_agent, ip_address)
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
             )
         `);
 
@@ -155,17 +236,17 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             ON ${sql.raw(refreshTokensTableName)}(token_hash)
         `);
 
-        // Create index on user_id for cleanup operations
+        // Create index on uid for cleanup operations
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user 
-            ON ${sql.raw(refreshTokensTableName)}(user_id)
+            ON ${sql.raw(refreshTokensTableName)}(uid)
         `);
 
         // Create password reset tokens table
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(passwordResetTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
@@ -179,10 +260,10 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             ON ${sql.raw(passwordResetTokensTableName)}(token_hash)
         `);
 
-        // Create index on user_id for password reset cleanup
+        // Create index on uid for password reset cleanup
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_password_reset_tokens_user 
-            ON ${sql.raw(passwordResetTokensTableName)}(user_id)
+            ON ${sql.raw(passwordResetTokensTableName)}(uid)
         `);
 
         // Create magic link tokens table
@@ -190,7 +271,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(magicLinkTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
@@ -204,10 +285,10 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             ON ${sql.raw(magicLinkTokensTableName)}(token_hash)
         `);
 
-        // Create index on user_id for magic link cleanup
+        // Create index on uid for magic link cleanup
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_magic_link_tokens_user 
-            ON ${sql.raw(magicLinkTokensTableName)}(user_id)
+            ON ${sql.raw(magicLinkTokensTableName)}(uid)
         `);
 
         // Create app config table
@@ -226,9 +307,15 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         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 NULLIF(current_setting('app.user_id', true), '');
+                    SELECT COALESCE(
+                        NULLIF(current_setting('app.uid', true), ''),
+                        NULLIF(current_setting('app.user_id', true), '')
+                    );
                 $$ LANGUAGE sql STABLE
             `);
 
@@ -268,6 +355,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             "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"
         ];
@@ -278,6 +366,86 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             `);
         }
 
+        // ── Migration: refresh_tokens become session-scoped, rotation-safe ──
+        // Two shapes are reconciled here, on EVERY table named refresh_tokens
+        // in whatever schema it lives (a database provisioned by an older era
+        // can carry the table in a different schema than the one this run
+        // derives, and auth would then read a table nobody migrated):
+        //
+        //   1. The new columns. A token is now a member of a session
+        //      (`session_id`) and is retained after rotation (`revoked`,
+        //      `rotated_at`) so a replayed token can be recognised instead of
+        //      looking like a forgery. `session_started_at` is carried across
+        //      rotations so `users.tokens_valid_after` cannot be outrun.
+        //   2. The removal of `unique_device_session`. It made (uid,
+        //      user_agent, ip_address) the identity of a session, which evicted
+        //      a second browser profile behind one NAT and churned rows as
+        //      phones changed networks. UA and IP are metadata now.
+        //
+        // Every existing row is adopted rather than dropped: it keeps its
+        // token_hash, gets a session of its own, and stays unrevoked — so the
+        // sessions live in browsers right now survive the upgrade rather than
+        // everyone being signed out by the fix for being signed out.
+        try {
+            const rtTables = await db.execute(sql`
+                SELECT table_schema, table_name
+                FROM information_schema.tables
+                WHERE table_name = 'refresh_tokens'
+            `);
+            const found = (rtTables.rows as { table_schema: string; table_name: string }[]);
+            logger.info(`🔍 refresh_tokens reconcile: found ${found.length} table(s): ${found.map(r => `"${r.table_schema}"."${r.table_name}"`).join(", ") || "(none)"}`);
+            for (const { table_schema } of found) {
+                const qualified = `"${table_schema}"."refresh_tokens"`;
+                try {
+                    // Added nullable, then back-filled, then constrained: adding
+                    // `session_id NOT NULL DEFAULT gen_random_uuid()` in one step
+                    // would stamp every existing row with the SAME uuid on some
+                    // Postgres versions, silently merging every live session into
+                    // one that a single logout would then wipe.
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS session_id TEXT`);
+                    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`);
+
+                    // One session per pre-existing row: under the old model a row
+                    // WAS a device session, and there is no record of which rows
+                    // descended from the same sign-in.
+                    await db.execute(sql`
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_id = gen_random_uuid()::text
+                        WHERE session_id IS NULL
+                    `);
+                    await db.execute(sql`
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_started_at = COALESCE(created_at, NOW())
+                        WHERE session_started_at IS NULL
+                    `);
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_id SET DEFAULT gen_random_uuid()::text`);
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_started_at SET DEFAULT NOW()`);
+                    // SET NOT NULL only once the back-fill above has definitely
+                    // run; on a table that somehow still holds a NULL this throws
+                    // and is caught below rather than failing the boot.
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_id SET NOT NULL`);
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_started_at SET NOT NULL`);
+
+                    await db.execute(sql`
+                        CREATE INDEX IF NOT EXISTS idx_refresh_tokens_session
+                        ON ${sql.raw(qualified)}(session_id)
+                    `);
+
+                    // The device-session constraint is now actively harmful: two
+                    // live tokens of one session (a rotation in flight) share a
+                    // uid, and usually a user agent and IP too.
+                    await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} DROP CONSTRAINT IF EXISTS unique_device_session`);
+                    logger.info(`✅ refresh_tokens reconciled for session-scoped rotation: ${qualified}`);
+                } catch (perTableError: unknown) {
+                    logger.warn(`⚠️  refresh_tokens reconcile failed for ${qualified}: ${perTableError instanceof Error ? perTableError.message : String(perTableError)}`);
+                }
+            }
+        } catch (migrationError: unknown) {
+            logger.warn(`⚠️  refresh_tokens session migration skipped: ${migrationError instanceof Error ? migrationError.message : String(migrationError)}`);
+        }
+
         // ── Migration: Copy roles from legacy junction table to inline column ──
         // If the old rebase.user_roles and rebase.roles tables exist, migrate
         // the data into the new TEXT[] column then drop the legacy tables.
@@ -322,7 +490,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(mfaFactorsTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 factor_type TEXT NOT NULL DEFAULT 'totp',
                 secret_encrypted TEXT NOT NULL,
                 friendly_name TEXT,
@@ -335,7 +503,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // Create indexes on mfa_factors
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_mfa_factors_user
-            ON ${sql.raw(mfaFactorsTableName)}(user_id)
+            ON ${sql.raw(mfaFactorsTableName)}(uid)
         `);
 
         // Create mfa_challenges table
@@ -360,7 +528,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(recoveryCodesTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 code_hash TEXT NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
@@ -370,7 +538,7 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // Create indexes on recovery_codes
         await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_recovery_codes_user
-            ON ${sql.raw(recoveryCodesTableName)}(user_id)
+            ON ${sql.raw(recoveryCodesTableName)}(uid)
         `);
 
         // ── Migration: clear stale FORCE ROW LEVEL SECURITY (older RLS model) ──