@podway/relay 0.2.3

package/FAQ.md

@@ -0,0 +1,87 @@
+# Running Podbay Relay on a headless host
+
+The relay can run on any NAS, Raspberry Pi, or other always-on machine that
+supports Node. This guide covers the common headless setup issues: finding
+`npx`, starting the relay at boot, and opening the dashboard remotely.
+
+## `npx: command not found`, even though I just installed Node
+
+Some NAS packages install `node` and `npm` without putting `npx` on your `PATH`.
+Synology's DSM Node.js package is one example. Check the directory containing
+`node`:
+
+```bash
+NODE_BIN="$(dirname "$(which node)")"
+ls "$NODE_BIN" | grep npx
+```
+
+If `npx` appears, add that directory to `PATH` in `~/.bashrc`, `~/.profile`, or
+the equivalent file for your shell.
+
+If it is genuinely absent, search for another copy:
+
+```bash
+find / -iname npx 2>/dev/null
+```
+
+If you find another copy, add its directory to `PATH`. You can also install it
+separately with `npm install -g npx`.
+
+Boot schedulers and one-command SSH sessions often use a shorter `PATH` than a
+normal login shell. If `npx` works after you log in but fails in a script, set
+`PATH` explicitly at the top of that script.
+
+## How do I make the relay survive a reboot?
+
+The relay itself does not need root. Use whichever startup mechanism your host
+provides:
+
+- **Synology DSM**: Go to Control Panel → Task Scheduler → Create →
+  Triggered Task → User-defined script, then choose **Boot-up**. Run:
+
+  ```bash
+  export PATH=/path/to/node/bin:$PATH   # wherever npx actually lives, see above
+  npx @podway/relay@latest start --gateway <url> --accept
+  ```
+
+- **A systemd host**: If you have root, create a service that runs the same
+  command at boot.
+- **A host with a user crontab**: Run `crontab -e` and add the same command as
+  an `@reboot` entry. Not every NAS includes a user crontab.
+
+The scheduler only needs to run the command once. `start` moves the relay into
+the background and exits.
+
+## Do I need to pass `--code` again every time it starts?
+
+No. `--code` is only used for the first pairing. The relay saves a reconnect
+token locally, so later `start` commands reconnect automatically:
+
+```bash
+npx @podway/relay@latest start --gateway <url> --accept
+```
+
+Do not save the original pairing code in your boot script; it expires and is
+not needed after pairing. To pair again, run
+`npx @podway/relay@latest reset`. This also clears the relay's other saved data.
+
+## How do I open the dashboard remotely?
+
+The dashboard listens only on `127.0.0.1`, so it is not exposed to your network.
+Create an SSH tunnel from your computer:
+
+```bash
+ssh -L 7373:127.0.0.1:7373 user@your-nas
+```
+
+Keep the tunnel open, run `npx @podway/relay@latest status` on the relay host,
+and open the printed `http://127.0.0.1:7373/...` URL on your computer.
+
+If the tunnel immediately resets, check whether the SSH server disables
+forwarding. Synology commonly sets `AllowTcpForwarding no`. Enabling it affects
+every authorized SSH user, not only Podbay, and requires administrator access:
+
+```bash
+sudo sed -i 's/^AllowTcpForwarding no/AllowTcpForwarding yes/' /etc/ssh/sshd_config
+sudo systemctl restart sshd   # or: synosystemctl restart sshd, on some DSM versions
+```

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Podbay
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,84 @@
+# Podbay Relay
+
+The Podbay relay lets your pods reach websites through your network instead of
+a datacenter. This helps with sites that block cloud IPs. For sites you choose,
+the relay can also use a separate browser session that you sign into.
+
+One relay handles two kinds of traffic:
+
+| mode | what the pod gets | used by |
+|---|---|---|
+| **fetch** | a page loaded by this machine, optionally with a session you provided | the agent's `podbay fetch get` command |
+| **tunnel** | a proxy connection through your IP, without your cookies | crawlers, scripts, Playwright, and other tools that load pages themselves |
+
+The tunnel lets a pod run a real browser while the connection comes from your
+network. Pods receive it through `$PODBAY_RELAY_PROXY`. It **fails closed**: if
+the relay is not running, those connections are refused instead of quietly
+leaving from the datacenter.
+
+```bash
+# Your pod prints the exact command, pinned to a version and pairing code:
+npx @podway/relay@<version> start --code <code> --accept
+```
+
+Once started, the relay runs in the background and handles both modes.
+
+## What it does — and what it does not do
+
+- **Public pages are clean by default.** They load in a fresh browser without
+  your cookies or accounts.
+- **Signed-in access is explicit.** `relay login <domain>` opens a browser so
+  you can sign in. Only that domain may use the saved session. The relay returns
+  page content, never cookies, credentials, or session tokens.
+- **The tunnel shares your IP, not your accounts.** Tools using the proxy get a
+  clean connection without your signed-in sessions.
+- **Your private network stays blocked.** Pods cannot reach localhost, your LAN,
+  private IPs, routers, or other internal services through the relay.
+- **You stay in control.** `relay dashboard` shows activity and lets you pause a
+  pod, block a site, revoke signed-in access, manage history, or stop the relay.
+- **Requests are rate-limited per site**, so one pod cannot hammer a source
+  through your connection.
+
+## Commands
+
+| command | description |
+|---|---|
+| `relay start --code <code> --gateway <url> --accept` | start the relay in the background |
+| `relay login <domain>` | allow signed-in fetches for one domain |
+| `relay dashboard` | open the local command center |
+| `relay status` | show the relay, gateway, and signed-in site status |
+| `relay stop` | stop it |
+| `relay reset` | remove saved sessions, logins, and pairing |
+
+## Trust
+
+The relay stores browser sessions for sites you sign into, so treat it as
+sensitive software. It is open source under Apache-2.0 and uses its own browser
+profile; it never touches your everyday browser, history, or cookies. Automating
+a signed-in session may violate a site's terms, and the account risk is yours.
+
+## Local command center and history
+
+`relay dashboard` shows the connection state, recent activity, and access
+controls. While the relay runs, the dashboard is live. When stopped, it shows
+saved history in read-only mode. The CLI always prints its local URL, so it also
+works on headless machines without `xdg-open`.
+
+Activity is stored in owner-only, daily files under `~/.podway/relay/events`.
+Events include the pod ID when available, mode, sanitized target, timing,
+outcome, HTTP status, signed-in use, and tunnel byte counts. History is kept for
+30 days by default; the dashboard offers 7, 30, or 90 days and enforces a
+storage limit.
+
+Before an event is written, URLs are stripped of usernames, passwords, query
+strings, and fragments. Logs never include cookies, authorization headers,
+browser storage, request or response bodies, or tunnel content. Detailed
+history and exports stay on your machine; Podbay receives only coarse,
+domain-level telemetry. Clearing history does not clear pairing, sessions,
+paused pods, or blocked sites.
+
+## Running headless
+
+Running the relay on a NAS, Raspberry Pi, or another always-on machine? See
+[FAQ.md](FAQ.md) for help with missing `npx`, starting at boot, and opening the
+dashboard remotely.

package/dist/audit.d.ts

@@ -0,0 +1,109 @@
+export type RelayMode = "fetch" | "tunnel";
+export type RelayOutcome = "ok" | "site-refused" | "owner-blocked" | "safety-blocked" | "rate-limited" | "network-error";
+export type RelaySource = {
+    podId: string;
+    podName?: string;
+} | {
+    system: "health-check";
+};
+/** The only detailed event shape allowed across the local persistence boundary. */
+export interface RelayEventV2 {
+    v: 2;
+    id: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    source?: RelaySource;
+    mode: RelayMode;
+    outcome: RelayOutcome;
+    target: string;
+    finalTarget?: string;
+    host: string;
+    httpStatus?: number;
+    session: boolean;
+    reason?: string;
+    bytesUp?: number;
+    bytesDown?: number;
+}
+/** Rows written by pb <= 0.1.6. */
+export interface AuditEntry {
+    host: string;
+    status: number;
+    ms: number;
+    session: boolean;
+    error?: string;
+    kind?: RelayMode;
+    bytes?: number;
+    at?: string;
+}
+export interface SafeFetchTarget {
+    target: string;
+    host: string;
+}
+/** Strip the credential-bearing and high-entropy portions before an event exists. */
+export declare function safeFetchTarget(value: string): SafeFetchTarget | null;
+export declare function safeTunnelTarget(hostValue: string, port: number): {
+    target: string;
+    host: string;
+} | null;
+export declare function fetchOutcome(status: number, error?: string): RelayOutcome;
+/** Rebuild a record from allowed fields, sanitizing targets again at the write boundary. */
+export declare function sanitizeEvent(input: RelayEventV2): RelayEventV2 | null;
+export interface EventQuery {
+    since?: string;
+    podId?: string;
+    mode?: RelayMode;
+    outcome?: RelayOutcome;
+    site?: string;
+    offset?: number;
+    limit?: number;
+}
+/** Bounded, day-partitioned, owner-local JSONL with an in-memory retained index. */
+export declare class RelayEventStore {
+    private readonly options;
+    private index;
+    private lastPrunedDay;
+    private selectedRetentionDays;
+    readonly root: string;
+    constructor(options?: {
+        root?: string;
+        legacyFile?: string;
+        retentionDays?: 7 | 30 | 90;
+        maxBytes?: number;
+        now?: () => number;
+    });
+    private now;
+    private retentionDays;
+    setRetentionDays(days: 7 | 30 | 90): void;
+    init(): this;
+    private eventFiles;
+    private parseLines;
+    reload(): void;
+    append(input: RelayEventV2): boolean;
+    query(query?: EventQuery): RelayEventV2[];
+    exportJson(): string;
+    clear(): void;
+    storageBytes(): number;
+    prune(force?: boolean): void;
+}
+/** Compatibility writer for callers not yet migrated to v2. */
+export declare function record(entry: AuditEntry): void;
+export interface AuditSummary {
+    total: number;
+    ok: number;
+    failed: number;
+    sessionFetches: number;
+    tunnelConnections: number;
+    tunnelBytes: number;
+    byHost: {
+        host: string;
+        count: number;
+        failed: number;
+        session: boolean;
+        tunnel: number;
+        bytes: number;
+    }[];
+}
+/** Legacy summary kept for compatibility with older integrations and tests. */
+export declare function summarize(text: string): AuditSummary;
+export declare function readSummary(): AuditSummary;

package/dist/audit.js

@@ -0,0 +1,339 @@
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, } from "node:fs";
+import path from "node:path";
+import { auditFile, eventsDir } from "./config.js";
+/** Strip the credential-bearing and high-entropy portions before an event exists. */
+export function safeFetchTarget(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        const host = url.hostname.toLowerCase().replace(/\.$/, "");
+        if (!host)
+            return null;
+        return { target: url.toString(), host };
+    }
+    catch {
+        return null;
+    }
+}
+export function safeTunnelTarget(hostValue, port) {
+    const host = hostValue.trim().toLowerCase().replace(/\.$/, "");
+    if (!host || /[\s/@?#]/.test(host) || !Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return { host, target: host.includes(":") ? `[${host}]:${port}` : `${host}:${port}` };
+}
+export function fetchOutcome(status, error) {
+    if (error)
+        return "network-error";
+    if (status === 403)
+        return "site-refused";
+    if (status === 429)
+        return "rate-limited";
+    if (status >= 200 && status < 400)
+        return "ok";
+    return "network-error";
+}
+function sourceOf(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const source = value;
+    if (typeof source.podId === "string" && source.podId.trim()) {
+        const out = { podId: source.podId.slice(0, 160) };
+        // Gateway-authoritative display name, bounded like the id. Optional — absent means
+        // the dashboard shows the id. (Old rows / old gateways simply omit it.)
+        if (typeof source.podName === "string" && source.podName.trim())
+            out.podName = source.podName.slice(0, 160);
+        return out;
+    }
+    if (source.system === "health-check")
+        return { system: "health-check" };
+    return undefined;
+}
+function boundedText(value, max = 500) {
+    return typeof value === "string" && value ? value.slice(0, max) : undefined;
+}
+/** Rebuild a record from allowed fields, sanitizing targets again at the write boundary. */
+export function sanitizeEvent(input) {
+    const safe = input.mode === "fetch"
+        ? safeFetchTarget(input.target)
+        : (() => {
+            const match = input.target.match(/^\[?([^\]]+?)\]?:([0-9]+)$/);
+            return match ? safeTunnelTarget(match[1], Number(match[2])) : null;
+        })();
+    if (!safe)
+        return null;
+    const final = input.mode === "fetch" && input.finalTarget ? safeFetchTarget(input.finalTarget)?.target : undefined;
+    return {
+        v: 2,
+        id: boundedText(input.id, 200) ?? crypto.randomUUID(),
+        startedAt: new Date(input.startedAt).toISOString(),
+        finishedAt: new Date(input.finishedAt).toISOString(),
+        durationMs: Math.max(0, Math.round(Number(input.durationMs) || 0)),
+        source: sourceOf(input.source),
+        mode: input.mode,
+        outcome: input.outcome,
+        target: safe.target,
+        ...(final ? { finalTarget: final } : {}),
+        host: safe.host,
+        ...(Number.isInteger(input.httpStatus) ? { httpStatus: input.httpStatus } : {}),
+        session: input.mode === "fetch" && input.session === true,
+        ...(boundedText(input.reason) ? { reason: boundedText(input.reason) } : {}),
+        ...(input.mode === "tunnel" ? {
+            bytesUp: Math.max(0, Math.round(Number(input.bytesUp) || 0)),
+            bytesDown: Math.max(0, Math.round(Number(input.bytesDown) || 0)),
+        } : {}),
+    };
+}
+function legacyToV2(row, index, fallbackAt) {
+    const mode = row.kind === "tunnel" ? "tunnel" : "fetch";
+    const at = typeof row.at === "string" && Number.isFinite(Date.parse(row.at)) ? row.at : fallbackAt;
+    const target = mode === "tunnel"
+        ? safeTunnelTarget(String(row.host ?? "unknown.invalid"), 443)?.target
+        : safeFetchTarget(`https://${String(row.host ?? "unknown.invalid")}/`)?.target;
+    if (!target)
+        return null;
+    return sanitizeEvent({
+        v: 2,
+        id: `legacy-${index}-${Date.parse(at) || 0}`,
+        startedAt: at,
+        finishedAt: new Date((Date.parse(at) || Date.now()) + Math.max(0, Number(row.ms) || 0)).toISOString(),
+        durationMs: Math.max(0, Number(row.ms) || 0),
+        mode,
+        outcome: fetchOutcome(Number(row.status) || 0, row.error),
+        target,
+        host: String(row.host ?? "unknown.invalid"),
+        ...(mode === "fetch" ? { httpStatus: Number(row.status) || 0 } : {}),
+        session: row.session === true,
+        ...(row.error ? { reason: row.error } : {}),
+        ...(mode === "tunnel" ? { bytesUp: 0, bytesDown: Math.max(0, Number(row.bytes) || 0) } : {}),
+    });
+}
+/** Bounded, day-partitioned, owner-local JSONL with an in-memory retained index. */
+export class RelayEventStore {
+    options;
+    index = [];
+    lastPrunedDay = "";
+    selectedRetentionDays;
+    root;
+    constructor(options = {}) {
+        this.options = options;
+        this.root = options.root ?? eventsDir();
+        this.selectedRetentionDays = options.retentionDays ?? 30;
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    retentionDays() { return this.selectedRetentionDays; }
+    setRetentionDays(days) { this.selectedRetentionDays = days; }
+    init() {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        chmodSync(this.root, 0o700);
+        this.prune(true);
+        this.reload();
+        return this;
+    }
+    eventFiles() {
+        if (!existsSync(this.root))
+            return [];
+        return readdirSync(this.root)
+            .filter((name) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(name))
+            .sort()
+            .map((name) => path.join(this.root, name));
+    }
+    parseLines(text) {
+        const out = [];
+        for (const line of text.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.v === 2) {
+                    const safe = sanitizeEvent(parsed);
+                    if (safe)
+                        out.push(safe);
+                }
+            }
+            catch { /* one corrupt row does not hide its siblings */ }
+        }
+        return out;
+    }
+    reload() {
+        const rows = [];
+        for (const file of this.eventFiles()) {
+            try {
+                rows.push(...this.parseLines(readFileSync(file, "utf8")));
+            }
+            catch { /* unreadable partition */ }
+        }
+        const legacy = this.options.legacyFile ?? auditFile();
+        try {
+            const fallback = new Date(statSync(legacy).mtimeMs).toISOString();
+            readFileSync(legacy, "utf8").split("\n").forEach((line, index) => {
+                if (!line)
+                    return;
+                try {
+                    const event = legacyToV2(JSON.parse(line), index, fallback);
+                    if (event)
+                        rows.push(event);
+                }
+                catch { /* malformed legacy row */ }
+            });
+        }
+        catch { /* no legacy log */ }
+        const cutoff = this.now() - this.retentionDays() * 86_400_000;
+        this.index = rows
+            .filter((event) => Date.parse(event.finishedAt) >= cutoff)
+            .sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+    }
+    append(input) {
+        try {
+            const event = sanitizeEvent(input);
+            if (!event)
+                return false;
+            mkdirSync(this.root, { recursive: true, mode: 0o700 });
+            const day = event.startedAt.slice(0, 10);
+            const file = path.join(this.root, `${day}.jsonl`);
+            appendFileSync(file, JSON.stringify(event) + "\n", { mode: 0o600 });
+            chmodSync(file, 0o600);
+            this.index.unshift(event);
+            this.prune();
+            return true;
+        }
+        catch {
+            return false; // audit must never fail relay transport
+        }
+    }
+    query(query = {}) {
+        const since = query.since ? Date.parse(query.since) : Number.NEGATIVE_INFINITY;
+        const site = query.site?.toLowerCase();
+        const rows = this.index.filter((event) => Date.parse(event.startedAt) >= since &&
+            (!query.podId || (!!event.source && "podId" in event.source && event.source.podId === query.podId)) &&
+            (!query.mode || event.mode === query.mode) &&
+            (!query.outcome || event.outcome === query.outcome) &&
+            (!site || event.host.includes(site)));
+        const offset = Math.max(0, query.offset ?? 0);
+        return rows.slice(offset, offset + Math.min(10_000, Math.max(1, query.limit ?? 500)));
+    }
+    exportJson() { return JSON.stringify(this.index, null, 2); }
+    clear() {
+        for (const file of this.eventFiles())
+            rmSync(file, { force: true });
+        rmSync(this.options.legacyFile ?? auditFile(), { force: true });
+        this.index = [];
+    }
+    storageBytes() {
+        let total = 0;
+        for (const file of this.eventFiles()) {
+            try {
+                total += statSync(file).size;
+            }
+            catch { }
+        }
+        try {
+            total += statSync(this.options.legacyFile ?? auditFile()).size;
+        }
+        catch { }
+        return total;
+    }
+    prune(force = false) {
+        const today = new Date(this.now()).toISOString().slice(0, 10);
+        if (!force && this.lastPrunedDay === today)
+            return;
+        this.lastPrunedDay = today;
+        const cutoffDay = new Date(this.now() - this.retentionDays() * 86_400_000).toISOString().slice(0, 10);
+        for (const file of this.eventFiles()) {
+            if (path.basename(file, ".jsonl") < cutoffDay)
+                rmSync(file, { force: true });
+        }
+        const legacy = this.options.legacyFile ?? auditFile();
+        try {
+            if (statSync(legacy).mtimeMs < this.now() - this.retentionDays() * 86_400_000)
+                rmSync(legacy, { force: true });
+        }
+        catch { }
+        const ceiling = this.options.maxBytes ?? 50 * 1024 * 1024;
+        const files = this.eventFiles();
+        let total = files.reduce((sum, file) => { try {
+            return sum + statSync(file).size;
+        }
+        catch {
+            return sum;
+        } }, 0);
+        try {
+            total += statSync(legacy).size;
+        }
+        catch { }
+        const candidates = [legacy, ...files];
+        for (const file of candidates) {
+            if (total <= ceiling)
+                break;
+            try {
+                const size = statSync(file).size;
+                rmSync(file, { force: true });
+                total -= size;
+            }
+            catch { }
+        }
+    }
+}
+/** Compatibility writer for callers not yet migrated to v2. */
+export function record(entry) {
+    try {
+        const at = new Date().toISOString();
+        const converted = legacyToV2({ ...entry, at }, 0, at);
+        if (converted)
+            new RelayEventStore().init().append(converted);
+    }
+    catch { /* best effort */ }
+}
+function isOk(row) {
+    return !row.error && row.status >= 200 && row.status < 400;
+}
+/** Legacy summary kept for compatibility with older integrations and tests. */
+export function summarize(text) {
+    const rows = text.split("\n").filter(Boolean).flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const byHost = new Map();
+    let ok = 0, failed = 0, sessionFetches = 0, tunnelConnections = 0, tunnelBytes = 0;
+    for (const row of rows) {
+        const host = byHost.get(row.host) ?? { count: 0, failed: 0, session: false, tunnel: 0, bytes: 0 };
+        const good = isOk(row);
+        if (row.kind === "tunnel") {
+            host.tunnel++;
+            host.bytes += row.bytes ?? 0;
+            tunnelConnections++;
+            tunnelBytes += row.bytes ?? 0;
+        }
+        else
+            host.count++;
+        if (!good)
+            host.failed++;
+        if (row.session) {
+            host.session = true;
+            sessionFetches++;
+        }
+        byHost.set(row.host, host);
+        if (good)
+            ok++;
+        else
+            failed++;
+    }
+    return { total: rows.length, ok, failed, sessionFetches, tunnelConnections, tunnelBytes,
+        byHost: [...byHost.entries()].map(([host, value]) => ({ host, ...value })).sort((a, b) => b.count + b.tunnel - a.count - a.tunnel) };
+}
+export function readSummary() {
+    try {
+        return summarize(readFileSync(auditFile(), "utf8"));
+    }
+    catch {
+        return summarize("");
+    }
+}

package/dist/browser-fetcher.d.ts

@@ -0,0 +1,58 @@
+import type { Fetcher } from "./relay-client.js";
+/**
+ * Fetch a page on the OWNER's machine, choosing the session per the login policy.
+ *
+ *  - A host the owner explicitly signed into (`isSessionDomain`) is fetched in the
+ *    PERSISTENT profile — as them, with their cookies. That is the deliberate,
+ *    opt-in "fetch as me".
+ *  - Every other host is fetched in a fresh EPHEMERAL context with no cookies — the
+ *    residential IP, but not the owner's accounts. So a prompt-injected pod fetching
+ *    gmail.com gets a logged-out page, not the owner's inbox.
+ *
+ * Both contexts: one page per request, always closed; warm and recycled after N pages;
+ * scrape and return bytes, never an eval channel or a live handle.
+ */
+export interface BrowserOptions {
+    profileDir: string;
+    channel?: string;
+    navTimeoutMs?: number;
+    /** Hard ceiling on a WHOLE fetch (launch + nav + read). A browser that stalls past
+     * this is aborted and torn down so it can't hang the relay — see `fetch`. */
+    fetchDeadlineMs?: number;
+    recycleAfter?: number;
+    headless?: boolean;
+    /** Does this host use the owner's signed-in session? Read from config per fetch. */
+    isSessionDomain: (host: string) => boolean;
+}
+export declare class BrowserFetcher {
+    private readonly opts;
+    private browser;
+    private session;
+    private served;
+    constructor(opts: BrowserOptions);
+    private pw;
+    /**
+     * Launch, preferring the owner's installed Chrome (no download) and falling back to
+     * Playwright's bundled Chromium. A missing browser entirely is a clear, actionable
+     * error, not a stack trace.
+     */
+    private launch;
+    private sessionCtx;
+    private cleanCtx;
+    /**
+     * WATCHDOG: a fetch that stalls (a site refusing a headless browser, a hung context,
+     * a wedged persistent profile) must NEVER hang the relay — that was the whole
+     * "relay running but nothing comes back" failure (live-caught on reddit, 2026-08-03).
+     * The nav timeout only bounds `goto`; launch, `content()`, and context creation could
+     * hang unbounded. So the whole fetch races a hard deadline, and on a blown deadline we
+     * TEAR DOWN the browser so the NEXT fetch relaunches clean rather than inheriting a
+     * wedged one.
+     */
+    readonly fetch: Fetcher;
+    private doFetch;
+    /** Drop the wedged context so the next fetch launches a fresh one. */
+    private resetBrowser;
+    /** Remove only one site's relay-profile cookies; clean contexts and siblings stay intact. */
+    revokeDomain(domain: string): Promise<void>;
+    close(): Promise<void>;
+}