@hakam-aldeen-kh/blix 0.6.1 → 0.8.0

package/README.md

@@ -123,8 +123,8 @@ register last.
 > interceptors become FIFO and the request-side rule flips to "register
 > `attachHttpMonitor` **first**" — while the response-side rule still says
 > last, so the two orders no longer agree and you must pick which leg matters
-> more. Response-interceptor order is unaffected by the flag. Blix does not
-> read this flag and cannot detect the situation.
+> more. Response-interceptor order is unaffected by the flag. Blix warns once,
+> in development, when a request carries the flag set to `false`.
 
 ```ts
 // src/network/axios.ts
@@ -188,8 +188,8 @@ instance.interceptors.response.use(undefined, (error) =>
 
 The consequence is silent and total: **every non-2xx request stays `pending`
 in the panel for the rest of the session.** No error, no warning, no Failed
-filter. (The 30-second pending cap only bounds how far the row's duration bar
-grows; it does not resolve the entry.)
+filter. Nothing times the row out either: its duration keeps counting for as
+long as the page stays open.
 
 Two ways out, and you currently have to choose one:
 
@@ -211,6 +211,45 @@ Two ways out, and you currently have to choose one:
 From a single `attachHttpMonitor` call you cannot currently have both plaintext
 request bodies and correlated errors while also discarding the `AxiosError`.
 
+#### Response interceptors that unwrap
+
+The same thing happens on the success path. A response interceptor registered
+before Blix that returns something other than the response —
+`(response) => response.data` is the usual one — hands Blix a value with no
+`config` on it, so there is nothing to correlate:
+
+- your request is unaffected: your code receives exactly what your interceptor
+  returned. (Before 0.7.0 Blix threw at this point, and every request on the
+  instance failed.)
+- the entry **stays `pending`** for the rest of the session. Blix does not
+  settle a request it cannot see settle.
+
+Register the unwrapping interceptor **after** `attachHttpMonitor` — response
+interceptors run in registration order, so Blix then sees the full response
+first — or unwrap at the call site instead.
+
+#### Which request headers the panel shows
+
+Blix's request interceptor runs before yours, so when it runs, the headers your
+interceptors add — auth, tracing, signing, locale — do not exist yet, and
+neither does the `Content-Type` axios sets itself. So the panel shows the
+headers the request **settled** with, re-read from the config axios hands back
+with the response or the error, and masked the same way. Until then — and for
+good, for a request that never settles or whose rejection carries no `config` —
+it shows the snapshot taken when the request started. JWT claims follow the same
+rule.
+
+Some headers never appear, because axios's adapter adds them to its own copy of
+the config, past the last point Blix can read:
+
+- **`Authorization: Basic …` from the `auth` option.** When `auth` is set, the
+  panel keeps the `Authorization` it saw when the request started: the settled
+  config still shows whatever your interceptors set, which is not what was
+  sent. Every other header is still taken from the settled config.
+- **The XSRF header** (`X-XSRF-TOKEN` by default).
+- **Headers the browser manages itself** — `Cookie`, `Origin`, `User-Agent` and
+  the like. Chrome's Network tab shows them; JavaScript never sees them.
+
 #### Encrypted payloads — `captureEncrypted(config, payload)`
 
 *Since 0.3.0.*
@@ -747,16 +786,17 @@ The panel is one header, one rail and two panes.
 Query. They are not filters over one table: each has its own columns and its
 own notion of a row, so switching source switches the whole view. `1`–`4` jump
 between them, and each keeps its own selection, so stepping to Redux and back
-returns you to the request you were reading. Below the sources it carries the
-session totals, and it collapses to icons — click the chevron, or let a narrow
-dock do it for you.
+returns you to the request you were reading. Each row ends with its own number
+key, because a shortcut is best taught where it is used. Below the sources it
+carries the session totals; collapsed, it keeps the sources and their counts
+and drops the totals, since four numbers without their labels are four
+unattributed numbers.
 
 **The header is the session**, not the entry: whether capture is running, what
-is being filtered out, and where the panel lives. Filter tokens you have
-already applied become chips *inside* the filter field, each removable on its
-own, so `method:post status:5xx` is two things you can undo separately rather
-than one string to re-edit. `.*` widens the search to request and response
-bodies.
+is being filtered out, and where the panel lives. While a filter is on, the
+field carries its own count — `8 of 56` — and a clear button, so you never
+have to read the status bar to know one is applied. `.*` widens the search to
+request and response bodies.
 
 **`Ctrl/⌘ K` opens the command palette**, and for several things it is the only
 way in — sort order, row density, dock position, the copy formats, the filter
@@ -765,6 +805,13 @@ reach for occasionally lives one keystroke away instead of costing a button
 each. Every row shows its key binding where it has one, so the palette teaches
 its own shortcuts. `?` still opens the full cheatsheet.
 
+**The columns are yours.** Right-click the column head — or open **Columns** in
+the overflow menu — and switch off any of Pin, Method, Size, Status, Time,
+Linked and Timing. The choice persists. ROUTE has no switch: it is the column
+that says *which* entry a row is, and a list of rows you cannot identify is not
+a list. A narrow pane drops columns on its own, worst-affordable first, so the
+route keeps the width it needs.
+
 **Linked events tie the sources together.** When Blix can see that a query
 caused a request, that a request came from a query, or that one entry is a
 replay of another, the row grows a coloured tick and the foot of the detail
@@ -821,6 +868,8 @@ says what it will contain before you pick a format.
 
 Captured `Authorization` headers are masked, so cURL and fetch output carries a
 placeholder rather than a working token — use **Replay** for a real re-run.
+Every export and snippet stays masked even with Authorization shown in full in
+the panel (see [What is redacted](#what-is-redacted)).
 
 ### Themes
 
@@ -854,14 +903,18 @@ panel's other preferences and survives a reload.
 The panel never inherits your app's styling — it portals outside every stacking
 context and ships its own palettes, so nothing you do to your own theme can
 distort it. Themes are complete rather than partial: every colour the panel
-paints, down to the JSON syntax highlighting and the duration bars, comes from
-the active theme. Each palette is checked against WCAG contrast targets — 4.5:1
-for anything read as text, 3:1 for badges and quiet chrome — which is why a few
-of the ported palettes differ by a shade from the originals in the slots used
-for dense monospace.
-
-There is no API for adding your own; a theme is ~20 colours in
-`src/ui/themes/themes.ts` if you are working from source.
+paints, down to the JSON syntax highlighting and the timing bars, comes from
+the active theme. The two tones that carry text are held to 4.5:1 against every
+ground they land on, which is why a few of the ported palettes differ by a
+shade from the originals in the slots used for dense monospace. One tone is
+deliberately below it and may never hold text: it is for separators, payload
+punctuation and disabled glyphs.
+
+There is no API for adding your own; a theme is 33 colour slots in
+`src/ui/themes/bx.ts` if you are working from source. Every theme fills the
+same set — a theme that cannot is reported in the console during development,
+along with any whose text tones fall under 4.5:1 on a ground they actually
+land on.
 
 ### `dbName` — when you need it
 
@@ -1106,6 +1159,54 @@ Shorter values are replaced outright. The Headers tab tags every masked row
 `MASKED` rather than leaving you to infer it from an ellipsis, and the stored
 value keeps a `(masked)` suffix so every export path carries the fact too.
 
+#### Showing `Authorization` in full
+
+Blix is development-only, and a developer reading their own token on their own
+screen is not the risk — the token leaving the machine is. So masking of
+`authorization`, and only `authorization`, can be switched off: command palette
+→ **Show Authorization values in full**, or **⋯ More actions** → **Show
+Authorization in full**. It is a saved preference, off by default, and while it
+is on the status bar reads **UNMASKED Authorization** and every such row in the
+Headers tab is tagged `UNMASKED`.
+
+- It applies to requests captured **after** it is switched on. Earlier entries
+  were masked when they were captured — the full value was never kept — and
+  the panel cannot reveal them; their row says so. An axios request re-reads
+  its headers when it settles (see
+  [Which request headers the panel shows](#which-request-headers-the-panel-shows)),
+  so for one still in flight what counts is the setting at the moment it
+  settles.
+- The full value is held in memory only. It is **never** written to IndexedDB,
+  and **every** export and copy path — HAR, JSON, NDJSON, CSV, Markdown, the
+  cURL script, **Copy as cURL** and **Copy as fetch** — still carries the
+  masked value. The row's own **Copy** button is the one way to take the full
+  value.
+- Masking again discards every full value held.
+- `cookie`, `set-cookie`, `x-api-key` and realtime connect tokens stay masked
+  regardless.
+
+#### JWT claims
+
+When an `Authorization` value is a JWT, Blix decodes it — for axios when the
+request settles, for `fetch` when it is made — and keeps only `alg`, `sub`,
+`iss`, `iat` and `exp`, never the token or its signature.
+The **JWT** chip on that row opens them, with the time left until `exp`, in red
+once it has passed. This works with masking on. The signature is not verified,
+and a value that is not a well-formed JWT stores no claims at all. The claims
+say where they were read: when a `fetch` call was made, from the headers an
+axios request settled with, or — for an axios request that never settled, or
+used the `auth` option — when it started.
+
+`alg` is shown but never acted on: a missing, empty or non-string `alg` still
+yields every other claim, and no value of it withholds anything. The XML-DSig
+URIs .NET writes into `alg` — `http://www.w3.org/2001/04/xmldsig-more#hmac-sha256`
+and its HMAC, RSA, RSA-PSS and ECDSA siblings — are shown by name, as
+`HMAC-SHA256 (HS256)`, with the raw value in the tooltip; the entry and the
+exports keep the raw value. An `alg` of `none`, in any letter case, is flagged
+as an unsigned token. The claims
+are part of the entry, so — unlike the token — they are saved with
+preserve-log on and included in the JSON and NDJSON exports.
+
 **Nothing inside a body is redacted.** Request bodies, response bodies, error
 payloads, the encrypted request/response values, Redux payloads and diffs, and
 realtime frames all pass through a size-only walker — it truncates large