rpc-agent 0.3.1 → 0.5.0

package/dist/auth.js

@@ -0,0 +1,416 @@
+// Authenticated captures: cookies, headers, storage state and saved sessions.
+//
+// Everything rpc injects is scoped to the target origin (plus any origins the
+// caller allows explicitly). Secret values never appear in output: summaries
+// carry names only, and error text is scrubbed of every value we injected.
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+export const MASK = '•••';
+// ------------------------------------------------------------------ parsing
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** `name=value; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Lax` */
+export function parseCookie(raw) {
+    const [pair = '', ...attrs] = raw.split(';');
+    const eq = pair.indexOf('=');
+    const name = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+    if (eq === -1 || !name || !TOKEN.test(name)) {
+        throw new Error(`--cookie expects "name=value[; Domain=…; Path=…]", got "${name || '(empty)'}${eq === -1 ? '' : `=${MASK}`}"`);
+    }
+    const cookie = { name, value: pair.slice(eq + 1).trim() };
+    for (const attr of attrs) {
+        const i = attr.indexOf('=');
+        const key = (i === -1 ? attr : attr.slice(0, i)).trim().toLowerCase();
+        const val = i === -1 ? '' : attr.slice(i + 1).trim();
+        if (!key)
+            continue;
+        if (key === 'domain')
+            cookie.domain = val;
+        else if (key === 'path')
+            cookie.path = val || '/';
+        else if (key === 'secure')
+            cookie.secure = true;
+        else if (key === 'httponly')
+            cookie.httpOnly = true;
+        else if (key === 'samesite') {
+            const s = val.toLowerCase();
+            if (s !== 'lax' && s !== 'strict' && s !== 'none')
+                throw new Error(`Cookie "${name}": SameSite must be Lax, Strict or None`);
+            cookie.sameSite = (s[0].toUpperCase() + s.slice(1));
+        }
+        else if (key === 'expires' || key === 'max-age')
+            continue;
+        else
+            throw new Error(`Cookie "${name}": unknown attribute "${key}" (supported: Domain, Path, Secure, HttpOnly, SameSite)`);
+    }
+    return cookie;
+}
+/** `Name: value` */
+export function parseHeader(raw) {
+    const i = raw.indexOf(':');
+    const name = (i === -1 ? raw : raw.slice(0, i)).trim();
+    if (i === -1 || !name || !TOKEN.test(name)) {
+        throw new Error(`--header expects "Name: value", got "${name || '(empty)'}${i === -1 ? '' : `: ${MASK}`}"`);
+    }
+    return [name, raw.slice(i + 1).trim()];
+}
+function originOf(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Accept `localhost:3000`, `https://x.com/path` or a bare host; return its origin. */
+export function toOrigin(input) {
+    const raw = input.trim();
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw)
+        ? raw
+        : /^(localhost|127\.|0\.0\.0\.0|\[::1\])/i.test(raw)
+            ? `http://${raw}`
+            : `https://${raw}`;
+    const o = originOf(withScheme);
+    if (!o)
+        throw new Error(`"${input}" is not an http(s) origin`);
+    return o;
+}
+/** Cookie domain-match (RFC 6265 5.1.3), ignoring a leading dot. */
+export function domainMatches(host, domain) {
+    const d = domain.replace(/^\./, '').toLowerCase();
+    const h = host.toLowerCase();
+    return h === d || h.endsWith(`.${d}`);
+}
+function hostOf(origin) {
+    return new URL(origin).hostname;
+}
+// ------------------------------------------------------------------ sessions
+/** `$RPC_SESSIONS_DIR`, else `$XDG_CONFIG_HOME/rpc-agent/sessions`, else `~/.config/rpc-agent/sessions`. */
+export function sessionsDir(env = process.env) {
+    if (env.RPC_SESSIONS_DIR)
+        return resolve(env.RPC_SESSIONS_DIR);
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'rpc-agent', 'sessions');
+}
+/** `http://localhost:3400` -> `http-localhost-3400` */
+export function originSlug(origin) {
+    return origin
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+export function sessionPath(origin, dir = sessionsDir()) {
+    return join(dir, `${originSlug(origin)}.json`);
+}
+/**
+ * Write a storage state readable only by this user: the file is 0600 and,
+ * for the default sessions dir, the directory is 0700.
+ */
+export async function writeSession(state, meta, file) {
+    const target = file ? resolve(file) : sessionPath(meta.origin);
+    const dir = dirname(target);
+    if (!file) {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        await chmod(dir, 0o700);
+    }
+    else {
+        await mkdir(dir, { recursive: true });
+    }
+    const body = { cookies: state.cookies, origins: state.origins, rpc: meta };
+    const tmp = `${target}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(body, null, 2) + '\n', { mode: 0o600 });
+    await chmod(tmp, 0o600);
+    await rename(tmp, target);
+    return target;
+}
+function readState(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Could not read storage state ${path}: ${err.message.split('\n')[0]}`);
+    }
+    const s = parsed;
+    if (!s || typeof s !== 'object' || !Array.isArray(s.cookies ?? []) || !Array.isArray(s.origins ?? [])) {
+        throw new Error(`${path} is not a Playwright storageState file (expected { cookies: [], origins: [] })`);
+    }
+    return { cookies: s.cookies ?? [], origins: s.origins ?? [], ...(s.rpc ? { rpc: s.rpc } : {}) };
+}
+/** Cookies and localStorage that belong to the allowed origins only. */
+export function scopeState(state, allowed) {
+    const hosts = allowed.map(hostOf);
+    return {
+        cookies: state.cookies.filter(c => hosts.some(h => domainMatches(h, c.domain))),
+        origins: state.origins.filter(o => allowed.includes(o.origin)),
+    };
+}
+/** Latest expiry of the cookies, and whether all of them have passed it. */
+function expiry(cookies, now = Date.now() / 1000) {
+    if (cookies.length === 0 || cookies.some(c => !(c.expires > 0)))
+        return { expired: false };
+    const latest = Math.max(...cookies.map(c => c.expires));
+    return { expired: latest < now, expires: new Date(latest * 1000).toISOString() };
+}
+function describeSession(path, file, origin) {
+    const own = scopeState(file, [origin]);
+    const e = expiry(own.cookies);
+    return {
+        origin,
+        path,
+        ...(file.rpc?.savedAt ? { savedAt: file.rpc.savedAt } : {}),
+        cookies: own.cookies.length,
+        localStorage: own.origins.length,
+        ...(e.expired ? { expired: true } : {}),
+        ...(e.expires ? { expires: e.expires } : {}),
+    };
+}
+export async function listSessions(dir = sessionsDir()) {
+    let names;
+    try {
+        names = (await readdir(dir)).filter(n => n.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        const path = join(dir, n);
+        try {
+            const file = readState(path);
+            const origin = file.rpc?.origin ?? originFromSlug(n);
+            if (origin)
+                out.push(describeSession(path, file, origin));
+        }
+        catch {
+            // Not ours or unreadable; skip.
+        }
+    }
+    return out;
+}
+function originFromSlug(name) {
+    const m = /^(https?)-(.+?)(?:-(\d+))?\.json$/.exec(name);
+    return m ? `${m[1]}://${m[2].replace(/-/g, '.')}${m[3] ? `:${m[3]}` : ''}` : undefined;
+}
+/** Delete the saved session for one origin, or all of them. Returns the origins removed. */
+export async function clearSessions(origin, dir = sessionsDir()) {
+    const all = await listSessions(dir);
+    const target = origin ? toOrigin(origin) : undefined;
+    const gone = all.filter(s => !target || s.origin === target);
+    for (const s of gone)
+        await rm(s.path, { force: true });
+    return gone.map(s => s.origin);
+}
+/** File mode bits, for tests and `rpc sessions list`. */
+export async function fileMode(path) {
+    return (await stat(path)).mode & 0o777;
+}
+// ------------------------------------------------------------------ resolve
+/**
+ * Validate cookies and headers against the target URL and load the storage
+ * state or saved session. Throws on bad input (names only in messages).
+ */
+export function resolveAuth(url, opts, dir = sessionsDir()) {
+    const origin = originOf(url);
+    const secrets = [];
+    const summary = {};
+    const allowed = [];
+    if (origin)
+        allowed.push(origin);
+    for (const o of opts.allowOrigins ?? []) {
+        const n = toOrigin(o);
+        if (!allowed.includes(n))
+            allowed.push(n);
+    }
+    if (opts.allowOrigins?.length)
+        summary.allowOrigins = allowed.slice(1);
+    const wantsInjection = Boolean(opts.cookies?.length || (opts.headers && Object.keys(opts.headers).length));
+    if (!origin && (wantsInjection || opts.storageState)) {
+        throw new Error('Cookies, headers and storage state need an http(s) URL');
+    }
+    // Cookies: host-only on the target unless a Domain that matches it (or an allowed origin) is given.
+    const cookies = [];
+    for (const c of opts.cookies ?? []) {
+        const host = hostOf(origin);
+        let domain = host;
+        if (c.domain) {
+            const ok = allowed.some(o => domainMatches(hostOf(o), c.domain));
+            if (!ok) {
+                throw new Error(`Cookie "${c.name}" has Domain=${c.domain}, which doesn't match ${host}. Cookies only go to the target origin; add --allow-origin to widen it.`);
+            }
+            // A Domain attribute means "this host and its subdomains", as in a browser.
+            domain = `.${c.domain.replace(/^\./, '')}`;
+        }
+        cookies.push({
+            name: c.name,
+            value: c.value,
+            domain,
+            path: c.path ?? '/',
+            expires: -1,
+            httpOnly: c.httpOnly ?? false,
+            secure: c.secure ?? false,
+            sameSite: c.sameSite ?? 'Lax',
+        });
+        secrets.push(c.value);
+    }
+    if (cookies.length) {
+        summary.cookies = cookies.map(c => ({ name: c.name, value: MASK, domain: c.domain, path: c.path }));
+    }
+    const headers = {};
+    for (const [k, v] of Object.entries(opts.headers ?? {})) {
+        if (!TOKEN.test(k))
+            throw new Error(`Invalid header name "${k}"`);
+        headers[k] = String(v);
+        secrets.push(String(v));
+    }
+    if (Object.keys(headers).length) {
+        summary.headers = Object.fromEntries(Object.keys(headers).map(k => [k, MASK]));
+    }
+    let state;
+    if (opts.storageState) {
+        const path = resolve(opts.storageState);
+        if (!existsSync(path))
+            throw new Error(`Storage state file not found: ${path}`);
+        state = scopeState(readState(path), allowed);
+        summary.storageState = path;
+    }
+    else if (origin) {
+        const path = sessionPath(origin, dir);
+        if (existsSync(path)) {
+            const file = readState(path);
+            const info = describeSession(path, file, origin);
+            const load = opts.useSession !== false && !info.expired;
+            const { localStorage: _ls, ...rest } = info;
+            summary.session = { ...rest, loaded: load };
+            if (load)
+                state = scopeState(file, allowed);
+        }
+    }
+    for (const c of state?.cookies ?? [])
+        secrets.push(c.value);
+    for (const o of state?.origins ?? [])
+        for (const kv of o.localStorage)
+            secrets.push(kv.value);
+    const used = Object.keys(summary).length > 0;
+    return {
+        ...(origin ? { origin } : {}),
+        allowed,
+        ...(state ? { state } : {}),
+        cookies,
+        headers,
+        ...(used ? { summary } : {}),
+        secrets: [...new Set(secrets.filter(s => s.length >= 4))].sort((a, b) => b.length - a.length),
+    };
+}
+/** `2026-10-29 22:55` in the local time zone. */
+export function localTime(iso) {
+    if (!iso)
+        return '';
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return '';
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+/** Replace every secret value in text with •••. */
+export function redact(text, secrets) {
+    let out = text;
+    for (const s of secrets)
+        if (out.includes(s))
+            out = out.split(s).join(MASK);
+    return out;
+}
+/** One line for plain output: `session http://x (saved …), cookie sid=•••, header Authorization: •••`. */
+export function describeAuth(s) {
+    const parts = [];
+    if (s.session) {
+        const when = s.session.savedAt ? `saved ${localTime(s.session.savedAt)}` : '';
+        if (s.session.loaded)
+            parts.push(`session ${s.session.origin}${when ? ` (${when})` : ''}`);
+        else if (s.session.expired)
+            parts.push(`session ${s.session.origin} expired, not loaded`);
+        else
+            parts.push(`session ${s.session.origin} skipped (--no-session)`);
+    }
+    if (s.storageState)
+        parts.push(`storage state ${s.storageState}`);
+    for (const c of s.cookies ?? [])
+        parts.push(`cookie ${c.name}=${MASK}`);
+    for (const h of Object.keys(s.headers ?? {}))
+        parts.push(`header ${h}: ${MASK}`);
+    if (s.allowOrigins?.length)
+        parts.push(`also ${s.allowOrigins.join(', ')}`);
+    return parts.join(', ');
+}
+// ------------------------------------------------------------------ apply
+/**
+ * Send the extra headers on requests to allowed origins only. Uses the CDP
+ * Fetch domain rather than page.route: route() header overrides follow
+ * redirects, so a 302 to another host would carry the header there. Fetch
+ * pauses each redirect hop separately, so every hop is checked.
+ */
+export async function applyHeaders(context, page, auth) {
+    const extra = Object.entries(auth.headers);
+    if (extra.length === 0)
+        return;
+    const lower = new Set(extra.map(([k]) => k.toLowerCase()));
+    const cdp = await context.newCDPSession(page);
+    cdp.on('Fetch.requestPaused', e => {
+        const allowed = auth.allowed.includes(originOf(e.request.url) ?? '');
+        const params = { requestId: e.requestId };
+        if (allowed) {
+            params.headers = [
+                ...Object.entries(e.request.headers)
+                    .filter(([k]) => !lower.has(k.toLowerCase()))
+                    .map(([name, value]) => ({ name, value: String(value) })),
+                ...extra.map(([name, value]) => ({ name, value })),
+            ];
+        }
+        cdp.send('Fetch.continueRequest', params).catch(() => { });
+    });
+    await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+}
+// ------------------------------------------------------------------ login pages
+const LOGIN_SEGMENT = /^(log-?in|sign-?in|sign_in|signin|auth|authenticate|oauth2?|sso)(\.\w+)?$/i;
+/** True when a path segment looks like a login page (`/login`, `/sign-in`, `/auth/...`). */
+export function isLoginUrl(url) {
+    try {
+        return new URL(url).pathname.split('/').some(seg => LOGIN_SEGMENT.test(seg));
+    }
+    catch {
+        return false;
+    }
+}
+/** The page ended on a login URL that isn't the one requested. */
+export function redirectedToLogin(requested, final) {
+    try {
+        const a = new URL(requested);
+        const b = new URL(final);
+        if (b.protocol !== 'http:' && b.protocol !== 'https:')
+            return false;
+        return isLoginUrl(final) && a.origin + a.pathname !== b.origin + b.pathname;
+    }
+    catch {
+        return false;
+    }
+}
+export function loginHint(origin) {
+    return `Session missing or expired: run \`rpc login ${origin}\``;
+}
+export class AuthRequiredError extends Error {
+    requested;
+    finalUrl;
+    status;
+    name = 'AuthRequiredError';
+    code = 'AUTH_REQUIRED';
+    hint;
+    constructor(requested, finalUrl, status) {
+        const final = new URL(finalUrl);
+        super(`Redirected to a login page (${final.origin}${final.pathname}) instead of ${requested}`);
+        this.requested = requested;
+        this.finalUrl = finalUrl;
+        this.status = status;
+        this.hint = loginHint(new URL(requested).origin);
+    }
+}

package/dist/browser.js

@@ -63,17 +63,19 @@ export async function doctor() {
 }
 /**
  * Run `playwright install --only-shell chromium` with this package's
- * Playwright, streaming its output. rpc always launches headless, which uses
+ * Playwright, streaming its output. Captures always run headless, which uses
  * the headless shell, so the full Chrome for Testing build (about 370 MB on
- * disk) would never run.
+ * disk) is only fetched with `headed` (for `rpc login`'s browser window).
  */
-export function installChromium() {
+export function installChromium(opts = {}) {
     return new Promise((res, rej) => {
         // Load the CLI through -e with a plain argv[1]. Under npx the real path is
         // in the `_npx` cache, and Playwright then prints a box telling the user
         // to install their project's dependencies, which doesn't apply here.
         const loader = `process.argv.splice(1, 0, 'playwright'); require(${JSON.stringify(playwrightCli())});`;
-        const child = spawn(process.execPath, ['-e', loader, 'install', '--only-shell', 'chromium'], { stdio: 'inherit' });
+        // --headed: full Chromium as well, for `rpc login`'s visible window.
+        const args = opts.headed ? ['install', 'chromium'] : ['install', '--only-shell', 'chromium'];
+        const child = spawn(process.execPath, ['-e', loader, ...args], { stdio: 'inherit' });
         child.on('error', rej);
         child.on('exit', code => res(code ?? 1));
     });

package/dist/capture.js

@@ -1,5 +1,6 @@
 import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
+import { applyHeaders, AuthRequiredError, redact, redirectedToLogin, resolveAuth, } from './auth.js';
 import { launchBrowser } from './browser.js';
 import { renderFramed, renderSlices } from './composite.js';
 import { explainError } from './errors.js';
@@ -11,7 +12,10 @@ export { launchBrowser } from './browser.js';
 export async function capture(opts, hooks = {}) {
     const devices = resolveDevices(opts.devices);
     const outDir = resolve(opts.outDir);
+    const auth = hooks.auth ?? resolveAuth(opts.url, opts.auth ?? {});
     await mkdir(outDir, { recursive: true });
+    if (auth.summary)
+        hooks.onAuth?.(auth.summary);
     const browser = hooks.browser ?? (await launchBrowser());
     try {
         const shots = [];
@@ -19,28 +23,38 @@ export async function capture(opts, hooks = {}) {
             let shot;
             hooks.onDeviceStart?.(device);
             try {
-                shot = await captureDevice(browser, device, opts, outDir, hooks);
+                shot = await captureDevice(browser, device, opts, outDir, hooks, auth);
             }
             catch (err) {
-                shot = baseShot(device);
-                const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
-                shot.error = e.error;
-                shot.code = e.code;
-                if (e.hint)
-                    shot.hint = e.hint;
+                shot = { ...baseShot(device), ...describeFailure(err, opts, auth) };
+            }
+            if (shot.consoleErrors?.length && auth.secrets.length) {
+                shot.consoleErrors = shot.consoleErrors.map(l => redact(l, auth.secrets));
             }
             if (!hooks.keepBuffers)
                 delete shot.buffers;
             hooks.onDevice?.(shot);
             shots.push(shot);
         }
-        return { url: opts.url, outDir, shots };
+        return { url: opts.url, outDir, shots, ...(auth.summary ? { auth: auth.summary } : {}) };
     }
     finally {
         if (!hooks.browser)
             await browser.close();
     }
 }
+/** A device's navigation/capture failure as `{ error, code, hint }`, secrets scrubbed. */
+export function describeFailure(err, opts, auth) {
+    if (err instanceof AuthRequiredError) {
+        return { status: err.status, finalUrl: err.finalUrl, error: err.message, code: err.code, hint: err.hint };
+    }
+    const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
+    return {
+        error: redact(e.error, auth.secrets),
+        code: e.code,
+        ...(e.hint ? { hint: redact(e.hint, auth.secrets) } : {}),
+    };
+}
 function baseShot(device) {
     return {
         device: device.id,
@@ -49,7 +63,8 @@ function baseShot(device) {
         dpr: device.dpr,
     };
 }
-async function captureDevice(browser, device, opts, outDir, hooks) {
+/** A fresh context for one device: viewport, DPR, mobile emulation, media features and auth state. */
+export async function newDeviceContext(browser, device, opts, auth) {
     const emu = opts.emulate ? emulationFor(device) : undefined;
     const context = await browser.newContext({
         viewport: { width: device.width, height: device.height },
@@ -60,11 +75,19 @@ async function captureDevice(browser, device, opts, outDir, hooks) {
         ...(opts.colorScheme ? { colorScheme: opts.colorScheme } : {}),
         ...(opts.reducedMotion ? { reducedMotion: 'reduce' } : {}),
         ignoreHTTPSErrors: true, // self-signed local dev certs
+        ...(auth.state ? { storageState: auth.state } : {}),
     });
+    if (auth.cookies.length)
+        await context.addCookies(auth.cookies);
+    return context;
+}
+async function captureDevice(browser, device, opts, outDir, hooks, auth) {
+    const context = await newDeviceContext(browser, device, opts, auth);
     const result = baseShot(device);
     const errors = new Set();
     try {
         const page = await context.newPage();
+        await applyHeaders(context, page, auth);
         page.on('pageerror', e => errors.add(`pageerror: ${e.message}`));
         page.on('console', m => {
             if (m.type() === 'error')
@@ -73,8 +96,20 @@ async function captureDevice(browser, device, opts, outDir, hooks) {
         const response = await page.goto(opts.url, { waitUntil: 'load', timeout: opts.timeoutMs });
         result.status = response?.status() ?? null;
         await settle(page, opts.timeoutMs);
+        // A login page instead of the requested one: say so rather than capture it.
+        const checkLogin = () => {
+            if (redirectedToLogin(opts.url, page.url()))
+                throw new AuthRequiredError(opts.url, page.url(), result.status ?? null);
+        };
+        checkLogin();
         if (opts.waitFor) {
-            await page.waitForSelector(opts.waitFor, { state: 'visible', timeout: opts.timeoutMs });
+            try {
+                await page.waitForSelector(opts.waitFor, { state: 'visible', timeout: opts.timeoutMs });
+            }
+            catch (err) {
+                checkLogin();
+                throw err;
+            }
         }
         if (opts.fullPage) {
             await warmUpScroll(page, opts.maxHeight);
@@ -82,6 +117,7 @@ async function captureDevice(browser, device, opts, outDir, hooks) {
         }
         if (opts.waitMs > 0)
             await page.waitForTimeout(opts.waitMs);
+        checkLogin();
         result.finalUrl = page.url();
         result.title = await page.title();
         result.scrollHeight = await page.evaluate(SCROLL_HEIGHT_JS);
@@ -211,7 +247,7 @@ const SCROLL_HEIGHT_JS = `Math.max(document.documentElement.scrollHeight, docume
  * Network idle (bounded: dev servers with HMR or analytics beacons may never
  * go idle), web fonts, and pending <img> loads.
  */
-async function settle(page, timeoutMs) {
+export async function settle(page, timeoutMs) {
     await page
         .waitForLoadState('networkidle', { timeout: Math.min(timeoutMs, 10_000) })
         .catch(() => { });