@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/web/src/native/convert.ts

@@ -0,0 +1,84 @@
+/**
+ * HTML-to-Markdown conversion for the native fetch backend.
+ *
+ * `linkedom`, `@mozilla/readability`, and `turndown` are imported on the first conversion only: a
+ * host that reads JSON or never fetches pays nothing for them. Readability keeps the article body
+ * (navigation, footers, and sidebars are dropped); when it finds nothing the whole `<body>` is
+ * converted. Relative links become absolute against the page URL, and a link whose scheme is not
+ * http(s) loses its attribute rather than becoming a `javascript:` Markdown link.
+ *
+ * Scripts never run: linkedom does not execute them and the converter removes their elements.
+ */
+const CHARSET_IN_TYPE = /charset\s*=\s*["']?([\w.:-]+)/iu;
+const CHARSET_IN_META = /<meta[^>]+charset\s*=\s*["']?([\w.:-]+)/iu;
+/** A charset declaration lives in the head; scanning further would decode binary as text. */
+const META_SCAN_BYTES = 1024;
+
+export interface HtmlConversion {
+  readonly markdown: string;
+  readonly title?: string;
+}
+
+/** The header charset, else `<meta charset>` from the first 1 KiB, else UTF-8. Invalid bytes are replaced. */
+export function decodeBody(bytes: Uint8Array, contentType: string | null): string {
+  const declared = CHARSET_IN_TYPE.exec(contentType ?? "")?.[1] ?? metaCharset(bytes) ?? "utf-8";
+  try {
+    return new TextDecoder(declared, { fatal: false }).decode(bytes);
+  } catch {
+    return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  }
+}
+
+/** Article HTML to Markdown, loaded lazily. `sourceUrl` resolves relative links in the output. */
+export async function convertHtml(html: string, sourceUrl: string): Promise<HtmlConversion> {
+  const [{ parseHTML }, { Readability }, { default: TurndownService }] = await Promise.all([
+    import("linkedom"),
+    import("@mozilla/readability"),
+    import("turndown"),
+  ]);
+  const { document } = parseHTML(html);
+  const article = new Readability(document as unknown as Document, { charThreshold: 0 }).parse();
+  const content = article?.content ?? document.body?.innerHTML;
+  if (content === undefined || content === "") return { markdown: "" };
+  const { document: contentDocument } = parseHTML(content);
+  absolutize(contentDocument, sourceUrl);
+  const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced", bulletListMarker: "-" });
+  turndown.remove(["script", "style", "noscript", "iframe", "object", "embed", "form"]);
+  // A content fragment parses outside `<body>`, so convert the root element rather than the body.
+  const markdown = turndown.turndown((contentDocument.documentElement ?? content) as unknown as HTMLElement).trim();
+  const title = article?.title ?? document.title;
+  return { markdown, ...(title ? { title } : {}) };
+}
+
+function metaCharset(bytes: Uint8Array): string | undefined {
+  const head = new TextDecoder("latin1").decode(bytes.subarray(0, META_SCAN_BYTES));
+  return CHARSET_IN_META.exec(head)?.[1];
+}
+
+interface AttributeElement {
+  getAttribute(name: string): string | null;
+  setAttribute(name: string, value: string): void;
+  removeAttribute(name: string): void;
+}
+
+/** Links and images only: absolute http(s) or a drop. `#fragment` targets are page-local and kept. */
+function absolutize(document: { querySelectorAll(selector: string): ArrayLike<AttributeElement> }, base: string): void {
+  for (const [selector, attribute] of [
+    ["a[href]", "href"],
+    ["img[src]", "src"],
+  ] as const) {
+    const elements = document.querySelectorAll(selector);
+    for (let index = 0; index < elements.length; index++) {
+      const element = elements[index]!;
+      const raw = element.getAttribute(attribute);
+      if (raw === null || raw.startsWith("#")) continue;
+      try {
+        const absolute = new URL(raw, base);
+        if (absolute.protocol !== "http:" && absolute.protocol !== "https:") element.removeAttribute(attribute);
+        else element.setAttribute(attribute, absolute.toString());
+      } catch {
+        element.removeAttribute(attribute);
+      }
+    }
+  }
+}

package/web/src/native/fetch.ts

@@ -0,0 +1,226 @@
+/**
+ * The keyless `native` fetch backend: `pinnedFetch`'s DNS pinning and SSRF gate, with redirects
+ * followed by hand so every hop is checked again.
+ *
+ * `pinnedFetch` itself refuses 3xx responses, so the loop here reuses its pieces instead: validate
+ * the URL, resolve and pin one address, request it, and repeat for `Location`. A hop to a private
+ * address, a loopback, a plaintext `http:` URL, or a non-http(s) scheme fails before any socket is
+ * opened. HTML becomes Markdown through `./convert.ts` (loaded on the first page only); text, JSON,
+ * and XML pass through.
+ */
+import { assertSsrfAllowedUrl, MediaContentError, type MediaHostnameResolver, type SsrfPolicy } from "@arnilo/prism";
+import { defaultResolver, requestPinned, resolvePinnedAddress } from "@arnilo/prism/net";
+import type { DomainPolicy } from "../domains.js";
+import { resolveWebLimits } from "../limits.js";
+import { citation } from "../normalize.js";
+import { truncateUtf8Bytes } from "../slice.js";
+import { WebToolError } from "../transport.js";
+import type { ResolvedWebLimits, WebFetchAdapter, WebLimits } from "../types.js";
+import { convertHtml, decodeBody } from "./convert.js";
+
+export const DEFAULT_MAX_REDIRECTS = 5;
+export const HARD_MAX_REDIRECTS = 10;
+/** One pinned, redirect-free request. Injected in tests; the default is the kernel's primitive. */
+export type NativeFetchRequest = (url: URL, init: RequestInit) => Promise<Response>;
+
+const HTML_TYPES = new Set(["text/html", "application/xhtml+xml"]);
+const TEXT_TYPES = new Set(["text/plain", "text/markdown", "text/csv", "application/json", "application/xml", "text/xml"]);
+const JSON_PRETTY_BYTES = 1024 * 1024;
+
+export interface NativeFetchOptions {
+  /** Sent as `user-agent` on every request. The package passes its own name and version. */
+  readonly userAgent: string;
+  /** Redirects followed before `ERR_PRISM_WEB_REDIRECT`; default 5, hard maximum 10. */
+  readonly maxRedirects?: number;
+  readonly limits?: WebLimits;
+  readonly ssrf?: SsrfPolicy;
+  /** Custom DNS resolver, as `pinnedFetch` takes; defaults to `node:dns/promises`. */
+  readonly resolver?: MediaHostnameResolver;
+  /** Replaces the pinned request in tests; the SSRF gate still runs on the URL. */
+  readonly request?: NativeFetchRequest;
+  /** Host domain policy; the first URL and every redirect hop must be permitted. */
+  readonly domains?: DomainPolicy;
+}
+
+export function createNativeFetch(options: NativeFetchOptions): WebFetchAdapter {
+  if (typeof options.userAgent !== "string" || options.userAgent.length === 0)
+    throw new WebToolError("ERR_PRISM_WEB_INPUT", "native fetch needs a userAgent");
+  const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  if (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0 || maxRedirects > HARD_MAX_REDIRECTS)
+    throw new WebToolError("ERR_PRISM_WEB_INPUT", `maxRedirects must be an integer between 0 and ${HARD_MAX_REDIRECTS}`);
+  const limits = resolveWebLimits(options.limits);
+  const request = options.request ?? pinnedRequest(options, limits);
+  return {
+    provider: "native",
+    async fetch(input, call = {}) {
+      const headers = { "user-agent": options.userAgent, accept: "text/html, text/markdown;q=0.9, text/plain;q=0.8, */*;q=0.1" };
+      const signal = AbortSignal.any([...(call.signal === undefined ? [] : [call.signal]), AbortSignal.timeout(limits.timeoutMs)]);
+      try {
+        const { response, url, redirects } = await follow(input, request, {
+          ssrf: options.ssrf,
+          maxRedirects,
+          signal,
+          headers,
+          ...(options.domains === undefined ? {} : { domains: options.domains }),
+        });
+        const body = await readBody(response, limits.maxResponseBytes, signal);
+        const header = response.headers.get("content-type");
+        const type = header?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+        let markdown: string;
+        let title: string | undefined;
+        if (HTML_TYPES.has(type)) {
+          const converted = await convertHtml(decodeBody(body, header), url.toString());
+          markdown = converted.markdown;
+          title = converted.title;
+        } else if (TEXT_TYPES.has(type)) {
+          markdown = decodeBody(body, header);
+          if (type === "application/json" && body.byteLength <= JSON_PRETTY_BYTES) markdown = prettyJson(markdown);
+        } else {
+          throw new WebToolError("ERR_PRISM_WEB_CONTENT_TYPE", `native fetch does not read ${type || "an unstated content type"}`);
+        }
+        // `maxBytes` never lifts the limit, it only lowers it; an over-long page is cut and flagged.
+        const limit = Math.min(call.maxBytes ?? limits.maxMarkdownBytes, limits.maxMarkdownBytes);
+        const sourceTruncated = Buffer.byteLength(markdown, "utf8") > limit;
+        return {
+          ...citation("native", url.toString()),
+          ...(title === undefined ? {} : { title }),
+          markdown: sourceTruncated ? truncateUtf8Bytes(markdown, limit) : markdown,
+          ...(sourceTruncated ? { sourceTruncated: true } : {}),
+          ...(redirects.length === 0 ? {} : { redirects }),
+          retrievedAt: new Date().toISOString(),
+          untrusted: true,
+        };
+      } catch (error) {
+        if (error instanceof WebToolError) throw error;
+        if (signal.aborted)
+          throw new WebToolError("ERR_PRISM_WEB_ABORTED", call.signal?.aborted === true ? "web fetch aborted" : "web fetch timed out");
+        if (error instanceof MediaContentError) throw translate(error);
+        throw new WebToolError("ERR_PRISM_WEB_REQUEST", `native fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    },
+  };
+}
+
+/** The default request: one DNS resolve, every candidate checked, the socket pinned to one address. */
+function pinnedRequest(options: NativeFetchOptions, limits: ResolvedWebLimits): NativeFetchRequest {
+  const resolver = options.resolver ?? defaultResolver;
+  return async (url, init) => {
+    const address = await resolvePinnedAddress(url, resolver, init.signal, false, options.ssrf, "Web fetch");
+    const response = await requestPinned(url, address, init, "Web fetch");
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limits.maxResponseBytes) {
+      await response.body?.cancel();
+      throw new WebToolError("ERR_PRISM_WEB_LIMIT", `web response exceeds ${limits.maxResponseBytes} bytes`);
+    }
+    return response;
+  };
+}
+
+interface FollowOptions {
+  readonly ssrf: SsrfPolicy | undefined;
+  readonly maxRedirects: number;
+  readonly signal: AbortSignal;
+  readonly headers: Record<string, string>;
+  readonly domains?: DomainPolicy;
+}
+
+/** At most `maxRedirects` hops, each target resolved against the current URL and gated again. */
+async function follow(
+  input: string,
+  request: NativeFetchRequest,
+  options: FollowOptions,
+): Promise<{ response: Response; url: URL; redirects: readonly string[] }> {
+  const start = parseTarget(input);
+  if (start === undefined) throw new WebToolError("ERR_PRISM_WEB_INPUT", "url must be an absolute http(s) URL");
+  let url: URL = start;
+  const seen = new Set<string>([url.toString()]);
+  const redirects: string[] = [];
+  for (;;) {
+    // Host policy first: a redirect is a new target and is gated exactly like the first URL.
+    options.domains?.assert(url.toString());
+    assertPublicTarget(url, options.ssrf);
+    const response = await request(url, { headers: options.headers, signal: options.signal, redirect: "manual" });
+    if (response.status < 300 || response.status >= 400) return { response, url, redirects };
+    await response.body?.cancel();
+    const location = response.headers.get("location");
+    const next: URL | undefined = location === null ? undefined : parseTarget(location, url);
+    if (next === undefined)
+      throw new WebToolError("ERR_PRISM_WEB_REDIRECT", `native fetch got status ${response.status} without a usable Location`);
+    if (redirects.length >= options.maxRedirects)
+      throw new WebToolError("ERR_PRISM_WEB_REDIRECT", `native fetch stopped after ${options.maxRedirects} redirects`);
+    if (seen.has(next.toString())) throw new WebToolError("ERR_PRISM_WEB_REDIRECT", "native fetch redirect loop");
+    seen.add(next.toString());
+    redirects.push(next.toString());
+    url = next;
+  }
+}
+
+/** https only (no loopback option here), no embedded credentials, and a public address. */
+function assertPublicTarget(url: URL, ssrf: SsrfPolicy | undefined): void {
+  if (url.protocol !== "https:") throw new WebToolError("ERR_PRISM_WEB_REQUEST", `native fetch requires https: (got ${url.protocol})`);
+  if (url.username || url.password) throw new WebToolError("ERR_PRISM_WEB_INPUT", "url must not embed credentials");
+  url.hash = "";
+  try {
+    assertSsrfAllowedUrl(url.toString(), ssrf);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new WebToolError("ERR_PRISM_WEB_REQUEST", `native fetch refused ${url.hostname}: ${reason}`);
+  }
+}
+
+function parseTarget(input: string, base?: URL): URL | undefined {
+  let url: URL;
+  try {
+    url = base === undefined ? new URL(input) : new URL(input, base);
+  } catch {
+    return undefined;
+  }
+  return url.protocol === "https:" || url.protocol === "http:" ? url : undefined;
+}
+
+/** Reads at most `maxBytes`; a larger body fails instead of filling memory. */
+async function readBody(response: Response, maxBytes: number, signal: AbortSignal): Promise<Uint8Array> {
+  if (response.body === null) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new WebToolError("ERR_PRISM_WEB_LIMIT", `web response exceeds ${maxBytes} bytes`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      /* Already released after cancel. */
+    }
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function prettyJson(text: string): string {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+
+function translate(error: MediaContentError): WebToolError {
+  if (error.code === "redirect") return new WebToolError("ERR_PRISM_WEB_REDIRECT", "native fetch redirects are followed by the caller");
+  return new WebToolError("ERR_PRISM_WEB_REQUEST", `native fetch failed: ${error.message}`);
+}

package/web/src/normalize.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { type ArtifactCitation, HARD_CITATION_EXCERPT_BYTES } from "@arnilo/prism/artifacts";
+import { WebToolError } from "./transport.js";
+import type { WebCitation, WebProvider, WebProviderMetadata, WebSearchProvider, WebSearchResult } from "./types.js";
+
+export function canonicalUrl(input: string): string {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new WebToolError("ERR_PRISM_WEB_RESPONSE", "Provider returned an invalid URL");
+  }
+  if (!/^https?:$/u.test(url.protocol) || url.username || url.password)
+    throw new WebToolError("ERR_PRISM_WEB_RESPONSE", "Provider returned an unsafe URL");
+  url.hash = "";
+  return url.toString();
+}
+export function citation(provider: WebProvider, inputUrl: string, sourceId?: string): WebCitation {
+  const url = canonicalUrl(inputUrl);
+  return {
+    provider,
+    sourceId,
+    url,
+    citationId: sourceId ? `web:${provider}:${sourceId}` : `web:${provider}:${createHash("sha256").update(url).digest("hex")}`,
+  };
+}
+
+/** Hash an already-fetched body. Never refetches, never stores credentials. */
+export function snapshotWebEvidence(input: {
+  readonly url: string;
+  readonly body: string | Uint8Array;
+  readonly provider: WebProvider;
+  readonly retrievedAt?: string;
+  readonly title?: string;
+  readonly sourceId?: string;
+  readonly tenantId?: string;
+  readonly excerpt?: string;
+  readonly span?: { readonly start: number; readonly end: number };
+  readonly revision?: string;
+}): ArtifactCitation {
+  const base = citation(input.provider, input.url, input.sourceId);
+  const bytes = typeof input.body === "string" ? Buffer.from(input.body, "utf8") : Buffer.from(input.body);
+  if (input.excerpt !== undefined && Buffer.byteLength(input.excerpt, "utf8") > HARD_CITATION_EXCERPT_BYTES) {
+    throw new WebToolError("ERR_PRISM_WEB_LIMIT", `excerpt exceeds ${HARD_CITATION_EXCERPT_BYTES} bytes`);
+  }
+  return {
+    uri: base.url,
+    kind: "web",
+    sourceId: base.sourceId ?? base.citationId,
+    revision: input.revision ?? "1",
+    contentHash: createHash("sha256").update(bytes).digest("hex"),
+    retrievedAt: input.retrievedAt ?? new Date().toISOString(),
+    support: "unverified",
+    ...(input.title === undefined ? {} : { title: input.title }),
+    ...(input.tenantId === undefined ? {} : { tenantId: input.tenantId }),
+    ...(input.excerpt === undefined ? {} : { excerpt: input.excerpt }),
+    ...(input.span === undefined ? {} : { span: input.span }),
+  };
+}
+/** Result rows only: provider/rate facts stay once at the response's top level, never per result. */
+export function normalizeSearchResults(
+  provider: WebSearchProvider,
+  _query: string,
+  raw: unknown,
+  maxResults: number,
+): readonly WebSearchResult[] {
+  const root = object(raw),
+    fields = SEARCH_FIELDS[provider],
+    list = fields.list(root);
+  if (!Array.isArray(list)) throw new WebToolError("ERR_PRISM_WEB_RESPONSE", `${provider} response has no results`);
+  const seen = new Set<string>(),
+    retrievedAt = new Date().toISOString(),
+    out: WebSearchResult[] = [];
+  for (const entry of list) {
+    if (out.length >= maxResults) break;
+    const item = object(entry);
+    if (typeof item.url !== "string") continue;
+    const base = citation(provider, item.url, typeof item.id === "string" ? item.id : undefined);
+    if (seen.has(base.url)) continue;
+    seen.add(base.url);
+    const highlights = Array.isArray(item.highlights)
+      ? item.highlights.filter((value): value is string => typeof value === "string").slice(0, 16)
+      : undefined;
+    out.push({
+      ...base,
+      title: text(item.title),
+      snippet: text(item[fields.snippet]),
+      highlights,
+      publishedAt: text(item[fields.publishedAt]),
+      retrievedAt,
+    });
+  }
+  return out;
+}
+/** Where each backend keeps its rows, snippet, and publish date. One table instead of per-provider ternaries. */
+const SEARCH_FIELDS: Readonly<
+  Record<
+    WebSearchProvider,
+    {
+      readonly list: (root: Record<string, unknown>) => unknown;
+      readonly snippet: string;
+      readonly publishedAt: string;
+    }
+  >
+> = {
+  brave: { list: (root) => object(root.web).results, snippet: "description", publishedAt: "page_age" },
+  exa: { list: (root) => root.results, snippet: "text", publishedAt: "publishedDate" },
+  searxng: { list: (root) => root.results, snippet: "content", publishedAt: "publishedDate" },
+  tavily: { list: (root) => root.results, snippet: "content", publishedAt: "published_date" },
+  kagi: { list: (root) => object(root.data).search, snippet: "snippet", publishedAt: "time" },
+};
+
+export function object(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new WebToolError("ERR_PRISM_WEB_RESPONSE", "Provider returned an invalid object");
+  return value as Record<string, unknown>;
+}
+export function text(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+export function providerFacts(raw: unknown, base?: WebProviderMetadata): WebProviderMetadata | undefined {
+  const root = object(raw);
+  const requestId = text(root.requestId) ?? base?.requestId;
+  const cost = root.costDollars ?? root.creditsUsed;
+  return requestId || cost !== undefined || base?.rate ? { requestId, cost: toJson(cost), rate: base?.rate } : undefined;
+}
+function toJson(value: unknown): import("@arnilo/prism").JsonValue | undefined {
+  return value === null || ["string", "number", "boolean"].includes(typeof value)
+    ? (value as import("@arnilo/prism").JsonValue)
+    : undefined;
+}

package/web/src/obscura/cdp.ts

@@ -0,0 +1,201 @@
+/**
+ * Managed/external CDP connectivity and Playwright composition for Obscura.
+ *
+ * `obscura serve` exposes a CDP endpoint (default ws://127.0.0.1:9222); hosts connect
+ * with their own Playwright via chromium.connectOverCDP — never connect() or launch.
+ * The resulting browser plugs straight into `@arnilo/prism-tools/browser`'s
+ * createBrowserTools/createBrowserManager; raw CDP (screenshots, PDF, screencast)
+ * stays available through Playwright's own CDP session APIs. No command allow-list
+ * is added here and Puppeteer is out of scope.
+ */
+import { isIP } from "node:net";
+import { ObscuraError } from "./errors.js";
+import type { PlaywrightBrowser } from "./playwright.js";
+import { spawnObscuraProcess } from "./process.js";
+import type { ObscuraProcessOptions, OwnedObscuraProcess } from "./types.js";
+
+/** Structural chromium surface this package needs — only `connectOverCDP`, never `connect` or `launch`. */
+export interface ObscuraChromium {
+  connectOverCDP(endpoint: string, options?: { timeout?: number }): Promise<PlaywrightBrowser>;
+}
+
+export interface ObscuraPlaywright {
+  readonly chromium: ObscuraChromium;
+}
+
+export interface ConnectObscuraCdpOptions
+  extends Omit<Pick<ObscuraProcessOptions, "command" | "args" | "env" | "cwd" | "stderr" | "allowInsecureFlags" | "limits">, "command"> {
+  /** Managed mode: absolute command to spawn (e.g. the obscura binary, or /usr/bin/docker). */
+  readonly command?: string;
+  /**
+   * External mode: attach to an already-running CDP endpoint (ws://, wss://, http://,
+   * https://). Loopback-only unless `allowRemoteEndpoint` is set. Remote endpoints have
+   * no authentication — front them with an authenticated tunnel/proxy.
+   */
+  readonly endpoint?: string;
+  /** Explicit opt-in for non-loopback CDP endpoints. Off by default; rejected otherwise. */
+  readonly allowRemoteEndpoint?: boolean;
+  /**
+   * Host-supplied Playwright. When omitted, the optional `playwright-core` peer is
+   * imported (see docs/peer-dependencies.md for the pinned version). Prism never
+   * launches browsers.
+   */
+  readonly playwright?: ObscuraPlaywright;
+  readonly signal?: AbortSignal;
+}
+
+export interface ObscuraCdpSession {
+  /** Pass to `createBrowserTools({ browser })` / `createBrowserManager({ browser })`. */
+  readonly browser: PlaywrightBrowser;
+  readonly endpoint: string;
+  /** Defined only when this session spawned the server; close() terminates it. */
+  readonly process: OwnedObscuraProcess | undefined;
+  /** Close the Playwright browser first, then any owned process. Idempotent. */
+  close(): Promise<void>;
+}
+
+function isLoopbackHost(host: string): boolean {
+  const normalized = host.toLowerCase();
+  if (normalized === "localhost") return true;
+  if (isIP(normalized) === 4) return normalized.startsWith("127.");
+  return normalized === "::1";
+}
+
+/** Loopback-only, credential-free, ws(s)/http(s)-only endpoint validation. */
+export function validateObscuraEndpoint(raw: string, allowRemote: boolean): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ObscuraError("ERR_OBSCURA_INPUT", "endpoint must be an absolute URL");
+  }
+  if (!["ws:", "wss:", "http:", "https:"].includes(url.protocol)) {
+    throw new ObscuraError("ERR_OBSCURA_INPUT", "endpoint scheme must be ws(s) or http(s)");
+  }
+  if (url.username || url.password) {
+    throw new ObscuraError("ERR_OBSCURA_INPUT", "endpoint must not carry credentials; use an authenticated tunnel/proxy");
+  }
+  if (!isLoopbackHost(url.hostname)) {
+    if (!allowRemote) {
+      throw new ObscuraError(
+        "ERR_OBSCURA_INSECURE_FLAG",
+        `non-loopback endpoint ${JSON.stringify(url.hostname)} requires allowRemoteEndpoint`,
+      );
+    }
+    if (url.protocol === "ws:" || url.protocol === "http:") {
+      throw new ObscuraError("ERR_OBSCURA_INSECURE_FLAG", "remote CDP has no authentication; require an authenticated wss/https tunnel");
+    }
+  }
+  return url;
+}
+
+/** Derive ws://host:port from managed `serve` args (--port, optional --host). */
+export function endpointFromServeArgs(args: readonly string[]): string {
+  let port: number | undefined;
+  let host = "127.0.0.1";
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    const value = arg === "--port" ? args[i + 1] : arg.startsWith("--port=") ? arg.slice("--port=".length) : undefined;
+    if (value !== undefined) {
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new ObscuraError("ERR_OBSCURA_INPUT", `invalid --port ${JSON.stringify(value)}`);
+      }
+      port = parsed;
+    }
+    const hostValue = arg === "--host" ? args[i + 1] : arg.startsWith("--host=") ? arg.slice("--host=".length) : undefined;
+    if (hostValue !== undefined) host = hostValue;
+  }
+  if (port === undefined) {
+    throw new ObscuraError("ERR_OBSCURA_INPUT", "managed mode needs --port in args or an explicit endpoint");
+  }
+  return `ws://${host}:${port}`;
+}
+
+async function loadPlaywright(): Promise<ObscuraPlaywright> {
+  try {
+    const mod = (await import("playwright-core")) as unknown as { default?: unknown } & Partial<ObscuraPlaywright>;
+    const playwright = (mod.default ?? mod) as ObscuraPlaywright;
+    if (typeof playwright.chromium?.connectOverCDP !== "function") {
+      throw new ObscuraError("ERR_OBSCURA_INPUT", "installed playwright-core does not expose chromium.connectOverCDP");
+    }
+    return playwright;
+  } catch (error) {
+    if (error instanceof ObscuraError) throw error;
+    throw new ObscuraError(
+      "ERR_OBSCURA_INPUT",
+      "optional peer playwright-core is not installed; install it or supply connectObscuraCdp({ playwright })",
+    );
+  }
+}
+
+/** HTTP readiness probe against the CDP endpoint's /json/version. */
+function makeProbe(endpoint: URL): () => Promise<boolean> {
+  const httpUrl = new URL(endpoint.toString());
+  httpUrl.protocol = endpoint.protocol === "wss:" ? "https:" : "http:";
+  httpUrl.pathname = "/json/version";
+  return async () => {
+    try {
+      const response = await fetch(httpUrl, { signal: AbortSignal.timeout(1000) });
+      await response.arrayBuffer();
+      return response.ok;
+    } catch {
+      return false;
+    }
+  };
+}
+
+/**
+ * Attach to an external CDP endpoint, or spawn `obscura serve` and attach once it
+ * is ready (bounded, abortable readiness — no fixed post-start sleep). Exactly one
+ * connectOverCDP call is made and its browser is returned for @arnilo/prism-tools/browser.
+ */
+export async function connectObscuraCdp(options: ConnectObscuraCdpOptions): Promise<ObscuraCdpSession> {
+  let endpointRaw: string | undefined = options.endpoint;
+  let process: OwnedObscuraProcess | undefined;
+
+  if (options.command !== undefined) {
+    if (endpointRaw === undefined) endpointRaw = endpointFromServeArgs(options.args ?? []);
+    process = spawnObscuraProcess({
+      command: options.command,
+      ...(options.args === undefined ? {} : { args: options.args }),
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+      ...(options.stderr === undefined ? {} : { stderr: options.stderr }),
+      ...(options.allowInsecureFlags === undefined ? {} : { allowInsecureFlags: options.allowInsecureFlags }),
+      ...(options.limits === undefined ? {} : { limits: options.limits }),
+    });
+  } else if (endpointRaw === undefined) {
+    throw new ObscuraError("ERR_OBSCURA_INPUT", "connectObscuraCdp requires endpoint or command");
+  }
+
+  const endpoint = validateObscuraEndpoint(endpointRaw, options.allowRemoteEndpoint ?? false);
+
+  try {
+    if (process !== undefined) {
+      await process.waitReady(makeProbe(endpoint), { signal: options.signal });
+    } else if (options.signal?.aborted) {
+      throw new ObscuraError("ERR_OBSCURA_ABORTED", "connect aborted");
+    }
+    const endpointString = endpoint.toString().replace(/\/$/, "");
+    const playwright = options.playwright ?? (await loadPlaywright());
+    const browser = await playwright.chromium.connectOverCDP(endpointString);
+    return {
+      browser,
+      endpoint: endpointString,
+      process,
+      close: async () => {
+        try {
+          await browser.close?.();
+        } catch {
+          // already disconnected
+        }
+        await process?.close();
+      },
+    };
+  } catch (error) {
+    // Only resources this call created are terminated; external servers stay alive.
+    await process?.close();
+    throw error;
+  }
+}

package/web/src/obscura/classify.ts

@@ -0,0 +1,35 @@
+/**
+ * Obscura tool classification. Reads are proven side-effect-free against the live
+ * session; every other tool (including unknown future upstream tools) falls back to
+ * the bridge's conservative external-mutation default. `browser_search` is in-page
+ * text search — it reads the current page and mutates nothing.
+ */
+const READ_TOOLS: ReadonlySet<string> = new Set([
+  // Read the page
+  "browser_snapshot",
+  "browser_markdown",
+  "browser_links",
+  "browser_extract",
+  "browser_interactive_elements",
+  "browser_detect_forms",
+  "browser_get_attribute",
+  "browser_count",
+  "browser_search",
+  // Diagnostics
+  "browser_console_messages",
+  "browser_network_requests",
+  // Tabs/cookies/storage reads
+  "browser_tab_list",
+  "browser_get_cookies",
+  "browser_storage_state",
+  // Waiters (observe only)
+  "browser_wait_for",
+  "browser_wait_for_text",
+  // Render captures (render-enabled builds)
+  "browser_screenshot",
+  "browser_pdf",
+]);
+
+export function isObscuraReadTool(name: string): boolean {
+  return READ_TOOLS.has(name);
+}