@rebasepro/server-postgres 0.0.1-canary.4829d6e

package/src/security/rls-enforcement.ts

@@ -0,0 +1,295 @@
+import { sql as drizzleSql, SQL } from "drizzle-orm";
+import { logger } from "@rebasepro/server";
+
+/**
+ * Unified RLS enforcement — the "user context vs server context" model.
+ *
+ * Every operation runs in one of two contexts:
+ *
+ *  - **User context** — a request authenticated (or anonymous) via
+ *    `driver.withAuth(user)`. Runs as the restricted `rebase_user` role: a
+ *    non-owner, NOSUPERUSER, NOBYPASSRLS role, so Postgres RLS binds *every*
+ *    statement (SELECT, INSERT, UPDATE, DELETE). The collection's
+ *    `securityRules` are the whole authorization model; app-layer callbacks
+ *    are validation/side-effects, not a security boundary.
+ *
+ *  - **Server context** — the base (owner) connection: auth flows, migrations,
+ *    background jobs, and the explicit `rebase.dataAsAdmin` accessor. As table
+ *    owner it bypasses RLS. This is the trusted plane, equivalent to
+ *    Supabase's `service_role`.
+ *
+ * This module provides the three pieces:
+ *
+ *  1. {@link detectConnectionPosture} — is the connection subject to RLS at
+ *     all? (superuser / BYPASSRLS / table owner ⇒ no)
+ *  2. {@link ensureAppRole} — idempotently provision `rebase_user` with
+ *     SELECT/INSERT/UPDATE/DELETE grants (+ default privileges so future
+ *     tables stay covered).
+ *  3. {@link applyAuthContext} — per-transaction: set the `app.*` GUCs the
+ *     policies read (`auth.uid()` etc.) and `SET LOCAL ROLE rebase_user` so
+ *     RLS binds. Transaction-scoped, so it composes with poolers.
+ *
+ * Provisioning runs from the framework's own bootstrap/migrate (which already
+ * self-creates the `auth` schema and functions) — enforcement is default-on,
+ * not an operator opt-in.
+ */
+
+/** The restricted role every authenticated (user-context) request runs as. */
+export const REBASE_USER_ROLE = "rebase_user";
+
+/** Minimal SQL runner so callers can adapt drizzle or pg.Client. */
+export type RawSqlRunner = (sqlText: string) => Promise<Record<string, unknown>[]>;
+
+/** Minimal transaction surface needed by {@link applyAuthContext}. */
+export interface SqlTx {
+    execute(query: SQL): Promise<unknown>;
+}
+
+export interface ConnectionPosture {
+    /** The connection's `current_user`. */
+    role: string;
+    superuser: boolean;
+    bypassRLS: boolean;
+    /** Owns at least one user table — owners bypass non-FORCE RLS. */
+    ownsTables: boolean;
+    /** True when RLS would NOT constrain this connection. */
+    privileged: boolean;
+}
+
+export interface AuthContext {
+    userId: string;
+    /** Raw roles as carried on the user (strings or `{ id }` objects). */
+    roles: unknown[];
+}
+
+const quoteIdent = (name: string): string => `"${name.replace(/"/g, "\"\"")}"`;
+
+/** DML the user role holds on managed tables (RLS still filters per row). */
+const USER_TABLE_PRIVILEGES = "SELECT, INSERT, UPDATE, DELETE";
+
+export async function detectConnectionPosture(run: RawSqlRunner): Promise<ConnectionPosture> {
+    const rows = await run(`
+        SELECT current_user            AS role,
+               r.rolsuper              AS superuser,
+               r.rolbypassrls          AS bypassrls,
+               EXISTS (
+                   SELECT 1 FROM pg_tables t
+                   WHERE t.tableowner = current_user
+                     AND t.schemaname NOT IN ('pg_catalog', 'information_schema')
+               )                       AS owns_tables
+        FROM pg_roles r
+        WHERE r.rolname = current_user
+    `);
+    const row = rows[0] ?? {};
+    const superuser = row.superuser === true;
+    const bypassRLS = row.bypassrls === true;
+    const ownsTables = row.owns_tables === true;
+    return {
+        role: String(row.role ?? "unknown"),
+        superuser,
+        bypassRLS,
+        ownsTables,
+        privileged: superuser || bypassRLS || ownsTables
+    };
+}
+
+/**
+ * Human-actionable instructions for when the connection cannot provision the
+ * user role itself (no CREATEROLE and role not pre-created by the platform).
+ */
+export function appRoleSetupInstructions(connectionRole: string, schemas: string[]): string {
+    const grants = schemas.map((s) =>
+        `GRANT USAGE ON SCHEMA ${quoteIdent(s)} TO ${REBASE_USER_ROLE};\n` +
+        `GRANT ${USER_TABLE_PRIVILEGES} ON ALL TABLES IN SCHEMA ${quoteIdent(s)} TO ${REBASE_USER_ROLE};\n` +
+        `GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${quoteIdent(s)} TO ${REBASE_USER_ROLE};`
+    ).join("\n");
+    return (
+        `Rebase enforces row-level security by running authenticated requests as ` +
+        `the restricted role "${REBASE_USER_ROLE}", but the connection role ` +
+        `"${connectionRole}" bypasses RLS and cannot create that role itself.\n` +
+        `Run the following as a database administrator, then restart:\n\n` +
+        `CREATE ROLE ${REBASE_USER_ROLE} NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT;\n` +
+        `GRANT ${REBASE_USER_ROLE} TO ${quoteIdent(connectionRole)};\n` +
+        grants
+    );
+}
+
+/**
+ * Idempotently provision the `rebase_user` role, membership for the current
+ * connection role, and DML grants (+ default privileges for future tables)
+ * on every existing schema in `schemas`.
+ *
+ * Split into privilege tiers so it works both when the connection is a
+ * superuser (creates everything) and when the platform pre-created the role
+ * and membership (e.g. CNPG `postInitApplicationSQL`) and the connection is
+ * merely the table owner — owners can always run the grant tier themselves.
+ *
+ * RLS still filters every row: these grants only make the tables *reachable*
+ * by the role; the policies decide which rows/commands actually pass.
+ *
+ * Throws with precise setup instructions when the role is missing and the
+ * connection cannot create it.
+ */
+export async function ensureAppRole(run: RawSqlRunner, schemas: string[]): Promise<void> {
+    const uniqueSchemas = Array.from(new Set(schemas.filter(Boolean)));
+
+    // Tier 1 — role existence.
+    const roleRows = await run(`SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}'`);
+    if (roleRows.length === 0) {
+        try {
+            await run(`CREATE ROLE ${REBASE_USER_ROLE} NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT`);
+        } catch (err) {
+            throw new Error(
+                `Failed to create the "${REBASE_USER_ROLE}" role: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                appRoleSetupInstructions("current connection role", uniqueSchemas)
+            );
+        }
+    }
+
+    // Tier 2 — membership, so a non-superuser connection may SET ROLE to it.
+    const memberRows = await run(`
+        SELECT (pg_has_role(current_user, '${REBASE_USER_ROLE}', 'MEMBER')
+                OR (SELECT rolsuper FROM pg_roles WHERE rolname = current_user)) AS can_set,
+               current_user AS role
+    `);
+    if (memberRows[0]?.can_set !== true) {
+        try {
+            await run(`GRANT ${REBASE_USER_ROLE} TO CURRENT_USER`);
+        } catch (err) {
+            throw new Error(
+                `The connection role is not a member of "${REBASE_USER_ROLE}" and cannot grant itself membership: ` +
+                `${err instanceof Error ? err.message : String(err)}\n\n` +
+                appRoleSetupInstructions(String(memberRows[0]?.role ?? "current connection role"), uniqueSchemas)
+            );
+        }
+    }
+
+    // Tier 3 — grants. Table owners (the expected non-superuser posture) can
+    // always grant on their own objects, so this tier needs no extra privilege.
+    const nspRows = await run("SELECT nspname FROM pg_namespace");
+    const existing = new Set(nspRows.map((r) => String(r.nspname)));
+    for (const schema of uniqueSchemas) {
+        if (!existing.has(schema)) continue;
+        const s = quoteIdent(schema);
+        await run(`GRANT USAGE ON SCHEMA ${s} TO ${REBASE_USER_ROLE}`);
+        await run(`GRANT ${USER_TABLE_PRIVILEGES} ON ALL TABLES IN SCHEMA ${s} TO ${REBASE_USER_ROLE}`);
+        await run(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${s} TO ${REBASE_USER_ROLE}`);
+        // Cover objects created later by the CURRENT role (the role that runs
+        // migrations), so a migrate can never strand the user role.
+        await run(`ALTER DEFAULT PRIVILEGES IN SCHEMA ${s} GRANT ${USER_TABLE_PRIVILEGES} ON TABLES TO ${REBASE_USER_ROLE}`);
+        await run(`ALTER DEFAULT PRIVILEGES IN SCHEMA ${s} GRANT USAGE, SELECT ON SEQUENCES TO ${REBASE_USER_ROLE}`);
+    }
+
+    logger.info(`🔐 [rls] User role "${REBASE_USER_ROLE}" provisioned (schemas: ${uniqueSchemas.join(", ")})`);
+}
+
+/**
+ * Apply the authenticated context to a transaction: the `app.*` GUCs that RLS
+ * policies read via `auth.uid()` / `auth.roles()` / `auth.jwt()`, and — when
+ * `userRole` is set — `SET LOCAL ROLE` so RLS binds every statement in this
+ * transaction (reads *and* writes).
+ *
+ * GUCs are set with `is_local = true` and the role switch is `LOCAL`: both
+ * reset at commit/rollback, so pooled connections are never polluted.
+ *
+ * Fails closed by construction: if the role switch errors, the transaction
+ * aborts instead of proceeding privileged.
+ *
+ * SECURITY: this function is only ever called on the **user** path (the server
+ * context uses the base/owner driver and never calls it). The default policies
+ * treat `auth.uid() IS NULL` as the trusted server context, and `auth.uid()`
+ * is `NULLIF(current_setting('app.user_id'), '')` — so an EMPTY user id would
+ * be read as NULL and silently escalate a user request to server privileges.
+ * Coerce empty/blank ids to a sentinel here, at the single chokepoint, rather
+ * than trusting every caller (e.g. realtime subscription auth) to do it.
+ */
+export async function applyAuthContext(tx: SqlTx, auth: AuthContext, userRole?: string): Promise<void> {
+    const userId = typeof auth.userId === "string" && auth.userId.trim() !== "" ? auth.userId : "anonymous";
+    const normalizedRoles = auth.roles.map((r: unknown) =>
+        typeof r === "string" ? r : (r as Record<string, unknown>)?.id ?? String(r)
+    );
+    await tx.execute(drizzleSql`
+        SELECT
+            set_config('app.user_id', ${userId}, true),
+            set_config('app.user_roles', ${normalizedRoles.join(",")}, true),
+            set_config('app.jwt', ${JSON.stringify({ sub: userId, roles: auth.roles })}, true)
+    `);
+    if (userRole) {
+        await tx.execute(drizzleSql.raw(`SET LOCAL ROLE ${quoteIdent(userRole)}`));
+    }
+}
+
+/** Role names from other BaaS platforms that people reach for out of habit. */
+const FOREIGN_CONVENTION_ROLES: Record<string, string> = {
+    authenticated: "Supabase",
+    anon: "Supabase",
+    service_role: "Supabase"
+};
+
+/**
+ * Reject `pgRoles` that this server can never satisfy.
+ *
+ * `pgRoles` sets the `TO` clause of a generated policy, so a policy naming a
+ * role the request never runs as simply never applies — and RLS then filters
+ * every row. The table reads as empty, which is indistinguishable from having
+ * no data, so the mistake survives review and ships.
+ *
+ * Requests run as `rebase_user`, so a policy is only reachable if it targets
+ * `public` or a role `rebase_user` holds. Anything else is a configuration
+ * error worth failing the boot for.
+ */
+export async function validatePolicyPgRoles(
+    run: RawSqlRunner,
+    collections: { slug?: string; securityRules?: readonly { name?: string; pgRoles?: readonly string[] }[] }[],
+    /** The role requests actually run as: `rebase_user` when the connection is
+     *  privileged enough to switch, otherwise the connection role itself. */
+    requestRole: string = REBASE_USER_ROLE
+): Promise<void> {
+    const wanted = new Map<string, string[]>();
+    for (const collection of collections) {
+        for (const rule of collection.securityRules ?? []) {
+            for (const role of rule.pgRoles ?? []) {
+                if (role === "public") continue;
+                wanted.set(role, [...(wanted.get(role) ?? []), collection.slug ?? "(unnamed)"]);
+            }
+        }
+    }
+    if (wanted.size === 0) return;
+
+    const names = [...wanted.keys()].map((r) => `'${r.replace(/'/g, "''")}'`).join(",");
+    const escapedRequestRole = requestRole.replace(/'/g, "''");
+    const rows = await run(`
+        SELECT r.rolname AS role,
+               COALESCE(pg_has_role(to_regrole('${escapedRequestRole}'), r.oid, 'MEMBER'), false) AS reachable
+        FROM pg_roles r
+        WHERE r.rolname IN (${names})
+    `);
+
+    const reachable = new Map(rows.map((row) => [String(row.role), row.reachable === true]));
+    const problems: string[] = [];
+
+    for (const [role, slugs] of wanted) {
+        if (reachable.get(role) === true) continue;
+
+        const why = reachable.has(role)
+            ? `"${requestRole}" is not a member of it`
+            : "no such role exists in this database";
+        const platform = FOREIGN_CONVENTION_ROLES[role];
+        const hint = platform
+            ? `"${role}" is a ${platform} convention, not a PostgreSQL role. Application roles belong in \`roles: ["${role === "service_role" ? "admin" : role}"]\`, which is checked inside the policy via auth.roles().`
+            : `Either grant it (GRANT ${role} TO ${requestRole}) or drop \`pgRoles\` so the policy targets \`public\`.`;
+
+        problems.push(
+            `  • pgRoles: ["${role}"] on ${slugs.join(", ")} — ${why}.\n    ${hint}`
+        );
+    }
+
+    if (problems.length > 0) {
+        throw new Error(
+            `Security rules target PostgreSQL roles this server cannot use. Requests run as ` +
+            `"${requestRole}", so these policies would never apply and every row would be ` +
+            `filtered out — the collections would look empty rather than error.\n\n` +
+            problems.join("\n\n") + "\n"
+        );
+    }
+}

package/src/services/BranchService.ts

@@ -0,0 +1,251 @@
+/**
+ * BranchService
+ *
+ * Manages database branching by creating/deleting PostgreSQL databases
+ * using `CREATE DATABASE ... TEMPLATE`. Branch metadata is stored in the
+ * `rebase.branches` table in the default (main) database, following the
+ * same `rebase` schema convention used by entity_history, auth, etc.
+ */
+
+import { sql } from "drizzle-orm";
+import { BranchInfo } from "@rebasepro/types";
+import { DrizzleClient } from "../interfaces";
+import { DatabasePoolManager } from "../databasePoolManager";
+
+/** Internal prefix applied to branch database names to avoid collisions. */
+const BRANCH_DB_PREFIX = "rb_";
+
+/** Fully-qualified metadata table in the rebase schema. */
+const BRANCHES_TABLE = "rebase.branches";
+
+/**
+ * Validate that a user-provided identifier only contains safe characters.
+ * Throws if the value contains characters outside [a-zA-Z0-9_-].
+ */
+function validateIdentifier(value: string, label: string): void {
+    if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+        throw new Error(`Invalid ${label}: only letters, digits, underscores, and hyphens are allowed.`);
+    }
+}
+
+/**
+ * Sanitize a user-provided branch name to a safe PostgreSQL identifier.
+ * Only allows alphanumeric characters and underscores.
+ */
+function sanitizeBranchName(name: string): string {
+    return name.replace(/[^a-zA-Z0-9_]/g, "");
+}
+
+/**
+ * Convert a user-facing branch name to the actual PostgreSQL database name.
+ */
+function toBranchDbName(name: string): string {
+    const sanitized = sanitizeBranchName(name);
+    if (!sanitized) throw new Error("Branch name must contain at least one alphanumeric character.");
+    return `${BRANCH_DB_PREFIX}${sanitized}`;
+}
+
+export class BranchService {
+    constructor(
+        private db: DrizzleClient,
+        private poolManager: DatabasePoolManager
+    ) {}
+
+    /**
+     * Ensure the `rebase.branches` metadata table exists in the default database.
+     * Idempotent — safe to call on every startup.
+     */
+    async ensureBranchMetadataTable(): Promise<void> {
+        // Create the rebase schema (idempotent — may already exist from auth/history init)
+        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+
+        await this.db.execute(sql.raw(`
+            CREATE TABLE IF NOT EXISTS ${BRANCHES_TABLE} (
+                name         TEXT PRIMARY KEY,
+                db_name      TEXT NOT NULL UNIQUE,
+                parent_db    TEXT NOT NULL,
+                created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                metadata     JSONB DEFAULT '{}'
+            );
+        `));
+    }
+
+    /**
+     * Create a new branch database by templating the source database.
+     *
+     * Uses `CREATE DATABASE ... TEMPLATE` for an instant, full-fidelity copy
+     * of both schema and data.
+     *
+     * @param name   User-facing branch name (e.g., "feature_auth")
+     * @param options.source  Source database to clone; defaults to the main database.
+     */
+    async createBranch(name: string, options?: { source?: string }): Promise<BranchInfo> {
+        if (options?.source) {
+            validateIdentifier(options.source, "source database name");
+        }
+
+        const dbName = toBranchDbName(name);
+        const sanitizedName = sanitizeBranchName(name);
+        const sourceDb = options?.source || this.poolManager.defaultDatabaseName;
+
+        // Check if branch already exists
+        const existing = await this.db.execute(
+            sql`SELECT name FROM rebase.branches WHERE name = ${sanitizedName} OR db_name = ${dbName}`
+        );
+        if ((existing.rows as unknown[]).length > 0) {
+            throw new Error(`Branch "${sanitizedName}" already exists.`);
+        }
+
+        // Disconnect any idle pools to the source DB so TEMPLATE works.
+        // CREATE DATABASE ... TEMPLATE requires no other connections to the template.
+        await this.poolManager.disconnectDatabase(sourceDb);
+
+        // Create the database using the source as a template.
+        // Note: Identifiers must be double-quoted, not parameterized.
+        const safeDbName = dbName.replace(/"/g, '""');
+        const safeSourceDb = sourceDb.replace(/"/g, '""');
+        try {
+            await this.db.execute(
+                sql.raw(`CREATE DATABASE "${safeDbName}" TEMPLATE "${safeSourceDb}"`)
+            );
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("already exists")) {
+                throw new Error(`Database "${dbName}" already exists on the server. Choose a different branch name.`);
+            }
+            // If template fails due to active connections, provide a helpful error
+            if (msg.includes("being accessed by other users")) {
+                throw new Error(
+                    `Cannot create branch: the source database "${sourceDb}" has active connections. ` +
+                    "Close other clients or connections and try again."
+                );
+            }
+            throw err;
+        }
+
+        // Record metadata in the default database
+        const now = new Date();
+        await this.db.execute(
+            sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at) 
+                VALUES (${sanitizedName}, ${dbName}, ${sourceDb}, ${now.toISOString()})`
+        );
+
+        return {
+            name: sanitizedName,
+            parentDatabase: sourceDb,
+            createdAt: now
+        };
+    }
+
+    /**
+     * Delete a branch database and remove its metadata.
+     * Cannot delete the main/default database.
+     */
+    async deleteBranch(name: string): Promise<void> {
+        const sanitizedName = sanitizeBranchName(name);
+        const dbName = toBranchDbName(name);
+
+        // Safety: never delete the default database
+        if (dbName === this.poolManager.defaultDatabaseName) {
+            throw new Error("Cannot delete the main database.");
+        }
+
+        // Verify the branch exists in our metadata
+        const existing = await this.db.execute(
+            sql`SELECT db_name FROM rebase.branches WHERE name = ${sanitizedName}`
+        );
+        if ((existing.rows as unknown[]).length === 0) {
+            throw new Error(`Branch "${sanitizedName}" not found.`);
+        }
+
+        // Disconnect any pools to this branch before dropping
+        await this.poolManager.disconnectDatabase(dbName);
+
+        // Drop the database
+        const safeDbName = dbName.replace(/"/g, '""');
+        try {
+            await this.db.execute(sql.raw(`DROP DATABASE "${safeDbName}"`));
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("being accessed by other users")) {
+                throw new Error(
+                    `Cannot delete branch "${sanitizedName}": the database has active connections. ` +
+                    "Close other clients and try again."
+                );
+            }
+            throw err;
+        }
+
+        // Remove metadata
+        await this.db.execute(
+            sql`DELETE FROM rebase.branches WHERE name = ${sanitizedName}`
+        );
+    }
+
+    /**
+     * List all branches recorded in the metadata table.
+     * Optionally fetches database sizes from pg_database.
+     */
+    async listBranches(): Promise<BranchInfo[]> {
+        const result = await this.db.execute(sql.raw(`
+            SELECT 
+                b.name,
+                b.parent_db,
+                b.created_at,
+                pg_database_size(b.db_name) as size_bytes
+            FROM ${BRANCHES_TABLE} b
+            JOIN pg_database d ON d.datname = b.db_name
+            ORDER BY b.created_at DESC
+        `));
+
+        return (result.rows as Record<string, unknown>[]).map((row) => ({
+            name: row.name as string,
+            parentDatabase: row.parent_db as string,
+            createdAt: new Date(row.created_at as string),
+            sizeBytes: row.size_bytes != null ? Number(row.size_bytes) : undefined
+        }));
+    }
+
+    /**
+     * Get info about a specific branch.
+     */
+    async getBranchInfo(name: string): Promise<BranchInfo | undefined> {
+        const sanitizedName = sanitizeBranchName(name);
+
+        const result = await this.db.execute(sql`
+            SELECT 
+                b.name,
+                b.parent_db,
+                b.created_at
+            FROM rebase.branches b
+            WHERE b.name = ${sanitizedName}
+        `);
+
+        const rows = result.rows as Record<string, unknown>[];
+        if (rows.length === 0) return undefined;
+
+        const row = rows[0];
+
+        // Attempt to get size — may fail if the DB was externally dropped
+        let sizeBytes: number | undefined;
+        try {
+            const dbName = toBranchDbName(sanitizedName);
+            const sizeResult = await this.db.execute(
+                sql`SELECT pg_database_size(${dbName}) as size_bytes`
+            );
+            const sizeRows = sizeResult.rows as Record<string, unknown>[];
+            if (sizeRows.length > 0 && sizeRows[0].size_bytes != null) {
+                sizeBytes = Number(sizeRows[0].size_bytes);
+            }
+        } catch {
+            // Database might not exist anymore
+        }
+
+        return {
+            name: row.name as string,
+            parentDatabase: row.parent_db as string,
+            createdAt: new Date(row.created_at as string),
+            sizeBytes
+        };
+    }
+}