@everystack/model 0.4.15 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "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

@@ -138,6 +138,80 @@ export function isPublicReadAbility(ability: Ability): boolean {
     && (!ability.condition.role || ability.condition.role === 'anon');
 }
 
+/**
+ * Does this ability hand out DELETE?
+ *
+ * `manage` is "all actions" and compiles to the admin-bypass ALL policy, so it carries DELETE
+ * even though nothing spells it. Counting only the literal `delete` verb would leave the
+ * soft-delete hazard one grant over — which is exactly the shape `@everystack/auth`'s own
+ * user model has: `deletedAt`, no public read, no `can('delete')`, and an admin `manage` that
+ * can still destroy the row.
+ */
+export function isDeleteAbility(ability: Ability): boolean {
+  return ability.action === 'delete' || ability.action === 'manage';
+}
+
+/**
+ * Does a `privileges` map hand out DELETE?
+ *
+ * The second spelling of a reachable DELETE, and the one that slipped the first version of
+ * this rule. `can()` decides a grant AND a policy together; `privileges` is the key for a
+ * grant that has no policy — which is exactly what `db:pull` renders when it finds a live
+ * DELETE grant no policy covers. On a `rls: false` table that grant is unrestricted, so the
+ * table can be destroyed row by row without a single `can('delete')` in the model.
+ *
+ * Takes the map rather than a descriptor because both callers already hold one in the same
+ * shape (a model's `privileges`, and `db:pull`'s `DerivedAbilities.privileges`), so unlike the
+ * ability axis this one needs no second representation and cannot drift at all.
+ */
+export function privilegesGrantDelete(privileges: Record<string, readonly string[]> | undefined): boolean {
+  return Object.values(privileges ?? {}).some((privs) => privs.includes('DELETE'));
+}
+
+/** The three facts the soft-delete rule turns on. See {@link needsSoftDeleteDeclaration}. */
+export interface SoftDeleteFacts {
+  /** A `deletedAt` / `deleted_at` field is present. */
+  hasDeletedAtField: boolean;
+  /** Some ability is a PUBLIC read — see {@link isPublicReadAbility}. */
+  hasPublicRead: boolean;
+  /**
+   * A DELETE can reach this table — via an ability ({@link isDeleteAbility}) or via a
+   * `privileges` grant ({@link privilegesGrantDelete}). The SPELLING of the grant was never
+   * load-bearing; what matters is that rows can be destroyed.
+   */
+  grantsDelete: boolean;
+}
+
+/**
+ * THE rule deciding when `softDelete` must be declared rather than defaulted.
+ *
+ * `softDelete` changes observable behaviour on TWO axes, and the refusal has to cover both:
+ *
+ *  - **visibility** — on a model with a public read, `true` AND-s `deleted_at IS NULL` into the
+ *    anon policy. What a caller with no session can see.
+ *  - **durability** — on ANY model that can be deleted from, `true` makes the handler mark
+ *    `deleted_at` instead of removing the row. What a DELETE destroys.
+ *
+ * The guard originally asked only the visibility question, so a model with an owner-scoped
+ * read and a `delete` ability sailed past it and silently defaulted to `false`. That is how
+ * `uploads` and `image_variants` began hard-deleting rows, orphaning their S3 objects forever
+ * — on those models `softDelete: true` adds no policy predicate at all, so visibility was
+ * never the axis that mattered.
+ *
+ * Deliberately NOT "any model with a `deletedAt` field": where nothing reads publicly and
+ * nothing deletes, the flag provably changes neither SQL nor handler behaviour, and refusing
+ * there would be ceremony charged to every brownfield pull for no hazard.
+ *
+ * Stated over FACTS, not over a descriptor, because it has two callers holding two
+ * representations: `defineModel` has structured {@link Ability} objects, and `db:pull`'s
+ * renderer only ever holds rendered source text. Both extract the same three facts and share
+ * this one boolean, so the two surfaces cannot drift on the rule itself — the failure that
+ * already bit this guard once, when the refusal and the renderer disagreed about `role: 'anon'`.
+ */
+export function needsSoftDeleteDeclaration(facts: SoftDeleteFacts): boolean {
+  return facts.hasDeletedAtField && (facts.hasPublicRead || facts.grantsDelete);
+}
+
 /** Declare one authorization rule. */
 export function can(action: Action, condition: AbilityCondition = {}): Ability {
   return { action, condition };

package/src/index.ts

@@ -20,7 +20,8 @@ export type { TableConstraint } from './constraints';
 export { sql } from './raw-sql';
 export type { RawSql } from './raw-sql';
 
-export { can, isColumnAbility, isPublicReadAbility } from './can';
+export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete } from './can';
+export type { SoftDeleteFacts } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
 export { belongsTo, hasMany } from './relations';

package/src/model.ts

@@ -13,7 +13,7 @@
 
 import type { FieldBuilder } from './field';
 import type { Ability } from './can';
-import { isPublicReadAbility } from './can';
+import { isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
 import type { RawSql } from './raw-sql';
@@ -125,9 +125,27 @@ export interface ModelDefinition {
    */
   privileges?: Record<string, TablePrivilege[]>;
   /**
-   * `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.**
+   * What a soft delete MEANS on this table. It drives two different machines, and both
+   * consequences are real — a model declaring it should expect all of this:
+   *
+   *  - **The generic data API** (`deriveHandlerConfig` → `createHandler`): `DELETE` becomes
+   *    `UPDATE SET deleted_at = now()` instead of removing the row; and soft-deleted rows are
+   *    then filtered out of GET (for EVERY role, unless `?deleted=include|only`), out of
+   *    embedded relation reads, and out of UPDATE. This half applies to every model, whatever
+   *    its audience.
+   *  - **RLS**: `deleted_at IS NULL` is AND-ed into the PUBLIC read policies. This half applies
+   *    only where there is a public read — on an owner-scoped or admin-only model the compiled
+   *    contract is byte-identical either way (pinned in cli's `public-read-pin.test.ts`).
+   *
+   * **Required — not inferred — on any model with a `deletedAt` field that either has a public
+   * read OR grants DELETE** (`can('delete')`, or `can('manage')`, which is "all actions"). See
+   * {@link needsSoftDeleteDeclaration}, the one rule this and `db:pull` share.
+   *
+   * The guard used to ask only about the public read, which is the visibility axis. That let a
+   * model with an owner-scoped read and a `delete` ability default to `false` and begin
+   * destroying rows — with an S3 purge job keyed on `deleted_at IS NOT NULL`, that orphaned
+   * every file it should have cleaned up. On those models the flag adds no policy at all, so
+   * visibility was never the axis that mattered.
    *
    * 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,
@@ -345,9 +363,12 @@ 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.
+  // so there is no default: on the exact set of models where the answer changes behaviour, it
+  // must be declared. `softDelete: true` is what the inference used to do.
+  //
+  // That set is NOT "has a public read". It is the union of two axes — see
+  // `needsSoftDeleteDeclaration`, which is the whole rule and is shared with db:pull so the two
+  // surfaces cannot drift on it.
   // `isPublicReadAbility`, not a local copy: this refusal and db:pull's renderer were asking
   // the same question — "can a caller with no session see these rows?" — and answering it
   // differently. The renderer already counted `role: 'anon'`; this refusal did not, so a table
@@ -356,15 +377,31 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   // spelled. Explicit `softDelete: false` remains the one-line answer, and pull writes that
   // line into every model it renders, so a pulled checkout keeps loading.
   const hasPublicRead = (def.abilities ?? []).some(isPublicReadAbility);
+  // Either spelling of a reachable DELETE. `privileges` matters most on an `rls: false` table,
+  // where the grant is unrestricted and no policy stands between it and every row.
+  const grantsDelete = (def.abilities ?? []).some(isDeleteAbility) || privilegesGrantDelete(def.privileges);
   // Both spellings of the field key. The guard used to test `'deletedAt' in def.fields`
   // literally, so a model keying the column `deleted_at` — the shape a snake_case brownfield
   // schema pulls as — carried a soft-delete column past a guard that never looked at it.
   const softDeleteField = 'deletedAt' in def.fields || 'deleted_at' in def.fields;
-  if (softDeleteField && hasPublicRead && def.softDelete === undefined) {
+  if (needsSoftDeleteDeclaration({ hasDeletedAtField: softDeleteField, hasPublicRead, grantsDelete }) && def.softDelete === undefined) {
+    // DURABILITY FIRST. The old message called this "a visibility decision", which is false
+    // for exactly the models that broke: with no public read, `softDelete: true` adds no
+    // policy predicate at all. Naming the wrong consequence teaches the wrong fix, so each
+    // axis is stated only when it actually fired.
+    const why = grantsDelete
+      ? `grants DELETE (via can('delete'), can('manage') — which is "all actions" — or a privileges DELETE grant), `
+        + `so it must declare softDelete. `
+        + `This is a durability decision: softDelete: true makes a DELETE mark deleted_at instead of destroying the row; `
+        + `softDelete: false makes DELETE permanent.`
+      : `has a public read, so it must declare softDelete.`;
+    const visibility = hasPublicRead
+      ? ` It is also a visibility decision: 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.`
+      : '';
     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.`,
+      `model '${table}': has a 'deletedAt' field and ${why}${visibility} `
+        + `What a DELETE destroys is declared, not guessed — add softDelete: true or softDelete: false.`,
     );
   }