refactor: enhance permission handling and introduce new Permission and Policy classes

- Updated the `Guard` class to improve permission checking by utilizing the new `Permission` class.
- Refactored tests in `authorize.spec.ts` to use `Permission` instances instead of strings for better type safety.
- Introduced a new `permissions.spec.ts` file to test the functionality of the `Permission` and `Policy` classes.
- Enhanced the `recursivelyReplacePlaceholders` utility function to support various object structures and types.
- Updated middleware and controller files to align with the new permission handling structure.

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

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { Guard } from "../../../src/auth/authorize/Guard";
+import { Guard } from "auth/authorize/Guard";
+import { Permission } from "core/security/Permission";
 
 describe("authorize", () => {
+   const read = new Permission("read");
+   const write = new Permission("write");
+
    test("basic", async () => {
       const guard = Guard.create(
          ["read", "write"],
@@ -16,10 +20,10 @@ describe("authorize", () => {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(read, user)).toBe(true);
+      expect(guard.granted(write, user)).toBe(true);
 
-      expect(() => guard.granted("something")).toThrow();
+      expect(() => guard.granted(new Permission("something"))).toThrow();
    });
 
    test("with default", async () => {
@@ -37,22 +41,22 @@ describe("authorize", () => {
          { enabled: true },
       );
 
-      expect(guard.granted("read")).toBe(true);
-      expect(guard.granted("write")).toBe(false);
+      expect(guard.granted(read)).toBe(true);
+      expect(guard.granted(write)).toBe(false);
 
       const user = {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(read, user)).toBe(true);
+      expect(guard.granted(write, user)).toBe(true);
    });
 
    test("guard implicit allow", async () => {
       const guard = Guard.create([], {}, { enabled: false });
 
-      expect(guard.granted("read")).toBe(true);
-      expect(guard.granted("write")).toBe(true);
+      expect(guard.granted(read)).toBe(true);
+      expect(guard.granted(write)).toBe(true);
    });
 
    test("role implicit allow", async () => {
@@ -66,8 +70,8 @@ describe("authorize", () => {
          role: "admin",
       };
 
-      expect(guard.granted("read", user)).toBe(true);
-      expect(guard.granted("write", user)).toBe(true);
+      expect(guard.granted(read, user)).toBe(true);
+      expect(guard.granted(write, user)).toBe(true);
    });
 
    test("guard with guest role implicit allow", async () => {
@@ -79,7 +83,7 @@ describe("authorize", () => {
       });
 
       expect(guard.getUserRole()?.name).toBe("guest");
-      expect(guard.granted("read")).toBe(true);
-      expect(guard.granted("write")).toBe(true);
+      expect(guard.granted(read)).toBe(true);
+      expect(guard.granted(write)).toBe(true);
    });
 });

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

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "bun:test";
+import { s } from "bknd/utils";
+import { Permission, Policy } from "core/security/Permission";
+
+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);
+   });
+});