@openlines/opl-pi-sht 0.2.7 → 0.2.8

package/README.md

@@ -17,7 +17,9 @@ A portable collection of various Pi coding agent extensions. Repository director
 <div align="center">
 
 >
-> ### v0.2.7 (29 Sept 2026) - **Unified `opl-guardian` safety**: adds configurable Bash confirmations, symlink-aware protected file-tool paths, destructive-session confirmations, and malformed-call filtering. <br/>See [CHANGELOG.md](CHANGELOG.md) for details.
+> ### v0.2.8 (29 Sept 2026) - **SSRF and tool-safety hardening**: `opl-webaccess` and `opl-browser` block private/link-local hosts by default and cloud metadata always (localhost stays available for dev), fetch redirects are re-checked per hop, screenshots refuse to overwrite existing files, and `evaluate` no longer crashes on `undefined`. <br/>See [CHANGELOG.md](CHANGELOG.md) for details.
+>
+> `Current project state also marked 'SAFE' for pi v0.99.0 release`<br/>*confirmed this because I was literally typing to push the patches when I noticed the release notif*
 >
 
 </div>
@@ -123,8 +125,8 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 
 - **`opl-init`** deterministically crawls and refines `AGENTS.md` with a single out-of-band model call (never a synthetic user message), writes it, and reloads context so the session runs on the new guide. A current fingerprint means zero model calls; mid-session invocations wait for the agent to settle instead of interrupting it. Needs pi >= 0.86.0.
 ![init](images/ss-init.png)
-- **`opl-browser`** gives full Chromium automation (navigate, snapshot, extract rendered-page markdown, interact, screenshot, console/network capture, evaluate) through a single tool, with handle+preview output for large results — navigation is http(s)-only and screenshots stay in the project directory.
-- **`opl-webaccess`** adds provider-backed search plus readable URL and PDF extraction, with session recovery of earlier results, an http(s)-only fetch, a 10 MB response cap, and a 30s timeout.
+- **`opl-browser`** gives full Chromium automation (navigate, snapshot, extract rendered-page markdown, interact, screenshot, console/network capture, evaluate) through a single tool, with handle+preview output for large results — navigation is http(s)-only, blocks private/link-local hosts by default and cloud metadata always (SSRF guard; localhost is allowed for dev), and screenshots must use `.png`/`.jpg`, stay in the project directory, and never overwrite an existing file.
+- **`opl-webaccess`** adds provider-backed search plus readable URL and PDF extraction, with session recovery of earlier results, an http(s)-only fetch that blocks private/link-local hosts by default and cloud metadata always, re-checks every redirect hop (SSRF guard; localhost is allowed for dev), a 10 MB response cap, and a 30s timeout.
 - **`opl-simplebench`** benchmarks models on deterministic closed-answer contracts, instruction-following, and tool-call generation so you pick a model on evidence, not vibes.
 ![simplebench](images/ss-simplebench.png)
 - **`opl-todo`** tracks branch-aware tasks that persist across a session and reconstruct from history.

package/configs/opl-browser.json.sample

@@ -1,9 +1,10 @@
 {
-  "_comment": "Optional. Copy to ~/.pi/agent/configs/opl-browser.json. All fields optional; defaults shown.",
+  "_comment": "Optional. Copy to ~/.pi/agent/configs/opl-browser.json. All fields optional; defaults shown. allowPrivateNetwork (default false) blocks navigate/new_page from reaching private/link-local ranges; loopback (localhost) is always allowed for local development, and cloud-metadata endpoints are always blocked.",
   "headless": true,
   "width": 1280,
   "height": 800,
   "navigationTimeoutMs": 30000,
   "previewChars": 4000,
-  "getChars": 30000
+  "getChars": 30000,
+  "allowPrivateNetwork": false
 }

package/configs/opl-modes.json.sample

@@ -6,7 +6,7 @@
   },
   "shortcuts": {
     "_comment": "Shortcut that cycles through all enabled, visible modes in registry order. Default: ctrl+alt+m.",
-    "cycleMode": "shift+tab"
+    "cycleMode": "ctrl+alt+m"
   },
   "cleanup": {
     "_comment": "Set to true to delete the plan file automatically after plan_complete is called.",
@@ -17,8 +17,8 @@
   "_comment_lazyTools": "Tool names withheld from the active set at rest and enabled on demand via the load_tools tool. Only affects modes that would otherwise include them (off/execute and custom modes that list them). Core built-ins, plan_complete, and load_tools are protected and ignored. Omit or leave empty to keep all tools always active.",
   "lazyTools": [],
   "bashPatterns": {
-    "_comment_safe": "Replace-only: providing bashPatterns.safePatterns replaces the built-in safe list. This is the default safe allowlist for every mode and it is checked per shell segment (&&, ||, a lone &, |, ;, newline, $(...), backticks, <( and >( each start a segment), so every chained or backgrounded command must be allowed. Quote-aware: grep \\\"a|b\\\" stays one command, but a $(...) or backtick payload still runs inside double quotes, so it is split out and checked too. Interpreters and tools that can write files or exec programs from their own arguments (awk, sed, xargs, perl, python, env) are deliberately not listed. A mode overrides it with its own safePatterns or opts out of Bash gating with unrestrictedBash. Shown here with the built-in list.",
-    "_comment_destructive": "Replace-only: providing bashPatterns.destructivePatterns replaces the built-in destructive list. This is the default destructive blocklist for every mode; a mode overrides it with its own destructivePatterns or opts out of Bash gating with unrestrictedBash. Program-name entries are anchored to command position (match each segment start) so read-only commands that only mention rm/cp/sh in an argument stay allowed, while flag and redirect entries stay unanchored - that is how find -fprint, sort -o in any position, git log --output, npm audit fix, uniq's output operand, and a bare > file are caught even behind a safe command. Descriptor duplication (2>&1, >&2) and redirects into /dev/null are not writes and stay allowed. Shown here with the built-in list.",
+    "_comment_safe": "Replace-only: providing bashPatterns.safePatterns replaces the built-in safe list. This is the default safe allowlist for every mode and it is checked per shell segment (&&, ||, a lone &, |, ;, newline, $(...), backticks, <( and >( each start a segment), so every chained or backgrounded command must be allowed. Quote-aware: grep \\\"a|b\\\" stays one command, but a $(...) or backtick payload still runs inside double quotes, so it is split out and checked too. Interpreters and tools that can write files or exec programs from their own arguments (awk, sed, xargs, perl, python, env) are deliberately not listed. A mode overrides it with its own safePatterns or opts out of Bash gating with unrestrictedBash. An empty top-level safePatterns array falls back to the built-in list (it cannot opt out); set a per-mode safePatterns: [] to opt that mode out. Shown here with the built-in list.",
+    "_comment_destructive": "Replace-only: providing bashPatterns.destructivePatterns replaces the built-in destructive list. This is the default destructive blocklist for every mode; a mode overrides it with its own destructivePatterns or opts out of Bash gating with unrestrictedBash. Program-name entries are anchored to command position (match each segment start) so read-only commands that only mention rm/cp/sh in an argument stay allowed, while flag and redirect entries stay unanchored - that is how find -fprint, sort -o in any position, git log --output, npm audit fix, uniq's output operand, and a bare > file are caught even behind a safe command. Descriptor duplication (2>&1, >&2) and redirects into /dev/null are not writes and stay allowed. An empty top-level destructivePatterns array falls back to the built-in list (it cannot opt out); set a per-mode destructivePatterns: [] to opt that mode out. Shown here with the built-in list.",
     "safePatterns": [
       "^\\s*cat\\b",
       "^\\s*head\\b",

package/configs/opl-webaccess.json.sample

@@ -1,7 +1,11 @@
 {
-  "_comment_limits": "Optional top-level caps: maxContentChars caps the initial web_search/fetch_content body (default 30000); maxRetrievalChars caps one get_search_content page (default 30000). Pass offset=N to get_search_content to continue a truncated retrieval.",
+  "_comment_limits": "Optional top-level caps: maxContentChars caps the initial web_search/fetch_content body (default 30000); maxRetrievalChars caps one get_search_content page (default 30000). Pass offset=N to get_search_content to continue a truncated retrieval. maxSearchQueries caps how many queries one web_search call runs (default 10); maxFetchUrls caps how many URLs one fetch_content call fetches (default 20). Excess inputs are skipped and reported in the tool output.",
+  "_comment_network": "allowPrivateNetwork defaults to false: fetch_content rejects private-range and link-local hosts. Loopback (localhost/127.0.0.1/::1) is always allowed for local development, and cloud-metadata endpoints are always blocked. Set allowPrivateNetwork true to reach private ranges (LAN servers). This does NOT affect provider API endpoints (ddgs.apiUrl / searxng.instanceUrl), which remain configurable.",
+  "allowPrivateNetwork": false,
   "maxContentChars": 30000,
   "maxRetrievalChars": 30000,
+  "maxSearchQueries": 10,
+  "maxFetchUrls": 20,
   "provider": "searxng",
   "providers": {
     "gemini": {

package/extensions/opl-browser/README.md

@@ -45,15 +45,25 @@ Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`,
   which only sees raw HTTP HTML. Static pages: `fetch_content`; rendered or
   interacted-with pages: `browser:extract`. With a `selector`, the matched element
   is converted verbatim (no article detection): Readability's candidate scoring is
-  a whole-document heuristic and mispicks inside small subtrees.
+  a whole-document heuristic and mispicks inside small subtrees. A selector that
+  matches multiple elements returns a clear error instead of a strict-mode crash,
+  and a selector with no match reports `(no elements match ...)`.
 - **Real Chromium via Playwright.** Navigation with `domcontentloaded` waits,
   CSS-selector interaction, viewport control, multi-page management.
 - **Scheme + path guards.** `navigate`/`new_page` accept http(s) only; `file:`,
-  `data:`, and `javascript:` are rejected. Screenshot paths are confined to the
-  project directory, so a bad `path` cannot overwrite arbitrary files.
+  `data:`, and `javascript:` are rejected, private-range and link-local hosts are
+  blocked by default, and cloud-metadata endpoints are always blocked (SSRF guard).
+  Loopback (`localhost`/`127.0.0.0/8`/`::1`) is allowed by default for local
+  development; set `allowPrivateNetwork: true` for private ranges. Redirect targets
+  are re-checked on the final URL. Screenshot paths must use `.png`/`.jpg`, stay
+  inside the project directory, and are refused when the file already exists, so a
+  bad action cannot overwrite or plant arbitrary files.
 - **Per-page capture.** Console messages and network requests are buffered per
   page as they occur; `console` and `network` actions return the active page's
-  buffer.
+  buffer, capped at the most recent `200` entries per page so an active
+  long-running page cannot grow the buffer without bound. `navigate: back`/
+  `forward` on a fresh session reports `(no history to go back/forward)` instead of
+  silently returning the unchanged page.
 - **One reused browser per session.** Launched on first use, closed automatically
   on `session_shutdown`, or on demand via `action: "close"`.
 
@@ -68,6 +78,7 @@ Optional `~/.pi/agent/configs/opl-browser.json` (see `opl-browser.json.sample`):
 | `navigationTimeoutMs` | `30000` | Default navigation and `wait_for` timeout. |
 | `previewChars` | `4000` | Inline threshold; larger outputs are stored and previewed. |
 | `getChars` | `30000` | Characters returned by one `action: "get"` page. |
+| `allowPrivateNetwork` | `false` | Allow `navigate`/`new_page` to reach private/link-local ranges (loopback is always allowed; cloud metadata is always blocked). |
 
 ### Dependencies
 
@@ -86,7 +97,8 @@ npx playwright install chromium
 index.ts     Pi wiring: registers the single `browser` tool, TTL result store,
              preview/handle logic, and session_shutdown cleanup.
 browser.ts   Playwright driver: browser/context/page lifecycle, per-page console
-             and network buffers, and the action switch.
+             and network buffers, and the action switch. Tool calls are serialized
+             on the single shared context.
 validate.ts  URL/path guards: http/https-only navigation, screenshot path confined
              to the project directory.
 paging.ts    Bounded `get` pagination and continuation metadata.
@@ -98,4 +110,6 @@ config.ts    DEFAULT_CONFIG + loadUserConfig (user overrides win via ??).
 Interaction is CSS-selector based. Snapshot-uid interaction (referencing elements
 by ids returned from `snapshot`) is intentionally not implemented; use CSS
 selectors, which are simpler and robust. The in-memory result store expires
-entries after one hour or when the browser is closed.
+entries after one hour or when the browser is closed; expiry is checked on read,
+not only when another result is stored, so an idle entry past its TTL is never
+served.

package/extensions/opl-browser/browser.ts

@@ -12,22 +12,37 @@ let activeIndex = 0;
 const consoleBuf = new WeakMap<Page, string[]>();
 const networkBuf = new WeakMap<Page, string[]>();
 
+/** Cap on per-page console/network log lines kept in memory. */
+export const MAX_LOG_ENTRIES = 200;
+
+/** Push one log line, trimming the oldest entries past the cap. */
+export function pushLogEntry(entries: string[], entry: string, max = MAX_LOG_ENTRIES): string[] {
+  entries.push(entry);
+  if (entries.length > max) entries.splice(0, entries.length - max);
+  return entries;
+}
+
 function track(page: Page, cfg: BrowserConfig): void {
   consoleBuf.set(page, []);
   networkBuf.set(page, []);
   page.setDefaultNavigationTimeout(cfg.navigationTimeoutMs);
-  page.on("console", (m: ConsoleMessage) => consoleBuf.get(page)?.push(`[${m.type()}] ${m.text()}`));
+  page.on("console", (m: ConsoleMessage) => {
+    const buf = consoleBuf.get(page);
+    if (buf) pushLogEntry(buf, `[${m.type()}] ${m.text()}`);
+  });
   page.on("requestfinished", async (req) => {
     try {
       const res = await req.response();
-      networkBuf.get(page)?.push(`${req.method()} ${res?.status() ?? "?"} ${req.url()}`);
+      const buf = networkBuf.get(page);
+      if (buf) pushLogEntry(buf, `${req.method()} ${res?.status() ?? "?"} ${req.url()}`);
     } catch {
       /* response unavailable */
     }
   });
-  page.on("requestfailed", (req) =>
-    networkBuf.get(page)?.push(`${req.method()} FAILED ${req.url()} (${req.failure()?.errorText ?? "unknown"})`),
-  );
+  page.on("requestfailed", (req) => {
+    const buf = networkBuf.get(page);
+    if (buf) pushLogEntry(buf, `${req.method()} FAILED ${req.url()} (${req.failure()?.errorText ?? "unknown"})`);
+  });
 }
 
 async function ensure(cfg: BrowserConfig): Promise<BrowserContext> {
@@ -46,6 +61,13 @@ function page(): Page {
   return pages[activeIndex] ?? pages[pages.length - 1];
 }
 
+/** Navigate with the host validated both before the request and on the final URL, so a
+ *  public URL that redirects to a private/link-local host is rejected. */
+async function gotoAllowed(target: Page, url: string, cfg: BrowserConfig): Promise<void> {
+  await target.goto(assertHttpUrl(url, { allowPrivateNetwork: cfg.allowPrivateNetwork }), { waitUntil: "domcontentloaded" });
+  assertHttpUrl(target.url(), { allowPrivateNetwork: cfg.allowPrivateNetwork });
+}
+
 export interface BrowserActionResult {
   text: string;
   file?: string;
@@ -67,9 +89,23 @@ export interface BrowserParams {
   height?: number;
 }
 
-export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+let last: Promise<unknown> = Promise.resolve();
+/** Serialize state-mutating browser work: a single shared context cannot service
+ *  concurrent tool calls safely (activeIndex, page(), ensure() all race). Each new
+ *  action is queued behind the previous one, and failures never break the chain. */
+function serialize<T>(task: () => Promise<T>): Promise<T> {
+  const run = last.then(task, task);
+  last = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+export function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+  return serialize(() => runActionInternal(p, cfg));
+}
+
+async function runActionInternal(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
   if (p.action === "close") {
-    await closeBrowser();
+    await closeBrowserInternal();
     return { text: "Browser closed." };
   }
 
@@ -78,10 +114,15 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
   switch (p.action) {
     case "navigate": {
       const url = p.url ?? "";
-      if (url === "back") { await page().goBack(); }
-      else if (url === "forward") { await page().goForward(); }
-      else if (url === "reload") { await page().reload(); }
-      else if (url) { await page().goto(assertHttpUrl(url), { waitUntil: "domcontentloaded" }); }
+      if (url === "back" || url === "forward") {
+        // Playwright returns null (no throw) when history is exhausted; report it
+        // clearly instead of silently returning the unchanged page.
+        const moved = url === "back" ? await page().goBack() : await page().goForward();
+        if (!moved) return { text: `(no history to go ${url})` };
+        return { text: `${page().url()} — ${await page().title()}` };
+      }
+      if (url === "reload") await page().reload();
+      else if (url) await gotoAllowed(page(), url, cfg);
       else throw new Error("navigate requires url (or back|forward|reload)");
       return { text: `${page().url()} — ${await page().title()}` };
     }
@@ -91,9 +132,18 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
     }
     case "extract": {
       const selector = p.selector;
-      const html = selector
-        ? await page().locator(selector).evaluate((el: Element) => el.outerHTML)
-        : await page().content();
+      let html: string;
+      if (selector) {
+        const loc = page().locator(selector);
+        const count = await loc.count();
+        if (count === 0) return { text: `(no elements match "${selector}")` };
+        if (count > 1) {
+          throw new Error(`extract selector "${selector}" matched ${count} elements; use a more specific selector`);
+        }
+        html = await loc.evaluate((el: Element) => el.outerHTML);
+      } else {
+        html = await page().content();
+      }
       const { markdown } = extractMarkdown(html, { raw: Boolean(selector) });
       return { text: markdown || "(empty extraction)" };
     }
@@ -130,15 +180,18 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
     case "evaluate": {
       if (!p.script) throw new Error("evaluate requires script");
       const value = await page().evaluate(p.script);
-      return { text: typeof value === "string" ? value : JSON.stringify(value, null, 2) };
+      if (value === undefined) return { text: "(undefined result)" };
+      return { text: typeof value === "string" ? value : (JSON.stringify(value, null, 2) ?? "(undefined result)") };
     }
     case "console": {
       const msgs = consoleBuf.get(page()) ?? [];
-      return { text: msgs.length ? msgs.join("\n") : "(no console messages)" };
+      const suffix = msgs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} entries)` : "";
+      return { text: msgs.length ? msgs.join("\n") + suffix : "(no console messages)" };
     }
     case "network": {
       const reqs = networkBuf.get(page()) ?? [];
-      return { text: reqs.length ? reqs.join("\n") : "(no network requests)" };
+      const suffix = reqs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} requests)` : "";
+      return { text: reqs.length ? reqs.join("\n") + suffix : "(no network requests)" };
     }
     case "wait_for": {
       const timeout = p.timeoutMs ?? cfg.navigationTimeoutMs;
@@ -155,7 +208,7 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
       const pg = await ctx.newPage();
       track(pg, cfg);
       activeIndex = ctx.pages().length - 1;
-      if (p.url) await pg.goto(assertHttpUrl(p.url), { waitUntil: "domcontentloaded" });
+      if (p.url) await gotoAllowed(pg, p.url, cfg);
       return { text: `Opened page [${activeIndex}] ${pg.url()}` };
     }
     case "select_page": {
@@ -182,7 +235,11 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
   }
 }
 
-export async function closeBrowser(): Promise<void> {
+export function closeBrowser(): Promise<void> {
+  return serialize(closeBrowserInternal);
+}
+
+async function closeBrowserInternal(): Promise<void> {
   try {
     await context?.close();
     await browser?.close();

package/extensions/opl-browser/config.ts

@@ -9,6 +9,9 @@ export interface BrowserConfig {
   navigationTimeoutMs: number;
   previewChars: number;
   getChars: number;
+  /** Allow navigate/new_page to reach private/link-local ranges (loopback is always
+   *  allowed; cloud metadata is always blocked). Default false. */
+  allowPrivateNetwork: boolean;
 }
 
 export const DEFAULT_CONFIG: BrowserConfig = {
@@ -18,6 +21,7 @@ export const DEFAULT_CONFIG: BrowserConfig = {
   navigationTimeoutMs: 30000,
   previewChars: 4000,
   getChars: 30000,
+  allowPrivateNetwork: false,
 };
 
 const CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "configs", "opl-browser.json");
@@ -36,5 +40,6 @@ export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
     navigationTimeoutMs: user.navigationTimeoutMs ?? DEFAULT_CONFIG.navigationTimeoutMs,
     previewChars: user.previewChars ?? DEFAULT_CONFIG.previewChars,
     getChars: user.getChars ?? DEFAULT_CONFIG.getChars,
+    allowPrivateNetwork: user.allowPrivateNetwork ?? DEFAULT_CONFIG.allowPrivateNetwork,
   };
 }

package/extensions/opl-browser/index.ts

@@ -62,6 +62,11 @@ export default function (pi: ExtensionAPI) {
         if (!p.responseId) return err("get requires responseId");
         const hit = STORE.get(p.responseId);
         if (!hit) return err(`No stored result for ${p.responseId} (expires after 1h or on browser close).`);
+        // Enforce TTL on read, not just on the next store.
+        if (Date.now() - hit.timestamp > TTL_MS) {
+          STORE.delete(p.responseId);
+          return err(`No stored result for ${p.responseId} (expires after 1h or on browser close).`);
+        }
         const page = paginateStored(hit.text, p.offset ?? 0, cfg.getChars);
         return {
           content: [{ type: "text", text: page.text + continuationNotice(page) }],
@@ -76,15 +81,18 @@ export default function (pi: ExtensionAPI) {
         return err(`browser ${p.action}: ${e instanceof Error ? e.message : String(e)}`);
       }
 
+      // Defensive: never let a missing/invalid action text crash the size gate.
+      const text = String(result.text ?? "");
+
       // Small outputs return inline; large outputs are stored and previewed.
-      if (result.text.length <= cfg.previewChars) {
-        return { content: [{ type: "text", text: result.text }], details: result.file ? { file: result.file } : {} };
+      if (text.length <= cfg.previewChars) {
+        return { content: [{ type: "text", text }], details: result.file ? { file: result.file } : {} };
       }
-      const id = store(p.action, result.text);
-      const preview = result.text.slice(0, cfg.previewChars);
+      const id = store(p.action, text);
+      const preview = text.slice(0, cfg.previewChars);
       return {
         content: [{ type: "text", text: `${preview}\n\n… truncated. Full result via action:get responseId: ${id}` }],
-        details: { responseId: id, action: p.action, chars: result.text.length },
+        details: { responseId: id, action: p.action, chars: text.length },
       };
     },
   });

package/extensions/opl-browser/validate.ts

@@ -1,10 +1,119 @@
 // Pure URL/path guards for the browser tool. No Playwright import so tests load it directly.
 
+import { existsSync } from "node:fs";
 import { resolve, sep } from "node:path";
 
-/** Normalize a URL, allowing only http/https so file:/data:/javascript: URLs can't
- *  be navigated (file:// + evaluate = local file bytes returned into model context). */
-export function assertHttpUrl(url: string): string {
+export interface HttpUrlOptions {
+  /** Allow private, link-local, and reserved network hosts (default false). Loopback is always allowed; cloud metadata is always blocked. */
+  allowPrivateNetwork?: boolean;
+}
+
+/** Well-known cloud metadata hostnames that resolve to instance-credential endpoints. */
+const BLOCKED_METADATA_HOSTS = new Set([
+  "metadata",
+  "metadata.google.internal",
+  "instance-data",
+  "instance-data.ec2.internal",
+]);
+
+/** Cloud metadata IPv6 literals (e.g. AWS IMDS over IPv6). Always blocked. */
+const BLOCKED_METADATA_V6 = new Set(["fd00:ec2::254"]);
+
+type HostClass = "loopback" | "metadata" | "private" | "public";
+
+function ipv4FromInteger(n: number): number[] | null {
+  if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) return null;
+  return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+}
+
+function ipv4Octets(host: string): number[] | null {
+  if (/^\d+$/.test(host)) return ipv4FromInteger(Number(host));
+  const octets = host.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : NaN));
+  if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+  return octets;
+}
+
+function isLoopbackIpv4(o: number[]): boolean {
+  return o[0] === 127;
+}
+
+function isMetadataIpv4(o: number[]): boolean {
+  return (
+    (o[0] === 169 && o[1] === 254 && o[2] === 169 && o[3] === 254) ||
+    (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200)
+  );
+}
+
+function isPrivateIpv4(o: number[]): boolean {
+  const [a, b, c] = o;
+  return (
+    a === 0 || a === 10 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 192 && b === 0 && (c === 0 || c === 2)) ||
+    (a === 198 && (b === 18 || b === 19)) ||
+    (a === 198 && b === 51 && c === 100) ||
+    (a === 203 && b === 0 && c === 113) ||
+    a >= 224
+  );
+}
+
+function ipv4MappedOctets(ip: string): number[] | null {
+  const dotted = ip.match(/^::ffff:(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (dotted) return dotted.slice(1).map(Number);
+  const hex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const n = (parseInt(hex[1], 16) << 16) | parseInt(hex[2], 16);
+    return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+  }
+  return null;
+}
+
+function classifyIpv4Octets(o: number[]): HostClass {
+  if (isLoopbackIpv4(o)) return "loopback";
+  if (isMetadataIpv4(o)) return "metadata";
+  if (isPrivateIpv4(o)) return "private";
+  return "public";
+}
+
+function classifyIpv6Host(host: string): HostClass {
+  const ip = host.replace(/^\[/, "").replace(/\]$/, "").replace(/%.*$/, "").toLowerCase();
+  if (BLOCKED_METADATA_V6.has(ip)) return "metadata";
+  if (ip === "::1") return "loopback";
+  const mapped = ipv4MappedOctets(ip);
+  if (mapped) return classifyIpv4Octets(mapped);
+  if (ip === "::") return "private";
+  if (/^f[cd]/.test(ip)) return "private";
+  if (/^fe[89ab]/.test(ip)) return "private";
+  if (/^ff/.test(ip)) return "private";
+  return "public";
+}
+
+function classifyHost(host: string): HostClass {
+  const lowered = host.toLowerCase();
+  if (BLOCKED_METADATA_HOSTS.has(lowered)) return "metadata";
+  if (lowered === "localhost" || lowered.endsWith(".localhost")) return "loopback";
+  if (lowered.includes(":")) return classifyIpv6Host(lowered);
+  const octets = ipv4Octets(lowered);
+  return octets ? classifyIpv4Octets(octets) : "public";
+}
+
+function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean): boolean {
+  const cls = classifyHost(host);
+  if (cls === "metadata") return true;
+  if (cls === "loopback" || cls === "public") return false;
+  return !allowPrivateNetwork;
+}
+
+/**
+ * Normalize a URL, allowing only http/https, so `file:`/`data:`/`javascript:` URLs and SSRF
+ * targets can't be navigated (file:// + evaluate = local file bytes returned into model context).
+ * Loopback is allowed by default for local development; private/link-local/reserved ranges are
+ * blocked unless allowPrivateNetwork is set; cloud metadata is always blocked.
+ */
+export function assertHttpUrl(url: string, opts: HttpUrlOptions = {}): string {
   let parsed: URL;
   try {
     parsed = new URL(url);
@@ -14,16 +123,25 @@ export function assertHttpUrl(url: string): string {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`only http/https URLs are allowed, got ${parsed.protocol}//`);
   }
+  if (isBlockedNetworkHost(parsed.hostname, opts.allowPrivateNetwork === true)) {
+    throw new Error(`blocked network host "${parsed.hostname}" — private, link-local, reserved, and cloud-metadata URLs are not allowed (set allowPrivateNetwork to opt in to private ranges; metadata is always blocked)`);
+  }
   return parsed.href;
 }
 
-/** Require a screenshot path to stay within the project directory (guard against
- *  overwriting absolute or parent-relative user files with PNG bytes). */
+/** Require a screenshot path to stay within the project directory and refuse to overwrite
+ *  existing files (guard against overwriting project files or writing outside the repo). */
 export function safeScreenshotPath(file: string, cwd: string = process.cwd()): string {
   const root = resolve(cwd);
   const abs = resolve(cwd, file);
   if (abs !== root && !abs.startsWith(root + sep)) {
     throw new Error(`screenshot path must stay within the project directory: ${file}`);
   }
+  if (!/\.(png|jpe?g)$/i.test(file)) {
+    throw new Error(`screenshot path must end in .png or .jpg: ${file}`);
+  }
+  if (existsSync(abs)) {
+    throw new Error(`screenshot path already exists (refusing to overwrite): ${file}`);
+  }
   return file;
 }

package/extensions/opl-guardian/README.md

@@ -6,7 +6,7 @@ A configurable session and tool safety extension. `opl-guardian` filters malform
 
 Copy `configs/opl-guardian.json.sample` to `~/.pi/agent/configs/opl-guardian.json` and customize it. For a package install, find the sample under the installed package's `configs/` directory. All settings are optional; absent settings use the defaults from the sample.
 
-- `permissionGate.patterns` is a list of case-insensitive JavaScript regex strings. A match prompts for confirmation in the terminal or over RPC; Yes allows the command, while No or cancel blocks it. An empty list disables pattern matching. `permissionGate.blockWithoutUI` defaults to `true` and blocks a match when confirmation UI is unavailable. Configured patterns replace the defaults; update existing config files manually to adopt changes to default patterns.
+- `permissionGate.patterns` is a list of case-insensitive JavaScript regex strings. A match prompts for confirmation in the terminal or over RPC; Yes allows the command, while No or cancel blocks it. The prompt defaults to No (fail closed), so an accidental or unattended confirmation denies rather than approves. An empty list disables pattern matching. `permissionGate.blockWithoutUI` defaults to `true` and blocks a match when confirmation UI is unavailable. Configured patterns replace the defaults; update existing config files manually to adopt changes to default patterns.
 - `protectedPaths.paths` contains `{ "path", "deny" }` entries. Valid denied operations are `read`, `write`, `edit`, and `bash`. Bare names match exact path segments for file tools; Bash uses literal command matching. Absolute and `~/` entries match resolved paths and descendants for file tools. An empty list disables path rules.
 - `confirmDestructive` controls confirmations for starting a new session (`clearSession`), resuming another session when unanswered user work exists (`switchWithUnsavedWork`), and forking (`forkSession`). All default to `true`. `confirmDestructive.blockWithoutUI` also defaults to `true`; set it to `false` to allow these actions without an interactive confirmation.
 - `dropMalformedToolCalls` defaults to `true`. Set it to `false` to disable only malformed-call filtering and its incident log.
@@ -23,7 +23,7 @@ The default patterns cover recursive `rm` flags (including `-rf`, `-fr`, and sep
 
 ### Protected paths
 
-Defaults protect `.env` from read/write/edit/Bash, `.git/` from read/write/edit, `node_modules/` from write/edit, and `~/.pi/agent/auth.json` from read/write/edit/Bash. File-tool path checks compare both the supplied path and its filesystem-resolved target, including existing symlinks and symlinked parents for new files; paths that cannot be safely resolved are blocked when an applicable path rule is active. A path denial is a hard block and takes precedence over a dangerous-command confirmation for the same Bash call. These are preflight checks, not filesystem confinement: paths can change between the check and the tool operation. Bash matching is literal and cannot reliably detect indirect access through scripts, variables, or shell expansion; do not rely on guardian alone as a security boundary against untrusted shell commands.
+Defaults protect `.env` from read/write/edit/Bash, `.git/` from read/write/edit, `node_modules/` from write/edit, and `~/.pi/agent/auth.json` from read/write/edit/Bash. File-tool path checks compare both the supplied path and its filesystem-resolved target, including existing symlinks and symlinked parents for new files; paths that cannot be safely resolved are blocked when an applicable path rule is active. A path denial is a hard block and takes precedence over a dangerous-command confirmation for the same Bash call. These are preflight checks, not filesystem confinement: paths can change between the check and the tool operation. Bash matching is literal and cannot reliably detect indirect access through scripts, variables, or shell expansion (for example `cat "$HOME/.pi/agent/auth.json"` misses the auth file); it also over-blocks commands that merely *mention* a protected path or name (for example `grep .env notes.md`). Do not rely on guardian alone as a security boundary against untrusted shell commands.
 
 ### Destructive session actions
 
@@ -31,7 +31,7 @@ Starting a new session, resuming another session with a pending user message, an
 
 ### Malformed provider tool calls
 
-A tool call is malformed when its ID or name is blank after trimming whitespace. The extension drops malformed calls before Pi persists or replays them, preserves valid sibling calls, and turns invalid-only responses into a text-only stop so the user can continue. Unfamiliar but non-empty tool names are not rejected.
+A tool call is malformed when its ID or name is blank after trimming whitespace. The extension drops malformed calls before Pi persists or replays them, preserves valid sibling calls, and turns invalid-only responses into a text-only stop so the user can continue. Unfamiliar but non-empty tool names are not rejected. As defense in depth, the `tool_call` boundary also blocks any blank-id/name call that slips through, so a malformed call can never execute even if the `message_end` filter is bypassed.
 
 ## Forensic JSONL
 
@@ -41,7 +41,7 @@ Each malformed-call incident appends one JSON object to:
 <project cwd>/err/guardian.jsonl
 ```
 
-Records include timestamp, session/project/provider/model metadata, and removed tool-call blocks. The log does not contain prompts, assistant text, thinking, or tool results, but tool-call arguments may include paths, commands, or user text. Treat it as local diagnostic data and ignore `err/` in version control where appropriate. On POSIX, a newly created log is restricted to mode `0600` on a best-effort basis. If logging fails, malformed calls are still removed and the diagnostic reports the write failure.
+Records include timestamp (falling back to the current time when a provider omitted or zeroed it), session/project/provider/model metadata, and removed tool-call blocks. The log does not contain prompts, assistant text, thinking, or tool results, but tool-call arguments may include paths, commands, or user text. Treat it as local diagnostic data and ignore `err/` in version control where appropriate. On POSIX, a newly created log is restricted to mode `0600` on a best-effort basis. If logging fails, malformed calls are still removed and the diagnostic reports the write failure.
 
 ## Testing
 

package/extensions/opl-guardian/guardian.ts

@@ -56,8 +56,12 @@ export function buildIncidentRecord(
   context: IncidentContext,
   removedToolCalls: ToolCall[],
 ): GuardianIncident {
+  // A missing/zero/NaN timestamp yields an invalid Date whose toISOString() throws,
+  // which would silently lose the forensic record. Fall back to the current time.
+  const timestamp =
+    Number.isFinite(message.timestamp) && message.timestamp > 0 ? message.timestamp : Date.now();
   return {
-    timestamp: new Date(message.timestamp).toISOString(),
+    timestamp: new Date(timestamp).toISOString(),
     kind: "malformed_tool_call",
     sessionId: context.sessionId,
     cwd: context.cwd,