enhance Guard and permission handling with new test cases

- Updated the `Guard` class to improve context validation and permission checks, ensuring clearer error messages for unmet conditions.
- Refactored the `Policy` and `RolePermission` classes to support default effects and better handle conditions and filters.
- Enhanced tests in `authorize.spec.ts` and `permissions.spec.ts` to cover new permission scenarios, including guest and member role behaviors.
- Added new tests for context validation in permission middleware, ensuring robust error handling for invalid contexts.
- Improved utility functions for better integration with the updated permission structure.

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

@@ -1,19 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { Guard, type GuardConfig } from "auth/authorize/Guard";
 import { Permission } from "auth/authorize/Permission";
-import { Role } from "auth/authorize/Role";
-import { objectTransform } from "bknd/utils";
+import { Role, type RoleSchema } from "auth/authorize/Role";
+import { objectTransform, s } from "bknd/utils";
 
 function createGuard(
    permissionNames: string[],
-   roles?: Record<
-      string,
-      {
-         permissions?: string[];
-         is_default?: boolean;
-         implicit_allow?: boolean;
-      }
-   >,
+   roles?: Record<string, Omit<RoleSchema, "name">>,
    config?: GuardConfig,
 ) {
    const _roles = roles
@@ -26,7 +19,9 @@ function createGuard(
 }
 
 describe("authorize", () => {
-   const read = new Permission("read");
+   const read = new Permission("read", {
+      filterable: true,
+   });
    const write = new Permission("write");
 
    test("basic", async () => {
@@ -109,4 +104,140 @@ describe("authorize", () => {
       expect(guard.granted(read, {})).toBeUndefined();
       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.getPolicyFilter(read, { role: "member" })).toEqual({
+            type: "member",
+         });
+
+         // get filter for guest
+         expect(guard.getPolicyFilter(read, {})).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.getPolicyFilter(read, {}, { entity: "posts" })).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.getPolicyFilter(read, { role: "member" }, { entity: "posts" }),
+         ).toBeUndefined();
+      });
+   });
 });