@podway/relay 0.2.3

package/dist/net-guard.js

@@ -0,0 +1,47 @@
+/**
+ * VENDORED from `@podbay/shared/src/net-guard.ts` — keep the two IDENTICAL in behaviour.
+ *
+ * Why a copy: `pb` is published standalone to npm and builds with plain tsc, so it can
+ * carry no workspace dependency. Why it is safe: `test/net-guard-parity.test.ts` runs
+ * BOTH implementations over the same table and fails if they ever disagree, so a drift
+ * in this security control breaks the build rather than opening a quiet hole.
+ */
+export function isDisallowedTarget(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    // IPv4 literal
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+    if (v4) {
+        const o = v4.slice(1).map(Number);
+        if (o.some((n) => n > 255))
+            return true; // malformed → refuse
+        const [a, b] = o;
+        if (a === 127 || a === 10 || a === 0)
+            return true; // loopback / private / this-host
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16/12
+        if (a === 192 && b === 168)
+            return true; // 192.168/16
+        if (a === 169 && b === 254)
+            return true; // link-local
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // CGNAT 100.64/10
+        if (a >= 224)
+            return true; // multicast / reserved
+        return false;
+    }
+    // IPv6 literal: refuse loopback, unspecified, link-local (fe80::/10), unique-local (fc00::/7)
+    if (h.includes(":")) {
+        if (h === "::1" || h === "::")
+            return true;
+        if (h.startsWith("fe8") || h.startsWith("fe9") || h.startsWith("fea") || h.startsWith("feb"))
+            return true;
+        if (h.startsWith("fc") || h.startsWith("fd"))
+            return true;
+        if (h.startsWith("::ffff:"))
+            return isDisallowedTarget(h.slice(7)); // v4-mapped
+        return false;
+    }
+    return false; // a domain name — allowed here; owner re-checks post-DNS
+}

package/dist/relay-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The relay's protocol brain: what to do with each fetch the gateway sends.
+ *
+ * The design (decided 2026-07-31): once the owner starts the relay, the pod may fetch
+ * the public web through it freely — no per-request approval, because nobody watches a
+ * terminal to click "allow". Oversight is after the fact: every fetch is audited, and
+ * the owner monitors via `relay dashboard` and the admin dashboard.
+ *
+ * Two guards remain, and both protect the OWNER, not us:
+ *  1. The relay refuses a URL that is not a plain web address or resolves to a bare IP
+ *     or private host. A prompt-injected pod must not be able to make the owner's
+ *     machine hit their own LAN (192.168.x, 10.x, localhost) — an SSRF the owner cannot
+ *     see to consent to.
+ *  2. WHICH sessions are used is decided by the fetcher: a domain the owner explicitly
+ *     signed into (`relay login`) is fetched AS them; every other domain is fetched
+ *     from a CLEAN context with no cookies. So "fetch as me" is opt-in per site, and a
+ *     compromised pod cannot read accounts the owner never lent it.
+ *
+ * Pure over injected effects (fetcher, audit) so the decisions test without a browser.
+ */
+import { type RelayEventV2, type RelaySource } from "./audit.js";
+import type { RelayRuntime } from "./runtime.js";
+export interface RelaySocket {
+    send(json: string): void;
+}
+export interface FetchJob {
+    id: string;
+    url: string;
+    source?: RelaySource;
+}
+export interface FetchOutput {
+    status: number;
+    body: string;
+    finalUrl?: string;
+    error?: string;
+    /** Whether the fetch used the owner's signed-in session (a login domain) or a clean
+     * context. Recorded in the audit so the owner can see it. */
+    session?: boolean;
+}
+export type Fetcher = (job: FetchJob) => Promise<FetchOutput>;
+export type AuditFn = (entry: RelayEventV2) => void;
+/** Host of a URL, or null if it is not a public web host the relay may fetch. */
+export declare function publicHostOf(url: string): string | null;
+interface Opts {
+    maxConcurrent?: number;
+    queueMax?: number;
+    audit?: AuditFn;
+    runtime?: RelayRuntime;
+    /** Return a refusal reason before any browser work, or undefined to allow. */
+    deny?: (source: RelaySource | undefined, host: string) => string | undefined;
+    now?: () => number;
+}
+export declare class RelayClient {
+    private readonly socket;
+    private readonly fetcher;
+    private readonly opts;
+    private active;
+    private readonly queue;
+    constructor(socket: RelaySocket, fetcher: Fetcher, opts?: Opts);
+    private reply;
+    onMessage(raw: string): Promise<void>;
+    private now;
+    private audit;
+    private run;
+}
+export {};

package/dist/relay-client.js

@@ -0,0 +1,154 @@
+/**
+ * The relay's protocol brain: what to do with each fetch the gateway sends.
+ *
+ * The design (decided 2026-07-31): once the owner starts the relay, the pod may fetch
+ * the public web through it freely — no per-request approval, because nobody watches a
+ * terminal to click "allow". Oversight is after the fact: every fetch is audited, and
+ * the owner monitors via `relay dashboard` and the admin dashboard.
+ *
+ * Two guards remain, and both protect the OWNER, not us:
+ *  1. The relay refuses a URL that is not a plain web address or resolves to a bare IP
+ *     or private host. A prompt-injected pod must not be able to make the owner's
+ *     machine hit their own LAN (192.168.x, 10.x, localhost) — an SSRF the owner cannot
+ *     see to consent to.
+ *  2. WHICH sessions are used is decided by the fetcher: a domain the owner explicitly
+ *     signed into (`relay login`) is fetched AS them; every other domain is fetched
+ *     from a CLEAN context with no cookies. So "fetch as me" is opt-in per site, and a
+ *     compromised pod cannot read accounts the owner never lent it.
+ *
+ * Pure over injected effects (fetcher, audit) so the decisions test without a browser.
+ */
+import { fetchOutcome, safeFetchTarget, } from "./audit.js";
+/** Host of a URL, or null if it is not a public web host the relay may fetch. */
+export function publicHostOf(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        return null;
+    const h = u.hostname.toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
+    if (!h.includes(".") || h.includes(":"))
+        return null;
+    // No bare IPs, and no private / loopback ranges — this is the SSRF guard.
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(h)) {
+        if (/^(10|127)\./.test(h) || /^192\.168\./.test(h) || /^172\.(1[6-9]|2\d|3[01])\./.test(h) || /^169\.254\./.test(h) || h === "0.0.0.0") {
+            return null;
+        }
+        return null; // a bare public IP is still refused — the relay lends NAMED sites
+    }
+    if (h === "localhost" || h.endsWith(".local") || h.endsWith(".internal") || h.endsWith(".lan"))
+        return null;
+    return h;
+}
+export class RelayClient {
+    socket;
+    fetcher;
+    opts;
+    active = 0;
+    queue = [];
+    constructor(socket, fetcher, opts = {}) {
+        this.socket = socket;
+        this.fetcher = fetcher;
+        this.opts = opts;
+    }
+    reply(id, out) {
+        this.socket.send(JSON.stringify({ type: "fetch-result", id, ...out }));
+    }
+    async onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (msg.type !== "fetch" || !msg.id || !msg.url)
+            return;
+        const safe = safeFetchTarget(msg.url);
+        const host = publicHostOf(msg.url);
+        if (!safe || !host) {
+            // The one thing we refuse rather than serve: a non-public / private target.
+            const auditSafe = safe ?? safeFetchTarget("https://invalid.invalid/");
+            this.audit({ id: msg.id, url: auditSafe.target, source: msg.source }, auditSafe, "safety-blocked", 0, false, "refused: not a public web URL");
+            this.reply(msg.id, { status: 0, body: "", error: "the relay only fetches public web addresses" });
+            return;
+        }
+        const denial = this.opts.deny?.(msg.source, host);
+        if (denial) {
+            this.audit({ id: msg.id, url: safe.target, source: msg.source }, safe, "owner-blocked", 0, false, denial);
+            this.reply(msg.id, { status: 0, body: "", error: denial });
+            return;
+        }
+        if (this.active >= (this.opts.maxConcurrent ?? 3)) {
+            if (this.queue.length >= (this.opts.queueMax ?? 200)) {
+                this.reply(msg.id, { status: 0, body: "", error: "relay busy — queue full" });
+                return;
+            }
+            this.queue.push({ id: msg.id, url: msg.url, source: msg.source });
+            return;
+        }
+        void this.run({ id: msg.id, url: msg.url, source: msg.source }, host, safe);
+    }
+    now() { return (this.opts.now ?? Date.now)(); }
+    audit(job, safe, outcome, started, session, reason, status, finalTarget) {
+        const finished = this.now();
+        this.opts.audit?.({
+            v: 2,
+            id: `fetch-${job.id}`,
+            startedAt: new Date(started || finished).toISOString(),
+            finishedAt: new Date(finished).toISOString(),
+            durationMs: started ? Math.max(0, finished - started) : 0,
+            source: job.source,
+            mode: "fetch",
+            outcome,
+            target: safe.target,
+            ...(finalTarget ? { finalTarget } : {}),
+            host: safe.host,
+            ...(status !== undefined ? { httpStatus: status } : {}),
+            session,
+            ...(reason ? { reason } : {}),
+        });
+    }
+    async run(job, host, safe = safeFetchTarget(job.url)) {
+        const denial = this.opts.deny?.(job.source, host);
+        if (denial) {
+            this.audit(job, safe, "owner-blocked", 0, false, denial);
+            this.reply(job.id, { status: 0, body: "", error: denial });
+            return;
+        }
+        this.active++;
+        const started = this.now();
+        this.opts.runtime?.begin({ id: job.id, source: job.source, mode: "fetch", target: safe.target, startedAt: new Date(started).toISOString() });
+        try {
+            const out = await this.fetcher(job);
+            // A redirect that landed on a private target is the same SSRF, after the fact.
+            if (out.finalUrl && !publicHostOf(out.finalUrl)) {
+                this.reply(job.id, { status: 0, body: "", error: "redirected to a non-public address" });
+                this.audit(job, safe, "safety-blocked", started, !!out.session, "redirect to private");
+                return;
+            }
+            this.reply(job.id, out);
+            const final = out.finalUrl ? safeFetchTarget(out.finalUrl)?.target : undefined;
+            this.audit(job, safe, fetchOutcome(out.status, out.error), started, !!out.session, out.error, out.status, final);
+        }
+        catch (e) {
+            this.reply(job.id, { status: 0, body: "", error: String(e) });
+            this.audit(job, safe, "network-error", started, false, String(e), 0);
+        }
+        finally {
+            this.opts.runtime?.finish(job.id);
+            this.active--;
+            const next = this.queue.shift();
+            if (next) {
+                const h = publicHostOf(next.url);
+                const nextSafe = safeFetchTarget(next.url);
+                if (h && nextSafe)
+                    void this.run(next, h, nextSafe);
+            }
+        }
+    }
+}

package/dist/relay-tunnel.d.ts

@@ -0,0 +1,62 @@
+import { type RelayEventV2, type RelaySource } from "./audit.js";
+import type { RelayRuntime } from "./runtime.js";
+/**
+ * The owner's half of the egress tunnel: a pod asked (via the gateway) for a connection
+ * to `host:port`; we make it FROM THIS MACHINE and stream the bytes back.
+ *
+ * The guard that only this end can enforce: **re-check after DNS**. The pod and gateway
+ * can only refuse address *literals* — a hostname that resolves to 127.0.0.1 or
+ * 192.168.x (a rebinding trick) gets past them. Here the socket is connected, so the
+ * resolved peer address is known: if it turns out to be private, the connection is
+ * dropped before a single byte flows. That is the difference between checking a string
+ * and checking where the packets actually went.
+ *
+ * Everything IO is injected (dial, audit, clock) so the routing and the guard are tested
+ * without opening a socket.
+ */
+export interface TunnelSink {
+    send(json: string): void;
+}
+/** The minimum of a net.Socket this module uses — so tests can supply a fake. */
+export interface DialedSocket {
+    on(event: "data", cb: (chunk: Buffer) => void): unknown;
+    on(event: "close" | "end" | "error", cb: () => void): unknown;
+    write(chunk: Buffer): unknown;
+    end(): unknown;
+    destroy(): unknown;
+    remoteAddress?: string;
+}
+export type Dialer = (host: string, port: number, onConnect: (s: DialedSocket) => void, onError: () => void) => DialedSocket;
+export interface TunnelAudit {
+    (event: RelayEventV2): void;
+}
+export declare class RelayTunnel {
+    private readonly sink;
+    private readonly opts;
+    private readonly streams;
+    constructor(sink: TunnelSink, opts?: {
+        dial?: Dialer;
+        audit?: TunnelAudit;
+        runtime?: RelayRuntime;
+        deny?: (source: RelaySource | undefined, host: string) => string | undefined;
+        now?: () => number;
+    });
+    get openCount(): number;
+    /** Handle one gateway frame. Returns false if it wasn't a tunnel frame. */
+    handle(msg: {
+        type?: string;
+        id?: string;
+        host?: string;
+        port?: number;
+        b64?: string;
+        source?: RelaySource;
+    }): boolean;
+    private now;
+    private audit;
+    private refuse;
+    private open;
+    /** Close a stream. `fromGateway` means the pod hung up, so we don't echo a close back. */
+    private dropStream;
+    /** Tear everything down (relay stopping / socket lost). */
+    closeAll(): void;
+}

package/dist/relay-tunnel.js

@@ -0,0 +1,138 @@
+import { connect } from "node:net";
+import { isDisallowedTarget } from "./net-guard.js";
+import { safeTunnelTarget } from "./audit.js";
+const defaultDial = (host, port, onConnect, onError) => {
+    const s = connect({ host, port });
+    s.once("connect", () => onConnect(s));
+    s.once("error", onError);
+    return s;
+};
+export class RelayTunnel {
+    sink;
+    opts;
+    streams = new Map();
+    constructor(sink, opts = {}) {
+        this.sink = sink;
+        this.opts = opts;
+    }
+    get openCount() {
+        return this.streams.size;
+    }
+    /** Handle one gateway frame. Returns false if it wasn't a tunnel frame. */
+    handle(msg) {
+        if (!msg.type?.startsWith("tunnel-"))
+            return false;
+        const id = msg.id;
+        if (!id)
+            return true;
+        switch (msg.type) {
+            case "tunnel-open":
+                this.open(id, String(msg.host ?? ""), Number(msg.port ?? 0), msg.source);
+                return true;
+            case "tunnel-data": {
+                const st = this.streams.get(id);
+                if (st && msg.b64) {
+                    const chunk = Buffer.from(msg.b64, "base64");
+                    st.up += chunk.length;
+                    this.opts.runtime?.addBytes(id, "up", chunk.length);
+                    st.sock.write(chunk);
+                }
+                return true;
+            }
+            case "tunnel-close":
+                this.dropStream(id, true);
+                return true;
+            default:
+                return true;
+        }
+    }
+    now() { return (this.opts.now ?? Date.now)(); }
+    audit(id, host, port, source, started, outcome, reason, bytesUp = 0, bytesDown = 0) {
+        const safe = safeTunnelTarget(host, port) ?? safeTunnelTarget("invalid.invalid", Number.isInteger(port) && port > 0 && port <= 65535 ? port : 1);
+        const finished = this.now();
+        this.opts.audit?.({
+            v: 2,
+            id: `tunnel-${id}`,
+            startedAt: new Date(started || finished).toISOString(),
+            finishedAt: new Date(finished).toISOString(),
+            durationMs: started ? Math.max(0, finished - started) : 0,
+            source,
+            mode: "tunnel",
+            outcome,
+            target: safe.target,
+            host: safe.host,
+            session: false,
+            bytesUp,
+            bytesDown,
+            ...(reason ? { reason } : {}),
+        });
+    }
+    refuse(id, host, port, source, outcome, reason, started = 0) {
+        this.opts.runtime?.finish(id);
+        this.audit(id, host, port, source, started, outcome, reason);
+        this.sink.send(JSON.stringify({ type: "tunnel-refused", id, reason }));
+    }
+    open(id, host, port, source) {
+        if (!host || !Number.isInteger(port) || port <= 0 || port > 65535) {
+            return this.refuse(id, host, port, source, "safety-blocked", "bad target");
+        }
+        const denial = this.opts.deny?.(source, host.toLowerCase().replace(/\.$/, ""));
+        if (denial)
+            return this.refuse(id, host, port, source, "owner-blocked", denial);
+        // Literal check (cheap, and catches the obvious attempt) …
+        if (isDisallowedTarget(host))
+            return this.refuse(id, host, port, source, "safety-blocked", "target not allowed");
+        const started = this.now();
+        const safe = safeTunnelTarget(host, port);
+        this.opts.runtime?.begin({ id, source, mode: "tunnel", target: safe.target, startedAt: new Date(started).toISOString() });
+        const dial = this.opts.dial ?? defaultDial;
+        const sock = dial(host, port, (s) => {
+            // … and the check only this end can do: where did it ACTUALLY connect? A
+            // hostname that resolves into the owner's LAN dies here, before any bytes.
+            // Fail CLOSED: if we can't read where it actually connected (falsy remoteAddress), we
+            // can't prove it isn't the owner's LAN — so refuse, don't wave it through.
+            const peer = s.remoteAddress;
+            if (!peer || isDisallowedTarget(peer)) {
+                s.destroy();
+                this.streams.delete(id);
+                return this.refuse(id, host, port, source, "safety-blocked", "resolved to a private address", started);
+            }
+            this.sink.send(JSON.stringify({ type: "tunnel-ready", id }));
+        }, () => {
+            this.streams.delete(id);
+            this.refuse(id, host, port, source, "network-error", "could not connect", started);
+        });
+        this.streams.set(id, { sock, host, port, up: 0, down: 0, source, started });
+        sock.on("data", (chunk) => {
+            const st = this.streams.get(id);
+            if (st)
+                st.down += chunk.length;
+            this.opts.runtime?.addBytes(id, "down", chunk.length);
+            this.sink.send(JSON.stringify({ type: "tunnel-data", id, b64: chunk.toString("base64") }));
+        });
+        sock.on("close", () => this.dropStream(id, false));
+        sock.on("error", () => this.dropStream(id, false, "network-error", "remote connection error"));
+    }
+    /** Close a stream. `fromGateway` means the pod hung up, so we don't echo a close back. */
+    dropStream(id, fromGateway, outcome = "ok", reason) {
+        const st = this.streams.get(id);
+        if (!st)
+            return;
+        this.streams.delete(id);
+        this.opts.runtime?.finish(id);
+        try {
+            st.sock.end();
+        }
+        catch {
+            /* already gone */
+        }
+        this.audit(id, st.host, st.port, st.source, st.started, outcome, reason, st.up, st.down);
+        if (!fromGateway)
+            this.sink.send(JSON.stringify({ type: "tunnel-close", id }));
+    }
+    /** Tear everything down (relay stopping / socket lost). */
+    closeAll() {
+        for (const id of [...this.streams.keys()])
+            this.dropStream(id, true);
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,41 @@
+import type { RelayMode, RelaySource } from "./audit.js";
+export type GatewayState = "connected" | "reconnecting" | "unavailable";
+export interface ActiveRelayWork {
+    id: string;
+    source?: RelaySource;
+    mode: RelayMode;
+    target: string;
+    startedAt: string;
+    bytesUp?: number;
+    bytesDown?: number;
+}
+export interface RelayRuntimeSnapshot {
+    daemon: "running" | "stopped";
+    gateway: GatewayState;
+    stateSince: string;
+    updatedAt: string;
+    version: string;
+    active: ActiveRelayWork[];
+}
+/** In-memory truth owned by the daemon; the dashboard reads snapshots, never state files. */
+export declare class RelayRuntime {
+    private readonly options;
+    private gateway;
+    private stateSince;
+    private readonly active;
+    constructor(options?: {
+        now?: () => number;
+        version?: string;
+        daemon?: "running" | "stopped";
+    });
+    private now;
+    private iso;
+    setGateway(state: GatewayState): void;
+    begin(work: Omit<ActiveRelayWork, "startedAt"> & {
+        startedAt?: string;
+    }): void;
+    addBytes(id: string, direction: "up" | "down", count: number): void;
+    finish(id: string): ActiveRelayWork | undefined;
+    clearActive(): void;
+    snapshot(): RelayRuntimeSnapshot;
+}

package/dist/runtime.js

@@ -0,0 +1,51 @@
+/** In-memory truth owned by the daemon; the dashboard reads snapshots, never state files. */
+export class RelayRuntime {
+    options;
+    gateway = "reconnecting";
+    stateSince;
+    active = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        this.stateSince = this.iso();
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    iso() { return new Date(this.now()).toISOString(); }
+    setGateway(state) {
+        if (state === this.gateway)
+            return;
+        this.gateway = state;
+        this.stateSince = this.iso();
+    }
+    begin(work) {
+        this.active.set(work.id, {
+            ...work,
+            startedAt: work.startedAt ?? this.iso(),
+            ...(work.mode === "tunnel" ? { bytesUp: work.bytesUp ?? 0, bytesDown: work.bytesDown ?? 0 } : {}),
+        });
+    }
+    addBytes(id, direction, count) {
+        const work = this.active.get(id);
+        if (!work || work.mode !== "tunnel")
+            return;
+        if (direction === "up")
+            work.bytesUp = (work.bytesUp ?? 0) + Math.max(0, count);
+        else
+            work.bytesDown = (work.bytesDown ?? 0) + Math.max(0, count);
+    }
+    finish(id) {
+        const work = this.active.get(id);
+        this.active.delete(id);
+        return work;
+    }
+    clearActive() { this.active.clear(); }
+    snapshot() {
+        return {
+            daemon: this.options.daemon ?? "running",
+            gateway: this.options.daemon === "stopped" ? "unavailable" : this.gateway,
+            stateSince: this.stateSince,
+            updatedAt: this.iso(),
+            version: this.options.version ?? "unknown",
+            active: [...this.active.values()].map((work) => ({ ...work, source: work.source ? { ...work.source } : undefined })),
+        };
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@podway/relay",
+  "version": "0.2.3",
+  "description": "Podbay relay — runs a fetch relay on your machine so a pod can read pages from your network, using sessions you sign into. Install: npm i -g @podway/relay, then `relay start`.",
+  "type": "module",
+  "bin": {
+    "relay": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "FAQ.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "playwright": "^1.49.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.9"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/podway-cloud/relay.git"
+  },
+  "homepage": "https://github.com/podway-cloud/relay#readme",
+  "bugs": {
+    "url": "https://github.com/podway-cloud/relay/issues"
+  }
+}