@openlines/opl-pi-sht 0.2.6 → 0.2.8

package/extensions/opl-questionnaire/index.ts

@@ -27,16 +27,41 @@ import {
 	type RenderOption,
 } from "./types.js";
 
-function errorResult(
+/** Build an error tool result. Marked as an error (not a cancellation) so the
+ *  result card renders the message instead of mislabeling it "Cancelled". */
+export function errorResult(
 	message: string,
-	questions: Question[] = [],
-): { content: { type: "text"; text: string }[]; details: QuestionnaireResult } {
+): { content: { type: "text"; text: string }[]; isError: true; details: QuestionnaireResult } {
 	return {
 		content: [{ type: "text", text: message }],
-		details: { questions, answers: [], cancelled: true },
+		isError: true,
+		details: { questions: [], answers: [], cancelled: false },
 	};
 }
 
+/** Validate the question list. Returns the first error message, or null when valid.
+ *  Blank ids are rejected (answers are keyed by id and "" would produce an empty key),
+ *  as are duplicate ids and questions with nothing selectable. */
+export function validateQuestions(questions: Question[]): string | null {
+	const seenIds = new Set<string>();
+	for (const q of questions) {
+		if (q.id.trim() === "") {
+			return "Error: Question id must be a non-empty string";
+		}
+		if (seenIds.has(q.id)) {
+			return `Error: Duplicate question id "${q.id}" — question ids must be unique`;
+		}
+		seenIds.add(q.id);
+	}
+	for (const q of questions) {
+		const allowOther = q.allowOther !== false;
+		if (q.options.length === 0 && !allowOther) {
+			return `Error: Question "${q.id}" has no options and allowOther is false — nothing is selectable`;
+		}
+	}
+	return null;
+}
+
 export default function questionnaire(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "questionnaire",
@@ -58,23 +83,9 @@ export default function questionnaire(pi: ExtensionAPI) {
 				return errorResult("Error: No questions provided");
 			}
 
-			// Reject duplicate ids — answers are keyed by id and would silently collide.
-			const seenIds = new Set<string>();
-			for (const q of params.questions) {
-				if (seenIds.has(q.id)) {
-					return errorResult(`Error: Duplicate question id "${q.id}" — question ids must be unique`);
-				}
-				seenIds.add(q.id);
-			}
-
-			// Reject unselectable questions (no options and no free-text fallback).
-			for (const q of params.questions) {
-				const allowOther = q.allowOther !== false;
-				if (q.options.length === 0 && !allowOther) {
-					return errorResult(
-						`Error: Question "${q.id}" has no options and allowOther is false — nothing is selectable`,
-					);
-				}
+			const validationError = validateQuestions(params.questions);
+			if (validationError) {
+				return errorResult(validationError);
 			}
 
 			// Normalize questions with defaults
@@ -424,6 +435,10 @@ export default function questionnaire(pi: ExtensionAPI) {
 		},
 
 		renderResult(result, _options, theme, _context) {
+			if (result.isError) {
+				const text = result.content[0];
+				return new Text(theme.fg("error", text?.type === "text" ? text.text : ""), 0, 0);
+			}
 			const details = result.details as QuestionnaireResult | undefined;
 			if (!details) {
 				const text = result.content[0];

package/extensions/opl-webaccess/README.md

@@ -5,8 +5,8 @@ Provides configurable web search and readable URL/PDF retrieval with session-bac
 ## Commands, flags, and shortcuts
 
 - Tools: `web_search`, `fetch_content`, and `get_search_content`.
-- `web_search` accepts `query` or parallel `queries`.
-- `fetch_content` accepts `url` or `urls` with at most three requests in flight.
+- `web_search` accepts `query` or parallel `queries` (at most 10 per call).
+- `fetch_content` accepts `url` or `urls` (at most 20 per call) with at most three requests in flight.
 - `get_search_content` uses a prior `responseId`, with `queryIndex`, `urlIndex`, or exact `url` selection. It returns one bounded page; pass `offset` to continue a truncated retrieval.
 - No slash commands or shortcuts.
 
@@ -14,8 +14,8 @@ Provides configurable web search and readable URL/PDF retrieval with session-bac
 
 - Searches through `gemini`, `tavily`, `ddgs`, `searxng`, or `exa`; multiple queries run concurrently and results include citations where available.
 - Extracts HTML with Readability and Markdown conversion, falls back to full-document Turndown conversion, passes PDF responses to the PDF extractor, and returns plain text, Markdown, and JSON directly.
-- Restricts `fetch_content` to http/https, caps each response at 10 MB, and applies a 30s timeout; Gemini keys are sent via the `x-goog-api-key` header rather than the query string.
-- Caps initial tool output at a configurable length (default 30,000 characters), then keeps it for retrieval for one hour or until the session ends.
+- Restricts `fetch_content` to http/https and blocks private-range, link-local, and reserved hosts by default, re-checks every redirect hop, and always blocks cloud-metadata endpoints (SSRF guard). Loopback (`localhost`/`127.0.0.0/8`/`::1`) is allowed by default for local development; set `allowPrivateNetwork: true` to reach private ranges. Caps each response at 10 MB and applies a 30s timeout; Gemini keys are sent via the `x-goog-api-key` header rather than the query string.
+- Caps initial tool output at a configurable length (default 30,000 characters), then keeps it for retrieval for one hour (expiry is enforced on read, not just on write) or until the session ends.
 - Pages `get_search_content` results (default 30,000 characters per page) with `offset` continuation, so a model never loads the whole stored body in one call.
 - Honors abort signals and returns provider, HTTP, and per-result failures through the tool boundary rather than throwing.
 
@@ -33,7 +33,7 @@ Copy [`configs/opl-webaccess.json.sample`](../../configs/opl-webaccess.json.samp
 }
 ```
 
-Provider fields include `apiKeyEnv`, `apiUrl`, `baseUrl`, `model`, `maxResults`, `instanceUrl`, `categories`, `safeSearch`, `searchType`, and `includeSummary`. API keys are read only from named environment variables. Missing or invalid config falls back to Gemini defaults; an unknown provider returns an error.
+Provider fields include `apiKeyEnv`, `apiUrl`, `baseUrl`, `model`, `maxResults`, `instanceUrl`, `categories`, `safeSearch`, `searchType`, and `includeSummary`. API keys are read only from named environment variables. Malformed config falls back to Gemini defaults - a non-object config, a non-string `provider`, a non-object `providers` map, or non-positive cap values (`maxContentChars`/`maxRetrievalChars`) are all treated as unset; an unknown provider returns an error.
 
 Optional top-level caps control how much content reaches the model:
 
@@ -41,6 +41,9 @@ Optional top-level caps control how much content reaches the model:
 |---|---|---|
 | `maxContentChars` | `30000` | Cap on the initial `web_search`/`fetch_content` body. |
 | `maxRetrievalChars` | `30000` | Cap on one `get_search_content` page. Pass `offset` to continue. |
+| `maxSearchQueries` | `10` | Cap on how many queries one `web_search` call runs. Excess queries are skipped and reported. |
+| `maxFetchUrls` | `20` | Cap on how many URLs one `fetch_content` call fetches. Excess URLs are skipped and reported. |
+| `allowPrivateNetwork` | `false` | Allow `fetch_content` to reach private/link-local ranges (loopback is always allowed; cloud metadata is always blocked). Provider API endpoints (e.g. `ddgs.apiUrl`, `searxng.instanceUrl`) are excluded from this guard. |
 
 Install extraction dependencies before use:
 

package/extensions/opl-webaccess/config.ts

@@ -22,16 +22,36 @@ export interface WebAccessConfig {
   maxContentChars?: number;
   /** Cap on one get_search_content retrieval page (chars). */
   maxRetrievalChars?: number;
+  /** Cap on the number of queries a single web_search call may run. */
+  maxSearchQueries?: number;
+  /** Cap on the number of URLs a single fetch_content call may fetch. */
+  maxFetchUrls?: number;
+  /** Allow fetch_content to reach private/link-local ranges (loopback is always
+   *  allowed; cloud metadata is always blocked). Default false. */
+  allowPrivateNetwork?: boolean;
 }
 
 export const DEFAULT_MAX_CONTENT_CHARS = 30_000;
 export const DEFAULT_MAX_RETRIEVAL_CHARS = 30_000;
+export const DEFAULT_MAX_SEARCH_QUERIES = 10;
+export const DEFAULT_MAX_FETCH_URLS = 20;
 
-/** Resolve configurable content caps, falling back to defaults. */
-export function resolveCaps(cfg: Pick<WebAccessConfig, "maxContentChars" | "maxRetrievalChars">) {
+/** Coerce an unknown value into a positive integer, else the fallback. */
+function positiveInt(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/** Resolve configurable caps, falling back to defaults when a cap is missing or not
+ *  a positive finite number (a string/negative/zero cap would otherwise make
+ *  truncate/slice produce empty, inverted, or unbounded output). */
+export function resolveCaps(
+  cfg: Pick<WebAccessConfig, "maxContentChars" | "maxRetrievalChars" | "maxSearchQueries" | "maxFetchUrls">,
+) {
   return {
-    maxContentChars: cfg.maxContentChars ?? DEFAULT_MAX_CONTENT_CHARS,
-    maxRetrievalChars: cfg.maxRetrievalChars ?? DEFAULT_MAX_RETRIEVAL_CHARS,
+    maxContentChars: positiveInt(cfg.maxContentChars, DEFAULT_MAX_CONTENT_CHARS),
+    maxRetrievalChars: positiveInt(cfg.maxRetrievalChars, DEFAULT_MAX_RETRIEVAL_CHARS),
+    maxSearchQueries: positiveInt(cfg.maxSearchQueries, DEFAULT_MAX_SEARCH_QUERIES),
+    maxFetchUrls: positiveInt(cfg.maxFetchUrls, DEFAULT_MAX_FETCH_URLS),
   };
 }
 
@@ -50,12 +70,43 @@ const DEFAULT_CONFIG: WebAccessConfig = {
 
 export function loadConfig(): WebAccessConfig {
   if (!existsSync(CONFIG_PATH)) return DEFAULT_CONFIG;
+  let parsed: unknown;
   try {
-    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as WebAccessConfig;
+    parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
   } catch {
     console.error(`[opl-webaccess] failed to parse ${CONFIG_PATH}, using defaults`);
     return DEFAULT_CONFIG;
   }
+  return normalizeConfig(parsed);
+}
+
+/** Validate a parsed config so malformed fields fall back to defaults instead of
+ *  silently misbehaving downstream (a non-object config, a non-string provider, or
+ *  a non-object providers map are all treated as unset). Cap values are validated
+ *  in resolveCaps. */
+function normalizeConfig(parsed: unknown): WebAccessConfig {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    console.error("[opl-webaccess] config is not a JSON object, using defaults");
+    return DEFAULT_CONFIG;
+  }
+  const record = parsed as Record<string, unknown>;
+  const provider =
+    typeof record.provider === "string" && record.provider.trim() !== ""
+      ? record.provider
+      : DEFAULT_CONFIG.provider;
+  const providers =
+    typeof record.providers === "object" && record.providers !== null && !Array.isArray(record.providers)
+      ? (record.providers as Record<string, ProviderConfig>)
+      : DEFAULT_CONFIG.providers;
+  return {
+    provider,
+    providers,
+    maxContentChars: record.maxContentChars as number | undefined,
+    maxRetrievalChars: record.maxRetrievalChars as number | undefined,
+    maxSearchQueries: record.maxSearchQueries as number | undefined,
+    maxFetchUrls: record.maxFetchUrls as number | undefined,
+    allowPrivateNetwork: record.allowPrivateNetwork === true,
+  };
 }
 
 export function getApiKey(cfg: ProviderConfig): string {

package/extensions/opl-webaccess/extract.ts

@@ -2,12 +2,15 @@ import { Readability } from "@mozilla/readability";
 import { parseHTML } from "linkedom";
 import TurndownService from "turndown";
 import { extractPdfBuffer } from "./pdf.js";
-import { errorMessage, isAbortError, isPdfUrl, isPdfContentType, assertHttpUrl } from "./utils.js";
+import { errorMessage, isAbortError, isPdfUrl, isPdfContentType, assertHttpUrl, type HttpUrlOptions } from "./utils.js";
 import type { ExtractedContent } from "./types.js";
 
 const CONCURRENT_LIMIT = 3;
 const MAX_FETCH_BYTES = 10 * 1024 * 1024; // 10 MB response cap
 const FETCH_TIMEOUT_MS = 30_000;
+const MAX_REDIRECTS = 5;
+/** Ceiling on the number of URLs a single fetch_content call may include. */
+export const MAX_FETCH_URLS = 20;
 
 const td = new TurndownService({
   headingStyle: "atx",
@@ -43,31 +46,53 @@ async function readBufferCapped(response: Response, maxBytes: number): Promise<A
 
 export async function fetchAllContent(
   urls: string[],
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  opts: HttpUrlOptions = {},
+  maxUrls: number = MAX_FETCH_URLS,
 ): Promise<ExtractedContent[]> {
+  const bounded = urls.slice(0, maxUrls);
   const results: ExtractedContent[] = [];
-  for (let i = 0; i < urls.length; i += CONCURRENT_LIMIT) {
+  for (let i = 0; i < bounded.length; i += CONCURRENT_LIMIT) {
     if (signal?.aborted) break;
-    const batch = urls.slice(i, i + CONCURRENT_LIMIT);
-    const batchResults = await Promise.all(batch.map((url) => fetchOne(url, signal)));
+    const batch = bounded.slice(i, i + CONCURRENT_LIMIT);
+    const batchResults = await Promise.all(batch.map((url) => fetchOne(url, signal, opts)));
     results.push(...batchResults);
   }
   return results;
 }
 
-async function fetchOne(url: string, signal?: AbortSignal): Promise<ExtractedContent> {
+/**
+ * Fetch with redirects followed manually so each hop is re-validated. The native
+ * `redirect: "follow"` would let a public URL bounce to a private/link-local host
+ * past the `assertHttpUrl` check.
+ */
+async function fetchWithRedirectValidation(
+  url: string,
+  fetchSignal: AbortSignal,
+  opts: HttpUrlOptions
+): Promise<Response> {
+  let current = assertHttpUrl(url, opts);
+  const headers = {
+    "User-Agent": "Mozilla/5.0 (compatible; pi-web-access/1.0)",
+    Accept: "text/html,application/xhtml+xml,application/pdf,*/*",
+  };
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await fetch(current, { signal: fetchSignal, headers, redirect: "manual" });
+    if (response.status < 300 || response.status >= 400) return response;
+    const location = response.headers.get("location");
+    if (!location) return response; // 3xx without a Location: treat as final
+    await response.body?.cancel().catch(() => {});
+    current = assertHttpUrl(new URL(location, current).href, opts);
+  }
+  throw new Error(`Too many redirects (max ${MAX_REDIRECTS})`);
+}
+
+async function fetchOne(url: string, signal?: AbortSignal, opts: HttpUrlOptions = {}): Promise<ExtractedContent> {
   try {
-    const target = assertHttpUrl(url);
     const fetchSignal = signal
       ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
       : AbortSignal.timeout(FETCH_TIMEOUT_MS);
-    const response = await fetch(target, {
-      signal: fetchSignal,
-      headers: {
-        "User-Agent": "Mozilla/5.0 (compatible; pi-web-access/1.0)",
-        Accept: "text/html,application/xhtml+xml,application/pdf,*/*",
-      },
-    });
+    const response = await fetchWithRedirectValidation(url, fetchSignal, opts);
 
     if (!response.ok) {
       return { url, title: "", content: "", error: `HTTP ${response.status}: ${url}` };

package/extensions/opl-webaccess/index.ts

@@ -14,7 +14,15 @@ import { loadConfig, resolveCaps } from "./config.js";
 import type { StoredData } from "./types.js";
 
 export default function (pi: ExtensionAPI) {
-  const caps = resolveCaps(loadConfig());
+  const config = loadConfig();
+  const caps = resolveCaps(config);
+  const allowPrivateNetwork = config.allowPrivateNetwork === true;
+
+  // Note shown to the model when the per-call URL/query cap drops some inputs.
+  const skippedNote = (dropped: number, limit: number, singular: string, plural: string) =>
+    dropped > 0
+      ? `\n\n*Note: ${dropped} additional ${dropped === 1 ? singular : plural} beyond the per-call limit of ${limit} ${dropped === 1 ? "was" : "were"} skipped.*`
+      : "";
 
   pi.on("session_start", async (_event, ctx) => {
     restoreFromSession(ctx);
@@ -34,18 +42,27 @@ export default function (pi: ExtensionAPI) {
       ),
     }),
     async execute(_toolCallId, params, signal) {
-      const queryList = params.queries ?? (params.query ? [params.query] : null);
-      if (!queryList?.length) {
+      const rawQueries = params.queries ?? (params.query ? [params.query] : null);
+      if (!rawQueries?.length) {
         return {
           content: [{ type: "text", text: "Error: provide either query or queries." }],
           isError: true,
           details: {} as Record<string, unknown>,
         };
       }
+      const queryList = rawQueries.slice(0, caps.maxSearchQueries);
+      const dropped = rawQueries.length - queryList.length;
 
       let results;
       try {
-        results = await Promise.all(queryList.map((q) => searchWeb(q, signal)));
+        // allSettled so one provider's throw (non-JSON body, missing key) cannot
+        // discard the sibling queries' results.
+        const settled = await Promise.allSettled(queryList.map((q) => searchWeb(q, signal)));
+        results = settled.map((s, i) =>
+          s.status === "fulfilled"
+            ? s.value
+            : { query: queryList[i], answer: "", results: [], error: errorMessage(s.reason) }
+        );
       } catch (err) {
         return {
           content: [{ type: "text", text: `Error: ${errorMessage(err)}` }],
@@ -70,8 +87,9 @@ export default function (pi: ExtensionAPI) {
       });
 
       const body = truncate(sections.join("\n\n---\n\n"), caps.maxContentChars);
+      const note = skippedNote(dropped, caps.maxSearchQueries, "query", "queries");
       return {
-        content: [{ type: "text", text: `${body}\n\n*responseId: ${id}*` }],
+        content: [{ type: "text", text: `${body}${note}\n\n*responseId: ${id}*` }],
         details: { responseId: id, queryCount: results.length },
       };
     },
@@ -101,8 +119,9 @@ export default function (pi: ExtensionAPI) {
       }
 
       let results;
+      const dropped = urlList.length > caps.maxFetchUrls ? urlList.length - caps.maxFetchUrls : 0;
       try {
-        results = await fetchAllContent(urlList, signal);
+        results = await fetchAllContent(urlList, signal, { allowPrivateNetwork }, caps.maxFetchUrls);
       } catch (err) {
         return {
           content: [{ type: "text", text: `Error: ${errorMessage(err)}` }],
@@ -123,8 +142,9 @@ export default function (pi: ExtensionAPI) {
       });
 
       const body = truncate(sections.join("\n\n---\n\n"), caps.maxContentChars);
+      const note = skippedNote(dropped, caps.maxFetchUrls, "URL", "URLs");
       return {
-        content: [{ type: "text", text: `${body}\n\n*responseId: ${id}*` }],
+        content: [{ type: "text", text: `${body}${note}\n\n*responseId: ${id}*` }],
         details: { responseId: id, urlCount: results.length },
       };
     },

package/extensions/opl-webaccess/providers/gemini.ts

@@ -41,7 +41,12 @@ export async function searchGemini(
     return { query, answer: "", results: [], error: errorMessage(err) };
   }
 
-  const data = (await response.json()) as GeminiResponse;
+  let data: GeminiResponse;
+  try {
+    data = (await response.json()) as GeminiResponse;
+  } catch {
+    return { query, answer: "", results: [], error: `Gemini API error: HTTP ${response.status} (non-JSON response)` };
+  }
 
   if (!response.ok) {
     const msg = data.error?.message ?? `HTTP ${response.status}`;

package/extensions/opl-webaccess/providers/tavily.ts

@@ -39,7 +39,12 @@ export async function searchTavily(
     return { query, answer: "", results: [], error: errorMessage(err) };
   }
 
-  const data = (await response.json()) as TavilyResponse;
+  let data: TavilyResponse;
+  try {
+    data = (await response.json()) as TavilyResponse;
+  } catch {
+    return { query, answer: "", results: [], error: `Tavily API error: HTTP ${response.status} (non-JSON response)` };
+  }
 
   if (!response.ok) {
     return { query, answer: "", results: [], error: `Tavily API error: HTTP ${response.status}` };

package/extensions/opl-webaccess/storage.ts

@@ -23,8 +23,14 @@ export function storeResult(id: string, data: StoredData): void {
   evictExpired();
 }
 
-export function getResult(id: string): StoredData | null {
-  return store.get(id) ?? null;
+export function getResult(id: string, now: number = Date.now()): StoredData | null {
+  const data = store.get(id);
+  if (!data) return null;
+  if (now - data.timestamp >= CACHE_TTL_MS) {
+    store.delete(id);
+    return null;
+  }
+  return data;
 }
 
 export function clearStore(): void {

package/extensions/opl-webaccess/utils.ts

@@ -54,8 +54,120 @@ export function isPdfContentType(contentType: string): boolean {
   return contentType.toLowerCase().includes("application/pdf");
 }
 
-/** Normalize a URL, allowing only http/https (file:/data:/etc. are rejected). */
-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";
+
+/** Decode a bare unsigned 32-bit integer hostname (e.g. 2130706433) into octets. */
+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];
+}
+
+/** Parse a host into IPv4 octets (dotted-quad or integer form), or null when not an IPv4 literal. */
+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) || // AWS/Azure/GCP/Oracle
+    (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200) // Alibaba
+  );
+}
+
+/** Non-globally-routable (blocked by default, opt-in via allowPrivateNetwork). */
+function isPrivateIpv4(o: number[]): boolean {
+  const [a, b, c] = o;
+  return (
+    a === 0 || a === 10 || // 0.0.0.0/8, 10/8
+    (a === 100 && b >= 64 && b <= 127) || // 100.64/10 carrier-grade NAT
+    (a === 169 && b === 254) || // 169.254/16 link-local
+    (a === 172 && b >= 16 && b <= 31) || // 172.16/12
+    (a === 192 && b === 168) || // 192.168/16
+    (a === 192 && b === 0 && (c === 0 || c === 2)) || // 192.0.0/24, 192.0.2/24
+    (a === 198 && (b === 18 || b === 19)) || // 198.18/15 benchmark
+    (a === 198 && b === 51 && c === 100) || // 198.51.100/24
+    (a === 203 && b === 0 && c === 113) || // 203.0.113/24
+    a >= 224 // 224/4 multicast and 240/4 reserved
+  );
+}
+
+/** Decode IPv4 from an IPv4-mapped IPv6 literal (::ffff:a.b.c.d or ::ffff:hex:hex). */
+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"; // unspecified
+  if (/^f[cd]/.test(ip)) return "private"; // fc00::/7 unique-local
+  if (/^fe[89ab]/.test(ip)) return "private"; // fe80::/10 link-local
+  if (/^ff/.test(ip)) return "private"; // ff00::/8 multicast
+  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; // never toggleable
+  if (cls === "loopback" || cls === "public") return false;
+  return !allowPrivateNetwork; // private / link-local / reserved
+}
+
+/**
+ * Normalize a URL, allowing only http/https. Loopback (localhost/127.0.0.0/8/::1) 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);
@@ -65,5 +177,8 @@ export function assertHttpUrl(url: string): string {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`Unsupported protocol "${parsed.protocol}//" — only http/https`);
   }
+  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;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.6",
-  "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, safe modes, fingerprinted /init, model benchmarking, web access, and browser automation.",
+  "version": "0.2.8",
+  "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, tool and session safety, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
     "url": "https://github.com/linellazatin/opl-pi-sht.git"
@@ -47,7 +47,7 @@
     "test:opl-init": "bun test tests/opl-init-crawl.test.mjs tests/opl-init-fingerprint.test.mjs tests/opl-init-packet.test.mjs && OPL_EXTENSION=opl-init bun test tests/extension-smoke.test.mjs",
     "test:opl-input": "bun test tests/opl-input-style.test.mjs && OPL_EXTENSION=opl-input bun test tests/extension-smoke.test.mjs",
     "test:opl-modes": "bun test tests/opl-modes-helpers.test.mjs tests/opl-modes-lifecycle.test.mjs && OPL_EXTENSION=opl-modes bun test tests/extension-smoke.test.mjs",
-    "test:opl-questionnaire": "OPL_EXTENSION=opl-questionnaire bun test tests/extension-smoke.test.mjs",
+    "test:opl-questionnaire": "bun test tests/opl-questionnaire-helpers.test.mjs && OPL_EXTENSION=opl-questionnaire bun test tests/extension-smoke.test.mjs",
     "test:opl-todo": "bun test tests/opl-todo-config.test.mjs tests/opl-todo-render.test.mjs && OPL_EXTENSION=opl-todo bun test tests/extension-smoke.test.mjs",
     "test:opl-webaccess": "bun test tests/opl-webaccess-helpers.test.mjs && OPL_EXTENSION=opl-webaccess bun test tests/extension-smoke.test.mjs",
     "test:opl-simplebench": "bun test tests/opl-simplebench.test.ts && OPL_EXTENSION=opl-simplebench bun test tests/extension-smoke.test.mjs",