@webda/debug 4.0.0-beta.5 → 4.0.0-beta.6

package/lib/debugservice.service.d.ts

@@ -1,19 +1,12 @@
 import { Service, ServiceParameters } from "@webda/core";
 import { RequestLog } from "./requestlog.js";
 import { CancelablePromise } from "@webda/utils";
-/**
- * Determine whether the given Origin header value is allowed to access the debug API.
- *
- * Allowed origins:
- * - http://localhost:3000 (docs dev server)
- * - http://127.0.0.1:3000 (docs dev server, alternate address)
- * - https://webda.io (production docs)
- * - https://*.webda.io (any HTTPS subdomain of webda.io)
- *
- * @param origin - The value of the HTTP `Origin` request header.
- * @returns `true` if the origin is allowed, `false` otherwise.
- */
-export declare function isAllowedOrigin(origin: string | undefined): boolean;
+export { isAllowedOrigin, allowedOrigins, DEBUG_API_VERSION } from "./security.js";
+/** Options of {@link DebugService.startDebugServer}. */
+export interface DebugServerOptions {
+    /** Serve the bundled dashboard and the one-time code exchange (`--local`) */
+    local?: boolean;
+}
 /**
  * Configuration parameters for the {@link DebugService}.
  *
@@ -48,7 +41,9 @@ export declare class DebugService extends Service<DebugServiceParameters> {
     requestLog: RequestLog;
     /** Ring buffer of application log entries */
     private logBuffer;
-    /** HTTP server for the debug API */
+    /** HTTP servers for the debug API (one per loopback address) */
+    private servers;
+    /** The IPv4 server, kept for the tests and the port lookup */
     private server?;
     /** WebSocket server for live event push */
     private wss?;
@@ -62,6 +57,46 @@ export declare class DebugService extends Service<DebugServiceParameters> {
     private running?;
     /** Timing map: requestId -> start timestamp */
     private timings;
+    /** Per-session token required on the API and the websocket */
+    private token;
+    /** Port the debug server actually listens on (resolved after listen) */
+    private listeningPort;
+    /** URL opened by the last `debug --web` run */
+    private dashboardUrl?;
+    /** Version of @webda/core, captured while the application context is available */
+    private frameworkVersion?;
+    /** Whether the bundled dashboard is served (`--local`) */
+    private localMode;
+    /** One-time code the local page exchanges for the token, with its expiry */
+    private bootstrap?;
+    /** Origins allowed by CORS (computed at start from the environment) */
+    private origins;
+    /**
+     * Port the debug server listens on (resolved after start).
+     * @returns the port
+     */
+    getPort(): number;
+    /**
+     * Loopback addresses the debug server is bound to.
+     * @returns the addresses, e.g. `["127.0.0.1", "::1"]`
+     */
+    getBoundAddresses(): string[];
+    /**
+     * Issue a one-time bootstrap code for the local page (`--local`).
+     *
+     * The code is random, single-use and expires after {@link BOOTSTRAP_CODE_TTL};
+     * `POST /api/session` exchanges it for the session token.
+     * @param ttl - lifetime in milliseconds (tests use a negative value for an expired code)
+     * @returns the code
+     */
+    issueBootstrapCode(ttl?: number): string;
+    /**
+     * Session token required on every `/api/*` request and websocket connection.
+     *
+     * It is generated when the service is created and never logged.
+     * @returns the token
+     */
+    getToken(): string;
     /**
      * Resolve the typed parameters and the capture knobs (with safe defaults
      * when the surrounding test environment does not load real parameters).
@@ -97,7 +132,10 @@ export declare class DebugService extends Service<DebugServiceParameters> {
      *
      * @param port - Port for the debug dashboard API
      * @param servePort - Port for the application HTTP server
-     * @param web - Disable TUI and only serve the web dashboard
+     * @param web - Disable TUI and open the web dashboard instead
+     * @param local - Serve the bundled dashboard from the debug server instead of the hosted one
+     * @param open - Open the dashboard in the default browser (`--no-open` to disable)
+     * @param telemetry - Allow usage analytics on the hosted dashboard (`--no-telemetry` to disable)
      * @returns a promise settled once the service stops or the TUI quits
      */
     debug(
@@ -105,16 +143,35 @@ export declare class DebugService extends Service<DebugServiceParameters> {
     port?: number, 
     /** @alias s @description Application server port */
     servePort?: number, 
-    /** @description Disable TUI and only serve the web dashboard */
-    web?: boolean): CancelablePromise<void>;
+    /** @description Disable TUI and open the web dashboard (hosted on webda.io) */
+    web?: boolean, 
+    /** @description With --web: serve the bundled dashboard from the debug port instead of webda.io */
+    local?: boolean, 
+    /** @description With --web: open the dashboard in the browser (--no-open to only print the URL) */
+    open?: boolean, 
+    /** @description With --web: allow usage analytics on the hosted dashboard (--no-telemetry or WEBDA_TELEMETRY=0 to disable) */
+    telemetry?: boolean): CancelablePromise<void>;
     /**
      * Start the application server, the debug server and the TUI or browser
      *
      * @param port - Port for the debug dashboard API
      * @param servePort - Port for the application HTTP server
-     * @param web - Disable TUI and only serve the web dashboard
+     * @param web - Disable TUI and open the web dashboard
+     * @param local - Serve the bundled dashboard instead of the hosted one
+     * @param open - Open the browser
+     * @param telemetry - Allow usage analytics on the hosted dashboard
      */
-    protected startDebug(port: number, servePort: number, web?: boolean): Promise<void>;
+    protected startDebug(port: number, servePort: number, web?: boolean, local?: boolean, open?: boolean, telemetry?: boolean): Promise<void>;
+    /**
+     * Print the dashboard URL for the user.
+     *
+     * The hosted URL carries the session token in its fragment, so it is written
+     * straight to stdout rather than through the logger: log output is captured
+     * by the log buffer, broadcast to the dashboard and may be persisted by other
+     * loggers.
+     * @param url - the dashboard URL
+     */
+    protected printDashboardUrl(url: string): void;
     /**
      * Settle the running debug command
      */
@@ -126,9 +183,40 @@ export declare class DebugService extends Service<DebugServiceParameters> {
     private openBrowser;
     /**
      * Create and start the debug HTTP server with WebSocket support.
-     * @param port - Port to listen on
+     *
+     * One server per loopback address: `127.0.0.1` and `::1`, so that no other
+     * local process can squat the IPv6 side of `localhost`. A port already taken
+     * on either address is an error; an unavailable IPv6 stack is tolerated.
+     * The websocket upgrade is handled by hand so that the `Host`, `Origin` and
+     * token checks run before `ws` completes the handshake.
+     * @param port - Port to listen on (0 for a random one)
+     * @param options - local mode
+     */
+    startDebugServer(port: number, options?: DebugServerOptions): Promise<void>;
+    /**
+     * Close every bound server.
+     */
+    private closeServers;
+    /**
+     * Start one HTTP server on an address.
+     * @param port - the port
+     * @param address - the loopback address
+     * @returns the listening server
+     */
+    private listen;
+    /**
+     * Authenticate a websocket upgrade before handing it to `ws`.
+     * @param req - the upgrade request
+     * @param socket - the underlying socket
+     * @param head - the first packet of the upgraded stream
      */
-    startDebugServer(port: number): Promise<void>;
+    private handleUpgrade;
+    /**
+     * Whether an Origin is the hosted dashboard, the dev server or the debug server itself.
+     * @param origin - the Origin header value
+     * @returns `true` when trusted
+     */
+    private isTrustedOrigin;
     /**
      * Route incoming HTTP requests to introspection handlers.
      * @param req - Incoming HTTP request
@@ -141,9 +229,32 @@ export declare class DebugService extends Service<DebugServiceParameters> {
      */
     private getOpenAPISpec;
     /**
-     * Serve a static file from the webui directory.
-     * Falls back to index.html for SPA-style routing.
+     * `POST /api/session`: exchange the one-time bootstrap code for the session token (`--local` only).
+     *
+     * The code is printed in the local URL fragment; the page sends it once and
+     * keeps the token in memory. Accepted only from the debug origin itself (or
+     * without Origin, for non-browser clients); 404 in hosted mode so the route
+     * reveals nothing there. The code is consumed on a successful match only, and a
+     * reuse after it was spent is logged (the link was used by another client).
+     * @param req - the request
+     * @param res - the response
+     */
+    private handleSessionExchange;
+    /**
+     * Security headers of the pages and assets the debug server serves.
+     * @param res - the response
+     * @param html - whether the response is a page
+     */
+    private pageHeaders;
+    /**
+     * Serve a static file from the webui directory (`--local`), or the hosted
+     * placeholder page.
+     *
+     * The page never carries the token: the local page obtains it through the
+     * one-time code exchange. Unknown paths fall back to index.html (SPA routing);
+     * directories are not found.
      * @param pathname - Request pathname
+     * @param req - Incoming request
      * @param res - Server response
      */
     private serveStaticFile;