@gotgenes/pi-permission-system 3.2.0 → 3.4.0

package/src/permission-dialog.ts

@@ -1,5 +1,6 @@
 export type PermissionDecisionState =
   | "approved"
+  | "approved_for_session"
   | "denied"
   | "denied_with_reason";
 
@@ -15,10 +16,12 @@ export interface PermissionDecisionUi {
 }
 
 const APPROVE_OPTION = "Yes";
+const APPROVE_FOR_SESSION_OPTION = "Yes, for this session";
 const DENY_OPTION = "No";
 const DENY_WITH_REASON_OPTION = "No, provide reason";
 const PERMISSION_DECISION_OPTIONS = [
   APPROVE_OPTION,
+  APPROVE_FOR_SESSION_OPTION,
   DENY_OPTION,
   DENY_WITH_REASON_OPTION,
 ] as const;
@@ -54,7 +57,10 @@ export function isPermissionDecisionState(
   value: unknown,
 ): value is PermissionDecisionState {
   return (
-    value === "approved" || value === "denied" || value === "denied_with_reason"
+    value === "approved" ||
+    value === "approved_for_session" ||
+    value === "denied" ||
+    value === "denied_with_reason"
   );
 }
 
@@ -74,6 +80,13 @@ export async function requestPermissionDecisionFromUi(
     };
   }
 
+  if (selected === APPROVE_FOR_SESSION_OPTION) {
+    return {
+      approved: true,
+      state: "approved_for_session",
+    };
+  }
+
   if (selected === DENY_WITH_REASON_OPTION) {
     const denialReason = normalizePermissionDenialReason(
       await ui.input(

package/src/permission-gate.ts

@@ -0,0 +1,74 @@
+import type { PermissionPromptDecision } from "./permission-dialog";
+
+/** Result of applying the permission gate. */
+export type PermissionGateResult =
+  | { action: "allow" }
+  | { action: "block"; reason: string };
+
+/** Everything the gate needs — no direct dependency on ExtensionContext. */
+export interface PermissionGateParams {
+  /** The resolved permission state from checkPermission(). */
+  state: "allow" | "deny" | "ask";
+
+  /** Whether the current context supports interactive prompts. */
+  canConfirm: boolean;
+
+  /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
+  promptForApproval: () => Promise<PermissionPromptDecision>;
+
+  /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
+  writeLog: (event: string, extra: Record<string, unknown>) => void;
+
+  /** Log context fields shared across all log calls for this gate. */
+  logContext: Record<string, unknown>;
+
+  /** Message strings/factories for each outcome. */
+  messages: {
+    denyReason: string;
+    unavailableReason: string;
+    userDeniedReason: (decision: PermissionPromptDecision) => string;
+  };
+}
+
+/**
+ * Apply the deny/ask/allow permission gate.
+ *
+ * This is a pure decision function: all IO is injected via callbacks.
+ */
+export async function applyPermissionGate(
+  params: PermissionGateParams,
+): Promise<PermissionGateResult> {
+  const {
+    state,
+    canConfirm,
+    promptForApproval,
+    writeLog,
+    logContext,
+    messages,
+  } = params;
+
+  if (state === "deny") {
+    writeLog("permission_request.blocked", {
+      ...logContext,
+      resolution: "policy_denied",
+    });
+    return { action: "block", reason: messages.denyReason };
+  }
+
+  if (state === "ask") {
+    if (!canConfirm) {
+      writeLog("permission_request.blocked", {
+        ...logContext,
+        resolution: "confirmation_unavailable",
+      });
+      return { action: "block", reason: messages.unavailableReason };
+    }
+
+    const decision = await promptForApproval();
+    if (!decision.approved) {
+      return { action: "block", reason: messages.userDeniedReason(decision) };
+    }
+  }
+
+  return { action: "allow" };
+}

package/src/session-approval-cache.ts

@@ -0,0 +1,81 @@
+import { dirname, sep } from "node:path";
+
+import { isPathWithinDirectory } from "./external-directory";
+
+/**
+ * Ephemeral in-memory cache of session-scoped permission approvals.
+ * Keyed by permission surface (e.g. "external_directory"), values are
+ * normalized directory prefixes that have been approved for the session.
+ *
+ * Cleared on session_shutdown — never persisted to disk.
+ */
+export class SessionApprovalCache {
+  private approvals = new Map<string, Set<string>>();
+
+  /** Record a directory prefix as approved for the given surface. */
+  approve(surface: string, prefix: string): void {
+    let prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      prefixes = new Set();
+      this.approvals.set(surface, prefixes);
+    }
+    prefixes.add(prefix);
+  }
+
+  /**
+   * Check whether a path falls under any approved prefix for the given surface.
+   * Uses `isPathWithinDirectory()` for correct separator-aware prefix matching.
+   */
+  has(surface: string, path: string): boolean {
+    const prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      return false;
+    }
+    for (const prefix of prefixes) {
+      if (isPathWithinDirectory(path, prefix)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Find and return the matching approved prefix, or null if none matches. */
+  findMatchingPrefix(surface: string, path: string): string | null {
+    const prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      return null;
+    }
+    for (const prefix of prefixes) {
+      if (isPathWithinDirectory(path, prefix)) {
+        return prefix;
+      }
+    }
+    return null;
+  }
+
+  /** Remove all session approvals. */
+  clear(): void {
+    this.approvals.clear();
+  }
+}
+
+/**
+ * Derive the directory prefix to approve from a normalized path.
+ * Returns `dirname(path)` with a trailing separator so that
+ * prefix matching via `isPathWithinDirectory()` works correctly.
+ *
+ * For paths that already end with a separator (directories),
+ * the trailing separator is stripped by dirname and re-added.
+ */
+export function deriveApprovalPrefix(normalizedPath: string): string {
+  // If the path already ends with a separator, it's a directory — return as-is.
+  if (normalizedPath.endsWith(sep)) {
+    return normalizedPath;
+  }
+  const dir = dirname(normalizedPath);
+  if (dir === normalizedPath) {
+    // Root path — dirname('/') === '/'
+    return dir;
+  }
+  return dir.endsWith(sep) ? dir : `${dir}${sep}`;
+}

package/tests/permission-dialog.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createDeniedPermissionDecision,
+  isPermissionDecisionState,
+  normalizePermissionDenialReason,
+  type PermissionDecisionUi,
+  requestPermissionDecisionFromUi,
+} from "../src/permission-dialog";
+
+describe("isPermissionDecisionState", () => {
+  it("accepts approved", () => {
+    expect(isPermissionDecisionState("approved")).toBe(true);
+  });
+
+  it("accepts denied", () => {
+    expect(isPermissionDecisionState("denied")).toBe(true);
+  });
+
+  it("accepts denied_with_reason", () => {
+    expect(isPermissionDecisionState("denied_with_reason")).toBe(true);
+  });
+
+  it("accepts approved_for_session", () => {
+    expect(isPermissionDecisionState("approved_for_session")).toBe(true);
+  });
+
+  it("rejects unknown strings", () => {
+    expect(isPermissionDecisionState("unknown")).toBe(false);
+  });
+
+  it("rejects non-strings", () => {
+    expect(isPermissionDecisionState(42)).toBe(false);
+    expect(isPermissionDecisionState(null)).toBe(false);
+  });
+});
+
+describe("requestPermissionDecisionFromUi", () => {
+  it("returns approved when user selects Yes", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("Yes"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: true, state: "approved" });
+  });
+
+  it("returns approved_for_session when user selects session option", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("Yes, for this session"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: true, state: "approved_for_session" });
+  });
+
+  it("returns denied when user selects No", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("returns denied_with_reason when user provides reason", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No, provide reason"),
+      input: vi.fn().mockResolvedValue("not now"),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({
+      approved: false,
+      state: "denied_with_reason",
+      denialReason: "not now",
+    });
+  });
+
+  it("returns denied when user selects deny-with-reason but gives empty input", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No, provide reason"),
+      input: vi.fn().mockResolvedValue(""),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("returns denied when user dismisses dialog (undefined)", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue(undefined),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("passes four options to ui.select", async () => {
+    const selectFn = vi.fn().mockResolvedValue("Yes");
+    const ui: PermissionDecisionUi = {
+      select: selectFn,
+      input: vi.fn(),
+    };
+    await requestPermissionDecisionFromUi(ui, "Title", "Message");
+    const options = selectFn.mock.calls[0][1] as string[];
+    expect(options).toEqual([
+      "Yes",
+      "Yes, for this session",
+      "No",
+      "No, provide reason",
+    ]);
+  });
+});
+
+describe("normalizePermissionDenialReason", () => {
+  it("returns trimmed string for non-empty input", () => {
+    expect(normalizePermissionDenialReason("  reason  ")).toBe("reason");
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(normalizePermissionDenialReason("")).toBeUndefined();
+  });
+
+  it("returns undefined for non-string", () => {
+    expect(normalizePermissionDenialReason(42)).toBeUndefined();
+  });
+});
+
+describe("createDeniedPermissionDecision", () => {
+  it("returns denied_with_reason when reason provided", () => {
+    expect(createDeniedPermissionDecision("nope")).toEqual({
+      approved: false,
+      state: "denied_with_reason",
+      denialReason: "nope",
+    });
+  });
+
+  it("returns denied when no reason", () => {
+    expect(createDeniedPermissionDecision()).toEqual({
+      approved: false,
+      state: "denied",
+    });
+  });
+});

package/tests/permission-gate.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from "vitest";
+import type { PermissionPromptDecision } from "../src/permission-dialog";
+import {
+  applyPermissionGate,
+  type PermissionGateParams,
+} from "../src/permission-gate";
+
+function makeParams(
+  overrides: Partial<PermissionGateParams> = {},
+): PermissionGateParams {
+  return {
+    state: "allow",
+    canConfirm: true,
+    promptForApproval: vi.fn<() => Promise<PermissionPromptDecision>>(),
+    writeLog: vi.fn(),
+    logContext: { source: "test" },
+    messages: {
+      denyReason: "Denied by policy.",
+      unavailableReason: "No interactive UI available.",
+      userDeniedReason: (d) =>
+        d.denialReason
+          ? `User denied. Reason: ${d.denialReason}.`
+          : "User denied.",
+    },
+    ...overrides,
+  };
+}
+
+describe("applyPermissionGate", () => {
+  describe("deny branch", () => {
+    it("returns block with deny reason when state is deny", async () => {
+      const params = makeParams({ state: "deny" });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "Denied by policy.",
+      });
+    });
+
+    it("calls writeLog with policy_denied resolution", async () => {
+      const params = makeParams({
+        state: "deny",
+        logContext: { source: "tool_call", toolName: "bash" },
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).toHaveBeenCalledOnce();
+      expect(params.writeLog).toHaveBeenCalledWith(
+        "permission_request.blocked",
+        {
+          source: "tool_call",
+          toolName: "bash",
+          resolution: "policy_denied",
+        },
+      );
+    });
+
+    it("does not call promptForApproval when state is deny", async () => {
+      const params = makeParams({ state: "deny" });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — unavailable", () => {
+    it("returns block with unavailable reason when canConfirm is false", async () => {
+      const params = makeParams({ state: "ask", canConfirm: false });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "No interactive UI available.",
+      });
+    });
+
+    it("calls writeLog with confirmation_unavailable resolution", async () => {
+      const params = makeParams({
+        state: "ask",
+        canConfirm: false,
+        logContext: { source: "skill_read", skillName: "foo" },
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).toHaveBeenCalledOnce();
+      expect(params.writeLog).toHaveBeenCalledWith(
+        "permission_request.blocked",
+        {
+          source: "skill_read",
+          skillName: "foo",
+          resolution: "confirmation_unavailable",
+        },
+      );
+    });
+
+    it("does not call promptForApproval when canConfirm is false", async () => {
+      const params = makeParams({ state: "ask", canConfirm: false });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — user rejects", () => {
+    it("returns block with user-denied reason when user rejects", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "block", reason: "User denied." });
+    });
+
+    it("passes denial reason through userDeniedReason formatter", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied_with_reason",
+        denialReason: "not now",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "User denied. Reason: not now.",
+      });
+    });
+
+    it("does not call writeLog when user rejects (logged by promptPermission)", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — user approves", () => {
+    it("returns allow when user approves", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not call writeLog when user approves", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("allow branch", () => {
+    it("returns allow immediately when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not call writeLog when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+
+    it("does not call promptForApproval when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+});