WireCraft

WireCraft is a zero-dependency local API gateway, mock engine, streaming reverse proxy, signed-webhook validator, chaos testing simulator, and live HTTP traffic studio built 100% with Node.js standard library modules.

⚡ Quick Start (npx CLI)

Run instantly without cloning or installing dependencies:

# Instant launch on port 3000
npx wirecraft

# Custom port and upstream backend proxy
npx wirecraft --port 8080 --upstream https://api.staging.example.com

# Simulate network latency and chaos errors (20% failure rate, 300ms delay)
npx wirecraft --chaos 20 --delay 300

Open http://localhost:3000/_inspect for the real-time Server-Sent Events (SSE) Traffic Studio.

🛠️ CLI Options

| Flag | Shorthand | Description | Default | | :--- | :--- | :--- | :--- | | --port <number> | -p | HTTP port to listen on | 3000 / $PORT | | --upstream <url> | -u | Upstream backend URL to proxy unmatched requests | None (Echo fallback) | | --routes <path> | -r | Custom path to routes.json file | ./routes.json | | --chaos <percent> | -c | Injects random 500/502/503/504 errors ($0-100%$) | 0 (Off) | | --delay <ms> | -d | Global minimum simulated network latency in ms | 0 (Off) | | --stripe-secret <s> | | Stripe Webhook Secret for HMAC verification | $STRIPE_WEBHOOK_SECRET | | --github-secret <s> | | GitHub Webhook Secret for HMAC verification | $GITHUB_WEBHOOK_SECRET | | --version | -v | Display version | v1.1.0 | | --help | -h | Display help and usage examples | |

🎭 Dynamic Mock Templating

routes.json is re-read automatically on every request without requiring a server restart. WireCraft supports powerful built-in dynamic interpolation tags:

{
  "method": "GET",
  "path": "/api/users/:userId/orders/:orderId",
  "status": 200,
  "response": {
    "userId": "{{params.userId}}",
    "orderId": "{{params.orderId}}",
    "uuid": "{{uuid}}",
    "createdAt": "{{timestamp}}",
    "status": "{{randomChoice:processing,confirmed,in_transit,delivered}}",
    "trackingNumber": "TRK-{{randomInt:100000-999999}}"
  }
}
### Supported Template Tags:
- `{{params.name}}`: Path parameters from `:name` or `*wildcard`
- `{{query.name}}`: URL query string values
- `{{body.name}}`: JSON body properties
- `{{headers.name}}`: Incoming request header values
- `{{uuid}}`: Generates a cryptographic `v4` UUID
- `{{timestamp}}`: ISO 8601 UTC timestamp (`2026-08-31T...`)
- `{{now}}`: Unix timestamp in milliseconds
- `{{randomInt:min-max}}`: Random integer in range (e.g. `{{randomInt:100-999}}`)
- `{{randomChoice:a,b,c}}`: Random item from a comma-separated list

---

## 🛡️ Webhook Signature Verification & Dispatcher

### 1. Verification
WireCraft validates incoming webhook signatures natively using constant-time HMAC-SHA256 comparisons (`node:crypto`):
- **Stripe**: Validates `Stripe-Signature` with 5-minute replay tolerance (`t=...,v1=...`).
- **GitHub**: Validates `X-Hub-Signature-256` (`sha256=...`).

### 2. Built-in Webhook Dispatcher
In the Traffic Studio UI (**Webhook Tester** tab), craft any Stripe or GitHub event payload and dispatch it to your local or remote application. WireCraft automatically generates valid HMAC signatures on the fly.

---

## 📦 Traffic Export (HAR 1.2)

Click the **Export HAR** button in the Traffic Studio header to export all captured traffic into standard `.har` (HTTP Archive 1.2) format, ready to import into Chrome DevTools, Postman, Insomnia, or attach to bug reports.

---

## Design notes and limits

- CORS is enabled for every response and `OPTIONS` preflights return `204`.
- Request bodies are buffered in memory and capped at 10 MB; this is a local developer tool, not a large-upload proxy.
- SSE clients are held in process and receive events only while connected; MicroMock intentionally has no database or persistence layer.
- The inspector displays request headers and payloads. Do not expose it to untrusted networks or send real secrets to it.
- Replay can make requests to any supplied HTTP(S) URL. Keep the endpoint local/private when handling untrusted input to avoid SSRF risk.

## Verification

```sh
npm run test
npm ls --omit=dev

The test command performs Node's built-in syntax check. The dependency command output is checked into deps-proof.txt.

Hackathon fit

• Track C — Web & Network: concurrent native HTTP server, protocol-correct CORS/SSE, and native outbound HTTP(S) replay.
• Track A — Developer Tools & CLI: fast local mocking and webhook debugging with a clean single-command startup surface.
• Single File bonus: all executable application logic and the dashboard live in server.mjs.