@rebasepro/common 0.9.0 → 0.9.1-canary.0fce67c

package/src/data/filter-dialect.ts

@@ -26,6 +26,7 @@ import {
     FilterCondition,
     NULL_OPS
 } from "@rebasepro/types";
+import { normalizeToEntityRelation } from "../util/entities";
 
 // ---------------------------------------------------------------------------
 // Value stringification
@@ -34,9 +35,14 @@ import {
 /**
  * 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";
+    const relation = normalizeToEntityRelation(value);
+    if (relation) return String(relation.id);
     return String(value);
 }
 

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);
+}

package/src/util/identity.ts

@@ -0,0 +1,166 @@
+/**
+ * Row identity: the address of a row, and how to derive it.
+ *
+ * Postgres has no `id`. A row is identified by its primary key — one or more
+ * columns, with any names and any types. `id` is something we synthesize on top
+ * of that: a single string token, because the admin needs *one* value it can put
+ * in a URL (`/products/1:::2`), use as a cache key, and hang a relation ref off.
+ *
+ * That token is an address, not data. It is derived from the row's columns and
+ * never stored in them — a row is exactly its columns, with their real types.
+ * Writing the address back into the row is what used to rename primary keys
+ * (`sku` → `id`) and restringify them (`42` → `"42"`) on the way out.
+ *
+ * These live in `common` because both sides need them and must agree exactly:
+ * the driver parses an incoming address back into key columns, and the admin
+ * derives the address from a row it was served.
+ */
+
+/**
+ * A primary-key column: its name, the type it round-trips as, and whether it is
+ * a UUID (which is a string despite sometimes being described as an id "number").
+ */
+export interface PrimaryKeyInfo {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}
+
+/** Separator between the parts of a composite address. */
+export const COMPOSITE_ID_SEPARATOR = ":::";
+
+/**
+ * Derive a row's address from its key columns.
+ *
+ * Single key → the value as a string. Composite → each part joined by
+ * {@link COMPOSITE_ID_SEPARATOR}, in primary-key order, which is what
+ * {@link parseIdValues} expects to invert.
+ */
+export function buildCompositeId(values: Record<string, unknown>, primaryKeys: PrimaryKeyInfo[]): string {
+    if (primaryKeys.length === 0) {
+        return "";
+    }
+    if (primaryKeys.length === 1) {
+        return String(values[primaryKeys[0].fieldName] ?? "");
+    }
+    return primaryKeys.map(pk => String(values[pk.fieldName] ?? "")).join(COMPOSITE_ID_SEPARATOR);
+}
+
+/**
+ * Invert {@link buildCompositeId}: turn an address back into key columns, each
+ * coerced to the type its column actually round-trips as.
+ *
+ * This is the boundary where a URL segment becomes a query parameter, so a
+ * malformed address must throw rather than silently produce a query that
+ * matches the wrong row (or none).
+ */
+export function parseIdValues(idValue: string | number, primaryKeys: PrimaryKeyInfo[]): Record<string, string | number> {
+    const result: Record<string, string | number> = {};
+
+    if (primaryKeys.length === 0) {
+        return result;
+    }
+
+    if (primaryKeys.length === 1) {
+        const pk = primaryKeys[0];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = typeof idValue === "number" ? idValue : parseInt(String(idValue), 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID: ${idValue}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = String(idValue);
+        }
+        return result;
+    }
+
+    // Composite key
+    const parts = String(idValue).split(COMPOSITE_ID_SEPARATOR);
+    if (parts.length !== primaryKeys.length) {
+        throw new Error(`Composite ID parts mismatch. Expected ${primaryKeys.length}, got ${parts.length} for ID: ${idValue}`);
+    }
+
+    for (let i = 0; i < primaryKeys.length; i++) {
+        const pk = primaryKeys[i];
+        const val = parts[i];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = parseInt(val, 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID component: ${val}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = val;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * The primary keys of a collection, as declared by its properties.
+ *
+ * This is the only tier both sides can read, because it is the only one written
+ * in the config: the postgres driver can also infer keys from the Drizzle
+ * schema, which the browser never sees and is never sent — the admin compiles
+ * the collection files into its own bundle rather than being served them. A key
+ * that lives only in the Drizzle schema is therefore invisible here, and the
+ * server says so at boot (`warnOnKeysTheAdminCannotResolve`) naming the `isId`
+ * to add.
+ *
+ * Returns an empty array when a collection declares none, which callers must
+ * treat as "not addressable" rather than defaulting to `id`: guessing a key
+ * that is not the real one produces confidently wrong addresses.
+ */
+export function getDeclaredPrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[] {
+    const properties = collection.properties;
+    if (!properties) return [];
+
+    const keys: PrimaryKeyInfo[] = [];
+    for (const [fieldName, propRaw] of Object.entries(properties)) {
+        const prop = propRaw as { type?: string; isId?: unknown } | undefined;
+        if (!prop || typeof prop !== "object") continue;
+        if (!("isId" in prop) || !prop.isId) continue;
+        keys.push({
+            fieldName,
+            type: prop.type === "number" ? "number" : "string",
+            isUUID: prop.isId === "uuid"
+        });
+    }
+    return keys;
+}
+
+/**
+ * The keys to address a collection's rows with, resolved the way the driver
+ * resolves them — minus the tier the browser cannot reach.
+ *
+ * The postgres driver tries, in order: properties marked `isId`; the primary
+ * keys of the Drizzle schema; and finally a column literally named `id`. Only
+ * the first and last are visible in a `CollectionConfig`, which is what both
+ * sides share.
+ *
+ * So the two agree except on a collection that declares no `isId` and whose key
+ * is known only to Drizzle. There, the driver reads the real key, and this
+ * either resolves nothing (reported to the console by the caller) or — if the
+ * table happens to have an unrelated `id` property — resolves `id`, which is
+ * the wrong key and cannot be detected from here: the addresses look right and
+ * route wrong. Only the config can settle it, so the server names both cases
+ * at boot (`warnOnKeysTheAdminCannotResolve`) with the `isId` to add.
+ */
+export function resolvePrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[] {
+    const declared = getDeclaredPrimaryKeys(collection);
+    if (declared.length > 0) return declared;
+
+    const idProp = collection.properties?.id as { type?: string } | undefined;
+    if (idProp && typeof idProp === "object") {
+        return [{ fieldName: "id",
+type: idProp.type === "number" ? "number" : "string" }];
+    }
+
+    return [];
+}

package/src/util/index.ts

@@ -1,6 +1,7 @@
 export * from "./collections";
 export * from "./common";
 export * from "./entities";
+export * from "./identity";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
@@ -13,6 +14,8 @@ export * from "./builders";
 export * from "./storage";
 export * from "./callbacks";
 export * from "./relations";
+export * from "./auth-default-policies";
+export * from "./junction-policies";
 export * from "./conditions";
 export * from "./navigation_utils";
 export * from "./filter-operator-resolution";