@gotgenes/pi-permission-system 23.0.1 → 23.0.2

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [23.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.1...pi-permission-system-v23.0.2) (2026-07-26)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** create forwarding request files owner-only ([8c77c72](https://github.com/gotgenes/pi-packages/commit/8c77c7228a52d3b57397c7d53d301d002087d92f)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+* **pi-permission-system:** create permission logs owner-only ([6043cf8](https://github.com/gotgenes/pi-packages/commit/6043cf81bbe6332290d2d6bc8882ba1eadf181cc)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+* **pi-permission-system:** mask sensitive-keyed values in permission logs ([05cb12a](https://github.com/gotgenes/pi-packages/commit/05cb12a1c85e3030f6de3a4ed20cf1cd150e2d56)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+* **pi-permission-system:** redact generic tool input in the review log ([2035fb2](https://github.com/gotgenes/pi-packages/commit/2035fb2276efd75daa8d1f4e6e2af8e67763a9f8)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+
+
+### Documentation
+
+* **pi-permission-system:** link ADR 0010 by absolute URL from shipped docs ([0384af6](https://github.com/gotgenes/pi-packages/commit/0384af6483bd1a2d7f00a5a91efbe241c6d6898f)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+* **pi-permission-system:** record ADR 0010 on permission-log secret exposure ([c13b48a](https://github.com/gotgenes/pi-packages/commit/c13b48a9a14635d25af18a2c0f70bf765141a623)), closes [#647](https://github.com/gotgenes/pi-packages/issues/647)
+
 ## [23.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.0...pi-permission-system-v23.0.1) (2026-07-25)
 
 

package/docs/configuration.md

@@ -98,16 +98,16 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 
 ## Runtime Knobs
 
-| Key                         | Default | Description                                                                                                                                                                |
-| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugLog`                  | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                              |
-| `permissionReviewLog`       | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`                                                                    |
-| `yoloMode`                  | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                 |
-| `doublePressToConfirm`      | `true`  | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                          |
-| `toolInputPreviewMaxLength` | `200`   | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.                            |
-| `toolTextSummaryMaxLength`  | `80`    | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                                      |
-| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME` expansion and wildcard patterns (`*`, `?`).                       |
-| `authorizerChain`           | `[]`    | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)). |
+| Key                         | Default | Description                                                                                                                                                                                        |
+| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugLog`                  | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                      |
+| `permissionReviewLog`       | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings verbatim — see [Log file sensitivity](#log-file-sensitivity) |
+| `yoloMode`                  | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                         |
+| `doublePressToConfirm`      | `true`  | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                  |
+| `toolInputPreviewMaxLength` | `200`   | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.                                                    |
+| `toolTextSummaryMaxLength`  | `80`    | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                                                              |
+| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME` expansion and wildcard patterns (`*`, `?`).                                               |
+| `authorizerChain`           | `[]`    | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                         |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.
@@ -903,7 +903,38 @@ Additional behaviors:
 - The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
-- Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls
+- Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked (see [Log file sensitivity](#log-file-sensitivity))
+
+---
+
+## Log file sensitivity
+
+The review log is enabled by default and records what the agent actually did, which means it records payload as well as decisions: the complete bash command string for every bash decision, and a bounded JSON preview of the tool input for other tools.
+The debug log carries the same payload when `debugLog` is on.
+
+Two protections apply.
+
+Both logs are created **owner-only** (`0600`, in a `0700` directory), and a log created by an earlier version is tightened on the next write.
+The permission-forwarding request and response files are written the same way.
+This closes the shared-host case: another user on the same machine cannot read them.
+
+Values bound to a **sensitive key name** — `authorization`, `token`, `secret`, `password`, `credential`, `cookie`, `api_key`, `private_key`, matched case-insensitively — are masked as `[redacted]` before anything is written.
+So a tool called with `{"authorization": "Bearer …"}` records `{"authorization": "[redacted]"}`.
+
+The boundary is worth stating exactly, because it is easy to over-read:
+
+> A value bound to a sensitive key name is masked; a secret embedded in a bash command string is not.
+
+A command string has no keys, so `deploy --token abc123` is logged verbatim.
+The extension deliberately does not try to guess which parts of a command look secret-shaped — see [ADR 0010] for the measured reasoning.
+
+Practical guidance:
+
+- Treat both log files as sensitive when sharing them: scrub before pasting into an issue or a chat.
+- Set `"permissionReviewLog": false` (and leave `debugLog` off) for a session that will handle credentials on the command line.
+- Owner-only modes do not protect against anything running as you, including a backup or cloud-sync agent that copies your home directory.
+
+[ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md
 
 ---
 

package/docs/troubleshooting.md

@@ -51,3 +51,8 @@ This makes it easy to verify which files the extension actually loaded:
 
 - If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
 - This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes)
+- The review log records bash command strings verbatim.
+  Log files are created owner-only (`0600`), and values bound to a sensitive key name (`authorization`, `token`, `password`, …) are masked — but a secret embedded in a command string is not.
+  See [Log file sensitivity](configuration.md#log-file-sensitivity) and [ADR 0010].
+
+[ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "23.0.1",
+  "version": "23.0.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/authority/forwarding-io.ts

@@ -18,6 +18,10 @@ import {
   type ForwardedSessionApproval,
   type PermissionForwardingLocation,
 } from "#src/authority/permission-forwarding";
+import {
+  OWNER_ONLY_DIRECTORY_MODE,
+  OWNER_ONLY_FILE_MODE,
+} from "#src/log-file-permissions";
 import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { DebugReviewLogger } from "#src/session-logger";
 
@@ -185,7 +189,7 @@ export function ensureDirectoryExists(
   description: string,
 ): boolean {
   try {
-    mkdirSync(path, { recursive: true });
+    mkdirSync(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
     return true;
   } catch (error) {
     logPermissionForwardingError(
@@ -365,7 +369,12 @@ export function writeJsonFileAtomic(
   const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
 
   try {
-    writeFileSync(tempPath, JSON.stringify(value), "utf-8");
+    // `rename` preserves the temp file's mode, so setting it here is enough —
+    // a response overwriting an existing file also comes through a fresh temp.
+    writeFileSync(tempPath, JSON.stringify(value), {
+      encoding: "utf-8",
+      mode: OWNER_ONLY_FILE_MODE,
+    });
     renameSync(tempPath, filePath);
   } catch (error) {
     safeDeleteFile(logger, tempPath, "temporary permission-forwarding");

package/src/extension-config.ts

@@ -1,11 +1,14 @@
 import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-
 import type {
   ShellToolsConfig,
   UnifiedPermissionConfig,
 } from "./config-loader";
+import {
+  OWNER_ONLY_DIRECTORY_MODE,
+  restrictExistingPathToOwner,
+} from "./log-file-permissions";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -94,7 +97,11 @@ export function ensurePermissionSystemLogsDirectory(
   logsDir: string,
 ): string | undefined {
   try {
-    mkdirSync(logsDir, { recursive: true });
+    // `recursive` applies the mode to every directory this creates, so a fresh
+    // install also gets an owner-only extension config dir. Directories that
+    // already exist are untouched by `mkdirSync`, hence the explicit tighten.
+    mkdirSync(logsDir, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
+    restrictExistingPathToOwner(logsDir, OWNER_ONLY_DIRECTORY_MODE);
     return undefined;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/src/json-safe-stringify.ts

@@ -0,0 +1,54 @@
+/**
+ * JSON serialization that survives the values a permission log actually
+ * carries: `Error` instances, `bigint`s, and object graphs with cycles.
+ *
+ * Lives apart from the JSONL writer because both the log path and the
+ * permission-prompt path serialize tool input, and only one of them redacts.
+ */
+
+/**
+ * Rewrites a value before the standard JSON-safe handling runs.
+ * Returning a replacement short-circuits nothing — the replacement itself
+ * flows through the `Error` / `bigint` / cycle handling below.
+ */
+export type JsonValueTransform = (key: string, value: unknown) => unknown;
+
+/**
+ * Build a `JSON.stringify` replacer. Each call owns a fresh `seen` set, so a
+ * replacer must not be reused across `stringify` calls.
+ */
+export function createJsonSafeReplacer(
+  transform?: JsonValueTransform,
+): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+
+  return (key: string, rawValue: unknown): unknown => {
+    const value = transform ? transform(key, rawValue) : rawValue;
+
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+      };
+    }
+
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return "[Circular]";
+      }
+      seen.add(value);
+    }
+
+    return value;
+  };
+}
+
+/** Serialize `value` to JSON, tolerating errors, bigints, and cycles. */
+export function safeJsonStringify(value: unknown): string | undefined {
+  return JSON.stringify(value, createJsonSafeReplacer());
+}

package/src/log-file-permissions.ts

@@ -0,0 +1,34 @@
+import { chmodSync } from "node:fs";
+
+/**
+ * Owner-only POSIX modes for the extension's on-disk artifacts.
+ *
+ * The permission logs record bash command strings and tool-input previews, and
+ * the forwarding files carry the same text between sessions. Left to the
+ * process umask they are created world-readable (0644 / 0755 under the common
+ * default), which is only acceptable on a single-user host.
+ */
+
+export const OWNER_ONLY_FILE_MODE = 0o600;
+export const OWNER_ONLY_DIRECTORY_MODE = 0o700;
+
+/**
+ * Best-effort tightening of an existing path's mode.
+ *
+ * Creation-time modes cover new files, but an installation that predates this
+ * hardening already has a world-readable log that no `mode` option will fix —
+ * hence the explicit `chmod`.
+ *
+ * Never throws, and never reports. On Windows `chmod` only toggles the
+ * read-only bit and can reject a directory outright; warning about that every
+ * session would be noise, since the file there is governed by NTFS ACL
+ * inheritance rather than POSIX modes. A hardening failure must also never
+ * break the gate, which is the caller's real work.
+ */
+export function restrictExistingPathToOwner(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // Intentionally ignored — see above.
+  }
+}

package/src/log-redaction.ts

@@ -0,0 +1,44 @@
+import { createJsonSafeReplacer } from "./json-safe-stringify";
+
+/**
+ * Key-name redaction for the permission logs.
+ *
+ * The technique is deliberately structural rather than predictive: a value is
+ * masked because of the *name* it is bound to, never because of what it looks
+ * like. Value-shape secret detection (provider prefixes, entropy heuristics)
+ * was measured against a real 6.7 MB review log and declined — see
+ * `docs/decisions/0010-permission-log-secret-exposure.md`.
+ *
+ * The boundary that follows from this, stated once: a value bound to a
+ * sensitive key name is masked; a secret embedded in a bash command string is
+ * not, because a command string has no keys.
+ */
+
+export const REDACTED_PLACEHOLDER = "[redacted]";
+
+const SENSITIVE_KEY_PATTERN =
+  /authorization|api[-_]?key|secret|token|password|passwd|credential|cookie|private[-_]?key/i;
+
+/** True when a log key names a credential-bearing value. */
+export function isSensitiveLogKey(key: string): boolean {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
+
+/**
+ * `safeJsonStringify` with sensitive-keyed values masked.
+ *
+ * Masking runs inside the replacer, so the structure beneath a sensitive key
+ * is never visited and the traversal's existing cycle guard is reused — one
+ * walk, not two. A `null` or `undefined` value is left alone so an absent
+ * field does not read as a suppressed one.
+ */
+export function redactedJsonStringify(value: unknown): string | undefined {
+  return JSON.stringify(
+    value,
+    createJsonSafeReplacer((key, currentValue) =>
+      currentValue != null && isSensitiveLogKey(key)
+        ? REDACTED_PLACEHOLDER
+        : currentValue,
+    ),
+  );
+}

package/src/logging.ts

@@ -4,35 +4,11 @@ import {
   EXTENSION_ID,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
-
-export function safeJsonStringify(value: unknown): string | undefined {
-  const seen = new WeakSet<object>();
-  return JSON.stringify(value, (_key, currentValue) => {
-    if (currentValue instanceof Error) {
-      return {
-        name: currentValue.name,
-        message: currentValue.message,
-        stack: currentValue.stack,
-      };
-    }
-
-    if (typeof currentValue === "bigint") {
-      return currentValue.toString();
-    }
-
-    if (typeof currentValue === "object" && currentValue !== null) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- JSON.stringify replacer receives any; currentValue is narrowed to object here
-      if (seen.has(currentValue)) {
-        return "[Circular]";
-      }
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- same as above
-      seen.add(currentValue);
-    }
-
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- JSON.stringify replacer must return any
-    return currentValue;
-  });
-}
+import {
+  OWNER_ONLY_FILE_MODE,
+  restrictExistingPathToOwner,
+} from "./log-file-permissions";
+import { redactedJsonStringify } from "./log-redaction";
 
 export interface PermissionSystemLogger {
   debug: (
@@ -56,6 +32,10 @@ export function createPermissionSystemLogger(
   options: PermissionSystemLoggerOptions,
 ): PermissionSystemLogger {
   const { debugLogPath, reviewLogPath, ensureLogsDirectory } = options;
+  // Per-session, so a log inherited from an earlier version is tightened once
+  // rather than on every line. Lives in the closure because the factory is
+  // re-invoked per session, unlike module scope, which now outlives one.
+  const hardened = new Set<string>();
 
   const writeLine = (
     stream: "debug" | "review",
@@ -69,7 +49,7 @@ export function createPermissionSystemLogger(
     }
 
     try {
-      const line = safeJsonStringify({
+      const line = redactedJsonStringify({
         timestamp: new Date().toISOString(),
         extension: EXTENSION_ID,
         stream,
@@ -79,7 +59,14 @@ export function createPermissionSystemLogger(
       if (!line) {
         return `Failed to write permission-system ${stream} log '${path}': event could not be serialized.`;
       }
-      appendFileSync(path, `${line}\n`, "utf-8");
+      appendFileSync(path, `${line}\n`, {
+        encoding: "utf-8",
+        mode: OWNER_ONLY_FILE_MODE,
+      });
+      if (!hardened.has(path)) {
+        hardened.add(path);
+        restrictExistingPathToOwner(path, OWNER_ONLY_FILE_MODE);
+      }
       return undefined;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);

package/src/tool-input-preview.ts

@@ -1,4 +1,5 @@
-import { safeJsonStringify } from "./logging";
+import { safeJsonStringify } from "./json-safe-stringify";
+import { redactedJsonStringify } from "./log-redaction";
 
 export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
 export const TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH = 1000;
@@ -24,8 +25,23 @@ export function formatCount(
   return `${value} ${value === 1 ? singular : plural}`;
 }
 
+/** Serialize tool input for display in a permission prompt, unredacted. */
 export function serializeToolInputPreview(input: unknown): string {
-  const serialized = safeJsonStringify(input);
+  return normalizeSerializedPreview(safeJsonStringify(input));
+}
+
+/**
+ * Serialize tool input for the review log, masking sensitive-keyed values.
+ *
+ * The log path needs its own entry point because the input is flattened to a
+ * string here — by the time it reaches the JSONL writer its keys are gone, so
+ * that boundary's redaction pass can no longer see them.
+ */
+export function serializeRedactedToolInputPreview(input: unknown): string {
+  return normalizeSerializedPreview(redactedJsonStringify(input));
+}
+
+function normalizeSerializedPreview(serialized: string | undefined): string {
   if (!serialized || serialized === "{}" || serialized === "null") {
     return "";
   }

package/src/tool-preview-formatter.ts

@@ -2,6 +2,7 @@ import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
+  serializeRedactedToolInputPreview,
   serializeToolInputPreview,
   TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
   TOOL_INPUT_PREVIEW_MAX_LENGTH,
@@ -145,9 +146,12 @@ export class ToolPreviewFormatter {
 
   // ── Log formatting ──────────────────────────────────────────────────────
 
-  /** Serialize `input` to inline JSON and truncate at `toolInputLogPreviewMaxLength`. */
+  /**
+   * Serialize `input` to inline JSON and truncate at
+   * `toolInputLogPreviewMaxLength`, masking sensitive-keyed values.
+   */
   formatGenericToolInputForLog(input: unknown): string | undefined {
-    const inline = serializeToolInputPreview(input);
+    const inline = serializeRedactedToolInputPreview(input);
     return inline
       ? `input ${truncateInlineText(inline, this.options.toolInputLogPreviewMaxLength)}`
       : undefined;