@emkodev/emkore 1.0.3 → 1.1.0

package/test/unit/authorization-constraints.test.ts

@@ -0,0 +1,1001 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test";
+import { Actor } from "../../src/common/abstract.actor.ts";
+import { Usecase } from "../../src/common/abstract.usecase.ts";
+import { AuthorizationInterceptor } from "../../src/common/interceptor/authorization.interceptor.ts";
+import { AuthorizationException } from "../../src/common/exception/authorization-exception.ts";
+import {
+  type Permission,
+  ResourceScope,
+} from "../../src/common/type/permission.type.ts";
+import type { ApiDefinition } from "../../src/common/llm/api-definition.type.ts";
+import type { UsecaseName } from "../../src/common/abstract.usecase.ts";
+
+class TestActor extends Actor {
+  constructor(
+    private _id: string,
+    private _businessId: string,
+    private _token: string,
+    permissions: Permission[] = [],
+  ) {
+    super();
+    this.permissions = permissions;
+  }
+
+  get id(): string {
+    return this._id;
+  }
+
+  get businessId(): string {
+    return this._businessId;
+  }
+
+  get token(): string {
+    return this._token;
+  }
+}
+
+class TestUsecase extends Usecase<void, void> {
+  override readonly usecaseName: UsecaseName;
+  override readonly apiDefinition: ApiDefinition = {
+    description: "test",
+    input: {},
+    output: {},
+  };
+
+  private _requiredPermissions: Permission[];
+
+  constructor(name: UsecaseName, requiredPermissions: Permission[]) {
+    super();
+    this.usecaseName = name;
+    this._requiredPermissions = requiredPermissions;
+  }
+
+  override get requiredPermissions(): Permission[] {
+    return this._requiredPermissions;
+  }
+
+  protected async _execute(): Promise<void> {}
+}
+
+describe("Authorization constraint matching", () => {
+  beforeEach(() => {
+    Usecase.use([new AuthorizationInterceptor()]);
+  });
+
+  afterEach(() => {
+    // Clear global interceptors by accessing private field
+    (Usecase as any)._globalInterceptors.clear();
+  });
+
+  describe("grant-side constraints are ignored when usecase does not require them", () => {
+    test("actor with teamId constraint passes when usecase only requires scope", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { scope: ResourceScope.BUSINESS, teamId: "sales" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "invoice"], [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor with statuses constraint passes when usecase does not require statuses", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "order",
+          action: "retrieve",
+          constraints: { scope: ResourceScope.TEAM, statuses: ["draft"] },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "order"], [
+        {
+          resource: "order",
+          action: "retrieve",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor with businessId constraint passes when usecase does not require businessId", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "report",
+          action: "list",
+          constraints: { scope: ResourceScope.BUSINESS, businessId: "biz-1" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["list", "report"], [
+        {
+          resource: "report",
+          action: "list",
+          constraints: { scope: ResourceScope.BUSINESS },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("no constraints required means any grant matches", () => {
+    test("actor with no constraints passes when usecase requires none", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        { resource: "item", action: "retrieve" },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "item"], [
+        { resource: "item", action: "retrieve" },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor with constraints passes when usecase requires none", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "item",
+          action: "retrieve",
+          constraints: { scope: ResourceScope.OWNED, teamId: "t1" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "item"], [
+        { resource: "item", action: "retrieve" },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("required constraints must be present on grant", () => {
+    test("actor without constraints fails when usecase requires scope", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        { resource: "invoice", action: "update" },
+      ]);
+
+      const usecase = new TestUsecase(["update", "invoice"], [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("actor without teamId fails when usecase requires specific teamId", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "doc"], [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("scope hierarchy in constraint matching", () => {
+    test("ALL scope satisfies TEAM requirement", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "doc",
+          action: "retrieve",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "doc"], [
+        {
+          resource: "doc",
+          action: "retrieve",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("TEAM scope does not satisfy PROJECT requirement (parallel siblings)", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "task",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "task"], [
+        {
+          resource: "task",
+          action: "update",
+          constraints: { scope: ResourceScope.PROJECT },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("OWNED scope does not satisfy TEAM requirement", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { scope: ResourceScope.OWNED },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "invoice"], [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("ID constraint exact matching", () => {
+    test("matching teamId passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "doc"], [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("mismatching teamId fails", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "sales" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "doc"], [
+        {
+          resource: "doc",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("status constraint matching", () => {
+    test("granted statuses superset of required passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "order",
+          action: "update",
+          constraints: { statuses: ["draft", "pending", "active"] },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "order"], [
+        {
+          resource: "order",
+          action: "update",
+          constraints: { statuses: ["draft", "pending"] },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("granted statuses subset of required fails", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "order",
+          action: "update",
+          constraints: { statuses: ["draft"] },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "order"], [
+        {
+          resource: "order",
+          action: "update",
+          constraints: { statuses: ["draft", "pending"] },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("empty requiredPermissions skips authorization", () => {
+    test("any actor passes when usecase requires no permissions", async () => {
+      const actor = new TestActor("u1", "b1", "t1", []);
+
+      const usecase = new TestUsecase(["retrieve", "public-item"], []);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("resourceId constraint", () => {
+    test("matching resourceId passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("mismatching resourceId fails", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-99" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("grant without resourceId fails when usecase requires it", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("grant with resourceId passes when usecase does not require it", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("resourceId alone without scope", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "delete",
+          constraints: { resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["delete", "document"], [
+        {
+          resource: "document",
+          action: "delete",
+          constraints: { resourceId: "doc-42" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("projectId constraint", () => {
+    test("matching projectId passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "task",
+          action: "create",
+          constraints: { scope: ResourceScope.PROJECT, projectId: "proj-1" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["create", "task"], [
+        {
+          resource: "task",
+          action: "create",
+          constraints: { scope: ResourceScope.PROJECT, projectId: "proj-1" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("mismatching projectId fails", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "task",
+          action: "create",
+          constraints: { scope: ResourceScope.PROJECT, projectId: "proj-1" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["create", "task"], [
+        {
+          resource: "task",
+          action: "create",
+          constraints: { scope: ResourceScope.PROJECT, projectId: "proj-2" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("constraint combinations", () => {
+    test("scope + teamId + statuses all matching passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "order",
+          action: "update",
+          constraints: {
+            scope: ResourceScope.TEAM,
+            teamId: "sales",
+            statuses: ["draft", "pending"],
+          },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "order"], [
+        {
+          resource: "order",
+          action: "update",
+          constraints: {
+            scope: ResourceScope.TEAM,
+            teamId: "sales",
+            statuses: ["draft"],
+          },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("scope + teamId + statuses — statuses mismatch fails despite scope and teamId matching", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "order",
+          action: "update",
+          constraints: {
+            scope: ResourceScope.TEAM,
+            teamId: "sales",
+            statuses: ["active"],
+          },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "order"], [
+        {
+          resource: "order",
+          action: "update",
+          constraints: {
+            scope: ResourceScope.TEAM,
+            teamId: "sales",
+            statuses: ["draft"],
+          },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("scope + resourceId + businessId all matching passes", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "contract",
+          action: "retrieve",
+          constraints: {
+            scope: ResourceScope.BUSINESS,
+            businessId: "biz-1",
+            resourceId: "contract-77",
+          },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "contract"], [
+        {
+          resource: "contract",
+          action: "retrieve",
+          constraints: {
+            scope: ResourceScope.BUSINESS,
+            businessId: "biz-1",
+            resourceId: "contract-77",
+          },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("scope + resourceId + businessId — resourceId mismatch fails", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "contract",
+          action: "retrieve",
+          constraints: {
+            scope: ResourceScope.BUSINESS,
+            businessId: "biz-1",
+            resourceId: "contract-77",
+          },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "contract"], [
+        {
+          resource: "contract",
+          action: "retrieve",
+          constraints: {
+            scope: ResourceScope.BUSINESS,
+            businessId: "biz-1",
+            resourceId: "contract-99",
+          },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("ALL scope does not bypass ID constraint requirements", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "delete",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["delete", "document"], [
+        {
+          resource: "document",
+          action: "delete",
+          constraints: { scope: ResourceScope.ALL, resourceId: "doc-42" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("multiple grants — first fails, second matches", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "sales" },
+        },
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("multiple grants — none match", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "sales" },
+        },
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "engineering" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("Recipe 1: edit a specific resource", () => {
+    test("actor with matching resourceId can edit the specific document", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor with different resourceId cannot edit someone else's document", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, resourceId: "doc-99" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("Recipe 2: see everything in a team", () => {
+    test("team member can list their team's tickets", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.TEAM, teamId: "engineering" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["list", "ticket"], [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.TEAM, teamId: "engineering" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("BUSINESS scope also satisfies team-scoped list", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.BUSINESS, teamId: "engineering" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["list", "ticket"], [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.TEAM, teamId: "engineering" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor from a different team cannot list", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.TEAM, teamId: "sales" },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["list", "ticket"], [
+        {
+          resource: "ticket",
+          action: "list",
+          constraints: { scope: ResourceScope.TEAM, teamId: "engineering" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("Recipe 3: only modify draft resources", () => {
+    test("actor with draft+pending statuses can update drafts", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { statuses: ["draft", "pending"] },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "invoice"], [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { statuses: ["draft"] },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("actor with only pending status cannot update drafts", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { statuses: ["pending"] },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "invoice"], [
+        {
+          resource: "invoice",
+          action: "update",
+          constraints: { statuses: ["draft"] },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+
+  describe("Recipe 4: public access via guest grants", () => {
+    test("guest with explicit grant passes usecase", async () => {
+      const guest = new TestActor("guest", "b1", "guest-token", [
+        { resource: "article", action: "retrieve" },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "article"], [
+        { resource: "article", action: "retrieve" },
+      ]);
+
+      await expect(usecase.execute(guest, undefined)).resolves.toBeUndefined();
+    });
+
+    test("guest without grant for that resource is denied", async () => {
+      const guest = new TestActor("guest", "b1", "guest-token", [
+        { resource: "article", action: "retrieve" },
+      ]);
+
+      const usecase = new TestUsecase(["retrieve", "document"], [
+        { resource: "document", action: "retrieve" },
+      ]);
+
+      await expect(usecase.execute(guest, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("empty requiredPermissions skips interceptor — no grant needed at all", async () => {
+      const guest = new TestActor("guest", "b1", "guest-token", []);
+
+      const usecase = new TestUsecase(["check", "health"], []);
+
+      await expect(usecase.execute(guest, undefined)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("ALL scope — god-mode, opt-in", () => {
+    test("ALL grant satisfies ALL requirement", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "system",
+          action: "configure",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["configure", "system"], [
+        {
+          resource: "system",
+          action: "configure",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("ALL requirement is the most restrictive — BUSINESS grant does not satisfy it", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "system",
+          action: "configure",
+          constraints: { scope: ResourceScope.BUSINESS },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["configure", "system"], [
+        {
+          resource: "system",
+          action: "configure",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+
+    test("ALL grant satisfies every lower scope requirement (god-mode)", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      const businessUsecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.BUSINESS },
+        },
+      ]);
+
+      const teamUsecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM },
+        },
+      ]);
+
+      const ownedUsecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.OWNED },
+        },
+      ]);
+
+      await expect(businessUsecase.execute(actor, undefined)).resolves.toBeUndefined();
+      await expect(teamUsecase.execute(actor, undefined)).resolves.toBeUndefined();
+      await expect(ownedUsecase.execute(actor, undefined)).resolves.toBeUndefined();
+    });
+
+    test("ALL grant does not bypass non-scope constraints", async () => {
+      const actor = new TestActor("u1", "b1", "t1", [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.ALL },
+        },
+      ]);
+
+      const usecase = new TestUsecase(["update", "document"], [
+        {
+          resource: "document",
+          action: "update",
+          constraints: { scope: ResourceScope.TEAM, teamId: "legal" },
+        },
+      ]);
+
+      await expect(usecase.execute(actor, undefined)).rejects.toThrow(
+        AuthorizationException,
+      );
+    });
+  });
+});