@rebasepro/common 0.8.0 → 0.9.1-canary.09aaf62

package/src/data/filter-dialect.ts

@@ -5,6 +5,13 @@
  * PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
  * Everything else speaks `FilterValues` exclusively.
  *
+ * Wire-format values are always strings — the wire format carries no type
+ * metadata, so type coercion is the responsibility of the server-side data
+ * driver which has access to the collection schema.
+ *
+ * Commas inside list values are backslash-escaped (`\,`), and literal
+ * backslashes are escaped as `\\`.
+ *
  * @module
  */
 
@@ -16,74 +23,130 @@ import {
     RestFilterOp,
     toCanonicalOp,
     LogicalCondition,
-    FilterCondition
+    FilterCondition,
+    NULL_OPS
 } from "@rebasepro/types";
+import { normalizeToEntityRelation } from "../util/entities";
 
 // ---------------------------------------------------------------------------
-// Value coercion (querystring → typed JS values)
+// Value stringification
 // ---------------------------------------------------------------------------
 
-/**
- * Coerce a raw querystring value to its natural JS type.
- * - `"true"` / `"false"` → boolean
- * - `"null"` → null
- * - Numeric strings → number
- * - Everything else → string (unchanged)
- */
-function coerceValue(raw: string): unknown {
-    if (raw === "true") return true;
-    if (raw === "false") return false;
-    if (raw === "null") return null;
-    if (raw !== "" && !isNaN(Number(raw))) return Number(raw);
-    return raw;
-}
-
 /**
  * Serialize a JS value to its querystring representation.
+ * `null` is serialized as the literal string `"null"`.
+ * Relation values (`EntityRelation` instances or `{ __type: "relation", id, path }`
+ * objects) are serialized as their raw id — the wire format only carries the
+ * value to compare against the FK column.
  */
 function stringifyValue(value: unknown): string {
     if (value === null) return "null";
-    if (typeof value === "boolean") return String(value);
+    const relation = normalizeToEntityRelation(value);
+    if (relation) return String(relation.id);
     return String(value);
 }
 
+// ---------------------------------------------------------------------------
+// Comma escaping for list values
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape a single list item for the wire format.
+ * `\` → `\\`, `,` → `\,`
+ */
+function escapeListItem(value: string): string {
+    return value.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
+}
+
+/**
+ * Unescape a single list item from the wire format.
+ * `\\` → `\`, `\,` → `,`
+ */
+function unescapeListItem(value: string): string {
+    let result = "";
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === "\\" && i + 1 < value.length) {
+            result += value[i + 1];
+            i++; // skip next char
+        } else {
+            result += value[i];
+        }
+    }
+    return result;
+}
+
+/**
+ * Split a parenthesized list string on unescaped commas.
+ * Input is the content between `(` and `)`.
+ *
+ * @example
+ * splitListItems("admin,editor")          // ["admin", "editor"]
+ * splitListItems("hello\\, world,foo")    // ["hello, world", "foo"]
+ */
+function splitListItems(inner: string): string[] {
+    const items: string[] = [];
+    let current = "";
+    for (let i = 0; i < inner.length; i++) {
+        if (inner[i] === "\\" && i + 1 < inner.length) {
+            // Escaped character — consume both chars
+            current += inner[i] + inner[i + 1];
+            i++;
+        } else if (inner[i] === ",") {
+            items.push(unescapeListItem(current));
+            current = "";
+        } else {
+            current += inner[i];
+        }
+    }
+    items.push(unescapeListItem(current));
+    return items;
+}
+
+// ---------------------------------------------------------------------------
+// Typed operator map lookups (no `as any`)
+// ---------------------------------------------------------------------------
+
+const REST_OP_LOOKUP = REST_TO_CANONICAL as Readonly<Record<string, WhereFilterOp | undefined>>;
+const CANONICAL_OP_LOOKUP = CANONICAL_TO_REST as Readonly<Record<string, RestFilterOp | undefined>>;
+
 // ---------------------------------------------------------------------------
 // Serialize: FilterValues → REST querystring
 // ---------------------------------------------------------------------------
 
 /**
- * Serialize a single condition tuple to a PostgREST dot-string.
+ * Serialize a single canonical condition tuple to a PostgREST dot-string.
+ *
+ * Throws `TypeError` if the input is not a valid `[WhereFilterOp, unknown]` tuple.
  *
  * @example
  * serializeTuple(["==", "active"])           // "eq.active"
  * serializeTuple(["in", ["admin","editor"]]) // "in.(admin,editor)"
  * serializeTuple([">=", 18])                 // "gte.18"
  */
-function serializeTuple(tuple: [WhereFilterOp, unknown] | unknown): string {
-    // If it's already a string, it might be a PostgREST string (with dot)
-    // or a raw value (without dot). In both cases, existing tests expect
-    // them to be passed through or treated as simple equality if no dot.
-    if (typeof tuple === "string") {
-        if (tuple.includes(".")) {
-            const dotIndex = tuple.indexOf(".");
-            const prefix = tuple.substring(0, dotIndex);
-            if ((REST_TO_CANONICAL as any)[prefix]) {
-                return tuple;
-            }
-        }
-        return tuple;
+function serializeTuple(tuple: [WhereFilterOp, unknown]): string {
+    if (!Array.isArray(tuple) || tuple.length !== 2) {
+        throw new TypeError(
+            `serializeTuple: expected a [WhereFilterOp, value] tuple, got ${JSON.stringify(tuple)}`
+        );
     }
 
-    // If it's NOT a canonical tuple [WhereFilterOp, value], treat as equality.
-    if (!Array.isArray(tuple) || tuple.length !== 2 || typeof tuple[0] !== "string" || !(CANONICAL_TO_REST as any)[tuple[0]]) {
-        return `eq.${stringifyValue(tuple)}`;
+    const [op, value] = tuple;
+
+    if (typeof op !== "string") {
+        throw new TypeError(
+            `serializeTuple: operator must be a string, got ${typeof op}`
+        );
     }
 
-    const [op, value] = tuple as [WhereFilterOp, unknown];
-    const restOp = CANONICAL_TO_REST[op];
+    const restOp = CANONICAL_OP_LOOKUP[op];
+    if (!restOp) {
+        throw new TypeError(
+            `serializeTuple: unknown operator "${op}". Valid operators: ${Object.keys(CANONICAL_TO_REST).join(", ")}`
+        );
+    }
 
     if (Array.isArray(value)) {
-        const items = value.map(stringifyValue).join(",");
+        const items = value.map(v => escapeListItem(stringifyValue(v))).join(",");
         return `${restOp}.(${items})`;
     }
 
@@ -91,8 +154,11 @@ function serializeTuple(tuple: [WhereFilterOp, unknown] | unknown): string {
 }
 
 /**
- * Convert `FilterValues` to a PostgREST-style querystring record.
+ * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
+ * querystring record.
  *
+ * - Canonical `[WhereFilterOp, value]` tuples are serialized strictly.
+ * - Pre-serialized PostgREST strings (e.g. `"eq.published"`) are passed through.
  * - Single conditions produce a string value.
  * - Multiple conditions on the same field produce a string array (repeated params).
  *
@@ -102,22 +168,34 @@ function serializeTuple(tuple: [WhereFilterOp, unknown] | unknown): string {
  *
  * serializeFilter({ age: [[">=", 18], ["<", 65]] })
  * // → { age: ["gte.18", "lt.65"] }
+ *
+ * // Pre-serialized strings pass through unchanged:
+ * serializeFilter({ status: "eq.published" })
+ * // → { status: "eq.published" }
  */
 export function serializeFilter(
-    filter: FilterValues<string> | Record<string, any>
+    filter: FilterValues<string> | Record<string, unknown>
 ): Record<string, string | string[]> {
     const result: Record<string, string | string[]> = {};
 
     for (const [field, condition] of Object.entries(filter)) {
         if (condition === undefined) continue;
 
+        // Pre-serialized PostgREST string — pass through unchanged.
+        // This supports WireFilterValues where values may already be
+        // serialized dot-strings like "eq.active" or raw strings like "true".
+        if (typeof condition === "string") {
+            result[field] = condition;
+            continue;
+        }
+
         // Multiple conditions on the same field: array of tuples
         // We detect this by checking if the first element is also an array.
         if (Array.isArray(condition) && condition.length > 0 && Array.isArray(condition[0])) {
-            result[field] = (condition as any[]).map(serializeTuple);
+            result[field] = (condition as [WhereFilterOp, unknown][]).map(serializeTuple);
         } else {
-            // Single condition (could be a tuple, a raw value, or an already-serialized string)
-            result[field] = serializeTuple(condition);
+            // Single condition — must be a [WhereFilterOp, value] tuple
+            result[field] = serializeTuple(condition as [WhereFilterOp, unknown]);
         }
     }
 
@@ -131,34 +209,47 @@ export function serializeFilter(
 /**
  * Parse a single PostgREST dot-string into a `[WhereFilterOp, unknown]` tuple.
  *
- * If the string doesn't match a known operator prefix, falls back to
+ * All values are returned as strings — the wire format carries no type
+ * metadata, so coercion is the data driver's responsibility.
+ *
+ * If the string doesn't match a known operator prefix, it falls back to
  * `["==", originalString]` (treating the whole string as an equality value).
+ * This intentional defense handles values like `"user@host.com"` or
+ * `"1.2.3"` that happen to contain dots.
  */
 function deserializeSingle(raw: string): [WhereFilterOp, unknown] {
     const dotIndex = raw.indexOf(".");
     if (dotIndex === -1) {
-        // No dot → equality on the raw value (coerced)
-        return ["==", coerceValue(raw)];
+        // No dot → equality on the raw value (kept as string)
+        return ["==", raw];
     }
 
     const prefix = raw.substring(0, dotIndex);
     const rest = raw.substring(dotIndex + 1);
 
-    // Check if the prefix is a known REST operator
-    const canonicalOp = (REST_TO_CANONICAL as Record<string, WhereFilterOp | undefined>)[prefix];
+    // Check if the prefix is a known REST operator.
+    // This is the key defense against values like "eq.something" or "gt.foo"
+    // being misinterpreted — only known REST short-codes are treated as operators.
+    const canonicalOp = REST_OP_LOOKUP[prefix];
     if (!canonicalOp) {
         // Not a known operator (e.g., email "user@host.com" or version "1.2.3")
         // Treat the entire string as an equality value
         return ["==", raw];
     }
 
+    // Null-testing operators ignore their serialized value — normalize to null
+    // so the tuple round-trips stably (`isnull.null` → ["is-null", null]).
+    if (NULL_OPS.has(canonicalOp)) {
+        return [canonicalOp, null];
+    }
+
     // Parse list values: "(admin,editor)" → ["admin", "editor"]
     if (rest.startsWith("(") && rest.endsWith(")")) {
-        const items = rest.slice(1, -1).split(",").map(s => coerceValue(s.trim()));
+        const items = splitListItems(rest.slice(1, -1));
         return [canonicalOp, items];
     }
 
-    return [canonicalOp, coerceValue(rest)];
+    return [canonicalOp, rest];
 }
 
 /**
@@ -172,10 +263,10 @@ function deserializeSingle(raw: string): [WhereFilterOp, unknown] {
  * // → { status: ["==", "active"] }
  *
  * deserializeFilter({ age: ["gte.18", "lt.65"] })
- * // → { age: [[">=", 18], ["<", 65]] }
+ * // → { age: [[">=", "18"], ["<", "65"]] }
  */
 export function deserializeFilter(
-    query: Record<string, any>
+    query: Record<string, unknown>
 ): FilterValues<string> {
     const result: FilterValues<string> = {};
 
@@ -244,9 +335,9 @@ export function serializeLogicalCondition(
     }
 
     // FilterCondition
-    const restOp = (CANONICAL_TO_REST as any)[cond.operator] || "eq";
+    const restOp = CANONICAL_OP_LOOKUP[cond.operator] ?? "eq";
     if (Array.isArray(cond.value)) {
-        const items = cond.value.map(stringifyValue).join(",");
+        const items = cond.value.map(v => escapeListItem(stringifyValue(v))).join(",");
         return `${cond.column}.${restOp}.(${items})`;
     }
     return `${cond.column}.${restOp}.${stringifyValue(cond.value)}`;
@@ -300,19 +391,19 @@ export function deserializeLogicalCondition(
 
     const secondDot = rest.indexOf(".");
     if (secondDot === -1) {
-        // "column.value" — treat as equality
-        return { column, operator: "==", value: coerceValue(rest) };
+        // "column.value" — treat as equality (value kept as string)
+        return { column, operator: "==", value: rest };
     }
 
     const opStr = rest.substring(0, secondDot);
-    let valueStr = rest.substring(secondDot + 1);
+    const valueStr = rest.substring(secondDot + 1);
     const operator = toCanonicalOp(opStr) ?? "==";
 
-    // Parse list values
+    // Parse list values with escape-aware splitting
     if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
-        const items = valueStr.slice(1, -1).split(",").map(s => coerceValue(s.trim()));
+        const items = splitListItems(valueStr.slice(1, -1));
         return { column, operator, value: items };
     }
 
-    return { column, operator, value: coerceValue(valueStr) };
+    return { column, operator, value: valueStr };
 }

package/src/data/query_builder.ts

@@ -1,4 +1,13 @@
-import { FindParams, Entity, FindResponse, CollectionAccessor, QueryBuilderInterface, WhereFilterOp, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+import {
+    CollectionAccessor,
+    FilterCondition,
+    FindParams,
+    FindResponse,
+    LogicalCondition,
+    QueryBuilderInterface,
+    WhereFilterOp,
+    WhereValue
+} from "@rebasepro/types";
 
 export function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition {
     return { type: "or",
@@ -67,7 +76,7 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
     orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
-        this.params.orderBy = `${column}:${direction}`;
+        this.params.orderBy = [column, direction];
         return this;
     }
 

package/src/data/resolveDataSource.ts

@@ -7,7 +7,7 @@ import {
 
 /**
  * The subset of a collection needed to resolve its data source. Accepting a
- * structural type (rather than the full `EntityCollection`) keeps this usable
+ * structural type (rather than the full `CollectionConfig`) keeps this usable
  * from anywhere — frontend router, backend registry, editor — without coupling
  * to the collection union.
  */

package/src/data/sort-dialect.ts

@@ -0,0 +1,56 @@
+import type { OrderByTuple } from "@rebasepro/types";
+
+/**
+ * Sort-order wire codec.
+ *
+ * This is the ONLY module that knows about the colon-delimited wire format
+ * (`"field:direction"`) used in HTTP query parameters.
+ * Everything else speaks {@link OrderByTuple} exclusively.
+ *
+ * Mirrors the filter architecture in `filter-dialect.ts`.
+ *
+ * @module
+ */
+
+/**
+ * Serialize an {@link OrderByTuple} to the wire format `"field:direction"`.
+ *
+ * **Runtime tolerance:** if the input is already a well-formed wire string
+ * (from an untyped JS caller), it is returned unchanged.
+ * This is undocumented tolerance, not public API — don't rely on it.
+ *
+ * @param orderBy - A canonical `[field, direction]` tuple, or at runtime
+ *   possibly a pre-serialized string (undocumented tolerance).
+ * @returns The wire-format string, or `undefined` if the input is falsy.
+ *
+ * @remarks
+ * Field names containing `:` are representable in the tuple form but
+ * **not** on the wire — this is an inherent limitation of the colon-delimited
+ * encoding and is not resolved here.
+ */
+export function serializeOrderBy(orderBy?: OrderByTuple | string): string | undefined {
+    if (!orderBy) return undefined;
+    // Runtime tolerance: pass through a pre-serialized wire string unchanged.
+    if (typeof orderBy === "string") return orderBy;
+    return `${orderBy[0]}:${orderBy[1]}`;
+}
+
+/**
+ * Deserialize a wire-format `"field:direction"` string into an {@link OrderByTuple}.
+ *
+ * Lenient parsing (matches existing server behaviour):
+ * - Bare field name (no colon): `"name"` → `["name", "asc"]`
+ * - Unknown direction: `"name:foo"` → `["name", "asc"]`
+ * - Empty / falsy input: → `undefined`
+ *
+ * @param raw - The wire-format string from an HTTP query parameter.
+ * @returns The canonical tuple, or `undefined` if the input is empty/falsy.
+ */
+export function deserializeOrderBy(raw?: string): OrderByTuple | undefined {
+    if (!raw) return undefined;
+    const idx = raw.indexOf(":");
+    if (idx === -1) return [raw, "asc"];
+    const field = raw.slice(0, idx);
+    const dir = raw.slice(idx + 1);
+    return [field, dir === "desc" ? "desc" : "asc"];
+}

package/src/index.ts

@@ -5,4 +5,5 @@ export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
 export * from "./data/filter-dialect";
+export * from "./data/sort-dialect";
 export * from "./table-classification";

package/src/util/auth-default-policies.ts

@@ -0,0 +1,152 @@
+import { CollectionConfig, SecurityRule, SecurityOperation, AuthCollectionConfig, PolicyExpression, isPostgresCollectionConfig, policy } from "@rebasepro/types";
+import { getTableName } from "./relations";
+
+/**
+ * Default RLS policies injected by the schema generator.
+ *
+ * Rebase's enforcement model is unified: authenticated (user-context) requests
+ * run under the restricted `rebase_user` role, so Postgres RLS binds *every*
+ * statement — reads and writes. A collection's `securityRules` are the whole
+ * authorization model. The server context (auth flows, migrations,
+ * `dataAsAdmin`) runs as the owner and bypasses RLS.
+ *
+ * Because RLS default-denies, every collection is **locked by default**: with
+ * no rules, only the server context and admins can touch it. The generator
+ * injects that safe baseline:
+ *
+ * **For every collection**
+ *  1. A permissive **server-or-admin SELECT** grant.
+ *  2. A permissive **server-or-admin write** grant (insert/update/delete).
+ *
+ * Author `securityRules` are permissive and OR together, so explicit rules only
+ * *broaden* access from this locked baseline (e.g. "users read/write their own
+ * rows").
+ *
+ * **For auth collections additionally**
+ *  3. A permissive **self SELECT** grant (`id = auth.uid()`), so users can read
+ *     their own row (profile, session bootstrap) without every app re-declaring
+ *     it.
+ *  4. A **restrictive** admin write gate. Restrictive policies are AND'd with
+ *     every other policy, so a write is rejected unless the caller is an admin
+ *     (or the server context) — even if the author also wrote a permissive rule
+ *     such as "a user may edit their own row". Without this, a permissive owner
+ *     rule would let a user change their own `roles`.
+ *
+ * The server context is recognised as `auth.uid() IS NULL` (`policy.serverContext()`)
+ * — the built-in flows that run without a user (signup, migrations) set no user
+ * GUC — which also lets the owner connection satisfy these policies even under
+ * FORCE RLS. A *user* request never reaches that state: an anonymous one carries
+ * `ANONYMOUS_USER_ID`, precisely so it cannot pass for the server here.
+ *
+ * Opt out with `disableDefaultPolicies: true` to take full responsibility for
+ * the collection's RLS.
+ */
+// Expressed structurally (not as raw SQL) so the admin UI can evaluate it
+// exactly — the framework's most security-critical policies must be reflected
+// precisely, not left as un-evaluable raw clauses. Compiles to
+// `auth.uid() IS NULL OR (string_to_array(auth.roles(), ',') && ARRAY['admin'])`.
+//
+// `serverContext()`, emphatically not `not(authenticated())`: the server arm of
+// this grant must match the server context and nothing else. Anonymous visitors
+// are not signed in either, so a negated `authenticated()` would hand them the
+// server-or-admin grant on every collection's default policy.
+const SERVER_OR_ADMIN_EXPR: PolicyExpression = policy.or(
+    policy.serverContext(),
+    policy.rolesOverlap(["admin"])
+);
+
+/** Write operations that must be admin-gated by default on auth collections. */
+const DEFAULT_GUARDED_OPS: SecurityOperation[] = ["insert", "update", "delete"];
+
+/** Whether a collection is flagged as an authentication collection. */
+function isAuthCollection(collection: CollectionConfig): boolean {
+    const auth = collection.auth;
+    return auth === true || (typeof auth === "object" && (auth as AuthCollectionConfig)?.enabled === true);
+}
+
+/** The property marked as the row id (falls back to `id`). */
+function getIdPropertyName(collection: CollectionConfig): string {
+    for (const [name, prop] of Object.entries(collection.properties ?? {})) {
+        if (prop && typeof prop === "object" && "isId" in prop && (prop as { isId?: unknown }).isId) {
+            return name;
+        }
+    }
+    return "id";
+}
+
+/**
+ * Returns the security rules that should be applied to a collection: the
+ * author's explicit `securityRules` plus the framework defaults described in
+ * the module doc (baseline server/admin read for all collections; self-read
+ * and the admin write gate for auth collections).
+ *
+ * Collections that opt out via `disableDefaultPolicies` are returned unchanged.
+ */
+export function getEffectiveSecurityRules(collection: CollectionConfig): SecurityRule[] {
+    const explicit = [...((isPostgresCollectionConfig(collection) ? collection.securityRules : undefined) ?? [])];
+
+    if (collection.disableDefaultPolicies) {
+        return explicit;
+    }
+
+    const tableName = getTableName(collection);
+    const injected: SecurityRule[] = [];
+
+    // Baseline read + write: the server context and admins can always operate.
+    // RLS default-denies under the user role, so without these a rule-less
+    // collection would be locked to everyone — including the admin studio.
+    // Author rules are permissive and broaden access from here.
+    injected.push({
+        name: `${tableName}_default_admin_read`,
+        operations: ["select"],
+        condition: SERVER_OR_ADMIN_EXPR
+    });
+    injected.push({
+        name: `${tableName}_default_admin_write`,
+        operations: [...DEFAULT_GUARDED_OPS],
+        condition: SERVER_OR_ADMIN_EXPR,
+        check: SERVER_OR_ADMIN_EXPR
+    });
+
+    if (isAuthCollection(collection)) {
+        // Self-read: a user can always read their own row.
+        injected.push({
+            name: `${tableName}_default_self_read`,
+            operations: ["select"],
+            condition: policy.compare(policy.field(getIdPropertyName(collection)), "eq", policy.authUid())
+        });
+
+        // Restrictive gate: AND'd with all other policies, so no permissive rule
+        // (e.g. an owner "edit your own row" rule) can let a non-admin change
+        // privileged columns like `roles`.
+        injected.push({
+            name: `${tableName}_require_admin_write`,
+            mode: "restrictive",
+            operations: [...DEFAULT_GUARDED_OPS],
+            condition: SERVER_OR_ADMIN_EXPR,
+            check: SERVER_OR_ADMIN_EXPR
+        });
+    }
+
+    return [...explicit, ...injected];
+}
+
+/**
+ * The framework defaults that {@link getEffectiveSecurityRules} would add to a
+ * collection, without the author's own rules.
+ *
+ * These policies appear in the database under names the author never wrote, and
+ * a permissive policy ORs with every other permissive policy — so someone
+ * reading their `securityRules` and then the real ACL sees more access than they
+ * declared. Dropping them by hand does nothing either: `db push` is declarative,
+ * so the next push asserts them again. Callers use this to say, in the generated
+ * DDL, which policies are injected and how to take them off.
+ */
+export function getInjectedSecurityRules(collection: CollectionConfig): SecurityRule[] {
+    if (collection.disableDefaultPolicies) return [];
+
+    const explicitCount = ((isPostgresCollectionConfig(collection) ? collection.securityRules : undefined) ?? []).length;
+    // getEffectiveSecurityRules appends the defaults after the author's rules,
+    // so everything past the author's count is injected.
+    return getEffectiveSecurityRules(collection).slice(explicitCount);
+}