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

package/src/schema/auth-users-columns.ts

@@ -0,0 +1,131 @@
+/**
+ * The one description of what an auth user table's columns must be.
+ *
+ * ## Why this exists
+ *
+ * Three different code paths create `rebase.users`, and before this module they
+ * disagreed about it:
+ *
+ * | column           | `db push` (generator) | `ensureAuthTablesExist` | `ensureCollectionTables` |
+ * |------------------|-----------------------|-------------------------|--------------------------|
+ * | `email`          | `TEXT UNIQUE NOT NULL`| `TEXT NOT NULL` + CHECK | `TEXT` (nullable)        |
+ * | `roles`          | `TEXT[]`              | `NOT NULL DEFAULT '{}'` | nullable, no default     |
+ * | `email_verified` | `BOOLEAN`             | `NOT NULL DEFAULT FALSE`| nullable                 |
+ * | `created_at`     | `DEFAULT now()`       | `NOT NULL DEFAULT NOW()`| no default               |
+ *
+ * They are all `CREATE TABLE IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS`, so
+ * whichever ran first decided the table and the other two silently no-op'd.
+ * Boot order therefore chose the constraints: a managed deploy (collection
+ * tables first) got a users table whose `email` was nullable and whose
+ * `email_verified` had no default, while the same project pushed from a
+ * checkout got the strict one. In the same table, `is_anonymous` came out
+ * `NOT NULL DEFAULT false` — because *that* column existed in only one of the
+ * three lists, so its owner's definition won by default.
+ *
+ * A second consequence was drift in the other direction. The scaffold's
+ * `users.ts` describes 12 columns; auth needs 14. `db push` is declarative and
+ * builds its desired state from the collection alone, so the two columns only
+ * auth knows about (`is_anonymous`, `tokens_valid_after`) read as unmanaged
+ * drift, and a push run after the server had booted once planned to DROP them.
+ *
+ * Both problems are the same problem: no single place said what this table is.
+ * This is that place. Every creator asks here first and only then falls back to
+ * the collection's own property definitions, so a column auth owns has one
+ * definition regardless of who gets there first, and a column the developer
+ * added to their users collection still behaves like any other field.
+ *
+ * ## What belongs here
+ *
+ * Only columns the auth services read or write. A developer's own additions to
+ * their users collection (`bio`, `stripe_customer_id`) are ordinary columns and
+ * must NOT be listed — they are generated from the collection like every other
+ * field, and listing them here would freeze a user's schema.
+ *
+ * `id` is deliberately absent: its type comes from the collection's id property
+ * (uuid / increment / text) and each creator already derives it.
+ *
+ * Keep in step with {@link AUTH_SCHEMA_VERSION} when a change here makes an
+ * older runtime unable to work against a migrated table.
+ */
+
+/**
+ * A column auth owns.
+ *
+ * Structured rather than one SQL string because the same facts are needed in
+ * three grammars — a `CREATE TABLE` column list, an `ADD COLUMN IF NOT EXISTS`,
+ * and a pair of `ALTER COLUMN … SET DEFAULT` / `SET NOT NULL` reconciles for a
+ * table that already exists with the wrong shape. Parsing a string back apart
+ * for the third of those is how the copies drifted in the first place.
+ */
+export interface AuthUsersColumn {
+    /** Physical column name. */
+    column: string;
+    /** Postgres type. */
+    type: string;
+    /** Default expression, verbatim, or absent for no default. */
+    default?: string;
+    /** Whether the column is NOT NULL. */
+    notNull?: boolean;
+}
+
+/**
+ * `email` is NOT NULL on purpose, and the anonymous sign-in route depends on it
+ * — it synthesizes `anon_<32 hex>@anonymous.local` rather than inserting NULL.
+ * The 320-char bound (RFC 5321) is a CHECK rather than a `VARCHAR(n)`, added
+ * separately by `ensureAuthTablesExist` so it can be `NOT VALID` on an adopted
+ * table that already holds a longer row.
+ */
+export const AUTH_USERS_COLUMNS: readonly AuthUsersColumn[] = [
+    { column: "email", type: "TEXT", notNull: true },
+    { column: "display_name", type: "TEXT" },
+    { column: "photo_url", type: "TEXT" },
+    { column: "roles", type: "TEXT[]", default: "'{}'", notNull: true },
+    { column: "password_hash", type: "TEXT" },
+    { column: "email_verified", type: "BOOLEAN", default: "FALSE", notNull: true },
+    { column: "email_verification_token", type: "TEXT" },
+    { column: "email_verification_sent_at", type: "TIMESTAMP WITH TIME ZONE" },
+    { column: "is_anonymous", type: "BOOLEAN", default: "FALSE", notNull: true },
+    { column: "metadata", type: "JSONB", default: "'{}'", notNull: true },
+    { column: "tokens_valid_after", type: "TIMESTAMP WITH TIME ZONE" },
+    { column: "created_at", type: "TIMESTAMP WITH TIME ZONE", default: "NOW()", notNull: true },
+    { column: "updated_at", type: "TIMESTAMP WITH TIME ZONE", default: "NOW()", notNull: true }
+];
+
+const BY_COLUMN = new Map(AUTH_USERS_COLUMNS.map(c => [c.column, c]));
+
+/** Type + inline constraints, as they appear after the column name. */
+export function authUsersColumnSql(spec: AuthUsersColumn): string {
+    return [
+        spec.type,
+        spec.default !== undefined ? `DEFAULT ${spec.default}` : "",
+        spec.notNull ? "NOT NULL" : ""
+    ].filter(Boolean).join(" ");
+}
+
+/**
+ * The auth-owned definition for a physical column name, or `undefined` when
+ * auth does not own it.
+ *
+ * Callers pass the RESOLVED column name (after `columnName` mapping), because
+ * that is the only name the three creators agree on: the scaffold's users
+ * collection spells the property `displayName` and the column `display_name`.
+ */
+export function authUsersColumnDefinition(column: string): string | undefined {
+    const spec = BY_COLUMN.get(column);
+    return spec ? authUsersColumnSql(spec) : undefined;
+}
+
+/**
+ * Whether a collection is an auth collection, i.e. whether the definitions in
+ * this module apply to its table at all.
+ *
+ * Duplicated in shape from `@rebasepro/common`'s policy defaults on purpose:
+ * that one takes a `CollectionConfig`, this one is called from DDL code paths
+ * that hold looser objects, and both spellings must accept `auth: true` as well
+ * as `auth: { enabled: true }`.
+ */
+export function isAuthCollection(collection: unknown): boolean {
+    const auth = (collection as { auth?: unknown } | undefined)?.auth;
+    if (auth === true) return true;
+    return typeof auth === "object" && auth !== null && (auth as { enabled?: unknown }).enabled === true;
+}

package/src/schema/doctor-cli.ts

@@ -5,62 +5,8 @@
  */
 import path from "path";
 import chalk from "chalk";
-import fs from "fs";
-import { runDoctor, loadCollections } from "./doctor";
-import { checkPolicyDrift, formatPolicyDrift, hasDrift } from "../security/policy-drift";
-import { validatePolicyPgRoles, warnOnAnonymousGrants } from "../security/rls-enforcement";
-import { logger } from "@rebasepro/server";
-
-/**
- * The RLS half of the doctor: policies actually deployed vs the ones the
- * collections describe, plus policy roles this server could never satisfy.
- *
- * Returns true when something is wrong, so callers can set the exit code.
- */
-async function runPolicyChecks(collectionsPath: string, databaseUrl?: string): Promise<boolean> {
-    if (!databaseUrl) {
-        logger.warn(chalk.yellow("  ⚠ No DATABASE_URL — skipping RLS policy checks"));
-        return false;
-    }
-
-    let problems = false;
-    const { Pool } = await import("pg");
-    const pool = new Pool({ connectionString: databaseUrl });
-    try {
-        const collections = await loadCollections(path.resolve(process.cwd(), collectionsPath));
-        const runSql = async (text: string) => (await pool.query(text)).rows as Record<string, unknown>[];
-
-        // A policy naming a role the server never runs as filters every row, so
-        // the collection reads as empty. Report it without booting a server.
-        try {
-            await validatePolicyPgRoles(runSql, collections as never);
-            logger.info(chalk.green("  ✓ Policy roles are usable by this server"));
-        } catch (err) {
-            problems = true;
-            logger.info("");
-            logger.error(chalk.red(err instanceof Error ? err.message : String(err)));
-        }
-
-        // A rule that reads as a lockdown but is true for every caller compiles
-        // to a grant. Report it without booting a server.
-        warnOnAnonymousGrants(collections as never);
-
-        const drift = await checkPolicyDrift(pool as never, collections);
-        logger.info("");
-        if (hasDrift(drift)) {
-            problems = true;
-            logger.info(chalk.yellow("  RLS policies: database does not match your collections"));
-            logger.info(formatPolicyDrift(drift));
-        } else {
-            logger.info(chalk.green("  ✓ RLS policies match your collections"));
-        }
-    } catch (err) {
-        logger.warn(chalk.yellow("  ⚠ Could not check RLS policies"), { error: err });
-    } finally {
-        await pool.end();
-    }
-    return problems;
-}
+import { runDoctor } from "./doctor";
+import { exitCodeForPolicyGate, runPolicyChecks } from "./doctor-policy-checks";
 
 async function main() {
     const collectionsArg = process.argv.find((a) => a.startsWith("--collections="));
@@ -80,9 +26,9 @@ async function main() {
         const dotenv = await import("dotenv");
         const envPath = process.env.DOTENV_CONFIG_PATH;
         if (envPath) {
-            dotenv.config({ path: envPath });
+            dotenv.config({ path: envPath, quiet: true });
         } else {
-            dotenv.config();
+            dotenv.config({ quiet: true });
         }
     } catch {
         // dotenv may not be installed
@@ -91,9 +37,9 @@ async function main() {
     const databaseUrl = process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING;
 
     if (policiesOnly) {
-        // Non-zero so this can gate CI — the whole point of the flag.
-        if (await runPolicyChecks(collectionsPath, databaseUrl)) process.exit(1);
-        return;
+        // Non-zero so this can gate CI — the whole point of the flag, and a
+        // check that could not run has not passed. See exitCodeForPolicyGate.
+        process.exit(exitCodeForPolicyGate(await runPolicyChecks(collectionsPath, databaseUrl)));
     }
 
     const report = await runDoctor({
@@ -103,15 +49,18 @@ async function main() {
         databaseUrl: databaseUrl ?? undefined
     });
 
-    const policiesDrifted = await runPolicyChecks(collectionsPath, databaseUrl);
+    const policyStatus = await runPolicyChecks(collectionsPath, databaseUrl);
 
-    // Exit with non-zero code if there are errors
-    if (report.summary.errors > 0 || policiesDrifted) {
+    // Exit non-zero if there are errors. A policy run that could not happen is
+    // reported loudly above but does not fail the interactive command — the
+    // same treatment the skipped database phase gets. `--policies` is the gate,
+    // and that one fails closed.
+    if (report.summary.errors > 0 || policyStatus === "problems") {
         process.exit(1);
     }
 }
 
 main().catch((err) => {
-    logger.error(chalk.red("  ✗ Doctor failed"), { error: err });
+    console.error(chalk.red("  ✗ Doctor failed"), err instanceof Error ? (err.stack ?? err.message) : String(err));
     process.exit(1);
 });

package/src/schema/doctor-policy-checks.ts

@@ -0,0 +1,105 @@
+/**
+ * The RLS half of `rebase doctor`, and the exit code `--policies` gates CI on.
+ *
+ * Lives beside `doctor-cli.ts` rather than inside it because that file runs
+ * `main()` on import: a gate whose failure modes cannot be unit-tested is how
+ * this one shipped reporting success for work it never did.
+ */
+import path from "path";
+import chalk from "chalk";
+import { CollectionConfig } from "@rebasepro/types";
+import { loadCollections } from "./doctor";
+import { checkPolicyDrift, formatPolicyDrift, hasDrift } from "../security/policy-drift";
+import { validatePolicyPgRoles, warnOnAnonymousGrants } from "../security/rls-enforcement";
+
+/**
+ * What the RLS checks concluded.
+ *
+ * `unchecked` exists because "we could not look" and "we looked and it is fine"
+ * used to be reported identically: a collections path that did not resolve made
+ * the loader return `[]` (it warns, it does not throw), `checkPolicyDrift`
+ * early-returned an empty diff, and the gate printed
+ * `✓ RLS policies match your collections` having compared zero policies against
+ * zero collections. Any exception at all — a collection file that throws on
+ * import, a `pg_policies` read the CI role is not granted, a connection reset —
+ * did the same thing through a `warn`, and exited 0.
+ */
+export type PolicyCheckStatus = "ok" | "problems" | "unchecked";
+
+/**
+ * The exit code for `rebase doctor --policies`.
+ *
+ * A gate that could not run has not passed. Only a completed, clean check
+ * exits 0 — anything else, including "we never opened a connection", is a
+ * failure, or the flag certifies a database nobody looked at.
+ */
+export function exitCodeForPolicyGate(status: PolicyCheckStatus): 0 | 1 {
+    return status === "ok" ? 0 : 1;
+}
+
+/**
+ * Policies actually deployed vs the ones the collections describe, plus policy
+ * roles this server could never satisfy.
+ *
+ * Never reports `ok` for work it did not do — see {@link PolicyCheckStatus}.
+ */
+export async function runPolicyChecks(collectionsPath: string, databaseUrl?: string): Promise<PolicyCheckStatus> {
+    if (!databaseUrl) {
+        console.error(chalk.yellow("  ⚠ No DATABASE_URL — RLS policies were NOT checked"));
+        return "unchecked";
+    }
+
+    const resolvedPath = path.resolve(process.cwd(), collectionsPath);
+    let problems = false;
+    const { Pool } = await import("pg");
+    const pool = new Pool({ connectionString: databaseUrl });
+    try {
+        const collections: CollectionConfig[] = await loadCollections(resolvedPath);
+
+        // Zero collections is not "no drift", it is nothing to compare. The
+        // loader returns `[]` for a path that does not exist, so the commonest
+        // way to get here is a `--collections` path resolved against the wrong
+        // directory — which used to render as a green tick.
+        if (collections.length === 0) {
+            console.error(chalk.red(`  ✗ No collections found in ${resolvedPath}`));
+            console.error(chalk.gray("    RLS policies were NOT checked. Pass --collections=<dir> if your collections live elsewhere."));
+            return "unchecked";
+        }
+
+        const runSql = async (text: string) => (await pool.query(text)).rows as Record<string, unknown>[];
+
+        // A policy naming a role the server never runs as filters every row, so
+        // the collection reads as empty. Report it without booting a server.
+        try {
+            await validatePolicyPgRoles(runSql, collections as never);
+            console.log(chalk.green("  ✓ Policy roles are usable by this server"));
+        } catch (err) {
+            problems = true;
+            console.log("");
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        }
+
+        // A rule that reads as a lockdown but is true for every caller compiles
+        // to a grant. Report it without booting a server.
+        warnOnAnonymousGrants(collections as never);
+
+        const drift = await checkPolicyDrift(pool as never, collections);
+        console.log("");
+        if (hasDrift(drift)) {
+            problems = true;
+            console.log(chalk.yellow("  RLS policies: database does not match your collections"));
+            console.log(formatPolicyDrift(drift));
+        } else {
+            console.log(chalk.green(`  ✓ RLS policies match your collections (${collections.length} collection(s) checked)`));
+        }
+    } catch (err) {
+        // Fail closed. This catch covers every query and every collection import
+        // above, so returning the pre-catch verdict made the documented CI gate
+        // green on exactly the runs it exists to catch.
+        console.error(chalk.red("  ✗ Could not check RLS policies:"), err instanceof Error ? err.message : String(err));
+        return "unchecked";
+    } finally {
+        await pool.end();
+    }
+    return problems ? "problems" : "ok";
+}