@gotgenes/pi-permission-system 16.2.1 → 17.1.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [17.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.0.0...pi-permission-system-v17.1.0) (2026-06-28)
+
+
+### Features
+
+* **pi-permission-system:** add PathNormalizer collaborator ([#510](https://github.com/gotgenes/pi-packages/issues/510)) ([d016089](https://github.com/gotgenes/pi-packages/commit/d016089690aff3821eabd5bd5351bb3a0c3639d4))
+
+## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.1...pi-permission-system-v17.0.0) (2026-06-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of bash path-rule tokens, so a path rule can fire on a symlink alias it previously missed, changing decisions on upgrade with no config edit.
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of a tool's file path. A path rule that previously matched only the as-typed spelling now also matches when the path resolves through a symlink to a target the pattern covers, which can change allow/deny decisions on upgrade with no config edit.
+
+### Features
+
+* **pi-permission-system:** add AccessPath.forPath and forLiteral factories ([4323cae](https://github.com/gotgenes/pi-packages/commit/4323cae859907dd62d9cb401c194443717ab752c)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+* **pi-permission-system:** match the canonical form on the bash-path gate ([6ce0c06](https://github.com/gotgenes/pi-packages/commit/6ce0c06b35c12eca32ffce5d4fe974c2f2dee393))
+* **pi-permission-system:** match the canonical form on the path tool gate ([869ca76](https://github.com/gotgenes/pi-packages/commit/869ca761cf3d7a8367eb932106065a866d996ce4))
+
+
+### Documentation
+
+* **pi-permission-system:** document canonical path-surface matching ([9606dce](https://github.com/gotgenes/pi-packages/commit/9606dce744bc1f95bd8424d2bb115a376d9a1191)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+
 ## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.0...pi-permission-system-v16.2.1) (2026-06-27)
 
 

package/README.md

@@ -17,7 +17,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Enforces allow / ask / deny** at tool-call time with UI confirmation dialogs
 - **Controls bash commands** with wildcard pattern matching (`git *: ask`, `rm -rf *: deny`)
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
-- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
+- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
@@ -69,6 +69,7 @@ See [docs/session-approvals.md](docs/session-approvals.md) for details on sessio
 
 The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.
 Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.arguments.path`, or a registered access extractor) are gated by default, so a `path` deny cannot be overridden by a per-tool allow — making it the right place to protect sensitive files like `.env` or `~/.ssh/*` from every tool at once.
+A `path` pattern matches both the path as the agent references it and its canonical (symlink-resolved) form, so a deny still fires when a symlink aliases a sensitive target.
 
 For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`.
 This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.

package/package.json

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

package/src/access-intent/access-intent.ts

@@ -17,8 +17,9 @@ export interface ToolAccessIntent {
 /**
  * Precomputed equivalent policy values for a path-shaped surface.
  *
- * Used by the bash-path gate (`path` surface), whose cd-resolved lexical
- * `string[]` carry no canonical-boundary notion.
+ * Not gate-emitted: the resolver produces it internally by unwrapping an
+ * `access-path` intent via `matchValues()`, keeping the low-level manager
+ * string-based (it never imports `AccessPath`). See {@link ResolvedAccessIntent}.
  */
 export interface PathValuesAccessIntent {
   kind: "path-values";
@@ -31,9 +32,9 @@ export interface PathValuesAccessIntent {
 /**
  * An `AccessPath` value object for a path-shaped surface.
  *
- * Used by the external-directory gates; lets `AccessPath` flow into the
- * resolver as a first-class variant so the resolver — not the gate — asks it
- * for `matchValues()` (Tell-Don't-Ask).
+ * Emitted by every path gate (the `path` and `external_directory` surfaces);
+ * lets `AccessPath` flow into the resolver as a first-class variant so the
+ * resolver — not the gate — asks it for `matchValues()` (Tell-Don't-Ask).
  */
 export interface AccessPathAccessIntent {
   kind: "access-path";
@@ -42,11 +43,8 @@ export interface AccessPathAccessIntent {
   agentName?: string;
 }
 
-/** What a gate emits — the full three-variant union. */
-export type AccessIntent =
-  | ToolAccessIntent
-  | PathValuesAccessIntent
-  | AccessPathAccessIntent;
+/** What a gate emits — a raw tool input or an `AccessPath`. */
+export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
 
 /**
  * What the manager consumes — the `access-path` variant has already been

package/src/access-intent/access-path.ts

@@ -20,7 +20,9 @@ import {
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
  *
- * Construct via {@link forExternalDirectory}; the constructor is private.
+ * Construct via {@link forPath} (resolved, with optional cd-folded base) or
+ * {@link forLiteral} (literal-only, for an unknown base); the constructor is
+ * private.
  */
 export class AccessPath {
   private constructor(
@@ -65,24 +67,45 @@ export class AccessPath {
   }
 
   /**
-   * Build an `AccessPath` for a tool-input or bash-token path resolved against
-   * `cwd`.
+   * Build an `AccessPath` for a tool-input or bash-token path, resolved against
+   * `resolveBase` (the cd-folded effective directory; defaults to `cwd`).
    *
-   * - `matchValues()` returns the same set as the former
-   *   `getExternalDirectoryPolicyValues(pathValue, cwd)` — the lexical alias
-   *   union from `getPathPolicyValues` plus the canonical alias from
-   *   `canonicalNormalizePathForComparison` (#418).
-   * - `boundaryValue()` returns `canonicalNormalizePathForComparison(pathValue, cwd)`,
-   *   which is win32-lowercased (#382) — do not substitute a raw
-   *   `canonicalizePath` output here.
-   * - `value()` returns `normalizePathForComparison(pathValue, cwd)`, the
-   *   absolute lexical form.
+   * Serves every path surface: the tool path gate, the tool external-directory
+   * gate, and the bash path/external-directory gates (which pass a cd-resolved
+   * `resolveBase`).
+   *
+   * - `matchValues()` returns the lexical alias union from `getPathPolicyValues`
+   *   plus the canonical alias from `canonicalNormalizePathForComparison`
+   *   (#418), so a config pattern on either the typed or symlink-resolved form
+   *   matches.
+   * - `boundaryValue()` returns
+   *   `canonicalNormalizePathForComparison(pathValue, resolveBase)`, which is
+   *   win32-lowercased (#382) — do not substitute a raw `canonicalizePath`
+   *   output here.
+   * - `value()` returns `normalizePathForComparison(pathValue, resolveBase)`,
+   *   the absolute lexical form.
    */
-  static forExternalDirectory(pathValue: string, cwd: string): AccessPath {
+  static forPath(
+    pathValue: string,
+    options: { cwd: string; resolveBase?: string; platform: NodeJS.Platform },
+  ): AccessPath {
+    const { cwd, resolveBase = cwd, platform } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, cwd),
-      getPathPolicyValues(pathValue, { cwd }),
-      canonicalNormalizePathForComparison(pathValue, cwd),
+      normalizePathForComparison(pathValue, resolveBase, platform),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }, platform),
+      canonicalNormalizePathForComparison(pathValue, resolveBase, platform),
     );
   }
+
+  /**
+   * Build a literal-only `AccessPath` for a path whose effective base is
+   * unknown (a relative bash token after a non-literal `cd`).
+   *
+   * Carries no canonical alias and no absolute resolution — `matchValues()` is
+   * `[literal]` (or `[]` when empty) and `boundaryValue()` is `""` — so no
+   * spurious absolute or symlink-resolved rule can match (#393).
+   */
+  static forLiteral(literal: string): AccessPath {
+    return new AccessPath(literal, literal ? [literal] : [], "");
+  }
 }