tuna-agent 0.1.0 → 0.1.2

package/dist/browser/security.js

@@ -0,0 +1,357 @@
+import { resolve, normalize, dirname, sep } from 'node:path';
+import { lookup } from 'node:dns/promises';
+import { lstat, realpath } from 'node:fs/promises';
+/**
+ * Thrown when a navigation URL is blocked by SSRF policy.
+ * Callers can catch this specifically to distinguish navigation blocks
+ * from other errors.
+ */
+export class InvalidBrowserNavigationUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidBrowserNavigationUrlError';
+    }
+}
+/** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
+export function withBrowserNavigationPolicy(ssrfPolicy) {
+    return { ssrfPolicy };
+}
+// Only http: and https: are permitted for navigation; about:blank is the sole non-network exception.
+const NETWORK_NAVIGATION_PROTOCOLS = new Set(['http:', 'https:']);
+const SAFE_NON_NETWORK_URLS = new Set(['about:blank']);
+/**
+ * Assert that a URL is allowed for browser navigation under the given SSRF policy.
+ * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
+ */
+export async function assertBrowserNavigationAllowed(opts) {
+    const rawUrl = String(opts.url ?? '').trim();
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new InvalidBrowserNavigationUrlError(`Invalid URL: "${rawUrl}"`);
+    }
+    // Block non-network protocols (file:, data:, javascript:, etc.) — only http/https allowed.
+    if (!NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol)) {
+        if (SAFE_NON_NETWORK_URLS.has(parsed.href))
+            return;
+        throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
+    }
+    const policy = opts.ssrfPolicy;
+    if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true)
+        return;
+    const allowedHostnames = [
+        ...(policy?.allowedHostnames ?? []),
+        ...(policy?.hostnameAllowlist ?? []),
+    ];
+    if (allowedHostnames.length) {
+        const hostname = parsed.hostname.toLowerCase();
+        if (allowedHostnames.some(h => h.toLowerCase() === hostname))
+            return;
+    }
+    if (await isInternalUrlResolved(rawUrl, opts.lookupFn)) {
+        throw new InvalidBrowserNavigationUrlError(`Navigation to internal/loopback address blocked: "${rawUrl}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`);
+    }
+}
+/**
+ * Validate that an output file path is safe — no directory traversal or escape.
+ * Rejects paths containing `..` segments or relative paths that could escape
+ * the intended output directory.
+ *
+ * @param path - The output path to validate
+ * @param allowedRoots - Optional list of allowed root directories. If provided,
+ *   the resolved path must be within one of these roots.
+ * @throws If the path is unsafe
+ */
+export async function assertSafeOutputPath(path, allowedRoots) {
+    if (!path || typeof path !== 'string') {
+        throw new Error('Output path is required.');
+    }
+    const normalized = normalize(path);
+    // Reject paths with traversal segments
+    if (normalized.includes('..')) {
+        throw new Error(`Unsafe output path: directory traversal detected in "${path}".`);
+    }
+    if (allowedRoots?.length) {
+        const resolved = resolve(normalized);
+        // Resolve the parent directory via realpath to detect symlink-parent escapes
+        let parentReal;
+        try {
+            parentReal = await realpath(dirname(resolved));
+        }
+        catch {
+            throw new Error(`Unsafe output path: parent directory is inaccessible for "${path}".`);
+        }
+        // If the target already exists, ensure it is not a symlink
+        try {
+            const targetStat = await lstat(resolved);
+            if (targetStat.isSymbolicLink()) {
+                throw new Error(`Unsafe output path: "${path}" is a symbolic link.`);
+            }
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        // Verify the resolved parent is within one of the allowed roots
+        const results = await Promise.all(allowedRoots.map(async (root) => {
+            try {
+                const rootStat = await lstat(resolve(root));
+                if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+                    return false;
+                const rootReal = await realpath(resolve(root));
+                return parentReal === rootReal || parentReal.startsWith(rootReal + sep);
+            }
+            catch {
+                return false;
+            }
+        }));
+        if (!results.some(Boolean)) {
+            throw new Error(`Unsafe output path: "${path}" is outside allowed directories.`);
+        }
+    }
+}
+/**
+ * Expand an IPv6 address (with optional :: abbreviation) to full 8-group
+ * colon-separated hex form. Returns null for invalid input.
+ */
+function expandIPv6(ip) {
+    let normalized = ip;
+    // Handle embedded IPv4 literal at end (e.g., 64:ff9b::192.168.1.1)
+    const v4Match = normalized.match(/^(.+:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (v4Match) {
+        const octets = v4Match[2].split('.').map(Number);
+        if (octets.some(o => o > 255))
+            return null;
+        const hexHi = ((octets[0] << 8) | octets[1]).toString(16).padStart(4, '0');
+        const hexLo = ((octets[2] << 8) | octets[3]).toString(16).padStart(4, '0');
+        normalized = v4Match[1] + hexHi + ':' + hexLo;
+    }
+    const halves = normalized.split('::');
+    if (halves.length > 2)
+        return null; // multiple :: is invalid
+    if (halves.length === 2) {
+        const left = halves[0] !== '' ? halves[0].split(':') : [];
+        const right = halves[1] !== '' ? halves[1].split(':') : [];
+        const needed = 8 - left.length - right.length;
+        if (needed < 0)
+            return null;
+        const groups = [...left, ...Array(needed).fill('0'), ...right];
+        if (groups.length !== 8)
+            return null;
+        return groups.map(g => g.padStart(4, '0')).join(':');
+    }
+    const groups = normalized.split(':');
+    if (groups.length !== 8)
+        return null;
+    return groups.map(g => g.padStart(4, '0')).join(':');
+}
+/**
+ * Convert two 16-bit hex group strings to a dotted-decimal IPv4 string.
+ */
+function hexToIPv4(hiHex, loHex) {
+    const hi = parseInt(hiHex, 16);
+    const lo = parseInt(loHex, 16);
+    return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+}
+/**
+ * Attempt to extract an IPv4 address embedded in an IPv6 transition address.
+ * Handles: IPv4-mapped (::ffff:), NAT64 (64:ff9b::/96, 64:ff9b:1::/48),
+ * 6to4 (2002::/16), and Teredo (2001:0000::/32).
+ *
+ * Returns:
+ *   - The embedded IPv4 string if found
+ *   - null if the address is not a known transition format
+ *   - '' (empty string) on parse error — callers MUST treat this as internal (fail closed)
+ */
+function extractEmbeddedIPv4(lower) {
+    // IPv4-mapped: ::ffff:a.b.c.d (most common transition form)
+    if (lower.startsWith('::ffff:')) {
+        return lower.slice(7);
+    }
+    // For NAT64, 6to4, and Teredo we need to fully expand the address
+    const expanded = expandIPv6(lower);
+    if (expanded === null)
+        return ''; // fail closed on invalid IPv6
+    const groups = expanded.split(':');
+    if (groups.length !== 8)
+        return ''; // fail closed
+    // NAT64 well-known prefix: 64:ff9b::/96
+    // Expanded form: 0064:ff9b:0000:0000:0000:0000:wwxx:yyzz → IPv4 = ww.xx.yy.zz
+    if (groups[0] === '0064' && groups[1] === 'ff9b' &&
+        groups[2] === '0000' && groups[3] === '0000' &&
+        groups[4] === '0000' && groups[5] === '0000') {
+        return hexToIPv4(groups[6], groups[7]);
+    }
+    // NAT64 local-use prefix: 64:ff9b:1::/48
+    // Expanded form: 0064:ff9b:0001:xxxx:xxxx:xxxx:wwxx:yyzz → IPv4 = ww.xx.yy.zz
+    if (groups[0] === '0064' && groups[1] === 'ff9b' && groups[2] === '0001') {
+        return hexToIPv4(groups[6], groups[7]);
+    }
+    // 6to4 prefix: 2002::/16
+    // Expanded form: 2002:aabb:ccdd:xxxx:xxxx:xxxx:xxxx:xxxx → IPv4 = aa.bb.cc.dd
+    if (groups[0] === '2002') {
+        return hexToIPv4(groups[1], groups[2]);
+    }
+    // Teredo prefix: 2001:0000::/32
+    // Expanded form: 2001:0000:...:...:...:...:~ww~xx:~yy~zz
+    // Client IPv4 is in the last 32 bits XOR'd with 0xFFFFFFFF
+    if (groups[0] === '2001' && groups[1] === '0000') {
+        const hiXored = (parseInt(groups[6], 16) ^ 0xffff).toString(16).padStart(4, '0');
+        const loXored = (parseInt(groups[7], 16) ^ 0xffff).toString(16).padStart(4, '0');
+        return hexToIPv4(hiXored, loXored);
+    }
+    return null; // not a known transition format
+}
+/**
+ * Validate a single IPv4 octet string: must be a plain decimal integer 0-255
+ * with no leading zeros, hex prefixes, or other non-standard forms.
+ * Returns false for any octet that doesn't round-trip cleanly.
+ */
+function isStrictDecimalOctet(part) {
+    if (!/^[0-9]+$/.test(part))
+        return false;
+    const n = parseInt(part, 10);
+    if (n < 0 || n > 255)
+        return false;
+    // Reject leading zeros (e.g. "0177" would be octal in some parsers)
+    if (String(n) !== part)
+        return false;
+    return true;
+}
+/**
+ * Returns true if the string looks like a legacy/non-standard IPv4 literal
+ * that should be treated as internal and blocked (fail closed).
+ * Catches octal (0177.0.0.1), hex (0xff.0.0.1), short (127.1),
+ * and packed decimal (2130706433) forms.
+ */
+function isUnsupportedIPv4Literal(ip) {
+    // Packed decimal: single integer with no dots
+    if (/^[0-9]+$/.test(ip))
+        return true;
+    const parts = ip.split('.');
+    // Must be exactly 4 dotted parts
+    if (parts.length !== 4)
+        return true;
+    // Each part must be a strict decimal octet
+    if (!parts.every(isStrictDecimalOctet))
+        return true;
+    return false;
+}
+/**
+ * Check whether an IP address string is internal/private/loopback.
+ */
+function isInternalIP(ip) {
+    // Reject non-standard IPv4 literals before any range checks (fail closed)
+    if (!ip.includes(':') && isUnsupportedIPv4Literal(ip))
+        return true;
+    // IPv4
+    if (/^127\./.test(ip))
+        return true;
+    if (/^10\./.test(ip))
+        return true;
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip))
+        return true;
+    if (/^192\.168\./.test(ip))
+        return true;
+    if (/^169\.254\./.test(ip))
+        return true;
+    if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip))
+        return true;
+    if (ip === '0.0.0.0')
+        return true;
+    // IPv6
+    const lower = ip.toLowerCase();
+    if (lower === '::1')
+        return true;
+    if (lower.startsWith('fe80:'))
+        return true; // link-local
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true; // ULA
+    if (lower.startsWith('ff'))
+        return true; // multicast (ff00::/8)
+    // IPv6 transition addresses: NAT64, 6to4, Teredo, IPv4-mapped
+    const embedded = extractEmbeddedIPv4(lower);
+    if (embedded !== null) {
+        if (embedded === '')
+            return true; // parse error — fail closed
+        return isInternalIP(embedded);
+    }
+    return false;
+}
+/**
+ * Check whether a URL targets a loopback or private/internal network address.
+ * Synchronous hostname-based check. Used to prevent SSRF attacks.
+ */
+export function isInternalUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        // Fail closed: treat unparseable URLs as internal/blocked
+        return true;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    // Direct hostname checks
+    // Note: URL.hostname strips IPv6 brackets, so [::1] becomes ::1
+    if (hostname === 'localhost')
+        return true;
+    // Check if hostname is an IP literal
+    if (isInternalIP(hostname))
+        return true;
+    // .local, .internal, .localhost TLDs
+    if (hostname.endsWith('.local') || hostname.endsWith('.internal') || hostname.endsWith('.localhost')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Validate upload file paths immediately before use — rejects symlinks,
+ * missing files, and non-regular files to prevent TOCTOU path-swap attacks.
+ */
+export async function assertSafeUploadPaths(paths) {
+    for (const filePath of paths) {
+        let stat;
+        try {
+            stat = await lstat(filePath);
+        }
+        catch {
+            throw new Error(`Upload path does not exist or is inaccessible: "${filePath}".`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Upload path is a symbolic link: "${filePath}".`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`Upload path is not a regular file: "${filePath}".`);
+        }
+    }
+}
+/**
+ * Async version that also resolves DNS to catch rebinding attacks
+ * where a public hostname resolves to an internal IP.
+ */
+export async function isInternalUrlResolved(url, lookupFn = lookup) {
+    // First do the fast synchronous check
+    if (isInternalUrl(url))
+        return true;
+    // Then resolve DNS to catch rebinding
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return true;
+    }
+    try {
+        const { address } = await lookupFn(parsed.hostname);
+        if (isInternalIP(address))
+            return true;
+    }
+    catch {
+        // DNS resolution failed — fail closed
+        return true;
+    }
+    return false;
+}

package/dist/browser/snapshot/ai-snapshot.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotResult, SnapshotOptions } from '../types.js';
+/**
+ * Take an AI-readable snapshot using Playwright's _snapshotForAI.
+ * This is the primary snapshot method — uses Playwright's built-in AI mode.
+ */
+export declare function snapshotAi(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    maxChars?: number;
+    timeoutMs?: number;
+    options?: SnapshotOptions;
+}): Promise<SnapshotResult>;

package/dist/browser/snapshot/ai-snapshot.js

@@ -0,0 +1,47 @@
+import { getPageForTargetId, ensurePageState, storeRoleRefsForTarget, normalizeTimeoutMs } from '../connection.js';
+import { buildRoleSnapshotFromAiSnapshot, getRoleSnapshotStats } from './ref-map.js';
+/**
+ * Take an AI-readable snapshot using Playwright's _snapshotForAI.
+ * This is the primary snapshot method — uses Playwright's built-in AI mode.
+ */
+export async function snapshotAi(opts) {
+    const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+    ensurePageState(page);
+    const maybe = page;
+    if (!maybe._snapshotForAI) {
+        throw new Error('Playwright _snapshotForAI is not available. Upgrade playwright-core to >= 1.50.');
+    }
+    const sourceUrl = page.url();
+    const result = await maybe._snapshotForAI({
+        timeout: normalizeTimeoutMs(opts.timeoutMs, 5000, 60000),
+        track: 'response',
+    });
+    let snapshot = String(result?.full ?? '');
+    const maxChars = opts.maxChars;
+    const limit = typeof maxChars === 'number' && Number.isFinite(maxChars) && maxChars > 0
+        ? Math.floor(maxChars) : undefined;
+    if (limit && snapshot.length > limit) {
+        const lastNewline = snapshot.lastIndexOf('\n', limit);
+        const cutoff = lastNewline > 0 ? lastNewline : limit;
+        snapshot = `${snapshot.slice(0, cutoff)}\n\n[...TRUNCATED - page too large]`;
+    }
+    const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
+    storeRoleRefsForTarget({
+        page,
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+        refs: built.refs,
+        mode: 'aria',
+    });
+    return {
+        snapshot: built.snapshot,
+        refs: built.refs,
+        stats: getRoleSnapshotStats(built.snapshot, built.refs),
+        untrusted: true,
+        contentMeta: {
+            sourceUrl,
+            contentType: 'browser-snapshot',
+            capturedAt: new Date().toISOString(),
+        },
+    };
+}

package/dist/browser/snapshot/aria-snapshot.d.ts

@@ -0,0 +1,26 @@
+import type { SnapshotResult, AriaSnapshotResult } from '../types.js';
+/**
+ * Take a role-based snapshot using Playwright's ariaSnapshot().
+ * This produces a tree with ref IDs that can be targeted by actions.
+ */
+export declare function snapshotRole(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    selector?: string;
+    frameSelector?: string;
+    refsMode?: 'role' | 'aria';
+    timeoutMs?: number;
+    options?: {
+        interactive?: boolean;
+        compact?: boolean;
+        maxDepth?: number;
+    };
+}): Promise<SnapshotResult>;
+/**
+ * Take a raw ARIA accessibility tree snapshot via CDP.
+ */
+export declare function snapshotAria(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    limit?: number;
+}): Promise<AriaSnapshotResult>;

package/dist/browser/snapshot/aria-snapshot.js

@@ -0,0 +1,121 @@
+import { getPageForTargetId, ensurePageState, storeRoleRefsForTarget, normalizeTimeoutMs } from '../connection.js';
+import { buildRoleSnapshotFromAriaSnapshot, getRoleSnapshotStats, } from './ref-map.js';
+/**
+ * Take a role-based snapshot using Playwright's ariaSnapshot().
+ * This produces a tree with ref IDs that can be targeted by actions.
+ */
+export async function snapshotRole(opts) {
+    const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+    ensurePageState(page);
+    const sourceUrl = page.url();
+    const frameSelector = opts.frameSelector?.trim() || '';
+    const selector = opts.selector?.trim() || '';
+    const locator = frameSelector
+        ? (selector
+            ? page.frameLocator(frameSelector).locator(selector)
+            : page.frameLocator(frameSelector).locator(':root'))
+        : (selector
+            ? page.locator(selector)
+            : page.locator(':root'));
+    const ariaSnapshot = await locator.ariaSnapshot({ timeout: normalizeTimeoutMs(opts.timeoutMs, 5000) });
+    const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ''), opts.options);
+    storeRoleRefsForTarget({
+        page,
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+        refs: built.refs,
+        frameSelector: frameSelector || undefined,
+        mode: opts.refsMode ?? 'role',
+    });
+    return {
+        snapshot: built.snapshot,
+        refs: built.refs,
+        stats: getRoleSnapshotStats(built.snapshot, built.refs),
+        untrusted: true,
+        contentMeta: {
+            sourceUrl,
+            contentType: 'browser-snapshot',
+            capturedAt: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Take a raw ARIA accessibility tree snapshot via CDP.
+ */
+export async function snapshotAria(opts) {
+    const limit = Math.max(1, Math.min(2000, Math.floor(opts.limit ?? 500)));
+    const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+    ensurePageState(page);
+    const sourceUrl = page.url();
+    const session = await page.context().newCDPSession(page);
+    try {
+        await session.send('Accessibility.enable').catch(() => { });
+        const res = await session.send('Accessibility.getFullAXTree');
+        return {
+            nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit),
+            untrusted: true,
+            contentMeta: {
+                sourceUrl,
+                contentType: 'browser-aria-tree',
+                capturedAt: new Date().toISOString(),
+            },
+        };
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+function axValue(v) {
+    if (!v || typeof v !== 'object')
+        return '';
+    const value = v.value;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return '';
+}
+function formatAriaNodes(nodes, limit) {
+    const byId = new Map();
+    for (const n of nodes)
+        if (n.nodeId)
+            byId.set(n.nodeId, n);
+    const referenced = new Set();
+    for (const n of nodes)
+        for (const c of n.childIds ?? [])
+            referenced.add(c);
+    const root = nodes.find(n => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
+    if (!root?.nodeId)
+        return [];
+    const out = [];
+    const stack = [{ id: root.nodeId, depth: 0 }];
+    while (stack.length && out.length < limit) {
+        const popped = stack.pop();
+        if (!popped)
+            break;
+        const { id, depth } = popped;
+        const n = byId.get(id);
+        if (!n)
+            continue;
+        const role = axValue(n.role);
+        const name = axValue(n.name);
+        const value = axValue(n.value);
+        const description = axValue(n.description);
+        const ref = `ax${out.length + 1}`;
+        out.push({
+            ref,
+            role: role || 'unknown',
+            name: name || '',
+            ...(value ? { value } : {}),
+            ...(description ? { description } : {}),
+            ...(typeof n.backendDOMNodeId === 'number' ? { backendDOMNodeId: n.backendDOMNodeId } : {}),
+            depth,
+        });
+        const children = (n.childIds ?? []).filter((c) => byId.has(c));
+        for (let i = children.length - 1; i >= 0; i--) {
+            if (children[i])
+                stack.push({ id: children[i], depth: depth + 1 });
+        }
+    }
+    return out;
+}

package/dist/browser/snapshot/ref-map.d.ts

@@ -0,0 +1,31 @@
+import type { RoleRefs } from '../types.js';
+export declare const INTERACTIVE_ROLES: Set<string>;
+export declare const CONTENT_ROLES: Set<string>;
+export declare const STRUCTURAL_ROLES: Set<string>;
+export interface SnapshotBuildOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+}
+/**
+ * Build a role snapshot from Playwright's ariaSnapshot() output.
+ * Assigns ref IDs (e1, e2, ...) to interactive/content elements.
+ */
+export declare function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot: string, options?: SnapshotBuildOptions): {
+    snapshot: string;
+    refs: RoleRefs;
+};
+/**
+ * Build a role snapshot from Playwright's AI snapshot output.
+ * Preserves Playwright's own aria-ref ids (e.g. ref=e13).
+ */
+export declare function buildRoleSnapshotFromAiSnapshot(aiSnapshot: string, options?: SnapshotBuildOptions): {
+    snapshot: string;
+    refs: RoleRefs;
+};
+export declare function getRoleSnapshotStats(snapshot: string, refs: RoleRefs): {
+    lines: number;
+    chars: number;
+    refs: number;
+    interactive: number;
+};