@everystack/model 0.4.25 → 0.4.26

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.26] - 2026-10-31
+
+### Added
+
+- declare request roles with defineModule({ roles: { request } })
+
+### Fixed
+
+- a granted definer role is not a request role in the lifecycle check
+
+### Documentation
+
+- say why a granted owner counts, and document roles.request
+- state what an older server skips under the role declaration
+
 ## [0.4.25] - 2026-10-30
 
 ### BREAKING CHANGES

package/README.md

@@ -294,6 +294,11 @@ An explicit field `onDelete: 'cascade'` into a lifecycle table is refused; use t
 running app hooks. `dependent: 'destroy'` has not shipped.
 AFTER DELETE audit triggers are supported; they do not run on a soft deletion.
 
+A trigger function on a lifecycle table must be owned by a role no request can become. The check counts
+every role the models grant to as a request role. If a definer role owns such a function and holds grants,
+declare the request roles: `defineModule({ roles: { request: [...] } })`. `moduleRequestRoles(modules)`
+returns their union. See [docs/lifecycle.md](../../docs/lifecycle.md#owner-definer-and-request-roles).
+
 #### Refusing some deletes: `deleteWhen`
 
 `lifecycle: { deleteWhen: sql\`<predicate>\` }` is lifecycle with a guard: a row may be deleted only when the predicate

package/package.json

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

@@ -461,6 +461,9 @@ export interface FunctionDescriptor {
  * Same rule as @everystack/server's withRole.
  */
 const OWNER_ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+/** The bare role-name rule, for every other place a module names a role (defineModule's roles.request). */
+export const BARE_ROLE_NAME = OWNER_ROLE_NAME;
+export const isBareRoleName = (role: string): boolean => OWNER_ROLE_NAME.test(role);
 
 /**
  * Refuse an owner that is not a bare lowercase role name. ONE implementation across

package/src/index.ts

@@ -36,8 +36,8 @@ export { veto, isVeto } from './lifecycle-hooks';
 export { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
 export type { ModelDescriptor, ModelDefinition, ModelHooks, LifecycleOptions, DestroyContext, DestroyHook, LifecycleContext, HookVeto, BeforeLifecycleHook, AfterLifecycleHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
-export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
-export type { Module, ModuleDefinition } from './module';
+export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles, moduleRequestRoles } from './module';
+export type { Module, ModuleDefinition, ModuleRoles } from './module';
 
 export {
   defineView, defineMaterializedView, defineFunction, defineSql, defineSequence,

package/src/module.ts

@@ -21,7 +21,7 @@
 
 import { LIFECYCLE_OWNER_ROLE, type ModelDescriptor } from './model';
 import type { DerivedDescriptor, SequenceDescriptor } from './derived';
-import { rejectHoles, functionArgSignature } from './derived';
+import { rejectHoles, functionArgSignature, isBareRoleName, BARE_ROLE_NAME } from './derived';
 import { deriveFunctionSchemas } from './derive';
 import { parseQualified } from './qualified';
 import { linkModels } from './link';
@@ -66,6 +66,20 @@ export interface ModuleDefinition {
    * baseline fails the gate. Exempt from reconciliation, never exempt from the report.
    */
   governedRoles?: string[];
+  /**
+   * What the database's roles are FOR, where the grants alone cannot tell.
+   *
+   * `request` — the roles a request can become: the roles the API sets for anon, signed-in and
+   * admin requests, and the login the application connects as. The lifecycle catalog check treats
+   * every role the models grant to as one a request can be. A least-privilege SECURITY DEFINER
+   * role that does not own the tables must still be granted DML, so without this list it counts
+   * as a request role, and every trigger function it owns on a lifecycle table is refused.
+   * Declared, a declared `owner:` that no request role can reach (and that cannot log in) no
+   * longer counts. Undeclared, the check runs as before.
+   *
+   * Refused: an empty list, `PUBLIC`, and `everystack_lifecycle`.
+   */
+  roles?: ModuleRoles;
   /**
    * Package-owned SQL emitted after the tables — SECURITY DEFINER functions, triggers, etc.
    * A thunk so it is generated lazily and can take run-specific input (the app's event-trigger
@@ -87,10 +101,39 @@ export interface Module {
   derived: DerivedDescriptor[];
   /** Roles this module's authz governs beyond the ones its models name. Widen-only. */
   governedRoles: string[];
+  /** What the roles are for — see {@link ModuleDefinition.roles}. Absent when not declared. */
+  roles?: ModuleRoles;
   /** Function-SQL thunks, normalized to an array so composing modules just concatenates. */
   functions: Array<() => string>;
 }
 
+/** {@link ModuleDefinition.roles}. On a Module, `request` is deduped and sorted. */
+export interface ModuleRoles {
+  /** The roles a request can become. */
+  request?: string[];
+}
+
+/** Validate and normalize `roles.request`: non-empty, real role names, never PUBLIC or the lifecycle role. */
+function normalizeRoles(roles: ModuleRoles): ModuleRoles {
+  if (roles.request === undefined) return {};
+  if (roles.request.length === 0) {
+    throw new Error('defineModule: roles.request is empty. Name every role a request can become (the API\'s request roles and the '
+      + 'login the application connects as), or leave roles.request out; an empty list would treat no role as a request role.');
+  }
+  for (const role of roles.request) {
+    if (role === 'PUBLIC' || role === 'public') {
+      throw new Error(`defineModule: roles.request names '${role}'. PUBLIC is every role, not one a request becomes; name the roles themselves.`);
+    }
+    if (role === LIFECYCLE_OWNER_ROLE) {
+      throw new Error(`defineModule: roles.request names '${role}'. That role is reserved for the lifecycle soft delete; a request must never become it.`);
+    }
+    if (!isBareRoleName(role)) {
+      throw new Error(`defineModule: roles.request names '${role}', which is not a bare lowercase role name (${BARE_ROLE_NAME}).`);
+    }
+  }
+  return { request: [...new Set(roles.request)].sort() };
+}
+
 /** Declare a package's database slice. Empty fields default to nothing — a models-only module is fine. */
 export function defineModule(def: ModuleDefinition): Module {
   // The loud undefined gate — a missing import composes as a hole; name it here,
@@ -124,6 +167,7 @@ export function defineModule(def: ModuleDefinition): Module {
     sequences: def.sequences ?? [],
     derived: def.derived ?? [],
     governedRoles: [...new Set(def.governedRoles ?? [])].sort(),
+    ...(def.roles ? { roles: normalizeRoles(def.roles) } : {}),
     functions: def.functions ? [def.functions] : [],
   };
 }
@@ -232,3 +276,13 @@ export function moduleGovernedRoles(modules: Module[]): string[] {
   const lifecycle = modules.some((m) => m.models.some((model) => model.lifecycle));
   return [...new Set([...modules.flatMap((m) => m.governedRoles), ...(lifecycle ? [LIFECYCLE_OWNER_ROLE] : [])])].sort();
 }
+
+/**
+ * The union of every module's request roles, sorted. Undefined when no module declares any, so a
+ * caller can tell "not declared" (the lifecycle check runs as before) from a declared list.
+ */
+export function moduleRequestRoles(modules: Module[]): string[] | undefined {
+  const declared = modules.filter((m) => m.roles?.request !== undefined);
+  if (declared.length === 0) return undefined;
+  return [...new Set(declared.flatMap((m) => m.roles!.request!))].sort();
+}

package/src/wire.ts

@@ -245,6 +245,19 @@ export interface ReconcileWirePayload extends ModelWireEnvelope {
    * declared object is lifecycle-owned = the reconcile refuses (fail closed).
    */
   applicationRoles?: string[];
+  /**
+   * The roles a request can become (`roles: { request }` on the modules), and every owner a
+   * declared derived object names. The catalog check reads them beside `applicationRoles`, so a
+   * definer role the models grant to is not mistaken for a request role.
+   *
+   * OPTIONAL, and added without a contract bump on purpose: absent (an older CLI), the server
+   * checks exactly as before. An older server ignores them and runs the check from before they
+   * existed: it refuses more, but it skips the live checks on the request roles (missing,
+   * superuser, BYPASSRLS). db:apply's CLI-side gates still run those; `db:reconcile --apply
+   * --stage` has none, so against an older server it does not. See wire-shape.test.ts.
+   */
+  requestRoles?: string[];
+  declaredOwners?: string[];
   actor?: string | null;
   gitRef?: string | null;
 }