@everystack/model 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/can.ts

@@ -28,6 +28,26 @@ export interface AbilityCondition {
   via?: string;
   /** Field in the JWT claims holding the owner id. Default: `sub`. */
   userField?: string;
+  /**
+   * The SQL expression that yields the signed-in user's id — the RIGHT side of the owner
+   * comparison. Default: the JWT claim read inline,
+   * `((current_setting('request.jwt.claims'::text, true))::jsonb ->> '<userField>'::text)`,
+   * cast to the owner column's type.
+   *
+   * Declare it when the database already has its own accessor — `auth.user_id()` is the
+   * common brownfield shape — so the compiled policy is the one that is already live
+   * rather than a semantically-similar rewrite of it. That matters more than it sounds:
+   * predicates are diffed as TEXT, so an equivalent-but-different expression is a
+   * DROP + CREATE on every owner policy in the schema, which is exactly the churn a
+   * first plan against an existing database must not produce.
+   *
+   * Deliberately per-ability, beside `userField`, and with no project-wide default: a
+   * single setting that silently repoints every owner policy in a schema is a worse
+   * security surface than saying it where it applies. When declared, the expression is
+   * emitted VERBATIM — no cast is added, because the accessor already returns the
+   * column's type (`auth.user_id() RETURNS integer` against an integer owner).
+   */
+  ownerExpr?: unknown;
   /**
    * Column-scoped exposure for a `read` ability. Names the field keys a role may read
    * (compiled to a `GRANT SELECT (cols)` column grant, not a table grant) instead of the

package/src/derive.ts

@@ -83,8 +83,9 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       };
     }
 
-    // Convention: a `deletedAt` field opts the table into soft-delete.
-    if (SOFT_DELETE_COLUMN in model.fields) softDeleteTables.push(table);
+    // Declared, not inferred — one `softDelete` decision drives both the API filter and the
+    // RLS guard, so the two can never disagree about what a soft-deleted row is.
+    if (model.softDelete) softDeleteTables.push(table);
 
     if (model.hooks) hooks[table] = model.hooks;
 

package/src/model.ts

@@ -59,6 +59,20 @@ export interface ModelDefinition {
   constraints?: TableConstraint[];
   /** The write principal — drives RLS posture. Default `'app'`. See {@link WrittenBy}. */
   writtenBy?: WrittenBy;
+  /**
+   * `true` excludes soft-deleted rows (`deleted_at IS NULL`) from the public read policies
+   * and from the generic data API. **Required — not inferred — on any model that has a
+   * `deletedAt` field and a public read.**
+   *
+   * It used to be inferred from the field's mere presence. A column named `deleted_at` is
+   * not a statement of visibility intent: it is carried for audit, for app-layer filtering,
+   * for half-finished migrations. Inferring the predicate made the compiler author a
+   * security rule nobody wrote — and because `db:pull` renders `deletedAt` straight from the
+   * live column, a brownfield model acquired it automatically and the FIRST plan narrowed a
+   * policy the adopter had written. `createHandler`'s own `softDelete: { column, tables }`
+   * was always explicit; this matches it. Convention may propose it, never enforce it.
+   */
+  softDelete?: boolean;
   /**
    * The Postgres schema the table lives in. Default `'public'`. Package-owned
    * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
@@ -118,6 +132,8 @@ export interface ModelDescriptor {
   constraints: TableConstraint[];
   /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
   writtenBy: WrittenBy;
+  /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
+  softDelete: boolean;
   /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
@@ -174,6 +190,23 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     }
   }
 
+  // The soft-delete guard used to be inferred from the field's presence, which meant a model
+  // could gain — or, once the inference was removed, silently LOSE — a predicate that decides
+  // what anonymous users can see, with nothing in any diff to review. Neither default is safe,
+  // so there is no default: on the exact set of models where the answer changes behaviour (a
+  // `deletedAt` field plus a public read), it must be declared. `softDelete: true` is what the
+  // inference used to do.
+  const hasPublicRead = (def.abilities ?? []).some(
+    (a) => a.action === 'read' && !a.condition.role && !a.condition.owner && !a.condition.via,
+  );
+  if ('deletedAt' in def.fields && hasPublicRead && def.softDelete === undefined) {
+    throw new Error(
+      `model '${table}': has a 'deletedAt' field and a public read, so it must declare softDelete. `
+        + `softDelete: true excludes soft-deleted rows from the public read policies (what the compiler used to infer from the field's presence); `
+        + `softDelete: false leaves them readable. This is a visibility decision, so it is declared, not guessed.`,
+    );
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -197,6 +230,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     primaryKey,
     constraints: def.constraints ?? [],
     writtenBy: def.writtenBy ?? 'app',
+    softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),