@everystack/model 0.4.13 → 0.4.14

package/package.json

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

@@ -174,6 +174,23 @@ export interface ModelDefinition {
    * just not exposed. Named `private` to avoid colliding with `schema: 'public'`.
    */
   private?: boolean;
+  /**
+   * `rls: false` declares this table's row security OFF — authorization is grants-only,
+   * exactly as a brownfield database holds it (`db:pull` writes this line when the live
+   * table has RLS disabled and no ability renders). Without it the compiler declares RLS
+   * ENABLED, and the first plan after adopting such a table proposes
+   * `ENABLE ROW LEVEL SECURITY` — which, with zero policies, denies every non-owner role
+   * the table it already uses. Declaring the live truth is the fix; forcing the flag on
+   * was a silent lockdown nobody asked for.
+   *
+   * `false` is the only value: RLS-on is the default and has one spelling (omit this key).
+   * Refused with abilities (a policy under disabled RLS is a dead policy — declare
+   * `privileges` for grants-only access) and with `writtenBy: 'app'` (the app principal
+   * writes through its policies; there are none). Turning security OFF on a live table is
+   * a widening: the emitted `DISABLE ROW LEVEL SECURITY` carries the destructive-plan
+   * ceremony.
+   */
+  rls?: false;
   /**
    * Triggers on this table — declared HERE because a trigger is existentially bound
    * to its table and the table's owner must see what runs on every write (owner
@@ -205,6 +222,8 @@ export interface ModelDescriptor {
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
   private: boolean;
+  /** Row-security posture — `false` = grants-only, no RLS (see {@link ModelDefinition.rls}). Default `true`. */
+  rls: boolean;
   /** One-shot rename hint: this table used to be named `renamedFrom` (same schema). */
   renamedFrom?: string;
   /** One-shot move hint: this table used to live in schema `movedFrom` (same name) — emits SET SCHEMA. */
@@ -369,6 +388,36 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     }
   }
 
+  // `rls: false` is the ONLY spelling — RLS-on is the default and one meaning gets one
+  // spelling, so `rls: true` (redundant today, load-bearing the day the default moves) is
+  // refused rather than accepted as a synonym.
+  if (def.rls !== undefined && def.rls !== false) {
+    throw new Error(
+      `model '${table}': rls: ${JSON.stringify(def.rls)} — RLS enabled is the default; omit the key. ` +
+        `The only declaration is rls: false (grants-only authorization, row security off).`,
+    );
+  }
+  if (def.rls === false) {
+    // An ability compiles to a policy, and a policy under disabled RLS is a dead policy —
+    // it filters nothing while looking like it does. The grants-only spelling is `privileges`.
+    if ((def.abilities ?? []).length) {
+      throw new Error(
+        `model '${table}': rls: false with abilities — an ability compiles to an RLS policy, and a ` +
+          `policy under disabled row security is dead: it filters nothing while reading as though it does. ` +
+          `Either drop rls: false (policies need RLS) or declare grants-only access via privileges.`,
+      );
+    }
+    // `writtenBy: 'app'` means the app writes THROUGH its policies (RLS FORCEd). With RLS
+    // off there are no policies to write through — the combination is a contradiction.
+    if ((def.writtenBy ?? 'app') === 'app') {
+      throw new Error(
+        `model '${table}': rls: false with writtenBy: 'app' (the default) — 'app' writes through RLS ` +
+          `policies, and rls: false declares there are none. Declare writtenBy: 'worker' or 'functions' ` +
+          `(owner-connection writes), which is how a grants-only table is actually written.`,
+      );
+    }
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -396,6 +445,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
+    rls: def.rls ?? true,
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
     ...(def.movedFrom ? { movedFrom: def.movedFrom } : {}),
     triggers: def.triggers ?? [],