@singhak/nodeui-core 0.1.0 → 0.3.1

package/dist/index.d.mts

@@ -1,5 +1,5 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
-import { ServerResponse, IncomingMessage } from 'node:http';
 
 /**
  * Shared typed contract for the NodeUI developer console.
@@ -8,7 +8,12 @@ import { ServerResponse, IncomingMessage } from 'node:http';
  * contract. Every provider returns a {@link ProviderResult}; every REST
  * endpoint returns an {@link ApiEnvelope} which is the same shape.
  */
-type PanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics';
+type BuiltInPanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics' | 'outgoing';
+/**
+ * Panel identifier. Built-in panels are listed in {@link BuiltInPanelId};
+ * plugins may register any other string id (lowercase letters, digits, `-`).
+ */
+type PanelId = BuiltInPanelId | (string & {});
 /** Resolved, validated console configuration. */
 interface NodeUIConfig {
     /** URL path prefix where the console and its API are served. Default `/nodeui`. */
@@ -35,6 +40,18 @@ interface NodeUIConfig {
     confirmTtlMs: number;
     /** Directory where heap snapshot files are written. */
     heapSnapshotDir: string;
+    /** Extra `Host` header hostnames accepted besides loopback names. */
+    allowedHosts: string[];
+    /** Extra `Origin` values accepted for cross-origin calls. */
+    allowedOrigins: string[];
+    /** Extra remote IPs / IPv4 CIDRs accepted (e.g. Docker bridge `172.17.0.0/16`). */
+    allowedRemoteAddresses: string[];
+    /** Accept requests carrying `X-Forwarded-*` headers. */
+    trustProxy: boolean;
+    /** Whether a shared access token is required. */
+    authRequired: boolean;
+    /** Maximum concurrent live (SSE) streams. */
+    maxSseClients: number;
 }
 /** Context handed to every provider call. */
 interface ProviderContext {
@@ -72,6 +89,8 @@ type ApiEnvelope<T> = ProviderResult<T>;
  */
 interface NodeUIProvider<T = unknown> {
     readonly id: PanelId;
+    /** Display label for plugin panels; defaults to the id. */
+    readonly title?: string;
     start?(ctx: ProviderContext): void;
     stop?(ctx: ProviderContext): void;
     get(ctx: ProviderContext): ProviderResult<T> | Promise<ProviderResult<T>>;
@@ -99,6 +118,12 @@ interface CpuData {
     totalPercent: number;
     sampleAtMs: number;
 }
+interface HealthCheckResult {
+    name: string;
+    status: 'up' | 'down';
+    durationMs: number;
+    error?: string;
+}
 interface HealthData {
     status: 'ok' | 'degraded' | 'critical' | 'unknown';
     statusReason: string;
@@ -108,6 +133,8 @@ interface HealthData {
     platform: string;
     eventLoopLagMs: number | null;
     memoryUsedPercent: number | null;
+    /** Results of user-registered dependency checks; empty when none. */
+    checks: HealthCheckResult[];
 }
 interface StartupMark {
     name: string;
@@ -128,9 +155,37 @@ interface RequestEntry {
     timestampMs: number;
     ip: string;
 }
+interface RouteStat {
+    method: string;
+    path: string;
+    count: number;
+    avgMs: number;
+    p95Ms: number;
+    errors: number;
+}
+interface RequestsSummary {
+    /** Requests currently held in the ring buffer. */
+    count: number;
+    errors: number;
+    /** `errors / count` in 0..1 (5xx only). */
+    errorRate: number;
+    avgMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    byStatus: {
+        '2xx': number;
+        '3xx': number;
+        '4xx': number;
+        '5xx': number;
+    };
+    /** Busiest/slowest routes, slowest p95 first (at most 8). */
+    routes: RouteStat[];
+}
 interface RequestsData {
     total: number;
     entries: RequestEntry[];
+    summary: RequestsSummary;
 }
 interface EnvEntry {
     key: string;
@@ -165,6 +220,21 @@ interface MetricsBucket {
 interface MetricsData {
     buckets: MetricsBucket[];
 }
+interface OutgoingRequestEntry {
+    id: number;
+    method: string;
+    /** Target as `host/path` (query string removed). */
+    url: string;
+    status: number | null;
+    durationMs: number;
+    timestampMs: number;
+    error?: string;
+}
+interface OutgoingData {
+    total: number;
+    failed: number;
+    entries: OutgoingRequestEntry[];
+}
 interface HeapSnapshotData {
     fileName: string;
     filePath: string;
@@ -194,6 +264,12 @@ interface ConfigData {
         enabled: boolean;
         pattern: string;
     };
+    locked: boolean;
+    /** Plugin panel ids and titles, in registration order. */
+    plugins: Array<{
+        id: PanelId;
+        title: string;
+    }>;
 }
 
 /** Replacement value used when masking secret values. */
@@ -222,6 +298,12 @@ declare class RingBuffer<T> {
 
 /** Keys whose values are redacted in any panel output. */
 declare const SECRET_KEY_PATTERN: RegExp;
+/**
+ * Redacts secrets embedded in free text: credentials in URLs
+ * (`postgres://user:pass@host`), bearer/basic tokens, JWTs and
+ * `password=...`-style pairs. Used for log lines and any string value.
+ */
+declare function maskSecretText(text: string): string;
 interface ActivationDecision {
     active: boolean;
     reason: string;
@@ -234,12 +316,53 @@ interface ActivationDecision {
 declare function resolveActivation(env: Record<string, string | undefined>): ActivationDecision;
 /** True when the socket address is a loopback address. */
 declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * True when `address` matches one of `allowed`, each an exact IP or an IPv4
+ * CIDR (e.g. `172.17.0.0/16`, the default Docker bridge network).
+ */
+declare function matchesAddress(address: string | undefined, allowed: readonly string[]): boolean;
+/** Extracts the lower-cased hostname from a `Host` header value (no port). */
+declare function hostnameFromHostHeader(value: string | undefined): string | null;
+/** True for the hostnames a browser uses to reach a loopback server. */
+declare function isLoopbackHostname(hostname: string | null): boolean;
 /**
  * Deep-clone a value, replacing any value under a key matching the secret
- * pattern with `[REDACTED]`. The input is not mutated.
+ * pattern with `[REDACTED]` and scrubbing secrets embedded in string values
+ * (URL credentials, bearer tokens, `password=...`). The input is not mutated.
  */
 declare function maskSecrets<T>(value: T, pattern?: RegExp): T;
 
+declare const AUTH_COOKIE = "nodeui_token";
+interface GuardOptions {
+    /** Configured console host; a loopback value enables the strict checks. */
+    host: string;
+    /** Extra `Host` header hostnames accepted (e.g. `myapp.local`). */
+    allowedHosts: readonly string[];
+    /** Extra `Origin` values accepted for cross-origin calls. */
+    allowedOrigins: readonly string[];
+    /** Extra remote IPs / IPv4 CIDRs accepted (e.g. `172.17.0.0/16` for Docker). */
+    allowedRemoteAddresses: readonly string[];
+    /** Accept requests carrying `X-Forwarded-*` headers. Default false. */
+    trustProxy: boolean;
+    /** When set, every request must present this token. */
+    authToken?: string;
+}
+type GuardResult = {
+    ok: true;
+    setToken?: string;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Builds the request guard for the console. It combines: loopback/remote
+ * address policy, `Host` validation (DNS-rebinding defence), `Origin`
+ * validation (cross-site request defence) and an optional shared token.
+ */
+declare function createGuard(options: GuardOptions): (req: IncomingMessage) => GuardResult;
+
 /**
  * Single-use, expiring confirmation nonces. Mutating actions (such as heap
  * snapshots) require a nonce issued here, presented via the
@@ -247,8 +370,9 @@ declare function maskSecrets<T>(value: T, pattern?: RegExp): T;
  */
 declare class ConfirmationStore {
     private readonly ttlMs;
+    private readonly maxOutstanding;
     private nonces;
-    constructor(ttlMs: number);
+    constructor(ttlMs: number, maxOutstanding?: number);
     issue(): ConfirmIssued;
     /** Consumes `nonce` and returns true only if it was valid and unexpired. */
     consume(nonce: string): boolean;
@@ -381,12 +505,45 @@ declare class EventLoopLagProvider implements NodeUIProvider<EventLoopSample> {
     };
 }
 
-/** Derives process + event-loop health from the latest sampled values. */
+/**
+ * A dependency check (database ping, cache ping, ...). Resolve for healthy,
+ * reject/throw (or resolve `false`) for unhealthy.
+ */
+type HealthCheck = () => unknown | Promise<unknown>;
+/** Derives process + event-loop health, plus optional dependency checks. */
 declare class HealthProvider implements NodeUIProvider<HealthData> {
+    private readonly checks;
     readonly id: "health";
-    get(ctx: ProviderContext): {
+    private cache;
+    constructor(checks?: Record<string, HealthCheck>);
+    private runChecks;
+    get(ctx: ProviderContext): Promise<{
         ok: true;
         data: HealthData;
+    }>;
+}
+
+type Recorder = (entry: Omit<OutgoingRequestEntry, 'id'>) => void;
+/**
+ * Refcounted instrumentation of outgoing HTTP calls made via `http`,
+ * `https` (axios, got, node-fetch, ...) and global `fetch` (undici). The
+ * first consumer installs the hooks, the last release restores everything.
+ */
+declare function interceptOutgoing(record: Recorder): () => void;
+/** Recent outgoing HTTP calls, recorded lazily while the panel is active. */
+declare class OutgoingProvider implements NodeUIProvider<OutgoingData> {
+    readonly id: "outgoing";
+    private buffer;
+    private nextId;
+    private failed;
+    private release;
+    constructor(size: number);
+    start(): void;
+    stop(): void;
+    record(entry: Omit<OutgoingRequestEntry, 'id'>): void;
+    get(): {
+        ok: true;
+        data: OutgoingData;
     };
 }
 
@@ -405,6 +562,7 @@ declare class HeapSnapshotProvider implements NodeUIProvider<HeapSnapshotPanelDa
     takeSnapshot(ctx: ProviderContext): Promise<ProviderResult<HeapSnapshotData>>;
 }
 
+declare function summarizeRequests(entries: readonly RequestEntry[]): RequestsSummary;
 /** Fixed-size ring buffer of recent HTTP requests, recorded via middleware hook. */
 declare class RequestsProvider implements NodeUIProvider<RequestsData> {
     readonly id: "requests";
@@ -521,7 +679,7 @@ interface SseStream {
  * Minimal Server-Sent Events writer over a raw HTTP response. Events are
  * emitted as `data: <json>\n\n`; heartbeats as `:ping\n\n`.
  */
-declare function startSse(res: ServerResponse): SseStream;
+declare function startSse(res: ServerResponse, extraHeaders?: Record<string, string>): SseStream;
 
 interface NodeUIOptions {
     /** URL path prefix. Default `/nodeui` (or `NODEUI_PATH`). */
@@ -548,8 +706,32 @@ interface NodeUIOptions {
     inactivityTimeoutMs?: number;
     /** TTL for mutation confirmation nonces. Default 60000. */
     confirmTtlMs?: number;
-    /** Directory for heap snapshot files. Defaults to the OS temp dir. */
+    /** Directory for heap snapshot files. Defaults to a private dir under the OS temp dir. */
     heapSnapshotDir?: string;
+    /** Extra `Host` hostnames accepted besides loopback names (or `NODEUI_ALLOWED_HOSTS`, comma-separated). */
+    allowedHosts?: string[];
+    /** Extra `Origin` values accepted for cross-origin calls (or `NODEUI_ALLOWED_ORIGINS`). */
+    allowedOrigins?: string[];
+    /**
+     * Extra remote IPs / IPv4 CIDRs accepted (or `NODEUI_ALLOWED_REMOTE`). Use
+     * `['172.16.0.0/12']` to reach the console from the host when the app runs in Docker.
+     */
+    allowedRemoteAddresses?: string[];
+    /** Accept requests carrying `X-Forwarded-*` headers (or `NODEUI_TRUST_PROXY=true`). Default false. */
+    trustProxy?: boolean;
+    /**
+     * Shared access token (or `NODEUI_TOKEN`). When set, open `/nodeui/?token=<token>` once;
+     * the browser then keeps an HttpOnly cookie. API clients may send `Authorization: Bearer`.
+     */
+    authToken?: string;
+    /** Maximum concurrent live (SSE) streams. Default 10. */
+    maxSseClients?: number;
+    /** Custom panels; each provider needs a unique lowercase id, e.g. `queues`. */
+    plugins?: NodeUIProvider[];
+    /** Named dependency checks (database, cache, ...) surfaced in the health panel. */
+    healthChecks?: Record<string, HealthCheck>;
+    /** Max recorded outgoing HTTP calls. Default 200. */
+    outgoingLogSize?: number;
 }
 interface NodeUIServer {
     readonly config: NodeUIConfig;
@@ -559,6 +741,11 @@ interface NodeUIServer {
     middleware(): NodeUIMiddleware;
     /** Direct request handling (no `next`); used for tests and adapters. */
     handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Supplies the route list directly (frameworks other than Express, e.g.
+     * Fastify's `onRoute`). Takes precedence over Express router introspection.
+     */
+    setRoutes(source: RouteEntry[] | (() => RouteEntry[])): void;
     /** Records a bootstrap timing mark, e.g. `mark("listening")`. */
     mark(name: string): void;
     /** Whether a background-sampling provider is currently running. */
@@ -576,7 +763,7 @@ type NodeUIMiddleware = (req: IncomingMessage, res: ServerResponse, next: () =>
  * Serializes an API envelope to JSON, applying secret masking so values
  * under keys like `TOKEN`/`KEY`/`SECRET`/`PASSWORD` never reach the UI.
  */
-declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>): string;
+declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>, mask?: boolean): string;
 declare function createNodeUI(options?: NodeUIOptions): NodeUIServer;
 
-export { type ActivationDecision, type ApiEnvelope, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, RingBuffer, type RouteEntry, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createNodeUI, extractRoutes, interceptConsole, isLoopbackAddress, maskSecrets, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse };
+export { AUTH_COOKIE, type ActivationDecision, type ApiEnvelope, type BuiltInPanelId, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type GuardOptions, type GuardResult, type HealthCheck, type HealthCheckResult, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type OutgoingData, OutgoingProvider, type OutgoingRequestEntry, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, type RequestsSummary, RingBuffer, type RouteEntry, type RouteStat, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createGuard, createNodeUI, extractRoutes, hostnameFromHostHeader, interceptConsole, interceptOutgoing, isLoopbackAddress, isLoopbackHostname, maskSecretText, maskSecrets, matchesAddress, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse, summarizeRequests };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
-import { ServerResponse, IncomingMessage } from 'node:http';
 
 /**
  * Shared typed contract for the NodeUI developer console.
@@ -8,7 +8,12 @@ import { ServerResponse, IncomingMessage } from 'node:http';
  * contract. Every provider returns a {@link ProviderResult}; every REST
  * endpoint returns an {@link ApiEnvelope} which is the same shape.
  */
-type PanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics';
+type BuiltInPanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics' | 'outgoing';
+/**
+ * Panel identifier. Built-in panels are listed in {@link BuiltInPanelId};
+ * plugins may register any other string id (lowercase letters, digits, `-`).
+ */
+type PanelId = BuiltInPanelId | (string & {});
 /** Resolved, validated console configuration. */
 interface NodeUIConfig {
     /** URL path prefix where the console and its API are served. Default `/nodeui`. */
@@ -35,6 +40,18 @@ interface NodeUIConfig {
     confirmTtlMs: number;
     /** Directory where heap snapshot files are written. */
     heapSnapshotDir: string;
+    /** Extra `Host` header hostnames accepted besides loopback names. */
+    allowedHosts: string[];
+    /** Extra `Origin` values accepted for cross-origin calls. */
+    allowedOrigins: string[];
+    /** Extra remote IPs / IPv4 CIDRs accepted (e.g. Docker bridge `172.17.0.0/16`). */
+    allowedRemoteAddresses: string[];
+    /** Accept requests carrying `X-Forwarded-*` headers. */
+    trustProxy: boolean;
+    /** Whether a shared access token is required. */
+    authRequired: boolean;
+    /** Maximum concurrent live (SSE) streams. */
+    maxSseClients: number;
 }
 /** Context handed to every provider call. */
 interface ProviderContext {
@@ -72,6 +89,8 @@ type ApiEnvelope<T> = ProviderResult<T>;
  */
 interface NodeUIProvider<T = unknown> {
     readonly id: PanelId;
+    /** Display label for plugin panels; defaults to the id. */
+    readonly title?: string;
     start?(ctx: ProviderContext): void;
     stop?(ctx: ProviderContext): void;
     get(ctx: ProviderContext): ProviderResult<T> | Promise<ProviderResult<T>>;
@@ -99,6 +118,12 @@ interface CpuData {
     totalPercent: number;
     sampleAtMs: number;
 }
+interface HealthCheckResult {
+    name: string;
+    status: 'up' | 'down';
+    durationMs: number;
+    error?: string;
+}
 interface HealthData {
     status: 'ok' | 'degraded' | 'critical' | 'unknown';
     statusReason: string;
@@ -108,6 +133,8 @@ interface HealthData {
     platform: string;
     eventLoopLagMs: number | null;
     memoryUsedPercent: number | null;
+    /** Results of user-registered dependency checks; empty when none. */
+    checks: HealthCheckResult[];
 }
 interface StartupMark {
     name: string;
@@ -128,9 +155,37 @@ interface RequestEntry {
     timestampMs: number;
     ip: string;
 }
+interface RouteStat {
+    method: string;
+    path: string;
+    count: number;
+    avgMs: number;
+    p95Ms: number;
+    errors: number;
+}
+interface RequestsSummary {
+    /** Requests currently held in the ring buffer. */
+    count: number;
+    errors: number;
+    /** `errors / count` in 0..1 (5xx only). */
+    errorRate: number;
+    avgMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    byStatus: {
+        '2xx': number;
+        '3xx': number;
+        '4xx': number;
+        '5xx': number;
+    };
+    /** Busiest/slowest routes, slowest p95 first (at most 8). */
+    routes: RouteStat[];
+}
 interface RequestsData {
     total: number;
     entries: RequestEntry[];
+    summary: RequestsSummary;
 }
 interface EnvEntry {
     key: string;
@@ -165,6 +220,21 @@ interface MetricsBucket {
 interface MetricsData {
     buckets: MetricsBucket[];
 }
+interface OutgoingRequestEntry {
+    id: number;
+    method: string;
+    /** Target as `host/path` (query string removed). */
+    url: string;
+    status: number | null;
+    durationMs: number;
+    timestampMs: number;
+    error?: string;
+}
+interface OutgoingData {
+    total: number;
+    failed: number;
+    entries: OutgoingRequestEntry[];
+}
 interface HeapSnapshotData {
     fileName: string;
     filePath: string;
@@ -194,6 +264,12 @@ interface ConfigData {
         enabled: boolean;
         pattern: string;
     };
+    locked: boolean;
+    /** Plugin panel ids and titles, in registration order. */
+    plugins: Array<{
+        id: PanelId;
+        title: string;
+    }>;
 }
 
 /** Replacement value used when masking secret values. */
@@ -222,6 +298,12 @@ declare class RingBuffer<T> {
 
 /** Keys whose values are redacted in any panel output. */
 declare const SECRET_KEY_PATTERN: RegExp;
+/**
+ * Redacts secrets embedded in free text: credentials in URLs
+ * (`postgres://user:pass@host`), bearer/basic tokens, JWTs and
+ * `password=...`-style pairs. Used for log lines and any string value.
+ */
+declare function maskSecretText(text: string): string;
 interface ActivationDecision {
     active: boolean;
     reason: string;
@@ -234,12 +316,53 @@ interface ActivationDecision {
 declare function resolveActivation(env: Record<string, string | undefined>): ActivationDecision;
 /** True when the socket address is a loopback address. */
 declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * True when `address` matches one of `allowed`, each an exact IP or an IPv4
+ * CIDR (e.g. `172.17.0.0/16`, the default Docker bridge network).
+ */
+declare function matchesAddress(address: string | undefined, allowed: readonly string[]): boolean;
+/** Extracts the lower-cased hostname from a `Host` header value (no port). */
+declare function hostnameFromHostHeader(value: string | undefined): string | null;
+/** True for the hostnames a browser uses to reach a loopback server. */
+declare function isLoopbackHostname(hostname: string | null): boolean;
 /**
  * Deep-clone a value, replacing any value under a key matching the secret
- * pattern with `[REDACTED]`. The input is not mutated.
+ * pattern with `[REDACTED]` and scrubbing secrets embedded in string values
+ * (URL credentials, bearer tokens, `password=...`). The input is not mutated.
  */
 declare function maskSecrets<T>(value: T, pattern?: RegExp): T;
 
+declare const AUTH_COOKIE = "nodeui_token";
+interface GuardOptions {
+    /** Configured console host; a loopback value enables the strict checks. */
+    host: string;
+    /** Extra `Host` header hostnames accepted (e.g. `myapp.local`). */
+    allowedHosts: readonly string[];
+    /** Extra `Origin` values accepted for cross-origin calls. */
+    allowedOrigins: readonly string[];
+    /** Extra remote IPs / IPv4 CIDRs accepted (e.g. `172.17.0.0/16` for Docker). */
+    allowedRemoteAddresses: readonly string[];
+    /** Accept requests carrying `X-Forwarded-*` headers. Default false. */
+    trustProxy: boolean;
+    /** When set, every request must present this token. */
+    authToken?: string;
+}
+type GuardResult = {
+    ok: true;
+    setToken?: string;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Builds the request guard for the console. It combines: loopback/remote
+ * address policy, `Host` validation (DNS-rebinding defence), `Origin`
+ * validation (cross-site request defence) and an optional shared token.
+ */
+declare function createGuard(options: GuardOptions): (req: IncomingMessage) => GuardResult;
+
 /**
  * Single-use, expiring confirmation nonces. Mutating actions (such as heap
  * snapshots) require a nonce issued here, presented via the
@@ -247,8 +370,9 @@ declare function maskSecrets<T>(value: T, pattern?: RegExp): T;
  */
 declare class ConfirmationStore {
     private readonly ttlMs;
+    private readonly maxOutstanding;
     private nonces;
-    constructor(ttlMs: number);
+    constructor(ttlMs: number, maxOutstanding?: number);
     issue(): ConfirmIssued;
     /** Consumes `nonce` and returns true only if it was valid and unexpired. */
     consume(nonce: string): boolean;
@@ -381,12 +505,45 @@ declare class EventLoopLagProvider implements NodeUIProvider<EventLoopSample> {
     };
 }
 
-/** Derives process + event-loop health from the latest sampled values. */
+/**
+ * A dependency check (database ping, cache ping, ...). Resolve for healthy,
+ * reject/throw (or resolve `false`) for unhealthy.
+ */
+type HealthCheck = () => unknown | Promise<unknown>;
+/** Derives process + event-loop health, plus optional dependency checks. */
 declare class HealthProvider implements NodeUIProvider<HealthData> {
+    private readonly checks;
     readonly id: "health";
-    get(ctx: ProviderContext): {
+    private cache;
+    constructor(checks?: Record<string, HealthCheck>);
+    private runChecks;
+    get(ctx: ProviderContext): Promise<{
         ok: true;
         data: HealthData;
+    }>;
+}
+
+type Recorder = (entry: Omit<OutgoingRequestEntry, 'id'>) => void;
+/**
+ * Refcounted instrumentation of outgoing HTTP calls made via `http`,
+ * `https` (axios, got, node-fetch, ...) and global `fetch` (undici). The
+ * first consumer installs the hooks, the last release restores everything.
+ */
+declare function interceptOutgoing(record: Recorder): () => void;
+/** Recent outgoing HTTP calls, recorded lazily while the panel is active. */
+declare class OutgoingProvider implements NodeUIProvider<OutgoingData> {
+    readonly id: "outgoing";
+    private buffer;
+    private nextId;
+    private failed;
+    private release;
+    constructor(size: number);
+    start(): void;
+    stop(): void;
+    record(entry: Omit<OutgoingRequestEntry, 'id'>): void;
+    get(): {
+        ok: true;
+        data: OutgoingData;
     };
 }
 
@@ -405,6 +562,7 @@ declare class HeapSnapshotProvider implements NodeUIProvider<HeapSnapshotPanelDa
     takeSnapshot(ctx: ProviderContext): Promise<ProviderResult<HeapSnapshotData>>;
 }
 
+declare function summarizeRequests(entries: readonly RequestEntry[]): RequestsSummary;
 /** Fixed-size ring buffer of recent HTTP requests, recorded via middleware hook. */
 declare class RequestsProvider implements NodeUIProvider<RequestsData> {
     readonly id: "requests";
@@ -521,7 +679,7 @@ interface SseStream {
  * Minimal Server-Sent Events writer over a raw HTTP response. Events are
  * emitted as `data: <json>\n\n`; heartbeats as `:ping\n\n`.
  */
-declare function startSse(res: ServerResponse): SseStream;
+declare function startSse(res: ServerResponse, extraHeaders?: Record<string, string>): SseStream;
 
 interface NodeUIOptions {
     /** URL path prefix. Default `/nodeui` (or `NODEUI_PATH`). */
@@ -548,8 +706,32 @@ interface NodeUIOptions {
     inactivityTimeoutMs?: number;
     /** TTL for mutation confirmation nonces. Default 60000. */
     confirmTtlMs?: number;
-    /** Directory for heap snapshot files. Defaults to the OS temp dir. */
+    /** Directory for heap snapshot files. Defaults to a private dir under the OS temp dir. */
     heapSnapshotDir?: string;
+    /** Extra `Host` hostnames accepted besides loopback names (or `NODEUI_ALLOWED_HOSTS`, comma-separated). */
+    allowedHosts?: string[];
+    /** Extra `Origin` values accepted for cross-origin calls (or `NODEUI_ALLOWED_ORIGINS`). */
+    allowedOrigins?: string[];
+    /**
+     * Extra remote IPs / IPv4 CIDRs accepted (or `NODEUI_ALLOWED_REMOTE`). Use
+     * `['172.16.0.0/12']` to reach the console from the host when the app runs in Docker.
+     */
+    allowedRemoteAddresses?: string[];
+    /** Accept requests carrying `X-Forwarded-*` headers (or `NODEUI_TRUST_PROXY=true`). Default false. */
+    trustProxy?: boolean;
+    /**
+     * Shared access token (or `NODEUI_TOKEN`). When set, open `/nodeui/?token=<token>` once;
+     * the browser then keeps an HttpOnly cookie. API clients may send `Authorization: Bearer`.
+     */
+    authToken?: string;
+    /** Maximum concurrent live (SSE) streams. Default 10. */
+    maxSseClients?: number;
+    /** Custom panels; each provider needs a unique lowercase id, e.g. `queues`. */
+    plugins?: NodeUIProvider[];
+    /** Named dependency checks (database, cache, ...) surfaced in the health panel. */
+    healthChecks?: Record<string, HealthCheck>;
+    /** Max recorded outgoing HTTP calls. Default 200. */
+    outgoingLogSize?: number;
 }
 interface NodeUIServer {
     readonly config: NodeUIConfig;
@@ -559,6 +741,11 @@ interface NodeUIServer {
     middleware(): NodeUIMiddleware;
     /** Direct request handling (no `next`); used for tests and adapters. */
     handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Supplies the route list directly (frameworks other than Express, e.g.
+     * Fastify's `onRoute`). Takes precedence over Express router introspection.
+     */
+    setRoutes(source: RouteEntry[] | (() => RouteEntry[])): void;
     /** Records a bootstrap timing mark, e.g. `mark("listening")`. */
     mark(name: string): void;
     /** Whether a background-sampling provider is currently running. */
@@ -576,7 +763,7 @@ type NodeUIMiddleware = (req: IncomingMessage, res: ServerResponse, next: () =>
  * Serializes an API envelope to JSON, applying secret masking so values
  * under keys like `TOKEN`/`KEY`/`SECRET`/`PASSWORD` never reach the UI.
  */
-declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>): string;
+declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>, mask?: boolean): string;
 declare function createNodeUI(options?: NodeUIOptions): NodeUIServer;
 
-export { type ActivationDecision, type ApiEnvelope, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, RingBuffer, type RouteEntry, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createNodeUI, extractRoutes, interceptConsole, isLoopbackAddress, maskSecrets, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse };
+export { AUTH_COOKIE, type ActivationDecision, type ApiEnvelope, type BuiltInPanelId, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type GuardOptions, type GuardResult, type HealthCheck, type HealthCheckResult, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type OutgoingData, OutgoingProvider, type OutgoingRequestEntry, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, type RequestsSummary, RingBuffer, type RouteEntry, type RouteStat, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createGuard, createNodeUI, extractRoutes, hostnameFromHostHeader, interceptConsole, interceptOutgoing, isLoopbackAddress, isLoopbackHostname, maskSecretText, maskSecrets, matchesAddress, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse, summarizeRequests };