@harness-fe/runtime 3.0.1 → 3.1.0

package/src/storagePatch.ts

@@ -0,0 +1,213 @@
+/**
+ * Storage monkey-patch — captures localStorage / sessionStorage / cookie
+ * mutations so agents can answer "who deleted my token?".
+ *
+ * Safety contract (mirrors fetchPatch / wsPatch):
+ *  1. Identity-preserving: replacements use Object.defineProperty so
+ *     `localStorage.setItem` keeps its prototype membership. Cookie wrapping
+ *     uses a `document` getter/setter pair on the prototype.
+ *  2. Error-isolated: capture failures swallowed; never propagate to callers.
+ *  3. No timing or value change: every wrapper calls the original synchronously
+ *     and returns its result.
+ *  4. crossTab events captured via the native `storage` event (no initiator —
+ *     the mutation happened in another tab so the stack is meaningless here).
+ *
+ * Idempotent. Returns a dispose function.
+ */
+
+import type { StorageEntry } from '@harness-fe/protocol';
+import { captureInitiator } from './initiator.js';
+
+const PATCHED_FLAG = '__hfeStoragePatched';
+
+export interface StoragePatchOptions {
+    onEntry: (entry: StorageEntry) => void;
+    /** Per-value byte cap. Default 4 KB — captures small tokens, drops giant blobs. */
+    valueCap?: number;
+}
+
+const DEFAULT_VALUE_CAP = 4 * 1024;
+
+export function installStoragePatch(opts: StoragePatchOptions): () => void {
+    if (typeof window === 'undefined') return () => {};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((window as any)[PATCHED_FLAG]) return () => {};
+
+    const valueCap = opts.valueCap ?? DEFAULT_VALUE_CAP;
+    const emit = (entry: StorageEntry): void => {
+        try {
+            opts.onEntry(entry);
+        } catch {
+            /* swallow */
+        }
+    };
+
+    const disposers: Array<() => void> = [];
+
+    // Patch each storage instance directly — own properties shadow the
+    // prototype regardless of how the engine implements them. This works
+    // uniformly across real browsers, happy-dom, jsdom, and Electron.
+    try {
+        disposers.push(patchStorageInstance(window.localStorage, 'local', valueCap, emit));
+    } catch { /* localStorage may be inaccessible (private mode, etc.) */ }
+    try {
+        disposers.push(patchStorageInstance(window.sessionStorage, 'session', valueCap, emit));
+    } catch { /* ignore */ }
+
+    if (typeof document !== 'undefined') {
+        const cookieDispose = patchCookie(valueCap, emit);
+        if (cookieDispose) disposers.push(cookieDispose);
+    }
+
+    // Cross-tab storage events.
+    const onStorageEvent = (ev: StorageEvent): void => {
+        const which: StorageEntry['which'] = ev.storageArea === window.sessionStorage ? 'session' : 'local';
+        const op: StorageEntry['op'] = ev.key === null ? 'clear' : ev.newValue === null ? 'remove' : 'set';
+        emit({
+            ts: Date.now(),
+            op,
+            which,
+            key: ev.key ?? undefined,
+            value: ev.newValue !== null ? clip(ev.newValue, valueCap) : undefined,
+            crossTab: true,
+        });
+    };
+    window.addEventListener('storage', onStorageEvent);
+    disposers.push(() => window.removeEventListener('storage', onStorageEvent));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window as any)[PATCHED_FLAG] = true;
+
+    return () => {
+        for (const d of disposers) {
+            try {
+                d();
+            } catch {
+                /* ignore */
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        delete (window as any)[PATCHED_FLAG];
+    };
+}
+
+/**
+ * Patch Storage.prototype.setItem / removeItem / clear. Both localStorage and
+ * sessionStorage share the same prototype, so one patch covers both — we
+ * disambiguate at call time via `this === window.sessionStorage`.
+ */
+function patchStorageInstance(
+    storage: Storage,
+    kind: StorageEntry['which'],
+    valueCap: number,
+    emit: (entry: StorageEntry) => void,
+): () => void {
+    const origSet = storage.setItem.bind(storage);
+    const origRemove = storage.removeItem.bind(storage);
+    const origClear = storage.clear.bind(storage);
+
+    Object.defineProperty(storage, 'setItem', {
+        configurable: true, writable: true,
+        value: (key: string, value: string) => {
+            emit({ ts: Date.now(), op: 'set', which: kind, key, value: clip(value, valueCap), initiator: captureInitiator() });
+            origSet(key, value);
+        },
+    });
+    Object.defineProperty(storage, 'removeItem', {
+        configurable: true, writable: true,
+        value: (key: string) => {
+            emit({ ts: Date.now(), op: 'remove', which: kind, key, initiator: captureInitiator() });
+            origRemove(key);
+        },
+    });
+    Object.defineProperty(storage, 'clear', {
+        configurable: true, writable: true,
+        value: () => {
+            emit({ ts: Date.now(), op: 'clear', which: kind, initiator: captureInitiator() });
+            origClear();
+        },
+    });
+    return () => {
+        // Restore by replacing the own properties with thin shims that
+        // forward to the captured originals. `delete` doesn't reliably
+        // expose the prototype method in every engine (happy-dom in
+        // particular), so this is the safer reset.
+        try {
+            Object.defineProperty(storage, 'setItem', {
+                configurable: true, writable: true,
+                value: (k: string, v: string) => origSet(k, v),
+            });
+            Object.defineProperty(storage, 'removeItem', {
+                configurable: true, writable: true,
+                value: (k: string) => origRemove(k),
+            });
+            Object.defineProperty(storage, 'clear', {
+                configurable: true, writable: true,
+                value: () => origClear(),
+            });
+        } catch { /* ignore */ }
+    };
+}
+
+function patchCookie(
+    valueCap: number,
+    emit: (entry: StorageEntry) => void,
+): (() => void) | undefined {
+    const descriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'cookie');
+    if (!descriptor || !descriptor.set || !descriptor.get) return undefined;
+    const origSet = descriptor.set;
+    const origGet = descriptor.get;
+
+    Object.defineProperty(Document.prototype, 'cookie', {
+        configurable: true,
+        get(this: Document) {
+            return origGet.call(this);
+        },
+        set(this: Document, val: string) {
+            const initiator = captureInitiator();
+            const { key, value, removed } = parseCookieAssignment(val);
+            emit({
+                ts: Date.now(),
+                op: removed ? 'remove' : 'set',
+                which: 'cookie',
+                key,
+                value: removed ? undefined : value !== undefined ? clip(value, valueCap) : undefined,
+                initiator,
+            });
+            return origSet.call(this, val);
+        },
+    });
+
+    return () => {
+        Object.defineProperty(Document.prototype, 'cookie', descriptor);
+    };
+}
+
+/**
+ * Cookie writes look like "key=value; Path=/; Expires=...; Max-Age=0".
+ * Treat Max-Age=0 or any past Expires as removal. Anything else is set.
+ */
+function parseCookieAssignment(raw: string): { key?: string; value?: string; removed: boolean } {
+    const parts = raw.split(';');
+    const head = (parts[0] ?? '').trim();
+    const eq = head.indexOf('=');
+    const key = eq >= 0 ? head.slice(0, eq) : head;
+    const value = eq >= 0 ? head.slice(eq + 1) : undefined;
+    let removed = false;
+    for (let i = 1; i < parts.length; i++) {
+        const seg = parts[i].trim();
+        const lower = seg.toLowerCase();
+        if (lower === 'max-age=0' || lower === 'max-age=-1') removed = true;
+        if (lower.startsWith('expires=')) {
+            const date = new Date(seg.slice('expires='.length).trim());
+            if (!Number.isNaN(date.getTime()) && date.getTime() <= Date.now()) {
+                removed = true;
+            }
+        }
+    }
+    return { key: key || undefined, value, removed };
+}
+
+function clip(s: string, cap: number): string {
+    return s.length <= cap ? s : `${s.slice(0, cap)}…[+${s.length - cap}B]`;
+}

package/src/wsPatch.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installWsPatch } from './wsPatch.js';
+import type { WsEntry } from '@harness-fe/protocol';
+
+let entries: WsEntry[];
+let dispose: () => void;
+
+/**
+ * happy-dom's WebSocket attempts real network on construction. We replace it
+ * with a controllable fake so the patch can be exercised in isolation.
+ */
+class FakeWebSocket extends EventTarget {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly url: string;
+    readonly protocols?: string | string[];
+    readyState = FakeWebSocket.CONNECTING;
+    sent: Array<unknown> = [];
+
+    constructor(url: string | URL, protocols?: string | string[]) {
+        super();
+        this.url = typeof url === 'string' ? url : url.toString();
+        this.protocols = protocols;
+    }
+
+    send(data: unknown): void {
+        this.sent.push(data);
+    }
+
+    close(_code?: number, _reason?: string): void {
+        this.readyState = FakeWebSocket.CLOSED;
+    }
+
+    // Test helpers — dispatch synthetic events.
+    fireMessage(data: unknown): void {
+        // happy-dom MessageEvent ctor accepts a `data` init.
+        this.dispatchEvent(new MessageEvent('message', { data: data as string }));
+    }
+
+    fireClose(code = 1000, reason = '', wasClean = true): void {
+        this.dispatchEvent(new CloseEvent('close', { code, reason, wasClean }));
+    }
+}
+
+let originalWs: typeof WebSocket;
+
+beforeEach(() => {
+    entries = [];
+    originalWs = window.WebSocket;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window as any).WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+});
+
+afterEach(() => {
+    dispose?.();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window as any).WebSocket = originalWs;
+});
+
+describe('installWsPatch', () => {
+    it('emits open on construction with url + protocols', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        new window.WebSocket('wss://example.test/ws', ['v1', 'v2']);
+        const open = entries.find((e) => e.phase === 'open')!;
+        expect(open).toBeDefined();
+        expect(open.url).toBe('wss://example.test/ws');
+        expect(open.protocols).toEqual(['v1', 'v2']);
+        expect(open.initiator).toBeDefined();
+    });
+
+    it('captures send with parsed JSON and initiator stack', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        const ws = new window.WebSocket('wss://x/');
+        ws.send(JSON.stringify({ kind: 'ping', n: 1 }));
+        const send = entries.find((e) => e.phase === 'send')!;
+        expect(send).toBeDefined();
+        expect(send.payload).toEqual({ kind: 'ping', n: 1 });
+        expect(send.initiator).toBeDefined();
+    });
+
+    it('captures recv frames, parses JSON, keeps raw text otherwise', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        const ws = new window.WebSocket('wss://x/') as unknown as FakeWebSocket;
+        ws.fireMessage(JSON.stringify({ notifyType: 'kick' }));
+        ws.fireMessage('hello');
+        const recvs = entries.filter((e) => e.phase === 'recv');
+        expect(recvs).toHaveLength(2);
+        expect(recvs[0].payload).toEqual({ notifyType: 'kick' });
+        expect(recvs[1].payload).toBe('hello');
+    });
+
+    it('captures close with code + reason', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        const ws = new window.WebSocket('wss://x/') as unknown as FakeWebSocket;
+        ws.fireClose(4001, 'kicked', false);
+        const close = entries.find((e) => e.phase === 'close')!;
+        expect(close.code).toBe(4001);
+        expect(close.reason).toBe('kicked');
+        expect(close.wasClean).toBe(false);
+    });
+
+    it('open / send / recv / close share the same id', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        const ws = new window.WebSocket('wss://x/') as unknown as FakeWebSocket;
+        ws.send('hi');
+        ws.fireMessage('there');
+        ws.fireClose();
+        const ids = new Set(entries.map((e) => e.id));
+        expect(ids.size).toBe(1);
+    });
+
+    it('truncates text payload above bodyCap', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e), bodyCap: 10 });
+        const ws = new window.WebSocket('wss://x/');
+        ws.send('x'.repeat(50));
+        const send = entries.find((e) => e.phase === 'send')!;
+        expect(send.payloadTruncated).toBe(true);
+        expect((send.payload as string).length).toBeLessThanOrEqual(10);
+    });
+
+    it('skips denylisted URLs (no entries emitted)', () => {
+        dispose = installWsPatch({
+            onEntry: (e) => entries.push(e),
+            denylist: [/test\.skip/],
+        });
+        new window.WebSocket('ws://test.skip/x');
+        expect(entries).toHaveLength(0);
+    });
+
+    it('records binary payloads as size markers', () => {
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        const ws = new window.WebSocket('wss://x/');
+        ws.send(new Uint8Array(32));
+        const send = entries.find((e) => e.phase === 'send')!;
+        expect(typeof send.payload).toBe('string');
+        expect(send.payload as string).toContain('[binary');
+        expect(send.payload as string).toContain('32');
+    });
+
+    it('dispose restores window.WebSocket', () => {
+        const before = window.WebSocket;
+        dispose = installWsPatch({ onEntry: (e) => entries.push(e) });
+        expect(window.WebSocket).not.toBe(before);
+        dispose();
+        expect(window.WebSocket).toBe(before);
+    });
+});

package/src/wsPatch.ts

@@ -0,0 +1,198 @@
+/**
+ * WebSocket monkey-patch — captures open / send / recv / close frames so
+ * agents can see long-lived push channels (IM, presence, sync, kick-out).
+ *
+ * Safety contract (mirrors fetchPatch):
+ *  1. Identity-preserving: replacement is a constructor with the same name,
+ *     prototype, and CONNECTING/OPEN/CLOSING/CLOSED static fields. Existing
+ *     `instanceof WebSocket` checks still pass because we extend the original.
+ *  2. Error-isolated: capture failures swallowed via safeEmit.
+ *  3. No timing or value change: pass-through to native WebSocket; we only
+ *     observe events and call sites. The original Promise / data flow is
+ *     untouched.
+ *  4. Bounded memory: frame payloads capped at BODY_CAP per send/recv. Binary
+ *     frames record a `[binary Nb]` marker rather than the bytes.
+ *
+ * The patch is idempotent. Returns a dispose function that restores
+ * `window.WebSocket`.
+ */
+
+import type { WsEntry } from '@harness-fe/protocol';
+import { captureInitiator } from './initiator.js';
+
+const DEFAULT_BODY_CAP = 256 * 1024;
+const PATCHED_FLAG = '__hfeWsPatched';
+
+export interface WsPatchOptions {
+    onEntry: (entry: WsEntry) => void;
+    bodyCap?: number;
+    /** URL patterns to skip entirely. Default skips daemon traffic. */
+    denylist?: RegExp[];
+}
+
+const DEFAULT_DENYLIST: RegExp[] = [/\/__hfe\//, /sockjs-node/];
+
+export function installWsPatch(opts: WsPatchOptions): () => void {
+    if (typeof window === 'undefined' || typeof window.WebSocket !== 'function') {
+        return () => {};
+    }
+    const OriginalWS = window.WebSocket;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((OriginalWS as any)[PATCHED_FLAG]) return () => {};
+
+    const bodyCap = opts.bodyCap ?? DEFAULT_BODY_CAP;
+    const denylist = opts.denylist ?? DEFAULT_DENYLIST;
+    const emit = (entry: WsEntry): void => {
+        try {
+            opts.onEntry(entry);
+        } catch {
+            /* swallow */
+        }
+    };
+
+    const Patched = function PatchedWebSocket(
+        this: WebSocket,
+        url: string | URL,
+        protocols?: string | string[],
+    ): WebSocket {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        const ws = protocols !== undefined
+            ? new OriginalWS(url, protocols)
+            : new OriginalWS(url);
+
+        if (denylist.some((re) => re.test(urlStr))) return ws;
+
+        const id = generateId();
+        const protoList = Array.isArray(protocols)
+            ? protocols
+            : typeof protocols === 'string'
+                ? [protocols]
+                : undefined;
+        const openInitiator = captureInitiator();
+
+        emit({
+            ts: Date.now(),
+            id,
+            phase: 'open',
+            url: urlStr,
+            protocols: protoList,
+            initiator: openInitiator,
+        });
+
+        ws.addEventListener('message', (ev: MessageEvent) => {
+            const { payload, truncated } = serializeFrame(ev.data, bodyCap);
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'recv',
+                url: urlStr,
+                payload,
+                payloadTruncated: truncated || undefined,
+            });
+        });
+
+        ws.addEventListener('close', (ev: CloseEvent) => {
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'close',
+                url: urlStr,
+                code: ev.code,
+                reason: ev.reason || undefined,
+                wasClean: ev.wasClean,
+            });
+        });
+
+        // Wrap `send` on this instance so we record outgoing payloads + caller.
+        const origSend = ws.send.bind(ws);
+        ws.send = function patchedSend(data: string | ArrayBufferLike | Blob | ArrayBufferView): void {
+            const initiator = captureInitiator();
+            const { payload, truncated } = serializeFrame(data, bodyCap);
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'send',
+                url: urlStr,
+                payload,
+                payloadTruncated: truncated || undefined,
+                initiator,
+            });
+            return origSend(data);
+        };
+
+        return ws;
+    } as unknown as typeof WebSocket;
+
+    // Preserve constructor surface so library detection still works.
+    Patched.prototype = OriginalWS.prototype;
+    for (const key of ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'] as const) {
+        try {
+            Object.defineProperty(Patched, key, {
+                value: OriginalWS[key],
+                writable: false,
+                configurable: true,
+            });
+        } catch {
+            /* readonly already — ignore */
+        }
+    }
+    try {
+        Object.defineProperty(Patched, 'name', { value: 'WebSocket' });
+    } catch {
+        /* ignore */
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (Patched as any)[PATCHED_FLAG] = true;
+
+    window.WebSocket = Patched;
+
+    return () => {
+        if (window.WebSocket === Patched) {
+            window.WebSocket = OriginalWS;
+        }
+    };
+}
+
+function generateId(): string {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    return `ws_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function serializeFrame(
+    data: unknown,
+    cap: number,
+): { payload?: unknown; truncated: boolean } {
+    if (typeof data === 'string') {
+        if (data.length <= cap) {
+            // Try JSON for structured payloads.
+            const parsed = tryJson(data);
+            return { payload: parsed !== undefined ? parsed : data, truncated: false };
+        }
+        return { payload: data.slice(0, cap), truncated: true };
+    }
+    if (data instanceof ArrayBuffer) {
+        return { payload: `[binary ArrayBuffer ${data.byteLength}B]`, truncated: false };
+    }
+    if (typeof Blob !== 'undefined' && data instanceof Blob) {
+        return { payload: `[binary Blob ${data.size}B]`, truncated: false };
+    }
+    if (ArrayBuffer.isView(data)) {
+        const view = data as ArrayBufferView;
+        return { payload: `[binary ${view.constructor.name} ${view.byteLength}B]`, truncated: false };
+    }
+    return { payload: undefined, truncated: false };
+}
+
+function tryJson(s: string): unknown {
+    const trimmed = s.trim();
+    if (!trimmed) return undefined;
+    const first = trimmed[0];
+    if (first !== '{' && first !== '[' && first !== '"') return undefined;
+    try {
+        return JSON.parse(trimmed);
+    } catch {
+        return undefined;
+    }
+}

package/src/xhrPatch.ts

@@ -19,6 +19,7 @@
  */
 
 import type { NetworkEntry } from '@harness-fe/protocol';
+import { captureInitiator } from './initiator.js';
 
 const DEFAULT_BODY_CAP = 256 * 1024;
 const PATCHED_FLAG = '__hfeXhrPatched';
@@ -113,6 +114,7 @@ export function installXhrPatch(opts: XhrPatchOptions): () => void {
         }
         meta.startedAt = performance.now();
         meta.startedTs = Date.now();
+        const initiator = captureInitiator();
 
         // Emit req eagerly with headers; body added on second emit after
         // serialization (mirrors fetchPatch behavior).
@@ -123,6 +125,7 @@ export function installXhrPatch(opts: XhrPatchOptions): () => void {
             method: meta.method,
             url: meta.url,
             requestHeaders: redactHeaders(meta.headers),
+            initiator,
         };
         emit(reqRecord);
         meta.reqEmitted = true;