@komarspn/pi-permission-system 16.0.2

package/test/scope-merge.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import type { MergedScopes } from "#src/scope-merge";
+import { mergeScopesWithOrigins } from "#src/scope-merge";
+
+describe("mergeScopesWithOrigins", () => {
+  it("returns empty result for empty scopes array", () => {
+    const result: MergedScopes = mergeScopesWithOrigins([]);
+    expect(result.mergedPermission).toEqual({});
+    expect(result.origins.size).toBe(0);
+  });
+
+  it("attributes a string surface value to the contributing scope via the '*' pattern", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "allow" });
+    expect(result.origins.get("bash")?.get("*")).toBe("global");
+  });
+
+  it("attributes each pattern of an object surface value to the contributing scope", () => {
+    const result = mergeScopesWithOrigins([
+      [
+        "project",
+        { permission: { bash: { "git *": "allow", "npm *": "deny" } } },
+      ],
+    ]);
+    expect(result.mergedPermission).toEqual({
+      bash: { "git *": "allow", "npm *": "deny" },
+    });
+    expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    expect(result.origins.get("bash")?.get("npm *")).toBe("project");
+  });
+
+  it(
+    "shallow-merge: patterns not redefined by the higher scope keep their lower-scope origin;" +
+      " patterns the higher scope defines switch to the higher scope",
+    () => {
+      const result = mergeScopesWithOrigins([
+        [
+          "global",
+          { permission: { bash: { "ls *": "allow", "git *": "allow" } } },
+        ],
+        ["project", { permission: { bash: { "git *": "deny" } } }],
+      ]);
+      expect(result.mergedPermission).toEqual({
+        bash: { "ls *": "allow", "git *": "deny" },
+      });
+      // "ls *" was not touched by project — retains global attribution
+      expect(result.origins.get("bash")?.get("ls *")).toBe("global");
+      // "git *" was overridden by project — switches to project attribution
+      expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    },
+  );
+
+  it("full replacement (string over object): higher scope re-attributes the entire surface to its own origin", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: { "ls *": "allow" } } }],
+      ["project", { permission: { bash: "deny" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "deny" });
+    // The string value produces a single "*" pattern for the replacing scope
+    expect(result.origins.get("bash")?.get("*")).toBe("project");
+    // The former "ls *" pattern from global is gone — origins are replaced, not merged
+    expect(result.origins.get("bash")?.has("ls *")).toBe(false);
+  });
+
+  it("full replacement (object over string): higher scope re-attributes the entire surface to its own origin", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: "ask" } }],
+      ["project", { permission: { bash: { "git *": "deny" } } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: { "git *": "deny" } });
+    // The object value attributes each pattern to the replacing scope
+    expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    // The former "*" attribution from global is gone
+    expect(result.origins.get("bash")?.has("*")).toBe(false);
+  });
+
+  it("applies four-scope precedence in lowest→highest order (global → project → agent → project-agent)", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { read: "ask" } }],
+      ["project", { permission: { write: "deny" } }],
+      ["agent", { permission: { bash: "deny" } }],
+      ["project-agent", { permission: { mcp: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({
+      read: "ask",
+      write: "deny",
+      bash: "deny",
+      mcp: "allow",
+    });
+    expect(result.origins.get("read")?.get("*")).toBe("global");
+    expect(result.origins.get("write")?.get("*")).toBe("project");
+    expect(result.origins.get("bash")?.get("*")).toBe("agent");
+    expect(result.origins.get("mcp")?.get("*")).toBe("project-agent");
+  });
+
+  it("skips scopes with no permission key, contributing nothing to either map", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", {}],
+      ["project", { permission: { bash: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "allow" });
+    expect(result.origins.get("bash")?.get("*")).toBe("project");
+  });
+
+  it("attributes the universal '*' surface like any other (downstream reads origins.get('*')?.get('*') for universalFallbackOrigin)", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { "*": "deny" } }],
+      ["project", { permission: { "*": "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ "*": "allow" });
+    // Both scopes write a string — each is a full replacement; project wins last
+    expect(result.origins.get("*")?.get("*")).toBe("project");
+  });
+});

package/test/service-lifecycle.test.ts

@@ -0,0 +1,163 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PermissionsService } from "#src/service";
+import {
+  PermissionServiceLifecycle,
+  type ServiceLifecycle,
+} from "#src/service-lifecycle";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
+
+import { makeCtx } from "#test/helpers/handler-fixtures";
+
+// ── module stubs ───────────────────────────────────────────────────────────
+
+const mockIsRegisteredSubagentChild = vi.hoisted(() =>
+  vi.fn<(ctx: unknown, registry: unknown) => boolean>().mockReturnValue(false),
+);
+const mockPublishPermissionsService = vi.hoisted(() => vi.fn<() => void>());
+const mockUnpublishPermissionsService = vi.hoisted(() => vi.fn<() => void>());
+const mockEmitReadyEvent = vi.hoisted(() => vi.fn<() => void>());
+
+vi.mock("#src/subagent-context", () => ({
+  isRegisteredSubagentChild: mockIsRegisteredSubagentChild,
+}));
+vi.mock("#src/service", () => ({
+  publishPermissionsService: mockPublishPermissionsService,
+  unpublishPermissionsService: mockUnpublishPermissionsService,
+}));
+vi.mock("#src/permission-events", () => ({
+  emitReadyEvent: mockEmitReadyEvent,
+}));
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeService(): PermissionsService {
+  return {
+    checkPermission: vi.fn(),
+    getToolPermission: vi.fn(),
+    registerToolInputFormatter: vi.fn(),
+    registerToolAccessExtractor: vi.fn(),
+  };
+}
+
+function makeRegistry(): SubagentSessionRegistry {
+  return {
+    has: vi.fn().mockReturnValue(false),
+  } as unknown as SubagentSessionRegistry;
+}
+
+function makeLifecycle(overrides?: { subscriptions?: (() => void)[] }) {
+  const service = makeService();
+  const registry = makeRegistry();
+  const events = { emit: vi.fn(), on: vi.fn() };
+  const subscriptions = overrides?.subscriptions ?? [];
+  const lifecycle = new PermissionServiceLifecycle(
+    service,
+    registry,
+    events,
+    subscriptions,
+  );
+  return { lifecycle, service, registry, events, subscriptions };
+}
+
+beforeEach(() => {
+  mockIsRegisteredSubagentChild.mockReset();
+  mockIsRegisteredSubagentChild.mockReturnValue(false);
+  mockPublishPermissionsService.mockReset();
+  mockUnpublishPermissionsService.mockReset();
+  mockEmitReadyEvent.mockReset();
+});
+
+// ── ServiceLifecycle interface shape ──────────────────────────────────────
+
+it("PermissionServiceLifecycle satisfies ServiceLifecycle", () => {
+  const { lifecycle } = makeLifecycle();
+  const _: ServiceLifecycle = lifecycle;
+  expect(_).toBeDefined();
+});
+
+// ── activate ──────────────────────────────────────────────────────────────
+
+describe("activate", () => {
+  it("publishes the service for a non-child session", () => {
+    const ctx = makeCtx();
+    const { lifecycle, service } = makeLifecycle();
+    mockIsRegisteredSubagentChild.mockReturnValue(false);
+    lifecycle.activate(ctx);
+    expect(mockPublishPermissionsService).toHaveBeenCalledWith(service);
+  });
+
+  it("skips publishing for a registered child session", () => {
+    const ctx = makeCtx();
+    const { lifecycle } = makeLifecycle();
+    mockIsRegisteredSubagentChild.mockReturnValue(true);
+    lifecycle.activate(ctx);
+    expect(mockPublishPermissionsService).not.toHaveBeenCalled();
+  });
+
+  it("always emits the ready event, even for a child session", () => {
+    const ctx = makeCtx();
+    const { lifecycle, events } = makeLifecycle();
+    mockIsRegisteredSubagentChild.mockReturnValue(true);
+    lifecycle.activate(ctx);
+    expect(mockEmitReadyEvent).toHaveBeenCalledWith(events);
+  });
+
+  it("emits ready after publishing the service", () => {
+    const ctx = makeCtx();
+    const order: string[] = [];
+    mockPublishPermissionsService.mockImplementation(() =>
+      order.push("publish"),
+    );
+    mockEmitReadyEvent.mockImplementation(() => order.push("ready"));
+    const { lifecycle } = makeLifecycle();
+    lifecycle.activate(ctx);
+    expect(order).toEqual(["publish", "ready"]);
+  });
+
+  it("passes ctx and registry to isRegisteredSubagentChild", () => {
+    const ctx = makeCtx();
+    const { lifecycle, registry } = makeLifecycle();
+    lifecycle.activate(ctx);
+    expect(mockIsRegisteredSubagentChild).toHaveBeenCalledWith(ctx, registry);
+  });
+});
+
+// ── teardown ──────────────────────────────────────────────────────────────
+
+describe("teardown", () => {
+  it("calls each subscription unsubscribe function", () => {
+    const unsub1 = vi.fn();
+    const unsub2 = vi.fn();
+    const unsub3 = vi.fn();
+    const { lifecycle } = makeLifecycle({
+      subscriptions: [unsub1, unsub2, unsub3],
+    });
+    lifecycle.teardown();
+    expect(unsub1).toHaveBeenCalledOnce();
+    expect(unsub2).toHaveBeenCalledOnce();
+    expect(unsub3).toHaveBeenCalledOnce();
+  });
+
+  it("unpublishes the service after running subscriptions", () => {
+    const order: string[] = [];
+    const unsub = vi.fn(() => order.push("unsub"));
+    mockUnpublishPermissionsService.mockImplementation(() =>
+      order.push("unpublish"),
+    );
+    const { lifecycle } = makeLifecycle({ subscriptions: [unsub] });
+    lifecycle.teardown();
+    expect(order).toEqual(["unsub", "unpublish"]);
+  });
+
+  it("passes the service to unpublishPermissionsService", () => {
+    const { lifecycle, service } = makeLifecycle();
+    lifecycle.teardown();
+    expect(mockUnpublishPermissionsService).toHaveBeenCalledWith(service);
+  });
+
+  it("works with no subscriptions", () => {
+    const { lifecycle } = makeLifecycle({ subscriptions: [] });
+    expect(() => lifecycle.teardown()).not.toThrow();
+    expect(mockUnpublishPermissionsService).toHaveBeenCalledOnce();
+  });
+});

package/test/service.test.ts

@@ -0,0 +1,308 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildInputForSurface } from "#src/input-normalizer";
+import type { PermissionsService } from "#src/service";
+import {
+  getPermissionsService,
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "#src/service";
+import { ToolAccessExtractorRegistry } from "#src/tool-access-extractor-registry";
+import { ToolInputFormatterRegistry } from "#src/tool-input-formatter-registry";
+import type { PermissionCheckResult } from "#src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeService(
+  overrides: Partial<PermissionsService> = {},
+): PermissionsService {
+  return {
+    checkPermission: vi.fn(),
+    getToolPermission: vi.fn(),
+    registerToolInputFormatter: vi.fn(),
+    registerToolAccessExtractor: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ── globalThis accessor ────────────────────────────────────────────────────
+
+describe("globalThis accessor", () => {
+  afterEach(() => {
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
+  });
+
+  it("returns undefined when nothing has been published", () => {
+    expect(getPermissionsService()).toBeUndefined();
+  });
+
+  it("returns the published service", () => {
+    const service = makeService();
+    publishPermissionsService(service);
+    expect(getPermissionsService()).toBe(service);
+  });
+
+  it("overwrites a previously published service", () => {
+    const first = makeService();
+    const second = makeService();
+    publishPermissionsService(first);
+    publishPermissionsService(second);
+    expect(getPermissionsService()).toBe(second);
+  });
+
+  it("removes the slot when it still holds the given service", () => {
+    const service = makeService();
+    publishPermissionsService(service);
+    unpublishPermissionsService(service);
+    expect(getPermissionsService()).toBeUndefined();
+  });
+
+  it("does not remove the slot when a different service occupies it", () => {
+    const parent = makeService();
+    const child = makeService();
+    publishPermissionsService(parent);
+    // A child instance never published `parent`; unpublishing its own service
+    // must be a no-op that leaves the parent's slot intact.
+    unpublishPermissionsService(child);
+    expect(getPermissionsService()).toBe(parent);
+  });
+
+  it("unpublish is safe to call when nothing was published", () => {
+    expect(() => unpublishPermissionsService(makeService())).not.toThrow();
+    expect(getPermissionsService()).toBeUndefined();
+  });
+});
+
+// ── service adapter delegation ─────────────────────────────────────────────
+
+describe("service adapter delegation", () => {
+  afterEach(() => {
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
+  });
+
+  const fakeResult: PermissionCheckResult = {
+    toolName: "bash",
+    state: "allow",
+    matchedPattern: "git *",
+    source: "bash",
+    origin: "global",
+  };
+
+  it("checkPermission delegates surface and value through buildInputForSurface", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "allow" as const,
+        layer: "session" as const,
+        origin: "session" as const,
+      },
+    ];
+
+    // Build the adapter the same way index.ts will
+    const service = makeService({
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, sessionRules);
+      },
+    });
+
+    publishPermissionsService(service);
+    const retrieved = getPermissionsService()!;
+    const result = retrieved.checkPermission("bash", "git push");
+
+    expect(result).toBe(fakeResult);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "bash",
+      { command: "git push" },
+      undefined,
+      sessionRules,
+    );
+  });
+
+  it("checkPermission passes agentName through", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+
+    const service = makeService({
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, []);
+      },
+    });
+
+    publishPermissionsService(service);
+    getPermissionsService()!.checkPermission("skill", "my-skill", "Explore");
+
+    expect(checkPermission).toHaveBeenCalledWith(
+      "skill",
+      { name: "my-skill" },
+      "Explore",
+      [],
+    );
+  });
+
+  it("getToolPermission delegates to the permission manager", () => {
+    const getToolPermissionFn = vi.fn(
+      (_t: string, _a?: string): "deny" => "deny",
+    );
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      getToolPermission(toolName, agentName) {
+        return getToolPermissionFn(toolName, agentName);
+      },
+      registerToolInputFormatter: vi.fn(),
+      registerToolAccessExtractor: vi.fn(),
+    };
+
+    publishPermissionsService(service);
+    const result = getPermissionsService()!.getToolPermission(
+      "bash",
+      "Explore",
+    );
+
+    expect(result).toBe("deny");
+    expect(getToolPermissionFn).toHaveBeenCalledWith("bash", "Explore");
+  });
+
+  it("getToolPermission works without agentName", () => {
+    const getToolPermissionFn = vi.fn(
+      (_t: string, _a?: string): "ask" => "ask",
+    );
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      getToolPermission(toolName, agentName) {
+        return getToolPermissionFn(toolName, agentName);
+      },
+      registerToolInputFormatter: vi.fn(),
+      registerToolAccessExtractor: vi.fn(),
+    };
+
+    publishPermissionsService(service);
+    const result = getPermissionsService()!.getToolPermission("write");
+
+    expect(result).toBe("ask");
+    expect(getToolPermissionFn).toHaveBeenCalledWith("write", undefined);
+  });
+
+  it("checkPermission uses empty object for unknown surfaces", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+
+    const service = makeService({
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, []);
+      },
+    });
+
+    publishPermissionsService(service);
+    getPermissionsService()!.checkPermission("read", "/tmp/file");
+
+    expect(checkPermission).toHaveBeenCalledWith("read", {}, undefined, []);
+  });
+});
+
+// ── registerToolInputFormatter delegation ─────────────────────────────────
+
+describe("registerToolInputFormatter delegation", () => {
+  afterEach(() => {
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
+  });
+
+  it("delegates to the registry and returns its disposer", () => {
+    const registry = new ToolInputFormatterRegistry();
+    const formatter = () => "preview";
+
+    const service = makeService({
+      registerToolInputFormatter(toolName, fmt) {
+        return registry.register(toolName, fmt);
+      },
+    });
+
+    publishPermissionsService(service);
+    const dispose = getPermissionsService()!.registerToolInputFormatter(
+      "my-tool",
+      formatter,
+    );
+
+    // Registry received the registration
+    expect(registry.get("my-tool")).toBe(formatter);
+
+    // Disposer returned from service removes it from the registry
+    dispose();
+    expect(registry.get("my-tool")).toBeUndefined();
+  });
+
+  it("throws when a formatter is already registered for the tool name", () => {
+    const registry = new ToolInputFormatterRegistry();
+    registry.register("my-tool", () => undefined);
+
+    const service = makeService({
+      registerToolInputFormatter(toolName, fmt) {
+        return registry.register(toolName, fmt);
+      },
+    });
+
+    publishPermissionsService(service);
+    expect(() =>
+      getPermissionsService()!.registerToolInputFormatter("my-tool", () => ""),
+    ).toThrow("my-tool");
+  });
+});
+
+// ── registerToolAccessExtractor delegation (#352) ────────────────────────
+
+describe("registerToolAccessExtractor delegation", () => {
+  afterEach(() => {
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
+  });
+
+  it("delegates to the registry and returns its disposer", () => {
+    const registry = new ToolAccessExtractorRegistry();
+    const extractor = () => "/etc/hosts";
+
+    const service = makeService({
+      registerToolAccessExtractor(toolName, ext) {
+        return registry.register(toolName, ext);
+      },
+    });
+
+    publishPermissionsService(service);
+    const dispose = getPermissionsService()!.registerToolAccessExtractor(
+      "ffgrep",
+      extractor,
+    );
+
+    expect(registry.get("ffgrep")).toBe(extractor);
+
+    dispose();
+    expect(registry.get("ffgrep")).toBeUndefined();
+  });
+
+  it("throws when an extractor is already registered for the tool name", () => {
+    const registry = new ToolAccessExtractorRegistry();
+    registry.register("ffgrep", () => undefined);
+
+    const service = makeService({
+      registerToolAccessExtractor(toolName, ext) {
+        return registry.register(toolName, ext);
+      },
+    });
+
+    publishPermissionsService(service);
+    expect(() =>
+      getPermissionsService()!.registerToolAccessExtractor("ffgrep", () => ""),
+    ).toThrow("ffgrep");
+  });
+});

package/test/session-approval.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { SessionApproval } from "#src/session-approval";
+
+describe("SessionApproval", () => {
+  describe("single", () => {
+    it("stores surface and one pattern", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.surface).toBe("bash");
+      expect(approval.patterns).toEqual(["git *"]);
+    });
+
+    it("representativePattern returns the pattern", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.representativePattern).toBe("git *");
+    });
+
+    it("toGateApproval returns { surface, pattern }", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.toGateApproval()).toEqual({
+        surface: "bash",
+        pattern: "git *",
+      });
+    });
+  });
+
+  describe("multiple", () => {
+    it("stores surface and all patterns", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.surface).toBe("external_directory");
+      expect(approval.patterns).toEqual(["/outside/a/*", "/outside/b/*"]);
+    });
+
+    it("representativePattern returns the first pattern", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.representativePattern).toBe("/outside/a/*");
+    });
+
+    it("toGateApproval returns { surface, pattern } using the first pattern", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.toGateApproval()).toEqual({
+        surface: "external_directory",
+        pattern: "/outside/a/*",
+      });
+    });
+
+    it("defensive copy — mutating the source array does not affect patterns", () => {
+      const source = ["/outside/a/*", "/outside/b/*"];
+      const approval = SessionApproval.multiple("external_directory", source);
+      source.push("/outside/c/*");
+      expect(approval.patterns).toEqual(["/outside/a/*", "/outside/b/*"]);
+    });
+  });
+
+  describe("empty patterns (degenerate case)", () => {
+    it("representativePattern returns undefined", () => {
+      const approval = SessionApproval.multiple("external_directory", []);
+      expect(approval.representativePattern).toBeUndefined();
+    });
+
+    it("toGateApproval returns undefined", () => {
+      const approval = SessionApproval.multiple("external_directory", []);
+      expect(approval.toGateApproval()).toBeUndefined();
+    });
+  });
+});