@rebasepro/server-postgres 0.11.1-canary.gfd39654 → 0.12.1-canary.g009ed95

package/src/PostgresBootstrapper.ts

@@ -15,6 +15,7 @@ import {
     DatabaseAdmin,
     type DataDriver,
     CollectionConfig,
+    isRelationalCollectionConfig,
     type HistoryConfig,
     InitializedDriver,
     RealtimeProvider,
@@ -41,6 +42,7 @@ import { provisionTriggerCdc, type CdcTableRef } from "./services/cdc/trigger-cd
 import { collectJunctionLinks } from "./services/cdc/junction-tables";
 import { createChannelBus, resolveChannelBusSetting } from "./services/channel-bus";
 import { isChannelBusInstance } from "@rebasepro/types";
+import { configureUnknownFilterFields, type UnknownFilterFieldsMode } from "./utils/drizzle-conditions";
 
 export interface PostgresDriverConfig {
     connectionString?: string;
@@ -67,6 +69,13 @@ export interface PostgresDriverConfig {
      *    instance and wrong for two. See {@link ChannelBusConfig}.
      */
     realtime?: RealtimeChannelsConfig;
+    /**
+     * What to do with a filter field that resolves to no column at all.
+     * Defaults to `"error"` — a filter that cannot be compiled would otherwise
+     * be dropped, and a dropped condition can only widen the result set.
+     * Set to `"warn"` to restore the pre-fix behaviour of dropping it silently.
+     */
+    unknownFilterFields?: UnknownFilterFieldsMode;
 }
 
 /**
@@ -93,6 +102,40 @@ export interface PostgresDriverInternals {
 
 // Re-export from shared CLI error utilities
 import { isEconnrefused } from "./cli-errors";
+import { classifyConnectFailure } from "./utils/pg-error-utils";
+
+/**
+ * Which table name the boot-time drift check should look for, for one collection.
+ *
+ * A declared `table` IS the table name, not a hint to be second-guessed. This
+ * used to ask the registry whether it had indexed the declared name and fall
+ * back to the SLUG when it had not — but "the registry does not know this table"
+ * is exactly the condition the drift check exists to report, so the fallback
+ * fired precisely when it was most harmful.
+ *
+ * A collection with `slug: "usage-daily", table: "usage_daily"` was reported as
+ * missing table `usage-daily`: a name that does not exist, should never exist,
+ * and that nobody can find by looking. Worse, the remediation the caller prints
+ * says to run `rebase db push` — which would then CREATE that invented table
+ * beside the correct one, the same "second copy" hazard the misplaced-schema
+ * branch further down exists to prevent. Seen in production, where a correctly
+ * migrated database reported drift on every boot.
+ *
+ * The slug is used only when nothing was declared, which is the config shape
+ * where the slug genuinely is the table name.
+ *
+ * Exported for its own test: the caller needs a live pool and a real database,
+ * and this is the part that was wrong.
+ */
+export function resolveDriftCheckName(
+    col: CollectionConfig,
+    registeredTableNames: string[]
+): string {
+    const declaredTable = isRelationalCollectionConfig(col) ? col.table : undefined;
+    return declaredTable
+        ?? registeredTableNames.find((k) => k === col.slug)
+        ?? col.slug;
+}
 
 /**
  * Default PostgreSQL bootstrapper.
@@ -106,16 +149,23 @@ import { isEconnrefused } from "./cli-errors";
  * ```
  */
 export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): BackendBootstrapper {
+    // Applied at construction rather than threaded through every read: the
+    // condition builder's static methods are reached from call sites that
+    // carry no config. See `UnknownFilterFieldsMode`.
+    if (pgConfig.unknownFilterFields) {
+        configureUnknownFilterFields(pgConfig.unknownFilterFields);
+    }
+
     return {
         type: "postgres",
 
         async initializeDriver(config: unknown): Promise<InitializedDriver> {
             // config is passed from coordinator, we merge it with our internal pgConfig if needed
             // Currently config from init.ts is `{ collections, collectionRegistry, mode }`
-            const { collections, collectionRegistry, mode, baas } = config as {
+            const { collections, collectionRegistry, introspectCollections, baas } = config as {
                 collections?: CollectionConfig[];
                 collectionRegistry?: unknown;
-                mode?: "cms" | "baas";
+                introspectCollections?: boolean;
                 baas?: { unprotectedTables?: "exclude" | "serve" };
             };
             // Secure by default: a table with no RLS is not served.
@@ -126,13 +176,13 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                 ? (connection as Record<string, unknown>).$client
                 : connection) as import("pg").Pool;
 
-            // ── BaaS mode: derive the schema from the database ───────────────
+            // ── No declared collections: derive the schema from the database ──
             // No collection files and no generated drizzle schema exist, so read
             // the live database and build both from what is actually there.
             let introspectedCollections: CollectionConfig[] | undefined;
             let introspectedTables: Record<string, PgTable> | undefined;
             let introspectedRelations: Record<string, Relations> | undefined;
-            if (mode === "baas" && (!collections || collections.length === 0)) {
+            if (introspectCollections && (!collections || collections.length === 0)) {
                 const pgSchemaName = pgConfig.introspectionSchema ?? "public";
                 const schema = await introspectSchema(rawClient, pgSchemaName);
 
@@ -244,9 +294,45 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                     throw new Error(`Cannot connect to PostgreSQL at ${hostInfo}: connection refused. Is the database running?`);
                 }
 
-                // For other errors (timeouts, auth failures, etc.) warn but continue —
-                // the pool may recover on subsequent attempts.
-                logger.error("❌ Failed to connect to PostgreSQL", { error: err });
+                /*
+                 * Everything else.
+                 *
+                 * Two problems with what used to happen here. First, the logged
+                 * error was Drizzle's wrapper — `Failed query: SELECT 1` and a
+                 * stack through drizzle internals — while the sentence that
+                 * actually says what is wrong ("password authentication failed
+                 * for user …", "database … does not exist") sits in `.cause`
+                 * and was never printed. A developer with a typo in their
+                 * DATABASE_URL got two walls of stack trace and no cause.
+                 *
+                 * Second, "continuing… the pool may recover" is only true for
+                 * a transient fault. A wrong password or a missing database is
+                 * settled: the next query fails the same way, so the process
+                 * died seconds later anyway — after printing a reassurance.
+                 * Those now fail here, where the message can be about the
+                 * cause rather than about whichever query ran next.
+                 */
+                const { fatal, reason, code } = classifyConnectFailure(err);
+                const detail = code ? ` [${code}]` : "";
+
+                if (fatal) {
+                    logger.error(
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `  ❌  PostgreSQL refused the connection\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `\n` +
+                        `  ${reason}${detail}\n` +
+                        `\n` +
+                        `  The server is reachable, so this is the credentials or the\n` +
+                        `  database name in DATABASE_URL — check them in your .env.\n` +
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`
+                    );
+                    throw new Error(`PostgreSQL refused the connection: ${reason}${detail}`);
+                }
+
+                logger.error(`❌ Failed to connect to PostgreSQL: ${reason}${detail}`, { error: err });
                 logger.warn("⚠️ Continuing without initial database verification. Drizzle/PG will attempt to connect on subsequent queries.");
             }
 
@@ -471,22 +557,28 @@ table: link.table });
             try {
                 const registeredCollections = registry.getCollections();
                 if (registeredCollections.length > 0) {
-                    const schemasToCheck = Array.from(new Set(
-                        registeredCollections.map(c => "schema" in c && c.schema ? c.schema : "public")
-                    ));
-                    const schemasList = schemasToCheck.map(s => `'${s}'`).join(",");
+                    // Deliberately unfiltered by schema: a table that is missing
+                    // from where the collection says it lives is very often
+                    // sitting in another schema entirely (see the misplaced-table
+                    // report below), and knowing *which* is the whole answer.
                     const result = await schemaAwareDb.execute(sql.raw(`
                         SELECT table_name, table_schema
                         FROM information_schema.tables
-                        WHERE table_schema IN (${schemasList})
+                        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
                           AND table_type = 'BASE TABLE'
                     `));
+                    const tablesByName = new Map<string, string[]>();
+                    for (const row of result.rows as Array<{ table_name: string; table_schema: string }>) {
+                        const schemas = tablesByName.get(row.table_name) ?? [];
+                        schemas.push(row.table_schema);
+                        tablesByName.set(row.table_name, schemas);
+                    }
                     const dbTables = new Set(
                         (result.rows as Array<{ table_name: string; table_schema: string }>).map(r =>
                             r.table_schema === "public" ? r.table_name : `${r.table_schema}.${r.table_name}`
                         )
                     );
-                    const missing: Array<{ slug: string; table: string }> = [];
+                    const missing: Array<{ slug: string; table: string; foundIn: string[] }> = [];
                     for (const col of registeredCollections) {
                         // Auth owns its table and creates it later in this same
                         // boot (initializeAuth → ensureAuthTablesExist), so it is
@@ -497,40 +589,72 @@ table: link.table });
                         if ((col as { auth?: { enabled?: boolean } }).auth?.enabled) continue;
 
                         const schemaName = "schema" in col && col.schema ? col.schema : "public";
-                        const tableName = registry.hasTableForCollection(
-                            col.table ?? col.slug
-                        )
-                            ? (col.table ?? col.slug)
-                            : col.slug;
-                        // Resolve the actual table name the registry stored
-                        const resolvedTable = registry.getTableNames().find((k) =>
-                            k === tableName ||
-                            k === col.slug
-                        );
-                        const checkName = resolvedTable ?? tableName;
+                        const checkName = resolveDriftCheckName(col, registry.getTableNames());
                         const fullCheckName = schemaName === "public" ? checkName : `${schemaName}.${checkName}`;
                         if (!dbTables.has(fullCheckName)) {
                             // Report what was actually looked up: an unqualified
                             // "users" sends people hunting for public.users.
                             missing.push({ slug: col.slug,
-table: fullCheckName });
+table: fullCheckName,
+foundIn: (tablesByName.get(checkName) ?? []).filter(s => s !== schemaName) });
                         }
                     }
                     if (missing.length > 0) {
                         const lines = missing.map(
-                            m => `    • collection "${m.slug}" → table "${m.table}"`
+                            m => `    • collection "${m.slug}" → table "${m.table}"` +
+                                (m.foundIn.length > 0
+                                    ? ` — but a table of that name exists in ${m.foundIn.map(s => `"${s}"`).join(", ")}`
+                                    : "")
                         );
+                        // A table that exists under the same name in another
+                        // schema is not ordinary drift: it is almost always this
+                        // framework's own `search_path` hazard. Postgres resolves
+                        // unqualified SQL through `"$user", public`, and this
+                        // project creates a schema named `rebase` while every
+                        // template names the database role `rebase` too — so an
+                        // unqualified CREATE TABLE (a hand-written migration, the
+                        // SQL editor, drizzle-kit) lands in `rebase`, and the
+                        // runtime, which now pins `search_path=public`, cannot see
+                        // it. Say so, because "missing table" sends people to
+                        // re-run a push that will create a *second* copy.
+                        const misplaced = missing.filter(m => m.foundIn.length > 0);
+                        const misplacedHelp = misplaced.length === 0 ? [] : [
+                            "  Those tables exist — in the wrong schema. Unqualified SQL run by a",
+                            "  role whose name matches a schema (`rebase` is both, by default)",
+                            "  resolves through search_path's \"$user\" and creates there. Move them:",
+                            ...misplaced.map(m =>
+                                `      ALTER TABLE "${m.foundIn[0]}"."${m.table.split(".").pop()}" SET SCHEMA "${m.table.includes(".") ? m.table.split(".")[0] : "public"}";`
+                            ),
+                            "  and qualify the SQL that created them, or pin search_path in DATABASE_URL",
+                            "  (`?options=-c%20search_path%3Dpublic`).",
+                            ""
+                        ];
+                        // This runtime creates collection tables (and their RLS)
+                        // at boot unless REBASE_MIGRATE_ON_BOOT=none, so a drift
+                        // this late means that step was disabled, could not run,
+                        // or failed — the guidance names a path for both a managed
+                        // tenant (whose in-cluster database `pnpm db:push` cannot
+                        // reach) and a self-host. Naming only the pnpm scripts, as
+                        // this once did, told a managed operator to run a command
+                        // that structurally cannot touch their database.
                         logger.warn([
                             "",
-                            "┌──────────────────────────────────────────────────────────────┐",
-                            "│  ⚠️  SCHEMA DRIFT — Missing tables in database               │",
-                            "├──────────────────────────────────────────────────────────────┤",
-                            ...lines.map(l => `│ ${l.padEnd(60)}│`),
-                            "├──────────────────────────────────────────────────────────────┤",
-                            "│  Run one of:                                                 │",
-                            "│    pnpm db:push      (dev — fast, no migration files)        │",
-                            "│    pnpm db:migrate   (prod — creates migration files)        │",
-                            "└──────────────────────────────────────────────────────────────┘",
+                            "⚠️  SCHEMA DRIFT — the database is missing tables this backend serves:",
+                            ...lines,
+                            "",
+                            ...misplacedHelp,
+                            "  This runtime applies the collection schema at boot unless",
+                            "  REBASE_MIGRATE_ON_BOOT=none. Check the \"Collection schema\" / \"policies\"",
+                            "  log lines above — this drift means that step was off, skipped, or failed.",
+                            "    • Managed cloud: redeploy with REBASE_MIGRATE_ON_BOOT unset or",
+                            "      \"ensure\"; the runtime applies the schema to the tenant DB.",
+                            "      If the log above says the driver does not implement collection-table",
+                            "      creation, THIS driver is too old to do it. A driver is installed from",
+                            "      your bundle's dependencies, not supplied by the platform image, so a",
+                            "      newer runtime will not update it: bump \"@rebasepro/server-postgres\"",
+                            "      in your project's package.json and redeploy.",
+                            "    • Self-host: run `rebase db push` (dev) or `rebase db migrate` (prod)",
+                            "      against DATABASE_URL.",
                             ""
                         ].join("\n"));
                     }
@@ -694,7 +818,59 @@ schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection))
                 collections as Parameters<typeof ensureCollectionTables>[1],
                 log
             );
-            return { applied: plan.actions.length };
+            for (const failure of plan.failures) {
+                logger.warn(
+                    `🔗 [schema] Could not add foreign key "${failure.target}" — the column exists and the ` +
+                    `collection still serves, but rows are not policed by this constraint: ${failure.error}`
+                );
+            }
+            return { applied: plan.actions.length - plan.failures.length };
+        },
+
+        /**
+         * Apply the collections' RLS policies — ENABLE ROW LEVEL SECURITY and the
+         * `securityRules` compiled to `CREATE POLICY` — so a freshly provisioned
+         * database serves data instead of denying every user-context read.
+         *
+         * The companion to {@link ensureCollectionSchema}: that creates the
+         * tables, this makes them servable. Boot runs it *after* auth
+         * initialization, because the generated policies call `auth.uid()` /
+         * `auth.roles()`, and `CREATE POLICY` validates those functions exist.
+         *
+         * Runs through the same drizzle handle, one statement at a time (that
+         * handle speaks the extended query protocol, which rejects multi-command
+         * strings). Failures are per-table and non-fatal: a table left un-policed
+         * stays RLS-enabled, so it denies rather than leaks.
+         */
+        async ensureCollectionPolicies(
+            collections: unknown[],
+            driverResult: InitializedDriver,
+            log?: (message: string) => void
+        ): Promise<{ applied: number }> {
+            const internals = driverResult.internals as PostgresDriverInternals;
+            const { ensureCollectionPolicies } = await import("./schema/ensure-collection-policies");
+            const queryable = {
+                async query<T>(text: string): Promise<{ rows: T[] }> {
+                    const result = await internals.db.execute(sql.raw(text));
+                    const rows = (result as unknown as { rows?: T[] }).rows;
+                    return { rows: rows ?? (Array.isArray(result) ? (result as T[]) : []) };
+                }
+            };
+            const outcome = await ensureCollectionPolicies(
+                queryable,
+                collections as CollectionConfig[],
+                log
+            );
+
+            for (const skip of outcome.skipped) {
+                logger.warn(`🔐 [rls] Policies not applied to "${skip.table}": ${skip.reason}`);
+            }
+            for (const failure of outcome.failures) {
+                logger.warn(
+                    `🔐 [rls] Could not fully apply policies to "${failure.table}" — it stays locked (denies) until this is resolved: ${failure.error}`
+                );
+            }
+            return { applied: outcome.policiesApplied };
         },
 
         getAdmin(driverResult: InitializedDriver): DatabaseAdmin | undefined {

package/src/auth/ensure-tables.ts

@@ -107,16 +107,38 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 ? "GENERATED ALWAYS AS IDENTITY"
                 : "DEFAULT gen_random_uuid()::text";
 
+        // Identifiers for the constraint and indexes reconciled further down.
+        // Derived from the resolved table name so two auth tables in different
+        // schemas cannot collide, and truncated to Postgres's 63-byte identifier
+        // limit here rather than letting the server truncate silently — the
+        // `IF NOT EXISTS` guards below have to compare against the same name
+        // Postgres actually stored, or they re-run forever.
+        const authIdentifier = (suffix: string) => `${resolvedTable}_${suffix}`.slice(0, 63);
+        const emailLengthConstraint = `"${authIdentifier("email_length_check")}"`;
+        const emailLowerUniqueIndex = authIdentifier("email_lower_key");
+        const verificationTokenIndex = authIdentifier("email_verification_token_idx");
+
+        // Every string column here is TEXT, deliberately. In Postgres VARCHAR(n)
+        // and TEXT are the same type with the same storage and the same
+        // performance; the only difference is a length check, and none of these
+        // columns wants one. The widths this table used to carry were inherited
+        // MySQL habit (255) and they were all wrong in the same direction —
+        // `password_hash VARCHAR(255)` against a 193-char scrypt string left 62
+        // characters of headroom in front of a KEY_LENGTH constant living in
+        // another package, and `photo_url VARCHAR(500)` rejected the `data:` URIs
+        // 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.
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(usersTableName)} (
                 id ${sql.raw(userIdType)} PRIMARY KEY ${sql.raw(idDefault)},
-                email VARCHAR(255) UNIQUE NOT NULL,
-                display_name VARCHAR(255),
-                photo_url VARCHAR(500),
+                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 VARCHAR(255),
+                password_hash TEXT,
                 email_verified BOOLEAN DEFAULT FALSE NOT NULL,
-                email_verification_token VARCHAR(255),
+                email_verification_token TEXT,
                 email_verification_sent_at TIMESTAMP WITH TIME ZONE,
                 is_anonymous BOOLEAN DEFAULT FALSE NOT NULL,
                 metadata JSONB DEFAULT '{}' NOT NULL,
@@ -359,12 +381,12 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // 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 VARCHAR(255)",
-            "photo_url VARCHAR(500)",
+            "display_name TEXT",
+            "photo_url TEXT",
             "roles TEXT[] DEFAULT '{}' NOT NULL",
-            "password_hash VARCHAR(255)",
+            "password_hash TEXT",
             "email_verified BOOLEAN DEFAULT FALSE NOT NULL",
-            "email_verification_token VARCHAR(255)",
+            "email_verification_token TEXT",
             "email_verification_sent_at TIMESTAMP WITH TIME ZONE",
             "is_anonymous BOOLEAN DEFAULT FALSE NOT NULL",
             "metadata JSONB DEFAULT '{}' NOT NULL",
@@ -379,6 +401,139 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             `);
         }
 
+        // Which of the columns below the table actually has. An adopted table —
+        // one this framework did not create, which the column-name resolution in
+        // `services.ts` exists to support — may be missing any of them, and every
+        // 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
+            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])
+        );
+
+        // ── Migration: VARCHAR(n) → TEXT on the users string columns ────────
+        // Tables created before the widths came off still carry them. Postgres
+        // treats varchar(n) → text as binary-coercible with no stricter
+        // constraint, so this is a catalogue-only change: no table rewrite, no
+        // index rebuild, just a brief ACCESS EXCLUSIVE lock. Guarded on the
+        // current type so it runs once and is a pure catalogue read thereafter.
+        for (const column of ["email", "display_name", "photo_url", "password_hash", "email_verification_token"]) {
+            if (usersColumnTypes.get(column) !== "character varying") continue;
+            await db.execute(sql`
+                ALTER TABLE ${sql.raw(usersTableName)}
+                ALTER COLUMN ${sql.raw(`"${column}"`)} TYPE TEXT
+            `);
+            logger.info(`🔧 Widened ${usersTableName}.${column} from VARCHAR(n) to TEXT`);
+        }
+
+        // ── Migration: case-insensitive email identity ──────────────────────
+        // `getUserByEmail` has always searched `email.toLowerCase()` while the
+        // write path stored whatever it was handed, leaving normalisation to a
+        // convention every caller had to remember. A row that reached the table
+        // with mixed case is then invisible to every lookup — the account exists,
+        // login reports no such user, and the plain UNIQUE on `email` does not
+        // stop a second row differing only in case, because it compares bytes.
+        //
+        // Fixed on both sides: `mapPayload` now folds on write, and this index
+        // makes the database agree. A unique index on lower(email) is strictly
+        // stronger than the byte-exact UNIQUE that older tables carry, so the
+        // old constraint is left alone — it can no longer fire on anything the
+        // new one would allow.
+        //
+        // Deliberately no AUTH_SCHEMA_VERSION bump: a runtime that predates this
+        // migration keeps working against the migrated table (all of its own
+        // write paths already lower-cased), which is exactly the additive case
+        // the version stamp is documented not to cover.
+        if (usersColumnTypes.has("email")) {
+            const indexPresent = await db.execute(sql`
+                SELECT 1 FROM pg_class c
+                JOIN pg_namespace n ON n.oid = c.relnamespace
+                WHERE n.nspname = ${usersSchema} AND c.relname = ${emailLowerUniqueIndex} AND c.relkind = 'i'
+            `);
+            if (indexPresent.rows.length === 0) {
+                // Case-collisions already in the table would make the unique
+                // index impossible to build. Report them and leave the table
+                // alone: the next boot retries, so fixing the rows is all the
+                // operator has to do. Failing loudly beats folding the emails
+                // and letting CREATE INDEX pick which account survives.
+                const collisions = await db.execute(sql`
+                    SELECT lower(email) AS normalized, count(*)::int AS occurrences
+                    FROM ${sql.raw(usersTableName)}
+                    WHERE email IS NOT NULL
+                    GROUP BY lower(email)
+                    HAVING count(*) > 1
+                    LIMIT 10
+                `);
+                if (collisions.rows.length > 0) {
+                    const sample = (collisions.rows as { normalized: string; occurrences: number }[])
+                        .map(row => `${row.normalized} (×${row.occurrences})`)
+                        .join(", ");
+                    logger.error(
+                        `❌ Cannot enforce case-insensitive email uniqueness on ${usersTableName}: ` +
+                        `these addresses already exist more than once, differing only in case — ${sample}. ` +
+                        "Merge or delete the duplicates and restart; until then two accounts can share " +
+                        "one address and only the lower-cased one is reachable by login."
+                    );
+                } else {
+                    const folded = await db.execute(sql`
+                        UPDATE ${sql.raw(usersTableName)}
+                        SET email = lower(email)
+                        WHERE email IS NOT NULL AND email <> lower(email)
+                    `);
+                    if (folded.rowCount) {
+                        logger.info(`🔧 Lower-cased ${folded.rowCount} email address(es) in ${usersTableName}`);
+                    }
+                    await db.execute(sql`
+                        CREATE UNIQUE INDEX IF NOT EXISTS ${sql.raw(`"${emailLowerUniqueIndex}"`)}
+                        ON ${sql.raw(usersTableName)} (lower(email))
+                    `);
+                    logger.info(`✅ Email uniqueness on ${usersTableName} is now case-insensitive`);
+                }
+            }
+        }
+
+        // ── Migration: bound the email column's length ──────────────────────
+        // The only length limit on this table worth keeping. 320 is the RFC 5321
+        // maximum (64-char local part + @ + 255-char domain), and it matters here
+        // beyond tidiness: `email` carries a btree index, and a sufficiently long
+        // value fails index insertion with an error that says nothing about
+        // email. NOT VALID so an adopted table with a long row still migrates —
+        // it binds all new writes, which is the part that matters.
+        if (usersColumnTypes.has("email")) {
+            const checkPresent = await db.execute(sql`
+                SELECT 1 FROM pg_constraint c
+                JOIN pg_class t ON t.oid = c.conrelid
+                JOIN pg_namespace n ON n.oid = t.relnamespace
+                WHERE n.nspname = ${usersSchema}
+                  AND t.relname = ${resolvedTable}
+                  AND c.conname = ${authIdentifier("email_length_check")}
+            `);
+            if (checkPresent.rows.length === 0) {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ADD CONSTRAINT ${sql.raw(emailLengthConstraint)} CHECK (length(email) <= 320) NOT VALID
+                `);
+            }
+        }
+
+        // ── Index: email verification token lookups ─────────────────────────
+        // `getUserByVerificationToken` filters on this column, which had no
+        // index — every click of a verification link was a sequential scan of
+        // the whole users table. Partial, because the column is NULL for every
+        // user who is not mid-verification, which is nearly all of them.
+        if (usersColumnTypes.has("email_verification_token")) {
+            await db.execute(sql`
+                CREATE INDEX IF NOT EXISTS ${sql.raw(`"${verificationTokenIndex}"`)}
+                ON ${sql.raw(usersTableName)} (email_verification_token)
+                WHERE email_verification_token IS NOT NULL
+            `);
+        }
+
         // ── 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

package/src/auth/services.ts

@@ -54,6 +54,28 @@ function getColumn(table: RebasePgTable | undefined, ...keys: string[]): RebaseP
     return key ? table[key] : undefined;
 }
 
+/**
+ * The single definition of what an email address looks like in storage.
+ *
+ * Reads have always folded case; writes did not, and normalising was left to
+ * each caller. That asymmetry is only ever one forgotten `.toLowerCase()` away
+ * from a row no lookup can find — the account exists, every sign-in path
+ * reports no such user, and the byte-exact UNIQUE on the column does not stop a
+ * duplicate differing only in case. Applied on both sides here so the guarantee
+ * belongs to the repository rather than to its callers' discipline; the
+ * `lower(email)` unique index added in `ensureAuthTablesExist` is the database
+ * half of the same rule.
+ *
+ * Whitespace goes too: a trailing space survives the fold and reproduces the
+ * problem exactly.
+ *
+ * Re-exported rather than defined here: `@rebasepro/server` and
+ * `@rebasepro/server-mongo` write this column too, and a second copy of this
+ * rule is the defect it exists to prevent.
+ */
+import { normalizeEmail } from "@rebasepro/common";
+export { normalizeEmail };
+
 /**
  * PostgreSQL implementation of UserRepository.
  * Handles all user-related database operations using Drizzle ORM.
@@ -184,7 +206,7 @@ export class UserService implements UserRepository {
         const metadataKey = getColumnKey(this.usersTable, "metadata") || "metadata";
 
         if ("id" in data) payload[idKey] = data.id;
-        if ("email" in data) payload[emailKey] = data.email;
+        if ("email" in data) payload[emailKey] = normalizeEmail(data.email);
         if ("passwordHash" in data) payload[passwordHashKey] = data.passwordHash;
         if ("displayName" in data) payload[displayNameKey] = data.displayName;
         if ("photoUrl" in data) payload[photoUrlKey] = data.photoUrl;
@@ -244,7 +266,7 @@ export class UserService implements UserRepository {
     async getUserByEmail(email: string): Promise<UserData | null> {
         const emailCol = getColumn(this.usersTable, "email");
         if (!emailCol) return null;
-        const [row] = await this.db.select().from(this.usersTable).where(eq(emailCol, email.toLowerCase()));
+        const [row] = await this.db.select().from(this.usersTable).where(eq(emailCol, normalizeEmail(email)));
         return row ? this.mapRowToUser(row as Record<string, unknown>) : null;
     }