@rebasepro/common 0.6.1 → 0.8.0

package/src/data/resolveDataSource.ts

@@ -0,0 +1,79 @@
+import {
+    DataSourceDefinition,
+    ResolvedDataSource,
+    DEFAULT_DATA_SOURCE_KEY,
+    getDataSourceCapabilities
+} from "@rebasepro/types";
+
+/**
+ * The subset of a collection needed to resolve its data source. Accepting a
+ * structural type (rather than the full `EntityCollection`) keeps this usable
+ * from anywhere — frontend router, backend registry, editor — without coupling
+ * to the collection union.
+ */
+export interface DataSourceResolvable {
+    /** Preferred routing key. */
+    dataSource?: string;
+    /** Engine type discriminant (set on variant collection types). */
+    engine?: string;
+    /** Within-engine instance. */
+    databaseId?: string;
+}
+
+/** A lookup of data-source definitions by key. */
+export type DataSourceRegistry = Record<string, DataSourceDefinition>;
+
+/**
+ * Build a keyed registry from a list of {@link DataSourceDefinition}s.
+ * Later entries win on key collision.
+ */
+export function createDataSourceRegistry(definitions?: DataSourceDefinition[]): DataSourceRegistry {
+    const registry: DataSourceRegistry = {};
+    for (const def of definitions ?? []) {
+        registry[def.key] = def;
+    }
+    return registry;
+}
+
+/**
+ * Resolve the effective data source for a collection — the single source of
+ * truth shared by the frontend router, the backend driver registry, and the
+ * editor's capability lookups.
+ *
+ * Resolution order:
+ * 1. The routing **key** is `collection.dataSource`, else
+ *    {@link DEFAULT_DATA_SOURCE_KEY}.
+ * 2. If a definition is registered for that key, it provides `engine`,
+ *    `transport`, and `databaseId`.
+ * 3. Otherwise values are synthesized: `engine` from `collection.engine`
+ *    (or the key, or `"postgres"`), `transport` defaults to `"server"`,
+ *    and `databaseId` from the collection.
+ *
+ * `capabilities` are always derived from the resolved `engine`, so two
+ * data sources sharing an engine share capabilities.
+ *
+ * @param collection the collection (or any object carrying the routing fields)
+ * @param registry   optional registry of declared data sources
+ */
+export function resolveDataSource(
+    collection: DataSourceResolvable | undefined,
+    registry?: DataSourceRegistry
+): ResolvedDataSource {
+    const key = collection?.dataSource ?? DEFAULT_DATA_SOURCE_KEY;
+    const def = registry?.[key];
+
+    const engine = def?.engine
+        ?? collection?.engine
+        ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : "postgres");
+
+    const transport = def?.transport ?? "server";
+    const databaseId = collection?.databaseId ?? def?.databaseId;
+
+    return {
+        key,
+        engine,
+        transport,
+        databaseId,
+        capabilities: getDataSourceCapabilities(engine)
+    };
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from "./util";
 export * from "./collections";
 export * from "./data/buildRebaseData";
+export * from "./data/buildRoutedRebaseData";
+export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
-
+export * from "./data/filter-dialect";
+export * from "./table-classification";

package/src/table-classification.ts

@@ -0,0 +1,109 @@
+/**
+ * Table Classification
+ *
+ * Shared constants and pure functions for classifying database tables.
+ * Used by both the server-side PostgresBackendDriver and the Studio RLS editor.
+ */
+
+/** Possible categories a database table can belong to. */
+export type TableCategory = "rebase-internal" | "junction" | "user";
+
+/** Schemas that are always considered Rebase-internal. */
+export const REBASE_INTERNAL_SCHEMAS: readonly string[] = ["rebase", "auth"];
+
+/** Table-name prefixes that mark a table as Rebase-internal regardless of schema. */
+export const REBASE_INTERNAL_PREFIXES: readonly string[] = [
+  "_rebase_",
+  "_auth_",
+  "drizzle_",
+];
+
+/**
+ * Synchronously classify a table based on naming conventions.
+ *
+ * @param tableName  - The unqualified name of the table.
+ * @param schemaName - The schema the table belongs to (e.g. `"public"`, `"rebase"`).
+ * @returns `"rebase-internal"` when the table belongs to a reserved schema or
+ *          carries a reserved prefix; `"user"` otherwise.
+ *
+ * @remarks
+ * Junction-table detection requires an async database query and is therefore
+ * **not** handled by this function. Use {@link detectJunctionTables} to obtain
+ * the set of junction tables, then reclassify as needed.
+ */
+export function classifyTable(
+  tableName: string,
+  schemaName: string,
+): TableCategory {
+  if (
+    REBASE_INTERNAL_SCHEMAS.includes(schemaName) ||
+    REBASE_INTERNAL_PREFIXES.some((prefix) => tableName.startsWith(prefix))
+  ) {
+    return "rebase-internal";
+  }
+
+  return "user";
+}
+
+/**
+ * Convenience predicate that checks whether a table is Rebase-internal.
+ *
+ * @param tableName  - The unqualified name of the table.
+ * @param schemaName - The schema the table belongs to.
+ * @returns `true` if the table is classified as `"rebase-internal"`.
+ */
+export function isRebaseInternalTable(
+  tableName: string,
+  schemaName: string,
+): boolean {
+  return classifyTable(tableName, schemaName) === "rebase-internal";
+}
+
+/** SQL query that detects junction tables in the `public` schema. */
+export const JUNCTION_TABLES_SQL = `
+  SELECT t.table_name
+  FROM information_schema.tables t
+  WHERE t.table_schema = 'public'
+    AND t.table_type = 'BASE TABLE'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM information_schema.columns c
+      WHERE c.table_schema = t.table_schema
+        AND c.table_name = t.table_name
+        AND c.column_name NOT IN (
+          SELECT kcu.column_name
+          FROM information_schema.key_column_usage kcu
+          JOIN information_schema.table_constraints tc
+            ON tc.constraint_name = kcu.constraint_name
+            AND tc.table_schema = kcu.table_schema
+          WHERE tc.constraint_type = 'FOREIGN KEY'
+            AND kcu.table_schema = t.table_schema
+            AND kcu.table_name = t.table_name
+        )
+    )
+`;
+
+/**
+ * Asynchronously detect junction (link) tables in the `public` schema.
+ *
+ * A junction table is defined as a table where **every** column participates in
+ * at least one foreign-key constraint.
+ *
+ * @param executeSql - A callback that executes a raw SQL string and returns the
+ *                     resulting rows.
+ * @returns A `Set` containing the names of all detected junction tables.
+ */
+export async function detectJunctionTables(
+  executeSql: (sql: string) => Promise<Record<string, unknown>[]>,
+): Promise<Set<string>> {
+  const rows = await executeSql(JUNCTION_TABLES_SQL);
+  const junctionTables = new Set<string>();
+
+  for (const row of rows) {
+    if (typeof row.table_name === "string") {
+      junctionTables.add(row.table_name);
+    }
+  }
+
+  return junctionTables;
+}

package/src/util/builders.ts

@@ -7,9 +7,17 @@ import {
     EntityCollection,
     EnumValueConfig,
     EnumValues,
+    FirebaseCollection,
+    FirebaseProperties,
     GeopointProperty,
+    InferEntityType,
     MapProperty,
-    NumberProperty, Properties,
+    MongoDBCollection,
+    MongoProperties,
+    NumberProperty,
+    PostgresCollection,
+    PostgresProperties,
+    Properties,
     Property,
     ReferenceProperty,
     StringProperty,
@@ -32,6 +40,75 @@ export function buildCollection<
     return collection;
 }
 
+// ── defineCollection ─────────────────────────────────────────────────────
+// A smarter builder that uses `const` type-parameter inference (TS 5.0+)
+// to capture literal property types automatically. This gives you
+// autocomplete on `titleProperty`, `sort`, `propertiesOrder`, `fixedFilter`,
+// callbacks, etc. — without writing `as const` or passing manual generics.
+
+/**
+ * Define a PostgreSQL-backed collection with full type inference.
+ *
+ * The `const P` generic captures literal property types from your
+ * `properties` object, which enables autocomplete on `titleProperty`,
+ * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
+ *
+ * @example
+ * ```ts
+ * const products = defineCollection({
+ *     name: "Products",
+ *     slug: "products",
+ *     table: "products",
+ *     properties: {
+ *         name: { name: "Name", type: "string", validation: { required: true } },
+ *         price: { name: "Price", type: "number" },
+ *     },
+ *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     sort: ["price", "asc"], // ✅ autocomplete on first element
+ * });
+ * ```
+ *
+ * @group Builder
+ */
+export function defineCollection<
+    const P extends PostgresProperties,
+    USER extends User = User
+>(
+    collection: Omit<PostgresCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): PostgresCollection<InferEntityType<P>, USER> & { properties: P };
+
+/**
+ * Define a Firestore-backed collection with full type inference.
+ * @group Builder
+ */
+export function defineCollection<
+    const P extends FirebaseProperties,
+    USER extends User = User
+>(
+    collection: Omit<FirebaseCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): FirebaseCollection<InferEntityType<P>, USER> & { properties: P };
+
+/**
+ * Define a MongoDB-backed collection with full type inference.
+ * @group Builder
+ */
+export function defineCollection<
+    const P extends MongoProperties,
+    USER extends User = User
+>(
+    collection: Omit<MongoDBCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): MongoDBCollection<InferEntityType<P>, USER> & { properties: P };
+
+/**
+ * Implementation — delegates to the correct overload at the type level.
+ * At runtime this is a plain identity function.
+ */
+export function defineCollection(
+    collection: EntityCollection
+): EntityCollection {
+    return collection;
+}
+
 /**
  * Identity function we use to defeat the type system of Typescript and preserve
  * the property keys.

package/src/util/callbacks.ts

@@ -1,4 +1,11 @@
-import { EntityCallbacks, Properties } from "@rebasepro/types";
+import { EntityCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
+
+/**
+ * Context passed to entity lifecycle callbacks.
+ * @group Models
+ */
+export type EntityCallbackContext = RebaseCallContext;
+
 
 /**
  * Helper function to recursively check if there are any callbacks in the properties.

package/src/util/index.ts

@@ -4,6 +4,7 @@ export * from "./entities";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
+export * from "./policy";
 export * from "./permissions";
 export * from "./references";
 export * from "./navigation_from_path";

package/src/util/permissions.test.ts

@@ -162,9 +162,10 @@ roles: ["author"] }
         expect(canReadCollection(collection, mockAuthController)).toBe(true);
     });
 
-    test("11. Empty roles array [] on rule grants access to everyone (public)", () => {
+    test("11. Empty roles array [] adds no role restriction (public rule stays public)", () => {
         const collection = createMockCollection([
             { operation: "insert",
+access: "public",
 roles: [] }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
@@ -172,9 +173,10 @@ roles: [] }
         expect(canCreateEntity(collection, adminAuthController, "test", null)).toBe(true);
     });
 
-    test("12. Undefined roles on rule grants access to everyone (public)", () => {
+    test("12. Undefined roles on a public rule grants access to everyone", () => {
         const collection = createMockCollection([
-            { operation: "insert" }
+            { operation: "insert",
+access: "public" }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
         expect(canCreateEntity(collection, unauthenticatedController, "test", null)).toBe(true);

package/src/util/permissions.ts

@@ -1,4 +1,6 @@
-import { CollectionWithRelations, Entity, EntityCollection, getDataSourceCapabilities, SecurityRule, User } from "@rebasepro/types";
+import { Entity, EntityCollection, getDataSourceCapabilities, SecurityOperation, SecurityRule, User } from "@rebasepro/types";
+import { securityRuleToConditions } from "./policy/securityRuleToConditions";
+import { evaluatePolicy, PolicyEvalContext, TriState } from "./policy/evaluatePolicy";
 
 /**
  * Minimal auth context for permission checking.
@@ -9,195 +11,120 @@ export interface AuthContext<USER extends User = User> {
     user: USER | null;
 }
 
-function evaluateAST<USER extends User, M extends Record<string, unknown>>(sqlString: string, auth: AuthContext<USER>, entity: Entity<M> | null): boolean {
-    // This is a client-side SQL evaluator used *only* for optimistic UI updates.
-    // It parses basic AND / OR statements to evaluate RLS without backend roundtrips.
-    if (!entity) return true;
-
-    // 1. Clean outer parentheses
-    let cleanedSQL = sqlString.trim();
-    while (cleanedSQL.startsWith("(") && cleanedSQL.endsWith(")")) {
-        let openCount = 0;
-        let isEnclosing = true;
-        for (let i = 0; i < cleanedSQL.length - 1; i++) {
-            if (cleanedSQL[i] === "(") openCount++;
-            else if (cleanedSQL[i] === ")") openCount--;
-            if (openCount === 0) {
-                isEnclosing = false;
-                break;
-            }
-        }
-        if (isEnclosing) {
-            cleanedSQL = cleanedSQL.substring(1, cleanedSQL.length - 1).trim();
-        } else {
-            break;
-        }
-    }
-
-    // 2. Split top-level OR / AND
-    const splitByTopLevel = (str: string, delimiter: string) => {
-        const parts: string[] = [];
-        let current = "";
-        let openCount = 0;
-        let i = 0;
-        while (i < str.length) {
-            if (str[i] === "(") openCount++;
-            else if (str[i] === ")") openCount--;
-
-            if (openCount === 0 && str.substring(i).toUpperCase().startsWith(delimiter)) {
-                parts.push(current);
-                current = "";
-                i += delimiter.length;
-            } else {
-                current += str[i];
-                i++;
-            }
-        }
-        parts.push(current);
-        return parts;
-    };
-
-    const orParts = splitByTopLevel(cleanedSQL, " OR ");
-    if (orParts.length > 1) {
-        return orParts.some(part => evaluateAST(part, auth, entity));
-    }
-
-    const andParts = splitByTopLevel(cleanedSQL, " AND ");
-    if (andParts.length > 1) {
-        return andParts.every(part => evaluateAST(part, auth, entity));
-    }
-
-    const upperSQL = cleanedSQL.toUpperCase();
-
-    // 3. Fallback for unparseable complex queries
-    if (upperSQL.includes(" IN ") || upperSQL.includes(" EXISTS ")) {
-        return true;
-    }
-
-    // 4. Role array checks
-    // Pattern: `string_to_array(auth.roles(), ',') && ARRAY['admin', 'editor']`
-    const roleIntersectMatch = cleanedSQL.match(/string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\[(.*?)\]/i);
-    if (roleIntersectMatch && roleIntersectMatch[1]) {
-        const requiredRoles = roleIntersectMatch[1].split(",").map(r => r.trim().replace(/'/g, ""));
-        const userRoles = auth.user?.roles || [];
-        return requiredRoles.some(r => userRoles.includes(r));
-    }
-
-    // Pattern: `string_to_array(auth.roles(), ',') @> ARRAY['admin']`
-    const roleContainMatch = cleanedSQL.match(/string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\[(.*?)\]/i);
-    if (roleContainMatch && roleContainMatch[1]) {
-        const requiredRoles = roleContainMatch[1].split(",").map(r => r.trim().replace(/'/g, ""));
-        const userRoles = auth.user?.roles || [];
-        return requiredRoles.every(r => userRoles.includes(r));
-    }
-
-    // 5. Existing ID patterns
-    const pattern1 = new RegExp("^\\{?([a-zA-Z0-9_]+)\\}?\\s*=\\s*(?:current_setting\\s*\\(\\s*'app\\.user_id'\\s*\\)|auth\\.uid\\(\\))");
-    const pattern2 = new RegExp("^(?:current_setting\\s*\\(\\s*'app\\.user_id'\\s*\\)|auth\\.uid\\(\\))\\s*=\\s*\\{?([a-zA-Z0-9_]+)\\}?");
-
-    const match1 = cleanedSQL.match(pattern1);
-    if (match1 && match1[1]) {
-        return entity.values[match1[1]] === auth.user?.uid;
-    }
+/**
+ * How to resolve a policy result that cannot be decided client-side (a raw-SQL
+ * escape-hatch rule, or a row-column reference with no row in hand).
+ *
+ * - `"allow"` (default): optimistic — used for admin-UI gating, where Postgres
+ *   remains the authoritative gate and hiding a working action is worse than
+ *   showing one the server may reject.
+ * - `"deny"`: fail-closed — used by real enforcement callers (e.g. a driver
+ *   applying policies in-process), so an undecidable rule never silently allows.
+ */
+export type UnknownResolution = "allow" | "deny";
 
-    const match2 = cleanedSQL.match(pattern2);
-    if (match2 && match2[1]) {
-        return entity.values[match2[1]] === auth.user?.uid;
-    }
+export interface CheckOperationOptions {
+    onUnknown?: UnknownResolution;
+}
 
-    // 6. Simple equality
-    // Pattern: `field = 'value'` or `{field} != 'value'`
-    const simpleEqualityMatch = cleanedSQL.match(/^\{?([\w_]+)\}?\s*(=|!=)\s*'([^']+)'$/i);
-    if (simpleEqualityMatch) {
-        const field = simpleEqualityMatch[1];
-        const operator = simpleEqualityMatch[2];
-        const value = simpleEqualityMatch[3];
-        const entityValue = entity.values[field];
-        if (operator === "=") return entityValue === value;
-        if (operator === "!=") return entityValue !== value;
-    }
+/** Combine clause results with AND under three-valued (Kleene) logic. */
+function kleeneAnd(values: TriState[]): TriState {
+    if (values.some(v => v === false)) return false;
+    if (values.some(v => v === "unknown")) return "unknown";
+    return true;
+}
 
-    return true; // Optimistic fallback for anything else
+/** The operations a rule covers, mirroring the Postgres generator's resolution. */
+function ruleOperations(rule: SecurityRule): SecurityOperation[] {
+    return rule.operations && rule.operations.length > 0
+        ? rule.operations
+        : [rule.operation ?? "all"];
 }
 
-function evaluateRule<USER extends User, M extends Record<string, unknown>>(rule: SecurityRule, auth: AuthContext<USER>, entity: Entity<M> | null): boolean {
+function ruleApplies(rule: SecurityRule, targetOperation: SecurityOperation): boolean {
+    const ops = ruleOperations(rule);
+    return ops.includes(targetOperation) || ops.includes("all");
+}
 
-    if (rule.access === "public") return true;
+/**
+ * Evaluate a single rule for one operation, returning a tri-state.
+ *
+ * A `null` clause (the rule contributes no condition for a required clause)
+ * denies — matching Postgres, which emits `USING (false)` / `WITH CHECK (false)`
+ * in that case. USING applies to SELECT/UPDATE/DELETE; WITH CHECK to
+ * INSERT/UPDATE; both must pass for UPDATE.
+ */
+function evaluateRuleForOperation(rule: SecurityRule, ctx: PolicyEvalContext, targetOperation: SecurityOperation): TriState {
+    const { usingExpr, withCheckExpr } = securityRuleToConditions(rule);
+    const clause = (expr: typeof usingExpr): TriState => expr === null ? false : evaluatePolicy(expr, ctx);
 
-    if (rule.ownerField) {
-        if (!entity) {
-            // null entity: optimistic — we can't evaluate ownership without data
-            // Fall through to SQL checks below (if any). If none, will return true.
-        } else {
-            // Entity present: strictly check ownership. Fail immediately if mismatch.
-            if (entity.values[rule.ownerField] !== auth.user?.uid) return false;
-        }
-    }
+    const needsUsing = targetOperation !== "insert";
+    const needsWithCheck = targetOperation === "insert" || targetOperation === "update";
 
-    // In PostgreSQL RLS, USING and WITH CHECK have distinct semantics:
-    // USING applies to existing rows (SELECT/UPDATE/DELETE read phase)
-    // WITH CHECK applies to new/modified values (INSERT/UPDATE write phase)
-    // Both must pass. We evaluate both independently.
-    if (rule.using && !evaluateAST(rule.using, auth, entity)) return false;
-    if (rule.withCheck && !evaluateAST(rule.withCheck, auth, entity)) return false;
+    const results: TriState[] = [];
+    if (needsUsing) results.push(clause(usingExpr));
+    if (needsWithCheck) results.push(clause(withCheckExpr));
+    return kleeneAnd(results);
+}
 
-    return true;
+function resolveTriState(value: TriState, onUnknown: UnknownResolution): boolean {
+    if (value === "unknown") return onUnknown === "allow";
+    return value;
 }
 
+/**
+ * Decide whether an operation is permitted for a user on a (possibly null) row,
+ * by evaluating the collection's security rules with the shared policy model —
+ * the same model compiled to Postgres RLS DDL, so the decision matches database
+ * enforcement for every non-raw rule.
+ *
+ * @param options.onUnknown how to treat rules that cannot be decided
+ *   client-side (raw SQL, or row predicates with no row). Defaults to `"allow"`
+ *   for optimistic UI gating; enforcement callers should pass `"deny"`.
+ */
 export function checkOperation<M extends Record<string, unknown>, USER extends User>(
     collection: EntityCollection<M>,
     authContext: AuthContext<USER>,
     entity: Entity<M> | null,
-    targetOperation: "select" | "insert" | "update" | "delete"
+    targetOperation: SecurityOperation,
+    options?: CheckOperationOptions
 ): boolean {
-    const securityRules = getDataSourceCapabilities(collection.driver).supportsRLS ? (collection as CollectionWithRelations).securityRules : undefined;
+    const onUnknown = options?.onUnknown ?? "allow";
+    const securityRules = getDataSourceCapabilities(collection.engine).supportsRLS ? collection.securityRules : undefined;
     if (!securityRules || securityRules.length === 0) {
         return true;
     }
 
-    const applicableRules = securityRules.filter((r: SecurityRule) =>
-        r.operation === targetOperation ||
-        r.operation === "all" ||
-        r.operations?.includes(targetOperation) ||
-        r.operations?.includes("all")
-    );
-
+    const applicableRules = securityRules.filter((r: SecurityRule) => ruleApplies(r, targetOperation));
     if (applicableRules.length === 0) return false;
 
-    const userRoleIds = authContext.user?.roles ?? [];
-    const userRoles = [...userRoleIds, "public"];
-    const roleApplicableRules = applicableRules.filter((rule: SecurityRule) => {
-        if (!rule.roles || rule.roles.length === 0) return true;
-        return rule.roles.some((r: string) => userRoles.includes(r));
-    });
-
-    if (roleApplicableRules.length === 0) return false;
+    const ctx: PolicyEvalContext = {
+        uid: authContext.user?.uid,
+        roles: authContext.user?.roles ?? [],
+        entity
+    };
 
     let grantedByPermissive = false;
     let deniedByRestrictive = false;
+    let hasPermissive = false;
 
-    for (const rule of roleApplicableRules) {
+    for (const rule of applicableRules) {
         const mode = rule.mode || "permissive";
-        const passed = evaluateRule(rule, authContext, entity);
+        const passed = resolveTriState(evaluateRuleForOperation(rule, ctx, targetOperation), onUnknown);
 
-        if (mode === "restrictive" && !passed) {
-            deniedByRestrictive = true;
-            break;
-        }
-
-        if (mode === "permissive" && passed) {
-            grantedByPermissive = true;
+        if (mode === "restrictive") {
+            if (!passed) {
+                deniedByRestrictive = true;
+                break;
+            }
+        } else {
+            hasPermissive = true;
+            if (passed) grantedByPermissive = true;
         }
     }
 
     if (deniedByRestrictive) return false;
-
-    const hasPermissive = roleApplicableRules.some((r: SecurityRule) => (r.mode || "permissive") === "permissive");
-    if (hasPermissive) {
-        return grantedByPermissive;
-    } else {
-        return false;
-    }
+    return hasPermissive ? grantedByPermissive : false;
 }
 
 export function canReadCollection<M extends Record<string, unknown>, USER extends User>