@rebasepro/common 0.17.3 → 0.18.0

package/src/util/policy/evaluatePolicy.ts

@@ -1,194 +0,0 @@
-import { ANONYMOUS_USER_ID, isAnonymousUid, Entity, PolicyCompareOperator, PolicyExpression, PolicyOperand } from "@rebasepro/types";
-
-/**
- * Result of evaluating a policy client-side. `"unknown"` means the expression
- * could not be decided without more information — either a raw-SQL escape-hatch
- * node (which the client deliberately never guesses) or a row-column reference
- * with no entity in hand (e.g. list-level gating). Callers decide how to resolve
- * `"unknown"`: fail-closed for an enforcement decision, optimistic for pure
- * visibility gating.
- */
-export type TriState = boolean | "unknown";
-
-/**
- * Context for {@link evaluatePolicy}: the acting user (or none) and the row
- * being evaluated (or none, for collection-level gating).
- */
-export interface PolicyEvalContext {
-    /**
-     * The current user's id, or null/undefined when no user is signed in.
-     *
-     * Null here means *anonymous visitor*, not "server context" — a client is
-     * never the server context. `authUid` operands therefore resolve to
-     * {@link ANONYMOUS_USER_ID} rather than `null`, matching the `rebase.uid()`
-     * the database would see for the same request.
-     */
-    uid?: string | null;
-    /** The current user's application roles. */
-    roles?: string[];
-    /** The row being evaluated, or null when no specific row is available. */
-    entity: Entity | null;
-}
-
-/**
- * Evaluates a {@link PolicyExpression} against a user + row, using three-valued
- * (Kleene) logic so that `"unknown"` sub-results propagate soundly.
- *
- * This is the JavaScript twin of {@link policyToPostgres}: both derive from the
- * same expression, so the admin UI matches database enforcement by construction
- * for every non-raw rule.
- */
-export function evaluatePolicy(expr: PolicyExpression, ctx: PolicyEvalContext): TriState {
-    switch (expr.kind) {
-        case "true":
-            return true;
-        case "false":
-            return false;
-        case "and":
-            return kleeneAnd(expr.operands.map(o => evaluatePolicy(o, ctx)));
-        case "or":
-            return kleeneOr(expr.operands.map(o => evaluatePolicy(o, ctx)));
-        case "not":
-            return kleeneNot(evaluatePolicy(expr.operand, ctx));
-        case "compare":
-            return evaluateCompare(expr.op, expr.left, expr.right, ctx);
-        case "rolesOverlap": {
-            const userRoles = ctx.roles ?? [];
-            return expr.roles.some(r => r === "public" || userRoles.includes(r));
-        }
-        case "rolesContain": {
-            const userRoles = ctx.roles ?? [];
-            return expr.roles.every(r => r === "public" || userRoles.includes(r));
-        }
-        case "authenticated":
-            // Every anonymous spelling, matching what this node compiles to in
-            // Postgres — the two evaluators disagreeing about who is signed in
-            // is the client optimistically rendering a row the database will
-            // refuse, or hiding one it would have allowed.
-            return ctx.uid != null && !isAnonymousUid(ctx.uid);
-        case "serverContext":
-            // A client is never the server context. Postgres decides this by
-            // `rebase.uid() IS NULL`, which a client request can never produce:
-            // the driver substitutes ANONYMOUS_USER_ID for a missing id.
-            return false;
-        case "existsIn":
-            // A membership subquery cannot be run client-side — server-authoritative.
-            return "unknown";
-        case "raw":
-            // Arbitrary SQL cannot be evaluated client-side — never guess.
-            return "unknown";
-    }
-}
-
-// ── Three-valued logic ───────────────────────────────────────────────
-
-function kleeneAnd(values: TriState[]): TriState {
-    if (values.some(v => v === false)) return false;
-    if (values.some(v => v === "unknown")) return "unknown";
-    return true;
-}
-
-function kleeneOr(values: TriState[]): TriState {
-    if (values.some(v => v === true)) return true;
-    if (values.some(v => v === "unknown")) return "unknown";
-    return false;
-}
-
-function kleeneNot(value: TriState): TriState {
-    if (value === "unknown") return "unknown";
-    return !value;
-}
-
-// ── Comparison ───────────────────────────────────────────────────────
-
-type ResolvedOperand = { known: false } | { known: true; value: unknown };
-
-function resolveOperand(operand: PolicyOperand, ctx: PolicyEvalContext): ResolvedOperand {
-    switch (operand.kind) {
-        case "literal":
-            return { known: true, value: operand.value };
-        case "authUid":
-            // The sentinel, not null: `rebase.uid()` is never NULL for a request
-            // that came from a client, so comparing against null here would
-            // disagree with the database on exactly the rules that test for it
-            // (e.g. `rebase.uid() <> 'anonymous'`).
-            return { known: true, value: ctx.uid ?? ANONYMOUS_USER_ID };
-        case "authRoles":
-            return { known: true, value: ctx.roles ?? [] };
-        case "field":
-            // Can't resolve a row column without the row.
-            if (!ctx.entity) return { known: false };
-            return { known: true, value: ctx.entity.values[operand.name] };
-        case "outerField":
-            // Only meaningful inside an `existsIn` subquery (server-authoritative).
-            return { known: false };
-    }
-}
-
-function evaluateCompare(
-    op: PolicyCompareOperator,
-    left: PolicyOperand,
-    right: PolicyOperand,
-    ctx: PolicyEvalContext
-): TriState {
-    const l = resolveOperand(left, ctx);
-    const r = resolveOperand(right, ctx);
-    if (!l.known || !r.known) return "unknown";
-
-    const a = l.value;
-    const b = r.value;
-
-    if (a === null || b === null) {
-        // SQL answers NULL for *every* comparison against NULL, and a policy
-        // that answers NULL does not grant the row. So the only question here
-        // is which JavaScript answer reproduces that outcome.
-        //
-        // This used to answer `false` for `eq` and `true` for `neq`, which is
-        // JavaScript's two-valued reading of a three-valued question.
-        //
-        // `neq` was a grant the database does not give:
-        // `owner_id != rebase.uid()` on a row whose `owner_id` is NULL read as
-        // *permitted* in the admin panel and was refused by Postgres — on every
-        // row where the column is null, which for a nullable column is usually
-        // most of them.
-        //
-        // `false` for `eq` looked safe, because false denies and NULL denies.
-        // It is not, because it does not survive negation: `not(a = NULL)`
-        // became `true` while `NOT NULL` stays NULL, so the same grant reappears
-        // one operator up. A local answer that is only right in a positive
-        // position is not right — it just moves.
-        //
-        // "unknown" is what SQL actually says, it composes correctly through
-        // Kleene negation, and enforcement callers already resolve it
-        // fail-closed. Both were found by the exhaustive Postgres differential
-        // in `policy-agreement-exhaustive.test.ts`, the second only after the
-        // first was fixed.
-        return "unknown";
-    }
-
-    if (op === "eq") return a === b;
-    if (op === "neq") return a !== b;
-
-    if (typeof a === "string" && typeof b === "string") {
-        if (op === "lt") return a < b;
-        if (op === "lte") return a <= b;
-        if (op === "gt") return a > b;
-        if (op === "gte") return a >= b;
-    }
-
-    if (typeof a === "number" && typeof b === "number") {
-        if (op === "lt") return a < b;
-        if (op === "lte") return a <= b;
-        if (op === "gt") return a > b;
-        if (op === "gte") return a >= b;
-    }
-
-    if (typeof a === "bigint" && typeof b === "bigint") {
-        if (op === "lt") return a < b;
-        if (op === "lte") return a <= b;
-        if (op === "gt") return a > b;
-        if (op === "gte") return a >= b;
-    }
-
-    return "unknown";
-}

package/src/util/policy/index.ts

@@ -1,4 +0,0 @@
-export * from "./securityRuleToConditions";
-export * from "./sqlToPolicy";
-export * from "./policyToPostgres";
-export * from "./evaluatePolicy";

package/src/util/policy/policyToPostgres.ts

@@ -1,263 +0,0 @@
-import { ANONYMOUS_USER_IDS, CollectionConfig, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property, ExistsInPolicyExpression, RLS_ROLES_SQL, RLS_UID_SQL, rewriteLegacyRlsFunctions } from "@rebasepro/types";
-import { toSnakeCase } from "@rebasepro/utils";
-import { getTableName } from "../relations";
-
-/**
- * Options for {@link policyToPostgres}.
- */
-export interface PolicyCompileOptions {
-    /**
-     * Resolve a collection by slug. Required to compile
-     * {@link ExistsInPolicyExpression} (`policy.existsIn`) — the compiler needs
-     * the joined collection to derive its table name / schema. When omitted, the
-     * join table falls back to a snake_cased slug.
-     */
-    resolveCollection?: (slug: string) => CollectionConfig | undefined;
-}
-
-/**
- * The lexical scope threaded through compilation. It changes when we descend
- * into an `existsIn` subquery: inside it, `field` refers to the joined table
- * (aliased) while `outerField` refers to the outer RLS row (table-qualified).
- */
-interface CompileScope {
-    /** Collection whose columns a bare `field` operand resolves against. */
-    fieldCollection?: CollectionConfig;
-    /** SQL prefix for `field` operands (`""` at top level, `"alias".` in a subquery). */
-    fieldPrefix: string;
-    /** The outer RLS collection, for `outerField` operands. */
-    outerCollection?: CollectionConfig;
-    /** SQL prefix for `outerField` operands (`""` at top level, `"schema"."table".` in a subquery). */
-    outerPrefix: string;
-    resolveCollection?: (slug: string) => CollectionConfig | undefined;
-    /** Monotonic counter for generating unique subquery aliases. */
-    alias: { n: number };
-}
-
-/**
- * Compiles a {@link PolicyExpression} to a PostgreSQL boolean SQL string,
- * suitable for a `USING (...)` / `WITH CHECK (...)` clause.
- *
- * This is one of the two consumers of the shared policy model (the other being
- * {@link evaluatePolicy}); the Postgres schema generators call it so that DDL
- * and the admin UI derive from the exact same expression.
- */
-export function policyToPostgres(expr: PolicyExpression, collection?: CollectionConfig, options?: PolicyCompileOptions): string {
-    return compile(expr, {
-        fieldCollection: collection,
-        fieldPrefix: "",
-        outerCollection: collection,
-        outerPrefix: "",
-        resolveCollection: options?.resolveCollection,
-        alias: { n: 0 }
-    });
-}
-
-function compile(expr: PolicyExpression, scope: CompileScope): string {
-    switch (expr.kind) {
-        case "true":
-            return "true";
-        case "false":
-            return "false";
-        case "and":
-            return expr.operands.length === 0
-                ? "true"
-                : expr.operands.map(o => `(${compile(o, scope)})`).join(" AND ");
-        case "or":
-            return expr.operands.length === 0
-                ? "false"
-                : expr.operands.map(o => `(${compile(o, scope)})`).join(" OR ");
-        case "not":
-            return `NOT (${compile(expr.operand, scope)})`;
-        case "compare": {
-            // `rebase.uid()` returns text; cast the column side so uuid / integer
-            // id columns compare cleanly instead of failing with
-            // "operator does not exist: uuid = text" at CREATE POLICY time.
-            const castForAuthUid = (operand: PolicyOperand, sqlText: string, other: PolicyOperand): string =>
-                other.kind === "authUid" && (operand.kind === "field" || operand.kind === "outerField")
-                    ? `(${sqlText})::text`
-                    : sqlText;
-            const leftSql = castForAuthUid(expr.left, operandToSql(expr.left, scope), expr.right);
-            const rightSql = castForAuthUid(expr.right, operandToSql(expr.right, scope), expr.left);
-            return `${leftSql} ${COMPARE_SQL[expr.op]} ${rightSql}`;
-        }
-        case "rolesOverlap":
-            return `string_to_array(${RLS_ROLES_SQL}, ',') && ${rolesArraySql(expr.roles)}`;
-        case "rolesContain":
-            return `string_to_array(${RLS_ROLES_SQL}, ',') @> ${rolesArraySql(expr.roles)}`;
-        case "authenticated":
-            // `IS NOT NULL` alone is a tautology on the user path: every
-            // user-context request sets `app.uid`, and an anonymous one sets
-            // it to a sentinel. Excluding the sentinels is what makes this mean
-            // "signed in" rather than "anyone at all".
-            //
-            // Every sentinel, not just the current one. This clause is written
-            // into the database and outlives the server that generated it: a
-            // policy compiled here may be enforced against an older server that
-            // still reports `'anon'`, which is exactly how excluding one
-            // spelling turned this helper into a grant. See ANONYMOUS_USER_IDS.
-            return `${RLS_UID_SQL} IS NOT NULL AND ${RLS_UID_SQL} NOT IN (${ANONYMOUS_USER_IDS.map(quoteLiteral).join(", ")})`;
-        case "serverContext":
-            // Only the built-in server flows leave `app.uid` unset.
-            return `${RLS_UID_SQL} IS NULL`;
-        case "existsIn":
-            return compileExistsIn(expr, scope);
-        case "raw": {
-            // A project written against a pre-1.0 release may still spell the
-            // helpers `auth.uid()`. Rewritten rather than rejected: the rule
-            // means exactly the same thing, the developer cannot be expected to
-            // have read a changelog mid-deploy, and the alternative is a policy
-            // that compiles cleanly and then denies every row at runtime because
-            // it calls a function that no longer exists.
-            //
-            // The counterpart is `warnOnLegacyRlsFunctions`, which says so once
-            // at boot with the file to edit — silence here would leave the old
-            // spelling working forever and make the migration permanent.
-            const sqlText = rewriteLegacyRlsFunctions(expr.sql);
-
-            // Full-power escape hatch: `{column}` denotes a column of the outer
-            // RLS row. It must be table-qualified, not bare: raw SQL may open its
-            // own subquery over the same table, and there a bare name binds to the
-            // inner scope, collapsing `m.x = {x}` into the tautology `m.x = m.x`.
-            return sqlText.replace(/\{(\w+)\}/g, (_, col) =>
-                `${outerQualifier(scope)}${resolveColumnName(col, scope.outerCollection)}`);
-        }
-    }
-}
-
-/**
- * Compiles `existsIn` to a correlated `EXISTS (SELECT 1 FROM <join> WHERE ...)`.
- * Inside the subquery, `field` operands bind to the aliased join table and
- * `outerField` operands bind to the (table-qualified) outer RLS row.
- */
-function compileExistsIn(expr: ExistsInPolicyExpression, scope: CompileScope): string {
-    const join = scope.resolveCollection?.(expr.collection);
-    const joinTable = join ? getTableName(join) : toSnakeCase(expr.collection);
-    const joinSchema = schemaOf(join) ?? schemaOf(scope.outerCollection) ?? "public";
-    const alias = `_ex${scope.alias.n++}`;
-
-    // `outerField` inside the subquery must be qualified with the outer table,
-    // otherwise a bare column name would bind to the joined table instead.
-    const outerPrefix = outerQualifier(scope);
-
-    const innerScope: CompileScope = {
-        fieldCollection: join,
-        fieldPrefix: `"${alias}".`,
-        outerCollection: scope.outerCollection,
-        outerPrefix,
-        resolveCollection: scope.resolveCollection,
-        alias: scope.alias
-    };
-    return `EXISTS (SELECT 1 FROM "${joinSchema}"."${joinTable}" "${alias}" WHERE ${compile(expr.where, innerScope)})`;
-}
-
-const COMPARE_SQL: Record<PolicyCompareOperator, string> = {
-    eq: "=",
-    neq: "!=",
-    lt: "<",
-    lte: "<=",
-    gt: ">",
-    gte: ">="
-};
-
-function operandToSql(operand: PolicyOperand, scope: CompileScope): string {
-    switch (operand.kind) {
-        case "field":
-            return `${scope.fieldPrefix}${resolveColumnName(operand.name, scope.fieldCollection)}`;
-        case "outerField":
-            return `${scope.outerPrefix}${resolveColumnName(operand.name, scope.outerCollection)}`;
-        case "literal":
-            return quoteLiteral(operand.value);
-        case "authUid":
-            return RLS_UID_SQL;
-        case "authRoles":
-            return `string_to_array(${RLS_ROLES_SQL}, ',')`;
-    }
-}
-
-/**
- * SQL prefix that qualifies a column of the outer RLS row (`"schema"."table".`),
- * or `""` when the collection is unknown.
- */
-function outerQualifier(scope: CompileScope): string {
-    const table = scope.outerCollection ? getTableName(scope.outerCollection) : undefined;
-    if (!table) return "";
-    return `"${schemaOf(scope.outerCollection) ?? "public"}"."${table}".`;
-}
-
-function schemaOf(collection?: CollectionConfig): string | undefined {
-    return (collection as { schema?: string } | undefined)?.schema || undefined;
-}
-
-function resolveColumnName(propName: string, collection?: CollectionConfig): string {
-    const prop = collection?.properties?.[propName] as Property | undefined;
-    if (prop && "columnName" in prop && typeof (prop as { columnName?: unknown }).columnName === "string") {
-        return quoteColumnIdentifier((prop as { columnName: string }).columnName);
-    }
-    return quoteColumnIdentifier(toSnakeCase(propName));
-}
-
-/**
- * Every PostgreSQL keyword that cannot stand as a bare column reference.
- * Appendix C's two reserved categories — plain "reserved", and "reserved (can
- * be function or type name)" — since neither may name a column unquoted.
- */
-const RESERVED_SQL_WORDS = new Set([
-    "all", "analyse", "analyze", "and", "any", "array", "as", "asc", "asymmetric", "authorization",
-    "binary", "both", "case", "cast", "check", "collate", "collation", "column", "concurrently",
-    "constraint", "create", "cross", "current_catalog", "current_date", "current_role",
-    "current_schema", "current_time", "current_timestamp", "current_user", "default", "deferrable",
-    "desc", "distinct", "do", "else", "end", "except", "false", "fetch", "for", "foreign", "freeze",
-    "from", "full", "grant", "group", "having", "ilike", "in", "initially", "inner", "intersect",
-    "into", "is", "isnull", "join", "lateral", "leading", "left", "like", "limit", "localtime",
-    "localtimestamp", "natural", "not", "notnull", "null", "offset", "on", "only", "or", "order",
-    "outer", "overlaps", "placing", "primary", "references", "returning", "right", "select",
-    "session_user", "similar", "some", "symmetric", "system_user", "table", "tablesample", "then",
-    "to", "trailing", "true", "union", "unique", "user", "using", "variadic", "verbose", "when",
-    "where", "window", "with"
-]);
-
-/** An identifier Postgres reads back unchanged without quotes. */
-const BARE_IDENTIFIER = /^[a-z_][a-z0-9_$]*$/;
-
-/**
- * Quote a column reference when Postgres would not read the bare name as that
- * column — and only then.
- *
- * Three ways a bare name goes wrong, in ascending order of how long it takes to
- * notice:
- *
- * - **Case.** `columnName` is used verbatim, and `rebase schema introspect`
- *   populates it from a live database, so a legacy `"createdAt"` column arrives
- *   spelled exactly that way. Unquoted, Postgres folds it to `createdat` and
- *   `CREATE POLICY` fails with "column does not exist" — the collection keeps
- *   RLS enabled with no policy, which denies every row.
- * - **Syntax.** A column named `order` or `default` is a syntax error mid-clause.
- * - **Silent rebinding.** `user`, `current_user`, `session_user`, `current_date`
- *   and friends are *valid bare expressions*, so the policy compiles, applies,
- *   and is reported as a success — while comparing against the connected role
- *   or the wall clock instead of the column. Under RLS every request runs as the
- *   same `rebase_user` role, so `USING (user = rebase.uid())` is a constant: it
- *   denies everything, and its negation admits everything.
- *
- * Only the names that need it are quoted, so an ordinary snake_case policy body
- * is emitted byte-for-byte as before. That keeps generated artifacts and the
- * policies already stored in shipped databases stable — this fix reaches the
- * clauses that were broken and no others.
- */
-function quoteColumnIdentifier(name: string): string {
-    if (BARE_IDENTIFIER.test(name) && !RESERVED_SQL_WORDS.has(name)) return name;
-    return `"${name.replace(/"/g, "\"\"")}"`;
-}
-
-function quoteLiteral(value: string | number | boolean | null): string {
-    if (value === null) return "NULL";
-    if (typeof value === "boolean") return value ? "true" : "false";
-    if (typeof value === "number") return String(value);
-    return `'${value.replace(/'/g, "''")}'`;
-}
-
-/** Sorted, single-quoted `ARRAY['a','b']` — matches the generators' output. */
-function rolesArraySql(roles: readonly string[]): string {
-    return `ARRAY[${[...roles].sort().map(r => `'${r}'`).join(",")}]`;
-}

package/src/util/policy/securityRuleToConditions.ts

@@ -1,67 +0,0 @@
-import { PolicyExpression, SecurityRule, policy } from "@rebasepro/types";
-import { sqlToPolicy } from "./sqlToPolicy";
-
-/**
- * The normalized `USING` / `WITH CHECK` conditions for a single security rule,
- * expressed in the engine-agnostic {@link PolicyExpression} model.
- *
- * A `null` clause means "this rule contributes no condition for that clause";
- * consumers apply the default (Postgres denies with `false`).
- */
-export interface RuleConditions {
-    usingExpr: PolicyExpression | null;
-    withCheckExpr: PolicyExpression | null;
-}
-
-/**
- * Desugars a {@link SecurityRule} — its `access`/`ownerField`/`roles` shortcuts,
- * structured `condition`/`check`, and raw `using`/`withCheck` — into a single
- * normalized {@link PolicyExpression} pair.
- *
- * **This is the linchpin against drift:** both the Postgres DDL generators and
- * the client-side evaluator consume this one function, so there is exactly one
- * definition of what a rule means. In particular, application `roles` are folded
- * into the expression here (AND'd with the base condition, matching how Postgres
- * generates the clause) rather than being handled separately by each consumer.
- */
-export function securityRuleToConditions(rule: SecurityRule): RuleConditions {
-    return {
-        usingExpr: withRoles(baseUsing(rule), rule),
-        withCheckExpr: withRoles(baseWithCheck(rule), rule)
-    };
-}
-
-function baseUsing(rule: SecurityRule): PolicyExpression | null {
-    if (rule.condition) return rule.condition;
-    if (rule.using != null) return sqlToPolicy(rule.using);
-    if (rule.access === "public") return policy.true();
-    if (rule.ownerField) return policy.compare(policy.field(rule.ownerField), "eq", policy.authUid());
-    return null;
-}
-
-function baseWithCheck(rule: SecurityRule): PolicyExpression | null {
-    if (rule.check) return rule.check;
-    if (rule.withCheck != null) return sqlToPolicy(rule.withCheck);
-    // No explicit WITH CHECK → fall back to the USING condition, matching
-    // PostgreSQL's own default behavior.
-    return baseUsing(rule);
-}
-
-/**
- * AND the base condition with an application-role check, or produce a roles-only
- * condition when there is no base. Mirrors the Postgres generator so that a
- * role-scoped restrictive rule denies exactly the same set of users on both
- * sides.
- */
-function withRoles(base: PolicyExpression | null, rule: SecurityRule): PolicyExpression | null {
-    if (!rule.roles || rule.roles.length === 0) return base;
-    const rolesExpr = policy.rolesOverlap(rule.roles);
-    if (rule.mode === "restrictive") {
-        // Restrictive rule: applies ONLY if user has the roles.
-        // If user DOES NOT have the roles, they are NOT restricted (passes).
-        // If user HAS the roles, they must pass the base condition.
-        // Logical equivalent: NOT(roles) OR base
-        return base ? policy.or(policy.not(rolesExpr), base) : policy.not(rolesExpr);
-    }
-    return base ? policy.and(base, rolesExpr) : rolesExpr;
-}