wslog-proxy 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leangdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# wslog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/wslog-proxy)](https://www.npmjs.com/package/wslog-proxy) [![CI](https://github.com/hoysengleang/wslog/actions/workflows/ci.yml/badge.svg)](https://github.com/hoysengleang/wslog/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/wslog-proxy)](LICENSE)
+
+**Point your app at wslog, open the browser, watch every WebSocket message. No code changes.**
+
+wslog is an open-source proxy that sits between your client and your WebSocket server, records every message, and streams it live to a browser dashboard.
+
+<!-- TODO: demo GIF + screenshot -->
+
+```bash
+npx wslog-proxy          # dashboard at http://localhost:4000
+npx wslog-proxy --demo   # same, plus a fake chat server so you can try it
+```
+
+1. Open `http://localhost:4000`.
+2. Paste the `ws://` or `wss://` URL your app connects to.
+3. Copy the proxy URL (e.g. `ws://127.0.0.1:4000/p/3f9a1c2b`) and use it in your app instead.
+4. Watch messages arrive live.
+
+Path and query are passed through: `ws://127.0.0.1:4000/p/3f9a1c2b/chat?room=1` reaches `<target>/chat?room=1`. Handshake headers (cookies, `Authorization`, `Origin`) and the negotiated subprotocol are forwarded too. Proxy URLs are derived from the target URL, and wslog remembers your targets (in `~/.config/wslog/targets.json`), so the proxy URL in your app keeps working across restarts.
+
+## Features
+
+| | |
+| --- | --- |
+| **Proxy** | Forwards text and binary frames both ways; mirrors close codes; passes handshake rejections (401, 404, …) through |
+| **Setup in the browser** | Paste a target URL, get a proxy URL. No flags to learn |
+| **Multiple targets** | Proxy several servers at once, each with its own proxy URL; click one to see only its traffic |
+| **Live traffic table** | Time, direction, size, connection, preview. Virtualized, stays fast with tens of thousands of rows |
+| **Detail pane** | Collapsible JSON tree, raw view, hex/base64 for binary, copy |
+| **Connections sidebar** | Status, close code, in/out counts, 30-second message-rate sparkline |
+| **Controls** | Pause/resume, search, filter by direction, connection, or target, clear, export JSON |
+| **Share link** | Read-only live view protected by a token |
+| **Storage** | In memory (default), JSONL file, or SQLite, with a size limit |
+| **Demo mode** | `--demo` starts a fake chat server with simulated users |
+| **Safe defaults** | Binds to localhost; masks configured fields before anything is stored |
+
+## Install
+
+```bash
+npx wslog-proxy                              # no install
+npm i -g wslog-proxy && wslog                # global; the command is `wslog`
+docker run -p 4000:4000 ghcr.io/hoysengleang/wslog  # Docker
+```
+
+Requires Node.js 22 or newer.
+
+In Docker, `localhost` means the container. Use `ws://host.docker.internal:8080` to reach a server on your machine; on Linux, also pass `--add-host=host.docker.internal:host-gateway` to `docker run`. The container listens on `0.0.0.0`, so open the **admin link** printed in the logs, or set a known token with `-e WSLOG_ADMIN_TOKEN=...`. The printed links assume `-p 4000:4000`; if you map another port, set `-e WSLOG_PUBLIC_URL=http://localhost:<port>`. To remember targets across container restarts, add `-v wslog:/home/node/.config/wslog`.
+
+## Options
+
+| Flag | Env | Default | Purpose |
+| --- | --- | --- | --- |
+| `[target-url...]` | `WSLOG_TARGET` | – | Register targets on startup. Pass several, or separate them with spaces or commas in the env var |
+| `-p, --port` | `WSLOG_PORT` | `4000` | Dashboard and proxy port |
+| `-H, --host` | `WSLOG_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` only on a trusted network |
+| `--public-url` | `WSLOG_PUBLIC_URL` | from host and port | Address people use to reach wslog, for printed and share links, e.g. `http://localhost:8080` when Docker maps port 8080 |
+| `-m, --mask` | `WSLOG_MASK` | none | Field names to hide, e.g. `token,password` |
+| `--max-messages` | `WSLOG_MAX_MESSAGES` | `10000` | Storage limit; oldest dropped first |
+| `--max-payload` | – | `1048576` | Bytes kept per message; longer payloads are truncated (still forwarded in full) |
+| `--store` | `WSLOG_STORE` | `memory` | `memory`, `./traffic.jsonl`, or `./traffic.db` (SQLite, needs Node.js 22.13+) |
+| `--share-token` | `WSLOG_SHARE_TOKEN` | random | Token for the read-only share link |
+| `--admin-token` | `WSLOG_ADMIN_TOKEN` | random | Token for full access from other machines |
+| – | `WSLOG_TARGETS_FILE` | `~/.config/wslog/targets.json` | Where targets are remembered between runs. Set it empty to keep them in memory only |
+| `--demo` | – | off | Start a fake chat server (also masks `token`, `password`) |
+| `-o, --open` | – | off | Open the dashboard in your browser |
+| `--verbose` / `-q, --quiet` | – | – | Debug logging / errors only |
+
+Memory: the `memory` and `.jsonl` stores keep messages in RAM, up to `--max-messages` × `--max-payload` bytes in the worst case (about 10 GB with the defaults if every message were 1 MB). For heavy traffic, lower `--max-payload` or use a `.db` (SQLite) store.
+
+## Security
+
+WebSocket traffic often carries tokens and personal data, so wslog is safe by default:
+
+- It listens on `127.0.0.1` only. Requests from this machine get full access; anything else needs a token.
+- **Masking happens before storage.** Masked values never reach disk, the dashboard, or exports. JSON is masked at any depth, including JSON encoded inside strings; other text by `key=value` / `"key": "value"` patterns (escaped or not), and URLs by query parameter, including target URLs. Binary frames that contain UTF-8 text are masked the same way. Passwords in URLs (`ws://user:pass@host`) are always hidden.
+- Handshake headers (cookies, `Authorization`) are forwarded to your server but never stored or shown. Only the `User-Agent` is recorded.
+- Saved traffic (`.jsonl`, `.db`) and the targets file are readable only by your user. Fields you did not mask are stored as sent, so treat these files like logs that contain secrets.
+- Share links are read-only and need the share token.
+- When wslog listens beyond localhost (including in Docker), it prints the admin link in its logs. Anyone who can read those logs gets full access, so keep them private or set your own `--admin-token`.
+- The dashboard API rejects cross-origin requests, including `Origin: null` (sandboxed iframes, local HTML files). Access without a token needs a local `Host` name, so DNS rebinding cannot reach it. Other sites cannot frame the dashboard.
+- **v0.1 has no user accounts. Do not expose wslog to the internet.**
+
+Found a vulnerability? Please report it privately; see [SECURITY.md](SECURITY.md).
+
+## How it compares
+
+| | wslog | Browser DevTools | wscat / websocat | mitmproxy |
+| --- | --- | --- | --- | --- |
+| Works for non-browser clients (Node, mobile, IoT) | ✅ | ❌ | ✅ (you are the client) | ✅ |
+| Live UI built for WebSocket traffic | ✅ | ✅ | ❌ | partial |
+| Search, filter, export across connections | ✅ | limited | ❌ | ✅ |
+| Share a live view with a teammate | ✅ | ❌ | ❌ | ❌ |
+| Setup | one command, no certs | none | none | proxy config + CA cert for TLS |
+
+## Development
+
+```bash
+npm install
+npm run dev      # server on :4000 (with --demo) + Vite dashboard on :5173
+npm run check    # typecheck + lint + unit tests
+npm run test:e2e # real browser against a real wslog (first time: npx playwright install chromium)
+npm run build    # dist/ (server) + dist/web (dashboard)
+```
+
+See [docs/architecture.md](docs/architecture.md) for how the code is organized and how to extend it, and [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli/args.d.ts

@@ -0,0 +1,14 @@
+import { type WslogConfig } from '../server/config.js';
+export declare const HELP: string;
+export interface CliOptions {
+    config: Partial<WslogConfig>;
+    open: boolean;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseCliArgs(argv: string[], env?: NodeJS.ProcessEnv): CliOptions;
+/**
+ * `WSLOG_TARGET` may list several URLs, separated by spaces or commas. A comma
+ * only splits when a new `scheme://` follows, so `ws://host/?topics=a,b` stays whole.
+ */
+export declare function splitTargets(value: string): string[];

package/dist/cli/args.js

@@ -0,0 +1,98 @@
+import { parseArgs } from 'node:util';
+import { DEFAULT_CONFIG } from '../server/config.js';
+import { defaultTargetsFile } from '../server/paths.js';
+export const HELP = `
+wslog — record WebSocket traffic and watch it live in your browser
+
+Usage
+  wslog [target-url...] [options]
+
+Examples
+  wslog                          start the dashboard at http://localhost:4000
+  wslog --demo                   start with a fake chat server to try it
+  wslog ws://localhost:8080      register a target from the command line
+  wslog ws://localhost:8080 ws://localhost:9000/socket
+                                 proxy several servers at once
+  wslog --mask token,password --store ./traffic.jsonl
+
+Options
+  -p, --port <n>           dashboard and proxy port (default ${DEFAULT_CONFIG.port})
+  -H, --host <addr>        bind address (default ${DEFAULT_CONFIG.host}); use 0.0.0.0 only on a trusted network
+      --public-url <url>   address people use to reach wslog, for printed and share links
+                           (e.g. http://localhost:8080 when Docker maps port 8080)
+  -m, --mask <fields>      comma-separated field names to hide, e.g. token,password (repeatable)
+      --max-messages <n>   keep at most n messages, oldest dropped first (default ${DEFAULT_CONFIG.maxMessages})
+      --max-payload <n>    keep at most n bytes per message (default ${DEFAULT_CONFIG.maxPayloadBytes})
+      --store <spec>       memory (default), ./file.jsonl, or ./file.db (SQLite, Node 22.13+)
+      --share-token <tok>  token for the read-only share link (default: random)
+      --admin-token <tok>  token for full access from other machines (default: random)
+      --demo               start a fake chat server with simulated users
+  -o, --open               open the dashboard in your browser
+      --verbose            debug logging
+  -q, --quiet              only log errors
+  -v, --version            print version
+  -h, --help               show this help
+
+Environment (handy for Docker; flags win)
+  WSLOG_PORT, WSLOG_HOST, WSLOG_PUBLIC_URL, WSLOG_MASK, WSLOG_STORE,
+  WSLOG_MAX_MESSAGES, WSLOG_SHARE_TOKEN, WSLOG_ADMIN_TOKEN, WSLOG_TARGET
+  WSLOG_TARGETS_FILE       where targets are remembered between runs
+                           (default ~/.config/wslog/targets.json; empty = don't remember)
+`;
+export function parseCliArgs(argv, env = process.env) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            port: { type: 'string', short: 'p' },
+            host: { type: 'string', short: 'H' },
+            'public-url': { type: 'string' },
+            mask: { type: 'string', short: 'm', multiple: true },
+            'max-messages': { type: 'string' },
+            'max-payload': { type: 'string' },
+            store: { type: 'string' },
+            'share-token': { type: 'string' },
+            'admin-token': { type: 'string' },
+            demo: { type: 'boolean' },
+            open: { type: 'boolean', short: 'o' },
+            verbose: { type: 'boolean' },
+            quiet: { type: 'boolean', short: 'q' },
+            version: { type: 'boolean', short: 'v' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const mask = values.mask ?? (env.WSLOG_MASK ? [env.WSLOG_MASK] : undefined);
+    const config = {
+        port: toInt(values.port ?? env.WSLOG_PORT, '--port'),
+        host: values.host ?? env.WSLOG_HOST,
+        publicUrl: values['public-url'] ?? env.WSLOG_PUBLIC_URL,
+        mask: mask?.flatMap((m) => m.split(',')),
+        maxMessages: toInt(values['max-messages'] ?? env.WSLOG_MAX_MESSAGES, '--max-messages'),
+        maxPayloadBytes: toInt(values['max-payload'], '--max-payload'),
+        store: values.store ?? env.WSLOG_STORE,
+        shareToken: values['share-token'] ?? env.WSLOG_SHARE_TOKEN,
+        adminToken: values['admin-token'] ?? env.WSLOG_ADMIN_TOKEN,
+        targets: positionals.length ? positionals : splitTargets(env.WSLOG_TARGET ?? ''),
+        targetsFile: env.WSLOG_TARGETS_FILE ?? defaultTargetsFile(env),
+        demo: values.demo,
+        logLevel: values.quiet ? 'error' : values.verbose ? 'debug' : undefined,
+    };
+    return { config, open: Boolean(values.open), help: Boolean(values.help), version: Boolean(values.version) };
+}
+/**
+ * `WSLOG_TARGET` may list several URLs, separated by spaces or commas. A comma
+ * only splits when a new `scheme://` follows, so `ws://host/?topics=a,b` stays whole.
+ */
+export function splitTargets(value) {
+    return value.split(/\s+|,(?=\s*[a-z][a-z0-9+.-]*:\/\/)/i).filter(Boolean);
+}
+function toInt(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n))
+        throw new Error(`${flag} expects a whole number, got "${value}"`);
+    return n;
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createWslog } from '../server/app.js';
+import { isLoopbackHost } from '../server/config.js';
+import { readVersion } from '../server/paths.js';
+import { color } from '../server/util/logger.js';
+import { HELP, parseCliArgs } from './args.js';
+async function main() {
+    let options;
+    try {
+        options = parseCliArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(color.red(`✖ ${err.message}`));
+        console.error('Run `wslog --help` for usage.');
+        process.exit(2);
+    }
+    if (options.help)
+        return void console.log(HELP);
+    if (options.version)
+        return void console.log(readVersion());
+    const wslog = await createWslog(options.config);
+    const { config, targets, store, masker, logger } = wslog.ctx;
+    try {
+        await wslog.listen();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'EADDRINUSE')
+            throw new Error(`Port ${config.port} is already in use. Try --port ${config.port + 1}.`, { cause: err });
+        throw err;
+    }
+    const url = wslog.dashboardUrl();
+    const { protocol, host, hostname } = new URL(url);
+    const proxyBase = config.publicUrl
+        ? `${protocol === 'https:' ? 'wss' : 'ws'}://${host}`
+        : `ws://${isLoopbackHost(config.host) ? '127.0.0.1' : hostname}:${wslog.ctx.port()}`;
+    logger.info('');
+    logger.info(`  ${color.bold('wslog')} ${color.dim(`v${wslog.ctx.version}`)}`);
+    logger.info('');
+    logger.info(`  ${color.green('➜')}  Dashboard  ${color.cyan(url)}`);
+    for (const t of targets.list()) {
+        logger.info(`  ${color.green('➜')}  Proxy      ${color.cyan(proxyBase + t.proxyPath)} ${color.dim(`→ ${masker.url(t.url)}`)}`);
+    }
+    logger.info(`     Storage    ${color.dim(store.kind)}${masker.fields.length ? color.dim(`  ·  masking ${masker.fields.join(', ')}`) : ''}`);
+    if (!isLoopbackHost(config.host)) {
+        logger.info('');
+        logger.info(`  ${color.yellow('!')}  Listening on ${config.host}. Anyone on this network can reach the proxy.`);
+        logger.info(`     Admin link (keep private): ${color.cyan(`${url}/?token=${config.adminToken}`)}`);
+        logger.info(`     Read-only share link:      ${color.cyan(wslog.shareUrl())}`);
+    }
+    logger.info('');
+    if (!targets.list().length)
+        logger.info(color.dim('  Open the dashboard and paste your WebSocket server URL to get started.\n'));
+    if (options.open)
+        openBrowser(url);
+    let closing = false;
+    const shutdown = async () => {
+        if (closing)
+            process.exit(1);
+        closing = true;
+        logger.info(color.dim('\n  shutting down…'));
+        await wslog.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+}
+main().catch((err) => {
+    console.error(color.red(`✖ ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE/C,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,OAAO,CAAC,IAAI;QAAE,OAAO,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,KAAK,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC;IAE7D,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,MAAM,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAA4B,CAAC;QACvC,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;YAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,CAAC,IAAI,kCAAkC,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACtI,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;IACjC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS;QAChC,CAAC,CAAC,GAAG,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,IAAI,EAAE;QACrD,CAAC,CAAC,QAAQ,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IACvF,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9E,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACjI,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,mBAAmB,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5I,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChB,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,kBAAkB,MAAM,CAAC,IAAI,+CAA+C,CAAC,CAAC;QAChH,MAAM,CAAC,IAAI,CAAC,mCAAmC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;QACnG,MAAM,CAAC,IAAI,CAAC,mCAAmC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM;QAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,4EAA4E,CAAC,CAAC,CAAC;IAEjI,IAAI,OAAO,CAAC,IAAI;QAAE,WAAW,CAAC,GAAG,CAAC,CAAC;IAEnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,IAAI,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACvG,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;AACtF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Programmatic API. Most people use the `wslog` CLI; import this to embed
+ * wslog in tests or tools, or to extend it with plugins and storage backends.
+ */
+export { createWslog, type CreateWslogOptions, type Wslog } from './server/app.js';
+export { DEFAULT_CONFIG, type WslogConfig } from './server/config.js';
+export type { WslogContext } from './server/context.js';
+export type { WslogEvents } from './server/events.js';
+export { definePlugin, type PluginApi, type WslogPlugin } from './server/plugins.js';
+export type { DraftRecord, MessageTransform } from './server/recorder.js';
+export { registerStore, type MessageQuery, type MessageStore, type StoreOptions } from './server/storage/index.js';
+export * from './shared/index.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Programmatic API. Most people use the `wslog` CLI; import this to embed
+ * wslog in tests or tools, or to extend it with plugins and storage backends.
+ */
+export { createWslog } from './server/app.js';
+export { DEFAULT_CONFIG } from './server/config.js';
+export { definePlugin } from './server/plugins.js';
+export { registerStore } from './server/storage/index.js';
+export * from './shared/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAuC,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAoB,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,YAAY,EAAoC,MAAM,qBAAqB,CAAC;AAErF,OAAO,EAAE,aAAa,EAA2D,MAAM,2BAA2B,CAAC;AACnH,cAAc,mBAAmB,CAAC"}

package/dist/server/app.d.ts

@@ -0,0 +1,19 @@
+import { type WslogConfig } from './config.js';
+import { type WslogContext } from './context.js';
+import type { WslogPlugin } from './plugins.js';
+export interface CreateWslogOptions extends Partial<WslogConfig> {
+    plugins?: WslogPlugin[];
+}
+export interface Wslog {
+    readonly ctx: WslogContext;
+    /** Start listening. Resolves once the dashboard URL is reachable. */
+    listen(): Promise<{
+        port: number;
+        url: string;
+    }>;
+    close(): Promise<void>;
+    dashboardUrl(): string;
+    shareUrl(): string;
+}
+/** Composition root: wires every subsystem together. */
+export declare function createWslog(options?: CreateWslogOptions): Promise<Wslog>;

package/dist/server/app.js

@@ -0,0 +1,96 @@
+import { resolve } from 'node:path';
+import { isWildcardHost, resolveConfig } from './config.js';
+import { ConnectionRegistry } from './connections.js';
+import { dashboardUrl, shareUrl } from './context.js';
+import { DemoController } from './demo/controller.js';
+import { EventBus } from './events.js';
+import { registerApiRoutes } from './http/api.js';
+import { LiveHub } from './http/live.js';
+import { Router } from './http/router.js';
+import { createHttpServer } from './http/server.js';
+import { createMasker } from './masking.js';
+import { defaultWebRoot, readVersion } from './paths.js';
+import { WebSocketProxy } from './proxy/proxy.js';
+import { maskingTransform, Recorder } from './recorder.js';
+import { createStore } from './storage/index.js';
+import { persistTargets, TargetRegistry } from './targets.js';
+import { createLogger } from './util/logger.js';
+/** Composition root: wires every subsystem together. */
+export async function createWslog(options = {}) {
+    const { plugins = [], ...configInput } = options;
+    const config = resolveConfig(configInput);
+    const logger = createLogger(config.logLevel);
+    const bus = new EventBus();
+    const store = await createStore(config.store, { maxMessages: config.maxMessages });
+    const masker = createMasker(config.mask);
+    const targets = new TargetRegistry(bus);
+    const connections = new ConnectionRegistry(bus);
+    const recorder = new Recorder({ store, bus, connections, maxPayloadBytes: config.maxPayloadBytes });
+    recorder.use(maskingTransform(masker));
+    const router = new Router();
+    // `httpServer` is created below; this is only called once it exists.
+    const port = () => httpServer.address()?.port ?? config.port;
+    const demo = new DemoController({
+        targets,
+        logger,
+        localProxyBase: () => {
+            const host = isWildcardHost(config.host) ? '127.0.0.1' : config.host;
+            return `ws://${host.includes(':') ? `[${host}]` : host}:${port()}`;
+        },
+    });
+    const ctx = {
+        config,
+        version: readVersion(),
+        logger,
+        bus,
+        store,
+        targets,
+        connections,
+        recorder,
+        masker,
+        router,
+        demo,
+        port,
+    };
+    for (const plugin of plugins) {
+        await plugin.setup(ctx, { transform: (fn) => recorder.use(fn) });
+        logger.debug(`plugin loaded: ${plugin.name}`);
+    }
+    registerApiRoutes(router, ctx);
+    if (config.targetsFile)
+        persistTargets(targets, bus, config.targetsFile, logger);
+    for (const url of config.targets)
+        targets.add(url);
+    const proxy = new WebSocketProxy({ connections, recorder, masker, logger });
+    bus.on('targets', (list) => proxy.closeRemovedTargets(list));
+    const live = new LiveHub(ctx);
+    const httpServer = createHttpServer({ ctx, proxy, live, webRoot: resolve(config.webRoot ?? defaultWebRoot) });
+    return {
+        ctx,
+        async listen() {
+            await new Promise((resolveListen, reject) => {
+                httpServer.once('error', reject);
+                httpServer.listen(config.port, config.host, () => {
+                    httpServer.off('error', reject);
+                    resolveListen();
+                });
+            });
+            if (config.demo)
+                await demo.start();
+            return { port: port(), url: dashboardUrl(ctx) };
+        },
+        async close() {
+            await demo.stop();
+            live.close();
+            proxy.closeAll();
+            httpServer.closeAllConnections();
+            await new Promise((done) => httpServer.close(() => done()));
+            for (const plugin of [...plugins].reverse())
+                await plugin.teardown?.();
+            await store.close();
+        },
+        dashboardUrl: () => dashboardUrl(ctx),
+        shareUrl: () => shareUrl(ctx),
+    };
+}
+//# sourceMappingURL=app.js.map

package/dist/server/app.js.map

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

package/dist/server/config.d.ts

@@ -0,0 +1,51 @@
+export interface WslogConfig {
+    /** Dashboard + proxy port. `0` picks a free port. */
+    port: number;
+    /** Bind address. Loopback by default; `0.0.0.0` only on trusted networks. */
+    host: string;
+    /**
+     * Address people use to reach wslog, for the links it prints and the share
+     * link, e.g. `http://localhost:8080` in Docker. Default: derived from host and port.
+     */
+    publicUrl?: string;
+    /** Field names to mask before anything is stored or shown. */
+    mask: string[];
+    /** Storage limit; oldest messages are dropped first. */
+    maxMessages: number;
+    /** Max bytes of payload kept per message; longer payloads are truncated. */
+    maxPayloadBytes: number;
+    /** `memory`, a `.jsonl` file path, or a `.db` / `.sqlite` file path. */
+    store: string;
+    /** Token for the read-only share link. */
+    shareToken: string;
+    /** Token for full access from non-loopback addresses. */
+    adminToken: string;
+    /** Target URLs to register on startup. */
+    targets: string[];
+    /**
+     * JSON file that remembers targets across restarts, so proxy URLs in your app
+     * keep working. The CLI sets one; unset keeps targets in memory only.
+     */
+    targetsFile?: string;
+    demo: boolean;
+    /** Path to the built dashboard. Defaults to `dist/web` inside the package. */
+    webRoot?: string;
+    logLevel: 'silent' | 'error' | 'info' | 'debug';
+}
+export declare const DEFAULT_CONFIG: {
+    port: number;
+    host: string;
+    mask: never[];
+    maxMessages: number;
+    maxPayloadBytes: number;
+    store: string;
+    targets: never[];
+    demo: false;
+    logLevel: "info";
+};
+/** Fields masked automatically in demo mode so the feature is visible. */
+export declare const DEMO_MASK_FIELDS: string[];
+export declare function generateToken(): string;
+export declare function resolveConfig(input?: Partial<WslogConfig>): WslogConfig;
+export declare function isLoopbackHost(host: string): boolean;
+export declare function isWildcardHost(host: string): boolean;

package/dist/server/config.js

@@ -0,0 +1,62 @@
+import { randomBytes } from 'node:crypto';
+export const DEFAULT_CONFIG = {
+    port: 4000,
+    host: '127.0.0.1',
+    mask: [],
+    maxMessages: 10_000,
+    maxPayloadBytes: 1024 * 1024,
+    store: 'memory',
+    targets: [],
+    demo: false,
+    logLevel: 'info',
+};
+/** Fields masked automatically in demo mode so the feature is visible. */
+export const DEMO_MASK_FIELDS = ['token', 'password'];
+export function generateToken() {
+    return randomBytes(18).toString('base64url');
+}
+export function resolveConfig(input = {}) {
+    const config = {
+        ...DEFAULT_CONFIG,
+        shareToken: generateToken(),
+        adminToken: generateToken(),
+        ...stripUndefined(input),
+    };
+    config.mask = [...new Set(config.mask.map((f) => f.trim()).filter(Boolean))];
+    if (config.demo && config.mask.length === 0)
+        config.mask = [...DEMO_MASK_FIELDS];
+    if (!Number.isInteger(config.port) || config.port < 0 || config.port > 65535) {
+        throw new Error(`Invalid port: ${config.port}`);
+    }
+    if (!Number.isInteger(config.maxMessages) || config.maxMessages < 1) {
+        throw new Error(`--max-messages must be a positive integer, got ${config.maxMessages}`);
+    }
+    if (!Number.isInteger(config.maxPayloadBytes) || config.maxPayloadBytes < 1) {
+        throw new Error(`--max-payload must be a positive integer, got ${config.maxPayloadBytes}`);
+    }
+    config.publicUrl = config.publicUrl?.trim() ? normalizePublicUrl(config.publicUrl) : undefined;
+    return config;
+}
+function normalizePublicUrl(input) {
+    let url;
+    try {
+        url = new URL(input.trim());
+    }
+    catch {
+        throw new Error(`--public-url must be a URL like http://localhost:4000, got "${input}"`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`--public-url must start with http:// or https://, got "${input}"`);
+    }
+    return url.origin;
+}
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+export function isLoopbackHost(host) {
+    return host === '127.0.0.1' || host === '::1' || host === 'localhost' || host.startsWith('127.');
+}
+export function isWildcardHost(host) {
+    return host === '0.0.0.0' || host === '::' || host === '';
+}
+//# sourceMappingURL=config.js.map

package/dist/server/config.js.map

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