api-tracer-kit 1.0.0 → 1.1.0

package/docs/getting-started.md

@@ -0,0 +1,120 @@
+# Getting started
+
+## Install
+
+```bash
+npm install api-tracer-kit
+```
+
+Nothing runs on install, and importing the package evaluates no browser global.
+Tracing begins only when you call `init()`.
+
+## One command
+
+```bash
+npx api-tracer setup
+```
+
+It detects your framework, writes a module that configures the tracer, adds the
+import to your entry file, and gitignores the console's data directory. Re-running
+it is safe, and it warns if anything else already calls `init()`.
+
+| Option | |
+| --- | --- |
+| `--framework cra\|vite\|next\|node` | override the detection |
+| `--entry <file>` | the entry file to import from |
+| `--out <file>` | where to write the module (default `src/apiTracer.js`) |
+| `--axios false` | do not attach axios |
+| `--envelope false` | your API reports failure in the status line, not the body |
+| `--force` | overwrite an existing file |
+
+What it works out for you:
+
+- **the framework**, from your dependencies
+- **the environment gate** that your bundler will actually fold — `REACT_APP_ENV`
+  for CRA, `import.meta.env.DEV` for Vite, `NODE_ENV` for Next and Node
+- **whether to attach axios**, from whether you depend on it
+- **TypeScript or JavaScript**, from whether you have a `tsconfig.json`
+
+## Or do it by hand
+
+Put this at your application's entry point, before anything makes a request:
+
+```ts
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init();
+```
+
+Every `fetch` and `XMLHttpRequest` afterwards is traced. Read them back with:
+
+```ts
+apiTracer.getTraces();
+```
+
+### If you use axios
+
+axios instances are plain objects with no global to patch, so hand yours over:
+
+```ts
+import axios from 'axios';
+
+apiTracer.init();
+apiTracer.useAxios(axios);
+```
+
+One call covers the default export **and every instance `axios.create()` makes
+afterwards**. See [axios](./tracer.md#axios) for why this is the one integration
+the package cannot do for you.
+
+> **Configure it in exactly one place.** `init()` is idempotent — a second call
+> keeps the first one's configuration and warns about the options it ignored.
+> Two modules each calling `init()` is the most common way to end up with a
+> tracer that runs but does nothing you asked for.
+
+## See them
+
+Three options, in increasing order of usefulness.
+
+**1. The console log.** Fine for a quick check:
+
+```ts
+apiTracer.subscribe((trace) => {
+  console.log(trace.request.method, trace.request.url, trace.response?.status, `${trace.timing.duration}ms`);
+});
+```
+
+**2. The in-app panel.** A floating list with search, filters and per-call
+detail. React only:
+
+```tsx
+import { ApiTracerPanel } from 'api-tracer-kit/ui';
+
+<ApiTracerPanel enabled={process.env.NODE_ENV !== 'production'} />;
+```
+
+**3. The console.** A separate process that maps every endpoint in your source,
+receives your app's traffic, and lets you re-send any call. This is the one
+worth setting up. See [the console](./console.md).
+
+```bash
+npx api-tracer start
+```
+
+then point the tracer at it:
+
+```ts
+apiTracer.init({ reportTo: true });   // true means http://localhost:4400
+```
+
+## Where to go next
+
+| | |
+| --- | --- |
+| [Tracer API](./tracer.md) | every option, the `ApiTrace` model, storage, lifecycle |
+| [The console](./console.md) | CLI, dashboard, replay, drift, coverage, import/export |
+| [Configuration](./configuration.md) | the config file, scanner presets, sign-in flows |
+| [Frameworks](./frameworks.md) | React, Next.js, Vite, CRA, Node, plain JavaScript |
+| [Troubleshooting](./troubleshooting.md) | when nothing is being recorded |
+| [Security](./security.md) | redaction, what is stored, what is safe to share |
+| [Architecture](./architecture.md) | how it works inside |

package/docs/security.md

@@ -0,0 +1,143 @@
+# Security
+
+The tracer sees everything your API sees. On some products that means
+credentials, personal data, and — in health, finance or HR software — data whose
+mishandling is a regulatory matter, not just an embarrassment. Read this before
+deploying a console anywhere but your own laptop.
+
+## What is redacted, by default
+
+**Headers**, matched case-insensitively:
+
+```
+authorization, cookie, set-cookie, proxy-authorization, x-api-key, api-key,
+auth_token, access_token, secret_token, x-auth-token, x-csrf-token
+```
+
+**Body and query fields**, matched by name:
+
+```
+/(token|password|passwd|secret|api[-_]?key|authorization|credential|otp|ssn)/i
+```
+
+The **value** is replaced with `<redacted>` and the surrounding shape is kept, so
+the sample still shows what the endpoint expects.
+
+Redaction happens **before** a trace is stored, so a real credential is never
+held in the tracer's memory, never reaches a subscriber, and never leaves the
+browser. The console redacts again before writing anything to disk.
+
+Extend rather than replace:
+
+```ts
+import { DEFAULT_REDACT_HEADERS } from 'api-tracer-kit';
+
+apiTracer.init({
+  redactHeaders: [...DEFAULT_REDACT_HEADERS, 'x-internal-key'],
+  redactFields: /(token|password|secret|nhs_number|date_of_birth)/i,
+});
+```
+
+## What is *not* redacted
+
+This is the part that matters.
+
+Redaction is **name-based**. A field called `notes` containing a patient's
+history, a `body` containing an address, a response listing every user — none of
+those look like credentials, and none are touched. The tracer records response
+bodies in full, up to `maxBodyBytes`.
+
+So: **assume every trace and every capture contains real data from the
+environment you are watching.**
+
+If that is unacceptable for your product, either narrow what is traced:
+
+```ts
+apiTracer.init({ include: ['/api/reference/'] });
+```
+
+or drop response bodies entirely:
+
+```ts
+apiTracer.init({ maxBodyBytes: 0 });
+```
+
+or post-process in a subscriber before anything is stored or reported.
+
+## Where data ends up
+
+### In the browser
+
+Traces live in memory, in a capped ring (500 by default), and disappear on
+reload. Nothing is persisted unless you supply storage that does.
+
+### In the console's data directory
+
+`<project>/.api-tracer/` holds captured request and response bodies, response
+shapes, and a real session token.
+
+**Add it to `.gitignore` before you run anything:**
+
+```
+.api-tracer/
+```
+
+`tokens.json` is written owner-only (`chmod 600`), but it is still a real
+credential on disk. **Sign out** deletes it, and on a shared machine that is
+worth doing.
+
+If it has already been committed, unstage it — the files stay on disk:
+
+```bash
+git rm -r --cached .api-tracer
+```
+
+If it reached a pushed commit, treat the token as compromised and rotate it. The
+bodies are in the history and removing them means rewriting it.
+
+## What is safe to share
+
+HAR, cURL and Postman exports carry `<paste your token>` in place of a real
+token, so an export is safe to attach to a ticket or hand to a backend
+developer — **as far as credentials go**.
+
+The bodies in them are still real. An export of a busy session is a data
+extract. Treat it accordingly.
+
+## Deploying a console
+
+It is a Node process that writes JSON files and holds a token. It is not a
+static asset.
+
+- **Keep it off the public internet.** VPN, SSO, or an allowlisted origin behind
+  your CDN.
+- **`CONSOLE_USER` / `CONSOLE_PASS`** turn on basic auth — but **`/api/record`
+  stays open**, because the app posts recordings from a browser that cannot send
+  those credentials. The gate protects reading captures, replaying calls and the
+  stored token; it does not stop someone who can reach the host from posting
+  junk recordings. If that matters, put the whole thing behind VPN or SSO.
+- **`ALLOWED_ORIGINS`** is an allowlist for posting recordings. Localhost always
+  works; every other origin must be named, so a stray site cannot feed or read
+  the console.
+- **`HOST`** stays on `127.0.0.1` unless you change it, so a laptop instance is
+  not exposed by accident.
+- **Keep the data volume off shared storage.**
+- **Mixed content**: an HTTPS app cannot post to an `http://` console, and the
+  browser blocks it silently. Terminate TLS in front of it, or serve it under a
+  path on the app's own origin.
+
+## Replaying against production
+
+The console refuses to replay writes against an environment named `prod`.
+
+That is a guard, not a guarantee — it matches on the environment name you
+configured. Consider commenting out the production base URL in your config
+entirely, so it cannot be selected. `LOCK_ENV` pins a shared console to one
+environment so nobody can switch it.
+
+Replay is not a dry run. Every POST creates a real record each time.
+
+## Reporting a vulnerability
+
+Open an issue for anything non-sensitive. For a genuine vulnerability, contact
+the maintainer directly rather than filing publicly.

package/docs/tracer.md

@@ -0,0 +1,330 @@
+# The tracer
+
+The framework-free half of the package. No React, no axios, no DOM required.
+
+## `apiTracer`
+
+A single shared instance. It is held in a global registry keyed by
+`Symbol.for('api-tracer-kit.registry')`, so `api-tracer-kit` and
+`api-tracer-kit/axios` — separate bundles with separate module graphs — resolve
+to the same object. Without that, `useAxios()` would attach to an instance
+`getTraces()` never reads from.
+
+| Method | Description |
+| --- | --- |
+| `init(options?)` | Installs the interceptors. Idempotent: a second call keeps the first one's configuration and warns about the options it ignored. Returns `this`. |
+| `useAxios(axios)` | Traces an axios object and everything it creates. Calls `init()` first if needed. Returns `this`. |
+| `getTraces()` | Every trace held, oldest first. |
+| `getTrace(id)` | One trace, or `undefined`. |
+| `subscribe(fn)` | Calls `fn(trace)` for each **finished** trace. Returns the unsubscribe function. |
+| `clear()` | Drops every trace. |
+| `remove(id)` | Drops one. |
+| `destroy()` | Restores every patched global and every axios adapter. After this the runtime behaves exactly as it did before `init()`. |
+| `isActive` | Whether tracing is currently installed. |
+
+Standalone function forms, for callers who would rather not reach through an
+object: `initApiTracer`, `getApiTraces`, `clearApiTraces`,
+`subscribeToApiTraces`, `destroyApiTracer`. They act on the same shared
+instance.
+
+`ApiTracer` is exported as a class too, if you want an isolated instance — most
+useful in tests, where a shared singleton between test cases is a nuisance.
+
+```ts
+import { ApiTracer } from 'api-tracer-kit';
+
+const tracer = new ApiTracer().init({ transports: ['fetch'] });
+// ...
+tracer.destroy();
+```
+
+## Options
+
+Every one is optional.
+
+### `transports`
+
+```ts
+transports?: ('fetch' | 'xhr' | 'axios')[]
+```
+
+Which globals to patch. Default: all of them that exist in the runtime. Pass
+`[]` to patch nothing globally — useful when you only want axios, which is
+attached separately.
+
+`'axios'` in this list does nothing on its own; axios has no global to patch and
+is reached only through `useAxios()`.
+
+### `include` / `exclude`
+
+```ts
+include?: (string | RegExp)[]
+exclude?: (string | RegExp)[]
+```
+
+Strings match by substring, so `'/api/'` is usually enough. `exclude` is applied
+first and wins. With no `include`, everything not excluded is traced.
+
+```ts
+apiTracer.init({ include: ['/api/'], exclude: [/\/health$/, 'analytics'] });
+```
+
+`reportTo`'s own endpoint is excluded automatically — the tracer never traces
+its own reporting.
+
+### `redactHeaders` / `redactFields`
+
+```ts
+redactHeaders?: string[]     // default: DEFAULT_REDACT_HEADERS
+redactFields?: RegExp        // default: DEFAULT_REDACT_FIELDS
+```
+
+Header names are matched case-insensitively; field names are matched with the
+regex. Both replace the **value** with `<redacted>` and keep the surrounding
+shape. Redaction happens before a trace is stored, so a real credential is never
+held in memory.
+
+Defaults are exported so you can extend rather than replace them:
+
+```ts
+import { DEFAULT_REDACT_HEADERS } from 'api-tracer-kit';
+
+apiTracer.init({ redactHeaders: [...DEFAULT_REDACT_HEADERS, 'x-internal-key'] });
+```
+
+`DEFAULT_REDACT_HEADERS` covers `authorization`, `cookie`, `set-cookie`,
+`proxy-authorization`, `x-api-key`, `api-key`, `auth_token`, `access_token`,
+`secret_token`, `x-auth-token`, `x-csrf-token`.
+
+`DEFAULT_REDACT_FIELDS` is
+`/(token|password|passwd|secret|api[-_]?key|authorization|credential|otp|ssn)/i`.
+
+### `maxBodyBytes`
+
+```ts
+maxBodyBytes?: number        // default 200_000
+```
+
+Bodies larger than this are recorded as omitted rather than truncated — a
+partial JSON body is more misleading than none. A response declaring a larger
+`content-length` is never read at all.
+
+### `maxTraces`
+
+```ts
+maxTraces?: number           // default 500
+```
+
+The in-memory store is a capped ring; older traces fall off the end. An
+unbounded store in a long-lived tab is a memory leak.
+
+### `envelope`
+
+```ts
+envelope?: {
+  codeFields?: string[];     // default ['status', 'code']
+  okField?: string;          // default 'success'
+  failFrom?: number;         // default 400
+} | false
+```
+
+For APIs that answer HTTP `200` and put the real verdict in the body:
+
+```json
+{ "status": 801, "success": false, "message": "Authentication token header missing" }
+```
+
+With an envelope configured, that trace gets `envelopeOk: false` and
+`envelopeCode: 801` even though `response.status` is `200`. Pass an empty object
+`{}` to accept the defaults; omit it entirely and no envelope is read.
+
+### `reportTo`
+
+```ts
+reportTo?: string | boolean
+```
+
+POST each finished trace to a console. `true` means `http://localhost:4400`.
+Failures are swallowed — a console that is not running must never affect the
+app — and after six consecutive failures the reporter stops trying.
+
+### `storage`
+
+```ts
+storage?: TraceStorage
+```
+
+Replaces the in-memory store. See [Storage](#storage).
+
+### `onTrace`
+
+```ts
+onTrace?: (trace: ApiTrace) => void
+```
+
+Identical to `subscribe()`, set up front. This is the one option a second
+`init()` still honours, because adding a subscriber from another module is
+legitimate.
+
+### `debug`
+
+```ts
+debug?: boolean              // default false
+```
+
+Logs a line on init and reports subscribers that throw.
+
+## The `ApiTrace` model
+
+```ts
+interface ApiTrace {
+  id: string;
+  transport: 'fetch' | 'xhr' | 'axios';
+  status: 'pending' | 'success' | 'error' | 'network-error' | 'cancelled';
+
+  request: {
+    url: string;                      // absolute
+    path: string;                     // origin + pathname, for grouping
+    method: string;
+    headers: Record<string, string>;  // redacted
+    params: Record<string, unknown>;  // parsed query string, redacted
+    body?: unknown;                   // parsed and redacted
+    bodyType: 'json' | 'formdata' | 'urlencoded' | 'text' | 'binary' | 'none';
+    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
+  };
+
+  response?: {
+    status: number;
+    statusText?: string;
+    headers: Record<string, string>;  // redacted
+    body?: string;                    // raw text
+    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
+    size?: number;
+  };
+
+  timing: {
+    startedAt: number;                // performance.now() where available
+    completedAt?: number;
+    duration?: number;                // milliseconds, rounded
+  };
+
+  error?: { message: string; name?: string; stack?: string };
+
+  envelopeOk?: boolean;
+  envelopeCode?: number;
+}
+```
+
+### What each `status` means
+
+| | |
+| --- | --- |
+| `pending` | in flight; `response` and `timing.duration` are not set yet |
+| `success` | HTTP 2xx |
+| `error` | the server answered, but not with a 2xx |
+| `network-error` | no answer: DNS failure, connection refused, timeout |
+| `cancelled` | aborted by the caller — not a broken endpoint |
+
+Subscribers are called only when a trace finishes, so a subscriber never sees
+`pending`. `getTraces()` can return one.
+
+### Bodies
+
+`bodyType` records what actually went on the wire, so a captured call can be
+replayed the same way. A `FormData` is unpacked field by field — `JSON.stringify`
+flattens one to `{}` — and files inside it become
+`<file: scan.pdf, 20418 bytes>`, because a file cannot be replayed.
+
+`bodyOmitted` says why a body is missing:
+
+| | |
+| --- | --- |
+| `too-large` | over `maxBodyBytes` |
+| `stream` | a `ReadableStream` request body, or a `text/event-stream` response — reading either would break it |
+| `binary` | a Blob, ArrayBuffer, or a non-textual content type |
+| `unreadable` | the body could not be cloned or parsed |
+
+## Storage
+
+```ts
+interface TraceStorage {
+  add(trace: ApiTrace): void;
+  update(id: string, patch: Partial<ApiTrace>): ApiTrace | undefined;
+  get(id: string): ApiTrace | undefined;
+  getAll(): ApiTrace[];
+  remove(id: string): void;
+  clear(): void;
+}
+```
+
+The default is `MemoryTraceStorage`, exported so you can size it yourself:
+
+```ts
+import { MemoryTraceStorage } from 'api-tracer-kit';
+
+apiTracer.init({ storage: new MemoryTraceStorage(50) });
+```
+
+`update()` returning `undefined` for an unknown id is normal, not an error: a
+long-running request can be evicted by the cap while still in flight.
+
+Nothing is persisted by default. To keep traces across reloads, supply storage
+backed by `sessionStorage` or IndexedDB — but see
+[Security](./security.md) first, because traces contain request and response
+bodies.
+
+## axios
+
+axios calls are traced two ways.
+
+In a browser axios rides on `XMLHttpRequest`, so `apiTracer.init()` alone sees
+them. `useAxios()` adds what the XHR adapter cannot:
+
+- the `params` object as axios received it, rather than a re-parsed query string
+- Node's `http` adapter, which no global patch can reach
+- correct handling of axios's habit of rejecting on non-2xx while still having a
+  response
+
+A call seen by both adapters is recorded **once**. axios builds and opens its
+XHR synchronously inside its adapter, so the tracer raises a flag around the
+adapter call that is still up when `open` runs and down before anything else can
+start a request. The suppression is exact, not time-based.
+
+`useAxios()` wraps the instance's adapter rather than only its interceptors,
+because the adapter is the one place both the request and the raw response are
+available. If your application later assigns `axios.defaults.adapter` — a mock,
+a retry library, a custom transport — tracing survives it: the property is an
+accessor that routes the assignment underneath the wrapper.
+
+`destroy()` gives every instance back the adapter it last had, including
+instances created through the patched `create()`.
+
+## What the tracer will not do to your app
+
+Removing it changes nothing. Specifically:
+
+- responses are read through `Response.clone()`, **after** the original has been
+  handed back, so your `.json()` still works
+- `text/event-stream` responses are never buffered
+- binary and non-textual responses are described, not read
+- request bodies that are streams are never consumed
+- errors are rethrown exactly as they arrived; aborts stay `AbortError`
+- `AbortSignal`, redirects, credentials and headers pass through untouched
+- nothing is retried, and no request is made twice
+- XHR is observed with `addEventListener`, never by taking `onload` or
+  `onreadystatechange` — those belong to the caller
+- a subscriber that throws is caught
+- `destroy()` restores every patched global
+
+## Cleanup
+
+```ts
+apiTracer.destroy();
+```
+
+Restores `fetch`, the `XMLHttpRequest` prototype and every axios adapter, clears
+the subscribers, and stops reporting. `fetch` is only restored if nothing else
+has patched it since — clobbering another tool's interceptor on the way out
+would be worse than leaving ours in place.
+
+Calling `destroy()` on a tracer that was never started is safe.