Update permissions handling and enhance Guard functionality

- Bump `jsonv-ts` dependency to 0.8.6.
- Refactor permission checks in the `Guard` class to improve context validation and error handling.
- Update tests to reflect changes in permission handling, ensuring robust coverage for new scenarios.
- Introduce new test cases for data permissions, enhancing overall test coverage and reliability.

app/src/data/api/DataController.ts

@@ -9,6 +9,7 @@ import {
    pickKeys,
    mcpTool,
    convertNumberedObjectToArray,
+   mergeObject,
 } from "bknd/utils";
 import * as SystemPermissions from "modules/permissions";
 import type { AppDataConfig } from "../data-schema";
@@ -95,7 +96,9 @@ export class DataController extends Controller {
       // read entity schema
       hono.get(
          "/schema.json",
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          describeRoute({
             summary: "Retrieve data schema",
             tags: ["data"],
@@ -121,7 +124,9 @@ export class DataController extends Controller {
       // read schema
       hono.get(
          "/schemas/:entity/:context?",
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          describeRoute({
             summary: "Retrieve entity schema",
             tags: ["data"],
@@ -161,7 +166,9 @@ export class DataController extends Controller {
        */
       hono.get(
          "/info/:entity",
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          describeRoute({
             summary: "Retrieve entity info",
             tags: ["data"],
@@ -213,7 +220,9 @@ export class DataController extends Controller {
       // fn: count
       hono.post(
          "/:entity/fn/count",
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          describeRoute({
             summary: "Count entities",
             tags: ["data"],
@@ -236,7 +245,9 @@ export class DataController extends Controller {
       // fn: exists
       hono.post(
          "/:entity/fn/exists",
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          describeRoute({
             summary: "Check if entity exists",
             tags: ["data"],
@@ -285,16 +296,26 @@ export class DataController extends Controller {
             parameters: saveRepoQueryParams(["limit", "offset", "sort", "select", "join"]),
             tags: ["data"],
          }),
-         permission(DataPermissions.entityRead, {}),
          jsc("param", s.object({ entity: entitiesEnum })),
          jsc("query", repoQuery, { skipOpenAPI: true }),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          async (c) => {
             const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
+
+            const { merge } = this.ctx.guard.filters(DataPermissions.entityRead, c, {
+               entity,
+            });
+
             const options = c.req.valid("query") as RepoQuery;
-            const result = await this.em.repository(entity).findMany(options);
+            const result = await this.em.repository(entity).findMany({
+               ...options,
+               where: merge(options.where),
+            });
 
             return c.json(result, { status: result.data ? 200 : 404 });
          },
@@ -308,7 +329,9 @@ export class DataController extends Controller {
             parameters: saveRepoQueryParams(["offset", "sort", "select"]),
             tags: ["data"],
          }),
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_read_one", {
             inputSchema: {
                param: s.object({ entity: entitiesEnum, id: idType }),
@@ -326,11 +349,19 @@ export class DataController extends Controller {
          jsc("query", repoQuery, { skipOpenAPI: true }),
          async (c) => {
             const { entity, id } = c.req.valid("param");
-            if (!this.entityExists(entity)) {
+            if (!this.entityExists(entity) || !id) {
                return this.notFound(c);
             }
             const options = c.req.valid("query") as RepoQuery;
-            const result = await this.em.repository(entity).findId(id, options);
+            const { merge } = this.ctx.guard.filters(
+               DataPermissions.entityRead,
+               c,
+               c.req.valid("param"),
+            );
+            const id_name = this.em.entity(entity).getPrimaryField().name;
+            const result = await this.em
+               .repository(entity)
+               .findOne(merge({ [id_name]: id }), options);
 
             return c.json(result, { status: result.data ? 200 : 404 });
          },
@@ -344,7 +375,9 @@ export class DataController extends Controller {
             parameters: saveRepoQueryParams(),
             tags: ["data"],
          }),
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          jsc(
             "param",
             s.object({
@@ -361,9 +394,20 @@ export class DataController extends Controller {
             }
 
             const options = c.req.valid("query") as RepoQuery;
-            const result = await this.em
+            const { entity: newEntity } = this.em
                .repository(entity)
-               .findManyByReference(id, reference, options);
+               .getEntityByReference(reference);
+
+            const { merge } = this.ctx.guard.filters(DataPermissions.entityRead, c, {
+               entity: newEntity.name,
+               id,
+               reference,
+            });
+
+            const result = await this.em.repository(entity).findManyByReference(id, reference, {
+               ...options,
+               where: merge(options.where),
+            });
 
             return c.json(result, { status: result.data ? 200 : 404 });
          },
@@ -390,7 +434,9 @@ export class DataController extends Controller {
             },
             tags: ["data"],
          }),
-         permission(DataPermissions.entityRead, {}),
+         permission(DataPermissions.entityRead, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
          mcpTool("data_entity_read_many", {
             inputSchema: {
                param: s.object({ entity: entitiesEnum }),
@@ -405,7 +451,13 @@ export class DataController extends Controller {
                return this.notFound(c);
             }
             const options = c.req.valid("json") as RepoQuery;
-            const result = await this.em.repository(entity).findMany(options);
+            const { merge } = this.ctx.guard.filters(DataPermissions.entityRead, c, {
+               entity,
+            });
+            const result = await this.em.repository(entity).findMany({
+               ...options,
+               where: merge(options.where),
+            });
 
             return c.json(result, { status: result.data ? 200 : 404 });
          },
@@ -421,7 +473,9 @@ export class DataController extends Controller {
             summary: "Insert one or many",
             tags: ["data"],
          }),
-         permission(DataPermissions.entityCreate, {}),
+         permission(DataPermissions.entityCreate, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_insert"),
          jsc("param", s.object({ entity: entitiesEnum })),
          jsc("json", s.anyOf([s.object({}), s.array(s.object({}))])),
@@ -438,6 +492,12 @@ export class DataController extends Controller {
             // to transform all validation targets into a single object
             const body = convertNumberedObjectToArray(_body);
 
+            this.ctx.guard
+               .filters(DataPermissions.entityCreate, c, {
+                  entity,
+               })
+               .matches(body, { throwOnError: true });
+
             if (Array.isArray(body)) {
                const result = await this.em.mutator(entity).insertMany(body);
                return c.json(result, 201);
@@ -455,7 +515,9 @@ export class DataController extends Controller {
             summary: "Update many",
             tags: ["data"],
          }),
-         permission(DataPermissions.entityUpdate, {}),
+         permission(DataPermissions.entityUpdate, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_update_many", {
             inputSchema: {
                param: s.object({ entity: entitiesEnum }),
@@ -482,7 +544,10 @@ export class DataController extends Controller {
                update: EntityData;
                where: RepoQuery["where"];
             };
-            const result = await this.em.mutator(entity).updateWhere(update, where);
+            const { merge } = this.ctx.guard.filters(DataPermissions.entityUpdate, c, {
+               entity,
+            });
+            const result = await this.em.mutator(entity).updateWhere(update, merge(where));
 
             return c.json(result);
          },
@@ -495,7 +560,9 @@ export class DataController extends Controller {
             summary: "Update one",
             tags: ["data"],
          }),
-         permission(DataPermissions.entityUpdate, {}),
+         permission(DataPermissions.entityUpdate, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_update_one"),
          jsc("param", s.object({ entity: entitiesEnum, id: idType })),
          jsc("json", s.object({})),
@@ -505,6 +572,17 @@ export class DataController extends Controller {
                return this.notFound(c);
             }
             const body = (await c.req.json()) as EntityData;
+            const fns = this.ctx.guard.filters(DataPermissions.entityUpdate, c, {
+               entity,
+               id,
+            });
+
+            // if it has filters attached, fetch entry and make the check
+            if (fns.filters.length > 0) {
+               const { data } = await this.em.repository(entity).findId(id);
+               fns.matches(data, { throwOnError: true });
+            }
+
             const result = await this.em.mutator(entity).updateOne(id, body);
 
             return c.json(result);
@@ -518,7 +596,9 @@ export class DataController extends Controller {
             summary: "Delete one",
             tags: ["data"],
          }),
-         permission(DataPermissions.entityDelete, {}),
+         permission(DataPermissions.entityDelete, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_delete_one"),
          jsc("param", s.object({ entity: entitiesEnum, id: idType })),
          async (c) => {
@@ -526,6 +606,18 @@ export class DataController extends Controller {
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
+
+            const fns = this.ctx.guard.filters(DataPermissions.entityDelete, c, {
+               entity,
+               id,
+            });
+
+            // if it has filters attached, fetch entry and make the check
+            if (fns.filters.length > 0) {
+               const { data } = await this.em.repository(entity).findId(id);
+               fns.matches(data, { throwOnError: true });
+            }
+
             const result = await this.em.mutator(entity).deleteOne(id);
 
             return c.json(result);
@@ -539,7 +631,9 @@ export class DataController extends Controller {
             summary: "Delete many",
             tags: ["data"],
          }),
-         permission(DataPermissions.entityDelete, {}),
+         permission(DataPermissions.entityDelete, {
+            context: (c) => ({ ...c.req.param() }) as any,
+         }),
          mcpTool("data_entity_delete_many", {
             inputSchema: {
                param: s.object({ entity: entitiesEnum }),
@@ -554,7 +648,10 @@ export class DataController extends Controller {
                return this.notFound(c);
             }
             const where = (await c.req.json()) as RepoQuery["where"];
-            const result = await this.em.mutator(entity).deleteWhere(where);
+            const { merge } = this.ctx.guard.filters(DataPermissions.entityDelete, c, {
+               entity,
+            });
+            const result = await this.em.mutator(entity).deleteWhere(merge(where));
 
             return c.json(result);
          },

app/src/data/entities/query/Repository.ts

@@ -1,4 +1,4 @@
-import type { DB as DefaultDB, PrimaryFieldType } from "bknd";
+import type { DB as DefaultDB, EntityRelation, PrimaryFieldType } from "bknd";
 import { $console } from "bknd/utils";
 import { type EmitsEvents, EventManager } from "core/events";
 import { type SelectQueryBuilder, sql } from "kysely";
@@ -280,16 +280,11 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       id: PrimaryFieldType,
       _options?: Partial<Omit<RepoQuery, "where" | "limit" | "offset">>,
    ): Promise<RepositoryResult<TBD[TB] | undefined>> {
-      const { qb, options } = this.buildQuery(
-         {
-            ..._options,
-            where: { [this.entity.getPrimaryField().name]: id },
-            limit: 1,
-         },
-         ["offset", "sort"],
-      );
+      if (typeof id === "undefined" || id === null) {
+         throw new InvalidSearchParamsException("id is required");
+      }
 
-      return this.single(qb, options) as any;
+      return this.findOne({ [this.entity.getPrimaryField().name]: id }, _options);
    }
 
    async findOne(
@@ -315,23 +310,27 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       return res as any;
    }
 
+   getEntityByReference(reference: string): { entity: Entity; relation: EntityRelation } {
+      const listable_relations = this.em.relations.listableRelationsOf(this.entity);
+      const relation = listable_relations.find((r) => r.ref(reference).reference === reference);
+      if (!relation) {
+         throw new Error(
+            `Relation "${reference}" not found or not listable on entity "${this.entity.name}"`,
+         );
+      }
+      return {
+         entity: relation.other(this.entity).entity,
+         relation,
+      };
+   }
+
    // @todo: add unit tests, specially for many to many
    async findManyByReference(
       id: PrimaryFieldType,
       reference: string,
       _options?: Partial<Omit<RepoQuery, "limit" | "offset">>,
    ): Promise<RepositoryResult<EntityData>> {
-      const entity = this.entity;
-      const listable_relations = this.em.relations.listableRelationsOf(entity);
-      const relation = listable_relations.find((r) => r.ref(reference).reference === reference);
-
-      if (!relation) {
-         throw new Error(
-            `Relation "${reference}" not found or not listable on entity "${entity.name}"`,
-         );
-      }
-
-      const newEntity = relation.other(entity).entity;
+      const { entity: newEntity, relation } = this.getEntityByReference(reference);
       const refQueryOptions = relation.getReferenceQuery(newEntity, id as number, reference);
       if (!("where" in refQueryOptions) || Object.keys(refQueryOptions.where as any).length === 0) {
          throw new Error(

app/src/data/permissions/index.ts

@@ -1,9 +1,51 @@
 import { Permission } from "auth/authorize/Permission";
+import { s } from "bknd/utils";
 
-export const entityRead = new Permission("data.entity.read");
-export const entityCreate = new Permission("data.entity.create");
-export const entityUpdate = new Permission("data.entity.update");
-export const entityDelete = new Permission("data.entity.delete");
+export const entityRead = new Permission(
+   "data.entity.read",
+   {
+      filterable: true,
+   },
+   s.object({
+      entity: s.string(),
+      id: s.anyOf([s.number(), s.string()]).optional(),
+   }),
+);
+/**
+ * Filter filters content given
+ */
+export const entityCreate = new Permission(
+   "data.entity.create",
+   {
+      filterable: true,
+   },
+   s.object({
+      entity: s.string(),
+   }),
+);
+/**
+ * Filter filters where clause
+ */
+export const entityUpdate = new Permission(
+   "data.entity.update",
+   {
+      filterable: true,
+   },
+   s.object({
+      entity: s.string(),
+      id: s.anyOf([s.number(), s.string()]).optional(),
+   }),
+);
+export const entityDelete = new Permission(
+   "data.entity.delete",
+   {
+      filterable: true,
+   },
+   s.object({
+      entity: s.string(),
+      id: s.anyOf([s.number(), s.string()]).optional(),
+   }),
+);
 export const databaseSync = new Permission("data.database.sync");
 export const rawQuery = new Permission("data.raw.query");
 export const rawMutate = new Permission("data.raw.mutate");