hookdesk 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,53 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.0] - 2026-11-21
9
+
10
+ ### Added
11
+
12
+ - Mock responses. A rule sets the status, headers, body, and delay that matching requests get back, matched by method (or `*`) and by exact path or a `/*` prefix. Rules come from `mocks.rules` in the config and from the new `/api/mocks` endpoint (`GET`, `POST`, `DELETE`, `DELETE /api/mocks/:id`); the first match answers and runtime rules go first. Without a matching rule the response stays `200 {"received":true,"id":...}`. This makes it possible to test how a sender handles errors, retries, and slow endpoints.
13
+ - Each captured request records the response it got (`response.status`, `mockId`, `mockPath`, `delayMs`), shown in the list, the detail view, and the API, so a test run can be verified afterwards.
14
+ - Every capture response carries an `x-hookdesk-event-id` header with the id of the stored request.
15
+ - Filters on `GET /api/events`: `method`, `path` (exact or `/*` prefix), and `since` (ISO 8601). The response adds `total`, the number of stored requests before filtering.
16
+ - `GET /api/events/wait`: returns the oldest matching request at once, or holds the connection until one arrives, or answers `408` after `timeout`. Lets automated tests assert that a webhook was sent.
17
+ - `GET /api/events/export`: downloads the matching requests with redacted headers, bodies, responses, and the active mock rules as a JSON file.
18
+ - Dashboard: a Mock responses panel to list, add, and remove rules; a Status column and a `mock` marker in the request list; a Response tab in the request detail; an Export button; the running version in the header.
19
+ - Settings `mocks.rules`, `mocks.maxRules`, `mocks.maxDelayMs`, `wait.defaultTimeoutMs`, and `wait.maxTimeoutMs`.
20
+ - Fully config-driven. `config/limits.json` holds every validation bound, pattern, and fixed list; `config/app.json` holds the product name, API routes and query parameter names, HTTP methods and status codes, header names, content types, security headers, default response, export file name, static file list, and dashboard constants (keys, timings, timeline drawing); `config/messages.json` holds every text the CLI, API errors, config validation, and dashboard show. These values were previously hardcoded in the `.js` and `.html` files. The `.js` files now contain only logic.
21
+ - The dashboard page is a template that the server fills from `messages.json` and `app.json`, so a text, route, or key changed in JSON appears in the dashboard without code changes.
22
+ - Tests for mock rules (`tests/mocks.test.js`), the event store (`tests/events.test.js`), the new config sections, every new endpoint, HEAD requests to mocked paths, a cancelled `wait`, IPv6 loopback, headers a mock rule cannot override, and the filled dashboard template: 53 tests in total, up from 30.
23
+ - `CHANGELOG.md`.
24
+
25
+ ### Changed
26
+
27
+ - Minimum Node.js version raised from 20 to 26 (`engines.node` is now `>=26`). Node.js 20 reached end of life on 2026-04-30; Node.js 26 is the current Active LTS line, supported until 2029-04-30. hookdesk has no npm dependencies, so the Node.js runtime is the only versioned component it relies on.
28
+ - Source split by responsibility: `src/cli.js` is the `hookdesk` command (the `bin` entry), `src/server.js` only routes HTTP, `src/loader/` reads and validates the JSON files, `src/mocks/rules.js` handles mock rules, `src/store/events.js` holds requests and waiters, and the dashboard files moved to `src/ui/` (`ui.html` is now `index.html`). The README wordmark moved to `assets/` and is no longer shipped in the npm package.
29
+ - Mock response bodies are served with `Content-Security-Policy: sandbox`, so a mocked HTML page cannot run scripts on the dashboard origin.
30
+ - Config validation messages for ranges now name the allowed range from `config/limits.json`, for example `server.port must be an integer 0..65535`. List settings report `<key> must be a list of names`.
31
+ - The "Last 60 s" stat tile is now labeled from `ui.rateWindowMs` ("Last 1m" by default).
32
+ - On narrow screens the command bar buttons wrap instead of running past the right edge.
33
+ - README: mock responses, verifying webhooks in tests, the new API endpoints and settings, the four config files, Node.js 26+, file structure, and a changelog section.
34
+ - Verified on Node.js 26.13.1: all 53 tests pass; the packed npm tarball installs, starts through the `hookdesk` command, and passes an end-to-end run of every endpoint; a headless Chrome run clicks through the dashboard (mock form, tabs, keyboard keys, replay, copy, export, themes, remove and clear with confirmation, offline and reconnect, 390 px phone width) with 43 of 43 checks passing; every README example was run against a live server and its output copied as is.
35
+
36
+ ## [0.1.0] - 2026-10-18
37
+
38
+ ### Added
39
+
40
+ - Local-only webhook inspector: captures any HTTP method on any path under `/hook/` and keeps the last 200 requests in memory. Nothing is written to disk.
41
+ - Live browser dashboard: activity timeline (one spike per request, colored by method, height by body size), stats tiles, request table, and request detail with Body, Headers, and cURL tabs.
42
+ - Replay of a captured request to the local inbox only, never to the original sender. Credential and hop-by-hop headers are stripped on replay; `CONNECT`, `TRACE`, and `TRACK` cannot be replayed.
43
+ - Redaction of credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard and API.
44
+ - Keyboard navigation: `j` / `k` to move, `r` to replay, `c` to copy as cURL.
45
+ - Dark, light, and auto themes, remembered per browser.
46
+ - Local REST API: `/api/events`, `/api/events/:id`, `/api/events/:id/replay`, `DELETE /api/events`, and `/api/config`.
47
+ - Configuration through `config/default.json`, overridable with `--config=<path>`, the `PORT` environment variable, and `--port=<number>`. Unknown keys and invalid values stop the server at startup with exit code 1.
48
+ - Security: binds to loopback only, `Host` and `Origin` checks against DNS rebinding and cross-site requests, strict Content Security Policy on the dashboard, 1 MiB body limit (HTTP 413).
49
+ - No npm dependencies: Node.js built-in modules only.
50
+ - 30 tests with the built-in Node.js test runner, including integration tests against a real HTTP server and a launch through an npm bin symlink.
51
+
52
+ [0.2.0]: https://github.com/psandis/hookdesk/compare/c0c7632...v0.2.0
53
+ [0.1.0]: https://github.com/psandis/hookdesk/commit/c0c7632
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Petri Sandholm
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,491 @@
1
- # Temporary Holding Version
1
+ <img src="assets/wordmark.svg" alt="HookDesk Mini" width="290" height="64">
2
2
 
3
- 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.
3
+ [![npm version](https://img.shields.io/npm/v/hookdesk.svg)](https://www.npmjs.com/package/hookdesk)
4
+ [![node](https://img.shields.io/badge/node-%3E%3D26-brightgreen)](https://nodejs.org)
5
+ [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
6
+
7
+ Local-only webhook inspector and test bench. Point any webhook or HTTP client at `http://127.0.0.1:4317/hook/...` and watch requests land in a live browser dashboard, where you can inspect headers and bodies, copy them as cURL, and replay them. Mock rules decide what the sender gets back, and a small API lets automated tests wait for a webhook and check exactly what arrived. No account, no cloud, no database, and no npm dependencies. The npm package and the command are both **hookdesk**.
8
+
9
+ ## What It Does
10
+
11
+ - captures any HTTP method on any path under `/hook/`
12
+ - mock responses: per path and method, choose the status, headers, body, and delay the sender receives
13
+ - records the response each request got, so you can verify how the sender was answered
14
+ - test API: filter captured requests, wait for a matching request, and export a run as JSON
15
+ - live activity timeline: one spike per request, colored by method, taller for bigger bodies
16
+ - live stats: requests in memory, requests in the last minute, time since the last request, total body size
17
+ - request table, newest first, with method, path, response status, size, and age
18
+ - request detail with tabs: syntax-highlighted JSON body, headers, the response sent, and a ready cURL command
19
+ - replays a captured request to the local inbox, never to its original sender
20
+ - redacts credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard, API, and export
21
+ - keyboard navigation: `j` / `k` to move, `r` to replay, `c` to copy as cURL
22
+ - dark, light, or auto theme, remembered per browser
23
+ - config-driven: every setting, limit, route, status code, header name, text, and UI constant lives in JSON files under `config/`
24
+ - binds to `127.0.0.1` only, with `Host` and `Origin` checks
25
+
26
+ ## Requirements
27
+
28
+ - Node.js 26+
29
+ - macOS, Linux, or Windows
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ npm install -g hookdesk
35
+ ```
36
+
37
+ Or run it once without installing:
38
+
39
+ ```bash
40
+ npx hookdesk
41
+ ```
42
+
43
+ ### From source
44
+
45
+ ```bash
46
+ git clone https://github.com/psandis/hookdesk.git
47
+ cd hookdesk
48
+ npm link
49
+ hookdesk
50
+ ```
51
+
52
+ There is nothing to install or build: hookdesk has no dependencies. Without linking, use `npm start` in place of `hookdesk`.
53
+
54
+ ## Quick Start
55
+
56
+ Start the dashboard:
57
+
58
+ ```bash
59
+ hookdesk
60
+ ```
61
+
62
+ ```text
63
+ HookDesk Mini is running
64
+ Dashboard: http://127.0.0.1:4317
65
+ Webhook: http://127.0.0.1:4317/hook
66
+ Mocks: none, every request gets 200 {"received":true}
67
+ Example: curl -X POST http://127.0.0.1:4317/hook/demo -H 'Content-Type: application/json' -d '{"event":"hello"}'
68
+ ```
69
+
70
+ Open the dashboard URL in a browser, then send a test request from another terminal.
71
+
72
+ macOS / Linux:
73
+
74
+ ```bash
75
+ curl -X POST http://127.0.0.1:4317/hook/order.created \
76
+ -H 'Content-Type: application/json' \
77
+ -d '{"event":"order.created","orderId":123,"amount":49.90}'
78
+ ```
79
+
80
+ Windows (PowerShell):
81
+
82
+ ```powershell
83
+ Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4317/hook/order.created `
84
+ -ContentType 'application/json' `
85
+ -Body '{"event":"order.created","orderId":123,"amount":49.90}'
86
+ ```
87
+
88
+ The request appears in the dashboard within the poll interval (1.5 seconds by default). Stop the server with `Ctrl+C`.
89
+
90
+ ## Mock Responses
91
+
92
+ Without rules, every captured request gets `200 {"received":true,"id":"<event id>"}`. A mock rule changes that for matching requests, so you can test how the sender handles errors, retries, and slow endpoints.
93
+
94
+ | Field | Default | Description |
95
+ |---|---|---|
96
+ | `id` | generated | Name of the rule. Rules from the config file without an id get `config-1`, `config-2`, ... |
97
+ | `method` | `*` | HTTP method, or `*` for any |
98
+ | `path` | required | Exact path such as `/hook/payments`, or a prefix ending in `/*` such as `/hook/orders/*`. Must be under `capture.pathPrefix`. The query string is ignored. |
99
+ | `status` | `200` | Response status, 200..599 |
100
+ | `headers` | none | Response headers as an object of strings. `content-length`, `transfer-encoding`, and other framing headers are set by the server. |
101
+ | `body` | none | A string is sent as is (`text/plain`); any other JSON value is sent as JSON (`application/json`), unless `headers` sets `content-type` |
102
+ | `delayMs` | `0` | Wait before answering, up to `mocks.maxDelayMs` |
103
+
104
+ The defaults come from `mocks.ruleDefaults` in `config/app.json`, and the allowed status range from `config/limits.json`. The first matching rule answers. Rules added through the API or the dashboard go first, so a test can override a rule from the config file.
105
+
106
+ Add a rule at runtime:
107
+
108
+ ```bash
109
+ curl -s -X POST http://127.0.0.1:4317/api/mocks \
110
+ -H 'Content-Type: application/json' \
111
+ -d '{"id":"payments-down","method":"POST","path":"/hook/payments","status":503,"headers":{"Retry-After":"30"},"body":{"error":"service unavailable"},"delayMs":2000}'
112
+ ```
113
+
114
+ ```text
115
+ {"rule":{"id":"payments-down","method":"POST","path":"/hook/payments","status":503,"headers":{"retry-after":"30","content-type":"application/json; charset=utf-8"},"body":"{\"error\":\"service unavailable\"}","delayMs":2000}}
116
+ ```
117
+
118
+ The sender now gets, after two seconds:
119
+
120
+ ```text
121
+ HTTP/1.1 503 Service Unavailable
122
+ cache-control: no-store
123
+ retry-after: 30
124
+ content-type: application/json; charset=utf-8
125
+ x-content-type-options: nosniff
126
+ content-security-policy: sandbox
127
+ x-hookdesk-event-id: c7ce5dfe-c629-461b-a00a-5d100408e514
128
+
129
+ {"error":"service unavailable"}
130
+ ```
131
+
132
+ Every capture response carries `x-hookdesk-event-id`, the id of the stored request.
133
+
134
+ Rules can also live in a config file, so they are active from startup:
135
+
136
+ ```json
137
+ {
138
+ "mocks": {
139
+ "rules": [
140
+ { "method": "POST", "path": "/hook/payments", "status": 503, "delayMs": 2000 },
141
+ { "path": "/hook/slow/*", "delayMs": 8000 }
142
+ ]
143
+ }
144
+ }
145
+ ```
146
+
147
+ In the dashboard, open **Mock responses** under the command bar to see, add, and remove rules.
148
+
149
+ ## Verifying Webhooks in Tests
150
+
151
+ The API lets a test suite check that a webhook was sent, and what it contained, without reading the dashboard.
152
+
153
+ 1. Optionally add mock rules for the scenario.
154
+ 2. Note the current time.
155
+ 3. Trigger the code that sends the webhook.
156
+ 4. Wait for the request with `/api/events/wait` and assert on it.
157
+
158
+ ```bash
159
+ SINCE=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
160
+ # ... trigger your app here ...
161
+ curl -s "http://127.0.0.1:4317/api/events/wait?method=POST&path=/hook/orders/*&since=$SINCE&timeout=5000"
162
+ ```
163
+
164
+ ```text
165
+ {
166
+ "event": {
167
+ "id": "00fd2eee-b7ea-458b-ac5c-0bfa1bfa1a4a",
168
+ "timestamp": "2026-11-21T15:35:33.831Z",
169
+ "method": "POST",
170
+ "path": "/hook/orders/123",
171
+ "headers": {
172
+ "host": "127.0.0.1:4317",
173
+ "user-agent": "curl/8.7.1",
174
+ "accept": "*/*",
175
+ "content-type": "application/json",
176
+ "content-length": "25"
177
+ },
178
+ "body": "{\"event\":\"order.created\"}",
179
+ "bytes": 25,
180
+ "replayOf": null,
181
+ "response": {
182
+ "status": 200,
183
+ "mockId": null,
184
+ "mockPath": null,
185
+ "delayMs": 0
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ `wait` returns the oldest matching request at once if one is already stored, otherwise it holds the connection until one arrives. With no match before the timeout it answers `408`:
192
+
193
+ ```text
194
+ {"error":"No matching request within 1000 ms"}
195
+ ```
196
+
197
+ The same filters work on the list and the export:
198
+
199
+ | Parameter | Example | Matches |
200
+ |---|---|---|
201
+ | `method` | `POST` | HTTP method, any case |
202
+ | `path` | `/hook/orders/*` | Exact path, or a prefix ending in `/*` |
203
+ | `since` | `2026-11-21T15:35:00.000Z` | Requests at or after this ISO 8601 time |
204
+ | `timeout` | `5000` | `wait` only: milliseconds, up to `wait.maxTimeoutMs` |
205
+
206
+ ```bash
207
+ curl -s "http://127.0.0.1:4317/api/events?path=/hook/payments"
208
+ ```
209
+
210
+ ```text
211
+ {"events":[{"id":"c7ce5dfe-c629-461b-a00a-5d100408e514","timestamp":"2026-11-21T15:35:30.807Z","method":"POST","path":"/hook/payments","bytes":16,"replayOf":null,"status":503,"mockId":"payments-down"}],"count":1,"total":2}
212
+ ```
213
+
214
+ `GET /api/events/export` downloads the matching requests with redacted headers, bodies, and responses, plus the active mock rules, as evidence of a test run. The dashboard **Export** button downloads everything.
215
+
216
+ To start each test from a clean state, call `DELETE /api/events` and `DELETE /api/mocks`.
217
+
218
+ ## Dashboard
219
+
220
+ ### Header
221
+
222
+ - **Logo**: brand mark on the left
223
+ - **version / host / buffer / storage**: running version, bind address, how many requests are kept, and where (memory)
224
+ - **Live**: whether the dashboard can reach the local server; turns to **Offline** when it cannot
225
+ - **Theme**: `Auto` follows the operating system, `Light` and `Dark` force a theme. The choice is remembered in the browser.
226
+
227
+ ### Stats
228
+
229
+ | Tile | Shows |
230
+ |---|---|
231
+ | Captured | Requests held in memory |
232
+ | Last 1m | Requests received in the last minute (`ui.rateWindowMs` in `config/app.json`) |
233
+ | Last hit | Time since the newest request |
234
+ | In memory | Total size of all request bodies. Hover for the exact byte count. |
235
+
236
+ ### Activity timeline
237
+
238
+ The last 5 minutes (`ui.timelineWindowMs`) of traffic. Each spike is one request: its color is the HTTP method (see the legend), its height grows with the body size on a log scale. Hover a spike to preview the request, click it to open it. New requests pulse when they arrive.
239
+
240
+ ### Send a test
241
+
242
+ The command bar shows a ready `curl` command for your endpoint.
243
+
244
+ | Button | Action |
245
+ |---|---|
246
+ | Copy endpoint | Copies the base URL, for pasting into a webhook provider or your app |
247
+ | Copy curl | Copies the test command |
248
+ | Export | Downloads all captured requests and their responses as JSON |
249
+ | Refresh | Reloads the request list immediately |
250
+ | Clear | Deletes all captured requests, after a confirmation |
251
+
252
+ ### Mock responses
253
+
254
+ A collapsible panel under the command bar. It lists the active rules (method, path, status, delay, id) and has a form to add a rule. **Remove** deletes one rule, **Remove all rules** deletes every rule after a confirmation.
255
+
256
+ ### Requests
257
+
258
+ A table of captured requests, newest first.
259
+
260
+ | Column | Description |
261
+ |---|---|
262
+ | Method | HTTP method, colored as in the timeline legend |
263
+ | Path | Path and query string. Replayed requests are marked `replay`, requests answered by a mock rule `mock`. |
264
+ | Status | The status the sender received. 400 and above are shown in red. |
265
+ | Size | Body size. Hover for the exact byte count. |
266
+ | Age | Time since the request arrived, updated every second |
267
+
268
+ ### Request detail
269
+
270
+ Clicking a row opens the request with its path, method, received date and time, size, and short ID.
271
+
272
+ | Tab | Content |
273
+ |---|---|
274
+ | Body | The body as received. JSON is pretty-printed and syntax-highlighted with line numbers. |
275
+ | Headers | All headers. Sensitive values show as `[REDACTED]`. |
276
+ | Response | The status sent, the mock rule that answered (or the default response), and the delay |
277
+ | cURL | A command that re-sends the request, without redacted headers |
278
+
279
+ **Replay locally** re-sends the request to this hookdesk inbox, never to the original sender. Credential headers and hop-by-hop headers are stripped; the body is re-sent unchanged. `CONNECT`, `TRACE`, and `TRACK` requests cannot be replayed. A replay to a path with a mock delay longer than `replay.timeoutMs` fails with `502`.
280
+
281
+ ### Keyboard
282
+
283
+ | Key | Action |
284
+ |---|---|
285
+ | `j` or `Down` | Next request |
286
+ | `k` or `Up` | Previous request |
287
+ | `r` | Replay the selected request |
288
+ | `c` | Copy the selected request as cURL |
289
+
290
+ The keys are set in `ui.keys` in `config/app.json`; the hints in the dashboard follow them.
291
+
292
+ ## Configuration
293
+
294
+ All values live in JSON files under [`config/`](config/). The `.js` files under `src/` contain only logic and read every value from these files.
295
+
296
+ | File | Contents | Overridable |
297
+ |---|---|---|
298
+ | [`config/default.json`](config/default.json) | Settings: server, capture, replay, redaction, mocks, wait, ui | Yes, with `--config` |
299
+ | [`config/limits.json`](config/limits.json) | Validation bounds and fixed lists: allowed ranges, patterns, loopback hosts, themes, reserved headers, rule keys | No |
300
+ | [`config/app.json`](config/app.json) | Product name, API routes and query parameter names, HTTP methods and status codes, header names, content types, security headers, default response, export file name, static files, dashboard constants (keys, timings, timeline drawing) | No |
301
+ | [`config/messages.json`](config/messages.json) | Every text shown by the CLI, the API errors, config validation, and the dashboard | No |
302
+
303
+ The dashboard page `src/ui/index.html` is a template: the server fills its `{{...}}` placeholders from `messages.json` and `app.json` before sending it, and the dashboard script gets the rest through `/api/config`. Changing a text or a route in JSON changes it everywhere.
304
+
305
+ To change settings, create a JSON file with only the keys you want to override and pass it with `--config`:
306
+
307
+ ```json
308
+ {
309
+ "capture": { "maxEvents": 50, "pathPrefix": "/inbox" },
310
+ "redaction": { "sensitiveHeaders": ["authorization", "cookie", "x-signature"] },
311
+ "ui": { "defaultTheme": "light" }
312
+ }
313
+ ```
314
+
315
+ ```bash
316
+ hookdesk --config=./hookdesk.config.json
317
+ ```
318
+
319
+ Values are merged in this order, later ones win:
320
+
321
+ 1. built-in defaults (`config/default.json`)
322
+ 2. the file passed with `--config=<path>`
323
+ 3. the `PORT` environment variable
324
+ 4. the `--port=<number>` flag
325
+
326
+ Changing the port:
327
+
328
+ ```bash
329
+ # macOS / Linux
330
+ hookdesk --port=4343
331
+ PORT=4343 hookdesk
332
+ ```
333
+
334
+ ```powershell
335
+ # Windows (PowerShell)
336
+ hookdesk --port=4343
337
+ $env:PORT=4343; hookdesk
338
+ ```
339
+
340
+ ### Settings
341
+
342
+ | Key | Type | Default | Description |
343
+ |---|---|---|---|
344
+ | `server.host` | string | `127.0.0.1` | Bind address. Must be loopback: `127.0.0.1`, `localhost`, or `::1` |
345
+ | `server.port` | integer | `4317` | Port. `0` picks a free port |
346
+ | `server.allowedHostnames` | string[] | `["127.0.0.1", "localhost"]` | Accepted `Host` and `Origin` hostnames. Loopback names only |
347
+ | `capture.pathPrefix` | string | `/hook` | Path under which requests are captured |
348
+ | `capture.maxBodyBytes` | integer | `1048576` | Body size limit (1 MiB). Larger bodies get HTTP 413 |
349
+ | `capture.maxEvents` | integer | `200` | Number of requests kept in memory |
350
+ | `replay.timeoutMs` | integer | `5000` | Replay request timeout |
351
+ | `replay.blockedMethods` | string[] | `["CONNECT", "TRACE", "TRACK"]` | Methods that cannot be replayed |
352
+ | `replay.excludedHeaders` | string[] | hop-by-hop and browser headers | Headers dropped on replay. Sensitive headers are always dropped too |
353
+ | `redaction.sensitiveHeaders` | string[] | `authorization`, `cookie`, `x-api-key`, ... | Headers shown as the placeholder in the dashboard, API, and export |
354
+ | `redaction.placeholder` | string | `[REDACTED]` | Replacement text for redacted values |
355
+ | `mocks.rules` | object[] | `[]` | Mock rules active at startup, see [Mock Responses](#mock-responses) |
356
+ | `mocks.maxRules` | integer | `100` | Maximum number of rules |
357
+ | `mocks.maxDelayMs` | integer | `30000` | Maximum `delayMs` of a rule |
358
+ | `wait.defaultTimeoutMs` | integer | `10000` | `wait` timeout when the request does not set one |
359
+ | `wait.maxTimeoutMs` | integer | `60000` | Largest `timeout` a `wait` request may ask for |
360
+ | `ui.pollIntervalMs` | integer | `1500` | Dashboard refresh interval |
361
+ | `ui.timelineWindowMs` | integer | `300000` | Time span of the activity timeline (5 minutes) |
362
+ | `ui.defaultTheme` | string | `auto` | `auto`, `light`, or `dark`. Each viewer can still switch in the header |
363
+ | `ui.curlExcludedHeaders` | string[] | `host`, `content-length`, ... | Headers left out of "Copy as cURL" |
364
+
365
+ ### Validation
366
+
367
+ The configuration is validated at startup against `config/limits.json`. Unknown keys (usually typos) and invalid values stop the server with exit code 1:
368
+
369
+ ```text
370
+ $ hookdesk --config=./hookdesk.config.json
371
+ Unknown config key "capture.maxEvent"
372
+
373
+ $ hookdesk --port=abc
374
+ Invalid configuration:
375
+ - server.port must be an integer 0..65535
376
+ ```
377
+
378
+ ## Storage
379
+
380
+ hookdesk writes nothing to disk. Captured requests and runtime mock rules are held only in memory (the last `capture.maxEvents` requests, default 200) and are erased when the server stops or restarts. The only file it reads besides its own is the optional `--config` file. The theme choice is kept in the browser's `localStorage`.
381
+
382
+ ## API
383
+
384
+ hookdesk exposes a local REST API on the same port as the dashboard. All endpoints return JSON.
385
+
386
+ | Method | Path | Description |
387
+ |---|---|---|
388
+ | any | `/hook`, `/hook/*` | Capture a request; answered by the first matching mock rule or the default response |
389
+ | `GET` | `/api/events` | List captured requests (summaries with response status, no headers or body). Accepts `method`, `path`, `since` |
390
+ | `GET` | `/api/events/wait` | Wait for a matching request. Accepts `method`, `path`, `since`, `timeout`. `408` on timeout |
391
+ | `GET` | `/api/events/export` | Download matching requests with redacted headers, bodies, responses, and the active mock rules |
392
+ | `GET` | `/api/events/:id` | One request with redacted headers, the body, and the response sent |
393
+ | `POST` | `/api/events/:id/replay` | Replay a request to the local inbox |
394
+ | `DELETE` | `/api/events` | Clear all captured requests |
395
+ | `GET` | `/api/mocks` | List mock rules in match order |
396
+ | `POST` | `/api/mocks` | Add a rule (JSON body, `Content-Type: application/json`). `201`, `400` invalid, `409` duplicate id, `415` wrong content type |
397
+ | `DELETE` | `/api/mocks/:id` | Remove one rule |
398
+ | `DELETE` | `/api/mocks` | Remove all rules |
399
+ | `GET` | `/api/config` | Settings the dashboard uses |
400
+
401
+ ## Security
402
+
403
+ - Binds to loopback only. `Host` and `Origin` checks block DNS rebinding and cross-site requests from web pages, including adding mock rules.
404
+ - `POST /api/mocks` requires `Content-Type: application/json`, which a plain HTML form cannot send.
405
+ - The dashboard is served with a strict Content Security Policy and no inline scripts or styles.
406
+ - Mock responses are served with `Content-Security-Policy: sandbox`, so a mocked HTML body cannot run scripts on the dashboard origin.
407
+ - Sensitive headers are redacted in the dashboard, API, and export. **Bodies are not redacted**, so do not send production credentials or personal data to it.
408
+ - hookdesk is not a tunnel. To receive webhooks from an external provider, use a trusted tunnel separately.
409
+ - Bodies are stored as UTF-8 text; binary payloads are not supported yet.
410
+
411
+ ## Testing
412
+
413
+ ```bash
414
+ npm test
415
+ ```
416
+
417
+ Current bar:
418
+
419
+ - 53 tests across config loading, mock rules, the event store, and the HTTP server, using the built-in Node.js test runner
420
+ - includes HEAD requests to mocked paths, a cancelled `wait`, IPv6 loopback (`::1`), and a check that the served dashboard has no unfilled template placeholders
421
+ - integration tests run a real HTTP server on port 0
422
+ - expected values are read from the JSON files under `config/`, so changing a setting does not break tests; only the security requirements (loopback binding, `authorization` redaction, blocked replay methods) are fixed values
423
+ - the `hookdesk` command is tested by launching it through a symlink, the way `npm install -g` runs it
424
+
425
+ ## Tech Stack
426
+
427
+ | Tool | Purpose |
428
+ |---|---|
429
+ | Node.js 26+ | Runtime |
430
+ | node:http | HTTP server, no framework |
431
+ | Vanilla JS / HTML / CSS | Dashboard, no frontend framework, no build step |
432
+ | Canvas 2D | Activity timeline |
433
+ | node:test | Testing |
434
+
435
+ ## File Structure
436
+
437
+ ```text
438
+ hookdesk/
439
+ ├── assets/
440
+ │ └── wordmark.svg README wordmark
441
+ ├── config/
442
+ │ ├── default.json settings, overridable with --config
443
+ │ ├── limits.json validation bounds and fixed lists
444
+ │ ├── app.json routes, status codes, headers, security policies, UI constants
445
+ │ └── messages.json every text the CLI, API, and dashboard show
446
+ ├── src/
447
+ │ ├── cli.js the hookdesk command: arguments, startup output
448
+ │ ├── server.js HTTP routing and responses
449
+ │ ├── loader/
450
+ │ │ ├── settings.js reads, merges, and validates default.json and --config
451
+ │ │ └── fixed.js reads limits.json, app.json, and messages.json
452
+ │ ├── mocks/
453
+ │ │ └── rules.js mock rule validation, matching, and the live rule list
454
+ │ ├── store/
455
+ │ │ └── events.js in-memory request store, filters, and wait
456
+ │ └── ui/
457
+ │ ├── index.html dashboard markup template, filled from config
458
+ │ ├── ui.css dashboard styles and themes
459
+ │ ├── ui.js dashboard logic and timeline
460
+ │ └── logo.svg logo and favicon
461
+ ├── tests/
462
+ │ ├── config.test.js
463
+ │ ├── events.test.js
464
+ │ ├── mocks.test.js
465
+ │ └── server.test.js
466
+ ├── package.json
467
+ ├── CHANGELOG.md
468
+ ├── LICENSE
469
+ └── README.md
470
+ ```
471
+
472
+ ## Next Steps
473
+
474
+ 1. Request search by body content
475
+ 2. Import of exported runs
476
+ 3. Binary payload support
477
+
478
+ ## Changelog
479
+
480
+ See [CHANGELOG.md](CHANGELOG.md) for version history.
481
+
482
+ ## Related
483
+
484
+ - [wiremonitor](https://github.com/psandis/wiremonitor): Network traffic web dashboard
485
+ - [portmind](https://github.com/psandis/portmind): Scan listening ports and remember what normally runs where
486
+ - [mydevkit](https://github.com/psandis/mydevkit): Everyday developer tools in one CLI
487
+ - [nscout](https://github.com/psandis/nscout): Scout a name across npm, GitHub, PyPI, and domain registries
488
+
489
+ ## License
490
+
491
+ See [MIT](LICENSE)