@rebasepro/common 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/util/builders.d.ts

@@ -3,7 +3,7 @@ import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBC
  * 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`,
+ * `properties` object, which enables autocomplete on `display.title`,
  * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
  *
  * @example
@@ -16,7 +16,7 @@ import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBC
  *         name: { name: "Name", type: "string", validation: { required: true } },
  *         price: { name: "Price", type: "number" },
  *     },
- *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     display: { title: "name" },  // ✅ autocomplete: "name" | "price"
  *     sort: ["price", "asc"], // ✅ autocomplete on first element
  * });
  * ```

package/dist/util/collections.d.ts

@@ -1,3 +1,20 @@
 import { CollectionConfig, Properties } from "@rebasepro/types";
 export declare function sortProperties<M extends Record<string, unknown>>(properties: Properties, propertiesOrder?: string[]): Properties;
+/**
+ * A copy of `collections` ordered by slug.
+ *
+ * Every generator that turns collections into a file is order-dependent, and
+ * every one of them is compared against its own output — `rebase doctor`
+ * regenerates in memory and diffs, `generate-sdk && git diff --exit-code` gates
+ * CI. While only the *writers* sorted, a project whose `readdirSync` order
+ * differed from its slug order was reported permanently out of date, and the
+ * fix the message printed rewrote the file in the order it was already in. The
+ * generators sort themselves now, so no caller can get this wrong.
+ *
+ * A slug-less collection is left to the generator's own validation, which names
+ * the offending collection; sorting must not throw first.
+ */
+export declare function sortCollectionsBySlug<C extends {
+    slug?: string;
+}>(collections: readonly C[]): C[];
 export declare function getPrimaryKeys<M extends Record<string, unknown>>(collection: CollectionConfig<M>): Extract<keyof M, string>[];

package/dist/util/conditions.d.ts

@@ -1,13 +1,17 @@
-import { AuthState, ConditionContext, JsonLogicRule } from "@rebasepro/types";
+import { AuthState, ConditionContext, ConditionRule } from "@rebasepro/types";
 /**
  * Register custom JSON Logic operations for Rebase.
  * Call this once at app initialization.
  */
 export declare function registerConditionOperations(): void;
 /**
- * Evaluate a JSON Logic rule against the given context.
+ * Evaluate a condition against the given context.
+ *
+ * A condition may be stated as a literal instead of a rule — `hidden: true`
+ * rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+ * answer, so it is returned rather than handed to the evaluator.
  */
-export declare function evaluateCondition(rule: JsonLogicRule, context: ConditionContext): unknown;
+export declare function evaluateCondition(rule: ConditionRule, context: ConditionContext): unknown;
 /**
  * Build a ConditionContext from the current property resolution context.
  */

package/dist/util/entities.d.ts

@@ -31,9 +31,16 @@ export declare function getRelationFrom<M extends Record<string, unknown>>(entit
  * have `id` and `path` fields — these are relation-shaped objects from
  * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
  *
+ * When `targetPath` is given, also accepts a bare id. A relation column is a
+ * foreign key, and the REST layer returns it as the scalar it is; only some
+ * fetch paths hydrate it into an object. Which form a caller sees therefore
+ * depends on how the row was loaded, and a caller that only accepted objects
+ * reported half of its own data as a type error. The declared target is the
+ * missing half: with it, an id is a relation that has not been fetched yet.
+ *
  * Returns null if the value cannot be coerced.
  */
-export declare function normalizeToEntityRelation(value: unknown, propertyType?: string): EntityRelation | null;
+export declare function normalizeToEntityRelation(value: unknown, propertyType?: string, targetPath?: string): EntityRelation | null;
 export declare function traverseValuesProperties<M extends Record<string, unknown>>(inputValues: Partial<EntityValues<M>>, properties: Properties, operation: (value: unknown, property: Property) => unknown): EntityValues<M> | undefined;
 export declare function traverseValueProperty(inputValue: unknown, property: Property, operation: (value: unknown, property: Property) => unknown): unknown;
 /**

package/dist/util/index.d.ts

@@ -18,3 +18,4 @@ export * from "./junction-policies";
 export * from "./conditions";
 export * from "./pg-column-to-property";
 export * from "./string-column-length";
+export * from "./internal-tables";

package/dist/util/internal-tables.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The tables Rebase creates for its own bookkeeping, and the SQL that keeps the
+ * end-user role away from them.
+ *
+ * ## Why this exists
+ *
+ * Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role
+ * provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table
+ * in the schemas a project uses — including `rebase`, because a project's own
+ * collections are allowed to live there (the scaffold puts `users` there). It
+ * also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the
+ * migrating role inherits the same grant.
+ *
+ * Every framework-internal table is created later: auth's tables come up during
+ * `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first
+ * job registers, `idempotency_keys` on the first request that carries a key. So
+ * they all inherited full DML for the end-user role — and none of them enables
+ * row-level security, because none of them is a collection with
+ * `securityRules`. Measured on a freshly provisioned database, `SET ROLE
+ * rebase_user` could read `rebase.refresh_tokens` (session token hashes),
+ * `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and
+ * `rebase.api_keys` (including its `admin` flag), and insert into
+ * `rebase.app_config`.
+ *
+ * Nothing routes a user-context query at those tables today, so this was not
+ * reachable over the API. That is the wrong thing to depend on: the documented
+ * model is that RLS is the authorization boundary, and these tables sat outside
+ * it. The boundary is now a privilege boundary instead — the role simply cannot
+ * address them.
+ *
+ * ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY
+ *
+ * RLS with no policy denies every row, which is the same outcome, but it is the
+ * *weaker* statement: it leaves the grant in place, so a later policy — or a
+ * `FORCE` flag cleared by some future migration — reopens the table. There is no
+ * row of `refresh_tokens` any end user should ever reach, so the honest encoding
+ * is "this role has no privilege here at all". It also keeps the owner
+ * connection (which auth actually runs on) completely unaffected.
+ *
+ * ## Keeping it true
+ *
+ * `packages/rls-check` scans the `rebase` schema — it used to skip it as a
+ * "platform" schema — and its `rls-disabled` check fires on exactly the
+ * condition this module removes: RLS off *and* a DML grant to a reachable role.
+ * So a table added here without a revoke is caught by `pnpm rls:check`, not by
+ * someone re-reading this file.
+ */
+/**
+ * The Postgres role authenticated requests run as.
+ *
+ * Defined here rather than in the Postgres driver because both the driver (which
+ * provisions the role) and this module (which revokes on its behalf) need it,
+ * and a second spelling of a role name is a silent no-op waiting to happen.
+ */
+export declare const REBASE_USER_ROLE = "rebase_user";
+/**
+ * Framework-internal table names, unqualified.
+ *
+ * Deliberately NOT including `users`: the auth user table is also a collection,
+ * with `securityRules`, RLS enabled and policies applied. Users read their own
+ * row through it — revoking there would break sign-in.
+ *
+ * `atlas_schema_revisions` is Atlas's migration ledger, which lands in `rebase`
+ * because `db migrate apply` passes `--revisions-schema rebase`.
+ */
+export declare const REBASE_INTERNAL_TABLES: readonly string[];
+/**
+ * A single statement that takes every privilege on `schema.table` away from the
+ * end-user role.
+ *
+ * Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which
+ * happen in practice:
+ *
+ *  - the role does not exist when the connection is unprivileged (Rebase then
+ *    relies on native RLS rather than a role switch), and a bare `REVOKE` on a
+ *    missing role is an error, not a no-op;
+ *  - the table may not exist yet — `cron_logs` never appears in a project with
+ *    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.
+ *
+ * One command, so it is safe on handles that speak the extended query protocol
+ * and reject multi-statement strings.
+ */
+export declare function revokeInternalTableSql(schema: string, table: string): string;
+/**
+ * Revoke on every internal table in `schema`, one statement at a time.
+ *
+ * Best-effort per table: a connection that does not own one of them (a
+ * pre-provisioned database, a platform-managed ledger) cannot revoke on it, and
+ * that must not take down a boot. The caller decides how loud to be — `onError`
+ * exists so the driver can warn without this module importing a logger.
+ */
+export declare function revokeInternalTableAccess(execute: (sql: string) => Promise<unknown>, schema: string, options?: {
+    tables?: readonly string[];
+    onError?: (table: string, error: unknown) => void;
+}): Promise<void>;

package/dist/util/permissions.d.ts

@@ -21,8 +21,27 @@ export type AuthContext<USER extends User = User> = AuthState<USER>;
  *   applying policies in-process), so an undecidable rule never silently allows.
  */
 export type UnknownResolution = "allow" | "deny";
+/**
+ * Which half of a rule to evaluate.
+ *
+ * Postgres evaluates `USING` against the row as it is *now* and `WITH CHECK`
+ * against the row as it *will be*, both inside the transaction. A driver
+ * enforcing an update in-process has two different rows in hand and therefore
+ * needs to ask the two questions separately — asking one question about one row
+ * either checks the new values against the old row's ownership or the reverse.
+ *
+ * - `"both"` (default): what a single-row decision means (`USING ∧ WITH CHECK`).
+ * - `"using"`: the read/target clause only — ask it about the stored row.
+ * - `"withCheck"`: the write clause only — ask it about the row being written.
+ *
+ * Rule *selection* is unaffected: the target operation still decides which rules
+ * apply, so `"using"` on an `update` evaluates the update rules' USING clause,
+ * not the delete rules'.
+ */
+export type PolicyClauses = "both" | "using" | "withCheck";
 export interface CheckOperationOptions {
     onUnknown?: UnknownResolution;
+    clauses?: PolicyClauses;
 }
 /**
  * Decide whether an operation is permitted for a user on a (possibly null) row,
@@ -30,9 +49,20 @@ export interface CheckOperationOptions {
  * the same model compiled to Postgres RLS DDL, so the decision matches database
  * enforcement for every non-raw rule.
  *
+ * Engine-independent by design. `securityRules` are a declaration about the
+ * data, not about Postgres: the engine decides *who* enforces them (Postgres
+ * compiles them to RLS DDL, a document driver applies them in-process), never
+ * *whether* they hold. Gating this function on the engine's `supportsRLS`
+ * capability is what made every `{ onUnknown: "deny" }` call site in the Mongo
+ * driver return `true` before it evaluated anything — and it did so only for
+ * collections that spelled their engine out, so declaring `engine: "mongodb"`
+ * was what switched authorization off.
+ *
  * @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"`.
+ * @param options.clauses which half of each rule to evaluate. See
+ *   {@link PolicyClauses}; defaults to `"both"`.
  */
 export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: CollectionConfig<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: SecurityOperation, options?: CheckOperationOptions): boolean;
 export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: CollectionConfig<M>, authContext: AuthContext<USER>): boolean;

package/dist/util/policy/sqlToPolicy.d.ts

@@ -12,13 +12,13 @@ export interface AnonymousGrantRisk {
 /**
  * Find clauses that read as "signed-in users only" but admit anonymous callers.
  *
- * Both spellings come from the same place — Supabase, where `auth.uid()` really
- * is NULL for an anonymous request. Rebase substitutes
+ * Both spellings come from the same place — Supabase, where its own `auth.uid()`
+ * really is NULL for an anonymous request. Rebase substitutes
  * {@link ANONYMOUS_USER_ID} instead (a blank id would read back as NULL, which
  * is how the trusted *server* context is recognised), so:
  *
- *  - `auth.uid() IS NOT NULL` is a tautology on the user path, and
- *  - `auth.uid() != 'anon'` excludes one spelling of anonymous and admits the
+ *  - `rebase.uid() IS NOT NULL` is a tautology on the user path, and
+ *  - `rebase.uid() != 'anon'` excludes one spelling of anonymous and admits the
  *    other. This one is not hypothetical and was not only a foreign habit:
  *    rebase's own request path reported `'anon'` while everything that compiled
  *    or checked a policy used `'anonymous'`, so whichever literal an author

package/dist/util/relations.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { CollectionConfig, ResolvedRelation, RelationProperty } from "@rebasepro/types";
 /**
  * Whether the target rows are shared with other parents — a many-to-many, or a
  * multi-hop `via` chain.
@@ -27,6 +27,23 @@ export declare function isJunctionBackedRelation(relation: ResolvedRelation): bo
  * which is worth hearing about.
  */
 export declare function resolveCollectionRelations(collection: CollectionConfig): Record<string, ResolvedRelation>;
+/**
+ * The path of the collection a relation property points at, derived from the
+ * property alone.
+ *
+ * A preview holds a property and a value and no collection, so it cannot call
+ * `resolveRelationProperty`. It does not need to: both forms that carry a
+ * target — the stamped `resolvedRelation` and the inline `relation` — name it
+ * directly. Only the third form, a relation declared by name in the
+ * collection's `relations` array, is out of reach, and that one has no target
+ * to read without the collection anyway.
+ *
+ * This is what lets a preview render a relation column that arrived as a bare
+ * foreign key: the id says *which* row, the declared target says *which
+ * collection*, and `RelationPreview` fetches the rest. Without it a scalar id
+ * is indistinguishable from a value of the wrong type.
+ */
+export declare function getRelationTargetPath(property: RelationProperty): string | undefined;
 export declare function getTableName(collection: CollectionConfig): string;
 export declare function getTableVarName(tableName: string): string;
 export declare function getEnumVarName(tableName: string, propName: string): string;

package/dist/util/resolutions.d.ts

@@ -92,6 +92,37 @@ export declare function resolveEnumValues(input: EnumValues): EnumValueConfig[]
  *   3. many-relations on an engine that has relations (SQL).
  */
 export declare function getEntityChildViews<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): EntityChildView[];
+/**
+ * Each of `collection`'s tabs paired with the property that declared it, when a
+ * property declared it: child view key → property key.
+ *
+ * A many-relation can only be declared as a property — that is the documented
+ * and only mechanism — and {@link getEntityChildViews} promotes it to a tab. So
+ * one declaration reaches the panel twice, and neither surface knew about the
+ * other. The form rendered a relation picker beside the tab, and the collection
+ * table rendered *two* columns under one heading: the relation's own column,
+ * showing the child rows, and a jump-to-tab button carrying the same name.
+ *
+ * The pairing is what lets each surface decide which half is redundant, and it
+ * has to be a pairing rather than two sets because the two keys differ whenever
+ * a relation is named. The match is on the resolved `relationName` — the
+ * identity `getEntityChildViews` itself dedupes on — so a relation declared in
+ * `relations` and pointed at by a differently-named property is recognised too.
+ *
+ * A relation with no property of its own is absent here, which is the point: it
+ * has exactly one surface already, and nothing to weigh it against.
+ *
+ * Only top-level properties: a relation nested inside a `map` gets no tab.
+ */
+export declare function getChildViewDeclaringProperties<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): Map<string, string>;
+/**
+ * The property keys of `collection` whose relation is already one of its tabs.
+ *
+ * What a form asks: the tab is the treatment for a list of child rows, so the
+ * picker beside it is the redundant half. See
+ * {@link getChildViewDeclaringProperties}.
+ */
+export declare function getChildViewRelationPropertyKeys<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): Set<string>;
 /**
  * The child views of `collection` as bare collections.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g06dbe5b",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -40,8 +40,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.13.0",
-    "@rebasepro/utils": "0.13.0"
+    "@rebasepro/types": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/utils": "0.13.1-canary.g06dbe5b"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -53,6 +53,7 @@
     "@types/react-measure": "^2.0.12",
     "babel-plugin-react-compiler": "beta",
     "cross-env": "^10.1.0",
+    "fast-check": "^4.9.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12",
     "tsd": "^0.33.0",