@rebasepro/common 0.6.1 → 0.8.0

package/src/util/policy/evaluatePolicy.ts

@@ -0,0 +1,146 @@
+import { 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 unauthenticated. */
+    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":
+            return ctx.uid != null;
+        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":
+            return { known: true, value: ctx.uid ?? null };
+        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] };
+    }
+}
+
+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) {
+        if (op === "eq") return false;
+        if (op === "neq") return true;
+        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

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

package/src/util/policy/policyToPostgres.ts

@@ -0,0 +1,85 @@
+import { EntityCollection, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property } from "@rebasepro/types";
+import { toSnakeCase } from "@rebasepro/utils";
+
+/**
+ * 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?: EntityCollection): string {
+    switch (expr.kind) {
+        case "true":
+            return "true";
+        case "false":
+            return "false";
+        case "and":
+            return expr.operands.length === 0
+                ? "true"
+                : expr.operands.map(o => `(${policyToPostgres(o, collection)})`).join(" AND ");
+        case "or":
+            return expr.operands.length === 0
+                ? "false"
+                : expr.operands.map(o => `(${policyToPostgres(o, collection)})`).join(" OR ");
+        case "not":
+            // Render the common `auth.uid() IS NULL` (unauthenticated) form directly.
+            if (expr.operand.kind === "authenticated") return "auth.uid() IS NULL";
+            return `NOT (${policyToPostgres(expr.operand, collection)})`;
+        case "compare":
+            return `${operandToSql(expr.left, collection)} ${COMPARE_SQL[expr.op]} ${operandToSql(expr.right, collection)}`;
+        case "rolesOverlap":
+            return `string_to_array(auth.roles(), ',') && ${rolesArraySql(expr.roles)}`;
+        case "rolesContain":
+            return `string_to_array(auth.roles(), ',') @> ${rolesArraySql(expr.roles)}`;
+        case "authenticated":
+            return "auth.uid() IS NOT NULL";
+        case "raw":
+            // Full-power escape hatch: `{column}` references resolve to the bare
+            // column name (matching the previous raw-SQL behavior).
+            return expr.sql.replace(/\{(\w+)\}/g, (_, col) => col);
+    }
+}
+
+const COMPARE_SQL: Record<PolicyCompareOperator, string> = {
+    eq: "=",
+    neq: "!=",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">="
+};
+
+function operandToSql(operand: PolicyOperand, collection?: EntityCollection): string {
+    switch (operand.kind) {
+        case "field":
+            return resolveColumnName(operand.name, collection);
+        case "literal":
+            return quoteLiteral(operand.value);
+        case "authUid":
+            return "auth.uid()";
+        case "authRoles":
+            return "string_to_array(auth.roles(), ',')";
+    }
+}
+
+function resolveColumnName(propName: string, collection?: EntityCollection): string {
+    const prop = collection?.properties?.[propName] as Property | undefined;
+    if (prop && "columnName" in prop && typeof (prop as { columnName?: unknown }).columnName === "string") {
+        return (prop as { columnName: string }).columnName;
+    }
+    return toSnakeCase(propName);
+}
+
+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: string[]): string {
+    return `ARRAY[${[...roles].sort().map(r => `'${r}'`).join(",")}]`;
+}

package/src/util/policy/securityRuleToConditions.ts

@@ -0,0 +1,67 @@
+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;
+}

package/src/util/policy/sqlToPolicy.ts

@@ -0,0 +1,88 @@
+import { PolicyExpression, policy } from "@rebasepro/types";
+
+/**
+ * A tiny, regex-based SQL "parser" for security rules.
+ *
+ * This is NOT a full SQL parser. It is designed to handle the subset of SQL
+ * commonly used in `USING` and `WITH CHECK` clauses, enough to drive the
+ * optimistic client-side UI decision.
+ *
+ * It handles:
+ * - `field = 'literal'`
+ * - `field != 'literal'`
+ * - `field = current_setting('app.user_id')`
+ * - `A AND B`
+ * - `true`
+ * - `IN (...)` (as optimistic true)
+ *
+ * For anything it doesn't understand, it returns a `raw` expression, which
+ * the evaluator treats as "unknown" (and usually optimistic true).
+ */
+export function sqlToPolicy(sql: string): PolicyExpression {
+    const trimmed = sql.trim();
+
+    if (trimmed.toLowerCase() === "true") return policy.true();
+    if (trimmed.toLowerCase() === "false") return policy.false();
+
+    // Handle roles overlap (&&)
+    // Matches: string_to_array(auth.roles(), ',') && ARRAY['admin', 'editor']
+    const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
+    if (overlapMatch) {
+        const roles = overlapMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
+        return policy.rolesOverlap(roles);
+    }
+
+    // Handle roles containment (@>)
+    // Matches: string_to_array(auth.roles(), ',') @> ARRAY['admin']
+    const containMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
+    if (containMatch) {
+        const roles = containMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
+        return policy.rolesContain(roles);
+    }
+
+    // Handle OR
+    if (trimmed.toUpperCase().includes(" OR ")) {
+        const parts = trimmed.split(/ OR /i);
+        return policy.or(...parts.map(sqlToPolicy));
+    }
+
+    // Handle AND (very basic split, doesn't handle nested parens properly)
+    if (trimmed.toUpperCase().includes(" AND ")) {
+        const parts = trimmed.split(/ AND /i);
+        return policy.and(...parts.map(sqlToPolicy));
+    }
+
+    // Handle = and !=
+    const match = trimmed.match(/^(.+?)\s*(!?=)\s*(.+)$/);
+    if (match) {
+        const [, leftStr, op, rightStr] = match;
+        const left = parseOperand(leftStr.trim());
+        const right = parseOperand(rightStr.trim());
+        if (left && right) {
+            return policy.compare(left, op === "=" ? "eq" : "neq", right);
+        }
+    }
+
+    // Fallback to raw
+    return policy.raw(sql);
+}
+
+function parseOperand(str: string) {
+    // current_setting('app.user_id') or auth.uid()
+    if (/current_setting\s*\(\s*'app\.user_id'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) {
+        return policy.authUid();
+    }
+
+    // Literal string: 'value'
+    const stringMatch = str.match(/^'(.+)'$/);
+    if (stringMatch) {
+        return policy.literal(stringMatch[1]);
+    }
+
+    // Bare field name
+    if (/^\w+$/.test(str)) {
+        return policy.field(str);
+    }
+
+    return null;
+}

package/src/util/references.ts

@@ -26,7 +26,7 @@ export function getEntityImagePreviewPropertyKey<M extends Record<string, unknow
     // and arrays of URL properties with image preview type
     for (const key in collection.properties) {
         const property = collection.properties[key];
-        if (property.type === "array" && property.of && !Array.isArray(property.of) && property.of.type === "string" && property.of.url === "image") {
+        if (property.type === "array" && property.of && !Array.isArray(property.of) && property.of.type === "string" && property.of.ui?.url === "image") {
             return key;
         }
     }

package/src/util/relations.ts

@@ -1,4 +1,4 @@
-import { CollectionWithRelations, EntityCollection, getDataSourceCapabilities, Property, Relation, RelationProperty } from "@rebasepro/types";
+import { EntityCollection, getDataSourceCapabilities, Property, Relation, RelationProperty } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { generateForeignKeyName } from "@rebasepro/utils";
 
@@ -89,7 +89,7 @@ name: evaluated } as EntityCollection;
 
                 try {
                     // Look for an owning relation on the target that points back to this collection
-                    const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? (((targetCollection as CollectionWithRelations).relations) || []) : [];
+                    const targetRelations = getDataSourceCapabilities(targetCollection.engine).supportsRelations ? (targetCollection.relations || []) : [];
                     for (const targetRel of targetRelations) {
                         if (targetRel.direction === "owning" &&
                             targetRel.cardinality === "one" &&
@@ -135,7 +135,7 @@ name: evaluated } as EntityCollection;
                     // `cardinality: "many" + direction: "owning"` is sufficient to identify owning M2M.
 
                     // 1. Check the explicit relations[] array
-                    const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? (((targetCollection as CollectionWithRelations).relations) || []) : [];
+                    const targetRelations = getDataSourceCapabilities(targetCollection.engine).supportsRelations ? (targetCollection.relations || []) : [];
                     for (const targetRel of targetRelations) {
                         if (targetRel.cardinality === "many" &&
                             (targetRel.direction === "owning" || !targetRel.direction) &&
@@ -206,8 +206,7 @@ export function resolveCollectionRelations(
     const cached = _resolvedRelationsCache.get(collection);
     if (cached) return cached;
 
-    if (!getDataSourceCapabilities(collection.driver).supportsRelations) return {};
-    const relCollection = collection as CollectionWithRelations;
+    if (!getDataSourceCapabilities(collection.engine).supportsRelations) return {};
     const relations: Record<string, Relation> = {};
 
     // Track which explicit relationName values have been registered so that
@@ -217,8 +216,8 @@ export function resolveCollectionRelations(
 
     // 1. Process explicit relations from the `relations` field.
     //    Each relation is stored once under its canonical relationName key.
-    if (relCollection.relations) {
-        relCollection.relations.forEach((relation: Relation) => {
+    if (collection.relations) {
+        collection.relations.forEach((relation: Relation) => {
             try {
                 const normalizedRelation = sanitizeRelation(relation, collection);
                 const relationKey = normalizedRelation.relationName;
@@ -306,8 +305,8 @@ export function resolvePropertyRelation({
 }
 
 export function getTableName(collection: EntityCollection): string {
-    if (getDataSourceCapabilities(collection.driver).supportsRelations) {
-        return (collection as CollectionWithRelations).table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
+    if (getDataSourceCapabilities(collection.engine).supportsRelations) {
+        return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
     }
     return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
 }

package/src/util/resolutions.ts

@@ -1,8 +1,6 @@
 import {
     ArrayProperty,
     AuthController,
-    CollectionWithRelations,
-    CollectionWithSubcollections,
     EntityCollection,
     EnumValueConfig,
     EnumValues,
@@ -12,7 +10,8 @@ import {
     Relation,
     RelationProperty,
     StringProperty,
-    getDataSourceCapabilities
+    getDataSourceCapabilities,
+    getDeclaredSubcollections
 } from "@rebasepro/types";
 
 type PropertyConfig = { property: unknown; [key: string]: unknown };
@@ -347,11 +346,12 @@ export function getSubcollections<M extends Record<string, unknown> = Record<str
         return collection.childCollections() ?? [];
     }
 
-    if (getDataSourceCapabilities(collection.driver).supportsSubcollections && (collection as CollectionWithSubcollections).subcollections) {
-        return (collection as CollectionWithSubcollections).subcollections!() ?? [];
+    const declaredSubcollections = getDeclaredSubcollections(collection);
+    if (getDataSourceCapabilities(collection.engine).supportsSubcollections && declaredSubcollections) {
+        return declaredSubcollections() ?? [];
     }
 
-    if (getDataSourceCapabilities(collection.driver).supportsRelations) {
+    if (getDataSourceCapabilities(collection.engine).supportsRelations) {
         const resolvedRelations = resolveCollectionRelations(collection);
         const manyRelations = Object.values(resolvedRelations).filter((r: Relation) => r.cardinality === "many");
 

package/src/util/storage.ts

@@ -1,6 +1,39 @@
-import { ArrayProperty, EntityValues, StorageConfig, StringProperty, UploadedFileContext } from "@rebasepro/types";
+import { ArrayProperty, EntityValues, StorageConfig, StorageSource, StorageSourceRegistry, StringProperty, UploadedFileContext } from "@rebasepro/types";
 import { randomString } from "@rebasepro/utils";
 
+/**
+ * Resolve the {@link StorageSource} to use for a property, given the key
+ * referenced by `StorageConfig.storageSource`.
+ *
+ * Resolution priority:
+ * 1. No `sourceKey` → the default source (backward compatible).
+ * 2. An explicit {@link StorageSourceRegistry} (e.g. `client.storageRegistry`).
+ * 3. A `sources` lookup map (e.g. the `StorageSourcesContext`).
+ * 4. Fall back to the default source.
+ *
+ * Shared by the upload hook, the markdown editor, and the read-only previews
+ * so the resolution logic lives in one place.
+ *
+ * @group Storage
+ */
+export function resolveStorageSource(params: {
+    /** Key from `StorageConfig.storageSource`. */
+    sourceKey?: string | null;
+    /** Built sources keyed by storage-source key (e.g. from context). */
+    sources?: Record<string, StorageSource>;
+    /** Optional explicit registry — takes precedence over `sources`. */
+    registry?: StorageSourceRegistry;
+    /** Default source, used when no key is set or the key cannot be resolved. */
+    defaultSource: StorageSource;
+}): StorageSource {
+    const { sourceKey, sources, registry, defaultSource } = params;
+    if (!sourceKey) return defaultSource;
+    if (registry) return registry.getOrDefault(sourceKey);
+    const fromSources = sources?.[sourceKey];
+    if (fromSources) return fromSources;
+    return defaultSource;
+}
+
 interface ResolveFilenameStringParams<M extends Record<string, unknown>> {
     input: string | ((context: UploadedFileContext) => (Promise<string> | string));
     storage: StorageConfig;