Merge remote-tracking branch 'origin/main' into feat/data-ui-fillable-visible

- fix password strategy openapi tags
- fix cli run picking up memory if specified
- fix view transition chrome crash

README.md

@@ -8,13 +8,17 @@
 </a>
 </p>
 
-bknd simplifies app development by providing a fully functional backend for database management, authentication, media and workflows. Being lightweight and built on Web Standards, it can be deployed nearly anywhere, including running inside your framework of choice. No more deploying multiple separate services!
+bknd simplifies app development by providing a fully functional visual backend for database management, authentication, media and workflows. Being lightweight and built on Web Standards, it can be deployed nearly anywhere, including running inside your framework of choice. No more deploying multiple separate services!
+
+It's designed to avoid vendor lock-in and architectural limitations. Built exclusively on [WinterTC Minimum Common Web Platform API](https://min-common-api.proposal.wintertc.org/) for universal compatibility, all functionality (data, auth, media, flows) is modular and opt-in, and infrastructure access is adapter-based with direct access to underlying drivers giving you full control without abstractions getting in your way.
+
 * **Runtimes**: Node.js 22+, Bun 1.0+, Deno, Browser, Cloudflare Workers/Pages, Vercel, Netlify, AWS Lambda, etc.
 * **Databases**:
   * SQLite: LibSQL, Node SQLite, Bun SQLite, Cloudflare D1, Cloudflare Durable Objects SQLite, SQLocal
   * Postgres: Vanilla Postgres, Supabase, Neon, Xata
 * **Frameworks**: React, Next.js, React Router, Astro, Vite, Waku
 * **Storage**: AWS S3, S3-compatible (Tigris, R2, Minio, etc.), Cloudflare R2 (binding), Cloudinary, Filesystem
+* **Deployment**: Standalone, Docker, Cloudflare Workers, Vercel, Netlify, Deno Deploy, AWS Lambda, Valtown etc.
 
 **For documentation and examples, please visit https://docs.bknd.io.**
 
@@ -24,6 +28,18 @@ bknd simplifies app development by providing a fully functional backend for data
 > Please keep in mind that **bknd** is still under active development
 > and therefore full backward compatibility is not guaranteed before reaching v1.0.0.
 
+## Use Cases
+
+bknd is a general purpose backend system that implements the primitives almost any backend needs. This way, you can use it for any backend use case, including but not limited to:
+
+- **Content Management System (CMS)** as Wordpress alternative, hosted separately or embedded in your frontend
+- **AI Agent Backends** for managing agent state with built-in data persistence, regardless where it is hosted. Optionally communicate over the integrated MCP server.
+- **SaaS Products** with multi-tenant data isolation (RLS) and user management, with freedom to choose your own database and storage provider
+- **Prototypes & MVPs** to validate ideas quickly without infrastructure overhead
+- **API-First Applications** where you need a reliable, type-safe backend without vendor lock-in either with the integrated TypeScript SDK or REST API using OpenAPI
+- **IoT & Embedded Devices** where minimal footprint matters
+
+
 ## Size
 ![gzipped size of bknd](https://img.shields.io/bundlejs/size/bknd?label=bknd)
 ![gzipped size of bknd/client](https://img.badgesize.io/https://unpkg.com/bknd@latest/dist/ui/client/index.js?compression=gzip&label=bknd/client)
@@ -46,13 +62,13 @@ Creating digital products always requires developing both the backend (the logic
   * **Media**: Effortlessly manage and serve all your media files.
   * **Flows**: Design and run workflows with seamless automation. (UI integration coming soon!)
 * 🌐 Built on Web Standards for maximum compatibility
+* 🛠️ MCP server, client and UI built-in to control your backend
 * 🏃‍♂️ Multiple run modes
   * standalone using the CLI
   * using a JavaScript runtime (Node, Bun, workerd)
   * using a React framework (Next.js, React Router, Astro)
 * 📦 Official API and React SDK with type-safety
 * ⚛️ React elements for auto-configured authentication and media components
-* 🛠️ MCP server, client and UI built-in to control your backend
 
 ## Structure
 The package is mainly split into 4 parts, each serving a specific purpose:

app/__test__/api/Api.spec.ts

@@ -6,13 +6,16 @@ describe("Api", async () => {
    it("should construct without options", () => {
       const api = new Api();
       expect(api.baseUrl).toBe("http://localhost");
-      expect(api.isAuthVerified()).toBe(false);
+
+      // verified is true, because no token, user, headers or request given
+      // therefore nothing to check, auth state is verified
+      expect(api.isAuthVerified()).toBe(true);
    });
 
    it("should ignore force verify if no claims given", () => {
       const api = new Api({ verified: true });
       expect(api.baseUrl).toBe("http://localhost");
-      expect(api.isAuthVerified()).toBe(false);
+      expect(api.isAuthVerified()).toBe(true);
    });
 
    it("should construct from request (token)", async () => {

app/__test__/app/mcp/mcp.auth.test.ts

@@ -201,7 +201,10 @@ describe("mcp auth", async () => {
          },
          return_config: true,
       });
-      expect(addGuestRole.config.guest.permissions).toEqual(["read", "write"]);
+      expect(addGuestRole.config.guest.permissions.map((p) => p.permission)).toEqual([
+         "read",
+         "write",
+      ]);
 
       // update role
       await tool(server, "config_auth_roles_update", {
@@ -210,13 +213,15 @@ describe("mcp auth", async () => {
             permissions: ["read"],
          },
       });
-      expect(app.toJSON().auth.roles?.guest?.permissions).toEqual(["read"]);
+      expect(app.toJSON().auth.roles?.guest?.permissions?.map((p) => p.permission)).toEqual([
+         "read",
+      ]);
 
       // get role
       const getGuestRole = await tool(server, "config_auth_roles_get", {
          key: "guest",
       });
-      expect(getGuestRole.value.permissions).toEqual(["read"]);
+      expect(getGuestRole.value.permissions.map((p) => p.permission)).toEqual(["read"]);
 
       // remove role
       await tool(server, "config_auth_roles_remove", {

app/__test__/auth/Authenticator.spec.ts

@@ -1,3 +1,41 @@
+import { Authenticator } from "auth/authenticate/Authenticator";
 import { describe, expect, test } from "bun:test";
 
-describe("Authenticator", async () => {});
+describe("Authenticator", async () => {
+   test("should return auth cookie headers", async () => {
+      const auth = new Authenticator({}, null as any, {
+         jwt: {
+            secret: "secret",
+            fields: [],
+         },
+         cookie: {
+            sameSite: "strict",
+         },
+      });
+      const headers = await auth.getAuthCookieHeader("token");
+      const cookie = headers.get("Set-Cookie");
+      expect(cookie).toStartWith("auth=");
+      expect(cookie).toEndWith("HttpOnly; Secure; SameSite=Strict");
+
+      // now expect it to be removed
+      const headers2 = await auth.removeAuthCookieHeader(headers);
+      const cookie2 = headers2.get("Set-Cookie");
+      expect(cookie2).toStartWith("auth=; Max-Age=0; Path=/; Expires=");
+      expect(cookie2).toEndWith("HttpOnly; Secure; SameSite=Strict");
+   });
+
+   test("should return auth cookie string", async () => {
+      const auth = new Authenticator({}, null as any, {
+         jwt: {
+            secret: "secret",
+            fields: [],
+         },
+         cookie: {
+            sameSite: "strict",
+         },
+      });
+      const cookie = await auth.unsafeGetAuthCookie("token");
+      expect(cookie).toStartWith("auth=");
+      expect(cookie).toEndWith("HttpOnly; Secure; SameSite=Strict");
+   });
+});

app/__test__/auth/authorize/authorize.spec.ts

@@ -1,9 +1,31 @@
 import { describe, expect, test } from "bun:test";
-import { Guard } from "../../../src/auth/authorize/Guard";
+import { Guard, type GuardConfig } from "auth/authorize/Guard";
+import { Permission } from "auth/authorize/Permission";
+import { Role, type RoleSchema } from "auth/authorize/Role";
+import { objectTransform, s } from "bknd/utils";
+
+function createGuard(
+   permissionNames: string[],
+   roles?: Record<string, Omit<RoleSchema, "name">>,
+   config?: GuardConfig,
+) {
+   const _roles = roles
+      ? objectTransform(roles, ({ permissions = [], is_default, implicit_allow }, name) => {
+           return Role.create(name, { permissions, is_default, implicit_allow });
+        })
+      : {};
+   const _permissions = permissionNames.map((name) => new Permission(name));
+   return new Guard(_permissions, Object.values(_roles), config);
+}
 
 describe("authorize", () => {
+   const read = new Permission("read", {
+      filterable: true,
+   });
+   const write = new Permission("write");
+
    test("basic", async () => {
-      const guard = Guard.create(
+      const guard = createGuard(
          ["read", "write"],
          {
             admin: {
@@ -16,14 +38,14 @@ describe("authorize", () => {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
+      expect(guard.granted(read, user)).toBeUndefined();
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(write, user)).toBeUndefined();
 
-      expect(() => guard.granted("something")).toThrow();
+      expect(() => guard.granted(new Permission("something"), {})).toThrow();
    });
 
    test("with default", async () => {
-      const guard = Guard.create(
+      const guard = createGuard(
          ["read", "write"],
          {
             admin: {
@@ -37,26 +59,26 @@ describe("authorize", () => {
          { enabled: true },
       );
 
-      expect(guard.granted("read")).toBe(true);
+      expect(guard.granted(read, {})).toBeUndefined();
-      expect(guard.granted("write")).toBe(false);
+      expect(() => guard.granted(write, {})).toThrow();
 
       const user = {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
+      expect(guard.granted(read, user)).toBeUndefined();
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(write, user)).toBeUndefined();
    });
 
    test("guard implicit allow", async () => {
-      const guard = Guard.create([], {}, { enabled: false });
+      const guard = createGuard([], {}, { enabled: false });
 
-      expect(guard.granted("read")).toBe(true);
+      expect(guard.granted(read, {})).toBeUndefined();
-      expect(guard.granted("write")).toBe(true);
+      expect(guard.granted(write, {})).toBeUndefined();
    });
 
    test("role implicit allow", async () => {
-      const guard = Guard.create(["read", "write"], {
+      const guard = createGuard(["read", "write"], {
          admin: {
             implicit_allow: true,
          },
@@ -66,12 +88,12 @@ describe("authorize", () => {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
+      expect(guard.granted(read, user)).toBeUndefined();
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(write, user)).toBeUndefined();
    });
 
    test("guard with guest role implicit allow", async () => {
-      const guard = Guard.create(["read", "write"], {
+      const guard = createGuard(["read", "write"], {
          guest: {
             implicit_allow: true,
             is_default: true,
@@ -79,7 +101,143 @@ describe("authorize", () => {
       });
 
       expect(guard.getUserRole()?.name).toBe("guest");
-      expect(guard.granted("read")).toBe(true);
+      expect(guard.granted(read, {})).toBeUndefined();
-      expect(guard.granted("write")).toBe(true);
+      expect(guard.granted(write, {})).toBeUndefined();
+   });
+
+   describe("cases", () => {
+      test("guest none, member deny if user.enabled is false", () => {
+         const guard = createGuard(
+            ["read"],
+            {
+               guest: {
+                  is_default: true,
+               },
+               member: {
+                  permissions: [
+                     {
+                        permission: "read",
+                        policies: [
+                           {
+                              condition: {},
+                              effect: "filter",
+                              filter: {
+                                 type: "member",
+                              },
+                           },
+                           {
+                              condition: {
+                                 "user.enabled": false,
+                              },
+                              effect: "deny",
+                           },
+                        ],
+                     },
+                  ],
+               },
+            },
+            { enabled: true },
+         );
+
+         expect(() => guard.granted(read, { role: "guest" })).toThrow();
+
+         // member is allowed, because default role permission effect is allow
+         // and no deny policy is met
+         expect(guard.granted(read, { role: "member" })).toBeUndefined();
+
+         // member is allowed, because deny policy is not met
+         expect(guard.granted(read, { role: "member", enabled: true })).toBeUndefined();
+
+         // member is denied, because deny policy is met
+         expect(() => guard.granted(read, { role: "member", enabled: false })).toThrow();
+
+         // get the filter for member role
+         expect(guard.filters(read, { role: "member" }).filter).toEqual({
+            type: "member",
+         });
+
+         // get filter for guest
+         expect(guard.filters(read, {}).filter).toBeUndefined();
+      });
+
+      test("guest should only read posts that are public", () => {
+         const read = new Permission(
+            "read",
+            {
+               // make this permission filterable
+               // without this, `filter` policies have no effect
+               filterable: true,
+            },
+            // expect the context to match this schema
+            // otherwise exit with 500 to ensure proper policy checking
+            s.object({
+               entity: s.string(),
+            }),
+         );
+         const guard = createGuard(
+            ["read"],
+            {
+               guest: {
+                  // this permission is applied if no (or invalid) role is provided
+                  is_default: true,
+                  permissions: [
+                     {
+                        permission: "read",
+                        // effect deny means only having this permission, doesn't guarantee access
+                        effect: "deny",
+                        policies: [
+                           {
+                              // only if this condition is met
+                              condition: {
+                                 entity: {
+                                    $in: ["posts"],
+                                 },
+                              },
+                              // the effect is allow
+                              effect: "allow",
+                           },
+                           {
+                              condition: {
+                                 entity: "posts",
+                              },
+                              effect: "filter",
+                              filter: {
+                                 public: true,
+                              },
+                           },
+                        ],
+                     },
+                  ],
+               },
+               // members should be allowed to read all
+               member: {
+                  permissions: [
+                     {
+                        permission: "read",
+                     },
+                  ],
+               },
+            },
+            { enabled: true },
+         );
+
+         // guest can only read posts
+         expect(guard.granted(read, {}, { entity: "posts" })).toBeUndefined();
+         expect(() => guard.granted(read, {}, { entity: "users" })).toThrow();
+
+         // and guests can only read public posts
+         expect(guard.filters(read, {}, { entity: "posts" }).filter).toEqual({
+            public: true,
+         });
+
+         // member can read posts and users
+         expect(guard.granted(read, { role: "member" }, { entity: "posts" })).toBeUndefined();
+         expect(guard.granted(read, { role: "member" }, { entity: "users" })).toBeUndefined();
+
+         // member should not have a filter
+         expect(
+            guard.filters(read, { role: "member" }, { entity: "posts" }).filter,
+         ).toBeUndefined();
+      });
    });
 });

app/__test__/auth/authorize/data.permissions.test.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { createApp } from "core/test/utils";
+import type { CreateAppConfig } from "App";
+import * as proto from "data/prototype";
+import { mergeObject } from "core/utils/objects";
+import type { App, DB } from "bknd";
+import type { CreateUserPayload } from "auth/AppAuth";
+import { disableConsoleLog, enableConsoleLog } from "core/utils/test";
+
+beforeAll(() => disableConsoleLog());
+afterAll(() => enableConsoleLog());
+
+async function makeApp(config: Partial<CreateAppConfig["config"]> = {}) {
+   const app = createApp({
+      config: mergeObject(
+         {
+            data: proto
+               .em(
+                  {
+                     users: proto.systemEntity("users", {}),
+                     posts: proto.entity("posts", {
+                        title: proto.text(),
+                        content: proto.text(),
+                     }),
+                     comments: proto.entity("comments", {
+                        content: proto.text(),
+                     }),
+                  },
+                  ({ relation }, { users, posts, comments }) => {
+                     relation(posts).manyToOne(users);
+                     relation(comments).manyToOne(posts);
+                  },
+               )
+               .toJSON(),
+            auth: {
+               enabled: true,
+               jwt: {
+                  secret: "secret",
+               },
+            },
+         },
+         config,
+      ),
+   });
+   await app.build();
+
+   return app;
+}
+
+async function createUsers(app: App, users: CreateUserPayload[]) {
+   return Promise.all(
+      users.map(async (user) => {
+         return await app.createUser(user);
+      }),
+   );
+}
+
+async function loadFixtures(app: App, fixtures: Record<string, any[]> = {}) {
+   const results = {} as any;
+   for (const [entity, data] of Object.entries(fixtures)) {
+      results[entity] = await app.em
+         .mutator(entity as any)
+         .insertMany(data)
+         .then((result) => result.data);
+   }
+   return results;
+}
+
+describe("data permissions", async () => {
+   const app = await makeApp({
+      server: {
+         mcp: {
+            enabled: true,
+         },
+      },
+      auth: {
+         guard: {
+            enabled: true,
+         },
+         roles: {
+            guest: {
+               is_default: true,
+               permissions: [
+                  {
+                     permission: "system.access.api",
+                  },
+                  {
+                     permission: "data.entity.read",
+                     policies: [
+                        {
+                           condition: {
+                              entity: "posts",
+                           },
+                           effect: "filter",
+                           filter: {
+                              users_id: { $isnull: 1 },
+                           },
+                        },
+                     ],
+                  },
+                  {
+                     permission: "data.entity.create",
+                     policies: [
+                        {
+                           condition: {
+                              entity: "posts",
+                           },
+                           effect: "filter",
+                           filter: {
+                              users_id: { $isnull: 1 },
+                           },
+                        },
+                     ],
+                  },
+                  {
+                     permission: "data.entity.update",
+                     policies: [
+                        {
+                           condition: {
+                              entity: "posts",
+                           },
+                           effect: "filter",
+                           filter: {
+                              users_id: { $isnull: 1 },
+                           },
+                        },
+                     ],
+                  },
+                  {
+                     permission: "data.entity.delete",
+                     policies: [
+                        {
+                           condition: { entity: "posts" },
+                        },
+                        {
+                           condition: { entity: "posts" },
+                           effect: "filter",
+                           filter: {
+                              users_id: { $isnull: 1 },
+                           },
+                        },
+                     ],
+                  },
+               ],
+            },
+         },
+      },
+   });
+   const users = [
+      { email: "foo@example.com", password: "password" },
+      { email: "bar@example.com", password: "password" },
+   ];
+   const fixtures = {
+      posts: [
+         { content: "post 1", users_id: 1 },
+         { content: "post 2", users_id: 2 },
+         { content: "post 3", users_id: null },
+      ],
+      comments: [
+         { content: "comment 1", posts_id: 1 },
+         { content: "comment 2", posts_id: 2 },
+         { content: "comment 3", posts_id: 3 },
+      ],
+   };
+   await createUsers(app, users);
+   const results = await loadFixtures(app, fixtures);
+
+   describe("http", async () => {
+      it("read many", async () => {
+         // many only includes posts with users_id is null
+         const res = await app.server.request("/api/data/entity/posts");
+         const data = await res.json().then((r: any) => r.data);
+         expect(data).toEqual([results.posts[2]]);
+
+         // same with /query
+         {
+            const res = await app.server.request("/api/data/entity/posts/query", {
+               method: "POST",
+            });
+            const data = await res.json().then((r: any) => r.data);
+            expect(data).toEqual([results.posts[2]]);
+         }
+      });
+
+      it("read one", async () => {
+         // one only includes posts with users_id is null
+         {
+            const res = await app.server.request("/api/data/entity/posts/1");
+            const data = await res.json().then((r: any) => r.data);
+            expect(res.status).toBe(404);
+            expect(data).toBeUndefined();
+         }
+
+         // read one by allowed id
+         {
+            const res = await app.server.request("/api/data/entity/posts/3");
+            const data = await res.json().then((r: any) => r.data);
+            expect(res.status).toBe(200);
+            expect(data).toEqual(results.posts[2]);
+         }
+      });
+
+      it("read many by reference", async () => {
+         const res = await app.server.request("/api/data/entity/posts/1/comments");
+         const data = await res.json().then((r: any) => r.data);
+         expect(res.status).toBe(200);
+         expect(data).toEqual(results.comments.filter((c: any) => c.posts_id === 1));
+      });
+
+      it("mutation create one", async () => {
+         // not allowed
+         {
+            const res = await app.server.request("/api/data/entity/posts", {
+               method: "POST",
+               body: JSON.stringify({ content: "post 4" }),
+            });
+            expect(res.status).toBe(403);
+         }
+         // allowed
+         {
+            const res = await app.server.request("/api/data/entity/posts", {
+               method: "POST",
+               body: JSON.stringify({ content: "post 4", users_id: null }),
+            });
+            expect(res.status).toBe(201);
+         }
+      });
+
+      it("mutation update one", async () => {
+         // update one: not allowed
+         const res = await app.server.request("/api/data/entity/posts/1", {
+            method: "PATCH",
+            body: JSON.stringify({ content: "post 4" }),
+         });
+         expect(res.status).toBe(403);
+
+         {
+            // update one: allowed
+            const res = await app.server.request("/api/data/entity/posts/3", {
+               method: "PATCH",
+               body: JSON.stringify({ content: "post 3 (updated)" }),
+            });
+            expect(res.status).toBe(200);
+            expect(await res.json().then((r: any) => r.data.content)).toBe("post 3 (updated)");
+         }
+      });
+
+      it("mutation update many", async () => {
+         // update many: not allowed
+         const res = await app.server.request("/api/data/entity/posts", {
+            method: "PATCH",
+            headers: {
+               "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+               update: { content: "post 4" },
+               where: { users_id: { $isnull: 0 } },
+            }),
+         });
+         expect(res.status).toBe(200); // because filtered
+         const _data = await res.json().then((r: any) => r.data.map((p: any) => p.users_id));
+         expect(_data.every((u: any) => u === null)).toBe(true);
+
+         // verify
+         const data = await app.em
+            .repo("posts")
+            .findMany({ select: ["content", "users_id"] })
+            .then((r) => r.data);
+
+         // expect non null users_id to not have content "post 4"
+         expect(
+            data.filter((p: any) => p.users_id !== null).every((p: any) => p.content !== "post 4"),
+         ).toBe(true);
+         // expect null users_id to have content "post 4"
+         expect(
+            data.filter((p: any) => p.users_id === null).every((p: any) => p.content === "post 4"),
+         ).toBe(true);
+      });
+
+      const count = async () => {
+         const {
+            data: { count: _count },
+         } = await app.em.repo("posts").count();
+         return _count;
+      };
+      it("mutation delete one", async () => {
+         const initial = await count();
+
+         // delete one: not allowed
+         const res = await app.server.request("/api/data/entity/posts/1", {
+            method: "DELETE",
+         });
+         expect(res.status).toBe(403);
+         expect(await count()).toBe(initial);
+
+         {
+            // delete one: allowed
+            const res = await app.server.request("/api/data/entity/posts/3", {
+               method: "DELETE",
+            });
+            expect(res.status).toBe(200);
+            expect(await count()).toBe(initial - 1);
+         }
+      });
+
+      it("mutation delete many", async () => {
+         // delete many: not allowed
+         const res = await app.server.request("/api/data/entity/posts", {
+            method: "DELETE",
+            headers: {
+               "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+               where: {},
+            }),
+         });
+         expect(res.status).toBe(200);
+
+         // only deleted posts with users_id is null
+         const remaining = await app.em
+            .repo("posts")
+            .findMany()
+            .then((r) => r.data);
+         expect(remaining.every((p: any) => p.users_id !== null)).toBe(true);
+      });
+   });
+});

app/__test__/auth/authorize/http/SystemController.spec.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "bun:test";
+import { SystemController } from "modules/server/SystemController";
+import { createApp } from "core/test/utils";
+import type { CreateAppConfig } from "App";
+import { getPermissionRoutes } from "auth/middlewares/permission.middleware";
+
+async function makeApp(config: Partial<CreateAppConfig> = {}) {
+   const app = createApp(config);
+   await app.build();
+   return app;
+}
+
+describe.skip("SystemController", () => {
+   it("...", async () => {
+      const app = await makeApp();
+      const controller = new SystemController(app);
+      const hono = controller.getController();
+      console.log(getPermissionRoutes(hono));
+   });
+});

app/__test__/auth/authorize/permissions.spec.ts

@@ -0,0 +1,543 @@
+import { describe, it, expect } from "bun:test";
+import { s } from "bknd/utils";
+import { Permission } from "auth/authorize/Permission";
+import { Policy } from "auth/authorize/Policy";
+import { Hono } from "hono";
+import { getPermissionRoutes, permission } from "auth/middlewares/permission.middleware";
+import { auth } from "auth/middlewares/auth.middleware";
+import { Guard, mergeFilters, type GuardConfig } from "auth/authorize/Guard";
+import { Role, RolePermission } from "auth/authorize/Role";
+import { Exception } from "bknd";
+import { convert } from "core/object/query/object-query";
+
+describe("Permission", () => {
+   it("works with minimal schema", () => {
+      expect(() => new Permission("test")).not.toThrow();
+   });
+
+   it("parses context", () => {
+      const p = new Permission(
+         "test3",
+         {
+            filterable: true,
+         },
+         s.object({
+            a: s.string(),
+         }),
+      );
+
+      // @ts-expect-error
+      expect(() => p.parseContext({ a: [] })).toThrow();
+      expect(p.parseContext({ a: "test" })).toEqual({ a: "test" });
+      // @ts-expect-error
+      expect(p.parseContext({ a: 1 })).toEqual({ a: "1" });
+   });
+});
+
+describe("Policy", () => {
+   it("works with minimal schema", () => {
+      expect(() => new Policy().toJSON()).not.toThrow();
+   });
+
+   it("checks condition", () => {
+      const p = new Policy({
+         condition: {
+            a: 1,
+         },
+      });
+
+      expect(p.meetsCondition({ a: 1 })).toBe(true);
+      expect(p.meetsCondition({ a: 2 })).toBe(false);
+      expect(p.meetsCondition({ a: 1, b: 1 })).toBe(true);
+      expect(p.meetsCondition({})).toBe(false);
+
+      const p2 = new Policy({
+         condition: {
+            a: { $gt: 1 },
+            $or: {
+               b: { $lt: 2 },
+            },
+         },
+      });
+
+      expect(p2.meetsCondition({ a: 2 })).toBe(true);
+      expect(p2.meetsCondition({ a: 1 })).toBe(false);
+      expect(p2.meetsCondition({ a: 1, b: 1 })).toBe(true);
+   });
+
+   it("filters", () => {
+      const p = new Policy({
+         filter: {
+            age: { $gt: 18 },
+         },
+      });
+      const subjects = [{ age: 19 }, { age: 17 }, { age: 12 }];
+
+      expect(p.getFiltered(subjects)).toEqual([{ age: 19 }]);
+
+      expect(p.meetsFilter({ age: 19 })).toBe(true);
+      expect(p.meetsFilter({ age: 17 })).toBe(false);
+      expect(p.meetsFilter({ age: 12 })).toBe(false);
+   });
+
+   it("replaces placeholders", () => {
+      const p = new Policy({
+         condition: {
+            a: "@auth.username",
+         },
+         filter: {
+            a: "@auth.username",
+         },
+      });
+      const vars = { auth: { username: "test" } };
+
+      expect(p.meetsCondition({ a: "test" }, vars)).toBe(true);
+      expect(p.meetsCondition({ a: "test2" }, vars)).toBe(false);
+      expect(p.meetsCondition({ a: "test2" })).toBe(false);
+      expect(p.meetsFilter({ a: "test" }, vars)).toBe(true);
+      expect(p.meetsFilter({ a: "test2" }, vars)).toBe(false);
+      expect(p.meetsFilter({ a: "test2" })).toBe(false);
+   });
+});
+
+describe("Guard", () => {
+   it("collects filters", () => {
+      const p = new Permission(
+         "test",
+         {
+            filterable: true,
+         },
+         s.object({
+            a: s.number(),
+         }),
+      );
+      const r = new Role("test", [
+         new RolePermission(p, [
+            new Policy({
+               condition: { a: { $eq: 1 } },
+               filter: { foo: "bar" },
+               effect: "filter",
+            }),
+         ]),
+      ]);
+      const guard = new Guard([p], [r], {
+         enabled: true,
+      });
+      expect(guard.filters(p, { role: r.name }, { a: 1 }).filter).toEqual({ foo: "bar" });
+      expect(guard.filters(p, { role: r.name }, { a: 2 }).filter).toBeUndefined();
+      // if no user context given, filter cannot be applied
+      expect(guard.filters(p, {}, { a: 1 }).filter).toBeUndefined();
+   });
+
+   it("collects filters for default role", () => {
+      const p = new Permission(
+         "test",
+         {
+            filterable: true,
+         },
+         s.object({
+            a: s.number(),
+         }),
+      );
+      const r = new Role(
+         "test",
+         [
+            new RolePermission(p, [
+               new Policy({
+                  condition: { a: { $eq: 1 } },
+                  filter: { foo: "bar" },
+                  effect: "filter",
+               }),
+            ]),
+         ],
+         true,
+      );
+      const guard = new Guard([p], [r], {
+         enabled: true,
+      });
+
+      expect(
+         guard.filters(
+            p,
+            {
+               role: r.name,
+            },
+            { a: 1 },
+         ).filter,
+      ).toEqual({ foo: "bar" });
+      expect(
+         guard.filters(
+            p,
+            {
+               role: r.name,
+            },
+            { a: 2 },
+         ).filter,
+      ).toBeUndefined();
+      // if no user context given, the default role is applied
+      // hence it can be found
+      expect(guard.filters(p, {}, { a: 1 }).filter).toEqual({ foo: "bar" });
+   });
+
+   it("merges filters correctly", () => {
+      expect(mergeFilters({ foo: "bar" }, { baz: "qux" })).toEqual({
+         foo: { $eq: "bar" },
+         baz: { $eq: "qux" },
+      });
+      expect(mergeFilters({ foo: "bar" }, { baz: { $eq: "qux" } })).toEqual({
+         foo: { $eq: "bar" },
+         baz: { $eq: "qux" },
+      });
+      expect(mergeFilters({ foo: "bar" }, { foo: "baz" })).toEqual({ foo: { $eq: "baz" } });
+
+      expect(mergeFilters({ foo: "bar" }, { foo: { $lt: 1 } })).toEqual({
+         foo: { $eq: "bar", $lt: 1 },
+      });
+
+      // overwrite base $or with priority
+      expect(mergeFilters({ $or: { foo: "one" } }, { foo: "bar" })).toEqual({
+         $or: {
+            foo: {
+               $eq: "bar",
+            },
+         },
+         foo: {
+            $eq: "bar",
+         },
+      });
+
+      // ignore base $or if priority has different key
+      expect(mergeFilters({ $or: { other: "one" } }, { foo: "bar" })).toEqual({
+         $or: {
+            other: {
+               $eq: "one",
+            },
+         },
+         foo: {
+            $eq: "bar",
+         },
+      });
+   });
+});
+
+describe("permission middleware", () => {
+   const makeApp = (
+      permissions: Permission<any, any, any, any>[],
+      roles: Role[] = [],
+      config: Partial<GuardConfig> = {},
+   ) => {
+      const app = {
+         module: {
+            auth: {
+               enabled: true,
+            },
+         },
+         modules: {
+            ctx: () => ({
+               guard: new Guard(permissions, roles, {
+                  enabled: true,
+                  ...config,
+               }),
+            }),
+         },
+      };
+      return new Hono()
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("app", app);
+            await next();
+         })
+         .use(auth())
+         .onError((err, c) => {
+            if (err instanceof Exception) {
+               return c.json(err.toJSON(), err.code as any);
+            }
+            return c.json({ error: err.message }, "code" in err ? (err.code as any) : 500);
+         });
+   };
+
+   it("allows if guard is disabled", async () => {
+      const p = new Permission("test");
+      const hono = makeApp([p], [], { enabled: false }).get("/test", permission(p, {}), async (c) =>
+         c.text("test"),
+      );
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe("test");
+   });
+
+   it("denies if guard is enabled", async () => {
+      const p = new Permission("test");
+      const hono = makeApp([p]).get("/test", permission(p, {}), async (c) => c.text("test"));
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(403);
+   });
+
+   it("allows if user has (plain) role", async () => {
+      const p = new Permission("test");
+      const r = Role.create("test", { permissions: [p.name] });
+      const hono = makeApp([p], [r])
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("auth", { registered: true, user: { id: 0, role: r.name } });
+            await next();
+         })
+         .get("/test", permission(p, {}), async (c) => c.text("test"));
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(200);
+   });
+
+   it("allows if user has role with policy", async () => {
+      const p = new Permission("test");
+      const r = new Role("test", [
+         new RolePermission(p, [
+            new Policy({
+               condition: {
+                  a: { $gte: 1 },
+               },
+            }),
+         ]),
+      ]);
+      const hono = makeApp([p], [r], {
+         context: {
+            a: 1,
+         },
+      })
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("auth", { registered: true, user: { id: 0, role: r.name } });
+            await next();
+         })
+         .get("/test", permission(p, {}), async (c) => c.text("test"));
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(200);
+   });
+
+   it("denies if user with role doesn't meet condition", async () => {
+      const p = new Permission("test");
+      const r = new Role("test", [
+         new RolePermission(
+            p,
+            [
+               new Policy({
+                  condition: {
+                     a: { $lt: 1 },
+                  },
+                  // default effect is allow
+               }),
+            ],
+            // change default effect to deny if no condition is met
+            "deny",
+         ),
+      ]);
+      const hono = makeApp([p], [r], {
+         context: {
+            a: 1,
+         },
+      })
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("auth", { registered: true, user: { id: 0, role: r.name } });
+            await next();
+         })
+         .get("/test", permission(p, {}), async (c) => c.text("test"));
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(403);
+   });
+
+   it("allows if user with role doesn't meet condition (from middleware)", async () => {
+      const p = new Permission(
+         "test",
+         {},
+         s.object({
+            a: s.number(),
+         }),
+      );
+      const r = new Role("test", [
+         new RolePermission(p, [
+            new Policy({
+               condition: {
+                  a: { $eq: 1 },
+               },
+            }),
+         ]),
+      ]);
+      const hono = makeApp([p], [r])
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("auth", { registered: true, user: { id: 0, role: r.name } });
+            await next();
+         })
+         .get(
+            "/test",
+            permission(p, {
+               context: (c) => ({
+                  a: 1,
+               }),
+            }),
+            async (c) => c.text("test"),
+         );
+
+      const res = await hono.request("/test");
+      expect(res.status).toBe(200);
+   });
+
+   it("throws if permission context is invalid", async () => {
+      const p = new Permission(
+         "test",
+         {},
+         s.object({
+            a: s.number({ minimum: 2 }),
+         }),
+      );
+      const r = new Role("test", [
+         new RolePermission(p, [
+            new Policy({
+               condition: {
+                  a: { $eq: 1 },
+               },
+            }),
+         ]),
+      ]);
+      const hono = makeApp([p], [r])
+         .use(async (c, next) => {
+            // @ts-expect-error
+            c.set("auth", { registered: true, user: { id: 0, role: r.name } });
+            await next();
+         })
+         .get(
+            "/test",
+            permission(p, {
+               context: (c) => ({
+                  a: 1,
+               }),
+            }),
+            async (c) => c.text("test"),
+         );
+
+      const res = await hono.request("/test");
+      // expecting 500 because bknd should have handled it correctly
+      expect(res.status).toBe(500);
+   });
+
+   it("checks context on routes with permissions", async () => {
+      const make = (user: any) => {
+         const p = new Permission(
+            "test",
+            {},
+            s.object({
+               a: s.number(),
+            }),
+         );
+         const r = new Role("test", [
+            new RolePermission(p, [
+               new Policy({
+                  condition: {
+                     a: { $eq: 1 },
+                  },
+               }),
+            ]),
+         ]);
+         return makeApp([p], [r])
+            .use(async (c, next) => {
+               // @ts-expect-error
+               c.set("auth", { registered: true, user });
+               await next();
+            })
+            .get(
+               "/valid",
+               permission(p, {
+                  context: (c) => ({
+                     a: 1,
+                  }),
+               }),
+               async (c) => c.text("test"),
+            )
+            .get(
+               "/invalid",
+               permission(p, {
+                  // @ts-expect-error
+                  context: (c) => ({
+                     b: "1",
+                  }),
+               }),
+               async (c) => c.text("test"),
+            )
+            .get(
+               "/invalid2",
+               permission(p, {
+                  // @ts-expect-error
+                  context: (c) => ({}),
+               }),
+               async (c) => c.text("test"),
+            )
+            .get(
+               "/invalid3",
+               // @ts-expect-error
+               permission(p),
+               async (c) => c.text("test"),
+            );
+      };
+
+      const hono = make({ id: 0, role: "test" });
+      const valid = await hono.request("/valid");
+      expect(valid.status).toBe(200);
+      const invalid = await hono.request("/invalid");
+      expect(invalid.status).toBe(500);
+      const invalid2 = await hono.request("/invalid2");
+      expect(invalid2.status).toBe(500);
+      const invalid3 = await hono.request("/invalid3");
+      expect(invalid3.status).toBe(500);
+
+      {
+         const hono = make(null);
+         const valid = await hono.request("/valid");
+         expect(valid.status).toBe(403);
+         const invalid = await hono.request("/invalid");
+         expect(invalid.status).toBe(500);
+         const invalid2 = await hono.request("/invalid2");
+         expect(invalid2.status).toBe(500);
+         const invalid3 = await hono.request("/invalid3");
+         expect(invalid3.status).toBe(500);
+      }
+   });
+});
+
+describe("Role", () => {
+   it("serializes and deserializes", () => {
+      const p = new Permission(
+         "test",
+         {
+            filterable: true,
+         },
+         s.object({
+            a: s.number({ minimum: 2 }),
+         }),
+      );
+      const r = new Role(
+         "test",
+         [
+            new RolePermission(p, [
+               new Policy({
+                  condition: {
+                     a: { $eq: 1 },
+                  },
+                  effect: "deny",
+                  filter: {
+                     b: { $lt: 1 },
+                  },
+               }),
+            ]),
+         ],
+         true,
+      );
+      const json = JSON.parse(JSON.stringify(r.toJSON()));
+      const r2 = Role.create(p.name, json);
+      expect(r2.toJSON()).toEqual(r.toJSON());
+   });
+});

app/__test__/core/object/object-query.spec.ts

@@ -66,4 +66,14 @@ describe("object-query", () => {
          expect(result).toBe(expected);
       }
    });
+
+   test("paths", () => {
+      const result = validate({ "user.age": { $lt: 18 } }, { user: { age: 17 } });
+      expect(result).toBe(true);
+   });
+
+   test("empty filters", () => {
+      const result = validate({}, { user: { age: 17 } });
+      expect(result).toBe(true);
+   });
 });

app/__test__/core/object/query.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import {
+   makeValidator,
+   exp,
+   Expression,
+   isPrimitive,
+   type Primitive,
+} from "../../../src/core/object/query/query";
+
+describe("query", () => {
+   test("isPrimitive", () => {
+      expect(isPrimitive(1)).toBe(true);
+      expect(isPrimitive("1")).toBe(true);
+      expect(isPrimitive(true)).toBe(true);
+      expect(isPrimitive(false)).toBe(true);
+
+      // not primitives
+      expect(isPrimitive(null)).toBe(false);
+      expect(isPrimitive(undefined)).toBe(false);
+      expect(isPrimitive([])).toBe(false);
+      expect(isPrimitive({})).toBe(false);
+      expect(isPrimitive(Symbol("test"))).toBe(false);
+      expect(isPrimitive(new Date())).toBe(false);
+      expect(isPrimitive(new Error())).toBe(false);
+      expect(isPrimitive(new Set())).toBe(false);
+      expect(isPrimitive(new Map())).toBe(false);
+   });
+
+   test("strict expression creation", () => {
+      // @ts-expect-error
+      expect(() => exp()).toThrow();
+      // @ts-expect-error
+      expect(() => exp("")).toThrow();
+      // @ts-expect-error
+      expect(() => exp("invalid")).toThrow();
+      // @ts-expect-error
+      expect(() => exp("$eq")).toThrow();
+      // @ts-expect-error
+      expect(() => exp("$eq", 1)).toThrow();
+      // @ts-expect-error
+      expect(() => exp("$eq", () => null)).toThrow();
+      // @ts-expect-error
+      expect(() => exp("$eq", () => null, 1)).toThrow();
+      expect(
+         exp(
+            "$eq",
+            () => true,
+            () => null,
+         ),
+      ).toBeInstanceOf(Expression);
+   });
+
+   test("$eq is required", () => {
+      expect(() => makeValidator([])).toThrow();
+      expect(() =>
+         makeValidator([
+            exp(
+               "$valid",
+               () => true,
+               () => null,
+            ),
+         ]),
+      ).toThrow();
+      expect(
+         makeValidator([
+            exp(
+               "$eq",
+               () => true,
+               () => null,
+            ),
+         ]),
+      ).toBeDefined();
+   });
+
+   test("validates filter structure", () => {
+      const validator = makeValidator([
+         exp(
+            "$eq",
+            (v: Primitive) => isPrimitive(v),
+            (e, a) => e === a,
+         ),
+         exp(
+            "$like",
+            (v: string) => typeof v === "string",
+            (e, a) => e === a,
+         ),
+      ]);
+
+      // @ts-expect-error intentionally typed as union of given expression keys
+      expect(validator.expressionKeys).toEqual(["$eq", "$like"]);
+
+      // @ts-expect-error "$and" is not allowed
+      expect(() => validator.convert({ $and: {} })).toThrow();
+
+      // @ts-expect-error "$or" must be an object
+      expect(() => validator.convert({ $or: [] })).toThrow();
+
+      // @ts-expect-error "invalid" is not a valid expression key
+      expect(() => validator.convert({ foo: { invalid: "bar" } })).toThrow();
+
+      // @ts-expect-error "invalid" is not a valid expression key
+      expect(() => validator.convert({ foo: { $invalid: "bar" } })).toThrow();
+
+      // @ts-expect-error "null" is not a valid value
+      expect(() => validator.convert({ foo: null })).toThrow();
+
+      // @ts-expect-error only primitives are allowed for $eq
+      expect(() => validator.convert({ foo: { $eq: [] } })).toThrow();
+
+      // @ts-expect-error only strings are allowed for $like
+      expect(() => validator.convert({ foo: { $like: 1 } })).toThrow();
+
+      // undefined values are ignored
+      expect(validator.convert({ foo: undefined })).toEqual({});
+
+      expect(validator.convert({ foo: "bar" })).toEqual({ foo: { $eq: "bar" } });
+      expect(validator.convert({ foo: { $eq: "bar" } })).toEqual({ foo: { $eq: "bar" } });
+      expect(validator.convert({ foo: { $like: "bar" } })).toEqual({ foo: { $like: "bar" } });
+   });
+});

app/__test__/core/utils.spec.ts

@@ -194,6 +194,182 @@ describe("Core Utils", async () => {
             expect(result).toEqual(expected);
          }
       });
+
+      test("recursivelyReplacePlaceholders", () => {
+         // test basic replacement with simple pattern
+         const obj1 = { a: "Hello, {$name}!", b: { c: "Hello, {$name}!" } };
+         const variables1 = { name: "John" };
+         const result1 = utils.recursivelyReplacePlaceholders(obj1, /\{\$(\w+)\}/g, variables1);
+         expect(result1).toEqual({ a: "Hello, John!", b: { c: "Hello, John!" } });
+
+         // test the specific example from the user request
+         const obj2 = { some: "value", here: "@auth.user" };
+         const variables2 = { auth: { user: "what" } };
+         const result2 = utils.recursivelyReplacePlaceholders(obj2, /^@([a-z\.]+)$/, variables2);
+         expect(result2).toEqual({ some: "value", here: "what" });
+
+         // test with arrays
+         const obj3 = { items: ["@config.name", "static", "@config.version"] };
+         const variables3 = { config: { name: "MyApp", version: "1.0.0" } };
+         const result3 = utils.recursivelyReplacePlaceholders(obj3, /^@([a-z\.]+)$/, variables3);
+         expect(result3).toEqual({ items: ["MyApp", "static", "1.0.0"] });
+
+         // test with nested objects and deep paths
+         const obj4 = {
+            user: "@auth.user.name",
+            settings: {
+               theme: "@ui.theme",
+               nested: {
+                  value: "@deep.nested.value",
+               },
+            },
+         };
+         const variables4 = {
+            auth: { user: { name: "Alice" } },
+            ui: { theme: "dark" },
+            deep: { nested: { value: "found" } },
+         };
+         const result4 = utils.recursivelyReplacePlaceholders(obj4, /^@([a-z\.]+)$/, variables4);
+         expect(result4).toEqual({
+            user: "Alice",
+            settings: {
+               theme: "dark",
+               nested: {
+                  value: "found",
+               },
+            },
+         });
+
+         // test with missing paths (should return original match)
+         const obj5 = { value: "@missing.path" };
+         const variables5 = { existing: "value" };
+         const result5 = utils.recursivelyReplacePlaceholders(obj5, /^@([a-z\.]+)$/, variables5);
+         expect(result5).toEqual({ value: "@missing.path" });
+
+         // test with non-matching strings (should remain unchanged)
+         const obj6 = { value: "normal string", other: "not@matching" };
+         const variables6 = { some: "value" };
+         const result6 = utils.recursivelyReplacePlaceholders(obj6, /^@([a-z\.]+)$/, variables6);
+         expect(result6).toEqual({ value: "normal string", other: "not@matching" });
+
+         // test with primitive values (should handle gracefully)
+         expect(
+            utils.recursivelyReplacePlaceholders("@test.value", /^@([a-z\.]+)$/, {
+               test: { value: "replaced" },
+            }),
+         ).toBe("replaced");
+         expect(utils.recursivelyReplacePlaceholders(123, /^@([a-z\.]+)$/, {})).toBe(123);
+         expect(utils.recursivelyReplacePlaceholders(null, /^@([a-z\.]+)$/, {})).toBe(null);
+
+         // test type preservation for full string matches
+         const variables7 = { test: { value: 123, flag: true, data: null, arr: [1, 2, 3] } };
+         const result7 = utils.recursivelyReplacePlaceholders(
+            {
+               number: "@test.value",
+               boolean: "@test.flag",
+               nullValue: "@test.data",
+               array: "@test.arr",
+            },
+            /^@([a-z\.]+)$/,
+            variables7,
+            null,
+         );
+         expect(result7).toEqual({
+            number: 123,
+            boolean: true,
+            nullValue: null,
+            array: [1, 2, 3],
+         });
+
+         // test partial string replacement (should convert to string)
+         const result8 = utils.recursivelyReplacePlaceholders(
+            { message: "The value is @test.value!" },
+            /@([a-z\.]+)/g,
+            variables7,
+         );
+         expect(result8).toEqual({ message: "The value is 123!" });
+
+         // test with fallback parameter
+         const obj9 = { user: "@user.id", config: "@config.theme" };
+         const variables9 = {}; // empty context
+         const result9 = utils.recursivelyReplacePlaceholders(
+            obj9,
+            /^@([a-z\.]+)$/,
+            variables9,
+            null,
+         );
+         expect(result9).toEqual({ user: null, config: null });
+
+         // test with fallback for partial matches
+         const obj10 = { message: "Hello @user.name, welcome!" };
+         const variables10 = {}; // empty context
+         const result10 = utils.recursivelyReplacePlaceholders(
+            obj10,
+            /@([a-z\.]+)/g,
+            variables10,
+            "Guest",
+         );
+         expect(result10).toEqual({ message: "Hello Guest, welcome!" });
+
+         // test with different fallback types
+         const obj11 = {
+            stringFallback: "@missing.string",
+            numberFallback: "@missing.number",
+            booleanFallback: "@missing.boolean",
+            objectFallback: "@missing.object",
+         };
+         const variables11 = {};
+         const result11 = utils.recursivelyReplacePlaceholders(
+            obj11,
+            /^@([a-z\.]+)$/,
+            variables11,
+            "default",
+         );
+         expect(result11).toEqual({
+            stringFallback: "default",
+            numberFallback: "default",
+            booleanFallback: "default",
+            objectFallback: "default",
+         });
+
+         // test fallback with arrays
+         const obj12 = { items: ["@item1", "@item2", "static"] };
+         const variables12 = { item1: "found" }; // item2 is missing
+         const result12 = utils.recursivelyReplacePlaceholders(
+            obj12,
+            /^@([a-zA-Z0-9\.]+)$/,
+            variables12,
+            "missing",
+         );
+         expect(result12).toEqual({ items: ["found", "missing", "static"] });
+
+         // test fallback with nested objects
+         const obj13 = {
+            user: "@user.id",
+            settings: {
+               theme: "@theme.name",
+               nested: {
+                  value: "@deep.value",
+               },
+            },
+         };
+         const variables13 = {}; // empty context
+         const result13 = utils.recursivelyReplacePlaceholders(
+            obj13,
+            /^@([a-z\.]+)$/,
+            variables13,
+            null,
+         );
+         expect(result13).toEqual({
+            user: null,
+            settings: {
+               theme: null,
+               nested: {
+                  value: null,
+               },
+            },
+         });
+      });
    });
 
    describe("file", async () => {
@@ -264,6 +440,35 @@ describe("Core Utils", async () => {
             height: 512,
          });
       });
+
+      test("isFileAccepted", () => {
+         const file = new File([""], "file.txt", {
+            type: "text/plain",
+         });
+         expect(utils.isFileAccepted(file, "text/plain")).toBe(true);
+         expect(utils.isFileAccepted(file, "text/plain,text/html")).toBe(true);
+         expect(utils.isFileAccepted(file, "text/html")).toBe(false);
+
+         {
+            const file = new File([""], "file.jpg", {
+               type: "image/jpeg",
+            });
+            expect(utils.isFileAccepted(file, "image/jpeg")).toBe(true);
+            expect(utils.isFileAccepted(file, "image/jpeg,image/png")).toBe(true);
+            expect(utils.isFileAccepted(file, "image/png")).toBe(false);
+            expect(utils.isFileAccepted(file, "image/*")).toBe(true);
+            expect(utils.isFileAccepted(file, ".jpg")).toBe(true);
+            expect(utils.isFileAccepted(file, ".jpg,.png")).toBe(true);
+            expect(utils.isFileAccepted(file, ".png")).toBe(false);
+         }
+
+         {
+            const file = new File([""], "file.png");
+            expect(utils.isFileAccepted(file, undefined as any)).toBe(true);
+         }
+
+         expect(() => utils.isFileAccepted(null as any, "text/plain")).toThrow();
+      });
    });
 
    describe("dates", () => {

app/__test__/data/data.test.ts

@@ -30,9 +30,9 @@ describe("some tests", async () => {
       const query = await em.repository(users).findId(1);
 
       expect(query.sql).toBe(
-         'select "users"."id" as "id", "users"."username" as "username", "users"."email" as "email" from "users" where "id" = ? limit ?',
+         'select "users"."id" as "id", "users"."username" as "username", "users"."email" as "email" from "users" where "id" = ? order by "users"."id" asc limit ? offset ?',
       );
-      expect(query.parameters).toEqual([1, 1]);
+      expect(query.parameters).toEqual([1, 1, 0]);
       expect(query.data).toBeUndefined();
    });
 

app/__test__/data/specs/SchemaManager.spec.ts

@@ -1,5 +1,5 @@
 // eslint-disable-next-line import/no-unresolved
-import { afterAll, describe, expect, test } from "bun:test";
+import { afterAll, describe, expect, spyOn, test } from "bun:test";
 import { randomString } from "core/utils";
 import { Entity, EntityManager } from "data/entities";
 import { TextField, EntityIndex } from "data/fields";
@@ -268,4 +268,39 @@ describe("SchemaManager tests", async () => {
       const diffAfter = await em.schema().getDiff();
       expect(diffAfter.length).toBe(0);
    });
+
+   test("returns statements", async () => {
+      const amount = 5;
+      const entities = new Array(amount)
+         .fill(0)
+         .map(() => new Entity(randomString(16), [new TextField("text")]));
+      const em = new EntityManager(entities, dummyConnection);
+      const statements = await em.schema().sync({ force: true });
+      expect(statements.length).toBe(amount);
+      expect(statements.every((stmt) => Object.keys(stmt).join(",") === "sql,parameters")).toBe(
+         true,
+      );
+   });
+
+   test("batches statements", async () => {
+      const { dummyConnection } = getDummyConnection();
+      const entities = new Array(20)
+         .fill(0)
+         .map(() => new Entity(randomString(16), [new TextField("text")]));
+      const em = new EntityManager(entities, dummyConnection);
+      const spy = spyOn(em.connection, "executeQueries");
+      const statements = await em.schema().sync();
+      expect(statements.length).toBe(entities.length);
+      expect(statements.every((stmt) => Object.keys(stmt).join(",") === "sql,parameters")).toBe(
+         true,
+      );
+      await em.schema().sync({ force: true });
+      expect(spy).toHaveBeenCalledTimes(1);
+      const tables = await em.connection.kysely
+         .selectFrom("sqlite_master")
+         .where("type", "=", "table")
+         .selectAll()
+         .execute();
+      expect(tables.length).toBe(entities.length + 1); /* 1+ for sqlite_sequence */
+   });
 });

app/__test__/data/specs/fields/JsonField.spec.ts

@@ -7,7 +7,7 @@ describe("[data] JsonField", async () => {
    const field = new JsonField("test");
    fieldTestSuite(bunTestRunner, JsonField, {
       defaultValue: { a: 1 },
-      sampleValues: ["string", { test: 1 }, 1],
+      //sampleValues: ["string", { test: 1 }, 1],
       schemaType: "text",
    });
 
@@ -33,9 +33,9 @@ describe("[data] JsonField", async () => {
    });
 
    test("getValue", async () => {
-      expect(field.getValue({ test: 1 }, "form")).toBe('{\n  "test": 1\n}');
+      expect(field.getValue({ test: 1 }, "form")).toEqual({ test: 1 });
-      expect(field.getValue("string", "form")).toBe('"string"');
+      expect(field.getValue("string", "form")).toBe("string");
-      expect(field.getValue(1, "form")).toBe("1");
+      expect(field.getValue(1, "form")).toBe(1);
 
       expect(field.getValue('{"test":1}', "submit")).toEqual({ test: 1 });
       expect(field.getValue('"string"', "submit")).toBe("string");
@@ -43,6 +43,5 @@ describe("[data] JsonField", async () => {
 
       expect(field.getValue({ test: 1 }, "table")).toBe('{"test":1}');
       expect(field.getValue("string", "table")).toBe('"string"');
-      expect(field.getValue(1, "form")).toBe("1");
    });
 });

app/__test__/integration/auth.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { App, createApp, type AuthResponse } from "../../src";
-import { auth } from "../../src/auth/middlewares";
+import { auth } from "../../src/modules/middlewares";
 import { randomString, secureRandomString, withDisabledConsole } from "../../src/core/utils";
 import { disableConsoleLog, enableConsoleLog } from "core/utils/test";
 import { getDummyConnection } from "../helper";

app/__test__/modules/migrations/migrations.spec.ts

@@ -7,7 +7,9 @@ import v7 from "./samples/v7.json";
 import v8 from "./samples/v8.json";
 import v8_2 from "./samples/v8-2.json";
 import v9 from "./samples/v9.json";
+import v10 from "./samples/v10.json";
 import { disableConsoleLog, enableConsoleLog } from "core/utils/test";
+import { CURRENT_VERSION } from "modules/db/migrations";
 
 beforeAll(() => disableConsoleLog());
 afterAll(enableConsoleLog);
@@ -61,7 +63,7 @@ async function getRawConfig(
    return await db
       .selectFrom("__bknd")
       .selectAll()
-      .$if(!!opts?.version, (qb) => qb.where("version", "=", opts?.version))
+      .where("version", "=", opts?.version ?? CURRENT_VERSION)
       .$if((opts?.types?.length ?? 0) > 0, (qb) => qb.where("type", "in", opts?.types))
       .execute();
 }
@@ -115,7 +117,6 @@ describe("Migrations", () => {
          "^^s3.secret_access_key^^",
       );
       const [config, secrets] = (await getRawConfig(app, {
-         version: 10,
          types: ["config", "secrets"],
       })) as any;
 
@@ -129,4 +130,15 @@ describe("Migrations", () => {
          "^^s3.secret_access_key^^",
       );
    });
+
+   test("migration from 10 to 11", async () => {
+      expect(v10.version).toBe(10);
+      expect(v10.data.entities.test.fields.title.config.fillable).toEqual(["read", "update"]);
+
+      const app = await createVersionedApp(v10);
+
+      expect(app.version()).toBeGreaterThan(10);
+      const [config] = (await getRawConfig(app, { types: ["config"] })) as any;
+      expect(config.json.data.entities.test.fields.title.config.fillable).toEqual(true);
+   });
 });

app/__test__/modules/migrations/samples/v10.json

@@ -0,0 +1,270 @@
+{
+  "version": 10,
+  "server": {
+    "cors": {
+      "origin": "*",
+      "allow_methods": ["GET", "POST", "PATCH", "PUT", "DELETE"],
+      "allow_headers": [
+        "Content-Type",
+        "Content-Length",
+        "Authorization",
+        "Accept"
+      ],
+      "allow_credentials": true
+    },
+    "mcp": {
+      "enabled": true,
+      "path": "/api/system/mcp",
+      "logLevel": "warning"
+    }
+  },
+  "data": {
+    "basepath": "/api/data",
+    "default_primary_format": "integer",
+    "entities": {
+      "test": {
+        "type": "regular",
+        "fields": {
+          "id": {
+            "type": "primary",
+            "config": {
+              "format": "integer",
+              "fillable": false,
+              "required": false
+            }
+          },
+          "title": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": ["read", "update"]
+            }
+          },
+          "status": {
+            "type": "enum",
+            "config": {
+              "default_value": "INACTIVE",
+              "options": {
+                "type": "strings",
+                "values": ["INACTIVE", "SUBSCRIBED", "UNSUBSCRIBED"]
+              },
+              "required": true,
+              "fillable": true
+            }
+          },
+          "created_at": {
+            "type": "date",
+            "config": {
+              "type": "datetime",
+              "required": true,
+              "fillable": true
+            }
+          },
+          "schema": {
+            "type": "jsonschema",
+            "config": {
+              "default_from_schema": true,
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "one": {
+                    "type": "number",
+                    "default": 1
+                  }
+                }
+              },
+              "required": true,
+              "fillable": true
+            }
+          },
+          "text": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          }
+        },
+        "config": {
+          "sort_field": "id",
+          "sort_dir": "asc"
+        }
+      },
+      "items": {
+        "type": "regular",
+        "fields": {
+          "id": {
+            "type": "primary",
+            "config": {
+              "format": "integer",
+              "fillable": false,
+              "required": false
+            }
+          },
+          "title": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          }
+        },
+        "config": {
+          "sort_field": "id",
+          "sort_dir": "asc"
+        }
+      },
+      "media": {
+        "type": "system",
+        "fields": {
+          "id": {
+            "type": "primary",
+            "config": {
+              "format": "integer",
+              "fillable": false,
+              "required": false
+            }
+          },
+          "path": {
+            "type": "text",
+            "config": {
+              "required": true,
+              "fillable": true
+            }
+          },
+          "folder": {
+            "type": "boolean",
+            "config": {
+              "default_value": false,
+              "hidden": true,
+              "fillable": ["create"],
+              "required": false
+            }
+          },
+          "mime_type": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          },
+          "size": {
+            "type": "number",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          },
+          "scope": {
+            "type": "text",
+            "config": {
+              "hidden": true,
+              "fillable": ["create"],
+              "required": false
+            }
+          },
+          "etag": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          },
+          "modified_at": {
+            "type": "date",
+            "config": {
+              "type": "datetime",
+              "required": false,
+              "fillable": true
+            }
+          },
+          "reference": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          },
+          "entity_id": {
+            "type": "text",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          },
+          "metadata": {
+            "type": "json",
+            "config": {
+              "required": false,
+              "fillable": true
+            }
+          }
+        },
+        "config": {
+          "sort_field": "id",
+          "sort_dir": "asc"
+        }
+      }
+    },
+    "relations": {},
+    "indices": {
+      "idx_unique_media_path": {
+        "entity": "media",
+        "fields": ["path"],
+        "unique": true
+      },
+      "idx_media_reference": {
+        "entity": "media",
+        "fields": ["reference"],
+        "unique": false
+      },
+      "idx_media_entity_id": {
+        "entity": "media",
+        "fields": ["entity_id"],
+        "unique": false
+      }
+    }
+  },
+  "auth": {
+    "enabled": false,
+    "basepath": "/api/auth",
+    "entity_name": "users",
+    "allow_register": true,
+    "jwt": {
+      "secret": "",
+      "alg": "HS256",
+      "fields": ["id", "email", "role"]
+    },
+    "cookie": {
+      "path": "/",
+      "sameSite": "lax",
+      "secure": true,
+      "httpOnly": true,
+      "expires": 604800,
+      "partitioned": false,
+      "renew": true,
+      "pathSuccess": "/",
+      "pathLoggedOut": "/"
+    },
+    "strategies": {
+      "password": {
+        "type": "password",
+        "enabled": true,
+        "config": {
+          "hashing": "sha256"
+        }
+      }
+    },
+    "guard": {
+      "enabled": false
+    },
+    "roles": {}
+  },
+  "media": {
+    "enabled": false
+  },
+  "flows": {
+    "basepath": "/api/flows",
+    "flows": {}
+  }
+}

app/build.ts

@@ -85,7 +85,12 @@ async function buildApi() {
       sourcemap,
       watch,
       define,
-      entry: ["src/index.ts", "src/core/utils/index.ts", "src/plugins/index.ts"],
+      entry: [
+         "src/index.ts",
+         "src/core/utils/index.ts",
+         "src/plugins/index.ts",
+         "src/modes/index.ts",
+      ],
       outDir: "dist",
       external: [...external],
       metafile: true,

app/internal/docs.build-assets.ts

@@ -3,11 +3,14 @@ import { createApp } from "bknd/adapter/bun";
 async function generate() {
    console.info("Generating MCP documentation...");
    const app = await createApp({
+      connection: {
+         url: ":memory:",
+      },
       config: {
          server: {
             mcp: {
                enabled: true,
-               path: "/mcp",
+               path: "/mcp2",
             },
          },
          auth: {
@@ -25,9 +28,9 @@ async function generate() {
       },
    });
    await app.build();
+   await app.getMcpClient().ping();
 
-   const res = await app.server.request("/mcp?explain=1");
+   const { tools, resources } = app.mcp!.toJSON();
-   const { tools, resources } = await res.json();
    await Bun.write("../docs/mcp.json", JSON.stringify({ tools, resources }, null, 2));
 
    console.info("MCP documentation generated.");

app/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "sideEffects": false,
   "bin": "./dist/cli/index.js",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Lightweight Firebase/Supabase alternative built to run anywhere — incl. Next.js, React Router, Astro, Cloudflare, Bun, Node, AWS Lambda & more.",
   "homepage": "https://bknd.io",
   "repository": {
@@ -65,7 +65,7 @@
     "hono": "4.8.3",
     "json-schema-library": "10.0.0-rc7",
     "json-schema-to-ts": "^3.1.1",
-    "jsonv-ts": "0.8.4",
+    "jsonv-ts": "0.9.1",
     "kysely": "0.27.6",
     "lodash-es": "^4.17.21",
     "oauth4webapi": "^2.11.1",
@@ -180,6 +180,11 @@
       "import": "./dist/plugins/index.js",
       "require": "./dist/plugins/index.js"
     },
+    "./modes": {
+      "types": "./dist/types/modes/index.d.ts",
+      "import": "./dist/modes/index.js",
+      "require": "./dist/modes/index.js"
+    },
     "./adapter/sqlite": {
       "types": "./dist/types/adapter/sqlite/edge.d.ts",
       "import": {

app/src/Api.ts

@@ -40,6 +40,7 @@ export type ApiOptions = {
    data?: SubApiOptions<DataApiOptions>;
    auth?: SubApiOptions<AuthApiOptions>;
    media?: SubApiOptions<MediaApiOptions>;
+   credentials?: RequestCredentials;
 } & (
    | {
         token?: string;
@@ -67,7 +68,7 @@ export class Api {
    public auth!: AuthApi;
    public media!: MediaApi;
 
-   constructor(private options: ApiOptions = {}) {
+   constructor(public options: ApiOptions = {}) {
       // only mark verified if forced
       this.verified = options.verified === true;
 
@@ -129,29 +130,45 @@ export class Api {
       } else if (this.storage) {
          this.storage.getItem(this.tokenKey).then((token) => {
             this.token_transport = "header";
-            this.updateToken(token ? String(token) : undefined);
+            this.updateToken(token ? String(token) : undefined, {
+               verified: true,
+               trigger: false,
+            });
          });
       }
    }
 
+   /**
+    * Make storage async to allow async storages even if sync given
+    * @private
+    */
    private get storage() {
-      if (!this.options.storage) return null;
+      const storage = this.options.storage;
-      return {
+      return new Proxy(
-         getItem: async (key: string) => {
+         {},
-            return await this.options.storage!.getItem(key);
+         {
+            get(_, prop) {
+               return (...args: any[]) => {
+                  const response = storage ? storage[prop](...args) : undefined;
+                  if (response instanceof Promise) {
+                     return response;
+                  }
+                  return {
+                     // biome-ignore lint/suspicious/noThenProperty: it's a promise :)
+                     then: (fn) => fn(response),
+                  };
+               };
+            },
          },
-         setItem: async (key: string, value: string) => {
+      ) as any;
-            return await this.options.storage!.setItem(key, value);
-         },
-         removeItem: async (key: string) => {
-            return await this.options.storage!.removeItem(key);
-         },
-      };
    }
 
-   updateToken(token?: string, opts?: { rebuild?: boolean; trigger?: boolean }) {
+   updateToken(
+      token?: string,
+      opts?: { rebuild?: boolean; verified?: boolean; trigger?: boolean },
+   ) {
       this.token = token;
-      this.verified = false;
+      this.verified = opts?.verified === true;
 
       if (token) {
          this.user = omitKeys(decode(token).payload as any, ["iat", "iss", "exp"]) as any;
@@ -159,21 +176,22 @@ export class Api {
          this.user = undefined;
       }
 
+      const emit = () => {
+         if (opts?.trigger !== false) {
+            this.options.onAuthStateChange?.(this.getAuthState());
+         }
+      };
       if (this.storage) {
          const key = this.tokenKey;
 
          if (token) {
-            this.storage.setItem(key, token).then(() => {
+            this.storage.setItem(key, token).then(emit);
-               this.options.onAuthStateChange?.(this.getAuthState());
-            });
          } else {
-            this.storage.removeItem(key).then(() => {
+            this.storage.removeItem(key).then(emit);
-               this.options.onAuthStateChange?.(this.getAuthState());
-            });
          }
       } else {
          if (opts?.trigger !== false) {
-            this.options.onAuthStateChange?.(this.getAuthState());
+            emit();
          }
       }
 
@@ -182,6 +200,7 @@ export class Api {
 
    private markAuthVerified(verfied: boolean) {
       this.verified = verfied;
+      this.options.onAuthStateChange?.(this.getAuthState());
       return this;
    }
 
@@ -208,11 +227,6 @@ export class Api {
    }
 
    async verifyAuth() {
-      if (!this.token) {
-         this.markAuthVerified(false);
-         return;
-      }
-
       try {
          const { ok, data } = await this.auth.me();
          const user = data?.user;
@@ -221,10 +235,10 @@ export class Api {
          }
 
          this.user = user;
-         this.markAuthVerified(true);
       } catch (e) {
-         this.markAuthVerified(false);
          this.updateToken(undefined);
+      } finally {
+         this.markAuthVerified(true);
       }
    }
 
@@ -239,6 +253,7 @@ export class Api {
          headers: this.options.headers,
          token_transport: this.token_transport,
          verbose: this.options.verbose,
+         credentials: this.options.credentials,
       });
    }
 
@@ -257,10 +272,9 @@ export class Api {
       this.auth = new AuthApi(
          {
             ...baseParams,
-            credentials: this.options.storage ? "omit" : "include",
             ...this.options.auth,
-            onTokenUpdate: (token) => {
+            onTokenUpdate: (token, verified) => {
-               this.updateToken(token, { rebuild: true });
+               this.updateToken(token, { rebuild: true, verified, trigger: true });
                this.options.auth?.onTokenUpdate?.(token);
             },
          },

app/src/App.ts

@@ -245,9 +245,8 @@ export class App<
 
    get fetch(): Hono["fetch"] {
       if (!this.isBuilt()) {
-         throw new Error("App is not built yet, run build() first");
+         console.error("App is not built yet, run build() first");
       }
-
       return this.server.fetch as any;
    }
 
@@ -296,6 +295,7 @@ export class App<
       return this.module.auth.createUser(p);
    }
 
+   // @todo: potentially add option to clone the app, so that when used in listeners, it won't trigger listeners
    getApi(options?: LocalApiOptions) {
       const fetcher = this.server.request as typeof fetch;
       if (options && options instanceof Request) {
@@ -311,8 +311,9 @@ export class App<
          throw new Error("MCP is not enabled");
       }
 
+      const url = new URL(config.path, "http://localhost").toString();
       return new McpClient({
-         url: "http://localhost" + config.path,
+         url,
          fetch: this.server.request,
       });
    }
@@ -385,6 +386,7 @@ export class App<
             }
          }
       }
+      await this.options?.manager?.onModulesBuilt?.(ctx);
    }
 }
 

app/src/adapter/astro/astro.adapter.ts

@@ -8,12 +8,15 @@ export type AstroBkndConfig<Env = AstroEnv> = FrameworkBkndConfig<Env>;
 
 export async function getApp<Env = AstroEnv>(
    config: AstroBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = import.meta.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? import.meta.env);
+   return await createFrameworkApp(config, args);
 }
 
-export function serve<Env = AstroEnv>(config: AstroBkndConfig<Env> = {}, args: Env = {} as Env) {
+export function serve<Env = AstroEnv>(
+   config: AstroBkndConfig<Env> = {},
+   args: Env = import.meta.env as Env,
+) {
    return async (fnArgs: TAstro) => {
       return (await getApp(config, args)).fetch(fnArgs.request);
    };

app/src/adapter/bun/bun.adapter.ts

@@ -12,7 +12,7 @@ export type BunBkndConfig<Env = BunEnv> = RuntimeBkndConfig<Env> & Omit<ServeOpt
 
 export async function createApp<Env = BunEnv>(
    { distPath, serveStatic: _serveStatic, ...config }: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    const root = path.resolve(distPath ?? "./node_modules/bknd/dist", "static");
    registerLocalMediaAdapter();
@@ -26,18 +26,18 @@ export async function createApp<Env = BunEnv>(
             }),
          ...config,
       },
-      args ?? (process.env as Env),
+      args,
    );
 }
 
 export function createHandler<Env = BunEnv>(
    config: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    let app: App | undefined;
    return async (req: Request) => {
       if (!app) {
-         app = await createApp(config, args ?? (process.env as Env));
+         app = await createApp(config, args);
       }
       return app.fetch(req);
    };
@@ -54,9 +54,10 @@ export function serve<Env = BunEnv>(
       buildConfig,
       adminOptions,
       serveStatic,
+      beforeBuild,
       ...serveOptions
    }: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    Bun.serve({
       ...serveOptions,
@@ -71,6 +72,7 @@ export function serve<Env = BunEnv>(
             adminOptions,
             distPath,
             serveStatic,
+            beforeBuild,
          },
          args,
       ),

app/src/adapter/bun/index.ts

@@ -1,3 +1,11 @@
 export * from "./bun.adapter";
 export * from "../node/storage";
 export * from "./connection/BunSqliteConnection";
+
+export async function writer(path: string, content: string) {
+   await Bun.write(path, content);
+}
+
+export async function reader(path: string) {
+   return await Bun.file(path).text();
+}

app/src/adapter/cloudflare/cloudflare-workers.adapter.spec.ts

@@ -5,8 +5,8 @@ import { adapterTestSuite } from "adapter/adapter-test-suite";
 import { bunTestRunner } from "adapter/bun/test";
 import { type CloudflareBkndConfig, createApp } from "./cloudflare-workers.adapter";
 
-/* beforeAll(disableConsoleLog);
+beforeAll(disableConsoleLog);
-afterAll(enableConsoleLog); */
+afterAll(enableConsoleLog);
 
 describe("cf adapter", () => {
    const DB_URL = ":memory:";

app/src/adapter/cloudflare/cloudflare-workers.adapter.ts

@@ -37,19 +37,19 @@ export async function createApp<Env extends CloudflareEnv = CloudflareEnv>(
    config: CloudflareBkndConfig<Env> = {},
    ctx: Partial<CloudflareContext<Env>> = {},
 ) {
-   const appConfig = await makeConfig(
+   const appConfig = await makeConfig(config, ctx);
+   return await createRuntimeApp<Env>(
       {
-         ...config,
+         ...appConfig,
          onBuilt: async (app) => {
             if (ctx.ctx) {
                registerAsyncsExecutionContext(app, ctx?.ctx);
             }
-            await config.onBuilt?.(app);
+            await appConfig.onBuilt?.(app);
          },
       },
-      ctx,
+      ctx?.env,
    );
-   return await createRuntimeApp<Env>(appConfig, ctx?.env);
 }
 
 // compatiblity

app/src/adapter/cloudflare/storage/StorageR2Adapter.ts

@@ -49,6 +49,8 @@ export function registerMedia(
  * @todo: add tests (bun tests won't work, need node native tests)
  */
 export class StorageR2Adapter extends StorageAdapter {
+   public keyPrefix: string = "";
+
    constructor(private readonly bucket: R2Bucket) {
       super();
    }
@@ -175,6 +177,9 @@ export class StorageR2Adapter extends StorageAdapter {
    }
 
    protected getKey(key: string) {
+      if (this.keyPrefix.length > 0) {
+         return `${this.keyPrefix}/${key}`.replace(/^\/\//, "/");
+      }
       return key;
    }
 

app/src/adapter/index.ts

@@ -6,18 +6,23 @@ import {
    guessMimeType,
    type MaybePromise,
    registries as $registries,
+   type Merge,
 } from "bknd";
 import { $console } from "bknd/utils";
 import type { Context, MiddlewareHandler, Next } from "hono";
 import type { AdminControllerOptions } from "modules/server/AdminController";
 import type { Manifest } from "vite";
 
-export type BkndConfig<Args = any> = CreateAppConfig & {
+export type BkndConfig<Args = any, Additional = {}> = Merge<
-   app?: Omit<BkndConfig, "app"> | ((args: Args) => MaybePromise<Omit<BkndConfig<Args>, "app">>);
+   CreateAppConfig & {
-   onBuilt?: (app: App) => MaybePromise<void>;
+      app?:
-   beforeBuild?: (app?: App, registries?: typeof $registries) => MaybePromise<void>;
+         | Merge<Omit<BkndConfig, "app"> & Additional>
-   buildConfig?: Parameters<App["build"]>[0];
+         | ((args: Args) => MaybePromise<Merge<Omit<BkndConfig<Args>, "app"> & Additional>>);
-};
+      onBuilt?: (app: App) => MaybePromise<void>;
+      beforeBuild?: (app?: App, registries?: typeof $registries) => MaybePromise<void>;
+      buildConfig?: Parameters<App["build"]>[0];
+   } & Additional
+>;
 
 export type FrameworkBkndConfig<Args = any> = BkndConfig<Args>;
 
@@ -51,11 +56,10 @@ export async function makeConfig<Args = DefaultArgs>(
    return { ...rest, ...additionalConfig };
 }
 
-// a map that contains all apps by id
 export async function createAdapterApp<Config extends BkndConfig = BkndConfig, Args = DefaultArgs>(
    config: Config = {} as Config,
    args?: Args,
-): Promise<App> {
+): Promise<{ app: App; config: BkndConfig<Args> }> {
    await config.beforeBuild?.(undefined, $registries);
 
    const appConfig = await makeConfig(config, args);
@@ -65,34 +69,37 @@ export async function createAdapterApp<Config extends BkndConfig = BkndConfig, A
          connection = config.connection;
       } else {
          const sqlite = (await import("bknd/adapter/sqlite")).sqlite;
-         const conf = appConfig.connection ?? { url: ":memory:" };
+         const conf = appConfig.connection ?? { url: "file:data.db" };
          connection = sqlite(conf) as any;
          $console.info(`Using ${connection!.name} connection`, conf.url);
       }
       appConfig.connection = connection;
    }
 
-   return App.create(appConfig);
+   return {
+      app: App.create(appConfig),
+      config: appConfig,
+   };
 }
 
 export async function createFrameworkApp<Args = DefaultArgs>(
    config: FrameworkBkndConfig = {},
    args?: Args,
 ): Promise<App> {
-   const app = await createAdapterApp(config, args);
+   const { app, config: appConfig } = await createAdapterApp(config, args);
 
    if (!app.isBuilt()) {
       if (config.onBuilt) {
          app.emgr.onEvent(
             App.Events.AppBuiltEvent,
             async () => {
-               await config.onBuilt?.(app);
+               await appConfig.onBuilt?.(app);
             },
             "sync",
          );
       }
 
-      await config.beforeBuild?.(app, $registries);
+      await appConfig.beforeBuild?.(app, $registries);
       await app.build(config.buildConfig);
    }
 
@@ -103,7 +110,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
    { serveStatic, adminOptions, ...config }: RuntimeBkndConfig<Args> = {},
    args?: Args,
 ): Promise<App> {
-   const app = await createAdapterApp(config, args);
+   const { app, config: appConfig } = await createAdapterApp(config, args);
 
    if (!app.isBuilt()) {
       app.emgr.onEvent(
@@ -116,7 +123,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
                app.modules.server.get(path, handler);
             }
 
-            await config.onBuilt?.(app);
+            await appConfig.onBuilt?.(app);
             if (adminOptions !== false) {
                app.registerAdminController(adminOptions);
             }
@@ -124,7 +131,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
          "sync",
       );
 
-      await config.beforeBuild?.(app, $registries);
+      await appConfig.beforeBuild?.(app, $registries);
       await app.build(config.buildConfig);
    }
 
@@ -147,23 +154,32 @@ export async function createRuntimeApp<Args = DefaultArgs>(
  * });
  * ```
  */
-export function serveStaticViaImport(opts?: { manifest?: Manifest }) {
+export function serveStaticViaImport(opts?: {
+   manifest?: Manifest;
+   appendRaw?: boolean;
+   package?: string;
+}) {
    let files: string[] | undefined;
+   const pkg = opts?.package ?? "bknd";
 
    // @ts-ignore
    return async (c: Context, next: Next) => {
       if (!files) {
          const manifest =
             opts?.manifest ||
-            ((await import("bknd/dist/manifest.json", { with: { type: "json" } }))
+            ((
-               .default as Manifest);
+               await import(/* @vite-ignore */ `${pkg}/dist/manifest.json`, {
+                  with: { type: "json" },
+               })
+            ).default as Manifest);
          files = Object.values(manifest).flatMap((asset) => [asset.file, ...(asset.css || [])]);
       }
 
       const path = c.req.path.substring(1);
       if (files.includes(path)) {
          try {
-            const content = await import(/* @vite-ignore */ `bknd/static/${path}?raw`, {
+            const url = `${pkg}/static/${path}${opts?.appendRaw ? "?raw" : ""}`;
+            const content = await import(/* @vite-ignore */ url, {
                with: { type: "text" },
             }).then((m) => m.default);
 
@@ -176,7 +192,7 @@ export function serveStaticViaImport(opts?: { manifest?: Manifest }) {
                });
             }
          } catch (e) {
-            console.error("Error serving static file:", e);
+            console.error(`Error serving static file "${path}":`, String(e));
             return c.text("File not found", 404);
          }
       }

app/src/adapter/nextjs/nextjs.adapter.ts

@@ -9,9 +9,9 @@ export type NextjsBkndConfig<Env = NextjsEnv> = FrameworkBkndConfig<Env> & {
 
 export async function getApp<Env = NextjsEnv>(
    config: NextjsBkndConfig<Env>,
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? (process.env as Env));
+   return await createFrameworkApp(config, args);
 }
 
 function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequest"]) {
@@ -39,7 +39,7 @@ function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequ
 
 export function serve<Env = NextjsEnv>(
    { cleanRequest, ...config }: NextjsBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    return async (req: Request) => {
       const app = await getApp(config, args);

app/src/adapter/node/index.ts

@@ -1,3 +1,13 @@
+import { readFile, writeFile } from "node:fs/promises";
+
 export * from "./node.adapter";
 export * from "./storage";
 export * from "./connection/NodeSqliteConnection";
+
+export async function writer(path: string, content: string) {
+   await writeFile(path, content);
+}
+
+export async function reader(path: string) {
+   return await readFile(path, "utf-8");
+}

app/src/adapter/node/node.adapter.ts

@@ -17,7 +17,7 @@ export type NodeBkndConfig<Env = NodeEnv> = RuntimeBkndConfig<Env> & {
 
 export async function createApp<Env = NodeEnv>(
    { distPath, relativeDistPath, ...config }: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    const root = path.relative(
       process.cwd(),
@@ -33,19 +33,18 @@ export async function createApp<Env = NodeEnv>(
          serveStatic: serveStatic({ root }),
          ...config,
       },
-      // @ts-ignore
+      args,
-      args ?? { env: process.env },
    );
 }
 
 export function createHandler<Env = NodeEnv>(
    config: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    let app: App | undefined;
    return async (req: Request) => {
       if (!app) {
-         app = await createApp(config, args ?? (process.env as Env));
+         app = await createApp(config, args);
       }
       return app.fetch(req);
    };
@@ -53,7 +52,7 @@ export function createHandler<Env = NodeEnv>(
 
 export function serve<Env = NodeEnv>(
    { port = $config.server.default_port, hostname, listener, ...config }: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    honoServe(
       {

app/src/adapter/react-router/react-router.adapter.ts

@@ -8,14 +8,14 @@ export type ReactRouterBkndConfig<Env = ReactRouterEnv> = FrameworkBkndConfig<En
 
 export async function getApp<Env = ReactRouterEnv>(
    config: ReactRouterBkndConfig<Env>,
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? process.env);
+   return await createFrameworkApp(config, args);
 }
 
 export function serve<Env = ReactRouterEnv>(
    config: ReactRouterBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    return async (fnArgs: ReactRouterFunctionArgs) => {
       return (await getApp(config, args)).fetch(fnArgs.request);

app/src/auth/AppAuth.ts

@@ -2,7 +2,7 @@ import type { DB, PrimaryFieldType } from "bknd";
 import * as AuthPermissions from "auth/auth-permissions";
 import type { AuthStrategy } from "auth/authenticate/strategies/Strategy";
 import type { PasswordStrategy } from "auth/authenticate/strategies/PasswordStrategy";
-import { $console, secureRandomString, transformObject } from "bknd/utils";
+import { $console, secureRandomString, transformObject, pickKeys } from "bknd/utils";
 import type { Entity, EntityManager } from "data/entities";
 import { em, entity, enumm, type FieldSchema } from "data/prototype";
 import { Module } from "modules/Module";
@@ -61,7 +61,7 @@ export class AppAuth extends Module<AppAuthSchema> {
 
       // register roles
       const roles = transformObject(this.config.roles ?? {}, (role, name) => {
-         return Role.create({ name, ...role });
+         return Role.create(name, role);
       });
       this.ctx.guard.setRoles(Object.values(roles));
       this.ctx.guard.setConfig(this.config.guard ?? {});
@@ -113,6 +113,19 @@ export class AppAuth extends Module<AppAuthSchema> {
       return authConfigSchema;
    }
 
+   getGuardContextSchema() {
+      const userschema = this.getUsersEntity().toSchema() as any;
+      return {
+         type: "object",
+         properties: {
+            user: {
+               type: "object",
+               properties: pickKeys(userschema.properties, this.config.jwt.fields as any),
+            },
+         },
+      };
+   }
+
    get authenticator(): Authenticator {
       this.throwIfNotBuilt();
       return this._authenticator!;
@@ -210,10 +223,12 @@ export class AppAuth extends Module<AppAuthSchema> {
       }
 
       const strategies = this.authenticator.getStrategies();
+      const roles = Object.fromEntries(this.ctx.guard.getRoles().map((r) => [r.name, r.toJSON()]));
 
       return {
          ...this.config,
          ...this.authenticator.toJSON(secrets),
+         roles,
          strategies: transformObject(strategies, (strategy) => ({
             enabled: this.isStrategyEnabled(strategy),
             ...strategy.toJSON(secrets),

app/src/auth/api/AuthApi.ts

@@ -4,7 +4,7 @@ import type { AuthResponse, SafeUser, AuthStrategy } from "bknd";
 import { type BaseModuleApiOptions, ModuleApi } from "modules/ModuleApi";
 
 export type AuthApiOptions = BaseModuleApiOptions & {
-   onTokenUpdate?: (token?: string) => void | Promise<void>;
+   onTokenUpdate?: (token?: string, verified?: boolean) => void | Promise<void>;
    credentials?: "include" | "same-origin" | "omit";
 };
 
@@ -17,23 +17,19 @@ export class AuthApi extends ModuleApi<AuthApiOptions> {
    }
 
    async login(strategy: string, input: any) {
-      const res = await this.post<AuthResponse>([strategy, "login"], input, {
+      const res = await this.post<AuthResponse>([strategy, "login"], input);
-         credentials: this.options.credentials,
-      });
 
       if (res.ok && res.body.token) {
-         await this.options.onTokenUpdate?.(res.body.token);
+         await this.options.onTokenUpdate?.(res.body.token, true);
       }
       return res;
    }
 
    async register(strategy: string, input: any) {
-      const res = await this.post<AuthResponse>([strategy, "register"], input, {
+      const res = await this.post<AuthResponse>([strategy, "register"], input);
-         credentials: this.options.credentials,
-      });
 
       if (res.ok && res.body.token) {
-         await this.options.onTokenUpdate?.(res.body.token);
+         await this.options.onTokenUpdate?.(res.body.token, true);
       }
       return res;
    }
@@ -71,6 +67,11 @@ export class AuthApi extends ModuleApi<AuthApiOptions> {
    }
 
    async logout() {
-      await this.options.onTokenUpdate?.(undefined);
+      return this.get(["logout"], undefined, {
+         headers: {
+            // this way bknd detects a json request and doesn't redirect back
+            Accept: "application/json",
+         },
+      }).then(() => this.options.onTokenUpdate?.(undefined, true));
    }
 }

app/src/auth/api/AuthController.ts

@@ -60,7 +60,10 @@ export class AuthController extends Controller {
       if (create) {
          hono.post(
             "/create",
-            permission([AuthPermissions.createUser, DataPermissions.entityCreate]),
+            permission(AuthPermissions.createUser, {}),
+            permission(DataPermissions.entityCreate, {
+               context: (c) => ({ entity: this.auth.config.entity_name }),
+            }),
             describeRoute({
                summary: "Create a new user",
                tags: ["auth"],
@@ -223,7 +226,6 @@ export class AuthController extends Controller {
 
       const roles = Object.keys(this.auth.config.roles ?? {});
       mcp.tool(
-         // @todo: needs permission
          "auth_user_create",
          {
             description: "Create a new user",
@@ -238,14 +240,13 @@ export class AuthController extends Controller {
             }),
          },
          async (params, c) => {
-            await c.context.ctx().helper.throwUnlessGranted(AuthPermissions.createUser, c);
+            await c.context.ctx().helper.granted(c, AuthPermissions.createUser);
 
             return c.json(await this.auth.createUser(params));
          },
       );
 
       mcp.tool(
-         // @todo: needs permission
          "auth_user_token",
          {
             description: "Get a user token",
@@ -255,7 +256,7 @@ export class AuthController extends Controller {
             }),
          },
          async (params, c) => {
-            await c.context.ctx().helper.throwUnlessGranted(AuthPermissions.createToken, c);
+            await c.context.ctx().helper.granted(c, AuthPermissions.createToken);
 
             const user = await getUser(params);
             return c.json({ user, token: await this.auth.authenticator.jwt(user) });
@@ -263,7 +264,6 @@ export class AuthController extends Controller {
       );
 
       mcp.tool(
-         // @todo: needs permission
          "auth_user_password_change",
          {
             description: "Change a user's password",
@@ -274,7 +274,7 @@ export class AuthController extends Controller {
             }),
          },
          async (params, c) => {
-            await c.context.ctx().helper.throwUnlessGranted(AuthPermissions.changePassword, c);
+            await c.context.ctx().helper.granted(c, AuthPermissions.changePassword);
 
             const user = await getUser(params);
             if (!(await this.auth.changePassword(user.id, params.password))) {
@@ -285,7 +285,6 @@ export class AuthController extends Controller {
       );
 
       mcp.tool(
-         // @todo: needs permission
          "auth_user_password_test",
          {
             description: "Test a user's password",
@@ -295,7 +294,7 @@ export class AuthController extends Controller {
             }),
          },
          async (params, c) => {
-            await c.context.ctx().helper.throwUnlessGranted(AuthPermissions.testPassword, c);
+            await c.context.ctx().helper.granted(c, AuthPermissions.testPassword);
 
             const pw = this.auth.authenticator.strategy("password") as PasswordStrategy;
             const controller = pw.getController(this.auth.authenticator);

app/src/auth/auth-permissions.ts

@@ -1,4 +1,4 @@
-import { Permission } from "core/security/Permission";
+import { Permission } from "auth/authorize/Permission";
 
 export const createUser = new Permission("auth.user.create");
 //export const updateUser = new Permission("auth.user.update");

app/src/auth/auth-schema.ts

@@ -1,6 +1,7 @@
 import { cookieConfig, jwtConfig } from "auth/authenticate/Authenticator";
 import { CustomOAuthStrategy, OAuthStrategy, PasswordStrategy } from "auth/authenticate/strategies";
-import { objectTransform, s } from "bknd/utils";
+import { roleSchema } from "auth/authorize/Role";
+import { objectTransform, omitKeys, pick, s } from "bknd/utils";
 import { $object, $record } from "modules/mcp";
 
 export const Strategies = {
@@ -40,11 +41,8 @@ export type AppAuthCustomOAuthStrategy = s.Static<typeof STRATEGIES.custom_oauth
 const guardConfigSchema = s.object({
    enabled: s.boolean({ default: false }).optional(),
 });
-export const guardRoleSchema = s.strictObject({
+
-   permissions: s.array(s.string()).optional(),
+export const guardRoleSchema = roleSchema;
-   is_default: s.boolean().optional(),
-   implicit_allow: s.boolean().optional(),
-});
 
 export const authConfigSchema = $object(
    "config_auth",

app/src/auth/authenticate/Authenticator.ts

@@ -6,10 +6,8 @@ import { deleteCookie, getSignedCookie, setSignedCookie } from "hono/cookie";
 import { sign, verify } from "hono/jwt";
 import { type CookieOptions, serializeSigned } from "hono/utils/cookie";
 import type { ServerEnv } from "modules/Controller";
-import { pick } from "lodash-es";
 import { InvalidConditionsException } from "auth/errors";
-import { s, parse, secret, runtimeSupports, truncate, $console } from "bknd/utils";
+import { s, parse, secret, runtimeSupports, truncate, $console, pickKeys } from "bknd/utils";
-import { $object } from "modules/mcp";
 import type { AuthStrategy } from "./strategies/Strategy";
 
 type Input = any; // workaround
@@ -44,6 +42,7 @@ export interface UserPool {
 const defaultCookieExpires = 60 * 60 * 24 * 7; // 1 week in seconds
 export const cookieConfig = s
    .strictObject({
+      domain: s.string().optional(),
       path: s.string({ default: "/" }),
       sameSite: s.string({ enum: ["strict", "lax", "none"], default: "lax" }),
       secure: s.boolean({ default: true }),
@@ -229,7 +228,7 @@ export class Authenticator<
 
    // @todo: add jwt tests
    async jwt(_user: SafeUser | ProfileExchange): Promise<string> {
-      const user = pick(_user, this.config.jwt.fields);
+      const user = pickKeys(_user, this.config.jwt.fields as any);
 
       const payload: JWTPayload = {
          ...user,
@@ -255,7 +254,7 @@ export class Authenticator<
    }
 
    async safeAuthResponse(_user: User): Promise<AuthResponse> {
-      const user = pick(_user, this.config.jwt.fields) as SafeUser;
+      const user = pickKeys(_user, this.config.jwt.fields as any) as SafeUser;
       return {
          user,
          token: await this.jwt(user),
@@ -290,6 +289,7 @@ export class Authenticator<
 
       return {
          ...cookieConfig,
+         domain: cookieConfig.domain ?? undefined,
          expires: new Date(Date.now() + expires * 1000),
       };
    }
@@ -327,6 +327,31 @@ export class Authenticator<
       await setSignedCookie(c, "auth", token, secret, this.cookieOptions);
    }
 
+   async getAuthCookieHeader(token: string, headers = new Headers()) {
+      const c = {
+         header: (key: string, value: string) => {
+            headers.set(key, value);
+         },
+      };
+      await this.setAuthCookie(c as any, token);
+      return headers;
+   }
+
+   async removeAuthCookieHeader(headers = new Headers()) {
+      const c = {
+         header: (key: string, value: string) => {
+            headers.set(key, value);
+         },
+         req: {
+            raw: {
+               headers,
+            },
+         },
+      };
+      this.deleteAuthCookie(c as any);
+      return headers;
+   }
+
    async unsafeGetAuthCookie(token: string): Promise<string | undefined> {
       // this works for as long as cookieOptions.prefix is not set
       return serializeSigned("auth", token, this.config.jwt.secret, this.cookieOptions);
@@ -354,7 +379,10 @@ export class Authenticator<
 
    // @todo: move this to a server helper
    isJsonRequest(c: Context): boolean {
-      return c.req.header("Content-Type") === "application/json";
+      return (
+         c.req.header("Content-Type") === "application/json" ||
+         c.req.header("Accept") === "application/json"
+      );
    }
 
    async getBody(c: Context) {

app/src/auth/authenticate/strategies/PasswordStrategy.ts

@@ -1,7 +1,7 @@
 import type { User } from "bknd";
 import type { Authenticator } from "auth/authenticate/Authenticator";
 import { InvalidCredentialsException } from "auth/errors";
-import { hash, $console, s, parse, jsc } from "bknd/utils";
+import { hash, $console, s, parse, jsc, describeRoute } from "bknd/utils";
 import { Hono } from "hono";
 import { compare as bcryptCompare, genSalt as bcryptGenSalt, hash as bcryptHash } from "bcryptjs";
 import { AuthStrategy } from "./Strategy";
@@ -84,51 +84,67 @@ export class PasswordStrategy extends AuthStrategy<typeof schema> {
       });
       const payloadSchema = this.getPayloadSchema();
 
-      hono.post("/login", jsc("query", redirectQuerySchema), async (c) => {
+      hono.post(
-         try {
+         "/login",
-            const body = parse(payloadSchema, await authenticator.getBody(c), {
+         describeRoute({
-               onError: (errors) => {
+            summary: "Login with email and password",
-                  $console.error("Invalid login payload", [...errors]);
+            tags: ["auth"],
-                  throw new InvalidCredentialsException();
+         }),
-               },
+         jsc("query", redirectQuerySchema),
-            });
+         async (c) => {
-            const { redirect } = c.req.valid("query");
+            try {
-
+               const body = parse(payloadSchema, await authenticator.getBody(c), {
-            return await authenticator.resolveLogin(c, this, body, this.verify(body.password), {
-               redirect,
-            });
-         } catch (e) {
-            return authenticator.respondWithError(c, e as any);
-         }
-      });
-
-      hono.post("/register", jsc("query", redirectQuerySchema), async (c) => {
-         try {
-            const { redirect } = c.req.valid("query");
-            const { password, email, ...body } = parse(
-               payloadSchema,
-               await authenticator.getBody(c),
-               {
                   onError: (errors) => {
-                     $console.error("Invalid register payload", [...errors]);
+                     $console.error("Invalid login payload", [...errors]);
-                     new InvalidCredentialsException();
+                     throw new InvalidCredentialsException();
                   },
-               },
+               });
-            );
+               const { redirect } = c.req.valid("query");
 
-            const profile = {
+               return await authenticator.resolveLogin(c, this, body, this.verify(body.password), {
-               ...body,
+                  redirect,
-               email,
+               });
-               strategy_value: await this.hash(password),
+            } catch (e) {
-            };
+               return authenticator.respondWithError(c, e as any);
+            }
+         },
+      );
 
-            return await authenticator.resolveRegister(c, this, profile, async () => void 0, {
+      hono.post(
-               redirect,
+         "/register",
-            });
+         describeRoute({
-         } catch (e) {
+            summary: "Register a new user with email and password",
-            return authenticator.respondWithError(c, e as any);
+            tags: ["auth"],
-         }
+         }),
-      });
+         jsc("query", redirectQuerySchema),
+         async (c) => {
+            try {
+               const { redirect } = c.req.valid("query");
+               const { password, email, ...body } = parse(
+                  payloadSchema,
+                  await authenticator.getBody(c),
+                  {
+                     onError: (errors) => {
+                        $console.error("Invalid register payload", [...errors]);
+                        new InvalidCredentialsException();
+                     },
+                  },
+               );
+
+               const profile = {
+                  ...body,
+                  email,
+                  strategy_value: await this.hash(password),
+               };
+
+               return await authenticator.resolveRegister(c, this, profile, async () => void 0, {
+                  redirect,
+               });
+            } catch (e) {
+               return authenticator.respondWithError(c, e as any);
+            }
+         },
+      );
 
       return hono;
    }

app/src/auth/authorize/Guard.ts

@@ -1,9 +1,12 @@
 import { Exception } from "core/errors";
-import { $console, objectTransform } from "bknd/utils";
+import { $console, mergeObject, type s } from "bknd/utils";
-import { Permission } from "core/security/Permission";
+import type { Permission, PermissionContext } from "auth/authorize/Permission";
 import type { Context } from "hono";
 import type { ServerEnv } from "modules/Controller";
-import { Role } from "./Role";
+import type { Role } from "./Role";
+import { HttpStatus } from "bknd/utils";
+import type { Policy, PolicySchema } from "./Policy";
+import { convert, type ObjectQuery } from "core/object/query/object-query";
 
 export type GuardUserContext = {
    role?: string | null;
@@ -12,41 +15,43 @@ export type GuardUserContext = {
 
 export type GuardConfig = {
    enabled?: boolean;
+   context?: object;
 };
 export type GuardContext = Context<ServerEnv> | GuardUserContext;
 
-export class Guard {
+export class GuardPermissionsException extends Exception {
-   permissions: Permission[];
+   override name = "PermissionsException";
-   roles?: Role[];
+   override code = HttpStatus.FORBIDDEN;
-   config?: GuardConfig;
 
-   constructor(permissions: Permission[] = [], roles: Role[] = [], config?: GuardConfig) {
+   constructor(
+      public permission: Permission,
+      public policy?: Policy,
+      public description?: string,
+   ) {
+      super(`Permission "${permission.name}" not granted`);
+   }
+
+   override toJSON(): any {
+      return {
+         ...super.toJSON(),
+         description: this.description,
+         permission: this.permission.name,
+         policy: this.policy?.toJSON(),
+      };
+   }
+}
+
+export class Guard {
+   constructor(
+      public permissions: Permission<any, any, any, any>[] = [],
+      public roles: Role[] = [],
+      public config?: GuardConfig,
+   ) {
       this.permissions = permissions;
       this.roles = roles;
       this.config = config;
    }
 
-   static create(
-      permissionNames: string[],
-      roles?: Record<
-         string,
-         {
-            permissions?: string[];
-            is_default?: boolean;
-            implicit_allow?: boolean;
-         }
-      >,
-      config?: GuardConfig,
-   ) {
-      const _roles = roles
-         ? objectTransform(roles, ({ permissions = [], is_default, implicit_allow }, name) => {
-              return Role.createWithPermissionNames(name, permissions, is_default, implicit_allow);
-           })
-         : {};
-      const _permissions = permissionNames.map((name) => new Permission(name));
-      return new Guard(_permissions, Object.values(_roles), config);
-   }
-
    getPermissionNames(): string[] {
       return this.permissions.map((permission) => permission.name);
    }
@@ -73,7 +78,7 @@ export class Guard {
       return this;
    }
 
-   registerPermission(permission: Permission) {
+   registerPermission(permission: Permission<any, any, any, any>) {
       if (this.permissions.find((p) => p.name === permission.name)) {
          throw new Error(`Permission ${permission.name} already exists`);
       }
@@ -82,9 +87,13 @@ export class Guard {
       return this;
    }
 
-   registerPermissions(permissions: Record<string, Permission>);
+   registerPermissions(permissions: Record<string, Permission<any, any, any, any>>);
-   registerPermissions(permissions: Permission[]);
+   registerPermissions(permissions: Permission<any, any, any, any>[]);
-   registerPermissions(permissions: Permission[] | Record<string, Permission>) {
+   registerPermissions(
+      permissions:
+         | Permission<any, any, any, any>[]
+         | Record<string, Permission<any, any, any, any>>,
+   ) {
       const p = Array.isArray(permissions) ? permissions : Object.values(permissions);
 
       for (const permission of p) {
@@ -117,56 +126,216 @@ export class Guard {
       return this.config?.enabled === true;
    }
 
-   hasPermission(permission: Permission, user?: GuardUserContext): boolean;
+   private collect(permission: Permission, c: GuardContext | undefined, context: any) {
-   hasPermission(name: string, user?: GuardUserContext): boolean;
-   hasPermission(permissionOrName: Permission | string, user?: GuardUserContext): boolean {
-      if (!this.isEnabled()) {
-         return true;
-      }
-
-      const name = typeof permissionOrName === "string" ? permissionOrName : permissionOrName.name;
-      $console.debug("guard: checking permission", {
-         name,
-         user: { id: user?.id, role: user?.role },
-      });
-      const exists = this.permissionExists(name);
-      if (!exists) {
-         throw new Error(`Permission ${name} does not exist`);
-      }
-
-      const role = this.getUserRole(user);
-
-      if (!role) {
-         $console.debug("guard: user has no role, denying");
-         return false;
-      } else if (role.implicit_allow === true) {
-         $console.debug(`guard: role "${role.name}" has implicit allow, allowing`);
-         return true;
-      }
-
-      const rolePermission = role.permissions.find(
-         (rolePermission) => rolePermission.permission.name === name,
-      );
-
-      $console.debug("guard: rolePermission, allowing?", {
-         permission: name,
-         role: role.name,
-         allowing: !!rolePermission,
-      });
-      return !!rolePermission;
-   }
-
-   granted(permission: Permission | string, c?: GuardContext): boolean {
       const user = c && "get" in c ? c.get("auth")?.user : c;
-      return this.hasPermission(permission as any, user);
+      const ctx = {
+         ...((context ?? {}) as any),
+         ...this.config?.context,
+         user,
+      };
+      const exists = this.permissionExists(permission.name);
+      const role = this.getUserRole(user);
+      const rolePermission = role?.permissions.find(
+         (rolePermission) => rolePermission.permission.name === permission.name,
+      );
+      return {
+         ctx,
+         user,
+         exists,
+         role,
+         rolePermission,
+      };
    }
 
-   throwUnlessGranted(permission: Permission | string, c: GuardContext) {
+   granted<P extends Permission<any, any, any, any>>(
-      if (!this.granted(permission, c)) {
+      permission: P,
-         throw new Exception(
+      c: GuardContext,
-            `Permission "${typeof permission === "string" ? permission : permission.name}" not granted`,
+      context: PermissionContext<P>,
-            403,
+   ): void;
+   granted<P extends Permission<any, any, undefined, any>>(permission: P, c: GuardContext): void;
+   granted<P extends Permission<any, any, any, any>>(
+      permission: P,
+      c: GuardContext,
+      context?: PermissionContext<P>,
+   ): void {
+      if (!this.isEnabled()) {
+         return;
+      }
+      const { ctx: _ctx, exists, role, rolePermission } = this.collect(permission, c, context);
+
+      // validate context
+      let ctx = Object.assign({}, _ctx);
+      if (permission.context) {
+         ctx = permission.parseContext(ctx);
+      }
+
+      $console.debug("guard: checking permission", {
+         name: permission.name,
+         context: ctx,
+      });
+      if (!exists) {
+         throw new GuardPermissionsException(
+            permission,
+            undefined,
+            `Permission ${permission.name} does not exist`,
          );
       }
+
+      if (!role) {
+         throw new GuardPermissionsException(permission, undefined, "User has no role");
+      }
+
+      if (!rolePermission) {
+         if (role.implicit_allow === true) {
+            $console.debug(`guard: role "${role.name}" has implicit allow, allowing`);
+            return;
+         }
+
+         throw new GuardPermissionsException(
+            permission,
+            undefined,
+            `Role "${role.name}" does not have required permission`,
+         );
+      }
+
+      if (rolePermission?.policies.length > 0) {
+         $console.debug("guard: rolePermission has policies, checking");
+
+         // set the default effect of the role permission
+         let allowed = rolePermission.effect === "allow";
+         for (const policy of rolePermission.policies) {
+            $console.debug("guard: checking policy", { policy: policy.toJSON(), ctx });
+            // skip filter policies
+            if (policy.content.effect === "filter") continue;
+
+            // if condition is met, check the effect
+            const meets = policy.meetsCondition(ctx);
+            if (meets) {
+               $console.debug("guard: policy meets condition");
+               // if deny, then break early
+               if (policy.content.effect === "deny") {
+                  $console.debug("guard: policy is deny, setting allowed to false");
+                  allowed = false;
+                  break;
+
+                  // if allow, set allow but continue checking
+               } else if (policy.content.effect === "allow") {
+                  allowed = true;
+               }
+            } else {
+               $console.debug("guard: policy does not meet condition");
+            }
+         }
+
+         if (!allowed) {
+            throw new GuardPermissionsException(permission, undefined, "Policy condition unmet");
+         }
+      }
+
+      $console.debug("guard allowing", {
+         permission: permission.name,
+         role: role.name,
+      });
+   }
+
+   filters<P extends Permission<any, any, any, any>>(
+      permission: P,
+      c: GuardContext,
+      context: PermissionContext<P>,
+   );
+   filters<P extends Permission<any, any, undefined, any>>(permission: P, c: GuardContext);
+   filters<P extends Permission<any, any, any, any>>(
+      permission: P,
+      c: GuardContext,
+      context?: PermissionContext<P>,
+   ) {
+      if (!permission.isFilterable()) {
+         throw new GuardPermissionsException(permission, undefined, "Permission is not filterable");
+      }
+
+      const {
+         ctx: _ctx,
+         exists,
+         role,
+         user,
+         rolePermission,
+      } = this.collect(permission, c, context);
+
+      // validate context
+      let ctx = Object.assign(
+         {
+            user,
+         },
+         _ctx,
+      );
+
+      if (permission.context) {
+         ctx = permission.parseContext(ctx, {
+            coerceDropUnknown: false,
+         });
+      }
+
+      const filters: PolicySchema["filter"][] = [];
+      const policies: Policy[] = [];
+      if (exists && role && rolePermission && rolePermission.policies.length > 0) {
+         for (const policy of rolePermission.policies) {
+            if (policy.content.effect === "filter") {
+               const meets = policy.meetsCondition(ctx);
+               if (meets) {
+                  policies.push(policy);
+                  filters.push(policy.getReplacedFilter(ctx));
+               }
+            }
+         }
+      }
+
+      const filter = filters.length > 0 ? mergeObject({}, ...filters) : undefined;
+      return {
+         filters,
+         filter,
+         policies,
+         merge: (givenFilter: object | undefined) => {
+            return mergeFilters(givenFilter ?? {}, filter ?? {});
+         },
+         matches: (subject: object | object[], opts?: { throwOnError?: boolean }) => {
+            const subjects = Array.isArray(subject) ? subject : [subject];
+            if (policies.length > 0) {
+               for (const policy of policies) {
+                  for (const subject of subjects) {
+                     if (!policy.meetsFilter(subject, ctx)) {
+                        if (opts?.throwOnError) {
+                           throw new GuardPermissionsException(
+                              permission,
+                              policy,
+                              "Policy filter not met",
+                           );
+                        }
+                        return false;
+                     }
+                  }
+               }
+            }
+            return true;
+         },
+      };
    }
 }
+
+export function mergeFilters(base: ObjectQuery, priority: ObjectQuery) {
+   const base_converted = convert(base);
+   const priority_converted = convert(priority);
+   const merged = mergeObject(base_converted, priority_converted);
+
+   // in case priority filter is also contained in base's $and, merge priority in
+   if ("$or" in base_converted && base_converted.$or) {
+      const $ors = base_converted.$or as ObjectQuery;
+      const priority_keys = Object.keys(priority_converted);
+      for (const key of priority_keys) {
+         if (key in $ors) {
+            merged.$or[key] = mergeObject($ors[key], priority_converted[key]);
+         }
+      }
+   }
+
+   return merged;
+}

app/src/auth/authorize/Permission.ts

@@ -0,0 +1,77 @@
+import { s, type ParseOptions, parse, InvalidSchemaError, HttpStatus } from "bknd/utils";
+
+export const permissionOptionsSchema = s
+   .strictObject({
+      description: s.string(),
+      filterable: s.boolean(),
+   })
+   .partial();
+
+export type TPermission = {
+   name: string;
+   description?: string;
+   filterable?: boolean;
+   context?: any;
+};
+
+export type PermissionOptions = s.Static<typeof permissionOptionsSchema>;
+export type PermissionContext<P extends Permission<any, any, any, any>> = P extends Permission<
+   any,
+   any,
+   infer Context,
+   any
+>
+   ? Context extends s.ObjectSchema
+      ? s.Static<Context>
+      : never
+   : never;
+
+export class InvalidPermissionContextError extends InvalidSchemaError {
+   override name = "InvalidPermissionContextError";
+
+   // changing to internal server error because it's an unexpected behavior
+   override code = HttpStatus.INTERNAL_SERVER_ERROR;
+
+   static from(e: InvalidSchemaError) {
+      return new InvalidPermissionContextError(e.schema, e.value, e.errors);
+   }
+}
+
+export class Permission<
+   Name extends string = string,
+   Options extends PermissionOptions = {},
+   Context extends s.ObjectSchema | undefined = undefined,
+   ContextValue = Context extends s.ObjectSchema ? s.Static<Context> : undefined,
+> {
+   constructor(
+      public name: Name,
+      public options: Options = {} as Options,
+      public context: Context = undefined as Context,
+   ) {}
+
+   isFilterable() {
+      return this.options.filterable === true;
+   }
+
+   parseContext(ctx: ContextValue, opts?: ParseOptions) {
+      // @todo: allow additional properties
+      if (!this.context) return ctx;
+      try {
+         return this.context ? parse(this.context!, ctx, opts) : undefined;
+      } catch (e) {
+         if (e instanceof InvalidSchemaError) {
+            throw InvalidPermissionContextError.from(e);
+         }
+
+         throw e;
+      }
+   }
+
+   toJSON() {
+      return {
+         name: this.name,
+         ...this.options,
+         context: this.context,
+      };
+   }
+}

app/src/auth/authorize/Policy.ts

@@ -0,0 +1,52 @@
+import { s, parse, recursivelyReplacePlaceholders } from "bknd/utils";
+import * as query from "core/object/query/object-query";
+
+export const policySchema = s
+   .strictObject({
+      description: s.string(),
+      condition: s.object({}).optional() as s.Schema<{}, query.ObjectQuery | undefined>,
+      // @todo: potentially remove this, and invert from rolePermission.effect
+      effect: s.string({ enum: ["allow", "deny", "filter"], default: "allow" }),
+      filter: s.object({}).optional() as s.Schema<{}, query.ObjectQuery | undefined>,
+   })
+   .partial();
+export type PolicySchema = s.Static<typeof policySchema>;
+
+export class Policy<Schema extends PolicySchema = PolicySchema> {
+   public content: Schema;
+
+   constructor(content?: Schema) {
+      this.content = parse(policySchema, content ?? {}, {
+         withDefaults: true,
+      }) as Schema;
+   }
+
+   replace(context: object, vars?: Record<string, any>, fallback?: any) {
+      return vars
+         ? recursivelyReplacePlaceholders(context, /^@([a-zA-Z_\.]+)$/, vars, fallback)
+         : context;
+   }
+
+   getReplacedFilter(context: object, fallback?: any) {
+      if (!this.content.filter) return context;
+      return this.replace(this.content.filter!, context, fallback);
+   }
+
+   meetsCondition(context: object, vars?: Record<string, any>) {
+      if (!this.content.condition) return true;
+      return query.validate(this.replace(this.content.condition!, vars), context);
+   }
+
+   meetsFilter(subject: object, vars?: Record<string, any>) {
+      if (!this.content.filter) return true;
+      return query.validate(this.replace(this.content.filter!, vars), subject);
+   }
+
+   getFiltered<Given extends any[]>(given: Given): Given {
+      return given.filter((item) => this.meetsFilter(item)) as Given;
+   }
+
+   toJSON() {
+      return this.content;
+   }
+}

app/src/auth/authorize/Role.ts

@@ -1,10 +1,39 @@
-import { Permission } from "core/security/Permission";
+import { s } from "bknd/utils";
+import { Permission } from "./Permission";
+import { Policy, policySchema } from "./Policy";
+
+// default effect is allow for backward compatibility
+const defaultEffect = "allow";
+
+export const rolePermissionSchema = s.strictObject({
+   permission: s.string(),
+   effect: s.string({ enum: ["allow", "deny"], default: defaultEffect }).optional(),
+   policies: s.array(policySchema).optional(),
+});
+export type RolePermissionSchema = s.Static<typeof rolePermissionSchema>;
+
+export const roleSchema = s.strictObject({
+   // @todo: remove anyOf, add migration
+   permissions: s.anyOf([s.array(s.string()), s.array(rolePermissionSchema)]).optional(),
+   is_default: s.boolean().optional(),
+   implicit_allow: s.boolean().optional(),
+});
+export type RoleSchema = s.Static<typeof roleSchema>;
 
 export class RolePermission {
    constructor(
-      public permission: Permission,
+      public permission: Permission<any, any, any, any>,
-      public config?: any,
+      public policies: Policy[] = [],
+      public effect: "allow" | "deny" = defaultEffect,
    ) {}
+
+   toJSON() {
+      return {
+         permission: this.permission.name,
+         policies: this.policies.map((p) => p.toJSON()),
+         effect: this.effect,
+      };
+   }
 }
 
 export class Role {
@@ -15,31 +44,23 @@ export class Role {
       public implicit_allow: boolean = false,
    ) {}
 
-   static createWithPermissionNames(
+   static create(name: string, config: RoleSchema) {
-      name: string,
+      const permissions =
-      permissionNames: string[],
+         config.permissions?.map((p: string | RolePermissionSchema) => {
-      is_default: boolean = false,
+            if (typeof p === "string") {
-      implicit_allow: boolean = false,
+               return new RolePermission(new Permission(p), []);
-   ) {
+            }
-      return new Role(
+            const policies = p.policies?.map((policy) => new Policy(policy));
-         name,
+            return new RolePermission(new Permission(p.permission), policies, p.effect);
-         permissionNames.map((name) => new RolePermission(new Permission(name))),
+         }) ?? [];
-         is_default,
+      return new Role(name, permissions, config.is_default, config.implicit_allow);
-         implicit_allow,
-      );
    }
 
-   static create(config: {
+   toJSON() {
-      name: string;
+      return {
-      permissions?: string[];
+         permissions: this.permissions.map((p) => p.toJSON()),
-      is_default?: boolean;
+         is_default: this.is_default,
-      implicit_allow?: boolean;
+         implicit_allow: this.implicit_allow,
-   }) {
+      };
-      return new Role(
-         config.name,
-         config.permissions?.map((name) => new RolePermission(new Permission(name))) ?? [],
-         config.is_default,
-         config.implicit_allow,
-      );
    }
 }

app/src/auth/middlewares/auth.middleware.ts

@@ -1,4 +1,3 @@
-import type { Permission } from "core/security/Permission";
 import { $console, patternMatch } from "bknd/utils";
 import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
@@ -49,7 +48,7 @@ export const auth = (options?: {
       // make sure to only register once
       if (authCtx.registered) {
          skipped = true;
-         $console.warn(`auth middleware already registered for ${getPath(c)}`);
+         $console.debug(`auth middleware already registered for ${getPath(c)}`);
       } else {
          authCtx.registered = true;
 
@@ -67,48 +66,3 @@ export const auth = (options?: {
       authCtx.resolved = false;
       authCtx.user = undefined;
    });
-
-export const permission = (
-   permission: Permission | Permission[],
-   options?: {
-      onGranted?: (c: Context<ServerEnv>) => Promise<Response | void | undefined>;
-      onDenied?: (c: Context<ServerEnv>) => Promise<Response | void | undefined>;
-   },
-) =>
-   // @ts-ignore
-   createMiddleware<ServerEnv>(async (c, next) => {
-      const app = c.get("app");
-      const authCtx = c.get("auth");
-      if (!authCtx) {
-         throw new Error("auth ctx not found");
-      }
-
-      // in tests, app is not defined
-      if (!authCtx.registered || !app) {
-         const msg = `auth middleware not registered, cannot check permissions for ${getPath(c)}`;
-         if (app?.module.auth.enabled) {
-            throw new Error(msg);
-         } else {
-            $console.warn(msg);
-         }
-      } else if (!authCtx.skip) {
-         const guard = app.modules.ctx().guard;
-         const permissions = Array.isArray(permission) ? permission : [permission];
-
-         if (options?.onGranted || options?.onDenied) {
-            let returned: undefined | void | Response;
-            if (permissions.every((p) => guard.granted(p, c))) {
-               returned = await options?.onGranted?.(c);
-            } else {
-               returned = await options?.onDenied?.(c);
-            }
-            if (returned instanceof Response) {
-               return returned;
-            }
-         } else {
-            permissions.some((p) => guard.throwUnlessGranted(p, c));
-         }
-      }
-
-      await next();
-   });

app/src/auth/middlewares/permission.middleware.ts

@@ -0,0 +1,94 @@
+import type { Permission, PermissionContext } from "auth/authorize/Permission";
+import { $console, threw } from "bknd/utils";
+import type { Context, Hono } from "hono";
+import type { RouterRoute } from "hono/types";
+import { createMiddleware } from "hono/factory";
+import type { ServerEnv } from "modules/Controller";
+import type { MaybePromise } from "core/types";
+import { GuardPermissionsException } from "auth/authorize/Guard";
+
+function getPath(reqOrCtx: Request | Context) {
+   const req = reqOrCtx instanceof Request ? reqOrCtx : reqOrCtx.req.raw;
+   return new URL(req.url).pathname;
+}
+
+const permissionSymbol = Symbol.for("permission");
+
+type PermissionMiddlewareOptions<P extends Permission<any, any, any, any>> = {
+   onGranted?: (c: Context<ServerEnv>) => MaybePromise<Response | void | undefined>;
+   onDenied?: (c: Context<ServerEnv>) => MaybePromise<Response | void | undefined>;
+} & (P extends Permission<any, any, infer PC, any>
+   ? PC extends undefined
+      ? {
+           context?: never;
+        }
+      : {
+           context: (c: Context<ServerEnv>) => MaybePromise<PermissionContext<P>>;
+        }
+   : {
+        context?: never;
+     });
+
+export function permission<P extends Permission<any, any, any, any>>(
+   permission: P,
+   options: PermissionMiddlewareOptions<P>,
+) {
+   // @ts-ignore (middlewares do not always return)
+   const handler = createMiddleware<ServerEnv>(async (c, next) => {
+      const app = c.get("app");
+      const authCtx = c.get("auth");
+      if (!authCtx) {
+         throw new Error("auth ctx not found");
+      }
+
+      // in tests, app is not defined
+      if (!authCtx.registered || !app) {
+         const msg = `auth middleware not registered, cannot check permissions for ${getPath(c)}`;
+         if (app?.module.auth.enabled) {
+            throw new Error(msg);
+         } else {
+            $console.warn(msg);
+         }
+      } else if (!authCtx.skip) {
+         const guard = app.modules.ctx().guard;
+         const context = (await options?.context?.(c)) ?? ({} as any);
+
+         if (options?.onGranted || options?.onDenied) {
+            let returned: undefined | void | Response;
+            if (threw(() => guard.granted(permission, c, context), GuardPermissionsException)) {
+               returned = await options?.onDenied?.(c);
+            } else {
+               returned = await options?.onGranted?.(c);
+            }
+            if (returned instanceof Response) {
+               return returned;
+            }
+         } else {
+            guard.granted(permission, c, context);
+         }
+      }
+
+      await next();
+   });
+
+   return Object.assign(handler, {
+      [permissionSymbol]: { permission, options },
+   });
+}
+
+export function getPermissionRoutes(hono: Hono<any>) {
+   const routes: {
+      route: RouterRoute;
+      permission: Permission;
+      options: PermissionMiddlewareOptions<Permission>;
+   }[] = [];
+   for (const route of hono.routes) {
+      if (permissionSymbol in route.handler) {
+         routes.push({
+            route,
+            ...(route.handler[permissionSymbol] as any),
+         });
+      }
+   }
+   return routes;
+}

app/src/cli/commands/create/create.ts

@@ -10,6 +10,7 @@ import color from "picocolors";
 import { overridePackageJson, updateBkndPackages } from "./npm";
 import { type Template, templates, type TemplateSetupCtx } from "./templates";
 import { createScoped, flush } from "cli/utils/telemetry";
+import path from "node:path";
 
 const config = {
    types: {
@@ -20,6 +21,7 @@ const config = {
       node: "Node.js",
       bun: "Bun",
       cloudflare: "Cloudflare",
+      deno: "Deno",
       aws: "AWS Lambda",
    },
    framework: {
@@ -259,17 +261,19 @@ async function action(options: {
       }
    }
 
-   // update package name
+   // update package name if there is a package.json
-   await overridePackageJson(
+   if (fs.existsSync(path.resolve(ctx.dir, "package.json"))) {
-      (pkg) => ({
+      await overridePackageJson(
-         ...pkg,
+         (pkg) => ({
-         name: ctx.name,
+            ...pkg,
-      }),
+            name: ctx.name,
-      { dir: ctx.dir },
+         }),
-   );
+         { dir: ctx.dir },
-   $p.log.success(`Updated package name to ${color.cyan(ctx.name)}`);
+      );
+      $p.log.success(`Updated package name to ${color.cyan(ctx.name)}`);
+   }
 
-   {
+   if (template.installDeps !== false) {
       const install =
          options.yes ??
          (await $p.confirm({

app/src/cli/commands/create/npm.ts

@@ -93,17 +93,19 @@ export async function replacePackageJsonVersions(
 }
 
 export async function updateBkndPackages(dir?: string, map?: Record<string, string>) {
-   const versions = {
+   try {
-      bknd: await sysGetVersion(),
+      const versions = {
-      ...(map ?? {}),
+         bknd: await sysGetVersion(),
-   };
+         ...(map ?? {}),
-   await replacePackageJsonVersions(
+      };
-      async (pkg) => {
+      await replacePackageJsonVersions(
-         if (pkg in versions) {
+         async (pkg) => {
-            return versions[pkg];
+            if (pkg in versions) {
-         }
+               return versions[pkg];
-         return;
+            }
-      },
+            return;
-      { dir },
+         },
-   );
+         { dir },
+      );
+   } catch (e) {}
 }

app/src/cli/commands/create/templates/deno.ts

@@ -0,0 +1,21 @@
+import { overrideJson } from "cli/commands/create/npm";
+import type { Template } from "cli/commands/create/templates";
+import { getVersion } from "cli/utils/sys";
+
+export const deno = {
+   key: "deno",
+   title: "Deno Basic",
+   integration: "deno",
+   description: "A basic bknd Deno server with static assets",
+   path: "gh:bknd-io/bknd/examples/deno",
+   installDeps: false,
+   ref: true,
+   setup: async (ctx) => {
+      const version = await getVersion();
+      await overrideJson(
+         "deno.json",
+         (json) => ({ ...json, links: undefined, imports: { bknd: `npm:bknd@${version}` } }),
+         { dir: ctx.dir },
+      );
+   },
+} satisfies Template;

app/src/cli/commands/create/templates/index.ts

@@ -1,3 +1,4 @@
+import { deno } from "cli/commands/create/templates/deno";
 import { cloudflare } from "./cloudflare";
 
 export type TemplateSetupCtx = {
@@ -15,6 +16,7 @@ export type Integration =
    | "react-router"
    | "astro"
    | "aws"
+   | "deno"
    | "custom";
 
 type TemplateScripts = "install" | "dev" | "build" | "start";
@@ -34,6 +36,11 @@ export type Template = {
     * adds a ref "#{ref}" to the path. If "true", adds the current version of bknd
     */
    ref?: true | string;
+   /**
+    * control whether to install dependencies automatically
+    * e.g. on deno, this is not needed
+    */
+   installDeps?: boolean;
    scripts?: Partial<Record<TemplateScripts, string>>;
    preinstall?: (ctx: TemplateSetupCtx) => Promise<void>;
    postinstall?: (ctx: TemplateSetupCtx) => Promise<void>;
@@ -90,4 +97,5 @@ export const templates: Template[] = [
       path: "gh:bknd-io/bknd/examples/aws-lambda",
       ref: true,
    },
+   deno,
 ];

app/src/cli/commands/run/run.ts

@@ -110,7 +110,10 @@ export async function makeAppFromEnv(options: Partial<RunOptions> = {}) {
       // try to use an in-memory connection
    } else if (options.memory) {
       console.info("Using", c.cyan("in-memory"), "connection");
-      app = await makeApp({ server: { platform: options.server } });
+      app = await makeApp({
+         server: { platform: options.server },
+         connection: { url: ":memory:" },
+      });
 
       // finally try to use env variables
    } else {

app/src/cli/commands/user.ts

@@ -3,6 +3,7 @@ import {
    log as $log,
    password as $password,
    text as $text,
+   select as $select,
 } from "@clack/prompts";
 import type { App } from "App";
 import type { PasswordStrategy } from "auth/authenticate/strategies";
@@ -29,6 +30,11 @@ async function action(action: "create" | "update" | "token", options: WithConfig
       server: "node",
    });
 
+   if (!app.module.auth.enabled) {
+      $log.error("Auth is not enabled");
+      process.exit(1);
+   }
+
    switch (action) {
       case "create":
          await create(app, options);
@@ -43,7 +49,28 @@ async function action(action: "create" | "update" | "token", options: WithConfig
 }
 
 async function create(app: App, options: any) {
-   const strategy = app.module.auth.authenticator.strategy("password") as PasswordStrategy;
+   const auth = app.module.auth;
+   let role: string | null = null;
+   const roles = Object.keys(auth.config.roles ?? {});
+
+   const strategy = auth.authenticator.strategy("password") as PasswordStrategy;
+   if (roles.length > 0) {
+      role = (await $select({
+         message: "Select role",
+         options: [
+            {
+               value: null,
+               label: "<none>",
+               hint: "No role will be assigned to the user",
+            },
+            ...roles.map((role) => ({
+               value: role,
+               label: role,
+            })),
+         ],
+      })) as any;
+      if ($isCancel(role)) process.exit(1);
+   }
 
    if (!strategy) {
       $log.error("Password strategy not configured");
@@ -76,6 +103,7 @@ async function create(app: App, options: any) {
       const created = await app.createUser({
          email,
          password: await strategy.hash(password as string),
+         role,
       });
       $log.success(`Created user: ${c.cyan(created.email)}`);
       process.exit(0);

app/src/core/events/EventManager.ts

@@ -205,7 +205,17 @@ export class EventManager<
          if (listener.mode === "sync") {
             syncs.push(listener);
          } else {
-            asyncs.push(async () => await listener.handler(event, listener.event.slug));
+            asyncs.push(async () => {
+               try {
+                  await listener.handler(event, listener.event.slug);
+               } catch (e) {
+                  if (this.options?.onError) {
+                     this.options.onError(event, e);
+                  } else {
+                     $console.error("Error executing async listener", listener, e);
+                  }
+               }
+            });
          }
          // Remove if `once` is true, otherwise keep
          return !listener.once;

app/src/core/object/query/query.ts

@@ -1,4 +1,5 @@
 import type { PrimaryFieldType } from "core/config";
+import { getPath, invariant, isPlainObject } from "bknd/utils";
 
 export type Primitive = PrimaryFieldType | string | number | boolean;
 export function isPrimitive(value: any): value is Primitive {
@@ -25,6 +26,10 @@ export function exp<const Key, const Expect, CTX = any>(
    valid: (v: Expect) => boolean,
    validate: (e: Expect, a: unknown, ctx: CTX) => any,
 ): Expression<Key, Expect, CTX> {
+   invariant(typeof key === "string", "key must be a string");
+   invariant(key[0] === "$", "key must start with '$'");
+   invariant(typeof valid === "function", "valid must be a function");
+   invariant(typeof validate === "function", "validate must be a function");
    return new Expression(key, valid, validate);
 }
 
@@ -50,7 +55,7 @@ function getExpression<Exps extends Expressions>(
 }
 
 type LiteralExpressionCondition<Exps extends Expressions> = {
-   [key: string]: Primitive | ExpressionCondition<Exps>;
+   [key: string]: undefined | Primitive | ExpressionCondition<Exps>;
 };
 
 const OperandOr = "$or" as const;
@@ -67,8 +72,9 @@ function _convert<Exps extends Expressions>(
    expressions: Exps,
    path: string[] = [],
 ): FilterQuery<Exps> {
+   invariant(typeof $query === "object", "$query must be an object");
    const ExpressionConditionKeys = expressions.map((e) => e.key);
-   const keys = Object.keys($query);
+   const keys = Object.keys($query ?? {});
    const operands = [OperandOr] as const;
    const newQuery: FilterQuery<Exps> = {};
 
@@ -83,13 +89,21 @@ function _convert<Exps extends Expressions>(
    function validate(key: string, value: any, path: string[] = []) {
       const exp = getExpression(expressions, key as any);
       if (exp.valid(value) === false) {
-         throw new Error(`Invalid value at "${[...path, key].join(".")}": ${value}`);
+         throw new Error(
+            `Given value at "${[...path, key].join(".")}" is invalid, got "${JSON.stringify(value)}"`,
+         );
       }
    }
 
    for (const [key, value] of Object.entries($query)) {
+      // skip undefined values
+      if (value === undefined) {
+         continue;
+      }
+
       // if $or, convert each value
       if (key === "$or") {
+         invariant(isPlainObject(value), "$or must be an object");
          newQuery.$or = _convert(value, expressions, [...path, key]);
 
          // if primitive, assume $eq
@@ -98,7 +112,7 @@ function _convert<Exps extends Expressions>(
          newQuery[key] = { $eq: value };
 
          // if object, check for expressions
-      } else if (typeof value === "object") {
+      } else if (isPlainObject(value)) {
          // when object is given, check if all keys are expressions
          const invalid = Object.keys(value).filter(
             (f) => !ExpressionConditionKeys.includes(f as any),
@@ -112,9 +126,13 @@ function _convert<Exps extends Expressions>(
             }
          } else {
             throw new Error(
-               `Invalid key(s) at "${key}": ${invalid.join(", ")}. Expected expressions.`,
+               `Invalid key(s) at "${key}": ${invalid.join(", ")}. Expected expression key: ${ExpressionConditionKeys.join(", ")}.`,
             );
          }
+      } else {
+         throw new Error(
+            `Invalid value at "${[...path, key].join(".")}", got "${JSON.stringify(value)}"`,
+         );
       }
    }
 
@@ -149,15 +167,19 @@ function _build<Exps extends Expressions>(
          throw new Error(`Expression does not exist: "${$op}"`);
       }
       if (!exp.valid(expected)) {
-         throw new Error(`Invalid expected value at "${[...path, $op].join(".")}": ${expected}`);
+         throw new Error(
+            `Invalid value at "${[...path, $op].join(".")}", got "${JSON.stringify(expected)}"`,
+         );
       }
       return exp.validate(expected, actual, options.exp_ctx);
    }
 
    // check $and
    for (const [key, value] of Object.entries($and)) {
+      if (value === undefined) continue;
+
       for (const [$op, $v] of Object.entries(value)) {
-         const objValue = options.value_is_kv ? key : options.object[key];
+         const objValue = options.value_is_kv ? key : getPath(options.object, key);
          result.$and.push(__validate($op, $v, objValue, [key]));
          result.keys.add(key);
       }
@@ -165,7 +187,7 @@ function _build<Exps extends Expressions>(
 
    // check $or
    for (const [key, value] of Object.entries($or ?? {})) {
-      const objValue = options.value_is_kv ? key : options.object[key];
+      const objValue = options.value_is_kv ? key : getPath(options.object, key);
 
       for (const [$op, $v] of Object.entries(value)) {
          result.$or.push(__validate($op, $v, objValue, [key]));
@@ -189,6 +211,10 @@ function _validate(results: ValidationResults): boolean {
 }
 
 export function makeValidator<Exps extends Expressions>(expressions: Exps) {
+   if (!expressions.some((e) => e.key === "$eq")) {
+      throw new Error("'$eq' expression is required");
+   }
+
    return {
       convert: (query: FilterQuery<Exps>) => _convert(query, expressions),
       build: (query: FilterQuery<Exps>, options: BuildOptions) =>

app/src/core/security/Permission.ts

@@ -1,11 +0,0 @@
-export class Permission<Name extends string = string> {
-   constructor(public name: Name) {
-      this.name = name;
-   }
-
-   toJSON() {
-      return {
-         name: this.name,
-      };
-   }
-}

app/src/core/types.ts

@@ -6,3 +6,7 @@ export interface Serializable<Class, Json extends object = object> {
 export type MaybePromise<T> = T | Promise<T>;
 
 export type PartialRec<T> = { [P in keyof T]?: PartialRec<T[P]> };
+
+export type Merge<T> = {
+   [K in keyof T]: T[K];
+};

app/src/core/utils/file.ts

@@ -240,3 +240,46 @@ export async function blobToFile(
       lastModified: Date.now(),
    });
 }
+
+export function isFileAccepted(file: File | unknown, _accept: string | string[]): boolean {
+   const accept = Array.isArray(_accept) ? _accept.join(",") : _accept;
+   if (!accept || !accept.trim()) return true; // no restrictions
+   if (!isFile(file)) {
+      throw new Error("Given file is not a File instance");
+   }
+
+   const name = file.name.toLowerCase();
+   const type = (file.type || "").trim().toLowerCase();
+
+   // split on commas, trim whitespace
+   const tokens = accept
+      .split(",")
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean);
+
+   // try each token until one matches
+   return tokens.some((token) => {
+      if (token.startsWith(".")) {
+         // extension match, e.g. ".png" or ".tar.gz"
+         return name.endsWith(token);
+      }
+
+      const slashIdx = token.indexOf("/");
+      if (slashIdx !== -1) {
+         const [major, minor] = token.split("/");
+         if (minor === "*") {
+            // wildcard like "image/*"
+            if (!type) return false;
+            const [fMajor] = type.split("/");
+            return fMajor === major;
+         } else {
+            // exact MIME like "image/svg+xml" or "application/pdf"
+            // because of "text/plain;charset=utf-8"
+            return type.startsWith(token);
+         }
+      }
+
+      // unknown token shape, ignore
+      return false;
+   });
+}

app/src/core/utils/objects.ts

@@ -372,7 +372,7 @@ export function isEqual(value1: any, value2: any): boolean {
 export function getPath(
    object: object,
    _path: string | (string | number)[],
-   defaultValue = undefined,
+   defaultValue: any = undefined,
 ): any {
    const path = typeof _path === "string" ? _path.split(/[.\[\]\"]+/).filter((x) => x) : _path;
 
@@ -512,3 +512,43 @@ export function convertNumberedObjectToArray(obj: object): any[] | object {
    }
    return obj;
 }
+
+export function recursivelyReplacePlaceholders(
+   obj: any,
+   pattern: RegExp,
+   variables: Record<string, any>,
+   fallback?: any,
+) {
+   if (typeof obj === "string") {
+      // check if the entire string matches the pattern
+      const match = obj.match(pattern);
+      if (match && match[0] === obj && match[1]) {
+         // full string match - replace with the actual value (preserving type)
+         const key = match[1];
+         const value = getPath(variables, key, null);
+         return value !== null ? value : fallback !== undefined ? fallback : obj;
+      }
+      // partial match - use string replacement
+      if (pattern.test(obj)) {
+         return obj.replace(pattern, (match, key) => {
+            const value = getPath(variables, key, null);
+            // convert to string for partial replacements
+            return value !== null
+               ? String(value)
+               : fallback !== undefined
+                 ? String(fallback)
+                 : match;
+         });
+      }
+   }
+   if (Array.isArray(obj)) {
+      return obj.map((item) => recursivelyReplacePlaceholders(item, pattern, variables, fallback));
+   }
+   if (obj && typeof obj === "object") {
+      return Object.entries(obj).reduce((acc, [key, value]) => {
+         acc[key] = recursivelyReplacePlaceholders(value, pattern, variables, fallback);
+         return acc;
+      }, {} as object);
+   }
+   return obj;
+}

app/src/core/utils/runtime.ts

@@ -61,3 +61,19 @@ export function invariant(condition: boolean | any, message: string) {
       throw new Error(message);
    }
 }
+
+export function threw(fn: () => any, instance?: new (...args: any[]) => Error) {
+   try {
+      fn();
+      return false;
+   } catch (e) {
+      if (instance) {
+         if (e instanceof instance) {
+            return true;
+         }
+         // if instance given but not what expected, throw
+         throw e;
+      }
+      return true;
+   }
+}

app/src/core/utils/schema/index.ts

@@ -1,3 +1,5 @@
+import { Exception } from "core/errors";
+import { HttpStatus } from "bknd/utils";
 import * as s from "jsonv-ts";
 
 export { validator as jsc, type Options } from "jsonv-ts/hono";
@@ -58,7 +60,10 @@ export const stringIdentifier = s.string({
    maxLength: 150,
 });
 
-export class InvalidSchemaError extends Error {
+export class InvalidSchemaError extends Exception {
+   override name = "InvalidSchemaError";
+   override code = HttpStatus.UNPROCESSABLE_ENTITY;
+
    constructor(
       public schema: s.Schema,
       public value: unknown,

app/src/data/api/DataController.ts

@@ -15,6 +15,7 @@ import type { AppDataConfig } from "../data-schema";
 import type { EntityManager, EntityData } from "data/entities";
 import * as DataPermissions from "data/permissions";
 import { repoQuery, type RepoQuery } from "data/server/query";
+import { EntityTypescript } from "data/entities/EntityTypescript";
 
 export class DataController extends Controller {
    constructor(
@@ -42,7 +43,7 @@ export class DataController extends Controller {
 
    override getController() {
       const { permission, auth } = this.middlewares;
-      const hono = this.create().use(auth(), permission(SystemPermissions.accessApi));
+      const hono = this.create().use(auth(), permission(SystemPermissions.accessApi, {}));
       const entitiesEnum = this.getEntitiesEnum(this.em);
 
       // info
@@ -58,7 +59,7 @@ export class DataController extends Controller {
       // sync endpoint
       hono.get(
          "/sync",
-         permission(DataPermissions.databaseSync),
+         permission(DataPermissions.databaseSync, {}),
          mcpTool("data_sync", {
             // @todo: should be removed if readonly
             annotations: {
@@ -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"],
@@ -153,6 +158,22 @@ export class DataController extends Controller {
          },
       );
 
+      hono.get(
+         "/types",
+         permission(SystemPermissions.schemaRead, {
+            context: (c) => ({ module: "data" }),
+         }),
+         describeRoute({
+            summary: "Retrieve data typescript definitions",
+            tags: ["data"],
+         }),
+         mcpTool("data_types"),
+         async (c) => {
+            const et = new EntityTypescript(this.em);
+            return c.text(et.toString());
+         },
+      );
+
       // entity endpoints
       hono.route("/entity", this.getEntityRoutes());
 
@@ -161,7 +182,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 +236,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 +261,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 +312,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 +345,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 +365,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 +391,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 +410,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 +450,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 +467,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 +489,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 +508,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 +531,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 +560,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 +576,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 +588,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 +612,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 +622,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 +647,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 +664,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/Entity.ts

@@ -136,8 +136,10 @@ export class Entity<
          .map((field) => (alias ? `${alias}.${field.name} as ${field.name}` : field.name));
    }
 
-   getFillableFields(context?: TActionContext, include_virtual?: boolean): Field[] {
+   getFillableFields(context?: "create" | "update", include_virtual?: boolean): Field[] {
-      return this.getFields(include_virtual).filter((field) => field.isFillable(context));
+      return this.getFields({ virtual: include_virtual }).filter((field) =>
+         field.isFillable(context),
+      );
    }
 
    getRequiredFields(): Field[] {
@@ -189,9 +191,15 @@ export class Entity<
       return this.fields.findIndex((field) => field.name === name) !== -1;
    }
 
-   getFields(include_virtual: boolean = false): Field[] {
+   getFields({
-      if (include_virtual) return this.fields;
+      virtual = false,
-      return this.fields.filter((f) => !f.isVirtual());
+      primary = true,
+   }: { virtual?: boolean; primary?: boolean } = {}): Field[] {
+      return this.fields.filter((f) => {
+         if (!virtual && f.isVirtual()) return false;
+         if (!primary && f instanceof PrimaryField) return false;
+         return true;
+      });
    }
 
    addField(field: Field) {
@@ -231,7 +239,7 @@ export class Entity<
          }
       }
 
-      const fields = this.getFillableFields(context, false);
+      const fields = this.getFillableFields(context as any, false);
 
       if (options?.ignoreUnknown !== true) {
          const field_names = fields.map((f) => f.name);
@@ -275,7 +283,7 @@ export class Entity<
             fields = this.getFillableFields(options.context);
             break;
          default:
-            fields = this.getFields(true);
+            fields = this.getFields({ virtual: true });
       }
 
       const _fields = Object.fromEntries(fields.map((field) => [field.name, field]));

app/src/data/entities/EntityManager.ts

@@ -34,7 +34,6 @@ export class EntityManager<TBD extends object = DefaultDB> {
    private _entities: Entity[] = [];
    private _relations: EntityRelation[] = [];
    private _indices: EntityIndex[] = [];
-   private _schema?: SchemaManager;
    readonly emgr: EventManager<typeof EntityManager.Events>;
    static readonly Events = { ...MutatorEvents, ...RepositoryEvents };
 
@@ -249,11 +248,7 @@ export class EntityManager<TBD extends object = DefaultDB> {
    }
 
    schema() {
-      if (!this._schema) {
+      return new SchemaManager(this);
-         this._schema = new SchemaManager(this);
-      }
-
-      return this._schema;
    }
 
    // @todo: centralize and add tests

app/src/data/entities/mutation/Mutator.ts

@@ -83,8 +83,10 @@ export class Mutator<
          }
 
          // we should never get here, but just to be sure (why?)
-         if (!field.isFillable(context)) {
+         if (!field.isFillable(context as any)) {
-            throw new Error(`Field "${key}" is not fillable on entity "${entity.name}"`);
+            throw new Error(
+               `Field "${key}" of entity "${entity.name}" is not fillable on context "${context}"`,
+            );
          }
 
          // transform from field

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(
+      if (typeof id === "undefined" || id === null) {
-         {
+         throw new InvalidSearchParamsException("id is required");
-            ..._options,
+      }
-            where: { [this.entity.getPrimaryField().name]: id },
-            limit: 1,
-         },
-         ["offset", "sort"],
-      );
 
-      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 { entity: newEntity, relation } = this.getEntityByReference(reference);
-      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 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/fields/Field.ts

@@ -26,11 +26,19 @@ export const baseFieldConfigSchema = s
    .strictObject({
       label: s.string(),
       description: s.string(),
-      required: s.boolean({ default: false }),
+      required: s.boolean({ default: DEFAULT_REQUIRED }),
-      fillable: s.anyOf([
+      fillable: s.anyOf(
-         s.boolean({ title: "Boolean" }),
+         [
-         s.array(s.string({ enum: ActionContext }), { title: "Context", uniqueItems: true }),
+            s.boolean({ title: "Boolean" }),
-      ]),
+            s.array(s.string({ enum: ["create", "update"] }), {
+               title: "Context",
+               uniqueItems: true,
+            }),
+         ],
+         {
+            default: DEFAULT_FILLABLE,
+         },
+      ),
       hidden: s.anyOf([
          s.boolean({ title: "Boolean" }),
          // @todo: tmp workaround
@@ -103,7 +111,7 @@ export abstract class Field<
       return this.config?.default_value;
    }
 
-   isFillable(context?: TActionContext): boolean {
+   isFillable(context?: "create" | "update"): boolean {
       if (Array.isArray(this.config.fillable)) {
          return context ? this.config.fillable.includes(context) : DEFAULT_FILLABLE;
       }
@@ -165,7 +173,7 @@ export abstract class Field<
    // @todo: add field level validation
    isValid(value: any, context: TActionContext): boolean {
       if (typeof value !== "undefined") {
-         return this.isFillable(context);
+         return this.isFillable(context as any);
       } else if (context === "create") {
          return !this.isRequired();
       }

app/src/data/fields/JsonField.ts

@@ -64,20 +64,27 @@ export class JsonField<Required extends true | false = false, TypeOverride = obj
       return false;
    }
 
+   override isValid(value: any): boolean {
+      return this.isSerializable(value);
+   }
+
    override getValue(value: any, context: TRenderContext): any {
       switch (context) {
-         case "form":
-            if (value === null) return "";
-            return JSON.stringify(value, null, 2);
          case "table":
             if (value === null) return null;
             return JSON.stringify(value);
          case "submit":
-            if (typeof value === "string" && value.length === 0) {
+            if (!value || (typeof value === "string" && value.length === 0)) {
                return null;
+            } else if (typeof value === "object") {
+               return value;
             }
 
-            return JSON.parse(value);
+            try {
+               return JSON.parse(value);
+            } catch (e) {
+               return value;
+            }
       }
 
       return value;

app/src/data/fields/field-test-suite.ts

@@ -99,6 +99,7 @@ export function fieldTestSuite(
       const _config = {
          ..._requiredConfig,
          required: false,
+         fillable: true,
       };
 
       function fieldJson(field: Field) {
@@ -116,10 +117,7 @@ export function fieldTestSuite(
 
       expect(fieldJson(fillable)).toEqual({
          type: noConfigField.type,
-         config: {
+         config: _config,
-            ..._config,
-            fillable: true,
-         },
       });
 
       expect(fieldJson(required)).toEqual({
@@ -150,7 +148,6 @@ export function fieldTestSuite(
          type: requiredAndDefault.type,
          config: {
             ..._config,
-            fillable: true,
             required: true,
             default_value: config.defaultValue,
          },

app/src/data/permissions/index.ts

@@ -1,9 +1,51 @@
-import { Permission } from "core/security/Permission";
+import { Permission } from "auth/authorize/Permission";
+import { s } from "bknd/utils";
 
-export const entityRead = new Permission("data.entity.read");
+export const entityRead = new Permission(
-export const entityCreate = new Permission("data.entity.create");
+   "data.entity.read",
-export const entityUpdate = new Permission("data.entity.update");
+   {
-export const entityDelete = new Permission("data.entity.delete");
+      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");

app/src/data/schema/SchemaManager.ts

@@ -77,7 +77,7 @@ export class SchemaManager {
    }
 
    getIntrospectionFromEntity(entity: Entity): IntrospectedTable {
-      const fields = entity.getFields(false);
+      const fields = entity.getFields({ virtual: false });
       const indices = this.em.getIndicesOf(entity);
 
       // this is intentionally setting values to defaults, like "nullable" and "default"
@@ -248,20 +248,16 @@ export class SchemaManager {
 
    async sync(config: { force?: boolean; drop?: boolean } = { force: false, drop: false }) {
       const diff = await this.getDiff();
-      let updates: number = 0;
       const statements: { sql: string; parameters: readonly unknown[] }[] = [];
       const schema = this.em.connection.kysely.schema;
+      const qbs: { compile(): CompiledQuery; execute(): Promise<void> }[] = [];
 
       for (const table of diff) {
-         const qbs: { compile(): CompiledQuery; execute(): Promise<void> }[] = [];
-         let local_updates: number = 0;
          const addFieldSchemas = this.collectFieldSchemas(table.name, table.columns.add);
          const dropFields = table.columns.drop;
          const dropIndices = table.indices.drop;
 
          if (table.isDrop) {
-            updates++;
-            local_updates++;
             if (config.drop) {
                qbs.push(schema.dropTable(table.name));
             }
@@ -269,8 +265,6 @@ export class SchemaManager {
             let createQb = schema.createTable(table.name);
             // add fields
             for (const fieldSchema of addFieldSchemas) {
-               updates++;
-               local_updates++;
                // @ts-ignore
                createQb = createQb.addColumn(...fieldSchema);
             }
@@ -281,8 +275,6 @@ export class SchemaManager {
             if (addFieldSchemas.length > 0) {
                // add fields
                for (const fieldSchema of addFieldSchemas) {
-                  updates++;
-                  local_updates++;
                   // @ts-ignore
                   qbs.push(schema.alterTable(table.name).addColumn(...fieldSchema));
                }
@@ -292,8 +284,6 @@ export class SchemaManager {
             if (config.drop && dropFields.length > 0) {
                // drop fields
                for (const column of dropFields) {
-                  updates++;
-                  local_updates++;
                   qbs.push(schema.alterTable(table.name).dropColumn(column));
                }
             }
@@ -311,35 +301,33 @@ export class SchemaManager {
                qb = qb.unique();
             }
             qbs.push(qb);
-            local_updates++;
-            updates++;
          }
 
          // drop indices
          if (config.drop) {
             for (const index of dropIndices) {
                qbs.push(schema.dropIndex(index));
-               local_updates++;
-               updates++;
             }
          }
+      }
 
-         if (local_updates === 0) continue;
+      if (qbs.length > 0) {
+         statements.push(
+            ...qbs.map((qb) => {
+               const { sql, parameters } = qb.compile();
+               return { sql, parameters };
+            }),
+         );
 
-         // iterate through built qbs
+         $console.debug(
-         // @todo: run in batches
+            "[SchemaManager]",
-         for (const qb of qbs) {
+            `${qbs.length} statements\n${statements.map((stmt) => stmt.sql).join(";\n")}`,
-            const { sql, parameters } = qb.compile();
+         );
-            statements.push({ sql, parameters });
 
-            if (config.force) {
+         try {
-               try {
+            await this.em.connection.executeQueries(...qbs);
-                  $console.debug("[SchemaManager]", sql);
+         } catch (e) {
-                  await qb.execute();
+            throw new Error(`Failed to execute batch: ${String(e)}`);
-               } catch (e) {
-                  throw new Error(`Failed to execute query: ${sql}: ${(e as any).message}`);
-               }
-            }
          }
       }
 

app/src/data/server/query.spec.ts

@@ -1,6 +1,8 @@
 import { test, describe, expect } from "bun:test";
 import * as q from "./query";
 import { parse as $parse, type ParseOptions } from "bknd/utils";
+import type { PrimaryFieldType } from "modules";
+import type { Generated } from "kysely";
 
 const parse = (v: unknown, o: ParseOptions = {}) =>
    $parse(q.repoQuery, v, {
@@ -186,4 +188,35 @@ describe("server/query", () => {
          decode({ with: { images: {}, comments: {} } }, output);
       }
    });
+
+   test("types", () => {
+      const id = 1 as PrimaryFieldType;
+      const id2 = "1" as unknown as Generated<string>;
+
+      const c: q.RepoQueryIn = {
+         where: {
+            // @ts-expect-error only primitives are allowed for $eq
+            something: [],
+            // this gets ignored
+            another: undefined,
+            // @ts-expect-error null is not a valid value
+            null_is_okay: null,
+            some_id: id,
+            another_id: id2,
+         },
+      };
+
+      const d: q.RepoQuery = {
+         where: {
+            // @ts-expect-error only primitives are allowed for $eq
+            something: [],
+            // this gets ignored
+            another: undefined,
+            // @ts-expect-error null is not a valid value
+            null_is_okay: null,
+            some_id: id,
+            another_id: id2,
+         },
+      };
+   });
 });

app/src/data/server/query.ts

@@ -84,8 +84,6 @@ const where = s.anyOf([s.string(), s.object({})], {
       return WhereBuilder.convert(q);
    },
 });
-//type WhereSchemaIn = s.Static<typeof where>;
-//type WhereSchema = s.StaticCoerced<typeof where>;
 
 // ------
 // with
@@ -128,7 +126,7 @@ const withSchema = <Type = unknown>(self: s.Schema): s.Schema<{}, Type, Type> =>
             }
          }
 
-         return value as unknown as any;
+         return value as any;
       },
    }) as any;
 
@@ -167,15 +165,3 @@ export type RepoQueryIn = {
 export type RepoQuery = s.StaticCoerced<typeof repoQuery> & {
    sort: SortSchema;
 };
-
-//export type RepoQuery = s.StaticCoerced<typeof repoQuery>;
-// @todo: CURRENT WORKAROUND
-/* export type RepoQuery = {
-   limit?: number;
-   offset?: number;
-   sort?: { by: string; dir: "asc" | "desc" };
-   select?: string[];
-   with?: Record<string, RepoQuery>;
-   join?: string[];
-   where?: WhereQuery;
-}; */

app/src/index.ts

@@ -41,15 +41,16 @@ export { getSystemMcp } from "modules/mcp/system-mcp";
 /**
  * Core
  */
-export type { MaybePromise } from "core/types";
+export type { MaybePromise, Merge } from "core/types";
 export { Exception, BkndError } from "core/errors";
 export { isDebug, env } from "core/env";
 export { type PrimaryFieldType, config, type DB, type AppEntity } from "core/config";
-export { Permission } from "core/security/Permission";
+export { Permission } from "auth/authorize/Permission";
 export { getFlashMessage } from "core/server/flash";
 export * from "core/drivers";
 export { Event, InvalidEventReturn } from "core/events/Event";
 export type {
+   EventListener,
    ListenerMode,
    ListenerHandler,
 } from "core/events/EventListener";

app/src/media/AppMedia.ts

@@ -22,6 +22,9 @@ declare module "bknd" {
 // @todo: current workaround to make it all required
 export class AppMedia extends Module<Required<TAppMediaConfig>> {
    private _storage?: Storage;
+   options = {
+      body_max_size: null as number | null,
+   };
 
    override async build() {
       if (!this.config.enabled) {

app/src/media/api/MediaApi.ts

@@ -1,11 +1,14 @@
 import type { FileListObject } from "media/storage/Storage";
 import {
    type BaseModuleApiOptions,
+   type FetchPromise,
+   type ResponseObject,
    ModuleApi,
    type PrimaryFieldType,
    type TInput,
 } from "modules/ModuleApi";
 import type { ApiFetcher } from "Api";
+import type { DB, FileUploadedEventData } from "bknd";
 
 export type MediaApiOptions = BaseModuleApiOptions & {
    upload_fetcher: ApiFetcher;
@@ -67,14 +70,14 @@ export class MediaApi extends ModuleApi<MediaApiOptions> {
       return new Headers();
    }
 
-   protected uploadFile(
+   protected uploadFile<T extends FileUploadedEventData>(
       body: File | Blob | ReadableStream | Buffer<ArrayBufferLike>,
       opts?: {
          filename?: string;
          path?: TInput;
          _init?: Omit<RequestInit, "body">;
       },
-   ) {
+   ): FetchPromise<ResponseObject<T>> {
       const headers = {
          "Content-Type": "application/octet-stream",
          ...(opts?._init?.headers || {}),
@@ -106,10 +109,10 @@ export class MediaApi extends ModuleApi<MediaApiOptions> {
          throw new Error("Invalid filename");
       }
 
-      return this.post(opts?.path ?? ["upload", name], body, init);
+      return this.post<T>(opts?.path ?? ["upload", name], body, init);
    }
 
-   async upload(
+   async upload<T extends FileUploadedEventData>(
       item: Request | Response | string | File | Blob | ReadableStream | Buffer<ArrayBufferLike>,
       opts: {
          filename?: string;
@@ -124,12 +127,12 @@ export class MediaApi extends ModuleApi<MediaApiOptions> {
          if (!res.ok || !res.body) {
             throw new Error("Failed to fetch file");
          }
-         return this.uploadFile(res.body, opts);
+         return this.uploadFile<T>(res.body, opts);
       } else if (item instanceof Response) {
          if (!item.body) {
             throw new Error("Invalid response");
          }
-         return this.uploadFile(item.body, {
+         return this.uploadFile<T>(item.body, {
             ...(opts ?? {}),
             _init: {
                ...(opts._init ?? {}),
@@ -141,7 +144,7 @@ export class MediaApi extends ModuleApi<MediaApiOptions> {
          });
       }
 
-      return this.uploadFile(item, opts);
+      return this.uploadFile<T>(item, opts);
    }
 
    async uploadToEntity(
@@ -153,7 +156,7 @@ export class MediaApi extends ModuleApi<MediaApiOptions> {
          _init?: Omit<RequestInit, "body">;
          fetcher?: typeof fetch;
       },
-   ) {
+   ): Promise<ResponseObject<FileUploadedEventData & { result: DB["media"] }>> {
       return this.upload(item, {
          ...opts,
          path: ["entity", entity, id, field],

app/src/media/api/MediaController.ts

@@ -36,7 +36,7 @@ export class MediaController extends Controller {
             summary: "Get the list of files",
             tags: ["media"],
          }),
-         permission(MediaPermissions.listFiles),
+         permission(MediaPermissions.listFiles, {}),
          async (c) => {
             const files = await this.getStorageAdapter().listObjects();
             return c.json(files);
@@ -51,7 +51,7 @@ export class MediaController extends Controller {
             summary: "Get a file by name",
             tags: ["media"],
          }),
-         permission(MediaPermissions.readFile),
+         permission(MediaPermissions.readFile, {}),
          async (c) => {
             const { filename } = c.req.param();
             if (!filename) {
@@ -81,7 +81,7 @@ export class MediaController extends Controller {
             summary: "Delete a file by name",
             tags: ["media"],
          }),
-         permission(MediaPermissions.deleteFile),
+         permission(MediaPermissions.deleteFile, {}),
          async (c) => {
             const { filename } = c.req.param();
             if (!filename) {
@@ -93,7 +93,10 @@ export class MediaController extends Controller {
          },
       );
 
-      const maxSize = this.getStorage().getConfig().body_max_size ?? Number.POSITIVE_INFINITY;
+      const maxSize =
+         this.media.options.body_max_size ??
+         this.getStorage().getConfig().body_max_size ??
+         Number.POSITIVE_INFINITY;
 
       if (isDebug()) {
          hono.post(
@@ -146,7 +149,7 @@ export class MediaController extends Controller {
             requestBody,
          }),
          jsc("param", s.object({ filename: s.string().optional() })),
-         permission(MediaPermissions.uploadFile),
+         permission(MediaPermissions.uploadFile, {}),
          async (c) => {
             const reqname = c.req.param("filename");
 
@@ -186,7 +189,10 @@ export class MediaController extends Controller {
             }),
          ),
          jsc("query", s.object({ overwrite: s.boolean().optional() })),
-         permission([DataPermissions.entityCreate, MediaPermissions.uploadFile]),
+         permission(DataPermissions.entityCreate, {
+            context: (c) => ({ entity: c.req.param("entity") }),
+         }),
+         permission(MediaPermissions.uploadFile, {}),
          async (c) => {
             const { entity: entity_name, id: entity_id, field: field_name } = c.req.valid("param");
 

app/src/media/media-permissions.ts

@@ -1,4 +1,4 @@
-import { Permission } from "core/security/Permission";
+import { Permission } from "auth/authorize/Permission";
 
 export const readFile = new Permission("media.file.read");
 export const listFiles = new Permission("media.file.list");

app/src/media/media-schema.ts

@@ -48,7 +48,7 @@ export function buildMediaSchema() {
       {
          default: {},
       },
-   );
+   ).strict();
 }
 
 export const mediaConfigSchema = buildMediaSchema();

app/src/modes/code.ts

@@ -0,0 +1,49 @@
+import type { BkndConfig } from "bknd/adapter";
+import { makeModeConfig, type BkndModeConfig } from "./shared";
+import { $console } from "bknd/utils";
+
+export type BkndCodeModeConfig<Args = any> = BkndModeConfig<Args>;
+
+export type CodeMode<AdapterConfig extends BkndConfig> = AdapterConfig extends BkndConfig<
+   infer Args
+>
+   ? BkndModeConfig<Args, AdapterConfig>
+   : never;
+
+export function code<Args>(config: BkndCodeModeConfig<Args>): BkndConfig<Args> {
+   return {
+      ...config,
+      app: async (args) => {
+         const {
+            config: appConfig,
+            plugins,
+            isProd,
+            syncSchemaOptions,
+         } = await makeModeConfig(config, args);
+
+         if (appConfig?.options?.mode && appConfig?.options?.mode !== "code") {
+            $console.warn("You should not set a different mode than `db` when using code mode");
+         }
+
+         return {
+            ...appConfig,
+            options: {
+               ...appConfig?.options,
+               mode: "code",
+               plugins,
+               manager: {
+                  // skip validation in prod for a speed boost
+                  skipValidation: isProd,
+                  onModulesBuilt: async (ctx) => {
+                     if (!isProd && syncSchemaOptions.force) {
+                        $console.log("[code] syncing schema");
+                        await ctx.em.schema().sync(syncSchemaOptions);
+                     }
+                  },
+                  ...appConfig?.options?.manager,
+               },
+            },
+         };
+      },
+   };
+}

app/src/modes/hybrid.ts

@@ -0,0 +1,89 @@
+import type { BkndConfig } from "bknd/adapter";
+import { makeModeConfig, type BkndModeConfig } from "./shared";
+import { getDefaultConfig, type MaybePromise, type ModuleConfigs, type Merge } from "bknd";
+import type { DbModuleManager } from "modules/db/DbModuleManager";
+import { invariant, $console } from "bknd/utils";
+
+export type BkndHybridModeOptions = {
+   /**
+    * Reader function to read the configuration from the file system.
+    * This is required for hybrid mode to work.
+    */
+   reader?: (path: string) => MaybePromise<string>;
+   /**
+    * Provided secrets to be merged into the configuration
+    */
+   secrets?: Record<string, any>;
+};
+
+export type HybridBkndConfig<Args = any> = BkndModeConfig<Args, BkndHybridModeOptions>;
+export type HybridMode<AdapterConfig extends BkndConfig> = AdapterConfig extends BkndConfig<
+   infer Args
+>
+   ? BkndModeConfig<Args, Merge<BkndHybridModeOptions & AdapterConfig>>
+   : never;
+
+export function hybrid<Args>({
+   configFilePath = "bknd-config.json",
+   ...rest
+}: HybridBkndConfig<Args>): BkndConfig<Args> {
+   return {
+      ...rest,
+      config: undefined,
+      app: async (args) => {
+         const {
+            config: appConfig,
+            isProd,
+            plugins,
+            syncSchemaOptions,
+         } = await makeModeConfig(
+            {
+               ...rest,
+               configFilePath,
+            },
+            args,
+         );
+
+         if (appConfig?.options?.mode && appConfig?.options?.mode !== "db") {
+            $console.warn("You should not set a different mode than `db` when using hybrid mode");
+         }
+         invariant(
+            typeof appConfig.reader === "function",
+            "You must set the `reader` option when using hybrid mode",
+         );
+
+         let fileConfig: ModuleConfigs;
+         try {
+            fileConfig = JSON.parse(await appConfig.reader!(configFilePath)) as ModuleConfigs;
+         } catch (e) {
+            const defaultConfig = (appConfig.config ?? getDefaultConfig()) as ModuleConfigs;
+            await appConfig.writer!(configFilePath, JSON.stringify(defaultConfig, null, 2));
+            fileConfig = defaultConfig;
+         }
+
+         return {
+            ...(appConfig as any),
+            beforeBuild: async (app) => {
+               if (app && !isProd) {
+                  const mm = app.modules as DbModuleManager;
+                  mm.buildSyncConfig = syncSchemaOptions;
+               }
+               await appConfig.beforeBuild?.(app);
+            },
+            config: fileConfig,
+            options: {
+               ...appConfig?.options,
+               mode: isProd ? "code" : "db",
+               plugins,
+               manager: {
+                  // skip validation in prod for a speed boost
+                  skipValidation: isProd,
+                  // secrets are required for hybrid mode
+                  secrets: appConfig.secrets,
+                  ...appConfig?.options?.manager,
+               },
+            },
+         };
+      },
+   };
+}

app/src/modes/index.ts

@@ -0,0 +1,3 @@
+export * from "./code";
+export * from "./hybrid";
+export * from "./shared";

app/src/modes/shared.ts

@@ -0,0 +1,183 @@
+import type { AppPlugin, BkndConfig, MaybePromise, Merge } from "bknd";
+import { syncTypes, syncConfig } from "bknd/plugins";
+import { syncSecrets } from "plugins/dev/sync-secrets.plugin";
+import { invariant, $console } from "bknd/utils";
+
+export type BkndModeOptions = {
+   /**
+    * Whether the application is running in production.
+    */
+   isProduction?: boolean;
+   /**
+    * Writer function to write the configuration to the file system
+    */
+   writer?: (path: string, content: string) => MaybePromise<void>;
+   /**
+    * Configuration file path
+    */
+   configFilePath?: string;
+   /**
+    * Types file path
+    * @default "bknd-types.d.ts"
+    */
+   typesFilePath?: string;
+   /**
+    * Syncing secrets options
+    */
+   syncSecrets?: {
+      /**
+       * Whether to enable syncing secrets
+       */
+      enabled?: boolean;
+      /**
+       * Output file path
+       */
+      outFile?: string;
+      /**
+       * Format of the output file
+       * @default "env"
+       */
+      format?: "json" | "env";
+      /**
+       * Whether to include secrets in the output file
+       * @default false
+       */
+      includeSecrets?: boolean;
+   };
+   /**
+    * Determines whether to automatically sync the schema if not in production.
+    * @default true
+    */
+   syncSchema?: boolean | { force?: boolean; drop?: boolean };
+};
+
+export type BkndModeConfig<Args = any, Additional = {}> = BkndConfig<
+   Args,
+   Merge<BkndModeOptions & Additional>
+>;
+
+export async function makeModeConfig<
+   Args = any,
+   Config extends BkndModeConfig<Args> = BkndModeConfig<Args>,
+>({ app, ..._config }: Config, args: Args) {
+   const appConfig = typeof app === "function" ? await app(args) : app;
+
+   const config = {
+      ..._config,
+      ...appConfig,
+   } as Omit<Config, "app">;
+
+   if (typeof config.isProduction !== "boolean") {
+      $console.warn(
+         "You should set `isProduction` option when using managed modes to prevent accidental issues",
+      );
+   }
+
+   invariant(
+      typeof config.writer === "function",
+      "You must set the `writer` option when using managed modes",
+   );
+
+   const { typesFilePath, configFilePath, writer, syncSecrets: syncSecretsOptions } = config;
+
+   const isProd = config.isProduction;
+   const plugins = appConfig?.options?.plugins ?? ([] as AppPlugin[]);
+   const syncSchemaOptions =
+      typeof config.syncSchema === "object"
+         ? config.syncSchema
+         : {
+              force: config.syncSchema !== false,
+              drop: true,
+           };
+
+   if (!isProd) {
+      if (typesFilePath) {
+         if (plugins.some((p) => p.name === "bknd-sync-types")) {
+            throw new Error("You have to unregister the `syncTypes` plugin");
+         }
+         plugins.push(
+            syncTypes({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (et) => {
+                  try {
+                     await config.writer?.(typesFilePath, et.toString());
+                  } catch (e) {
+                     console.error(`Error writing types to"${typesFilePath}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+
+      if (configFilePath) {
+         if (plugins.some((p) => p.name === "bknd-sync-config")) {
+            throw new Error("You have to unregister the `syncConfig` plugin");
+         }
+         plugins.push(
+            syncConfig({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (config) => {
+                  try {
+                     await writer?.(configFilePath, JSON.stringify(config, null, 2));
+                  } catch (e) {
+                     console.error(`Error writing config to "${configFilePath}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+
+      if (syncSecretsOptions && syncSecretsOptions.enabled !== false) {
+         if (plugins.some((p) => p.name === "bknd-sync-secrets")) {
+            throw new Error("You have to unregister the `syncSecrets` plugin");
+         }
+
+         let outFile = syncSecretsOptions.outFile;
+         const format = syncSecretsOptions.format ?? "env";
+         if (!outFile) {
+            outFile = ["env", !syncSecretsOptions.includeSecrets && "example", format]
+               .filter(Boolean)
+               .join(".");
+         }
+
+         plugins.push(
+            syncSecrets({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (secrets) => {
+                  const values = Object.fromEntries(
+                     Object.entries(secrets).map(([key, value]) => [
+                        key,
+                        syncSecretsOptions.includeSecrets ? value : "",
+                     ]),
+                  );
+
+                  try {
+                     if (format === "env") {
+                        await writer?.(
+                           outFile,
+                           Object.entries(values)
+                              .map(([key, value]) => `${key}=${value}`)
+                              .join("\n"),
+                        );
+                     } else {
+                        await writer?.(outFile, JSON.stringify(values, null, 2));
+                     }
+                  } catch (e) {
+                     console.error(`Error writing secrets to "${outFile}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+   }
+
+   return {
+      config,
+      isProd,
+      plugins,
+      syncSchemaOptions,
+   };
+}

app/src/modules/ModuleApi.ts

@@ -8,6 +8,7 @@ export type BaseModuleApiOptions = {
    host: string;
    basepath?: string;
    token?: string;
+   credentials?: RequestCredentials;
    headers?: Headers;
    token_transport?: "header" | "cookie" | "none";
    verbose?: boolean;
@@ -106,6 +107,7 @@ export abstract class ModuleApi<Options extends BaseModuleApiOptions = BaseModul
 
       const request = new Request(url, {
          ..._init,
+         credentials: this.options.credentials,
          method,
          body,
          headers,

app/src/modules/ModuleHelper.ts

@@ -5,7 +5,7 @@ import { entityTypes } from "data/entities/Entity";
 import { isEqual } from "lodash-es";
 import type { ModuleBuildContext, ModuleBuildContextMcpContext } from "./Module";
 import type { EntityRelation } from "data/relations";
-import type { Permission } from "core/security/Permission";
+import type { Permission, PermissionContext } from "auth/authorize/Permission";
 import { Exception } from "core/errors";
 import { invariant, isPlainObject } from "bknd/utils";
 
@@ -114,10 +114,20 @@ export class ModuleHelper {
       entity.__replaceField(name, newField);
    }
 
-   async throwUnlessGranted(
+   async granted<P extends Permission<any, any, any, any>>(
-      permission: Permission | string,
       c: { context: ModuleBuildContextMcpContext; raw?: unknown },
-   ) {
+      permission: P,
+      context: PermissionContext<P>,
+   ): Promise<void>;
+   async granted<P extends Permission<any, any, undefined, any>>(
+      c: { context: ModuleBuildContextMcpContext; raw?: unknown },
+      permission: P,
+   ): Promise<void>;
+   async granted<P extends Permission<any, any, any, any>>(
+      c: { context: ModuleBuildContextMcpContext; raw?: unknown },
+      permission: P,
+      context?: PermissionContext<P>,
+   ): Promise<void> {
       invariant(c.context.app, "app is not available in mcp context");
       const auth = c.context.app.module.auth;
       if (!auth.enabled) return;
@@ -127,12 +137,6 @@ export class ModuleHelper {
       }
 
       const user = await auth.authenticator?.resolveAuthFromRequest(c.raw as any);
-
+      this.ctx.guard.granted(permission, user as any, context as any);
-      if (!this.ctx.guard.granted(permission, user)) {
-         throw new Exception(
-            `Permission "${typeof permission === "string" ? permission : permission.name}" not granted`,
-            403,
-         );
-      }
    }
 }

app/src/modules/SystemApi.ts

@@ -1,6 +1,7 @@
 import type { ConfigUpdateResponse } from "modules/server/SystemController";
 import { ModuleApi } from "./ModuleApi";
 import type { ModuleConfigs, ModuleKey, ModuleSchemas } from "./ModuleManager";
+import type { TPermission } from "auth/authorize/Permission";
 
 export type ApiSchemaResponse = {
    version: number;
@@ -54,4 +55,8 @@ export class SystemApi extends ModuleApi<any> {
    removeConfig<Module extends ModuleKey>(module: Module, path: string) {
       return this.delete<ConfigUpdateResponse>(["config", "remove", module, path]);
    }
+
+   permissions() {
+      return this.get<{ permissions: TPermission[]; context: object }>("permissions");
+   }
 }

app/src/modules/db/DbModuleManager.ts

@@ -70,6 +70,9 @@ export class DbModuleManager extends ModuleManager {
    private readonly _booted_with?: "provided" | "partial";
    private _stable_configs: ModuleConfigs | undefined;
 
+   // config used when syncing database
+   public buildSyncConfig: { force?: boolean; drop?: boolean } = { force: true };
+
    constructor(connection: Connection, options?: Partial<ModuleManagerOptions>) {
       let initial = {} as InitialModuleConfigs;
       let booted_with = "partial" as any;
@@ -393,7 +396,7 @@ export class DbModuleManager extends ModuleManager {
 
                const version_before = this.version();
                const [_version, _configs] = await migrate(version_before, result.configs.json, {
-                  db: this.db
+                  db: this.db,
                });
 
                this._version = _version;
@@ -463,7 +466,7 @@ export class DbModuleManager extends ModuleManager {
             this.logger.log("db sync requested");
 
             // sync db
-            await ctx.em.schema().sync({ force: true });
+            await ctx.em.schema().sync(this.buildSyncConfig);
             state.synced = true;
 
             // save

app/src/modules/db/migrations.ts

@@ -1,6 +1,7 @@
 import { transformObject } from "bknd/utils";
 import type { Kysely } from "kysely";
 import { set } from "lodash-es";
+import type { InitialModuleConfigs } from "modules/ModuleManager";
 
 export type MigrationContext = {
    db: Kysely<any>;
@@ -107,6 +108,29 @@ export const migrations: Migration[] = [
          return config;
       },
    },
+   {
+      // change field.config.fillable to only "create" and "update"
+      version: 11,
+      up: async (config: InitialModuleConfigs) => {
+         const { data, ...rest } = config;
+         return {
+            ...rest,
+            data: {
+               ...data,
+               entities: transformObject(data?.entities ?? {}, (entity) => {
+                  return {
+                     ...entity,
+                     fields: transformObject(entity?.fields ?? {}, (field) => {
+                        const fillable = field!.config?.fillable;
+                        if (!fillable || typeof fillable === "boolean") return field;
+                        return { ...field, config: { ...field!.config, fillable: true } };
+                     }),
+                  };
+               }),
+            },
+         };
+      },
+   },
 ];
 
 export const CURRENT_VERSION = migrations[migrations.length - 1]?.version ?? 0;

app/src/modules/middlewares/index.ts

@@ -1 +1,2 @@
-export { auth, permission } from "auth/middlewares";
+export { auth } from "auth/middlewares/auth.middleware";
+export { permission } from "auth/middlewares/permission.middleware";

app/src/modules/permissions/index.ts

@@ -1,10 +1,35 @@
-import { Permission } from "core/security/Permission";
+import { Permission } from "auth/authorize/Permission";
+import { s } from "bknd/utils";
 
 export const accessAdmin = new Permission("system.access.admin");
 export const accessApi = new Permission("system.access.api");
-export const configRead = new Permission("system.config.read");
+export const configRead = new Permission(
-export const configReadSecrets = new Permission("system.config.read.secrets");
+   "system.config.read",
-export const configWrite = new Permission("system.config.write");
+   {},
-export const schemaRead = new Permission("system.schema.read");
+   s.object({
+      module: s.string().optional(),
+   }),
+);
+export const configReadSecrets = new Permission(
+   "system.config.read.secrets",
+   {},
+   s.object({
+      module: s.string().optional(),
+   }),
+);
+export const configWrite = new Permission(
+   "system.config.write",
+   {},
+   s.object({
+      module: s.string().optional(),
+   }),
+);
+export const schemaRead = new Permission(
+   "system.schema.read",
+   {},
+   s.object({
+      module: s.string().optional(),
+   }),
+);
 export const build = new Permission("system.build");
 export const mcp = new Permission("system.mcp");

app/src/modules/server/AdminController.tsx

@@ -114,8 +114,9 @@ export class AdminController extends Controller {
             }),
             permission(SystemPermissions.schemaRead, {
                onDenied: async (c) => {
-                  addFlashMessage(c, "You not allowed to read the schema", "warning");
+                  addFlashMessage(c, "You are not allowed to read the schema", "warning");
                },
+               context: (c) => ({}),
             }),
             async (c) => {
                const obj: AdminBkndWindowContext = {
@@ -139,17 +140,19 @@ export class AdminController extends Controller {
       }
 
       if (auth_enabled) {
+         const options = {
+            onGranted: async (c) => {
+               // @todo: add strict test to permissions middleware?
+               if (c.get("auth")?.user) {
+                  $console.log("redirecting to success");
+                  return c.redirect(authRoutes.success);
+               }
+            },
+            context: (c) => ({}),
+         };
          const redirectRouteParams = [
-            permission([SystemPermissions.accessAdmin, SystemPermissions.schemaRead], {
+            permission(SystemPermissions.accessAdmin, options as any),
-               // @ts-ignore
+            permission(SystemPermissions.schemaRead, options),
-               onGranted: async (c) => {
-                  // @todo: add strict test to permissions middleware?
-                  if (c.get("auth")?.user) {
-                     $console.log("redirecting to success");
-                     return c.redirect(authRoutes.success);
-                  }
-               },
-            }),
             async (c) => {
                return c.html(c.get("html")!);
             },

app/src/modules/server/AppServer.ts

@@ -52,11 +52,16 @@ export class AppServer extends Module<AppServerConfig> {
    }
 
    override async build() {
-      const origin = this.config.cors.origin ?? "";
+      const origin = this.config.cors.origin ?? "*";
+      const origins = origin.includes(",") ? origin.split(",").map((o) => o.trim()) : [origin];
+      const all_origins = origins.includes("*");
       this.client.use(
          "*",
          cors({
-            origin: origin.includes(",") ? origin.split(",").map((o) => o.trim()) : origin,
+            origin: (origin: string) => {
+               if (all_origins) return origin;
+               return origins.includes(origin) ? origin : undefined;
+            },
             allowMethods: this.config.cors.allow_methods,
             allowHeaders: this.config.cors.allow_headers,
             credentials: this.config.cors.allow_credentials,
@@ -87,6 +92,10 @@ export class AppServer extends Module<AppServerConfig> {
          }
 
          if (err instanceof AuthException) {
+            if (isDebug()) {
+               return c.json(err.toJSON(), err.code);
+            }
+
             return c.json(err.toJSON(), err.getSafeErrorAndCode().code);
          }
 

app/src/modules/server/SystemController.ts

@@ -17,6 +17,7 @@ import {
    mcp as mcpMiddleware,
    isNode,
    type McpServer,
+   threw,
 } from "bknd/utils";
 import type { Context, Hono } from "hono";
 import { Controller } from "modules/Controller";
@@ -32,6 +33,7 @@ import { getVersion } from "core/env";
 import type { Module } from "modules/Module";
 import { getSystemMcp } from "modules/mcp/system-mcp";
 import type { DbModuleManager } from "modules/db/DbModuleManager";
+import type { TPermission } from "auth/authorize/Permission";
 
 export type ConfigUpdate<Key extends ModuleKey = ModuleKey> = {
    success: true;
@@ -46,7 +48,8 @@ export type SchemaResponse = {
    schema: ModuleSchemas;
    readonly: boolean;
    config: ModuleConfigs;
-   permissions: string[];
+   //permissions: string[];
+   permissions: TPermission[];
 };
 
 export class SystemController extends Controller {
@@ -67,10 +70,14 @@ export class SystemController extends Controller {
       if (!config.mcp.enabled) {
          return;
       }
+      const { permission, auth } = this.middlewares;
 
       this.registerMcp();
 
-      app.server.use(
+      app.server.all(
+         config.mcp.path,
+         auth(),
+         permission(SystemPermissions.mcp, {}),
          mcpMiddleware({
             setup: async () => {
                if (!this._mcpServer) {
@@ -108,7 +115,6 @@ export class SystemController extends Controller {
                explainEndpoint: true,
             },
             endpoint: {
-               path: config.mcp.path as any,
                // @ts-ignore
                _init: isNode() ? { duplex: "half" } : {},
             },
@@ -119,7 +125,7 @@ export class SystemController extends Controller {
    private registerConfigController(client: Hono<any>): void {
       const { permission } = this.middlewares;
       // don't add auth again, it's already added in getController
-      const hono = this.create().use(permission(SystemPermissions.configRead));
+      const hono = this.create(); /* .use(permission(SystemPermissions.configRead)); */
 
       if (!this.app.isReadOnly()) {
          const manager = this.app.modules as DbModuleManager;
@@ -130,7 +136,11 @@ export class SystemController extends Controller {
                summary: "Get the raw config",
                tags: ["system"],
             }),
-            permission([SystemPermissions.configReadSecrets]),
+            permission(SystemPermissions.configReadSecrets, {
+               context: (c) => ({
+                  module: c.req.param("module"),
+               }),
+            }),
             async (c) => {
                // @ts-expect-error "fetch" is private
                return c.json(await this.app.modules.fetch().then((r) => r?.configs));
@@ -165,7 +175,11 @@ export class SystemController extends Controller {
 
          hono.post(
             "/set/:module",
-            permission(SystemPermissions.configWrite),
+            permission(SystemPermissions.configWrite, {
+               context: (c) => ({
+                  module: c.req.param("module"),
+               }),
+            }),
             jsc("query", s.object({ force: s.boolean().optional() }), { skipOpenAPI: true }),
             async (c) => {
                const module = c.req.param("module") as any;
@@ -194,32 +208,44 @@ export class SystemController extends Controller {
             },
          );
 
-         hono.post("/add/:module/:path", permission(SystemPermissions.configWrite), async (c) => {
+         hono.post(
-            // @todo: require auth (admin)
+            "/add/:module/:path",
-            const module = c.req.param("module") as any;
+            permission(SystemPermissions.configWrite, {
-            const value = await c.req.json();
+               context: (c) => ({
-            const path = c.req.param("path") as string;
+                  module: c.req.param("module"),
+               }),
+            }),
+            async (c) => {
+               // @todo: require auth (admin)
+               const module = c.req.param("module") as any;
+               const value = await c.req.json();
+               const path = c.req.param("path") as string;
 
-            if (this.app.modules.get(module).schema().has(path)) {
+               if (this.app.modules.get(module).schema().has(path)) {
-               return c.json(
+                  return c.json(
-                  { success: false, path, error: "Path already exists" },
+                     { success: false, path, error: "Path already exists" },
-                  { status: 400 },
+                     { status: 400 },
-               );
+                  );
-            }
+               }
 
-            return await handleConfigUpdateResponse(c, async () => {
+               return await handleConfigUpdateResponse(c, async () => {
-               await manager.mutateConfigSafe(module).patch(path, value);
+                  await manager.mutateConfigSafe(module).patch(path, value);
-               return {
+                  return {
-                  success: true,
+                     success: true,
-                  module,
+                     module,
-                  config: this.app.module[module].config,
+                     config: this.app.module[module].config,
-               };
+                  };
-            });
+               });
-         });
+            },
+         );
 
          hono.patch(
             "/patch/:module/:path",
-            permission(SystemPermissions.configWrite),
+            permission(SystemPermissions.configWrite, {
+               context: (c) => ({
+                  module: c.req.param("module"),
+               }),
+            }),
             async (c) => {
                // @todo: require auth (admin)
                const module = c.req.param("module") as any;
@@ -239,7 +265,11 @@ export class SystemController extends Controller {
 
          hono.put(
             "/overwrite/:module/:path",
-            permission(SystemPermissions.configWrite),
+            permission(SystemPermissions.configWrite, {
+               context: (c) => ({
+                  module: c.req.param("module"),
+               }),
+            }),
             async (c) => {
                // @todo: require auth (admin)
                const module = c.req.param("module") as any;
@@ -259,7 +289,11 @@ export class SystemController extends Controller {
 
          hono.delete(
             "/remove/:module/:path",
-            permission(SystemPermissions.configWrite),
+            permission(SystemPermissions.configWrite, {
+               context: (c) => ({
+                  module: c.req.param("module"),
+               }),
+            }),
             async (c) => {
                // @todo: require auth (admin)
                const module = c.req.param("module") as any;
@@ -295,7 +329,11 @@ export class SystemController extends Controller {
             const { secrets } = c.req.valid("query");
             const { module } = c.req.valid("param");
 
-            secrets && this.ctx.guard.throwUnlessGranted(SystemPermissions.configReadSecrets, c);
+            if (secrets) {
+               this.ctx.guard.granted(SystemPermissions.configReadSecrets, c, {
+                  module,
+               });
+            }
 
             const config = this.app.toJSON(secrets);
 
@@ -326,7 +364,11 @@ export class SystemController extends Controller {
             summary: "Get the schema for a module",
             tags: ["system"],
          }),
-         permission(SystemPermissions.schemaRead),
+         permission(SystemPermissions.schemaRead, {
+            context: (c) => ({
+               module: c.req.param("module"),
+            }),
+         }),
          jsc(
             "query",
             s
@@ -340,10 +382,22 @@ export class SystemController extends Controller {
          async (c) => {
             const module = c.req.param("module") as ModuleKey | undefined;
             const { config, secrets, fresh } = c.req.valid("query");
-            const readonly = this.app.isReadOnly();
+            const readonly =
+               // either if app is read only in general
+               this.app.isReadOnly() ||
+               // or if user is not allowed to modify the config
+               threw(() => this.ctx.guard.granted(SystemPermissions.configWrite, c, { module }));
 
-            config && this.ctx.guard.throwUnlessGranted(SystemPermissions.configRead, c);
+            if (config) {
-            secrets && this.ctx.guard.throwUnlessGranted(SystemPermissions.configReadSecrets, c);
+               this.ctx.guard.granted(SystemPermissions.configRead, c, {
+                  module,
+               });
+            }
+            if (secrets) {
+               this.ctx.guard.granted(SystemPermissions.configReadSecrets, c, {
+                  module,
+               });
+            }
 
             const { version, ...schema } = this.app.getSchema();
 
@@ -368,11 +422,23 @@ export class SystemController extends Controller {
                readonly,
                schema,
                config: config ? this.app.toJSON(secrets) : undefined,
-               permissions: this.app.modules.ctx().guard.getPermissionNames(),
+               permissions: this.app.modules.ctx().guard.getPermissions(),
             });
          },
       );
 
+      hono.get(
+         "/permissions",
+         describeRoute({
+            summary: "Get the permissions",
+            tags: ["system"],
+         }),
+         (c) => {
+            const permissions = this.app.modules.ctx().guard.getPermissions();
+            return c.json({ permissions, context: this.app.module.auth.getGuardContextSchema() });
+         },
+      );
+
       hono.post(
          "/build",
          describeRoute({
@@ -383,7 +449,7 @@ export class SystemController extends Controller {
          jsc("query", s.object({ sync: s.boolean().optional(), fetch: s.boolean().optional() })),
          async (c) => {
             const options = c.req.valid("query") as Record<string, boolean>;
-            this.ctx.guard.throwUnlessGranted(SystemPermissions.build, c);
+            this.ctx.guard.granted(SystemPermissions.build, c);
 
             await this.app.build(options);
             return c.json({
@@ -455,7 +521,7 @@ export class SystemController extends Controller {
       const { version, ...appConfig } = this.app.toJSON();
 
       mcp.resource("system_config", "bknd://system/config", async (c) => {
-         await c.context.ctx().helper.throwUnlessGranted(SystemPermissions.configRead, c);
+         await c.context.ctx().helper.granted(c, SystemPermissions.configRead, {});
 
          return c.json(this.app.toJSON(), {
             title: "System Config",
@@ -465,7 +531,9 @@ export class SystemController extends Controller {
             "system_config_module",
             "bknd://system/config/{module}",
             async (c, { module }) => {
-               await this.ctx.helper.throwUnlessGranted(SystemPermissions.configRead, c);
+               await this.ctx.helper.granted(c, SystemPermissions.configRead, {
+                  module,
+               });
 
                const m = this.app.modules.get(module as any) as Module;
                return c.json(m.toJSON(), {
@@ -477,7 +545,7 @@ export class SystemController extends Controller {
             },
          )
          .resource("system_schema", "bknd://system/schema", async (c) => {
-            await this.ctx.helper.throwUnlessGranted(SystemPermissions.schemaRead, c);
+            await this.ctx.helper.granted(c, SystemPermissions.schemaRead, {});
 
             return c.json(this.app.getSchema(), {
                title: "System Schema",
@@ -487,7 +555,9 @@ export class SystemController extends Controller {
             "system_schema_module",
             "bknd://system/schema/{module}",
             async (c, { module }) => {
-               await this.ctx.helper.throwUnlessGranted(SystemPermissions.schemaRead, c);
+               await this.ctx.helper.granted(c, SystemPermissions.schemaRead, {
+                  module,
+               });
 
                const m = this.app.modules.get(module as any);
                return c.json(m.getSchema().toJSON(), {

app/src/plugins/data/timestamp.plugin.spec.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { timestamps } from "./timestamps.plugin";
+import { em, entity, text } from "bknd";
+import { createApp } from "core/test/utils";
+import { disableConsoleLog, enableConsoleLog } from "core/utils/test";
+
+beforeAll(() => disableConsoleLog());
+afterAll(enableConsoleLog);
+
+describe("timestamps plugin", () => {
+   test("should ignore if no or invalid entities are provided", async () => {
+      const app = createApp({
+         options: {
+            plugins: [timestamps({ entities: [] })],
+         },
+      });
+      await app.build();
+      expect(app.em.entities.map((e) => e.name)).toEqual([]);
+
+      {
+         const app = createApp({
+            options: {
+               plugins: [timestamps({ entities: ["posts"] })],
+            },
+         });
+         await app.build();
+         expect(app.em.entities.map((e) => e.name)).toEqual([]);
+      }
+   });
+
+   test("should add timestamps to the specified entities", async () => {
+      const app = createApp({
+         config: {
+            data: em({
+               posts: entity("posts", {
+                  title: text(),
+               }),
+            }).toJSON(),
+         },
+         options: {
+            plugins: [timestamps({ entities: ["posts", "invalid"] })],
+         },
+      });
+      await app.build();
+      expect(app.em.entities.map((e) => e.name)).toEqual(["posts"]);
+      expect(app.em.entity("posts")?.fields.map((f) => f.name)).toEqual([
+         "id",
+         "title",
+         "created_at",
+         "updated_at",
+      ]);
+
+      // insert
+      const mutator = app.em.mutator(app.em.entity("posts"));
+      const { data } = await mutator.insertOne({ title: "Hello" });
+      expect(data.created_at).toBeDefined();
+      expect(data.updated_at).toBeDefined();
+      expect(data.created_at).toBeInstanceOf(Date);
+      expect(data.updated_at).toBeInstanceOf(Date);
+      const diff = data.created_at.getTime() - data.updated_at.getTime();
+      expect(diff).toBeLessThan(10);
+      expect(diff).toBeGreaterThan(-1);
+
+      // update (set updated_at to null, otherwise it's too fast to test)
+      await app.em.connection.kysely
+         .updateTable("posts")
+         .set({ updated_at: null })
+         .where("id", "=", data.id)
+         .execute();
+      const { data: updatedData } = await mutator.updateOne(data.id, { title: "Hello 2" });
+      expect(updatedData.updated_at).toBeDefined();
+      expect(updatedData.updated_at).toBeInstanceOf(Date);
+   });
+});

app/src/plugins/data/timestamps.plugin.ts

@@ -0,0 +1,86 @@
+import { type App, type AppPlugin, em, entity, datetime, DatabaseEvents } from "bknd";
+import { $console } from "bknd/utils";
+
+export type TimestampsPluginOptions = {
+   entities: string[];
+   setUpdatedOnCreate?: boolean;
+};
+
+/**
+ * This plugin adds `created_at` and `updated_at` fields to the specified entities.
+ * Add it to your plugins in `bknd.config.ts` like this:
+ *
+ * ```ts
+ * export default {
+ *    plugins: [timestamps({ entities: ["posts"] })],
+ * }
+ * ```
+ */
+export function timestamps({
+   entities = [],
+   setUpdatedOnCreate = true,
+}: TimestampsPluginOptions): AppPlugin {
+   return (app: App) => ({
+      name: "timestamps",
+      schema: () => {
+         if (entities.length === 0) {
+            $console.warn("No entities specified for timestamps plugin");
+            return;
+         }
+
+         const appEntities = app.em.entities.map((e) => e.name);
+
+         return em(
+            Object.fromEntries(
+               entities
+                  .filter((e) => appEntities.includes(e))
+                  .map((e) => [
+                     e,
+                     entity(e, {
+                        created_at: datetime(),
+                        updated_at: datetime(),
+                     }),
+                  ]),
+            ),
+         );
+      },
+      onBuilt: async () => {
+         app.emgr.onEvent(
+            DatabaseEvents.MutatorInsertBefore,
+            (event) => {
+               const { entity, data } = event.params;
+               if (entities.includes(entity.name)) {
+                  return {
+                     ...data,
+                     created_at: new Date(),
+                     updated_at: setUpdatedOnCreate ? new Date() : null,
+                  };
+               }
+               return data;
+            },
+            {
+               mode: "sync",
+               id: "bknd-timestamps",
+            },
+         );
+
+         app.emgr.onEvent(
+            DatabaseEvents.MutatorUpdateBefore,
+            async (event) => {
+               const { entity, data } = event.params;
+               if (entities.includes(entity.name)) {
+                  return {
+                     ...data,
+                     updated_at: new Date(),
+                  };
+               }
+               return data;
+            },
+            {
+               mode: "sync",
+               id: "bknd-timestamps",
+            },
+         );
+      },
+   });
+}

app/src/plugins/index.ts

@@ -7,3 +7,4 @@ export { showRoutes, type ShowRoutesOptions } from "./dev/show-routes.plugin";
 export { syncConfig, type SyncConfigOptions } from "./dev/sync-config.plugin";
 export { syncTypes, type SyncTypesOptions } from "./dev/sync-types.plugin";
 export { syncSecrets, type SyncSecretsOptions } from "./dev/sync-secrets.plugin";
+export { timestamps, type TimestampsPluginOptions } from "./data/timestamps.plugin";

app/src/ui/client/BkndProvider.tsx

@@ -15,13 +15,14 @@ import { AppReduced } from "./utils/AppReduced";
 import { Message } from "ui/components/display/Message";
 import { useNavigate } from "ui/lib/routes";
 import type { BkndAdminProps } from "ui/Admin";
+import type { TPermission } from "auth/authorize/Permission";
 
 export type BkndContext = {
    version: number;
    readonly: boolean;
    schema: ModuleSchemas;
    config: ModuleConfigs;
-   permissions: string[];
+   permissions: TPermission[];
    hasSecrets: boolean;
    requireSecrets: () => Promise<void>;
    actions: ReturnType<typeof getSchemaActions>;
@@ -122,11 +123,14 @@ export function BkndProvider({
             fetching.current = Fetching.None;
          };
 
-         if ("startViewTransition" in document) {
+         // disable view transitions for now
+         // because it causes browser crash on heavy pages (e.g. schema)
+         commit();
+         /* if ("startViewTransition" in document) {
             document.startViewTransition(commit);
          } else {
             commit();
-         }
+         } */
       });
    }
 

app/src/ui/client/ClientProvider.tsx

@@ -53,9 +53,7 @@ export const ClientProvider = ({
       [JSON.stringify(apiProps)],
    );
 
-   const [authState, setAuthState] = useState<Partial<AuthState> | undefined>(
+   const [authState, setAuthState] = useState<Partial<AuthState> | undefined>(api.getAuthState());
-      apiProps.user ? api.getAuthState() : undefined,
-   );
 
    return (
       <ClientContext.Provider value={{ baseUrl: api.baseUrl, api, authState }}>

app/src/ui/client/api/use-api.ts

@@ -1,6 +1,6 @@
 import type { Api } from "Api";
 import { FetchPromise, type ModuleApi, type ResponseObject } from "modules/ModuleApi";
-import useSWR, { type SWRConfiguration, useSWRConfig } from "swr";
+import useSWR, { type SWRConfiguration, useSWRConfig, type Middleware, type SWRHook } from "swr";
 import useSWRInfinite from "swr/infinite";
 import { useApi } from "ui/client";
 import { useState } from "react";
@@ -35,7 +35,7 @@ export const useApiInfiniteQuery = <
    RefineFn extends (data: ResponseObject<Data>) => unknown = (data: ResponseObject<Data>) => Data,
 >(
    fn: (api: Api, page: number) => FetchPromise<Data>,
-   options?: SWRConfiguration & { refine?: RefineFn },
+   options?: SWRConfiguration & { refine?: RefineFn; pageSize?: number },
 ) => {
    const [endReached, setEndReached] = useState(false);
    const api = useApi();
@@ -47,7 +47,7 @@ export const useApiInfiniteQuery = <
    // @ts-ignore
    const swr = useSWRInfinite<RefinedData>(
       (index, previousPageData: any) => {
-         if (previousPageData && !previousPageData.length) {
+         if (index > 0 && previousPageData && previousPageData.length < (options?.pageSize ?? 0)) {
             setEndReached(true);
             return null; // reached the end
          }
@@ -89,3 +89,25 @@ export const useInvalidate = (options?: { exact?: boolean }) => {
       return mutate((k) => typeof k === "string" && k.startsWith(key));
    };
 };
+
+const mountOnceCache = new Map<string, any>();
+
+/**
+ * Simple middleware to only load on first mount.
+ */
+export const mountOnce: Middleware = (useSWRNext: SWRHook) => (key, fetcher, config) => {
+   if (typeof key === "string") {
+      if (mountOnceCache.has(key)) {
+         return useSWRNext(key, fetcher, {
+            ...config,
+            revalidateOnMount: false,
+         });
+      }
+      const swr = useSWRNext(key, fetcher, config);
+      if (swr.data) {
+         mountOnceCache.set(key, true);
+      }
+      return swr;
+   }
+   return useSWRNext(key, fetcher, config);
+};

app/src/ui/client/api/use-entity.ts

@@ -1,8 +1,14 @@
-import type { DB, PrimaryFieldType, EntityData, RepoQueryIn } from "bknd";
+import type {
+   DB,
+   PrimaryFieldType,
+   EntityData,
+   RepoQueryIn,
+   RepositoryResult,
+   ResponseObject,
+   ModuleApi,
+} from "bknd";
 import { objectTransform, encodeSearch } from "bknd/utils";
-import type { RepositoryResult } from "data/entities";
 import type { Insertable, Selectable, Updateable } from "kysely";
-import type { FetchPromise, ModuleApi, ResponseObject } from "modules/ModuleApi";
 import useSWR, { type SWRConfiguration, type SWRResponse, mutate } from "swr";
 import { type Api, useApi } from "ui/client";
 
@@ -108,7 +114,7 @@ export function makeKey(
    );
 }
 
-interface UseEntityQueryReturn<
+export interface UseEntityQueryReturn<
    Entity extends keyof DB | string,
    Id extends PrimaryFieldType | undefined = undefined,
    Data = Entity extends keyof DB ? Selectable<DB[Entity]> : EntityData,
@@ -136,11 +142,11 @@ export const useEntityQuery = <
    const fetcher = () => read(query ?? {});
 
    type T = Awaited<ReturnType<typeof fetcher>>;
-   const swr = useSWR<T>(options?.enabled === false ? null : key, fetcher as any, {
+   const swr = useSWR(options?.enabled === false ? null : key, fetcher as any, {
       revalidateOnFocus: false,
       keepPreviousData: true,
       ...options,
-   });
+   }) as ReturnType<typeof useSWR<T>>;
 
    const mutateFn = async (id?: PrimaryFieldType) => {
       const entityKey = makeKey(api, entity as string, id);

app/src/ui/client/schema/auth/use-auth.ts

@@ -16,8 +16,8 @@ type UseAuth = {
    verified: boolean;
    login: (data: LoginData) => Promise<AuthResponse>;
    register: (data: LoginData) => Promise<AuthResponse>;
-   logout: () => void;
+   logout: () => Promise<void>;
-   verify: () => void;
+   verify: () => Promise<void>;
    setToken: (token: string) => void;
 };
 
@@ -42,12 +42,13 @@ export const useAuth = (options?: { baseUrl?: string }): UseAuth => {
    }
 
    async function logout() {
-      api.updateToken(undefined);
+      await api.auth.logout();
-      invalidate();
+      await invalidate();
    }
 
    async function verify() {
       await api.verifyAuth();
+      await invalidate();
    }
 
    return {