@everystack/model 0.4.8 → 0.4.10

package/README.md

@@ -96,7 +96,19 @@ The table-level surface, composed in `constraints: [...]`, for what a column-sco
 - `{ where: 'deleted_at IS NULL' }` — a column/scalar predicate, compiled to the policy's `USING` clause.
 - `{ sql: … }` — a verbatim RLS predicate escape hatch.
 
-These compile to RLS policies and grants (via `@everystack/cli`'s `compileTableContract`, what `db:generate` emits). `can('manage', …)` covers all actions.
+These compile to RLS policies and grants (via `@everystack/cli`'s `compileTableContract`, what `db:generate` emits). `can('manage', …)` covers all four DML actions: `SELECT`, `INSERT`, `UPDATE`, `DELETE`.
+
+Exactly those four, and no more. A verb that expanded to "every privilege" would hand out `TRUNCATE`, which no `DELETE` policy filters. The other table privileges are named one at a time:
+
+```typescript
+defineModel('posts', {
+  fields: { … },
+  abilities: [can('read'), can('manage', { role: 'admin' })],
+  privileges: { admin: ['REFERENCES', 'TRIGGER', 'TRUNCATE'] },
+});
+```
+
+`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.
 
 ## Relations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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/index.ts

@@ -22,8 +22,8 @@ export type { Ability, AbilityCondition, Action } from './can';
 export { belongsTo, hasMany } from './relations';
 export type { Relation } from './relations';
 
-export { defineModel, defineMaterializedTable } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, MaterializedTableMarker, MaterializedTableDefinition } from './model';
+export { defineModel, defineMaterializedTable, EXTRA_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, ExtraPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';

package/src/model.ts

@@ -50,6 +50,23 @@ export interface ModelHooks {
  */
 export type WrittenBy = 'app' | 'worker' | 'functions';
 
+/**
+ * A table privilege that is NOT one of the four CRUD verbs — the ones `can()` has no word for.
+ *
+ * `can('manage')` means exactly INSERT/SELECT/UPDATE/DELETE, and that is deliberate: a verb
+ * that quietly expanded to "every privilege" would hand out TRUNCATE, which is not a DELETE
+ * and is not filtered by a DELETE policy. So these three are named one at a time, by the
+ * author, in {@link ModelDefinition.privileges}.
+ *
+ * Why the vocabulary stops here: a real database routinely grants its admin role REFERENCES,
+ * TRIGGER and TRUNCATE, and everystack had no way to SAY that — so the first plan against an
+ * existing schema revoked all three on every table. That is our spelling, not their bug.
+ */
+export type ExtraPrivilege = 'REFERENCES' | 'TRIGGER' | 'TRUNCATE';
+
+/** The declarable privilege set — the one definition; the CLI's classifier reads it too. */
+export const EXTRA_PRIVILEGES: readonly ExtraPrivilege[] = ['REFERENCES', 'TRIGGER', 'TRUNCATE'];
+
 export interface ModelDefinition {
   fields: Record<string, FieldBuilder>;
   abilities?: Ability[];
@@ -59,6 +76,21 @@ export interface ModelDefinition {
   constraints?: TableConstraint[];
   /** The write principal — drives RLS posture. Default `'app'`. See {@link WrittenBy}. */
   writtenBy?: WrittenBy;
+  /**
+   * Privileges a role holds on this table BEYOND the CRUD an ability compiles to —
+   * `privileges: { admin: ['REFERENCES', 'TRIGGER', 'TRUNCATE'] }`.
+   *
+   * Only {@link ExtraPrivilege} values are accepted. The four DML privileges are NOT
+   * declarable here on purpose: `SELECT`/`INSERT`/`UPDATE`/`DELETE` come from `can()`, which
+   * decides the grant and the RLS policy together. A grant declared without its policy is a
+   * privilege with no row gate — the exact shape `db:pull` refuses to render.
+   *
+   * ADDITIVE, never subtractive: these are unioned with what the abilities grant, so this key
+   * can widen a role's privileges and can never narrow them. Naming a role here GOVERNS it —
+   * same rule as `can(…, { role })` — so a role that appears only in this map has its other
+   * privileges reconciled everywhere, not just on this table.
+   */
+  privileges?: Record<string, ExtraPrivilege[]>;
   /**
    * `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
@@ -132,6 +164,8 @@ export interface ModelDescriptor {
   constraints: TableConstraint[];
   /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
   writtenBy: WrittenBy;
+  /** Beyond-CRUD privileges per role, unioned with what the abilities grant. See {@link ModelDefinition.privileges}. */
+  privileges: Record<string, ExtraPrivilege[]>;
   /** `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. */
@@ -207,6 +241,26 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     );
   }
 
+  // A privilege outside the beyond-CRUD set is refused rather than passed through. The DML
+  // four are the dangerous ones: declared here they would compile to a GRANT with no policy
+  // beside it, which is a privilege nobody row-gated. They come from can(), where the grant
+  // and the policy are decided in one place.
+  for (const [role, privs] of Object.entries(def.privileges ?? {})) {
+    if (!Array.isArray(privs)) {
+      throw new Error(`model '${table}': privileges['${role}'] must be an array of ${EXTRA_PRIVILEGES.join(' | ')}.`);
+    }
+    for (const p of privs) {
+      if (EXTRA_PRIVILEGES.includes(p)) continue;
+      const dml = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'].includes(String(p).toUpperCase());
+      throw new Error(
+        `model '${table}': privileges['${role}'] contains '${p}', which is not one of ${EXTRA_PRIVILEGES.join(', ')}. `
+          + (dml
+            ? `Declare ${String(p).toUpperCase()} with can() — that is what decides the row policy beside the grant. A grant declared here would have no policy.`
+            : `This key names only the table privileges can() has no verb for.`),
+      );
+    }
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -230,6 +284,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     primaryKey,
     constraints: def.constraints ?? [],
     writtenBy: def.writtenBy ?? 'app',
+    privileges: def.privileges ?? {},
     softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
@@ -266,6 +321,8 @@ export interface MaterializedTableDefinition {
   writtenBy?: WrittenBy;
   private?: boolean;
   renamedFrom?: string;
+  /** Beyond-CRUD privileges per role. See {@link ModelDefinition.privileges}. */
+  privileges?: Record<string, ExtraPrivilege[]>;
 }
 
 export function defineMaterializedTable(table: string, def: MaterializedTableDefinition): ModelDescriptor {
@@ -282,6 +339,7 @@ export function defineMaterializedTable(table: string, def: MaterializedTableDef
     constraints: def.constraints,
     writtenBy: def.writtenBy ?? 'worker',
     private: def.private,
+    ...(def.privileges ? { privileges: def.privileges } : {}),
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
   });
   model.materialized = {