@podway/relay 0.2.3

package/dist/browser-fetcher.js

@@ -0,0 +1,132 @@
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+    }
+    catch {
+        return "";
+    }
+}
+export class BrowserFetcher {
+    opts;
+    browser = null;
+    session = null; // persistent profile (login domains)
+    served = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async pw() {
+        return (await import("playwright").catch(() => {
+            throw new Error("Playwright missing. The relay bundles it; reinstall: npx @podbay/relay@latest");
+        }));
+    }
+    /**
+     * 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.
+     */
+    async launch(fn) {
+        const base = { headless: this.opts.headless ?? true, viewport: { width: 1440, height: 900 } };
+        try {
+            return await fn({ ...base, channel: this.opts.channel ?? "chrome" });
+        }
+        catch {
+            try {
+                return await fn(base); // bundled chromium
+            }
+            catch (e) {
+                throw new Error(`no browser found. Install one for the relay: npx playwright install chromium  (${String(e).slice(0, 80)})`);
+            }
+        }
+    }
+    async sessionCtx() {
+        if (this.session)
+            return this.session;
+        const pw = await this.pw();
+        this.session = (await this.launch((o) => pw.chromium.launchPersistentContext(this.opts.profileDir, o)));
+        return this.session;
+    }
+    async cleanCtx() {
+        if (!this.browser) {
+            const pw = await this.pw();
+            this.browser = (await this.launch((o) => pw.chromium.launch(o)));
+        }
+        return this.browser.newContext({ viewport: { width: 1440, height: 900 } });
+    }
+    /**
+     * 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.
+     */
+    fetch = async (job) => {
+        const host = hostOf(job.url);
+        const useSession = this.opts.isSessionDomain(host);
+        const deadlineMs = this.opts.fetchDeadlineMs ?? 25_000;
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`relay fetch timed out after ${deadlineMs}ms`)), deadlineMs);
+        });
+        try {
+            return await Promise.race([this.doFetch(job, useSession), deadline]);
+        }
+        catch (e) {
+            await this.resetBrowser(useSession); // a hung/errored browser must not poison the next fetch
+            throw e;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    async doFetch(job, useSession) {
+        const ctx = useSession ? await this.sessionCtx() : await this.cleanCtx();
+        const page = await ctx.newPage();
+        try {
+            const res = await page.goto(job.url, { waitUntil: "domcontentloaded", timeout: this.opts.navTimeoutMs ?? 20_000 });
+            await page.waitForTimeout(1500);
+            const out = { status: res?.status() ?? 0, body: await page.content(), finalUrl: page.url(), session: useSession };
+            this.served++;
+            return out;
+        }
+        finally {
+            await page.close().catch(() => undefined);
+            // Ephemeral contexts are closed immediately (each is single-use); the persistent
+            // session stays warm. Recycle the shared clean browser after N pages.
+            if (!useSession)
+                await ctx.close().catch(() => undefined);
+            if (this.served >= (this.opts.recycleAfter ?? 200) && this.browser) {
+                const b = this.browser;
+                this.browser = null;
+                this.served = 0;
+                await b.close().catch(() => undefined);
+            }
+        }
+    }
+    /** Drop the wedged context so the next fetch launches a fresh one. */
+    async resetBrowser(useSession) {
+        if (useSession) {
+            const s = this.session;
+            this.session = null;
+            await s?.close?.().catch(() => undefined);
+        }
+        else {
+            const b = this.browser;
+            this.browser = null;
+            this.served = 0;
+            await b?.close?.().catch(() => undefined);
+        }
+    }
+    /** Remove only one site's relay-profile cookies; clean contexts and siblings stay intact. */
+    async revokeDomain(domain) {
+        const escaped = domain.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const ctx = await this.sessionCtx();
+        await ctx.clearCookies({ domain: new RegExp(`(^|\\.)${escaped}$`, "i") });
+    }
+    async close() {
+        await this.session?.close().catch(() => undefined);
+        await this.browser?.close?.().catch(() => undefined);
+    }
+}

package/dist/colors.d.ts

@@ -0,0 +1,14 @@
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    cyan: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+};
+/**
+ * Render aligned "command — description" rows: the command padded to a common width
+ * and coloured, the description dimmed, so a help block reads as a table instead of a
+ * wall of text.
+ */
+export declare function rows(pairs: [cmd: string, desc: string][], color?: (s: string) => string): string;

package/dist/colors.js

@@ -0,0 +1,25 @@
+/**
+ * Minimal ANSI styling for the CLI's human-facing output.
+ *
+ * Off automatically when stdout is not a TTY (piped/redirected) or when NO_COLOR is
+ * set — so `pb ... | cat` and CI logs stay clean, never littered with escape codes.
+ */
+const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const c = {
+    bold: wrap("1"),
+    dim: wrap("2"),
+    green: wrap("32"),
+    cyan: wrap("36"),
+    yellow: wrap("33"),
+    red: wrap("31"),
+};
+/**
+ * Render aligned "command — description" rows: the command padded to a common width
+ * and coloured, the description dimmed, so a help block reads as a table instead of a
+ * wall of text.
+ */
+export function rows(pairs, color = c.cyan) {
+    const w = Math.max(...pairs.map(([cmd]) => cmd.length));
+    return pairs.map(([cmd, desc]) => `  ${color(cmd.padEnd(w))}  ${c.dim(desc)}`).join("\n");
+}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The relay's state on the owner's machine. Disk IS the shared state between the
+ * background daemon and the `login`/`dashboard`/`stop` commands — no IPC needed: login
+ * writes here and the daemon re-reads it per fetch; dashboard reads the audit log; stop
+ * reads the pidfile. Simpler and more robust than a socket.
+ */
+export interface RelayConfig {
+    gatewayUrl?: string;
+    /** Domains the owner explicitly signed into — these, and only these, are fetched
+     * with their session. Everything else is a clean, cookieless fetch. */
+    loginDomains: string[];
+    consentedAt?: string;
+    /** Durable reconnect token, handed to us at pairing. We reconnect with THIS (not the
+     * one-time code) so a gateway restart or network blip does not force re-pairing. */
+    reconnectToken?: string;
+    /** Explicit local denials. Clean public-web access remains open by default. */
+    pausedPodIds?: string[];
+    blockedDomains?: string[];
+    retentionDays?: 7 | 30 | 90;
+    /** Opt-in (`relay start --keep-awake`): prevent the Mac from idle-sleeping while the relay runs,
+     * for a host meant to stay online 24/7. Persisted so it survives restarts. Default off. */
+    keepAwake?: boolean;
+}
+export declare const profileDir: () => string;
+export declare const pidFile: () => string;
+export declare const auditFile: () => string;
+export declare const eventsDir: () => string;
+export declare const dashboardRuntimeFile: () => string;
+export declare function load(): RelayConfig;
+export declare function save(cfg: RelayConfig): void;
+export declare function addLoginDomain(domain: string): void;
+export declare function setPodPaused(podId: string, paused: boolean): RelayConfig;
+export declare function setDomainBlocked(domain: string, blocked: boolean): RelayConfig;
+export declare function setRetentionDays(days: number): RelayConfig;
+export declare function revokeLoginDomain(domain: string): RelayConfig;
+export declare function isPodPaused(cfg: RelayConfig, podId?: string): boolean;
+export declare function isDomainBlocked(cfg: RelayConfig, host: string): boolean;
+export declare function resetProfile(): void;

package/dist/config.js

@@ -0,0 +1,99 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+const dir = () => process.env.PB_RELAY_HOME ?? path.join(homedir(), ".podway", "relay");
+const file = () => path.join(dir(), "config.json");
+export const profileDir = () => path.join(dir(), "profile");
+export const pidFile = () => path.join(dir(), "relay.pid");
+export const auditFile = () => path.join(dir(), "fetch-audit.jsonl");
+export const eventsDir = () => path.join(dir(), "events");
+export const dashboardRuntimeFile = () => path.join(dir(), "dashboard.json");
+function defaults(value = {}) {
+    return {
+        ...value,
+        loginDomains: Array.isArray(value.loginDomains) ? value.loginDomains : [],
+        pausedPodIds: Array.isArray(value.pausedPodIds) ? value.pausedPodIds : [],
+        blockedDomains: Array.isArray(value.blockedDomains) ? value.blockedDomains : [],
+        retentionDays: value.retentionDays === 7 || value.retentionDays === 90 ? value.retentionDays : 30,
+    };
+}
+export function load() {
+    try {
+        return defaults(JSON.parse(readFileSync(file(), "utf8")));
+    }
+    catch {
+        return defaults();
+    }
+}
+export function save(cfg) {
+    mkdirSync(dir(), { recursive: true, mode: 0o700 });
+    writeFileSync(file(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+export function addLoginDomain(domain) {
+    const cfg = load();
+    if (!cfg.loginDomains.includes(domain))
+        cfg.loginDomains.push(domain);
+    save(cfg);
+}
+const normalizedDomain = (value) => value.trim().toLowerCase().replace(/^\.+|\.+$/g, "");
+const normalizedPodId = (value) => value.trim().slice(0, 160);
+export function setPodPaused(podId, paused) {
+    const cfg = load();
+    const id = normalizedPodId(podId);
+    if (!id)
+        return cfg;
+    const values = new Set(cfg.pausedPodIds ?? []);
+    if (paused)
+        values.add(id);
+    else
+        values.delete(id);
+    cfg.pausedPodIds = [...values].sort();
+    save(cfg);
+    return cfg;
+}
+export function setDomainBlocked(domain, blocked) {
+    const cfg = load();
+    const value = normalizedDomain(domain);
+    if (!value || /[\s/:@?#]/.test(value))
+        return cfg;
+    const values = new Set(cfg.blockedDomains ?? []);
+    if (blocked)
+        values.add(value);
+    else
+        values.delete(value);
+    cfg.blockedDomains = [...values].sort();
+    save(cfg);
+    return cfg;
+}
+export function setRetentionDays(days) {
+    if (days !== 7 && days !== 30 && days !== 90)
+        throw new Error("retention must be 7, 30, or 90 days");
+    const cfg = load();
+    cfg.retentionDays = days;
+    save(cfg);
+    return cfg;
+}
+export function revokeLoginDomain(domain) {
+    const value = normalizedDomain(domain);
+    const cfg = load();
+    cfg.loginDomains = cfg.loginDomains.filter((item) => item !== value);
+    save(cfg);
+    return cfg;
+}
+export function isPodPaused(cfg, podId) {
+    return !!podId && (cfg.pausedPodIds ?? []).includes(podId);
+}
+export function isDomainBlocked(cfg, host) {
+    return (cfg.blockedDomains ?? []).some((domain) => host === domain || host.endsWith(`.${domain}`));
+}
+export function resetProfile() {
+    if (existsSync(profileDir()))
+        rmSync(profileDir(), { recursive: true, force: true });
+    const cfg = load();
+    cfg.loginDomains = [];
+    // Forget the reconnect token too — reset means fully un-pair; the next start needs a
+    // fresh code. (The gateway-side token expires on its own; a security revoke is a
+    // separate operation.)
+    delete cfg.reconnectToken;
+    save(cfg);
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,67 @@
+import type { RelayEventStore } from "./audit.js";
+import { type RelayConfig } from "./config.js";
+import { RelayRuntime } from "./runtime.js";
+export interface DashboardEvent {
+    id: string;
+    at: string;
+    podId?: string;
+    /** Gateway-resolved display name; the UI shows this in place of podId when present. */
+    podName?: string;
+    mode: "fetch" | "tunnel";
+    outcome: "ok" | "site-refused" | "owner-blocked" | "safety-blocked" | "rate-limited" | "network-error";
+    target: string;
+    host: string;
+    status?: number;
+    ms: number;
+    session: boolean;
+    bytesUp?: number;
+    bytesDown?: number;
+    reason?: string;
+}
+export interface DashboardData {
+    preview: boolean;
+    state: "connected" | "reconnecting" | "stopped";
+    stateSince: string;
+    updatedAt: string;
+    events: DashboardEvent[];
+    active: Array<{
+        id: string;
+        podId?: string;
+        podName?: string;
+        mode: "fetch" | "tunnel";
+        target: string;
+        startedAt: string;
+        bytesUp?: number;
+        bytesDown?: number;
+    }>;
+    signedInSites: string[];
+    blockedSites: string[];
+    pausedPods: string[];
+    retentionDays: 7 | 30 | 90;
+    storagePath: string;
+    storageBytes: number;
+    trend: number[];
+}
+export type DashboardFixture = "active" | "empty" | "healthy" | "failures" | "signed-in" | "legacy" | "stopped" | "large";
+export declare function fixtureData(name: DashboardFixture, now?: number): DashboardData;
+export interface DashboardActions {
+    stop?(): void | Promise<void>;
+    revokeSession?(domain: string): void | Promise<void>;
+}
+export interface DashboardOptions {
+    preview?: boolean;
+    fixture?: DashboardFixture;
+    readOnly?: boolean;
+    store?: RelayEventStore;
+    runtime?: RelayRuntime;
+    config?: () => RelayConfig;
+    actions?: DashboardActions;
+    routeToken?: string;
+    csrfToken?: string;
+}
+export declare function serveDashboard(port?: number, options?: DashboardOptions): Promise<{
+    url: string;
+    close: () => void;
+    routeToken: string;
+    csrfToken: string;
+}>;