@everystack/model 0.4.15 → 0.4.17

package/README.md

@@ -110,6 +110,50 @@ defineModel('posts', {
 
 `privileges` takes only those three, and it is additive — it widens what a role holds and can never narrow it. DML stays in `can()`, where the grant and the row policy are decided together. `db:pull --abilities live` writes this key from the live grants, so an existing database that grants its admin role all three keeps them.
 
+## Soft delete
+
+A `deletedAt` column is a column. `softDelete` is the decision about what it MEANS, and it sits
+on the model beside `fields`:
+
+```typescript
+export const Upload = defineModel('uploads', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    accountId: field.uuid().notNull().references(() => Account),
+    s3Key: field.text().notNull(),
+    deletedAt: field.timestamptz(),
+  },
+  softDelete: true,
+  abilities: [can('read', { owner: 'accountId' }), can('delete', { owner: 'accountId' })],
+});
+```
+
+It changes two different things, and neither default is safe:
+
+- **Durability, on every model** — `true` makes a `DELETE` mark `deleted_at` instead of removing
+  the row, and hides marked rows from the data API's reads and updates. `false` makes `DELETE`
+  permanent.
+- **Visibility, only where there is a public read** — `true` AND-s `deleted_at IS NULL` into the
+  anon policy. On an owner-scoped or admin-only model the compiled SQL is identical either way,
+  so durability is the axis that matters there.
+
+**`defineModel` refuses to guess** when a model has `deletedAt` AND either a public read or a way
+to DELETE (`can('delete')`, `can('manage')`, or a `privileges` DELETE grant). Omit the line on
+such a model and it throws at import, naming which branch it tripped. Where nothing reads
+publicly and nothing deletes, the flag provably changes neither the SQL nor the handler, so
+nothing is required.
+
+Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or purge
+job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
+audit-only and a `DELETE` really should remove the row. It is not cosmetic: a table whose S3
+cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should have purged if
+the row is hard-deleted instead.
+
+A column named `deleted_at` is not a statement of intent — it is carried for audit, for
+app-layer filtering, for half-finished migrations. This used to be inferred from the field's
+presence, which made the compiler author a security rule nobody wrote. `db:pull` writes the
+flag explicitly for the same reason.
+
 ## Relations
 
 ```typescript
@@ -137,13 +181,18 @@ everystack db:pull     --stage dev   # reverse an existing database into model s
 
 ### Handler config
 
-`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
+`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership, **`softDelete.tables`**) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
 
 ```typescript
 import { deriveHandlerConfig } from '@everystack/model';
 const handler = createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
+Do not hand-write the per-table keys beside it. Each one is a view of the models, and a
+hand-kept copy drifts silently: `softDelete.tables` losing two entries is what let a table start
+hard-deleting rows whose S3 objects a purge job keyed on `deleted_at IS NOT NULL`. Handler-level
+options that are not per-table — `auth`, `pgSettings`, `rpc`, limits — stay explicit.
+
 ## Programmatic API (`@everystack/cli/model`)
 
 The same compiler the CLI uses is importable for your own CI and tests — point it at your live DB and assert the declaration and the database agree, or red-team the deployed authorization:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -12,10 +12,12 @@
   ],
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
     "./drizzle": {
+      "source": "./src/drizzle.ts",
       "types": "./src/drizzle.ts",
       "default": "./src/drizzle.ts"
     }

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/derived.ts

@@ -416,6 +416,15 @@ export interface FunctionDefinition {
    * PUBLIC-executable. Opinion lives in the linter, never in the parser.
    */
   privileges?: Record<string, string[]>;
+  /**
+   * Owner-only by design — no app role may ever EXECUTE this function.
+   *
+   * Parallel to `private` on views/matviews. An `internal` function is a helper called only
+   * by other SECURITY DEFINER functions running as the owner. The compiler still emits
+   * `REVOKE ALL … FROM PUBLIC`; `internal` tells the lint (`db:check`) the absence of callers
+   * is reviewed and permanent, not an oversight. Contradicts `abilities` and `privileges`.
+   */
+  internal?: boolean;
   comment?: string;
   body: RawSql;
 }
@@ -436,6 +445,7 @@ export interface FunctionDescriptor {
   abilities: Ability[];
   /** Recorded EXECUTE grants — see {@link FunctionDefinition.privileges}. */
   privileges: Record<string, string[]>;
+  internal: boolean;
   comment?: string;
   body: string;
 }
@@ -487,6 +497,12 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     if (seen.has(a.name)) throw new Error(`function '${name}': duplicate argument '${a.name}'.`);
     seen.add(a.name);
   }
+  if (def.internal && (def.abilities?.length ?? 0) > 0) {
+    throw new Error(`function '${name}': internal: true declares it owner-only — it cannot also declare abilities. Drop one.`);
+  }
+  if (def.internal && Object.keys(def.privileges ?? {}).length > 0) {
+    throw new Error(`function '${name}': internal: true declares it owner-only — it cannot also declare privileges. Drop one.`);
+  }
   for (const a of def.abilities ?? []) {
     if (a.action !== 'execute') {
       throw new Error(`function '${name}': can('${a.action}') is not a function ability — functions carry can('execute', { role }) only.`);
@@ -526,6 +542,7 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     dependsOn: def.dependsOn ?? [],
     abilities: def.abilities ?? [],
     privileges,
+    internal: def.internal ?? false,
     ...(def.comment ? { comment: def.comment } : {}),
     body: def.body.sql,
   };

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.`,
     );
   }