@oscharko-dev/keiko 0.1.0-beta.0

package/dist/tools/browser/cdp-client.js

@@ -0,0 +1,218 @@
+// Thin CDP JSON-RPC client over the existing `ws` runtime dep (ADR-0017 D1, D4). NOT a
+// general-purpose CDP library: a hard-coded permit list gates `send` so a server bug cannot send
+// `Runtime.evaluate` or any cookie-reading method. Pending requests are correlated by an
+// incrementing integer `id`; the in-process id allocator is private so a CDP response cannot spoof
+// the id of a request it didn't trigger.
+import { WebSocket } from "ws";
+import { BrowserToolError } from "./errors.js";
+// ADR-0017 D4 — exact permit list. New methods require an ADR amendment, not a code-only patch.
+export const PERMITTED_CDP_METHODS = new Set([
+    "Target.createTarget",
+    "Target.attachToTarget",
+    "Target.closeTarget",
+    "Page.enable",
+    "Page.navigate",
+    "Page.stopLoading",
+    "Page.captureScreenshot",
+    "DOM.getDocument",
+    "DOM.getOuterHTML",
+    "Browser.getVersion",
+]);
+const DEFAULT_CDP_TIMEOUT_MS = 10_000;
+function isCdpFrame(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const rec = value;
+    return typeof rec.id === "number" || typeof rec.method === "string";
+}
+function parseCdpText(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return isCdpFrame(parsed) ? parsed : undefined;
+}
+function rawDataToText(data) {
+    if (typeof data === "string")
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString("utf8");
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString("utf8");
+    return Buffer.from(data).toString("utf8");
+}
+export class CdpClient {
+    socket;
+    timeoutMs;
+    pending = new Map();
+    listeners = new Set();
+    closeListeners = new Set();
+    nextId = 1;
+    connectPromise;
+    closed = false;
+    closeReason;
+    constructor(url, options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS;
+        const factory = options.socketFactory ?? ((target) => new WebSocket(target));
+        this.socket = factory(url);
+        this.socket.on("message", (data, isBinary) => {
+            this.handleMessage(data, isBinary);
+        });
+        this.socket.on("close", () => {
+            this.handleSocketClosed("chrome-disconnected");
+        });
+        this.socket.on("error", () => {
+            this.handleSocketClosed("chrome-disconnected");
+        });
+    }
+    connect() {
+        if (this.connectPromise !== undefined)
+            return this.connectPromise;
+        this.connectPromise = new Promise((resolve, reject) => {
+            if (this.socket.readyState === this.socket.OPEN) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => {
+                reject(new BrowserToolError("CDP_TIMEOUT", "CDP connection did not open in time."));
+            }, this.timeoutMs);
+            this.socket.once("open", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.socket.once("error", (err) => {
+                clearTimeout(timer);
+                reject(new BrowserToolError("CHROME_UNREACHABLE", `CDP connection failed: ${err.message}`));
+            });
+        });
+        return this.connectPromise;
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    onClose(listener) {
+        this.closeListeners.add(listener);
+        return () => {
+            this.closeListeners.delete(listener);
+        };
+    }
+    async send(method, params = {}, sessionId) {
+        if (!PERMITTED_CDP_METHODS.has(method)) {
+            throw new BrowserToolError("CDP_METHOD_FORBIDDEN", "The requested CDP method is not permitted.");
+        }
+        if (this.closed) {
+            throw new BrowserToolError("TARGET_CLOSED", "CDP connection is closed.");
+        }
+        await this.connect();
+        const id = this.nextId;
+        this.nextId += 1;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new BrowserToolError("CDP_TIMEOUT", "CDP response did not arrive in time."));
+            }, this.timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    resolve(value);
+                },
+                reject,
+                timer,
+            });
+            const frame = sessionId === undefined ? { id, method, params } : { id, method, params, sessionId };
+            try {
+                this.socket.send(JSON.stringify(frame));
+            }
+            catch (err) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                const message = err instanceof Error ? err.message : "send failed";
+                reject(new BrowserToolError("CHROME_UNREACHABLE", `CDP send failed: ${message}`));
+            }
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.handleSocketClosed("explicit");
+        try {
+            this.socket.close();
+        }
+        catch {
+            // The underlying socket may already be torn down; treat as idempotent.
+        }
+    }
+    isClosed() {
+        return this.closed;
+    }
+    closeCause() {
+        return this.closeReason;
+    }
+    handleMessage(data, isBinary) {
+        if (isBinary)
+            return;
+        const parsed = parseCdpText(rawDataToText(data));
+        if (parsed === undefined)
+            return;
+        if ("id" in parsed && typeof parsed.id === "number") {
+            this.resolvePending(parsed);
+            return;
+        }
+        if ("method" in parsed && typeof parsed.method === "string") {
+            this.dispatchEvent(parsed);
+        }
+    }
+    dispatchEvent(frame) {
+        const listenerEvent = {
+            method: frame.method,
+            params: frame.params ?? {},
+            ...(typeof frame.sessionId === "string" ? { sessionId: frame.sessionId } : {}),
+        };
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(listenerEvent);
+            }
+            catch {
+                // A listener throwing must not stop event dispatch to other subscribers.
+            }
+        }
+    }
+    resolvePending(frame) {
+        const pending = this.pending.get(frame.id);
+        if (pending === undefined)
+            return;
+        this.pending.delete(frame.id);
+        clearTimeout(pending.timer);
+        if (frame.error !== undefined) {
+            pending.reject(new BrowserToolError("CDP_METHOD_FORBIDDEN", 
+            // Static message — the raw Chrome error may contain paths or session IDs.
+            "Chrome rejected a CDP method."));
+            return;
+        }
+        pending.resolve(frame.result ?? {});
+    }
+    handleSocketClosed(reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeReason = reason;
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new BrowserToolError("TARGET_CLOSED", "CDP connection closed."));
+        }
+        this.pending.clear();
+        for (const listener of [...this.closeListeners]) {
+            try {
+                listener(reason);
+            }
+            catch {
+                // A close listener throwing must not stop cleanup notifications.
+            }
+        }
+    }
+}

package/dist/tools/browser/errors.d.ts

@@ -0,0 +1,25 @@
+export declare const BROWSER_ERROR_CODES: {
+    readonly CHROME_UNREACHABLE: "CHROME_UNREACHABLE";
+    readonly CHROME_VERSION_MISMATCH: "CHROME_VERSION_MISMATCH";
+    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+    readonly SESSION_LIMIT_EXCEEDED: "SESSION_LIMIT_EXCEEDED";
+    readonly ORIGIN_NOT_ALLOWED: "ORIGIN_NOT_ALLOWED";
+    readonly SCHEME_NOT_ALLOWED: "SCHEME_NOT_ALLOWED";
+    readonly TARGET_CLOSED: "TARGET_CLOSED";
+    readonly CDP_TIMEOUT: "CDP_TIMEOUT";
+    readonly SCREENSHOT_TOO_LARGE: "SCREENSHOT_TOO_LARGE";
+    readonly CONTENT_TOO_LARGE: "CONTENT_TOO_LARGE";
+    readonly CDP_METHOD_FORBIDDEN: "CDP_METHOD_FORBIDDEN";
+    readonly CDP_TRANSPORT_REFUSED: "CDP_TRANSPORT_REFUSED";
+    readonly BAD_PORT: "BAD_PORT";
+    readonly BAD_URL: "BAD_URL";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly NO_PENDING_SCREENSHOT: "NO_PENDING_SCREENSHOT";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+};
+export type BrowserErrorCode = (typeof BROWSER_ERROR_CODES)[keyof typeof BROWSER_ERROR_CODES];
+export declare class BrowserToolError extends Error {
+    readonly code: BrowserErrorCode;
+    readonly status: number;
+    constructor(code: BrowserErrorCode, message: string);
+}

package/dist/tools/browser/errors.js

@@ -0,0 +1,55 @@
+// Typed failure modes for the browser tool (ADR-0017 D10). Callers switch on `code`, never on
+// message — messages are static strings that never leak filesystem paths or raw Chrome diagnostics
+// to the UI.
+export const BROWSER_ERROR_CODES = {
+    CHROME_UNREACHABLE: "CHROME_UNREACHABLE",
+    CHROME_VERSION_MISMATCH: "CHROME_VERSION_MISMATCH",
+    SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+    SESSION_LIMIT_EXCEEDED: "SESSION_LIMIT_EXCEEDED",
+    ORIGIN_NOT_ALLOWED: "ORIGIN_NOT_ALLOWED",
+    SCHEME_NOT_ALLOWED: "SCHEME_NOT_ALLOWED",
+    TARGET_CLOSED: "TARGET_CLOSED",
+    CDP_TIMEOUT: "CDP_TIMEOUT",
+    SCREENSHOT_TOO_LARGE: "SCREENSHOT_TOO_LARGE",
+    CONTENT_TOO_LARGE: "CONTENT_TOO_LARGE",
+    CDP_METHOD_FORBIDDEN: "CDP_METHOD_FORBIDDEN",
+    CDP_TRANSPORT_REFUSED: "CDP_TRANSPORT_REFUSED",
+    BAD_PORT: "BAD_PORT",
+    BAD_URL: "BAD_URL",
+    BAD_REQUEST: "BAD_REQUEST",
+    NO_PENDING_SCREENSHOT: "NO_PENDING_SCREENSHOT",
+    PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+};
+// HTTP status mapping per ADR-0017 D10. The two pure-input codes (BAD_PORT, BAD_URL, BAD_REQUEST)
+// always map to 400; SESSION_LIMIT_EXCEEDED to 429; ORIGIN_NOT_ALLOWED to 403; SCHEME_NOT_ALLOWED
+// to 400; TARGET_CLOSED to 410; CDP_TIMEOUT to 504; size-cap codes to 413; FORBIDDEN to 500
+// (server bug); SESSION_NOT_FOUND to 404; CHROME_UNREACHABLE to 503; CHROME_VERSION_MISMATCH to 400.
+const STATUS_MAP = {
+    CHROME_UNREACHABLE: 503,
+    CHROME_VERSION_MISMATCH: 400,
+    SESSION_NOT_FOUND: 404,
+    SESSION_LIMIT_EXCEEDED: 429,
+    ORIGIN_NOT_ALLOWED: 403,
+    SCHEME_NOT_ALLOWED: 400,
+    TARGET_CLOSED: 410,
+    CDP_TIMEOUT: 504,
+    SCREENSHOT_TOO_LARGE: 413,
+    CONTENT_TOO_LARGE: 413,
+    CDP_METHOD_FORBIDDEN: 500,
+    CDP_TRANSPORT_REFUSED: 503,
+    BAD_PORT: 400,
+    BAD_URL: 400,
+    BAD_REQUEST: 400,
+    NO_PENDING_SCREENSHOT: 409,
+    PAYLOAD_TOO_LARGE: 413,
+};
+export class BrowserToolError extends Error {
+    code;
+    status;
+    constructor(code, message) {
+        super(message);
+        this.name = "BrowserToolError";
+        this.code = code;
+        this.status = STATUS_MAP[code];
+    }
+}

package/dist/tools/browser/index.d.ts

@@ -0,0 +1,5 @@
+export { BROWSER_ERROR_CODES, BrowserToolError, type BrowserErrorCode } from "./errors.js";
+export { isLoopbackHost, isLoopbackUrl, normalizeCdpPort, normalizeNavigateUrl, } from "./validators.js";
+export type { BrowserContentResult, BrowserNavigateResult, BrowserScreenshotPersisted, BrowserScreenshotPreview, BrowserScreenshotResult, BrowserSessionMeta, BrowserSessionStatus, BrowserViewportPx, CdpReachability, NormalizedNavigateUrl, } from "./types.js";
+export { CdpClient, PERMITTED_CDP_METHODS, type CdpCloseListener, type CdpClientOptions, type CdpEventListener, } from "./cdp-client.js";
+export { createBrowserSessionManager, type BrowserEventEmitter, type BrowserEventEnvelope, type BrowserEventKind, type BrowserSessionManager, type BrowserSessionManagerOptions, } from "./session.js";

package/dist/tools/browser/index.js

@@ -0,0 +1,6 @@
+// Browser tool barrel — re-exports the public surface that BFF handlers and tests compose.
+// ADR-0017. No runtime side effects.
+export { BROWSER_ERROR_CODES, BrowserToolError } from "./errors.js";
+export { isLoopbackHost, isLoopbackUrl, normalizeCdpPort, normalizeNavigateUrl, } from "./validators.js";
+export { CdpClient, PERMITTED_CDP_METHODS, } from "./cdp-client.js";
+export { createBrowserSessionManager, } from "./session.js";

package/dist/tools/browser/session.d.ts

@@ -0,0 +1,44 @@
+import { CdpClient, type CdpClientOptions } from "./cdp-client.js";
+import type { BrowserContentResult, BrowserNavigateResult, BrowserScreenshotResult, BrowserSessionMeta, CdpReachability } from "./types.js";
+import { type SideFileWriterOptions } from "../../audit/side-file.js";
+import type { EvidenceStore } from "../../audit/store.js";
+export type BrowserEventKind = "session-opened" | "navigated" | "screenshot-captured" | "page-content-captured" | "session-closed" | "trust-warning" | "error";
+export interface BrowserEventEnvelope {
+    readonly schemaVersion: "1";
+    readonly type: `browser:${BrowserEventKind}`;
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly seq: number;
+    readonly ts: number;
+    readonly kind: BrowserEventKind;
+    readonly sessionId: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+export type BrowserEventEmitter = (event: BrowserEventEnvelope) => void;
+export interface BrowserSessionManagerOptions {
+    readonly evidenceDir: string;
+    readonly evidenceStore?: EvidenceStore | undefined;
+    readonly redactor?: (value: unknown) => unknown;
+    readonly cdpClientFactory?: (url: string, opts: CdpClientOptions) => CdpClient;
+    readonly fetchVersion?: (url: string) => Promise<unknown>;
+    readonly sideFileOptions?: SideFileWriterOptions;
+    readonly idleTtlMs?: number;
+    readonly nowMs?: () => number;
+}
+export interface BrowserSessionManager {
+    readonly checkStatus: (cdpPort: number) => Promise<CdpReachability>;
+    readonly openSession: (cdpPort: number) => Promise<BrowserSessionMeta>;
+    readonly closeSession: (sessionId: string) => Promise<void>;
+    readonly navigate: (sessionId: string, url: string) => Promise<BrowserNavigateResult>;
+    readonly screenshot: (sessionId: string) => Promise<BrowserScreenshotResult>;
+    readonly applyScreenshot: (sessionId: string, captureSeq: number) => Promise<BrowserScreenshotResult>;
+    readonly content: (sessionId: string) => Promise<BrowserContentResult>;
+    readonly listSessionIds: () => readonly string[];
+    readonly hasSession: (sessionId: string) => boolean;
+    readonly dispose: () => Promise<void>;
+    readonly subscribe: (sessionId: string, listener: BrowserEventEmitter) => () => void;
+    readonly counterAccessor: () => {
+        readonly navigations: number;
+    };
+}
+export declare function createBrowserSessionManager(options: BrowserSessionManagerOptions): BrowserSessionManager;