@openlines/opl-pi-sht 0.2.12 → 0.3.1

package/extensions/opl-webaccess/storage.ts

@@ -1,8 +1,20 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { StoredData } from "./types.js";
 
 const CUSTOM_TYPE = "web-access-results";
-const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+export const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Bytes of body text kept per item in the session copy. The body itself is
+ * spilled to `cacheDir()`; a session used to hold every fetched byte forever
+ * (up to 10 MB x 20 URLs per call) while the in-memory cache only lives an hour.
+ */
+export const PREVIEW_ITEM_BYTES = 512;
+/** Ceiling for the spill directory; the oldest bodies are dropped past it. */
+export const MAX_CACHE_BYTES = 32 * 1024 * 1024;
 
 const store = new Map<string, StoredData>();
 
@@ -18,11 +30,119 @@ export function generateId(): string {
   return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
 
+/** Where full bodies are spilled: outside the session file, inside pi's agent dir. */
+export function cacheDir(): string {
+  return join(getAgentDir(), "web-access-cache");
+}
+
+/** Only our own ids are ever turned into a path. */
+function cacheFileFor(id: string): string | null {
+  if (!/^[a-z0-9]+$/i.test(id)) return null;
+  return join(cacheDir(), `${id}.json`);
+}
+
+function capItem(text: string): string {
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= PREVIEW_ITEM_BYTES) return text;
+  let head = Buffer.from(text, "utf8").subarray(0, PREVIEW_ITEM_BYTES).toString("utf8");
+  if (head.endsWith("\uFFFD")) head = head.slice(0, -1); // never cut mid-codepoint
+  const omitted = bytes - Buffer.byteLength(head, "utf8");
+  return `${head}\n\n[… ${omitted} bytes omitted from the session copy — the full body stays in the disk cache for ${Math.round(CACHE_TTL_MS / 60000)} minutes]`;
+}
+
+/** A bounded copy for the session entry: identity plus the head of each body. */
+export function previewize(data: StoredData): StoredData {
+  const out: StoredData = { id: data.id, type: data.type, timestamp: data.timestamp };
+  let truncated = false;
+  if (data.queries) {
+    out.queries = data.queries.map((q) => {
+      const answer = capItem(q.answer ?? "");
+      truncated ||= answer !== (q.answer ?? "");
+      return { ...q, answer };
+    });
+  }
+  if (data.urls) {
+    out.urls = data.urls.map((u) => {
+      const content = capItem(u.content ?? "");
+      truncated ||= content !== (u.content ?? "");
+      return { ...u, content };
+    });
+  }
+  if (truncated) out.truncated = true;
+  return out;
+}
+
+/** Write the full body to the disk cache. A cache we cannot write must not fail the call. */
+function spill(data: StoredData): string | null {
+  const file = cacheFileFor(data.id);
+  if (!file) return null;
+  try {
+    mkdirSync(cacheDir(), { recursive: true });
+    writeFileSync(file, JSON.stringify(data), "utf8");
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+function readSpill(data: StoredData): StoredData | null {
+  if (!data.file) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(data.file, "utf8")) as StoredData;
+    return parsed && parsed.id === data.id && parsed.type === data.type ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drop expired bodies, then trim the oldest ones until the directory fits
+ * MAX_CACHE_BYTES. Returns how many files were removed.
+ */
+export function pruneCache(now: number = Date.now(), maxBytes: number = MAX_CACHE_BYTES): number {
+  const dir = cacheDir();
+  if (!existsSync(dir)) return 0;
+  const cutoff = now - CACHE_TTL_MS;
+  let removed = 0;
+  const alive: { path: string; mtimeMs: number; size: number }[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(dir, name);
+    try {
+      const stat = statSync(path);
+      if (stat.mtimeMs < cutoff) {
+        rmSync(path, { force: true });
+        removed++;
+        continue;
+      }
+      alive.push({ path, mtimeMs: stat.mtimeMs, size: stat.size });
+    } catch {
+      // Raced away between readdir and stat: nothing to keep.
+    }
+  }
+  let total = alive.reduce((sum, f) => sum + f.size, 0);
+  if (total > maxBytes) {
+    alive.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+    for (const f of alive) {
+      if (total <= maxBytes) break;
+      rmSync(f.path, { force: true });
+      total -= f.size;
+      removed++;
+    }
+  }
+  return removed;
+}
+
 export function storeResult(id: string, data: StoredData): void {
   store.set(id, data);
   evictExpired();
 }
 
+/**
+ * Read a result. Entries restored from the session hold a preview plus a pointer;
+ * the full body is hydrated from disk on first read and cached in memory, so
+ * session_start never has to open every file.
+ */
 export function getResult(id: string, now: number = Date.now()): StoredData | null {
   const data = store.get(id);
   if (!data) return null;
@@ -30,6 +150,13 @@ export function getResult(id: string, now: number = Date.now()): StoredData | nu
     store.delete(id);
     return null;
   }
+  if (data.truncated && data.file) {
+    const full = readSpill(data);
+    if (full) {
+      store.set(id, full);
+      return full;
+    }
+  }
   return data;
 }
 
@@ -37,8 +164,13 @@ export function clearStore(): void {
   store.clear();
 }
 
+/** Persist a pointer plus a bounded preview; the body goes to the disk cache. */
 export function persistResult(pi: ExtensionAPI, data: StoredData): void {
-  pi.appendEntry(CUSTOM_TYPE, data);
+  const entry = previewize(data);
+  const file = spill(data);
+  if (file) entry.file = file;
+  pi.appendEntry(CUSTOM_TYPE, entry);
+  pruneCache();
 }
 
 export function restoreFromSession(ctx: ExtensionContext): void {

package/extensions/opl-webaccess/types.ts

@@ -23,4 +23,8 @@ export interface StoredData {
   timestamp: number;
   queries?: SearchQueryResult[];
   urls?: ExtractedContent[];
+  /** True when this is the session copy: body text was capped and lives in `file`. */
+  truncated?: boolean;
+  /** Path of the spilled full body in the disk cache, when one was written. */
+  file?: string;
 }

package/extensions/opl-webaccess/utils.ts

@@ -1,3 +1,6 @@
+import { promises as dns } from "node:dns";
+import type { PinnedFetchOptions, PinnedResponse } from "./http.js";
+
 export function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
@@ -55,10 +58,31 @@ export function isPdfContentType(contentType: string): boolean {
 }
 
 export interface HttpUrlOptions {
-  /** Allow private, link-local, and reserved network hosts (default false). Loopback is always allowed; cloud metadata is always blocked. */
+  /** Allow private, link-local, and reserved network hosts (default false). Cloud metadata is always blocked. */
   allowPrivateNetwork?: boolean;
+  /** Allow loopback hosts — localhost, 127.0.0.0/8, ::1 (default false: opt in). */
+  allowLoopback?: boolean;
+  /** Deadline for one request (ms), combined with the caller's signal so the shorter
+   *  of the two wins. Used by the fetch path; the guard itself ignores it. */
+  timeoutMs?: number;
+  /** Ceiling on one response body (bytes). The transport stops reading and drops the socket
+   *  past it, so an oversized page cannot cost memory before truncation gets a say. */
+  maxResponseBytes?: number;
+  /** Test seam for host resolution; production callers leave it unset and use node:dns. */
+  resolveHost?: (host: string) => Promise<string[]>;
+  /** Test seam for the socket layer; production callers leave it unset and use pinnedFetch.
+   *  The guard still runs - only the connection is replaced. */
+  transport?: (target: SafeHttpTarget, opts: PinnedFetchOptions) => Promise<PinnedResponse>;
+  /** Caller's abort signal. The lookup itself cannot be cancelled, so this only bounds how long
+   *  the caller waits; without it a stalled getaddrinfo outlives the caller's own timeout. */
+  signal?: AbortSignal;
+  /** Self-bound for the DNS round-trip when the caller passes no signal (ms). */
+  dnsTimeoutMs?: number;
 }
 
+// BEGIN SHARED HOST GUARD — duplicated verbatim in extensions/opl-browser/validate.ts
+// (install.sh installs one extension directory at a time, so this cannot be a shared import;
+//  tests/net-guard-parity.test.mjs fails if the two copies drift)
 /** Well-known cloud metadata hostnames that resolve to instance-credential endpoints. */
 const BLOCKED_METADATA_HOSTS = new Set([
   "metadata",
@@ -68,29 +92,55 @@ const BLOCKED_METADATA_HOSTS = new Set([
 ]);
 
 /** Cloud metadata IPv6 literals (e.g. AWS IMDS over IPv6). Always blocked. */
-const BLOCKED_METADATA_V6 = new Set(["fd00:ec2::254"]);
+const BLOCKED_METADATA_V6 = new Set(["fd00:ec2:0:0:0:0:0:254"]);
+
+type HostClass = "loopback" | "metadata" | "unspecified" | "translation" | "private" | "public";
 
-type HostClass = "loopback" | "metadata" | "private" | "public";
+/** The four octets of an IPv4 address. The arity is the whole point of the classifier, so it is a
+ *  tuple rather than a list whose elements TypeScript must assume could be missing. */
+type Ipv4 = readonly [number, number, number, number];
+/** The eight groups of an IPv6 literal, with any `::` already expanded. */
+type Ipv6Groups = readonly [number, number, number, number, number, number, number, number];
+
+/** Build a tuple from a list whose arity a length check established but `split`/`map` cannot show
+ *  to TypeScript. The length test keeps the previous rejection of over-long quads; the per-element
+ *  tests are what the compiler needs. These are the only two widening points in the guard. */
+function asIpv4(values: number[]): Ipv4 | null {
+  const [a, b, c, d] = values;
+  if (values.length !== 4 || a === undefined || b === undefined || c === undefined || d === undefined) return null;
+  return [a, b, c, d];
+}
+function asIpv6Groups(values: number[]): Ipv6Groups | null {
+  const [a, b, c, d, e, f, g, h] = values;
+  if (
+    values.length !== 8 ||
+    a === undefined || b === undefined || c === undefined || d === undefined ||
+    e === undefined || f === undefined || g === undefined || h === undefined
+  ) {
+    return null;
+  }
+  return [a, b, c, d, e, f, g, h];
+}
 
 /** Decode a bare unsigned 32-bit integer hostname (e.g. 2130706433) into octets. */
-function ipv4FromInteger(n: number): number[] | null {
+function ipv4FromInteger(n: number): Ipv4 | 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 {
+function ipv4Octets(host: string): Ipv4 | 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;
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+  return asIpv4(octets);
 }
 
-function isLoopbackIpv4(o: number[]): boolean {
+function isLoopbackIpv4(o: Ipv4): boolean {
   return o[0] === 127;
 }
 
-function isMetadataIpv4(o: number[]): boolean {
+function isMetadataIpv4(o: Ipv4): 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
@@ -98,10 +148,10 @@ function isMetadataIpv4(o: number[]): boolean {
 }
 
 /** Non-globally-routable (blocked by default, opt-in via allowPrivateNetwork). */
-function isPrivateIpv4(o: number[]): boolean {
+function isPrivateIpv4(o: Ipv4): boolean {
   const [a, b, c] = o;
   return (
-    a === 0 || a === 10 || // 0.0.0.0/8, 10/8
+    a === 10 || // 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
@@ -114,32 +164,84 @@ function isPrivateIpv4(o: number[]): boolean {
   );
 }
 
-/** 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];
+/** "This host on this network" (0.0.0.0/8, ::) — reaching it means reaching local listeners,
+ * so it is never toggleable the way cloud metadata is not. */
+function isUnspecifiedIpv4(o: Ipv4): boolean {
+  return o[0] === 0;
+}
+
+/** Expand a compressed, dotted-suffix or full IPv6 literal into its eight 16-bit groups. */
+function ipv6Groups(ip: string): Ipv6Groups | null {
+  const sides = ip.split("::");
+  if (sides.length > 2) return null;
+  const parse = (side: string): number[] | null => {
+    if (!side) return [];
+    const out: number[] = [];
+    for (const part of side.split(":")) {
+      const dotted = part.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+      if (dotted) {
+        const o = asIpv4(dotted.slice(1, 5).map(Number));
+        if (!o || o.some((n) => n > 255)) return null;
+        const [q0, q1, q2, q3] = o;
+        out.push((q0 << 8) | q1, (q2 << 8) | q3);
+        continue;
+      }
+      if (!part || !/^[0-9a-f]{1,4}$/.test(part)) return null;
+      out.push(parseInt(part, 16));
+    }
+    return out;
+  };
+  const head = parse(sides[0] ?? "");
+  if (!head) return null;
+  if (sides.length === 1) return asIpv6Groups(head);
+  const tail = parse(sides[1] ?? "");
+  if (!tail) return null;
+  const fill = 8 - head.length - tail.length;
+  if (fill < 1) return null; // `::` must stand for at least one zero group
+  return asIpv6Groups([...head, ...Array(fill).fill(0), ...tail]);
+}
+
+/** IPv4 that an IPv6 literal still routes to: mapped (`::ffff:`), NAT64 (`64:ff9b::/96`),
+ *  6to4 (`2002::/16`) and the deprecated IPv4-compatible form (`::a.b`).
+ *  Wherever those prefixes are still routable they reach the embedded address, so the embedded
+ *  address is what has to be classified — otherwise `http://[64:ff9b::a9fe:a9fe]/` walks past the
+ *  metadata block one literal away from 169.254.169.254, and a DNS64 answer can do the same. */
+function embeddedIpv4Octets(ip: string): Ipv4 | null {
+  const g = ipv6Groups(ip);
+  if (!g) return null;
+  const zeros = (from: number, to: number) => g.slice(from, to).every((x) => x === 0);
+  const low32 = (): Ipv4 => [(g[6] >> 8) & 0xff, g[6] & 0xff, (g[7] >> 8) & 0xff, g[7] & 0xff];
+  if (g[5] === 0xffff && zeros(0, 5)) return low32();
+  if (g[0] === 0x2002) {
+    return [(g[1] >> 8) & 0xff, g[1] & 0xff, (g[2] >> 8) & 0xff, g[2] & 0xff]; // 6to4 carries v4 after the prefix (tuple by return type)
+  }
+  if (g[0] === 0x0064 && g[1] === 0xff9b) {
+    if (zeros(2, 6)) return low32(); // NAT64 well-known prefix
   }
+  if (zeros(0, 6) && (g[6] !== 0 || g[7] !== 0)) return low32(); // IPv4-compatible (deprecated)
   return null;
 }
 
-function classifyIpv4Octets(o: number[]): HostClass {
+function classifyIpv4Octets(o: Ipv4): HostClass {
   if (isLoopbackIpv4(o)) return "loopback";
   if (isMetadataIpv4(o)) return "metadata";
+  if (isUnspecifiedIpv4(o)) return "unspecified";
   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
+  const groups = ipv6Groups(ip);
+  if (groups) {
+    if (BLOCKED_METADATA_V6.has(groups.map((g) => g.toString(16)).join(":"))) return "metadata";
+    if (groups.every((g) => g === 0)) return "unspecified";
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return "loopback";
+    // Local-use translation layouts vary; no opt-in may bypass this prefix block.
+    if (groups[0] === 0x0064 && groups[1] === 0xff9b && groups[2] === 1) return "translation";
+  }
+  const embedded = embeddedIpv4Octets(ip);
+  if (embedded) return classifyIpv4Octets(embedded);
   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
@@ -155,17 +257,18 @@ function classifyHost(host: string): HostClass {
   return octets ? classifyIpv4Octets(octets) : "public";
 }
 
-function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean): boolean {
+function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean, allowLoopback: boolean): boolean {
   const cls = classifyHost(host);
-  if (cls === "metadata") return true; // never toggleable
-  if (cls === "loopback" || cls === "public") return false;
+  if (cls === "metadata" || cls === "unspecified" || cls === "translation") return true; // never toggleable
+  if (cls === "loopback") return !allowLoopback;
+  if (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.
+ * opt-in through allowLoopback; private/link-local/reserved ranges are blocked unless
+ * allowPrivateNetwork is set; cloud metadata, unspecified addresses and 64:ff9b:1::/48 are always blocked.
  */
 export function assertHttpUrl(url: string, opts: HttpUrlOptions = {}): string {
   let parsed: URL;
@@ -175,10 +278,95 @@ export function assertHttpUrl(url: string, opts: HttpUrlOptions = {}): string {
     throw new Error(`Invalid URL: ${url}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`Unsupported protocol "${parsed.protocol}//" — only http/https`);
+    throw new Error(`Only http/https URLs are allowed, "${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)`);
+  if (isBlockedNetworkHost(parsed.hostname, opts.allowPrivateNetwork === true, opts.allowLoopback === true)) {
+    throw new Error(`Blocked network host "${parsed.hostname}" — private, link-local, and reserved URLs are not allowed (set allowPrivateNetwork to opt in to private ranges, or allowLoopback for localhost and 127.0.0.0/8; cloud-metadata, unspecified addresses such as 0.0.0.0, and the 64:ff9b:1::/48 translation prefix are always blocked)`);
   }
   return parsed.href;
 }
+
+export function isIpLiteralHost(host: string): boolean {
+  const lowered = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return lowered.includes(":") || /^\d+$/.test(lowered) || /^\d{1,3}(\.\d{1,3}){3}$/.test(lowered);
+}
+
+/** In-flight lookups by host. A page with hundreds of subresources on one host would otherwise
+ *  serialize hundreds of getaddrinfo calls on libuv's small thread pool. Entries are dropped as
+ *  soon as the lookup settles, so this deduplicates concurrency only: no decision is reused, and
+ *  a hostname that changes between two calls still gets two independent answers. */
+const inflightLookups = new Map<string, Promise<string[]>>();
+
+/** Default resolver. Rethrows the original error so `.code` survives for callers. */
+export function resolveHostAddresses(host: string): Promise<string[]> {
+  const running = inflightLookups.get(host);
+  if (running) return running;
+  const pending = dns
+    .lookup(host, { all: true, verbatim: true })
+    .then((hits) => hits.map((hit) => hit.address));
+  inflightLookups.set(host, pending);
+  const stop = () => {
+    if (inflightLookups.get(host) === pending) inflightLookups.delete(host);
+  };
+  pending.then(stop, stop);
+  return pending;
+}
+
+/** Reject as soon as the caller gives up. `dns.lookup` cannot be cancelled, so without this a
+ *  stalled getaddrinfo would hold the tool past its own timeout. */
+function untilAborted<T>(pending: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return pending;
+  const aborted = new Promise<never>((_, reject) => {
+    const fail = () => reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    if (signal.aborted) fail();
+    else signal.addEventListener("abort", fail, { once: true });
+  });
+  return Promise.race([pending, aborted]);
+}
+
+/** A URL that passed the policy check, together with the addresses that decision used. */
+export interface SafeHttpTarget {
+  /** Normalized absolute URL. */
+  url: string;
+  /** Hostname with any IPv6 brackets stripped. */
+  host: string;
+  /** The classified answers. A literal-IP host contributes that literal. */
+  addresses: string[];
+}
+
+/**
+ * Same policy as assertHttpUrl, plus a DNS round-trip: a hostname that answers with a
+ * loopback, private, link-local, reserved, or metadata address is rejected before any
+ * request is made. Literal-IP hosts skip the lookup. Text-only classification is not enough
+ * on its own — `http://169.254.169.254.nip.io/` reads as a public hostname.
+ *
+ * The answers are returned so a caller can pin its socket to one of them: validating a name
+ * and then letting the transport resolve it again leaves a window where a short-TTL record
+ * answers a public address at check time and an internal one at connect time.
+ */
+export async function resolveSafeHostUrl(url: string, opts: HttpUrlOptions = {}): Promise<SafeHttpTarget> {
+  const normalized = assertHttpUrl(url, opts);
+  const host = new URL(normalized).hostname.replace(/^\[|\]$/g, "");
+  if (isIpLiteralHost(host)) return { url: normalized, host, addresses: [host] }; // already classified; no DNS round-trip
+  // A stalled getaddrinfo must not outlive the caller's own budget, and with no caller signal
+  // (a browser route handler, a frame re-check) the guard bounds itself instead of hanging.
+  const dnsSignal = opts.signal ?? (opts.dnsTimeoutMs ? AbortSignal.timeout(opts.dnsTimeoutMs) : undefined);
+  const answers = opts.resolveHost
+    ? await untilAborted(Promise.resolve(opts.resolveHost(host)), dnsSignal)
+    : await untilAborted(resolveHostAddresses(host), dnsSignal);
+  if (!answers.length) throw new Error(`Could not resolve host "${host}"`);
+  const allowPrivate = opts.allowPrivateNetwork === true;
+  const allowLoopback = opts.allowLoopback === true;
+  for (const answer of answers) {
+    if (isBlockedNetworkHost(answer, allowPrivate, allowLoopback)) {
+      throw new Error(`Blocked network host "${host}" — it resolves to ${answer}, and private, link-local, and reserved addresses are not allowed (set allowPrivateNetwork to opt in to private ranges, or allowLoopback for localhost and 127.0.0.0/8; cloud-metadata, unspecified addresses such as 0.0.0.0, and the 64:ff9b:1::/48 translation prefix are always blocked)`);
+    }
+  }
+  return { url: normalized, host, addresses: answers };
+}
+
+/** `resolveSafeHostUrl` for callers that do not open a socket. */
+export async function assertSafeHttpUrl(url: string, opts: HttpUrlOptions = {}): Promise<string> {
+  return (await resolveSafeHostUrl(url, opts)).url;
+}
+// END SHARED HOST GUARD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.12",
+  "version": "0.3.1",
   "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",
@@ -8,7 +8,7 @@
   },
   "files": [
     "extensions/",
-    "configs/",
+    "configs/*.json.sample",
     "images/"
   ],
   "keywords": [
@@ -42,20 +42,27 @@
   "type": "module",
   "scripts": {
     "test": "node tests/test-summary.mjs",
-    "test:opl-browser": "bun test tests/opl-browser-helpers.test.mjs && OPL_EXTENSION=opl-browser bun test tests/extension-smoke.test.mjs",
-    "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs tests/opl-footer-lifecycle.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
-    "test:opl-guardian": "bun test tests/opl-guardian.test.mjs && OPL_EXTENSION=opl-guardian bun test tests/extension-smoke.test.mjs",
-    "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:shared": "bun test tests/agent-dir-config.test.mjs tests/net-guard-parity.test.mjs tests/cross-extension-seams.test.mjs tests/git-guard.test.mjs tests/session-cwd.test.mjs tests/install-sh.test.mjs tests/package-metadata.test.mjs",
+    "test:opl-browser": "bun test tests/opl-browser-helpers.test.mjs tests/opl-browser-page-target.test.mjs tests/opl-browser-screenshot-path.test.mjs && OPL_EXTENSION=opl-browser bun test tests/extension-smoke.test.mjs",
+    "test:opl-configurator": "bun test tests/opl-configurator.test.mjs && OPL_EXTENSION=opl-configurator bun test tests/extension-smoke.test.mjs",
+    "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs tests/opl-footer-lifecycle.test.mjs tests/opl-footer-git-invalidation.test.mjs tests/opl-footer-render-budget.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
+    "test:opl-guardian": "bun test tests/opl-guardian.test.mjs tests/opl-guardian-incident-log.test.mjs && OPL_EXTENSION=opl-guardian bun test tests/extension-smoke.test.mjs",
+    "test:opl-init": "bun test tests/opl-init-crawl.test.mjs tests/opl-init-fingerprint.test.mjs tests/opl-init-fingerprint-budget.test.mjs tests/opl-init-glob.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 tests/opl-input-pi-tui-markers.test.mjs tests/opl-input-config.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 tests/opl-modes-plan-budget.test.mjs && OPL_EXTENSION=opl-modes 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-todo": "bun test tests/opl-todo-config.test.mjs tests/opl-todo-render.test.mjs tests/opl-todo-widget-height.test.mjs && OPL_EXTENSION=opl-todo bun test tests/extension-smoke.test.mjs",
+    "test:opl-webaccess": "bun test tests/opl-webaccess-helpers.test.mjs tests/opl-webaccess-storage.test.mjs tests/opl-webaccess-search.test.mjs tests/opl-webaccess-http.test.mjs tests/opl-webaccess-redirect-pin.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",
     "test:opl-ctxtrim": "bun test tests/opl-ctxtrim.test.ts && OPL_EXTENSION=opl-ctxtrim bun test tests/extension-smoke.test.mjs",
-    "test:pi-host": "bun test tests/pi-host-loader.test.mjs"
+    "test:pi-host": "bun test tests/pi-host-loader.test.mjs",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.87.0"
+    "@earendil-works/pi-ai": ">=0.87.0",
+    "@earendil-works/pi-coding-agent": ">=0.87.0",
+    "@earendil-works/pi-tui": ">=0.87.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.2"
   }
 }