wslog-proxy 0.0.0-stage → 0.1.1

package/dist/server/masking.js

@@ -0,0 +1,104 @@
+export const MASK = '***';
+const identity = { fields: [], text: (s) => s, url: (s) => redactUrlPassword(s) };
+/**
+ * Longest backslash run treated as JSON escaping. Each nesting level of
+ * JSON-in-a-string doubles it (1, 3, 7, 15, 31), so 31 covers five levels.
+ * Bounding it keeps masking linear: an unbounded run made it quadratic, and
+ * one 100 KB message stalled the proxy for seconds.
+ */
+const MAX_ESCAPE_RUN = 31;
+export function createMasker(fields) {
+    const keys = new Set(fields.map((f) => f.toLowerCase()).filter(Boolean));
+    if (keys.size === 0)
+        return identity;
+    const isMasked = (key) => keys.has(key.toLowerCase());
+    const alternation = [...keys].map(escapeRegExp).join('|');
+    // "token": "abc"   'token': 'abc'   "token": 123
+    const quotedPattern = new RegExp(`(["'](?:${alternation})["']\\s*:\\s*)("(?:[^"\\\\]|\\\\.)*"|'[^']*'|[^,}\\]\\s]+)`, 'gi');
+    // token=abc   token: abc
+    const plainPattern = new RegExp(`(\\b(?:${alternation})\\s*[=:]\\s*)([^\\s&,;"'}\\]]+)`, 'gi');
+    // \"token\":\"abc\"   JSON escaped inside a string, any depth (the backslash run must repeat).
+    // The run must start at a non-backslash, so a long run is tried once, not from every position.
+    const escapedPattern = new RegExp(`(?<!\\\\)((\\\\{1,${MAX_ESCAPE_RUN}})"(?:${alternation})\\2"\\s*:\\s*)(\\2"(?:(?!\\2").)*\\2"|[^,}\\]\\s\\\\]+)`, 'gi');
+    function maskValue(value) {
+        if (isRawJson(value))
+            return value;
+        if (Array.isArray(value))
+            return value.map(maskValue);
+        if (value && typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = isMasked(k) ? MASK : maskValue(v);
+            return out;
+        }
+        // Strings can carry secrets too: JSON-encoded payloads (echoes, envelopes) and URLs.
+        if (typeof value === 'string')
+            return maskText(value);
+        return value;
+    }
+    function maskText(input) {
+        const json = maskJson(input);
+        if (json !== undefined)
+            return json;
+        return input
+            .replace(escapedPattern, (_m, prefix, slashes) => `${prefix}${slashes}"${MASK}${slashes}"`)
+            .replace(quotedPattern, (_m, prefix) => `${prefix}"${MASK}"`)
+            .replace(plainPattern, (_m, prefix) => `${prefix}${MASK}`);
+    }
+    function maskJson(input) {
+        const first = input.trimStart()[0];
+        if (first !== '{' && first !== '[')
+            return undefined;
+        try {
+            const parsed = parseLossless(input);
+            const masked = JSON.stringify(maskValue(parsed));
+            // Keep the original formatting when nothing needed masking.
+            return masked === JSON.stringify(parsed) ? input : masked;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return {
+        fields: [...keys],
+        text: maskText,
+        url(input) {
+            const redacted = redactUrlPassword(input);
+            const qIndex = redacted.indexOf('?');
+            if (qIndex === -1)
+                return redacted;
+            const params = new URLSearchParams(redacted.slice(qIndex + 1));
+            let changed = false;
+            for (const key of [...params.keys()]) {
+                if (isMasked(key)) {
+                    params.set(key, MASK);
+                    changed = true;
+                }
+            }
+            return changed ? `${redacted.slice(0, qIndex)}?${params.toString()}` : redacted;
+        },
+    };
+}
+/** `ws://user:secret@host/x` → `ws://user:***@host/x`. */
+export function redactUrlPassword(input) {
+    return input.replace(/^([a-z][a-z0-9+.-]*:\/\/[^/?#@:]*:)[^/?#@]*@/i, `$1${MASK}@`);
+}
+// `JSON.rawJSON` keeps a number's exact source text through parse → stringify
+// (Node 21+). Without it, 12345678901234567890 would be stored as 12345678901234567000.
+const jsonExt = JSON;
+const isRawJson = (value) => jsonExt.isRawJSON?.(value) ?? false;
+/** A run this long may be a number that does not survive a double round trip. */
+const MAYBE_LOSSY_NUMBER = /\d[\d.eE+-]{15}/;
+/** JSON.parse, but numbers keep their exact text. Throws (→ text masking) if that is not possible. */
+function parseLossless(input) {
+    if (!MAYBE_LOSSY_NUMBER.test(input))
+        return JSON.parse(input);
+    const { rawJSON } = jsonExt;
+    if (!rawJSON)
+        throw new Error('JSON.rawJSON is not available');
+    return JSON.parse(input, (_key, value, context) => typeof value === 'number' && context?.source !== undefined && JSON.stringify(value) !== context.source ? rawJSON(context.source) : value);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=masking.js.map

package/dist/server/masking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"masking.js","sourceRoot":"","sources":["../../src/server/masking.ts"],"names":[],"mappings":"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"}

package/dist/server/paths.d.ts

@@ -0,0 +1,12 @@
+/** Package root, from both `src/server/` (tsx) and `dist/server/` (built). */
+export declare const packageRoot: string;
+export declare const defaultWebRoot: string;
+/** Where the CLI remembers targets between runs. */
+export declare function defaultTargetsFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Create `path` if needed and make it readable by the current user only.
+ * Traffic and target files can hold tokens; `mode` alone would not tighten
+ * a file that already exists.
+ */
+export declare function ensurePrivateFile(path: string): void;
+export declare function readVersion(): string;

package/dist/server/paths.js

@@ -0,0 +1,30 @@
+import { chmodSync, closeSync, openSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+/** Package root, from both `src/server/` (tsx) and `dist/server/` (built). */
+export const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+export const defaultWebRoot = join(packageRoot, 'dist', 'web');
+/** Where the CLI remembers targets between runs. */
+export function defaultTargetsFile(env = process.env) {
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'wslog', 'targets.json');
+}
+/**
+ * Create `path` if needed and make it readable by the current user only.
+ * Traffic and target files can hold tokens; `mode` alone would not tighten
+ * a file that already exists.
+ */
+export function ensurePrivateFile(path) {
+    closeSync(openSync(path, 'a', 0o600));
+    chmodSync(path, 0o600);
+}
+export function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/server/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/server/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/D,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;AAC1F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACtC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC;QACxG,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/server/plugins.d.ts

@@ -0,0 +1,20 @@
+import type { WslogContext } from './context.js';
+import type { MessageTransform } from './recorder.js';
+/**
+ * Extension point for wslog. A plugin gets the full context and can:
+ * - subscribe to events:        ctx.bus.on('message', ...)
+ * - add HTTP routes:            ctx.router.get('/api/my-plugin', ...)
+ * - change or drop messages:    api.transform(draft => ...)
+ *
+ * Plugins run in order, after built-in masking.
+ */
+export interface WslogPlugin {
+    name: string;
+    setup(ctx: WslogContext, api: PluginApi): void | Promise<void>;
+    /** Called on shutdown, in reverse order. */
+    teardown?(): void | Promise<void>;
+}
+export interface PluginApi {
+    transform(fn: MessageTransform): void;
+}
+export declare function definePlugin(plugin: WslogPlugin): WslogPlugin;

package/dist/server/plugins.js

@@ -0,0 +1,4 @@
+export function definePlugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=plugins.js.map

package/dist/server/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../src/server/plugins.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/server/proxy/headers.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, OutgoingHttpHeaders } from 'node:http';
+/** Copy the client's handshake headers (cookies, auth, origin, ...) to the upstream request. */
+export declare function forwardHeaders(req: IncomingMessage): OutgoingHttpHeaders;
+export declare function parseProtocols(header: string | undefined): string[];

package/dist/server/proxy/headers.js

@@ -0,0 +1,39 @@
+/** Headers that describe the client↔proxy hop and must not be copied upstream. */
+const HOP_BY_HOP = new Set([
+    'host',
+    'connection',
+    'upgrade',
+    'keep-alive',
+    'proxy-connection',
+    'transfer-encoding',
+    'content-length',
+    'sec-websocket-key',
+    'sec-websocket-version',
+    'sec-websocket-extensions',
+    'sec-websocket-protocol',
+    'sec-websocket-accept',
+]);
+/** Copy the client's handshake headers (cookies, auth, origin, ...) to the upstream request. */
+export function forwardHeaders(req) {
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined || HOP_BY_HOP.has(name))
+            continue;
+        headers[name] = value;
+    }
+    const clientIp = req.socket.remoteAddress;
+    if (clientIp) {
+        const prior = req.headers['x-forwarded-for'];
+        headers['x-forwarded-for'] = prior ? `${String(prior)}, ${clientIp}` : clientIp;
+    }
+    return headers;
+}
+export function parseProtocols(header) {
+    if (!header)
+        return [];
+    return header
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=headers.js.map

package/dist/server/proxy/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../../src/server/proxy/headers.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,MAAM;IACN,YAAY;IACZ,SAAS;IACT,YAAY;IACZ,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,mBAAmB;IACnB,uBAAuB;IACvB,0BAA0B;IAC1B,wBAAwB;IACxB,sBAAsB;CACvB,CAAC,CAAC;AAEH,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,GAAoB;IACjD,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC1D,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC;IAC1C,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC7C,OAAO,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAA0B;IACvD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC"}

package/dist/server/proxy/proxy.d.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { TargetInfo } from '../../shared/protocol.js';
+import type { ConnectionRegistry } from '../connections.js';
+import type { Masker } from '../masking.js';
+import type { Recorder } from '../recorder.js';
+import type { Logger } from '../util/logger.js';
+export interface ProxyDeps {
+    connections: ConnectionRegistry;
+    recorder: Recorder;
+    masker: Masker;
+    logger: Logger;
+    handshakeTimeoutMs?: number;
+}
+/**
+ * Bridges a client WebSocket to its target server and records every frame.
+ *
+ * The upstream connection is opened first; the client handshake is only
+ * completed once the server accepted, so the negotiated subprotocol and
+ * any rejection status (401, 404, ...) are passed through to the client.
+ */
+export declare class WebSocketProxy {
+    private readonly deps;
+    private readonly wss;
+    private readonly selectedProtocol;
+    private readonly sockets;
+    /** Open bridges by connection id, so removing a target can disconnect its apps. */
+    private readonly bridges;
+    constructor(deps: ProxyDeps);
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, target: TargetInfo): void;
+    /**
+     * An app used a proxy URL with no target behind it. Record the attempt so the
+     * dashboard can say so, instead of the app failing with a 404 nobody sees.
+     */
+    rejectUnknownTarget(req: IncomingMessage, socket: Duplex, targetId: string): void;
+    private bridge;
+    /** Disconnect apps whose target is no longer in `targets`, so nothing keeps recording unseen. */
+    closeRemovedTargets(targets: readonly TargetInfo[]): void;
+    /** Close every proxied connection (server shutdown). */
+    closeAll(): void;
+}

package/dist/server/proxy/proxy.js

@@ -0,0 +1,188 @@
+import WebSocket, { WebSocketServer } from 'ws';
+import { buildUpstreamUrl } from '../targets.js';
+import { rejectUpgrade } from '../http/upgrade.js';
+import { forwardHeaders, parseProtocols } from './headers.js';
+/**
+ * Bridges a client WebSocket to its target server and records every frame.
+ *
+ * The upstream connection is opened first; the client handshake is only
+ * completed once the server accepted, so the negotiated subprotocol and
+ * any rejection status (401, 404, ...) are passed through to the client.
+ */
+export class WebSocketProxy {
+    deps;
+    wss;
+    selectedProtocol = new WeakMap();
+    sockets = new Set();
+    /** Open bridges by connection id, so removing a target can disconnect its apps. */
+    bridges = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.wss = new WebSocketServer({
+            noServer: true,
+            handleProtocols: (_offered, req) => this.selectedProtocol.get(req) ?? false,
+        });
+    }
+    handleUpgrade(req, socket, head, target) {
+        const { connections, masker, logger } = this.deps;
+        const requestPath = req.url ?? target.proxyPath;
+        const upstreamUrl = buildUpstreamUrl(target, requestPath);
+        const connection = connections.create({
+            targetId: target.id,
+            path: masker.url(requestPath),
+            upstreamUrl: masker.url(upstreamUrl),
+            clientAddress: req.socket.remoteAddress ?? 'unknown',
+            userAgent: req.headers['user-agent'],
+        });
+        const upstream = new WebSocket(upstreamUrl, parseProtocols(req.headers['sec-websocket-protocol']), {
+            headers: forwardHeaders(req),
+            handshakeTimeout: this.deps.handshakeTimeoutMs ?? 10_000,
+            followRedirects: false,
+        });
+        upstream.binaryType = 'nodebuffer';
+        let settled = false;
+        const fail = (status, message, failure) => {
+            if (settled)
+                return;
+            settled = true;
+            logger.debug(`proxy ${connection.id}: ${message}`);
+            connections.update(connection.id, { status: 'error', error: message, failure, closedBy: 'proxy' });
+            rejectUpgrade(socket, status, message);
+        };
+        // Client gave up while we were still dialing the server.
+        const onEarlyClose = () => {
+            if (settled)
+                return;
+            settled = true;
+            upstream.terminate();
+            connections.update(connection.id, { status: 'closed', closedBy: 'client' });
+        };
+        socket.once('close', onEarlyClose);
+        upstream.once('unexpected-response', (_req, res) => {
+            const status = res.statusCode ?? 502;
+            res.resume();
+            fail(status, `Server rejected the handshake: ${status} ${res.statusMessage ?? ''}`.trim(), 'rejected');
+            upstream.terminate();
+        });
+        upstream.on('error', (err) => {
+            if (!settled)
+                fail(502, `Could not reach ${masker.url(upstreamUrl)}: ${err.message}`, 'unreachable');
+        });
+        upstream.once('open', () => {
+            if (settled)
+                return upstream.terminate();
+            settled = true;
+            socket.off('close', onEarlyClose);
+            if (upstream.protocol)
+                this.selectedProtocol.set(req, upstream.protocol);
+            this.wss.handleUpgrade(req, socket, head, (client) => this.bridge(client, upstream, connection.id, target.id));
+        });
+    }
+    /**
+     * An app used a proxy URL with no target behind it. Record the attempt so the
+     * dashboard can say so, instead of the app failing with a 404 nobody sees.
+     */
+    rejectUnknownTarget(req, socket, targetId) {
+        const { connections, masker } = this.deps;
+        const message = 'No target for this proxy URL. Paste the server URL in the dashboard again; the proxy URL will be the same.';
+        const connection = connections.create({
+            targetId,
+            path: masker.url(req.url ?? ''),
+            upstreamUrl: '',
+            clientAddress: req.socket.remoteAddress ?? 'unknown',
+            userAgent: req.headers['user-agent'],
+        });
+        connections.update(connection.id, { status: 'error', error: message, failure: 'no-target', closedBy: 'proxy' });
+        rejectUpgrade(socket, 404, message);
+    }
+    bridge(client, upstream, connectionId, targetId) {
+        const { connections, recorder, logger } = this.deps;
+        client.binaryType = 'nodebuffer';
+        this.sockets.add(client);
+        this.sockets.add(upstream);
+        connections.update(connectionId, { status: 'open', protocol: upstream.protocol || undefined });
+        // Forward first, then record: recording (masking, storage) must never delay traffic.
+        client.on('message', (data, isBinary) => {
+            const buffer = toBuffer(data);
+            if (upstream.readyState === WebSocket.OPEN)
+                upstream.send(buffer, { binary: isBinary });
+            recorder.record({ connectionId, targetId, direction: 'out', data: buffer, isBinary });
+        });
+        upstream.on('message', (data, isBinary) => {
+            const buffer = toBuffer(data);
+            if (client.readyState === WebSocket.OPEN)
+                client.send(buffer, { binary: isBinary });
+            recorder.record({ connectionId, targetId, direction: 'in', data: buffer, isBinary });
+        });
+        let closed = false;
+        let closedByProxy = false;
+        this.bridges.set(connectionId, {
+            targetId,
+            close: (why) => {
+                closedByProxy = true;
+                client.close(1001, why);
+                upstream.close(1001, why);
+            },
+        });
+        const onClose = (side, other) => (code, reason) => {
+            this.sockets.delete(side === 'client' ? client : upstream);
+            this.sockets.delete(other);
+            this.bridges.delete(connectionId);
+            closeWith(other, code, reason);
+            if (closed)
+                return;
+            closed = true;
+            connections.update(connectionId, {
+                status: 'closed',
+                closedBy: closedByProxy ? 'proxy' : side,
+                closeCode: code,
+                closeReason: reason.toString('utf8') || undefined,
+            });
+        };
+        client.on('close', onClose('client', upstream));
+        upstream.on('close', onClose('server', client));
+        client.on('error', (err) => {
+            logger.debug(`proxy ${connectionId}: client error: ${err.message}`);
+            upstream.terminate();
+        });
+        upstream.on('error', (err) => {
+            logger.debug(`proxy ${connectionId}: server error: ${err.message}`);
+            connections.update(connectionId, { error: err.message });
+            client.terminate();
+        });
+    }
+    /** Disconnect apps whose target is no longer in `targets`, so nothing keeps recording unseen. */
+    closeRemovedTargets(targets) {
+        const ids = new Set(targets.map((t) => t.id));
+        for (const bridge of this.bridges.values()) {
+            if (!ids.has(bridge.targetId))
+                bridge.close('Target removed in wslog');
+        }
+    }
+    /** Close every proxied connection (server shutdown). */
+    closeAll() {
+        for (const ws of this.sockets)
+            ws.close(1001, 'wslog shutting down');
+        this.sockets.clear();
+    }
+}
+function toBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    return Buffer.from(data);
+}
+/** Mirror a close to the other side, mapping codes that may not be sent on the wire. */
+function closeWith(ws, code, reason) {
+    if (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING)
+        return;
+    if (code === 1006 || code === 1015)
+        return ws.terminate(); // abnormal: no close frame was received
+    const sendable = (code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005) || (code >= 3000 && code <= 4999);
+    if (sendable)
+        ws.close(code, reason.subarray(0, 123));
+    else
+        ws.close(1000);
+}
+//# sourceMappingURL=proxy.js.map

package/dist/server/proxy/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../../src/server/proxy/proxy.ts"],"names":[],"mappings":"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"}

package/dist/server/recorder.d.ts

@@ -0,0 +1,34 @@
+import type { Direction, MessageRecord } from '../shared/protocol.js';
+import type { ConnectionRegistry } from './connections.js';
+import type { EventBus } from './events.js';
+import type { Masker } from './masking.js';
+import type { MessageStore } from './storage/types.js';
+export type DraftRecord = Omit<MessageRecord, 'id'>;
+/**
+ * Runs on every message before it is stored. Return a (possibly changed)
+ * draft, or `null` to drop the message. Masking is the first built-in transform.
+ */
+export type MessageTransform = (draft: DraftRecord) => DraftRecord | null;
+export interface Frame {
+    connectionId: string;
+    targetId: string;
+    direction: Direction;
+    data: Buffer;
+    isBinary: boolean;
+}
+export interface RecorderOptions {
+    store: MessageStore;
+    bus: EventBus;
+    connections: ConnectionRegistry;
+    maxPayloadBytes: number;
+}
+export declare function maskingTransform(masker: Masker): MessageTransform;
+/** Turns raw proxied frames into stored, masked records and announces them. */
+export declare class Recorder {
+    private readonly options;
+    private readonly transforms;
+    private nextId;
+    constructor(options: RecorderOptions);
+    use(transform: MessageTransform): void;
+    record(frame: Frame): MessageRecord | undefined;
+}

package/dist/server/recorder.js

@@ -0,0 +1,65 @@
+import { isUtf8 } from 'node:buffer';
+export function maskingTransform(masker) {
+    if (!masker.fields.length)
+        return (draft) => draft;
+    return (draft) => {
+        if (draft.kind === 'text')
+            return { ...draft, payload: masker.text(draft.payload) };
+        // Binary frames often carry text too, e.g. `ws.send(Buffer.from(JSON.stringify(msg)))`.
+        const text = utf8Text(Buffer.from(draft.payload, 'base64'), draft.truncated);
+        if (text === undefined)
+            return draft;
+        const masked = masker.text(text);
+        return masked === text ? draft : { ...draft, payload: Buffer.from(masked, 'utf8').toString('base64') };
+    };
+}
+/** The bytes as text if they are UTF-8. A truncated frame may end in the middle of a character. */
+function utf8Text(bytes, truncated) {
+    if (isUtf8(bytes))
+        return bytes.toString('utf8');
+    for (let cut = 1; truncated && cut <= 3 && cut < bytes.length; cut++) {
+        const head = bytes.subarray(0, bytes.length - cut);
+        if (isUtf8(head))
+            return head.toString('utf8');
+    }
+    return undefined;
+}
+/** Turns raw proxied frames into stored, masked records and announces them. */
+export class Recorder {
+    options;
+    transforms = [];
+    nextId;
+    constructor(options) {
+        this.options = options;
+        this.nextId = options.store.lastId() + 1;
+    }
+    use(transform) {
+        this.transforms.push(transform);
+    }
+    record(frame) {
+        const { data, isBinary } = frame;
+        const truncated = data.length > this.options.maxPayloadBytes;
+        const body = truncated ? data.subarray(0, this.options.maxPayloadBytes) : data;
+        let draft = {
+            connectionId: frame.connectionId,
+            targetId: frame.targetId,
+            direction: frame.direction,
+            time: Date.now(),
+            size: data.length,
+            kind: isBinary ? 'binary' : 'text',
+            payload: isBinary ? body.toString('base64') : body.toString('utf8'),
+            truncated,
+        };
+        for (const transform of this.transforms) {
+            draft = transform(draft);
+            if (!draft)
+                return undefined;
+        }
+        const record = { id: this.nextId++, ...draft };
+        this.options.store.append(record);
+        this.options.connections.countMessage(record.connectionId, record.direction, record.size);
+        this.options.bus.emit('message', record);
+        return record;
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/server/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/server/recorder.ts"],"names":[],"mappings":"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"}

package/dist/server/storage/index.d.ts

@@ -0,0 +1,14 @@
+import { JsonlStore } from './jsonl.js';
+import { MemoryStore } from './memory.js';
+import { SqliteStore } from './sqlite.js';
+import type { MessageStore, StoreOptions } from './types.js';
+export type { MessageQuery, MessageStore, StoreOptions } from './types.js';
+export { MemoryStore, JsonlStore, SqliteStore };
+type StoreFactory = (path: string, options: StoreOptions) => Promise<MessageStore>;
+/** Register a custom storage backend, used as `--store <scheme>:<path>`. */
+export declare function registerStore(scheme: string, factory: StoreFactory): void;
+export declare function parseStoreSpec(spec: string): {
+    scheme: string;
+    path: string;
+};
+export declare function createStore(spec: string, options: StoreOptions): Promise<MessageStore>;