@facilis.dev/db 0.0.0-stage → 0.1.1

package/dist/policy.js

@@ -0,0 +1,111 @@
+import { sql } from "drizzle-orm";
+/** Non-superuser role used for policy-scoped work; RLS is bypassed by superusers (D-008). */
+export const APP_ROLE = "facilis_app";
+/** Thrown when the app role has not been bootstrapped yet (`ensureAppRole`). */
+export class AppRoleUnavailableError extends Error {
+    code = "app_role_unavailable";
+    constructor(cause) {
+        super(`App role "${APP_ROLE}" is unavailable; run ensureAppRole() after migrations.`, {
+            cause,
+        });
+        this.name = "AppRoleUnavailableError";
+    }
+}
+/**
+ * Creates the non-superuser role that policy-scoped queries run as and reconciles its
+ * privileges with the live schema: **RLS is the grant boundary** (D-136). A table with RLS
+ * enabled gets DML for the app role (its policies then decide the rows); a table without RLS
+ * gets no table privilege at all, so only the system identity can touch it. Sequences stay
+ * granted to both classes: USAGE can neither read nor write a table, and serial/identity
+ * columns need it for inserts. Idempotent and re-asserting: safe on every boot, and the
+ * blanket grants an older cluster carries are revoked the next time this runs.
+ *
+ * The role is `NOINHERIT` on purpose. It is a member of `facilis_system` so a deployment
+ * whose connection already is `facilis_app` can `SET ROLE` for the audited elevation
+ * (D-099); membership must not hand the request identity the system role's grants, or the
+ * system-only tables would be reachable from every handler. `SET ROLE` still works with
+ * `NOINHERIT`: only implicit inheritance of the member role's privileges is disabled.
+ */
+export async function ensureAppRole(db) {
+    const existing = await db.db.execute(sql `select 1 from pg_roles where rolname = ${APP_ROLE}`);
+    if (existing.rows.length === 0) {
+        await db.db.execute(sql.raw(`CREATE ROLE ${APP_ROLE} NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT`));
+    }
+    // Re-assert attributes in case an older dev dataDir created the role differently.
+    await db.db.execute(sql.raw(`ALTER ROLE ${APP_ROLE} NOSUPERUSER NOBYPASSRLS NOLOGIN NOINHERIT`));
+    await db.db.execute(sql.raw(`GRANT USAGE ON SCHEMA public TO ${APP_ROLE}`));
+    // No table default privilege: a table a migration creates stays closed to the app role
+    // until its RLS is on and this function runs again after the migration. The REVOKE also
+    // clears the default an older version of this function installed on existing clusters.
+    await db.db.execute(sql.raw(`ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE SELECT, INSERT, UPDATE, DELETE ON TABLES FROM ${APP_ROLE}`));
+    await db.db.execute(sql.raw(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${APP_ROLE}`));
+    await db.db.execute(sql.raw(`ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${APP_ROLE}`));
+    // Clear every table-class privilege before re-granting: it removes the blanket grant an
+    // older cluster installed on objects the classification below does not cover (partition
+    // children, materialized and foreign tables) and on system-only tables. Views lose their
+    // grant here and get it back from applyViews, the only code that grants one (D-097).
+    await db.db.execute(sql.raw(`REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA public FROM ${APP_ROLE}`));
+    const systemOnlyTables = [];
+    for (const table of await publicTables(db)) {
+        const identifier = sql.identifier(table.name);
+        if (table.rowSecurityEnabled) {
+            await db.db.execute(sql `grant select, insert, update, delete on table ${identifier} to ${sql.identifier(APP_ROLE)}`);
+            continue;
+        }
+        // Belt and braces: PUBLIC holds nothing by default, but a hand-written grant must not
+        // reopen a system-only table.
+        await db.db.execute(sql `revoke all privileges on table ${identifier} from ${sql.identifier(APP_ROLE)}`);
+        await db.db.execute(sql `revoke all privileges on table ${identifier} from public`);
+        systemOnlyTables.push(table.name);
+    }
+    return { systemOnlyTables };
+}
+/**
+ * Runs `fn` in one transaction whose Postgres identity is facilis_app and whose GUCs carry
+ * the scope. GUC values travel through set_config parameters, never string concatenation.
+ */
+export async function runWithPolicyScope(db, scope, fn) {
+    return db.db.transaction(async (tx) => {
+        try {
+            // SET LOCAL ROLE drops back to the connecting (superuser) role at commit.
+            await tx.execute(sql.raw(`SET LOCAL ROLE ${APP_ROLE}`));
+        }
+        catch (cause) {
+            throw new AppRoleUnavailableError(cause);
+        }
+        const roles = JSON.stringify(scope.roles ?? []);
+        const permissions = JSON.stringify(scope.permissions ?? []);
+        await tx.execute(sql `
+      select
+        set_config('app.tenant_id', ${scope.tenantId ?? ""}, true),
+        set_config('app.user_id', ${scope.userId ?? ""}, true),
+        set_config('app.roles', ${roles}, true),
+        set_config('app.permissions', ${permissions}, true)
+    `);
+        return fn(tx);
+    });
+}
+/**
+ * The grant loop's input. The catalog, not the code schema, decides: migrations are what
+ * actually enabled RLS. Partition children are skipped — routing through a partitioned
+ * parent checks the parent's privilege, and the framework has no partitioned tables today.
+ */
+async function publicTables(db) {
+    const result = await db.db.execute(sql `
+    select c.relname as name, c.relrowsecurity as row_security
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'public' and c.relkind in ('r', 'p') and not c.relispartition
+    order by c.relname
+  `);
+    const tables = [];
+    for (const row of result.rows) {
+        const name = row["name"];
+        const rowSecurityEnabled = row["row_security"];
+        if (typeof name !== "string" || typeof rowSecurityEnabled !== "boolean") {
+            throw new Error("ensureAppRole: unexpected pg_class row shape");
+        }
+        tables.push({ name, rowSecurityEnabled });
+    }
+    return tables;
+}

package/dist/query-console.d.ts

@@ -0,0 +1,44 @@
+import type { FacilisDb } from "./client.js";
+export declare const DEFAULT_QUERY_LIMIT = 100;
+export declare const MAX_QUERY_LIMIT = 500;
+/** A console query must not hang the dev server; 5s is generous for a preview. */
+export declare const QUERY_STATEMENT_TIMEOUT_MS = 5000;
+export type QueryExecutionErrorCode = "invalid_name" | "invalid_sql" | "invalid_permission" | "query_failed" | "create_failed";
+/** A console operation the route reports as a 400 `{ code }` body. */
+export declare class QueryExecutionError extends Error {
+    readonly code: QueryExecutionErrorCode;
+    constructor(code: QueryExecutionErrorCode, message: string);
+}
+export interface QueryColumn {
+    readonly name: string;
+    /** Postgres type name from pg_type (e.g. "uuid", "timestamptz"). */
+    readonly pgType: string;
+}
+export interface QueryExecution {
+    readonly columns: readonly QueryColumn[];
+    readonly rows: readonly (readonly unknown[])[];
+    readonly rowCount: number;
+    readonly elapsedMs: number;
+    readonly truncated: boolean;
+}
+/**
+ * Run one read-only statement for the console.
+ *
+ * The prefix check is the friendly error; the read-only transaction is the boundary: a
+ * data-modifying CTE (WITH ... DELETE) passes the prefix check and is rejected by
+ * Postgres. The statement is wrapped in an outer LIMIT so a preview cannot stream the
+ * whole table into the browser, and a statement timeout keeps a runaway query from
+ * pinning the dev server.
+ */
+export declare function runReadOnlyQuery(db: FacilisDb, sqlText: string, limit?: number): Promise<QueryExecution>;
+/**
+ * Create (or replace) a live view from the console's SQL and grant the policy role.
+ * The Studio writes db/views/<name>.ts afterwards; this call makes the view usable
+ * immediately, before the next boot re-applies the code.
+ */
+export declare function createLiveView(db: FacilisDb, name: string, queryText: string, permission?: string): Promise<void>;
+/**
+ * JSON-safe cell value. Postgres drivers hand back bigint, Date, Uint8Array and nested
+ * jsonb; JSON.stringify would throw on bigint and silently reshape the rest.
+ */
+export declare function toJsonValue(value: unknown): unknown;

package/dist/query-console.js

@@ -0,0 +1,173 @@
+// Read-only SQL execution and live view creation for the Studio's dev console
+// (SPEC §11.2, D-097).
+//
+// This lives in @facilis.dev/db because it is SQL: AGENTS.md security rule 5 keeps raw Drizzle
+// imports inside this package. The Nitro route owns transport and validation; this module
+// owns the read-only transaction and the JSON-safe result shape.
+import { sql } from "drizzle-orm";
+import { APP_ROLE } from "./policy.js";
+import { isReadOnlySql, stripTrailingSemicolon } from "./read-only-sql.js";
+import { grantViewSelect, ViewDefinitionError, viewDefinitionStatement } from "./views.js";
+export const DEFAULT_QUERY_LIMIT = 100;
+export const MAX_QUERY_LIMIT = 500;
+/** A console query must not hang the dev server; 5s is generous for a preview. */
+export const QUERY_STATEMENT_TIMEOUT_MS = 5000;
+/** A console operation the route reports as a 400 `{ code }` body. */
+export class QueryExecutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "QueryExecutionError";
+        this.code = code;
+    }
+}
+/**
+ * Run one read-only statement for the console.
+ *
+ * The prefix check is the friendly error; the read-only transaction is the boundary: a
+ * data-modifying CTE (WITH ... DELETE) passes the prefix check and is rejected by
+ * Postgres. The statement is wrapped in an outer LIMIT so a preview cannot stream the
+ * whole table into the browser, and a statement timeout keeps a runaway query from
+ * pinning the dev server.
+ */
+export async function runReadOnlyQuery(db, sqlText, limit = DEFAULT_QUERY_LIMIT) {
+    if (!isReadOnlySql(sqlText)) {
+        throw new QueryExecutionError("invalid_sql", "The console runs one read-only statement (SELECT, WITH, VALUES or TABLE).");
+    }
+    const statement = stripTrailingSemicolon(sqlText);
+    const capped = Math.min(Math.max(Math.trunc(limit), 1), MAX_QUERY_LIMIT);
+    const startedAt = performance.now();
+    try {
+        return await db.db.transaction(async (tx) => {
+            await tx.execute(sql.raw("set transaction read only"));
+            await tx.execute(sql.raw("set local statement_timeout = '" + QUERY_STATEMENT_TIMEOUT_MS + "ms'"));
+            const result = await tx.execute(sql.raw("select * from (\n" + statement + "\n) as __facilis_query limit " + (capped + 1)));
+            const fields = readFields(result);
+            if (fields.length === 0) {
+                throw new QueryExecutionError("query_failed", "The statement returned no result columns.");
+            }
+            const types = await readTypeNames(tx, fields);
+            const rows = result.rows
+                .slice(0, capped)
+                .map((row) => fields.map((field) => toJsonValue(row[field.name])));
+            return {
+                columns: fields.map((field) => ({
+                    name: field.name,
+                    pgType: types.get(field.dataTypeID) ?? "unknown",
+                })),
+                rows,
+                rowCount: rows.length,
+                elapsedMs: Math.round(performance.now() - startedAt),
+                truncated: result.rows.length > capped,
+            };
+        });
+    }
+    catch (error) {
+        // Postgres errors are plain driver objects; the console reports the reason as a code,
+        // never a 500 with a stack.
+        if (error instanceof QueryExecutionError)
+            throw error;
+        throw new QueryExecutionError("query_failed", messageOf(error));
+    }
+}
+/**
+ * Create (or replace) a live view from the console's SQL and grant the policy role.
+ * The Studio writes db/views/<name>.ts afterwards; this call makes the view usable
+ * immediately, before the next boot re-applies the code.
+ */
+export async function createLiveView(db, name, queryText, permission) {
+    let statement;
+    try {
+        statement = viewDefinitionStatement(name, queryText, permission);
+    }
+    catch (error) {
+        if (error instanceof ViewDefinitionError) {
+            throw new QueryExecutionError(error.code, error.message);
+        }
+        throw error;
+    }
+    try {
+        await db.db.execute(statement);
+    }
+    catch (error) {
+        throw new QueryExecutionError("create_failed", messageOf(error));
+    }
+    try {
+        await grantViewSelect(db, name);
+    }
+    catch (error) {
+        throw new QueryExecutionError("create_failed", "View created, but the grant to " + APP_ROLE + " failed: " + messageOf(error));
+    }
+}
+async function readTypeNames(tx, fields) {
+    const types = new Map();
+    const oids = [...new Set(fields.map((field) => field.dataTypeID))].filter((oid) => Number.isInteger(oid));
+    if (oids.length === 0)
+        return types;
+    const result = await tx.execute(sql.raw("select oid, typname from pg_type where oid in (" + oids.join(", ") + ")"));
+    for (const row of result.rows) {
+        const oid = Number(row["oid"]);
+        const name = row["typname"];
+        if (Number.isInteger(oid) && typeof name === "string")
+            types.set(oid, name);
+    }
+    return types;
+}
+function readFields(result) {
+    if (typeof result !== "object" || result === null)
+        return [];
+    const fields = Reflect.get(result, "fields");
+    if (!Array.isArray(fields))
+        return [];
+    const out = [];
+    for (const entry of fields) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const name = Reflect.get(entry, "name");
+        const oid = Reflect.get(entry, "dataTypeID");
+        if (typeof name === "string" && typeof oid === "number")
+            out.push({ name, dataTypeID: oid });
+    }
+    return out;
+}
+/**
+ * JSON-safe cell value. Postgres drivers hand back bigint, Date, Uint8Array and nested
+ * jsonb; JSON.stringify would throw on bigint and silently reshape the rest.
+ */
+export function toJsonValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Uint8Array)
+        return "\\x" + [...value].map(hexByte).join("");
+    if (Array.isArray(value))
+        return value.map(toJsonValue);
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value))
+            out[key] = toJsonValue(entry);
+        return out;
+    }
+    return String(value);
+}
+function hexByte(byte) {
+    return byte.toString(16).padStart(2, "0");
+}
+function messageOf(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    // Drizzle wraps a driver error in "Failed query: …"; the reason (e.g. "cannot execute
+    // DELETE in a read-only transaction") is in the cause and is what the console shows.
+    const cause = error.cause;
+    if (cause instanceof Error && cause.message.length > 0) {
+        return error.message + ": " + cause.message;
+    }
+    return error.message;
+}

package/dist/read-only-sql.d.ts

@@ -0,0 +1,13 @@
+/** True for a single read-only statement: SELECT, WITH, VALUES or TABLE. */
+export declare function isReadOnlySql(text: string): boolean;
+/** The statement without a trailing semicolon, for embedding in a wrapper or in DDL. */
+export declare function stripTrailingSemicolon(text: string): string;
+/** The first keyword of the statement, comments and whitespace skipped. */
+export declare function firstKeyword(text: string): string | null;
+/**
+ * True when a ';' is followed by anything but comments/whitespace, or by another ';'.
+ * Backslashes are NOT treated as escapes: standard_conforming_strings is on, and a
+ * missed closing quote would make the scanner swallow a real statement separator (a
+ * false "single statement" is the one answer this must never give).
+ */
+export declare function hasMultipleStatements(text: string): boolean;

package/dist/read-only-sql.js

@@ -0,0 +1,145 @@
+// Static guards for SQL text that reaches a read-only surface (SPEC §11.2).
+//
+// These checks are the UX half of the contract: the dev query endpoint wraps every
+// statement in a read-only transaction, which is what actually rejects writes. They still
+// matter where a query is inlined into another statement — a view definition is embedded
+// in CREATE VIEW, so a second statement must never slip through, and a prefix check alone
+// would accept "select 1; drop table todos".
+const READ_ONLY_KEYWORDS = new Set(["SELECT", "WITH", "VALUES", "TABLE"]);
+/** True for a single read-only statement: SELECT, WITH, VALUES or TABLE. */
+export function isReadOnlySql(text) {
+    const keyword = firstKeyword(text);
+    if (keyword === null || !READ_ONLY_KEYWORDS.has(keyword))
+        return false;
+    return !hasMultipleStatements(text);
+}
+/** The statement without a trailing semicolon, for embedding in a wrapper or in DDL. */
+export function stripTrailingSemicolon(text) {
+    return text.trim().replace(/;\s*$/, "");
+}
+function isSpace(ch) {
+    return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+/** True when the text at `cursor.index` starts a comment; advances past it when so. */
+function skipComment(cursor) {
+    const { text, index } = cursor;
+    if (text[index] === "-" && text[index + 1] === "-") {
+        const newline = text.indexOf("\n", index + 2);
+        cursor.index = newline === -1 ? text.length : newline + 1;
+        return true;
+    }
+    if (text[index] === "/" && text[index + 1] === "*") {
+        // Postgres block comments nest; count them so an inner comment cannot end the outer.
+        let depth = 1;
+        let at = index + 2;
+        while (at < text.length && depth > 0) {
+            if (text[at] === "/" && text[at + 1] === "*") {
+                depth += 1;
+                at += 2;
+                continue;
+            }
+            if (text[at] === "*" && text[at + 1] === "/") {
+                depth -= 1;
+                at += 2;
+                continue;
+            }
+            at += 1;
+        }
+        cursor.index = at;
+        return true;
+    }
+    return false;
+}
+/** The first keyword of the statement, comments and whitespace skipped. */
+export function firstKeyword(text) {
+    const cursor = { text, index: 0 };
+    while (cursor.index < text.length) {
+        while (cursor.index < text.length && isSpace(text[cursor.index] ?? ""))
+            cursor.index += 1;
+        if (skipComment(cursor))
+            continue;
+        break;
+    }
+    const match = /^[A-Za-z]+/.exec(text.slice(cursor.index));
+    return match === null ? null : match[0].toUpperCase();
+}
+/**
+ * True when a ';' is followed by anything but comments/whitespace, or by another ';'.
+ * Backslashes are NOT treated as escapes: standard_conforming_strings is on, and a
+ * missed closing quote would make the scanner swallow a real statement separator (a
+ * false "single statement" is the one answer this must never give).
+ */
+export function hasMultipleStatements(text) {
+    const cursor = { text, index: 0 };
+    let state = { kind: "normal" };
+    let separatorSeen = false;
+    while (cursor.index < text.length) {
+        const ch = text[cursor.index] ?? "";
+        if (state.kind === "normal") {
+            if (skipComment(cursor))
+                continue;
+            if (isSpace(ch)) {
+                cursor.index += 1;
+                continue;
+            }
+            if (separatorSeen)
+                return true;
+            if (ch === "'") {
+                state = { kind: "single" };
+                cursor.index += 1;
+                continue;
+            }
+            if (ch === '"') {
+                state = { kind: "double" };
+                cursor.index += 1;
+                continue;
+            }
+            if (ch === "$") {
+                const tag = dollarTagAt(text, cursor.index);
+                if (tag !== null) {
+                    state = { kind: "dollar", tag };
+                    cursor.index += tag.length;
+                    continue;
+                }
+            }
+            if (ch === ";")
+                separatorSeen = true;
+            cursor.index += 1;
+            continue;
+        }
+        if (state.kind === "single") {
+            if (ch === "'") {
+                if (text[cursor.index + 1] === "'") {
+                    cursor.index += 2;
+                    continue;
+                }
+                state = { kind: "normal" };
+            }
+            cursor.index += 1;
+            continue;
+        }
+        if (state.kind === "double") {
+            if (ch === '"') {
+                if (text[cursor.index + 1] === '"') {
+                    cursor.index += 2;
+                    continue;
+                }
+                state = { kind: "normal" };
+            }
+            cursor.index += 1;
+            continue;
+        }
+        if (text.startsWith(state.tag, cursor.index)) {
+            cursor.index += state.tag.length;
+            state = { kind: "normal" };
+            continue;
+        }
+        cursor.index += 1;
+    }
+    return false;
+}
+/** A complete dollar-quote tag (`$tag$`) at `index`, or null for a positional parameter. */
+function dollarTagAt(text, index) {
+    const match = /^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/.exec(text.slice(index));
+    return match === null ? null : match[0];
+}

package/dist/rls.d.ts

@@ -0,0 +1,37 @@
+import { type PgPolicy } from "drizzle-orm/pg-core";
+/** Row-level-security extras returned by `rlsForTable` for a pgTable definition. */
+export interface RlsOptions {
+    readonly tenantColumn?: string;
+    readonly ownerColumn?: string;
+    readonly rolesColumn?: string;
+}
+export interface RlsExtras {
+    readonly enableRLS: true;
+    readonly policies: PgPolicy[];
+}
+/**
+ * Tenant isolation as a RESTRICTIVE policy. Deviation from SPEC §8.4.5's original SQL:
+ * as written there the policy is permissive, and Postgres ORs permissive policies, so
+ * role/owner clauses let callers cross tenants. D-008 (Phase 0 evidence) fixes this by
+ * making tenant isolation RESTRICTIVE (always AND-ed); this generator emits that form.
+ */
+export declare function tenantIsolationPolicy(column?: string): PgPolicy;
+/** Permissive policy granting a caller rows they own (SPEC §8.4.5 owner clause). */
+export declare function ownerIsolationPolicy(column?: string): PgPolicy;
+/**
+ * Permissive role policy: a row is visible when the row's `column` names one of the
+ * caller's app roles (`app.roles::jsonb ? column`). Columns hold a role name such as
+ * "admin"; roles themselves are never Postgres roles (SPEC §8.4.5).
+ */
+export declare function rolePolicy(column: string, policyName?: string): PgPolicy;
+/**
+ * Builds the standard policy set for a scoped table. Use as
+ * `pgTable(..., () => rlsForTable({ tenantColumn }).policies).enableRLS()`.
+ * (`enableRLS` is returned so callers can assert/forward the flag; Drizzle applies it
+ * through `.enableRLS()`, since pgTable's extras callback only accepts config values.)
+ */
+export declare function rlsForTable(options?: RlsOptions): RlsExtras;
+/** Alias kept for the wording used in the Phase 1 contracts file. */
+export declare const withRls: typeof rlsForTable;
+/** Renders a complete CREATE POLICY statement (used by migrations and the manifest). */
+export declare function policyCreateSql(tableName: string, policy: PgPolicy): string;

package/dist/rls.js

@@ -0,0 +1,90 @@
+import { sql } from "drizzle-orm";
+import { PgDialect, pgPolicy } from "drizzle-orm/pg-core";
+const dialect = new PgDialect();
+/**
+ * Tenant isolation as a RESTRICTIVE policy. Deviation from SPEC §8.4.5's original SQL:
+ * as written there the policy is permissive, and Postgres ORs permissive policies, so
+ * role/owner clauses let callers cross tenants. D-008 (Phase 0 evidence) fixes this by
+ * making tenant isolation RESTRICTIVE (always AND-ed); this generator emits that form.
+ */
+export function tenantIsolationPolicy(column = "tenant_id") {
+    return pgPolicy("tenant_isolation", {
+        as: "restrictive",
+        for: "all",
+        using: tenantPredicate(column),
+        withCheck: tenantPredicate(column),
+    });
+}
+/** Permissive policy granting a caller rows they own (SPEC §8.4.5 owner clause). */
+export function ownerIsolationPolicy(column = "owner_id") {
+    return pgPolicy("owner_isolation", {
+        for: "all",
+        using: ownerPredicate(column),
+        withCheck: ownerPredicate(column),
+    });
+}
+/**
+ * Permissive role policy: a row is visible when the row's `column` names one of the
+ * caller's app roles (`app.roles::jsonb ? column`). Columns hold a role name such as
+ * "admin"; roles themselves are never Postgres roles (SPEC §8.4.5).
+ */
+export function rolePolicy(column, policyName = "role_access") {
+    return pgPolicy(policyName, {
+        for: "all",
+        using: rolePredicate(column),
+        withCheck: rolePredicate(column),
+    });
+}
+/**
+ * Builds the standard policy set for a scoped table. Use as
+ * `pgTable(..., () => rlsForTable({ tenantColumn }).policies).enableRLS()`.
+ * (`enableRLS` is returned so callers can assert/forward the flag; Drizzle applies it
+ * through `.enableRLS()`, since pgTable's extras callback only accepts config values.)
+ */
+export function rlsForTable(options = {}) {
+    const policies = [tenantIsolationPolicy(options.tenantColumn)];
+    if (options.ownerColumn !== undefined)
+        policies.push(ownerIsolationPolicy(options.ownerColumn));
+    if (options.rolesColumn !== undefined)
+        policies.push(rolePolicy(options.rolesColumn));
+    return { enableRLS: true, policies };
+}
+/** Alias kept for the wording used in the Phase 1 contracts file. */
+export const withRls = rlsForTable;
+/** Renders a complete CREATE POLICY statement (used by migrations and the manifest). */
+export function policyCreateSql(tableName, policy) {
+    const parts = [`CREATE POLICY ${quoteIdentifier(policy.name)} ON ${quoteIdentifier(tableName)}`];
+    if (policy.as !== undefined)
+        parts.push(`AS ${policy.as.toUpperCase()}`);
+    parts.push(`FOR ${(policy.for ?? "all").toUpperCase()}`);
+    if (policy.to !== undefined)
+        parts.push(`TO ${policyToList(policy.to)}`);
+    if (policy.using !== undefined)
+        parts.push(`USING (${dialect.sqlToQuery(policy.using).sql})`);
+    if (policy.withCheck !== undefined) {
+        parts.push(`WITH CHECK (${dialect.sqlToQuery(policy.withCheck).sql})`);
+    }
+    return `${parts.join(" ")};`;
+}
+function tenantPredicate(column) {
+    return sql `${sql.identifier(column)} = nullif(current_setting('app.tenant_id', true), '')::uuid`;
+}
+function ownerPredicate(column) {
+    return sql `${sql.identifier(column)} = nullif(current_setting('app.user_id', true), '')::uuid`;
+}
+function rolePredicate(column) {
+    return sql `nullif(current_setting('app.roles', true), '')::jsonb ? ${sql.identifier(column)}`;
+}
+function quoteIdentifier(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+function policyToList(to) {
+    if (Array.isArray(to))
+        return to.map((entry) => policyToList(entry)).join(", ");
+    if (typeof to === "string") {
+        return ["public", "current_role", "current_user", "session_user"].includes(to)
+            ? to.toUpperCase()
+            : quoteIdentifier(to);
+    }
+    return quoteIdentifier(to.name);
+}