@piwitests/instrumentation-nitro 0.36.0 → 0.38.0

package/README.md

@@ -4,9 +4,9 @@ Nitro / Nuxt server plugin for [Piwi Dashboard](https://piwitests.dev) — captu
 
 During a Playwright test run, the reporter reads this header from every response and stores the entries alongside the network request. The entries are then available in the Piwi Dashboard test-case view and are included in the AI diagnosis context.
 
-**Active outside production by default.** Capture is controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
+**Active in development and test only, by default.** Capture and probe verification run only outside production, using the same Development/Test allow-list as the ASP.NET package. Controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
 
-- unset — capture is on, except when `NODE_ENV === 'production'`
+- unset — capture is on when `NODE_ENV` is unset, `development`, or `test`; off for any other value (`production`, `staging`, `prod`, …)
 - `PIWI_TEST_LOGS_DISABLED=true` — capture is off everywhere
 - `PIWI_TEST_LOGS_DISABLED=false` — capture is on even in production builds (useful for a production-mode test deployment)
 
@@ -71,6 +71,65 @@ The plugin wraps Nitro's root H3 handler and uses three mechanisms:
 2. **`AsyncLocalStorage.run()`** — scopes that buffer around the entire downstream chain (hooks, middleware, route handlers), so the process-global `consola` reporter always appends to the correct request's buffer.
 3. **A patched `res.end`** — the header is written just before the response goes out, which covers **every** response, including H3 error responses that bypass Nitro's `beforeResponse` hook. Right before writing, unhandled errors are drained from `event.context.nitro.errors`, so thrown errors appear even when nothing logged via consola.
 
+## Server probes — the `X-Piwi-Probe` header
+
+The plugin accepts a signed fault instruction from a Piwi probe run (Test Map,
+level two), so a passing test can be checked against the server's real error
+path. A verified header is always recorded on the request scope
+(`event.context._piwiProbe`); a fault is **applied** only once a project turns
+server probes on (`PIWI_SERVER_PROBES=true`), which stays off by default.
+
+The header is honored only outside production, under the **same guard as log
+capture** (`PIWI_TEST_LOGS_DISABLED`), and only when a shared secret is set:
+
+| Variable             | Effect                                                             |
+|----------------------|-------------------------------------------------------------------|
+| `PIWI_PROBE_SECRET`  | Shared HMAC secret. When unset, the probe header is ignored.      |
+| `PIWI_SERVER_PROBES` | `true` to apply verified faults to the signed request.            |
+
+**Faults applied** (to the one request the probe run signs — the reporter picks
+the Nth match and signs that request, so the plugin applies the fault to any
+request the header matches and the single-use nonce keeps it from repeating;
+gated per project on the dashboard side): `throw`, `status`/`auth` (run the
+server's error path with a
+500/401), `delay`/`slow`/`slow-first` (+5s), `extreme` (empty default),
+`data`/`drop-field`/`empty-body` (mutate the response before serialization), and
+`dependency` (fail one outbound `$fetch` whose URL names the targeted
+dependency; when no call matches, nothing is applied). The plugin reports
+the fault it actually applied in `X-Piwi-Trace` (root-span `piwi.probe.applied`),
+so a probe the server did not honor is recorded as **inconclusive**, never a pass.
+
+**Entry condition.** Turn this on when the client probes (level one) report
+"not-noticed" on at least one in ten probed pairs across your pilot projects —
+that is the signal the suite has false comfort the network boundary cannot reveal.
+
+**Header format.** `X-Piwi-Probe` carries a base64-encoded JSON envelope:
+
+```jsonc
+{
+  "nonce": "<hex, single use>",
+  "ts": 1700000000000,            // issued-at, Unix ms; honored within 60s
+  "specJson": "{\"route\":\"POST /api/orders\",\"fault\":\"status-500\",\"nth\":1}",
+  "sig": "<hex HMAC-SHA256>"      // over `${nonce}.${ts}.${specJson}` with PIWI_PROBE_SECRET
+}
+```
+
+`specJson` is the exact JSON string that was signed (the plugin re-parses it
+after the signature check, so no canonicalization is needed). A verified spec is
+exposed on `event.context._piwiProbe` for future handler use. The signing and
+verification helpers are exported (`signProbeMessage`, `verifyProbeHeader`).
+
+> **Single-use nonces are tracked per process.** The plugin remembers honored
+> nonces in memory to reject replays within the 60s TTL, so a header replayed to a
+> *different* instance behind a load balancer — or after a restart — is not
+> caught by the nonce check (the TTL and signature still bound it). Probe runs
+> target a single instance, so this is not a concern in practice; run the probed
+> server as one instance if you need the replay guard to be exact.
+
+The root request span also carries the matched handler's source file as
+`attrs['piwi.handler']` when Nitro exposes it, so the dashboard can attribute a
+route to its handler by observation rather than by convention.
+
 ## Peer dependencies
 
 | Package     | Version   |

package/dist/faults.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Server-probe fault classes (Test Map, level two) — the pure decisions the
+ * plugin applies to one signed request. Kept side-effect-free so each class is
+ * unit-tested without a running server; the plugin owns the throwing, delaying
+ * and outbound-call interception these describe.
+ */
+/** A verified probe fault instruction for one request. */
+export interface ProbeFaultSpec {
+    /** Route key `METHOD /pattern` the fault targets, when scoped to one route. */
+    route?: string;
+    /** The fault class to apply. */
+    fault: string;
+    /** Apply to the Nth matching request (1-based); defaults to 1. */
+    nth?: number;
+    /** Dependency name a dependency fault targets, when scoped. */
+    dependency?: string;
+}
+/** The HTTP status a fault forces on the response, or null when it forces none. */
+export declare function faultStatus(fault: string): number | null;
+/** The delay (ms) a timing fault adds before the response, or 0 for none. */
+export declare function faultDelayMs(fault: string): number;
+/** A handler fault throws inside the handler so the server's error path runs. */
+export declare function isThrowFault(fault: string): boolean;
+/** An extreme fault returns the handler's empty/default value. */
+export declare function isExtremeFault(fault: string): boolean;
+/** A data fault mutates the response object before serialization. */
+export declare function isDataFault(fault: string): boolean;
+/** A dependency fault fails or delays one outbound call the handler makes. */
+export declare function isDependencyFault(fault: string): boolean;
+/**
+ * Apply a data fault to a response body before serialization: `empty-body`
+ * empties it, `drop-field` removes the first own key of an object, `data` nulls
+ * the first own key. Anything else is returned unchanged.
+ */
+export declare function mutateResponseBody(fault: string, body: unknown): unknown;
+/**
+ * True when a probe spec's route targets this request. An unscoped spec (no
+ * route) matches every request. The reporter signs the header onto exactly the
+ * request it wants faulted, so a route match is the whole selector server-side —
+ * the `nth` occurrence is chosen by the reporter, never re-counted here.
+ */
+export declare function routeMatchesRequest(spec: ProbeFaultSpec, method: string, path: string): boolean;
+/** True when an outbound call's target names the dependency a fault is scoped to. */
+export declare function dependencyCallMatches(dependency: string | undefined, target: string): boolean;
+/** The label reported in X-Piwi-Trace for the fault the server actually applied. */
+export declare function appliedFaultLabel(spec: ProbeFaultSpec): string;

package/dist/faults.js

@@ -0,0 +1,119 @@
+/**
+ * Server-probe fault classes (Test Map, level two) — the pure decisions the
+ * plugin applies to one signed request. Kept side-effect-free so each class is
+ * unit-tested without a running server; the plugin owns the throwing, delaying
+ * and outbound-call interception these describe.
+ */
+const DELAY_MS = 5000;
+/** The HTTP status a fault forces on the response, or null when it forces none. */
+export function faultStatus(fault) {
+    switch (fault) {
+        case 'status':
+        case 'status-500':
+            return 500;
+        case 'auth':
+            return 401;
+        default:
+            return null;
+    }
+}
+/** The delay (ms) a timing fault adds before the response, or 0 for none. */
+export function faultDelayMs(fault) {
+    return fault === 'delay' || fault === 'slow' || fault === 'slow-first' ? DELAY_MS : 0;
+}
+/** A handler fault throws inside the handler so the server's error path runs. */
+export function isThrowFault(fault) {
+    return fault === 'throw';
+}
+/** An extreme fault returns the handler's empty/default value. */
+export function isExtremeFault(fault) {
+    return fault === 'extreme';
+}
+/** A data fault mutates the response object before serialization. */
+export function isDataFault(fault) {
+    return fault === 'data' || fault === 'drop-field' || fault === 'empty-body';
+}
+/** A dependency fault fails or delays one outbound call the handler makes. */
+export function isDependencyFault(fault) {
+    return fault === 'dependency';
+}
+/**
+ * Apply a data fault to a response body before serialization: `empty-body`
+ * empties it, `drop-field` removes the first own key of an object, `data` nulls
+ * the first own key. Anything else is returned unchanged.
+ */
+export function mutateResponseBody(fault, body) {
+    if (fault === 'empty-body')
+        return Array.isArray(body) ? [] : typeof body === 'string' ? '' : {};
+    if (!body || typeof body !== 'object')
+        return body;
+    if (Array.isArray(body))
+        return fault === 'drop-field' ? [] : body;
+    const keys = Object.keys(body);
+    if (keys.length === 0)
+        return body;
+    const clone = { ...body };
+    const first = keys[0];
+    if (fault === 'drop-field')
+        delete clone[first];
+    else if (fault === 'data')
+        clone[first] = null;
+    return clone;
+}
+/** Split a route key into method + path pattern (`POST /api/orders` → …). */
+function parseRouteKey(routeKey) {
+    const space = routeKey.indexOf(' ');
+    if (space < 0)
+        return { method: '', pattern: routeKey };
+    return { method: routeKey.slice(0, space).toUpperCase(), pattern: routeKey.slice(space + 1) };
+}
+/** True when a concrete request matches a route pattern with `:param` segments. */
+function pathMatchesPattern(pattern, path) {
+    const p = (pattern.split('?')[0] ?? pattern).split('/').filter(Boolean);
+    const a = (path.split('?')[0] ?? path).split('/').filter(Boolean);
+    if (p.length !== a.length)
+        return false;
+    for (let i = 0; i < p.length; i++) {
+        const seg = p[i];
+        if (seg.startsWith(':') || (seg.startsWith('[') && seg.endsWith(']')) || (seg.startsWith('{') && seg.endsWith('}')))
+            continue;
+        if (seg !== a[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * True when a probe spec's route targets this request. An unscoped spec (no
+ * route) matches every request. The reporter signs the header onto exactly the
+ * request it wants faulted, so a route match is the whole selector server-side —
+ * the `nth` occurrence is chosen by the reporter, never re-counted here.
+ */
+export function routeMatchesRequest(spec, method, path) {
+    if (!spec.route)
+        return true;
+    const { method: m, pattern } = parseRouteKey(spec.route);
+    if (m && m !== method.toUpperCase())
+        return false;
+    return pathMatchesPattern(pattern, path);
+}
+/** True when an outbound call's target names the dependency a fault is scoped to. */
+export function dependencyCallMatches(dependency, target) {
+    if (!dependency)
+        return true;
+    if (!target)
+        return false;
+    const needle = dependency.toLowerCase();
+    const hay = target.toLowerCase();
+    if (hay.includes(needle))
+        return true;
+    try {
+        return new URL(target).host.toLowerCase().includes(needle);
+    }
+    catch {
+        return false;
+    }
+}
+/** The label reported in X-Piwi-Trace for the fault the server actually applied. */
+export function appliedFaultLabel(spec) {
+    return spec.dependency ? `${spec.fault}:${spec.dependency}` : spec.fault;
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import type { NitroAppPlugin } from 'nitropack';
+export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, type PiwiProbeSpec, type SignedProbe, } from './probe';
+export { buildRouteManifest, recordObservedRoute, collapsePathPattern, type RouteManifest } from './manifest';
+export * from './faults';
 export interface PiwiTestLogEntry {
     timestamp: number;
     level: string;

package/dist/index.js

@@ -2,6 +2,13 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomBytes } from 'node:crypto';
 import { gzipSync } from 'node:zlib';
 import { consola } from 'consola';
+import { createError } from 'h3';
+import { verifyProbeHeader, ProbeNonceCache } from './probe';
+import { buildRouteManifest, recordObservedRoute, collapsePathPattern, } from './manifest';
+import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults';
+export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe';
+export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest';
+export * from './faults';
 const MAX_ENTRIES = 50;
 const MAX_MSG_LENGTH = 500;
 const MAX_STACK_FRAMES = 5;
@@ -40,6 +47,17 @@ function parseTraceparent(tp) {
         return parts[1];
     return undefined;
 }
+/**
+ * Record the fault the server actually applied for this request, so X-Piwi-Trace
+ * carries it and the reporter can compare it with the fault it asked for. Called
+ * only at the point a fault takes effect, never on a bare route match.
+ */
+function markProbeApplied(store) {
+    if (store.probe)
+        store.probeApplied = appliedFaultLabel(store.probe);
+}
+/** Signed probe nonces already honored this process, so a header is single-use. */
+const probeNonces = new ProbeNonceCache();
 // Links consola calls and recorded spans to the request being handled. The store
 // is scoped with als.run() around the whole downstream handler chain —
 // enterWith() from a request hook is not reliable here (the binding dies with
@@ -58,8 +76,43 @@ export function recordServerSpan(span) {
 }
 // The consola reporter is process-global — register it only once.
 let reporterAdded = false;
+// Capture and probe verification run only outside production, matching the
+// ASP.NET package's Development/Test allow-list: only an unset/empty NODE_ENV or
+// `development`/`test` is treated as non-production. Any other value
+// (`production`, `staging`, `prod`, …) disables capture unless
+// PIWI_TEST_LOGS_DISABLED is explicitly `false`, so a signed probe header is
+// never honored on a production-like deployment that skipped `NODE_ENV=production`.
+const NODE_ENV = process.env.NODE_ENV;
+const IS_DEV_OR_TEST = !NODE_ENV || NODE_ENV === 'development' || NODE_ENV === 'test';
 const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
-    (process.env.NODE_ENV === 'production' && process.env.PIWI_TEST_LOGS_DISABLED !== 'false');
+    (!IS_DEV_OR_TEST && process.env.PIWI_TEST_LOGS_DISABLED !== 'false');
+/** The shared secret a probe run signs the `X-Piwi-Probe` header with. */
+const PROBE_SECRET = process.env.PIWI_PROBE_SECRET || undefined;
+/** The declared-surface route path the plugin serves outside production. */
+const MANIFEST_PATH = '/__piwi/manifest';
+/**
+ * Routes the server has matched this process, accumulated for `/__piwi/manifest`.
+ * Nitro exposes no runtime route table, so the manifest is built from observation.
+ */
+const observedRoutes = new Map();
+/**
+ * Server probes stay off unless a project opts in. When off (the default in this
+ * milestone) a signed probe header is still verified and recorded, but no fault
+ * is applied — only the client-safe subset would ever be, and only once this is
+ * on.
+ */
+const SERVER_PROBES_ENABLED = process.env.PIWI_SERVER_PROBES === 'true';
+/**
+ * Best-effort source file of the matched route handler, for the root span's
+ * `piwi.handler` attribute. Nitro exposes the matched route on the event context
+ * on recent versions; when it carries no file, the attribute is omitted and the
+ * dashboard falls back to its file-routing convention.
+ */
+function resolveHandlerFile(event) {
+    const matched = event?.context?.matchedRoute;
+    const file = matched?.file ?? matched?.filename;
+    return typeof file === 'string' && file ? file : undefined;
+}
 const piwiTestLogs = (nitroApp) => {
     if (TEST_LOGS_DISABLED)
         return;
@@ -89,9 +142,49 @@ const piwiTestLogs = (nitroApp) => {
     // als.run() scope covers every hook, middleware, and route handler.
     const originalHandler = nitroApp.h3App.handler;
     nitroApp.h3App.handler = ((event) => {
+        // Serve the declared-surface manifest outside production (the plugin already
+        // returned early when log capture is disabled). Built from observed routes.
+        const requestPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
+        if (requestPath === MANIFEST_PATH) {
+            const res = event.node.res;
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(buildRouteManifest(observedRoutes)));
+            return;
+        }
         const store = { logs: [], spans: [], startMs: Date.now() };
         event.context._piwiLogs = store.logs;
         event.context._piwiSpans = store.spans;
+        // The beforeResponse hook fires outside this handler's async scope (it is
+        // driven by the layer above h3App.handler), so als.getStore() is unreliable
+        // there — reach the request store through the event context instead.
+        event.context._piwiStore = store;
+        // Verify a signed probe header, honored only outside production (under the
+        // same guard as log capture) and only when a shared secret is configured.
+        // The spec is recorded on the request scope, and a fault is applied only when
+        // server probes are turned on for the project and this is the Nth match.
+        const probe = verifyProbeHeader(event.node.req.headers['x-piwi-probe'], PROBE_SECRET, Date.now(), undefined, probeNonces);
+        if (probe) {
+            store.probe = probe;
+            event.context._piwiProbe = probe;
+            if (SERVER_PROBES_ENABLED) {
+                const method = String(event.method ?? event.node.req.method ?? 'GET');
+                const reqPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
+                // The reporter signs the header onto exactly the request it wants faulted
+                // (it already chose the Nth match), so a route match is the whole
+                // selector; the header's single-use nonce keeps it from applying twice.
+                // The fault is only *marked applied* where it actually takes effect (the
+                // handler wrap, the beforeResponse hook, or the outbound-call patch), so
+                // an unimplemented fault (`replay`) or a no-op (`data` on an array body)
+                // records inconclusive, never a false gap.
+                if (routeMatchesRequest(probe, method, reqPath)) {
+                    store.probeShouldApply = true;
+                    // A dependency fault only applies once a matching outbound call fires.
+                    if (isDependencyFault(probe.fault))
+                        store.probeDependencyPending = true;
+                }
+            }
+        }
         // Patch res.end so the X-Piwi-Logs / X-Piwi-Trace headers are injected for
         // ALL responses, including H3 error responses where Nitro bypasses the
         // 'beforeResponse' hook (h3 skips onBeforeResponse once the error handler
@@ -127,6 +220,12 @@ const piwiTestLogs = (nitroApp) => {
                 const path = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
                 const statusCode = Number(res.statusCode) || 0;
                 const traceId = parseTraceparent(event.node.req.headers['traceparent']) ?? randomBytes(16).toString('hex');
+                const handlerFile = resolveHandlerFile(event);
+                // Record this route for the declared-surface manifest. Prefer the matched
+                // route's own pattern; fall back to collapsing the concrete path.
+                const matchedPattern = event.context?.matchedRoute?.route;
+                const pattern = typeof matchedPattern === 'string' && matchedPattern ? matchedPattern : collapsePathPattern(path);
+                recordObservedRoute(observedRoutes, { method, pattern, handler: handlerFile });
                 const rootSpan = {
                     id: randomBytes(8).toString('hex'),
                     name: `${method} ${path}`.trim(),
@@ -135,7 +234,16 @@ const piwiTestLogs = (nitroApp) => {
                     durMs: Math.max(0, endMs - store.startMs),
                     status: statusCode >= 500 ? 'error' : 'ok',
                     traceId,
-                    attrs: { 'http.method': method, 'http.route': path, 'http.status_code': statusCode },
+                    attrs: {
+                        'http.method': method,
+                        'http.route': path,
+                        'http.status_code': statusCode,
+                        ...(handlerFile ? { 'piwi.handler': handlerFile } : {}),
+                        // A probe was signed for this request; `applied` names the fault the
+                        // server honored, or is absent when it was not applied (inconclusive).
+                        ...(store.probe ? { 'piwi.probe': store.probe.fault } : {}),
+                        ...(store.probeApplied ? { 'piwi.probe.applied': store.probeApplied } : {}),
+                    },
                 };
                 for (const s of store.spans)
                     if (!s.parentId)
@@ -145,7 +253,96 @@ const piwiTestLogs = (nitroApp) => {
             }
             return originalEnd(...args);
         };
-        return als.run(store, () => originalHandler(event));
+        return als.run(store, async () => {
+            // Apply the handler and pipeline faults inside the request scope. Delay
+            // faults slow the response; throw/status/auth run the server's error path;
+            // extreme returns the empty default. Each is marked applied only once it
+            // takes effect. Data and dependency faults are applied later (the
+            // beforeResponse hook and the outbound-fetch patch); an unimplemented fault
+            // (`replay`) matches none of these, so it is never marked applied.
+            const spec = store.probeShouldApply ? store.probe : undefined;
+            if (spec && !isDataFault(spec.fault) && !isDependencyFault(spec.fault)) {
+                const delayMs = faultDelayMs(spec.fault);
+                if (delayMs > 0)
+                    await new Promise((r) => setTimeout(r, delayMs));
+                if (isThrowFault(spec.fault)) {
+                    markProbeApplied(store);
+                    throw createError({ statusCode: 500, statusMessage: 'Piwi probe: injected error' });
+                }
+                const status = faultStatus(spec.fault);
+                if (status != null) {
+                    markProbeApplied(store);
+                    throw createError({ statusCode: status, statusMessage: `Piwi probe: injected ${status}` });
+                }
+                if (isExtremeFault(spec.fault)) {
+                    markProbeApplied(store);
+                    // Send the empty response ourselves: h3's toNodeListener ignores the
+                    // handler's return value, so returning '' here would never end the
+                    // node response and the probed request would hang until its timeout.
+                    res.statusCode = 200;
+                    res.end('');
+                    return '';
+                }
+                // A pure delay fault took effect once the delay elapsed.
+                if (delayMs > 0)
+                    markProbeApplied(store);
+            }
+            return originalHandler(event);
+        });
+    });
+    // Data faults mutate the response body before it is serialized and sent. The
+    // fault is marked applied only when the body actually changed — `data` on an
+    // array body, or an empty object, is left unchanged and records inconclusive.
+    nitroApp.hooks.hook('beforeResponse', (event, response) => {
+        const store = event.context?._piwiStore;
+        const probe = store?.probe;
+        if (store?.probeShouldApply && probe && isDataFault(probe.fault) && response && 'body' in response) {
+            const before = response.body;
+            const mutated = mutateResponseBody(probe.fault, before);
+            if (mutated !== before) {
+                response.body = mutated;
+                markProbeApplied(store);
+            }
+        }
     });
+    // Dependency faults fail one outbound call the handler makes through the
+    // instrumented `$fetch`, so the handler's own error handling runs. The fault
+    // targets the call whose URL names `spec.dependency`; when no outbound call
+    // matches, nothing is applied and the probe records inconclusive.
+    if (SERVER_PROBES_ENABLED) {
+        const g = globalThis;
+        if (typeof g.$fetch === 'function' && !g.$fetch.__piwiProbePatched) {
+            const original = g.$fetch;
+            const patched = (...args) => {
+                const store = als.getStore();
+                if (store?.probeDependencyPending &&
+                    store.probe &&
+                    isDependencyFault(store.probe.fault) &&
+                    !store.probeDependencyConsumed &&
+                    dependencyCallMatches(store.probe.dependency, outboundCallTarget(args))) {
+                    store.probeDependencyConsumed = true;
+                    markProbeApplied(store);
+                    return Promise.reject(new Error('Piwi probe: injected dependency failure'));
+                }
+                return original(...args);
+            };
+            patched.__piwiProbePatched = true;
+            g.$fetch = Object.assign(patched, original);
+        }
+    }
 };
+/** The request target of an outbound `$fetch` call, for dependency-fault matching. */
+function outboundCallTarget(args) {
+    const first = args[0];
+    if (typeof first === 'string')
+        return first;
+    if (first instanceof URL)
+        return first.toString();
+    if (first && typeof first === 'object') {
+        const url = first.url ?? first.href;
+        if (typeof url === 'string')
+            return url;
+    }
+    return '';
+}
 export default piwiTestLogs;

package/dist/manifest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
+ * outside production. Nitro has no stable public API to enumerate its route table
+ * at runtime, so the manifest is accumulated from the routes the server actually
+ * matches — each request contributes its method, matched pattern and handler
+ * file. The Piwi reporter fetches it once at run start and uploads it, and a
+ * declared route no test reaches becomes a "declared, never hit" gap.
+ */
+/** One declared route: method, path pattern and the handler's source file. */
+export interface ManifestRouteEntry {
+    method: string;
+    pattern: string;
+    handler?: string;
+}
+/** The manifest body served at `/__piwi/manifest`. */
+export interface RouteManifest {
+    routes: ManifestRouteEntry[];
+}
+/**
+ * Collapse a concrete request path to a pattern: numeric and uuid segments become
+ * `:id` / `:uuid`, so `/api/orders/42` and `/api/orders/43` fold to one route.
+ * Used only when the matched route carries no pattern of its own.
+ */
+export declare function collapsePathPattern(path: string): string;
+/**
+ * Record an observed route in the accumulator, keeping the first handler file
+ * seen for it. Bounded so a pathological app (or an unbounded set of patterns
+ * slipping through) cannot grow the map without limit.
+ */
+export declare function recordObservedRoute(map: Map<string, ManifestRouteEntry>, entry: ManifestRouteEntry, max?: number): void;
+/** Build the manifest body from the accumulator, routes sorted for stable output. */
+export declare function buildRouteManifest(map: Map<string, ManifestRouteEntry>): RouteManifest;

package/dist/manifest.js

@@ -0,0 +1,56 @@
+/**
+ * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
+ * outside production. Nitro has no stable public API to enumerate its route table
+ * at runtime, so the manifest is accumulated from the routes the server actually
+ * matches — each request contributes its method, matched pattern and handler
+ * file. The Piwi reporter fetches it once at run start and uploads it, and a
+ * declared route no test reaches becomes a "declared, never hit" gap.
+ */
+/**
+ * Collapse a concrete request path to a pattern: numeric and uuid segments become
+ * `:id` / `:uuid`, so `/api/orders/42` and `/api/orders/43` fold to one route.
+ * Used only when the matched route carries no pattern of its own.
+ */
+export function collapsePathPattern(path) {
+    const clean = path.split('?')[0] ?? path;
+    return ('/' +
+        clean
+            .split('/')
+            .filter(Boolean)
+            .map((seg) => {
+            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg))
+                return ':uuid';
+            if (/^\d+$/.test(seg))
+                return ':id';
+            return seg;
+        })
+            .join('/'));
+}
+/** The unique key for a route in the accumulator: method plus pattern. */
+function routeKey(method, pattern) {
+    return `${method.toUpperCase()} ${pattern}`;
+}
+/**
+ * Record an observed route in the accumulator, keeping the first handler file
+ * seen for it. Bounded so a pathological app (or an unbounded set of patterns
+ * slipping through) cannot grow the map without limit.
+ */
+export function recordObservedRoute(map, entry, max = 2000) {
+    if (!entry.method || !entry.pattern)
+        return;
+    const key = routeKey(entry.method, entry.pattern);
+    const existing = map.get(key);
+    if (existing) {
+        if (!existing.handler && entry.handler)
+            existing.handler = entry.handler;
+        return;
+    }
+    if (map.size >= max)
+        return;
+    map.set(key, { method: entry.method.toUpperCase(), pattern: entry.pattern, handler: entry.handler });
+}
+/** Build the manifest body from the accumulator, routes sorted for stable output. */
+export function buildRouteManifest(map) {
+    const routes = [...map.values()].sort((a, b) => routeKey(a.method, a.pattern).localeCompare(routeKey(b.method, b.pattern)));
+    return { routes };
+}

package/dist/probe.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Server-probe support (Piwi Test Map, level two). A probe run signs a fault
+ * spec into the `X-Piwi-Probe` request header; the instrumentation verifies the
+ * signature here and, when server probes are enabled, applies the fault inside
+ * the request scope. In this release the header is only parsed and verified —
+ * nothing is applied unless a project turns server probes on, which stays off by
+ * default (see the README).
+ */
+/** A fault the probe run asks the server to apply to one request. */
+export interface PiwiProbeSpec {
+    /** Route pattern the fault targets, e.g. `POST /api/orders`. */
+    route?: string;
+    /** The fault to apply. The client-safe subset is applied first (see README). */
+    fault: string;
+    /** Apply only to the Nth matching request (1-based); default the first. */
+    nth?: number;
+    /** Dependency name a dependency fault targets, when scoped to one. */
+    dependency?: string;
+}
+/** The signed envelope carried in the `X-Piwi-Probe` header (base64 JSON). */
+export interface SignedProbe {
+    /** Single-use nonce, hex. */
+    nonce: string;
+    /** Issued-at, Unix epoch milliseconds — the TTL is measured from here. */
+    ts: number;
+    /** The exact JSON string of the {@link PiwiProbeSpec} that was signed. */
+    specJson: string;
+    /** Hex HMAC-SHA256 over `${nonce}.${ts}.${specJson}` with the shared secret. */
+    sig: string;
+}
+/** Default probe header lifetime — a probe is honored within a minute of issue. */
+export declare const PROBE_TTL_MS = 60000;
+/** The message signed and verified for a probe: nonce, timestamp and spec JSON. */
+export declare function probeSigningMessage(nonce: string, ts: number, specJson: string): string;
+/** Compute the hex HMAC-SHA256 signature for a probe envelope. */
+export declare function signProbeMessage(secret: string, nonce: string, ts: number, specJson: string): string;
+/**
+ * A TTL-bounded set of probe nonces already honored, so a signed header is
+ * single-use: a replay within the TTL is rejected. Entries prune lazily on each
+ * use, bounding memory to the probes seen within one TTL window.
+ */
+export declare class ProbeNonceCache {
+    private readonly ttlMs;
+    private readonly seen;
+    constructor(ttlMs?: number);
+    /** Record a nonce as used; returns false when it was already used within the TTL. */
+    use(nonce: string, nowMs: number): boolean;
+}
+/**
+ * Verify a signed probe header and return its fault spec, or null when the
+ * header is absent, malformed, past its TTL, or fails the signature check. Pure
+ * over its inputs (no environment reads) so it can be unit-tested directly.
+ */
+export declare function verifyProbeHeader(headerValue: string | string[] | undefined, secret: string | undefined, nowMs: number, ttlMs?: number, seen?: ProbeNonceCache): PiwiProbeSpec | null;

package/dist/probe.js

@@ -0,0 +1,87 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** Default probe header lifetime — a probe is honored within a minute of issue. */
+export const PROBE_TTL_MS = 60_000;
+/** The message signed and verified for a probe: nonce, timestamp and spec JSON. */
+export function probeSigningMessage(nonce, ts, specJson) {
+    return `${nonce}.${ts}.${specJson}`;
+}
+/** Compute the hex HMAC-SHA256 signature for a probe envelope. */
+export function signProbeMessage(secret, nonce, ts, specJson) {
+    return createHmac('sha256', secret).update(probeSigningMessage(nonce, ts, specJson)).digest('hex');
+}
+/**
+ * A TTL-bounded set of probe nonces already honored, so a signed header is
+ * single-use: a replay within the TTL is rejected. Entries prune lazily on each
+ * use, bounding memory to the probes seen within one TTL window.
+ */
+export class ProbeNonceCache {
+    constructor(ttlMs = PROBE_TTL_MS) {
+        this.ttlMs = ttlMs;
+        this.seen = new Map();
+    }
+    /** Record a nonce as used; returns false when it was already used within the TTL. */
+    use(nonce, nowMs) {
+        for (const [n, expiry] of this.seen)
+            if (expiry <= nowMs)
+                this.seen.delete(n);
+        if (this.seen.has(nonce))
+            return false;
+        this.seen.set(nonce, nowMs + this.ttlMs);
+        return true;
+    }
+}
+/** Constant-time hex-signature comparison; false on any length or format mismatch. */
+function signaturesEqual(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Verify a signed probe header and return its fault spec, or null when the
+ * header is absent, malformed, past its TTL, or fails the signature check. Pure
+ * over its inputs (no environment reads) so it can be unit-tested directly.
+ */
+export function verifyProbeHeader(headerValue, secret, nowMs, ttlMs = PROBE_TTL_MS, seen) {
+    if (!secret)
+        return null;
+    const raw = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (!raw)
+        return null;
+    let envelope;
+    try {
+        envelope = JSON.parse(Buffer.from(raw, 'base64').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!envelope || typeof envelope !== 'object')
+        return null;
+    const { nonce, ts, specJson, sig } = envelope;
+    if (typeof nonce !== 'string' || typeof ts !== 'number' || typeof specJson !== 'string' || typeof sig !== 'string') {
+        return null;
+    }
+    // TTL: reject an expired or not-yet-valid (clock-skewed future) probe.
+    if (!Number.isFinite(ts) || nowMs - ts > ttlMs || ts - nowMs > ttlMs)
+        return null;
+    const expected = signProbeMessage(secret, nonce, ts, specJson);
+    if (!signaturesEqual(sig, expected))
+        return null;
+    let spec;
+    try {
+        spec = JSON.parse(specJson);
+    }
+    catch {
+        return null;
+    }
+    if (!spec || typeof spec !== 'object' || typeof spec.fault !== 'string')
+        return null;
+    // Single-use: reject a replay of a nonce already honored within the TTL.
+    if (seen && !seen.use(nonce, nowMs))
+        return null;
+    return spec;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/instrumentation-nitro",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Nitro/Nuxt server plugin for sending backend logs to Piwi Dashboard via the X-Piwi-Logs response header",
   "homepage": "https://piwitests.dev",
   "repository": {
@@ -32,6 +32,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "files": [