@lunora/server 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/packem_shared/{mask-eCUYOwhd.mjs → mask-BepaW7YN.mjs}

@@ -1,5 +1,5 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
-import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
+import { LunoraError } from './LunoraError-WbxmrpxR.mjs';
+import { bindTableFacade, bindOrm } from './bindOrm-CaY7Wq9Z.mjs';
 
 const permissionName = (permission) => typeof permission === "string" ? permission : permission.name;
 const indexRolePermissions = (roles) => {
@@ -46,6 +46,29 @@ const maskRow = (row, columns, base) => {
 const maskPage = (page, columns, base) => {
   return { ...page, page: page.page.map((row) => maskRow(row, columns, base)) };
 };
+const assertIndexFieldsAllowed = (builderCallback, columns, tableName, method) => {
+  if (typeof builderCallback !== "function") {
+    return;
+  }
+  const referenced = /* @__PURE__ */ new Set();
+  const makeRecorder = () => /* @__PURE__ */ new Proxy(
+    {},
+    {
+      get: () => (field) => {
+        if (typeof field === "string") {
+          referenced.add(field);
+        }
+        return makeRecorder();
+      }
+    }
+  );
+  builderCallback(makeRecorder());
+  for (const field of referenced) {
+    if (field in columns) {
+      throw new LunoraError("MASK_UNSUPPORTED", `${method}() filtering "${tableName}" by masked column "${field}" is not supported`);
+    }
+  }
+};
 const isFacadeEntry = (value) => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return false;
@@ -54,21 +77,27 @@ const isFacadeEntry = (value) => {
   return typeof candidate["findMany"] === "function" && typeof candidate["withSearchIndex"] === "function";
 };
 const wrapDatabase = (base, perTable, context) => {
-  const wrapReader = (reader, columns) => {
+  const wrapReader = (reader, columns, tableName) => {
     return {
       collect: async () => {
         const rows = await reader.collect();
         return rows.map((row) => maskRow(row, columns, context));
       },
+      // SECURITY (value oracle): the predicate must see the MASKED row, not
+      // the raw stored row — otherwise a caller can `.filter(d => d.ssn ===
+      // guess)` to read the value the mask hides. Masking before the
+      // predicate keeps filtering on non-masked columns working while
+      // redacting masked cells the predicate can observe.
       filter: (predicate) => wrapReader(
-        reader.filter((document) => predicate(document)),
-        columns
+        reader.filter((document) => predicate(maskRow(document, columns, context))),
+        columns,
+        tableName
       ),
       first: async () => {
         const row = await reader.first();
         return row ? maskRow(row, columns, context) : null;
       },
-      order: (direction) => wrapReader(reader.order(direction), columns),
+      order: (direction) => wrapReader(reader.order(direction), columns, tableName),
       paginate: async (options) => maskPage(await reader.paginate(options), columns, context),
       take: async (limit) => {
         const rows = await reader.take(limit);
@@ -78,8 +107,22 @@ const wrapDatabase = (base, perTable, context) => {
         const row = await reader.unique();
         return row ? maskRow(row, columns, context) : null;
       },
-      withIndex: (indexName, range) => wrapReader(reader.withIndex(indexName, range), columns),
-      withSearchIndex: (indexName, search) => wrapReader(reader.withSearchIndex(indexName, search), columns)
+      // SECURITY (value oracle): reject before delegating when the range /
+      // search references a masked column — an index range or search term
+      // over a masked column is the same value oracle as a masked-column
+      // `where`, so it must fail closed (see `assertIndexFieldsAllowed`).
+      // Reads over NON-masked columns pass through and still mask output.
+      withIndex: (indexName, range) => {
+        assertIndexFieldsAllowed(range, columns, tableName, "withIndex");
+        return wrapReader(reader.withIndex(indexName, range), columns, tableName);
+      },
+      withSearchIndex: (indexName, search) => {
+        assertIndexFieldsAllowed(search, columns, tableName, "withSearchIndex");
+        return wrapReader(reader.withSearchIndex(indexName, search), columns, tableName);
+      },
+      // A geo query's builder (`.near`/`.within`) exposes no column name, so
+      // there's no masked-column value oracle to guard — just mask the output.
+      withGeoIndex: (indexName, build) => wrapReader(reader.withGeoIndex(indexName, build), columns, tableName)
     };
   };
   const locate = async (id, expectedTable) => {
@@ -120,23 +163,102 @@ const wrapDatabase = (base, perTable, context) => {
       throw new LunoraError("MASK_UNSUPPORTED", `${method}() over masked column "${offending}" on "${tableName}" is not supported`);
     }
   };
+  const collectWhereFields = (where, into) => {
+    if (!where || typeof where !== "object" || Array.isArray(where)) {
+      return;
+    }
+    for (const [key, value] of Object.entries(where)) {
+      if (key === "AND" || key === "OR") {
+        if (Array.isArray(value)) {
+          for (const clause of value) {
+            collectWhereFields(clause, into);
+          }
+        }
+      } else if (key === "NOT") {
+        collectWhereFields(value, into);
+      } else if (!key.startsWith("__")) {
+        into.add(key);
+      }
+    }
+  };
+  const assertWhereAllowed = (tableName, where, method) => {
+    const columns = perTable.get(tableName);
+    if (!columns || where === void 0) {
+      return;
+    }
+    const referenced = /* @__PURE__ */ new Set();
+    collectWhereFields(where, referenced);
+    for (const field of referenced) {
+      if (field in columns) {
+        throw new LunoraError("MASK_UNSUPPORTED", `${method}() filtering "${tableName}" by masked column "${field}" is not supported`);
+      }
+    }
+  };
+  const assertOrderByAllowed = (tableName, orderBy, method) => {
+    const columns = perTable.get(tableName);
+    if (!columns || !Array.isArray(orderBy)) {
+      return;
+    }
+    for (const entry of orderBy) {
+      if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+        for (const field of Object.keys(entry)) {
+          if (field in columns) {
+            throw new LunoraError("MASK_UNSUPPORTED", `${method}() ordering "${tableName}" by masked column "${field}" is not supported`);
+          }
+        }
+      }
+    }
+  };
   const wrapped = {
     ...base,
+    async deleteWhere(tableName, where, options) {
+      assertWhereAllowed(tableName, where, "deleteMany({ where })");
+      if (base.deleteWhere === void 0) {
+        throw new LunoraError("INTERNAL", `ctx.db.${tableName}.deleteMany({ where }) is unavailable: this writer has no where-based delete`);
+      }
+      return base.deleteWhere(tableName, where, options);
+    },
+    async patchWhere(tableName, args, options) {
+      assertWhereAllowed(tableName, args.where, "patchMany({ where })");
+      if (base.patchWhere === void 0) {
+        throw new LunoraError("INTERNAL", `ctx.db.${tableName}.patchMany({ where }) is unavailable: this writer has no where-based patch`);
+      }
+      return base.patchWhere(tableName, args, options);
+    },
     aggregate(tableName, options) {
       assertReductionAllowed(tableName, [options.field], "aggregate");
+      assertWhereAllowed(tableName, options.where, "aggregate");
       return base.aggregate(tableName, options);
     },
+    count(tableName, whereOrArgs) {
+      const wrapper = whereOrArgs && typeof whereOrArgs === "object" && !Array.isArray(whereOrArgs) ? whereOrArgs : void 0;
+      const where = wrapper && ("where" in wrapper || "baseWhere" in wrapper || "restrictsCounts" in wrapper) ? wrapper.where : whereOrArgs;
+      assertWhereAllowed(tableName, where, "count");
+      if (wrapper) {
+        assertWhereAllowed(tableName, wrapper.baseWhere, "count");
+      }
+      return base.count(tableName, whereOrArgs);
+    },
     async findFirst(tableName, args) {
+      assertWhereAllowed(tableName, args?.where, "findFirst");
+      assertWhereAllowed(tableName, args?.baseWhere, "findFirst");
+      assertOrderByAllowed(tableName, args?.orderBy, "findFirst");
       const row = await base.findFirst(tableName, args);
       const columns = perTable.get(tableName);
       return row && columns ? maskRow(row, columns, context) : row;
     },
     async findFirstOrThrow(tableName, args) {
+      assertWhereAllowed(tableName, args?.where, "findFirstOrThrow");
+      assertWhereAllowed(tableName, args?.baseWhere, "findFirstOrThrow");
+      assertOrderByAllowed(tableName, args?.orderBy, "findFirstOrThrow");
       const row = await base.findFirstOrThrow(tableName, args);
       const columns = perTable.get(tableName);
       return columns ? maskRow(row, columns, context) : row;
     },
     async findMany(tableName, args) {
+      assertWhereAllowed(tableName, args?.where, "findMany");
+      assertWhereAllowed(tableName, args?.baseWhere, "findMany");
+      assertOrderByAllowed(tableName, args?.orderBy, "findMany");
       const page = await base.findMany(tableName, args);
       const columns = perTable.get(tableName);
       return columns ? maskPage(page, columns, context) : page;
@@ -151,12 +273,13 @@ const wrapDatabase = (base, perTable, context) => {
     },
     groupBy(tableName, options) {
       assertReductionAllowed(tableName, [...options.by, options.agg?.field], "groupBy");
+      assertWhereAllowed(tableName, options.where, "groupBy");
       return base.groupBy(tableName, options);
     },
     query(tableName) {
       const reader = base.query(tableName);
       const columns = perTable.get(tableName);
-      return columns ? wrapReader(reader, columns) : reader;
+      return columns ? wrapReader(reader, columns, tableName) : reader;
     },
     async rankPage(tableName, indexName, options) {
       const page = await base.rankPage(tableName, indexName, options);

package/dist/packem_shared/policy-tag-DvpVH2tv.mjs

@@ -0,0 +1,13 @@
+const RLS_TAG = /* @__PURE__ */ Symbol.for("lunora.rls.middleware-policies");
+const tagRlsMiddleware = (middleware, tag) => {
+  Object.defineProperty(middleware, RLS_TAG, { configurable: true, enumerable: false, value: tag });
+  return middleware;
+};
+const readRlsTag = (middleware) => {
+  if (middleware === null || typeof middleware !== "function" && typeof middleware !== "object") {
+    return void 0;
+  }
+  return middleware[RLS_TAG];
+};
+
+export { readRlsTag as r, tagRlsMiddleware as t };

package/dist/packem_shared/{protectPublic-BjFkQ_Or.mjs → protectPublic-BlcGpiRc.mjs}

@@ -1,4 +1,4 @@
-import { r as runMiddlewareChain } from './run-middleware-CYQOuoV6.mjs';
+import { r as runMiddlewareChain } from './run-middleware-I6EiQfxL.mjs';
 
 const protectPublic = (options) => {
   const chain = [options.rateLimit, options.captcha, ...options.use ?? []].filter(

package/dist/packem_shared/{rls-Bi9HiyDC.mjs → rls-BaDQf7MG.mjs}

@@ -1,5 +1,6 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
-import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
+import { LunoraError } from './LunoraError-WbxmrpxR.mjs';
+import { bindTableFacade, bindOrm } from './bindOrm-CaY7Wq9Z.mjs';
+import { t as tagRlsMiddleware } from './policy-tag-DvpVH2tv.mjs';
 
 const DEFAULT_BATCH_LIMIT = 500;
 const assertBatchLimit = (count, limit, op) => {
@@ -244,7 +245,6 @@ const isFacadeEntry = (value) => {
   return typeof candidate["findMany"] === "function" && typeof candidate["withSearchIndex"] === "function";
 };
 const wrapDatabase = (base, raw, perTable, context) => {
-  const route = (tableName) => perTable.has(tableName) ? raw : base;
   const readBaseCache = /* @__PURE__ */ new Map();
   const readBase = (tableName) => {
     const cached = readBaseCache.get(tableName);
@@ -262,6 +262,7 @@ const wrapDatabase = (base, raw, perTable, context) => {
     readBaseCache.set(tableName, result);
     return result;
   };
+  const route = (tableName) => readBase(tableName).restricts ? raw : base;
   const relationReadFilter = (table) => readBase(table).baseWhere;
   const locateRow = async (id, expectedTable) => {
     if (raw.lookupById) {
@@ -299,7 +300,7 @@ const wrapDatabase = (base, raw, perTable, context) => {
       const nextRow = computeNextRow ? computeNextRow(located.row) : void 0;
       const writeOk = evaluateWrite(policies, op, { ...context, row: located.row }, nextRow);
       if (!writeOk) {
-        throw new LunoraError("FORBIDDEN", `${op} on "${located.tableName}" denied by policy`);
+        throw new LunoraError("FORBIDDEN", `${op} denied by policy`);
       }
     }
     return perform(raw);
@@ -332,6 +333,16 @@ const wrapDatabase = (base, raw, perTable, context) => {
       }
       return { deleted: ids.length };
     },
+    async deleteWhere(tableName, where, options) {
+      const { baseWhere } = readBase(tableName);
+      const resolved = await route(tableName).findMany(tableName, {
+        baseWhere: mergeBaseWhere(where, baseWhere),
+        relationBaseWhere: relationReadFilter
+      });
+      const ids = resolved.page.map((row) => String(row["_id"]));
+      assertBatchLimit(ids.length, options?.limit, "deleteWhere");
+      return wrapped.deleteMany(ids, options);
+    },
     async findFirst(tableName, args) {
       const { baseWhere } = readBase(tableName);
       return route(tableName).findFirst(tableName, {
@@ -365,7 +376,10 @@ const wrapDatabase = (base, raw, perTable, context) => {
         return base.get(id, expectedTable);
       }
       const { baseWhere, restricts } = readBase(located.tableName);
-      if (!restricts || !baseWhere) {
+      if (!restricts) {
+        return base.get(id, expectedTable);
+      }
+      if (!baseWhere) {
         return located.row;
       }
       const allowed = await raw.findFirst(located.tableName, { baseWhere, limit: 1, where: { _id: id } });
@@ -432,6 +446,19 @@ const wrapDatabase = (base, raw, perTable, context) => {
           expectedTable
         );
       }
+      return { patched: patches.length };
+    },
+    async patchWhere(tableName, args, options) {
+      const { baseWhere } = readBase(tableName);
+      const resolved = await route(tableName).findMany(tableName, {
+        baseWhere: mergeBaseWhere(args.where, baseWhere),
+        relationBaseWhere: relationReadFilter
+      });
+      const patches = resolved.page.map((row) => {
+        return { id: String(row["_id"]), patch: args.patch };
+      });
+      assertBatchLimit(patches.length, options?.limit, "patchWhere");
+      return wrapped.patchMany(patches, options);
     },
     query(tableName) {
       const { baseWhere } = readBase(tableName);
@@ -532,7 +559,7 @@ const indexRolePermissions = (roles) => {
 const rls = (policies, options = {}) => {
   const perTable = indexByTable(policies);
   const rolePermissions = indexRolePermissions(options.roles);
-  return async ({ ctx, next }) => {
+  const middleware = async ({ ctx, next }) => {
     const auth = ctx.auth ?? {};
     const identity = await auth.getIdentity?.() ?? null;
     const roles = auth.roles ?? [];
@@ -562,6 +589,7 @@ const rls = (policies, options = {}) => {
     }
     return next({ ctx: extension });
   };
+  return tagRlsMiddleware(middleware, { policies, roles: options.roles ?? [] });
 };
 
 export { computeReadBaseWhere, evaluateWrite, indexRolePermissions, matchesWhere, permissionName, rls };

package/dist/packem_shared/{run-middleware-CYQOuoV6.mjs → run-middleware-I6EiQfxL.mjs}

@@ -1,8 +1,10 @@
+import { LunoraError as LunoraError$1 } from '@lunora/errors';
+
 const runMiddlewareChain = async (middlewares, baseContext, terminal) => {
   let lastIndex = -1;
   const dispatch = async (index, context) => {
     if (index <= lastIndex) {
-      throw new Error("middleware next() called multiple times");
+      throw new LunoraError$1("INTERNAL", "middleware next() called multiple times");
     }
     lastIndex = index;
     const middleware = middlewares[index];

package/dist/packem_shared/{storageRules-4a30FSpI.mjs → storageRules-6QxzDOcx.mjs}

@@ -1,4 +1,4 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-WbxmrpxR.mjs';
 
 const permissionName = (permission) => typeof permission === "string" ? permission : permission.name;
 const indexRolePermissions = (roles = []) => {

package/dist/packem_shared/types.d-C4CMJK8x.d.mts

@@ -0,0 +1,141 @@
+import { WhereOf } from "../data-model.mjs";
+/** Structural mirror of `@lunora/do`'s `WhereInput`. */
+interface WhereInput {
+  [field: string]: unknown;
+  AND?: WhereInput[];
+  NOT?: WhereInput;
+  OR?: WhereInput[];
+}
+/** Operations a policy can gate. `read` covers `get`/`findMany`/`query`/`count`. */
+type PolicyOperation = "delete" | "insert" | "read" | "update";
+/**
+ * A policy's `when` decision:
+ *
+ * - `WhereInput`: a row-shape predicate. On reads it is AND-merged into every
+ * query against the table — the row is invisible unless it matches. On writes
+ * it is evaluated against the candidate document (`insert`) or the pre-write
+ * row (`update`/`delete`); a mismatch denies the write with
+ * `LunoraError("FORBIDDEN")`. Same operator set as the SQL compiler
+ * (`eq`/`ne`/`in`/`notIn`/`lt`/`lte`/`gt`/`gte`/`isNull`/`contains` +
+ * `AND`/`OR`/`NOT`).
+ * - `true`: unrestricted. On reads no predicate is merged; on writes the row is
+ * allowed.
+ * - `false`: deny. On reads the table is forced to match zero rows (a sentinel
+ * predicate); on writes the operation throws `LunoraError("FORBIDDEN")`.
+ *
+ * Returning `undefined` opts this specific policy out (rare; useful when
+ * branching on `ctx.auth.roles`).
+ */
+type PolicyDecision = WhereInput | boolean | undefined;
+/**
+ * Relation-aware twin of {@link PolicyDecision}, parameterized over the
+ * generated `DataModel` (`DM`) + `Relations` (`REL`) maps and a table `T`. A
+ * read policy may now return a Prisma-style relation predicate (the
+ * `@lunora/do` pre-resolver resolves it via a semijoin), so the typed
+ * authoring surface accepts `WhereOf<DM, REL, T>` — column predicates **and**
+ * `is`/`isNot`/`some`/`none`/`every` over `T`'s declared relations — in
+ * addition to the `boolean`/`undefined` decisions. Used by the project-bound
+ * `definePolicy` from `createPolicyDsl`.
+ */
+type PolicyDecisionOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = WhereOf<DM, REL, T> | boolean | undefined;
+/**
+ * Relation-aware input for a project-bound `definePolicy` (see
+ * `createPolicyDsl`). `table` is constrained to a real table name and
+ * `when`'s return type is the table-specific {@link PolicyDecisionOf} — so an
+ * unknown table, a stray column, or a relation predicate naming a relation the
+ * table does not declare is a compile error rather than a silent runtime deny.
+ */
+interface TypedDefinePolicyInput<DM, REL extends Record<keyof DM, object>, T extends keyof DM, Context = unknown, Identity = Record<string, unknown>> {
+  on: PolicyOperation;
+  table: T;
+  when: (context: PolicyContext<Context, Identity>) => PolicyDecisionOf<DM, REL, T>;
+}
+/**
+ * Context handed to a policy. `auth.roles` is the per-request role list,
+ * sourced from the identity resolver (better-auth claims today). `auth.can`
+ * answers whether any of those roles grants a permission (see
+ * {@link Permission} / {@link RlsOptions}). `row` is present only on write
+ * policies (`insert`/`update`/`delete`) — for `update` and `delete` it is the
+ * pre-write row; for `insert` it is the candidate document. `ctx` is the full
+ * procedure context the middleware closed over.
+ */
+interface PolicyContext<Context = unknown, Identity = Record<string, unknown>> {
+  readonly auth: {
+    /**
+     * `true` when any of the request's `roles` grants `permission` (passed
+     * by {@link Permission} object or its `name`). Always `false` when no
+     * roles were handed to the middleware (`rls(policies, { roles })`), or
+     * when none of the request's roles lists the permission.
+     */
+    readonly can: (permission: Permission | string) => boolean;
+    /**
+     * The resolved identity, typed to the `Identity` type parameter bound on
+     * `createPolicyDsl` — e.g. the app's `defineIdentity(...)` claim type via
+     * the `InferIdentity` helper; otherwise the untyped claim bag.
+     * `undefined`/`null` when the request is anonymous.
+     */
+    readonly identity?: Identity | null;
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
+  };
+  readonly ctx: Context;
+  readonly row?: Record<string, unknown>;
+}
+/** A registered policy as stored in the policy table. */
+interface Policy<Context = unknown> {
+  readonly on: PolicyOperation;
+  readonly table: string;
+  readonly when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+ * Input accepted by `definePolicy`. The branded result is the same
+ * shape; we keep the input/output split so callers can read JSDoc on the
+ * constructor without the type re-exposing `Policy` internals.
+ */
+interface DefinePolicyInput<Context = unknown> {
+  on: PolicyOperation;
+  /** Logical table name the policy applies to. */
+  table: string;
+  /**
+   * Decision function. Returning a `WhereInput` (read only) AND-merges the
+   * predicate; `true` allows; `false` denies; `undefined` skips this policy.
+   *
+   * NOTE: `count()` is **unsupported** on a policy-restricted table — the
+   * reader throws `LunoraError("COUNT_RLS_UNSUPPORTED")` (422). This mirrors
+   * kitcn's documented behavior.
+   */
+  when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+ * A named, abstract capability a policy can check with `ctx.auth.can(...)`,
+ * instead of branching on raw role strings. Declare one with
+ * `definePermission`; grant it to a role via {@link Role.permissions};
+ * register the roles with the middleware via {@link RlsOptions.roles}.
+ */
+interface Permission {
+  readonly description?: string;
+  readonly name: string;
+}
+/**
+ * A role declaration. Roles are string labels attached to the request's
+ * identity (via better-auth claims today). `permissions` lists the
+ * capabilities the role grants — at request time the middleware unions the
+ * permissions of every role in `ctx.auth.roles` so a policy can ask
+ * `ctx.auth.can(permission)` rather than enumerate roles.
+ */
+interface Role {
+  readonly description?: string;
+  readonly name: string;
+  /** Permissions this role grants — by {@link Permission} object or bare name. */
+  readonly permissions?: ReadonlyArray<Permission | string>;
+}
+/**
+ * Options for the `rls(policies, options)` middleware. `roles` registers the
+ * role→permission grants that back `ctx.auth.can(...)`; a role not listed here
+ * grants no permissions (so `can` is conservative — it fails closed for
+ * unknown roles).
+ */
+interface RlsOptions {
+  readonly roles?: ReadonlyArray<Role>;
+}
+export { DefinePolicyInput as D, PolicyOperation as P, Role as R, TypedDefinePolicyInput as T, WhereInput as W, Policy as a, Permission as b, RlsOptions as c, PolicyContext as d, PolicyDecision as e, PolicyDecisionOf as f };

package/dist/packem_shared/types.d-DdYF8E18.d.ts

@@ -0,0 +1,141 @@
+import { WhereOf } from "../data-model.js";
+/** Structural mirror of `@lunora/do`'s `WhereInput`. */
+interface WhereInput {
+  [field: string]: unknown;
+  AND?: WhereInput[];
+  NOT?: WhereInput;
+  OR?: WhereInput[];
+}
+/** Operations a policy can gate. `read` covers `get`/`findMany`/`query`/`count`. */
+type PolicyOperation = "delete" | "insert" | "read" | "update";
+/**
+ * A policy's `when` decision:
+ *
+ * - `WhereInput`: a row-shape predicate. On reads it is AND-merged into every
+ * query against the table — the row is invisible unless it matches. On writes
+ * it is evaluated against the candidate document (`insert`) or the pre-write
+ * row (`update`/`delete`); a mismatch denies the write with
+ * `LunoraError("FORBIDDEN")`. Same operator set as the SQL compiler
+ * (`eq`/`ne`/`in`/`notIn`/`lt`/`lte`/`gt`/`gte`/`isNull`/`contains` +
+ * `AND`/`OR`/`NOT`).
+ * - `true`: unrestricted. On reads no predicate is merged; on writes the row is
+ * allowed.
+ * - `false`: deny. On reads the table is forced to match zero rows (a sentinel
+ * predicate); on writes the operation throws `LunoraError("FORBIDDEN")`.
+ *
+ * Returning `undefined` opts this specific policy out (rare; useful when
+ * branching on `ctx.auth.roles`).
+ */
+type PolicyDecision = WhereInput | boolean | undefined;
+/**
+ * Relation-aware twin of {@link PolicyDecision}, parameterized over the
+ * generated `DataModel` (`DM`) + `Relations` (`REL`) maps and a table `T`. A
+ * read policy may now return a Prisma-style relation predicate (the
+ * `@lunora/do` pre-resolver resolves it via a semijoin), so the typed
+ * authoring surface accepts `WhereOf<DM, REL, T>` — column predicates **and**
+ * `is`/`isNot`/`some`/`none`/`every` over `T`'s declared relations — in
+ * addition to the `boolean`/`undefined` decisions. Used by the project-bound
+ * `definePolicy` from `createPolicyDsl`.
+ */
+type PolicyDecisionOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = WhereOf<DM, REL, T> | boolean | undefined;
+/**
+ * Relation-aware input for a project-bound `definePolicy` (see
+ * `createPolicyDsl`). `table` is constrained to a real table name and
+ * `when`'s return type is the table-specific {@link PolicyDecisionOf} — so an
+ * unknown table, a stray column, or a relation predicate naming a relation the
+ * table does not declare is a compile error rather than a silent runtime deny.
+ */
+interface TypedDefinePolicyInput<DM, REL extends Record<keyof DM, object>, T extends keyof DM, Context = unknown, Identity = Record<string, unknown>> {
+  on: PolicyOperation;
+  table: T;
+  when: (context: PolicyContext<Context, Identity>) => PolicyDecisionOf<DM, REL, T>;
+}
+/**
+ * Context handed to a policy. `auth.roles` is the per-request role list,
+ * sourced from the identity resolver (better-auth claims today). `auth.can`
+ * answers whether any of those roles grants a permission (see
+ * {@link Permission} / {@link RlsOptions}). `row` is present only on write
+ * policies (`insert`/`update`/`delete`) — for `update` and `delete` it is the
+ * pre-write row; for `insert` it is the candidate document. `ctx` is the full
+ * procedure context the middleware closed over.
+ */
+interface PolicyContext<Context = unknown, Identity = Record<string, unknown>> {
+  readonly auth: {
+    /**
+     * `true` when any of the request's `roles` grants `permission` (passed
+     * by {@link Permission} object or its `name`). Always `false` when no
+     * roles were handed to the middleware (`rls(policies, { roles })`), or
+     * when none of the request's roles lists the permission.
+     */
+    readonly can: (permission: Permission | string) => boolean;
+    /**
+     * The resolved identity, typed to the `Identity` type parameter bound on
+     * `createPolicyDsl` — e.g. the app's `defineIdentity(...)` claim type via
+     * the `InferIdentity` helper; otherwise the untyped claim bag.
+     * `undefined`/`null` when the request is anonymous.
+     */
+    readonly identity?: Identity | null;
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
+  };
+  readonly ctx: Context;
+  readonly row?: Record<string, unknown>;
+}
+/** A registered policy as stored in the policy table. */
+interface Policy<Context = unknown> {
+  readonly on: PolicyOperation;
+  readonly table: string;
+  readonly when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+ * Input accepted by `definePolicy`. The branded result is the same
+ * shape; we keep the input/output split so callers can read JSDoc on the
+ * constructor without the type re-exposing `Policy` internals.
+ */
+interface DefinePolicyInput<Context = unknown> {
+  on: PolicyOperation;
+  /** Logical table name the policy applies to. */
+  table: string;
+  /**
+   * Decision function. Returning a `WhereInput` (read only) AND-merges the
+   * predicate; `true` allows; `false` denies; `undefined` skips this policy.
+   *
+   * NOTE: `count()` is **unsupported** on a policy-restricted table — the
+   * reader throws `LunoraError("COUNT_RLS_UNSUPPORTED")` (422). This mirrors
+   * kitcn's documented behavior.
+   */
+  when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+ * A named, abstract capability a policy can check with `ctx.auth.can(...)`,
+ * instead of branching on raw role strings. Declare one with
+ * `definePermission`; grant it to a role via {@link Role.permissions};
+ * register the roles with the middleware via {@link RlsOptions.roles}.
+ */
+interface Permission {
+  readonly description?: string;
+  readonly name: string;
+}
+/**
+ * A role declaration. Roles are string labels attached to the request's
+ * identity (via better-auth claims today). `permissions` lists the
+ * capabilities the role grants — at request time the middleware unions the
+ * permissions of every role in `ctx.auth.roles` so a policy can ask
+ * `ctx.auth.can(permission)` rather than enumerate roles.
+ */
+interface Role {
+  readonly description?: string;
+  readonly name: string;
+  /** Permissions this role grants — by {@link Permission} object or bare name. */
+  readonly permissions?: ReadonlyArray<Permission | string>;
+}
+/**
+ * Options for the `rls(policies, options)` middleware. `roles` registers the
+ * role→permission grants that back `ctx.auth.can(...)`; a role not listed here
+ * grants no permissions (so `can` is conservative — it fails closed for
+ * unknown roles).
+ */
+interface RlsOptions {
+  readonly roles?: ReadonlyArray<Role>;
+}
+export { DefinePolicyInput as D, PolicyOperation as P, Role as R, TypedDefinePolicyInput as T, WhereInput as W, Policy as a, Permission as b, RlsOptions as c, PolicyContext as d, PolicyDecision as e, PolicyDecisionOf as f };