@qodalis/cli-core 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli-core",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Core interfaces, types, and utilities for the @qodalis CLI ecosystem.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",

package/public-api.d.mts

@@ -2119,6 +2119,25 @@ interface CliBootOptions {
      */
     slowStepMs?: number;
 }
+/**
+ * The name and icon an application ships the CLI under. Anything left out
+ * keeps Qodalis CLI's; the copyright line, the docs link and `version` stay
+ * Qodalis CLI's.
+ */
+interface CliBranding {
+    /**
+     * The product name: the welcome banner ("Welcome to RateBell CLI", shown
+     * instead of the Qodalis CLI art), the panel's title and the startup log.
+     * `version` adds it to the Qodalis CLI details.
+     * @default 'Web CLI' (panel title 'CLI')
+     */
+    name?: string;
+    /**
+     * The panel's icon (header and hide tab) instead of the terminal glyph:
+     * an image URL (http(s), a path, or a `data:image` URL).
+     */
+    icon?: string;
+}
 /**
  * Options for the CLI
  */
@@ -2127,6 +2146,11 @@ type CliOptions = Record<string, any> & {
      * How the CLI reports its startup (boot log, spinner).
      */
     boot?: CliBootOptions;
+    /**
+     * The name and icon the CLI shows (welcome banner, panel title, startup
+     * log); defaults to Qodalis CLI's.
+     */
+    branding?: CliBranding;
     /**
      * Custom terminal options
      */
@@ -3342,6 +3366,34 @@ type CliServerConfig = {
     headers?: CliHeadersProvider;
     /** Request timeout in milliseconds. @default 30000 */
     timeout?: number;
+    /**
+     * Copy `headers` into WebSocket URLs as `_header_<name>` query params
+     * (the behaviour up to 2.0.0). Off by default: tokens in URLs end up in
+     * access, proxy and CDN logs and in browser history. Without it, sockets
+     * authenticate with a single-use ticket from
+     * `POST /api/v1/qcli/sessions/ws-ticket` (users plugin) fetched with these
+     * headers. Only for servers that still read `_header_Authorization`, such
+     * as a shell `accessToken` without the users plugin.
+     * @deprecated use the users plugin's WebSocket tickets
+     */
+    unsafeHeadersInWebSocketUrl?: boolean;
+};
+/**
+ * Which rows of a longer result a server table holds. Commands that page (`--skip`,
+ * `--take`) send it; servers also send it, with `truncated`, when they cut a
+ * table from a command that does not page.
+ */
+type CliServerTablePage = {
+    /** Rows skipped before these */
+    skip: number;
+    /** Rows asked for */
+    take: number;
+    /** All rows, when the command knows it */
+    total?: number;
+    /** Whether more rows follow */
+    hasMore: boolean;
+    /** The server cut the table: `--skip` will not show the rest */
+    truncated?: boolean;
 };
 /**
  * A single output item in a server response
@@ -3354,6 +3406,7 @@ type CliServerOutput = {
     type: 'table';
     headers: string[];
     rows: string[][];
+    page?: CliServerTablePage;
 } | {
     type: 'list';
     items: string[];
@@ -3740,35 +3793,40 @@ declare class ServerVersionNegotiator {
 }
 
 /**
- * Builds a WebSocket URL that includes authentication credentials from headers
- * as query parameters. Since the browser WebSocket API does not support custom
- * request headers, this allows the host server's auth middleware to validate
- * the connection during the HTTP upgrade handshake.
- *
- * All configured headers are forwarded as query parameters prefixed with
- * `_header_` to avoid collisions with application-level query params.
+ * Copies headers into a WebSocket URL as `_header_<name>` query params.
  *
- * Accepts both static header maps and dynamic provider functions.
- *
- * **Security note:** Query parameters are visible in browser history, server
- * access logs, proxy/CDN logs, and the `Referer` header. Tokens placed in the
- * URL are therefore more exposed than those sent via HTTP headers. This is an
- * inherent limitation of the browser WebSocket API (no custom headers).
- * Server-side middleware that reads `_header_*` params should strip them from
- * logs and avoid forwarding them in redirects.
+ * **Unsafe:** query parameters are visible in browser history and in server,
+ * proxy and CDN access logs. Used only for servers configured with
+ * `unsafeHeadersInWebSocketUrl: true`; everything else goes through
+ * {@link buildServerWebSocketUrl}, which keeps headers out of the URL.
  *
  * @param wsUrl  The base WebSocket URL (may already contain query parameters)
  * @param headers  The headers provider from CliServerConfig (may include Authorization, etc.)
- * @returns The WebSocket URL with auth credentials appended as query parameters
+ * @returns The WebSocket URL with the headers appended as query parameters
  */
 declare function buildAuthenticatedWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider): string;
+/** Options for {@link buildServerWebSocketUrl} and {@link resolveServerWebSocketUrl}. */
+interface CliWebSocketAuthOptions {
+    /** See `CliServerConfig.unsafeHeadersInWebSocketUrl` */
+    unsafeHeadersInWebSocketUrl?: boolean;
+}
+/** Ticket endpoint of the users plugin, relative to the server root */
+declare const CLI_WS_TICKET_PATH = "/api/v1/qcli/sessions/ws-ticket";
+/**
+ * Authenticates a WebSocket URL with headers without putting them in it:
+ * fetches a single-use ticket from `POST /api/v1/qcli/sessions/ws-ticket`
+ * with the headers and appends `?ticket=`. When no ticket can be had, the
+ * socket connects without credentials and a warning is logged once.
+ * Headers are copied into the URL only with `unsafeHeadersInWebSocketUrl`.
+ */
+declare function buildServerWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider, options?: CliWebSocketAuthOptions): Promise<string>;
 /**
  * Build the WebSocket URL for a configured server. Prefers upgrade params
- * from auth providers (e.g. a single-use ticket from the users module); only
- * when no provider handles the server are headers copied into the URL
- * (legacy behaviour, see {@link buildAuthenticatedWebSocketUrl}).
+ * from auth providers (e.g. a single-use ticket from the users module);
+ * otherwise authenticates with the server's headers through
+ * {@link buildServerWebSocketUrl}.
  */
-declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider): Promise<string>;
+declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider, options?: CliWebSocketAuthOptions): Promise<string>;
 /** Append query params to a URL that may already have some. */
 declare function appendQueryParams(url: string, params: Record<string, string>): string;
 
@@ -4100,7 +4158,7 @@ interface CliThemeInfo {
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0";
+declare const LIBRARY_VERSION = "2.1.0";
 declare const API_VERSION = 2;
 
 /**
@@ -4161,5 +4219,5 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, CliAccessDeniedError, CliBackgroundColor, CliForegroundColor, CliHttpError, CliIcon, CliKeyData, CliLogLevel, CliModuleRegistry, CliServerPermissions, CliUsersPermissions, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, ICliAuditService_TOKEN, ICliAuthService_TOKEN, ICliAuthorizationService_TOKEN, ICliCommandGuard_TOKEN, ICliCompletionProvider_TOKEN, ICliDragDropService_TOKEN, ICliEventBus_TOKEN, ICliFilePickerProvider_TOKEN, ICliFileTransferService_TOKEN, ICliGroupsStoreService_TOKEN, ICliHttpClient_TOKEN, ICliKeyValueStore_TOKEN, ICliPermissionRegistry_TOKEN, ICliPermissionService_TOKEN, ICliServerAuthService_TOKEN, ICliServerAuthTokenProvider_TOKEN, ICliServerManager_TOKEN, ICliSessionsService_TOKEN, ICliTranslationService_TOKEN, ICliUserEventService_TOKEN, ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN, LIBRARY_VERSION, ObjectDescriber, ServerVersionNegotiator, appendQueryParams, bootCliModule, buildAuthenticatedWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createCliToken, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, joinShellWords, loadPanelPosition, nextPanelPosition, quoteShellWord, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, splitShellWords, stripAnsi, toQueryString, truncateToWidth, unquoteRawArgument, utils, visibleLength, writeExamples, writeHint, writeUsage, writeWrapped };
-export type { CliAccessAction, CliAddUser, CliBackgroundServiceStatus, CliBackgroundServiceType, CliBootOptions, CliCommandGuardResult, CliDateOptions, CliEmitOptions, CliEngineSnapshot, CliEvent, CliEventData, CliEventHandler, CliEventMap, CliEventType, CliFactoryProvider, CliFilePickerOptions, CliFileResult, CliFullScreenOptions, CliHeadersProvider, CliHelpRow, CliHttpRequestOptions, CliLineOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNotification, CliNotificationLevel, CliNumberOptions, CliOptions, CliPackageSource, CliPanelConfig, CliPanelHideAlignment, CliPanelPaneState, CliPanelPosition, CliPanelState, CliPanelTabState, CliPercentageProgressBarUpdateValueOptions, CliPermissionDefinition, CliProcessCommand, CliProcessorMetadata, CliProvider, CliSelectOption, CliSelectOptions, CliServerCapabilities, CliServerCommandDescriptor, CliServerConfig, CliServerOutput, CliServerResponse, CliServiceEventHandler, CliServiceExecutionMode, CliServiceLogLevel, CliState, CliStateConfiguration, CliStateScope, CliStateStoreOptions, CliTableOptions, CliTextAnimatorOptions, CliTheme, CliThemeCategory, CliThemeInfo, CliToken, CliTypeProvider, CliUpdateUser, CliValueProvider, CliWorkerInboundMessage, CliWorkerOutboundMessage, CustomEventType, DefaultThemesType, ICliAuditEntry, ICliAuditService, ICliAuthService, ICliAuthorizationService, ICliBackgroundService, ICliBackgroundServiceInfo, ICliBackgroundServiceRegistry, ICliClipboard, ICliCommandAuthor, ICliCommandChildProcessor, ICliCommandControls, ICliCommandExecutorService, ICliCommandGuard, ICliCommandKey, ICliCommandParameterDescriptor, ICliCommandProcessor, ICliCommandProcessorRegistry, ICliCompletionContext, ICliCompletionProvider, ICliConfigurableModule, ICliConfigurationOption, ICliDragDropService, ICliEventBus, ICliExecutionContext, ICliExecutionProcess, ICliFileEntry, ICliFilePickerProvider, ICliFileTransferService, ICliGlobalParameterHandler, ICliGroup, ICliGroupsStoreService, ICliHttpClient, ICliInputReader, ICliKeyValueStore, ICliLogger, ICliManagedInterval, ICliManagedTimer, ICliModule, ICliNotifier, ICliOwnership, ICliPanelRef, ICliPercentageProgressBar, ICliPermissionRegistry, ICliPermissionService, ICliPingServerService, ICliPrincipal, ICliProcessEntry, ICliProcessRegisterOptions, ICliProcessRegistry, ICliProcessorHook, ICliProgressBar, ICliProtectedResource, ICliServerAuthService, ICliServerAuthTokenProvider, ICliServerManager, ICliServiceContext, ICliServiceEvent, ICliServiceLogEntry, ICliServiceProvider, ICliSessionInfo, ICliSessionsService, ICliSpinner, ICliStateStore, ICliTerminalWriter, ICliTextAnimator, ICliTranslationService, ICliUser, ICliUserCredentials, ICliUserEvent, ICliUserEventService, ICliUserSession, ICliUserSessionService, ICliUsersStoreService, ISyntaxHighlightRule, ISyntaxHighlighter, ISyntaxTheme, LineState, Package, ServerVersionInfo, WorkerServiceContext };
+export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CLI_WS_TICKET_PATH, CancellablePromise, CliAccessDeniedError, CliBackgroundColor, CliForegroundColor, CliHttpError, CliIcon, CliKeyData, CliLogLevel, CliModuleRegistry, CliServerPermissions, CliUsersPermissions, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, ICliAuditService_TOKEN, ICliAuthService_TOKEN, ICliAuthorizationService_TOKEN, ICliCommandGuard_TOKEN, ICliCompletionProvider_TOKEN, ICliDragDropService_TOKEN, ICliEventBus_TOKEN, ICliFilePickerProvider_TOKEN, ICliFileTransferService_TOKEN, ICliGroupsStoreService_TOKEN, ICliHttpClient_TOKEN, ICliKeyValueStore_TOKEN, ICliPermissionRegistry_TOKEN, ICliPermissionService_TOKEN, ICliServerAuthService_TOKEN, ICliServerAuthTokenProvider_TOKEN, ICliServerManager_TOKEN, ICliSessionsService_TOKEN, ICliTranslationService_TOKEN, ICliUserEventService_TOKEN, ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN, LIBRARY_VERSION, ObjectDescriber, ServerVersionNegotiator, appendQueryParams, bootCliModule, buildAuthenticatedWebSocketUrl, buildServerWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createCliToken, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, joinShellWords, loadPanelPosition, nextPanelPosition, quoteShellWord, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, splitShellWords, stripAnsi, toQueryString, truncateToWidth, unquoteRawArgument, utils, visibleLength, writeExamples, writeHint, writeUsage, writeWrapped };
+export type { CliAccessAction, CliAddUser, CliBackgroundServiceStatus, CliBackgroundServiceType, CliBootOptions, CliBranding, CliCommandGuardResult, CliDateOptions, CliEmitOptions, CliEngineSnapshot, CliEvent, CliEventData, CliEventHandler, CliEventMap, CliEventType, CliFactoryProvider, CliFilePickerOptions, CliFileResult, CliFullScreenOptions, CliHeadersProvider, CliHelpRow, CliHttpRequestOptions, CliLineOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNotification, CliNotificationLevel, CliNumberOptions, CliOptions, CliPackageSource, CliPanelConfig, CliPanelHideAlignment, CliPanelPaneState, CliPanelPosition, CliPanelState, CliPanelTabState, CliPercentageProgressBarUpdateValueOptions, CliPermissionDefinition, CliProcessCommand, CliProcessorMetadata, CliProvider, CliSelectOption, CliSelectOptions, CliServerCapabilities, CliServerCommandDescriptor, CliServerConfig, CliServerOutput, CliServerResponse, CliServerTablePage, CliServiceEventHandler, CliServiceExecutionMode, CliServiceLogLevel, CliState, CliStateConfiguration, CliStateScope, CliStateStoreOptions, CliTableOptions, CliTextAnimatorOptions, CliTheme, CliThemeCategory, CliThemeInfo, CliToken, CliTypeProvider, CliUpdateUser, CliValueProvider, CliWebSocketAuthOptions, CliWorkerInboundMessage, CliWorkerOutboundMessage, CustomEventType, DefaultThemesType, ICliAuditEntry, ICliAuditService, ICliAuthService, ICliAuthorizationService, ICliBackgroundService, ICliBackgroundServiceInfo, ICliBackgroundServiceRegistry, ICliClipboard, ICliCommandAuthor, ICliCommandChildProcessor, ICliCommandControls, ICliCommandExecutorService, ICliCommandGuard, ICliCommandKey, ICliCommandParameterDescriptor, ICliCommandProcessor, ICliCommandProcessorRegistry, ICliCompletionContext, ICliCompletionProvider, ICliConfigurableModule, ICliConfigurationOption, ICliDragDropService, ICliEventBus, ICliExecutionContext, ICliExecutionProcess, ICliFileEntry, ICliFilePickerProvider, ICliFileTransferService, ICliGlobalParameterHandler, ICliGroup, ICliGroupsStoreService, ICliHttpClient, ICliInputReader, ICliKeyValueStore, ICliLogger, ICliManagedInterval, ICliManagedTimer, ICliModule, ICliNotifier, ICliOwnership, ICliPanelRef, ICliPercentageProgressBar, ICliPermissionRegistry, ICliPermissionService, ICliPingServerService, ICliPrincipal, ICliProcessEntry, ICliProcessRegisterOptions, ICliProcessRegistry, ICliProcessorHook, ICliProgressBar, ICliProtectedResource, ICliServerAuthService, ICliServerAuthTokenProvider, ICliServerManager, ICliServiceContext, ICliServiceEvent, ICliServiceLogEntry, ICliServiceProvider, ICliSessionInfo, ICliSessionsService, ICliSpinner, ICliStateStore, ICliTerminalWriter, ICliTextAnimator, ICliTranslationService, ICliUser, ICliUserCredentials, ICliUserEvent, ICliUserEventService, ICliUserSession, ICliUserSessionService, ICliUsersStoreService, ISyntaxHighlightRule, ISyntaxHighlighter, ISyntaxTheme, LineState, Package, ServerVersionInfo, WorkerServiceContext };

package/public-api.d.ts

@@ -2119,6 +2119,25 @@ interface CliBootOptions {
      */
     slowStepMs?: number;
 }
+/**
+ * The name and icon an application ships the CLI under. Anything left out
+ * keeps Qodalis CLI's; the copyright line, the docs link and `version` stay
+ * Qodalis CLI's.
+ */
+interface CliBranding {
+    /**
+     * The product name: the welcome banner ("Welcome to RateBell CLI", shown
+     * instead of the Qodalis CLI art), the panel's title and the startup log.
+     * `version` adds it to the Qodalis CLI details.
+     * @default 'Web CLI' (panel title 'CLI')
+     */
+    name?: string;
+    /**
+     * The panel's icon (header and hide tab) instead of the terminal glyph:
+     * an image URL (http(s), a path, or a `data:image` URL).
+     */
+    icon?: string;
+}
 /**
  * Options for the CLI
  */
@@ -2127,6 +2146,11 @@ type CliOptions = Record<string, any> & {
      * How the CLI reports its startup (boot log, spinner).
      */
     boot?: CliBootOptions;
+    /**
+     * The name and icon the CLI shows (welcome banner, panel title, startup
+     * log); defaults to Qodalis CLI's.
+     */
+    branding?: CliBranding;
     /**
      * Custom terminal options
      */
@@ -3342,6 +3366,34 @@ type CliServerConfig = {
     headers?: CliHeadersProvider;
     /** Request timeout in milliseconds. @default 30000 */
     timeout?: number;
+    /**
+     * Copy `headers` into WebSocket URLs as `_header_<name>` query params
+     * (the behaviour up to 2.0.0). Off by default: tokens in URLs end up in
+     * access, proxy and CDN logs and in browser history. Without it, sockets
+     * authenticate with a single-use ticket from
+     * `POST /api/v1/qcli/sessions/ws-ticket` (users plugin) fetched with these
+     * headers. Only for servers that still read `_header_Authorization`, such
+     * as a shell `accessToken` without the users plugin.
+     * @deprecated use the users plugin's WebSocket tickets
+     */
+    unsafeHeadersInWebSocketUrl?: boolean;
+};
+/**
+ * Which rows of a longer result a server table holds. Commands that page (`--skip`,
+ * `--take`) send it; servers also send it, with `truncated`, when they cut a
+ * table from a command that does not page.
+ */
+type CliServerTablePage = {
+    /** Rows skipped before these */
+    skip: number;
+    /** Rows asked for */
+    take: number;
+    /** All rows, when the command knows it */
+    total?: number;
+    /** Whether more rows follow */
+    hasMore: boolean;
+    /** The server cut the table: `--skip` will not show the rest */
+    truncated?: boolean;
 };
 /**
  * A single output item in a server response
@@ -3354,6 +3406,7 @@ type CliServerOutput = {
     type: 'table';
     headers: string[];
     rows: string[][];
+    page?: CliServerTablePage;
 } | {
     type: 'list';
     items: string[];
@@ -3740,35 +3793,40 @@ declare class ServerVersionNegotiator {
 }
 
 /**
- * Builds a WebSocket URL that includes authentication credentials from headers
- * as query parameters. Since the browser WebSocket API does not support custom
- * request headers, this allows the host server's auth middleware to validate
- * the connection during the HTTP upgrade handshake.
- *
- * All configured headers are forwarded as query parameters prefixed with
- * `_header_` to avoid collisions with application-level query params.
+ * Copies headers into a WebSocket URL as `_header_<name>` query params.
  *
- * Accepts both static header maps and dynamic provider functions.
- *
- * **Security note:** Query parameters are visible in browser history, server
- * access logs, proxy/CDN logs, and the `Referer` header. Tokens placed in the
- * URL are therefore more exposed than those sent via HTTP headers. This is an
- * inherent limitation of the browser WebSocket API (no custom headers).
- * Server-side middleware that reads `_header_*` params should strip them from
- * logs and avoid forwarding them in redirects.
+ * **Unsafe:** query parameters are visible in browser history and in server,
+ * proxy and CDN access logs. Used only for servers configured with
+ * `unsafeHeadersInWebSocketUrl: true`; everything else goes through
+ * {@link buildServerWebSocketUrl}, which keeps headers out of the URL.
  *
  * @param wsUrl  The base WebSocket URL (may already contain query parameters)
  * @param headers  The headers provider from CliServerConfig (may include Authorization, etc.)
- * @returns The WebSocket URL with auth credentials appended as query parameters
+ * @returns The WebSocket URL with the headers appended as query parameters
  */
 declare function buildAuthenticatedWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider): string;
+/** Options for {@link buildServerWebSocketUrl} and {@link resolveServerWebSocketUrl}. */
+interface CliWebSocketAuthOptions {
+    /** See `CliServerConfig.unsafeHeadersInWebSocketUrl` */
+    unsafeHeadersInWebSocketUrl?: boolean;
+}
+/** Ticket endpoint of the users plugin, relative to the server root */
+declare const CLI_WS_TICKET_PATH = "/api/v1/qcli/sessions/ws-ticket";
+/**
+ * Authenticates a WebSocket URL with headers without putting them in it:
+ * fetches a single-use ticket from `POST /api/v1/qcli/sessions/ws-ticket`
+ * with the headers and appends `?ticket=`. When no ticket can be had, the
+ * socket connects without credentials and a warning is logged once.
+ * Headers are copied into the URL only with `unsafeHeadersInWebSocketUrl`.
+ */
+declare function buildServerWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider, options?: CliWebSocketAuthOptions): Promise<string>;
 /**
  * Build the WebSocket URL for a configured server. Prefers upgrade params
- * from auth providers (e.g. a single-use ticket from the users module); only
- * when no provider handles the server are headers copied into the URL
- * (legacy behaviour, see {@link buildAuthenticatedWebSocketUrl}).
+ * from auth providers (e.g. a single-use ticket from the users module);
+ * otherwise authenticates with the server's headers through
+ * {@link buildServerWebSocketUrl}.
  */
-declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider): Promise<string>;
+declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider, options?: CliWebSocketAuthOptions): Promise<string>;
 /** Append query params to a URL that may already have some. */
 declare function appendQueryParams(url: string, params: Record<string, string>): string;
 
@@ -4100,7 +4158,7 @@ interface CliThemeInfo {
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0";
+declare const LIBRARY_VERSION = "2.1.0";
 declare const API_VERSION = 2;
 
 /**
@@ -4161,5 +4219,5 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, CliAccessDeniedError, CliBackgroundColor, CliForegroundColor, CliHttpError, CliIcon, CliKeyData, CliLogLevel, CliModuleRegistry, CliServerPermissions, CliUsersPermissions, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, ICliAuditService_TOKEN, ICliAuthService_TOKEN, ICliAuthorizationService_TOKEN, ICliCommandGuard_TOKEN, ICliCompletionProvider_TOKEN, ICliDragDropService_TOKEN, ICliEventBus_TOKEN, ICliFilePickerProvider_TOKEN, ICliFileTransferService_TOKEN, ICliGroupsStoreService_TOKEN, ICliHttpClient_TOKEN, ICliKeyValueStore_TOKEN, ICliPermissionRegistry_TOKEN, ICliPermissionService_TOKEN, ICliServerAuthService_TOKEN, ICliServerAuthTokenProvider_TOKEN, ICliServerManager_TOKEN, ICliSessionsService_TOKEN, ICliTranslationService_TOKEN, ICliUserEventService_TOKEN, ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN, LIBRARY_VERSION, ObjectDescriber, ServerVersionNegotiator, appendQueryParams, bootCliModule, buildAuthenticatedWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createCliToken, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, joinShellWords, loadPanelPosition, nextPanelPosition, quoteShellWord, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, splitShellWords, stripAnsi, toQueryString, truncateToWidth, unquoteRawArgument, utils, visibleLength, writeExamples, writeHint, writeUsage, writeWrapped };
-export type { CliAccessAction, CliAddUser, CliBackgroundServiceStatus, CliBackgroundServiceType, CliBootOptions, CliCommandGuardResult, CliDateOptions, CliEmitOptions, CliEngineSnapshot, CliEvent, CliEventData, CliEventHandler, CliEventMap, CliEventType, CliFactoryProvider, CliFilePickerOptions, CliFileResult, CliFullScreenOptions, CliHeadersProvider, CliHelpRow, CliHttpRequestOptions, CliLineOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNotification, CliNotificationLevel, CliNumberOptions, CliOptions, CliPackageSource, CliPanelConfig, CliPanelHideAlignment, CliPanelPaneState, CliPanelPosition, CliPanelState, CliPanelTabState, CliPercentageProgressBarUpdateValueOptions, CliPermissionDefinition, CliProcessCommand, CliProcessorMetadata, CliProvider, CliSelectOption, CliSelectOptions, CliServerCapabilities, CliServerCommandDescriptor, CliServerConfig, CliServerOutput, CliServerResponse, CliServiceEventHandler, CliServiceExecutionMode, CliServiceLogLevel, CliState, CliStateConfiguration, CliStateScope, CliStateStoreOptions, CliTableOptions, CliTextAnimatorOptions, CliTheme, CliThemeCategory, CliThemeInfo, CliToken, CliTypeProvider, CliUpdateUser, CliValueProvider, CliWorkerInboundMessage, CliWorkerOutboundMessage, CustomEventType, DefaultThemesType, ICliAuditEntry, ICliAuditService, ICliAuthService, ICliAuthorizationService, ICliBackgroundService, ICliBackgroundServiceInfo, ICliBackgroundServiceRegistry, ICliClipboard, ICliCommandAuthor, ICliCommandChildProcessor, ICliCommandControls, ICliCommandExecutorService, ICliCommandGuard, ICliCommandKey, ICliCommandParameterDescriptor, ICliCommandProcessor, ICliCommandProcessorRegistry, ICliCompletionContext, ICliCompletionProvider, ICliConfigurableModule, ICliConfigurationOption, ICliDragDropService, ICliEventBus, ICliExecutionContext, ICliExecutionProcess, ICliFileEntry, ICliFilePickerProvider, ICliFileTransferService, ICliGlobalParameterHandler, ICliGroup, ICliGroupsStoreService, ICliHttpClient, ICliInputReader, ICliKeyValueStore, ICliLogger, ICliManagedInterval, ICliManagedTimer, ICliModule, ICliNotifier, ICliOwnership, ICliPanelRef, ICliPercentageProgressBar, ICliPermissionRegistry, ICliPermissionService, ICliPingServerService, ICliPrincipal, ICliProcessEntry, ICliProcessRegisterOptions, ICliProcessRegistry, ICliProcessorHook, ICliProgressBar, ICliProtectedResource, ICliServerAuthService, ICliServerAuthTokenProvider, ICliServerManager, ICliServiceContext, ICliServiceEvent, ICliServiceLogEntry, ICliServiceProvider, ICliSessionInfo, ICliSessionsService, ICliSpinner, ICliStateStore, ICliTerminalWriter, ICliTextAnimator, ICliTranslationService, ICliUser, ICliUserCredentials, ICliUserEvent, ICliUserEventService, ICliUserSession, ICliUserSessionService, ICliUsersStoreService, ISyntaxHighlightRule, ISyntaxHighlighter, ISyntaxTheme, LineState, Package, ServerVersionInfo, WorkerServiceContext };
+export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CLI_WS_TICKET_PATH, CancellablePromise, CliAccessDeniedError, CliBackgroundColor, CliForegroundColor, CliHttpError, CliIcon, CliKeyData, CliLogLevel, CliModuleRegistry, CliServerPermissions, CliUsersPermissions, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, ICliAuditService_TOKEN, ICliAuthService_TOKEN, ICliAuthorizationService_TOKEN, ICliCommandGuard_TOKEN, ICliCompletionProvider_TOKEN, ICliDragDropService_TOKEN, ICliEventBus_TOKEN, ICliFilePickerProvider_TOKEN, ICliFileTransferService_TOKEN, ICliGroupsStoreService_TOKEN, ICliHttpClient_TOKEN, ICliKeyValueStore_TOKEN, ICliPermissionRegistry_TOKEN, ICliPermissionService_TOKEN, ICliServerAuthService_TOKEN, ICliServerAuthTokenProvider_TOKEN, ICliServerManager_TOKEN, ICliSessionsService_TOKEN, ICliTranslationService_TOKEN, ICliUserEventService_TOKEN, ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN, LIBRARY_VERSION, ObjectDescriber, ServerVersionNegotiator, appendQueryParams, bootCliModule, buildAuthenticatedWebSocketUrl, buildServerWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createCliToken, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, joinShellWords, loadPanelPosition, nextPanelPosition, quoteShellWord, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, splitShellWords, stripAnsi, toQueryString, truncateToWidth, unquoteRawArgument, utils, visibleLength, writeExamples, writeHint, writeUsage, writeWrapped };
+export type { CliAccessAction, CliAddUser, CliBackgroundServiceStatus, CliBackgroundServiceType, CliBootOptions, CliBranding, CliCommandGuardResult, CliDateOptions, CliEmitOptions, CliEngineSnapshot, CliEvent, CliEventData, CliEventHandler, CliEventMap, CliEventType, CliFactoryProvider, CliFilePickerOptions, CliFileResult, CliFullScreenOptions, CliHeadersProvider, CliHelpRow, CliHttpRequestOptions, CliLineOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNotification, CliNotificationLevel, CliNumberOptions, CliOptions, CliPackageSource, CliPanelConfig, CliPanelHideAlignment, CliPanelPaneState, CliPanelPosition, CliPanelState, CliPanelTabState, CliPercentageProgressBarUpdateValueOptions, CliPermissionDefinition, CliProcessCommand, CliProcessorMetadata, CliProvider, CliSelectOption, CliSelectOptions, CliServerCapabilities, CliServerCommandDescriptor, CliServerConfig, CliServerOutput, CliServerResponse, CliServerTablePage, CliServiceEventHandler, CliServiceExecutionMode, CliServiceLogLevel, CliState, CliStateConfiguration, CliStateScope, CliStateStoreOptions, CliTableOptions, CliTextAnimatorOptions, CliTheme, CliThemeCategory, CliThemeInfo, CliToken, CliTypeProvider, CliUpdateUser, CliValueProvider, CliWebSocketAuthOptions, CliWorkerInboundMessage, CliWorkerOutboundMessage, CustomEventType, DefaultThemesType, ICliAuditEntry, ICliAuditService, ICliAuthService, ICliAuthorizationService, ICliBackgroundService, ICliBackgroundServiceInfo, ICliBackgroundServiceRegistry, ICliClipboard, ICliCommandAuthor, ICliCommandChildProcessor, ICliCommandControls, ICliCommandExecutorService, ICliCommandGuard, ICliCommandKey, ICliCommandParameterDescriptor, ICliCommandProcessor, ICliCommandProcessorRegistry, ICliCompletionContext, ICliCompletionProvider, ICliConfigurableModule, ICliConfigurationOption, ICliDragDropService, ICliEventBus, ICliExecutionContext, ICliExecutionProcess, ICliFileEntry, ICliFilePickerProvider, ICliFileTransferService, ICliGlobalParameterHandler, ICliGroup, ICliGroupsStoreService, ICliHttpClient, ICliInputReader, ICliKeyValueStore, ICliLogger, ICliManagedInterval, ICliManagedTimer, ICliModule, ICliNotifier, ICliOwnership, ICliPanelRef, ICliPercentageProgressBar, ICliPermissionRegistry, ICliPermissionService, ICliPingServerService, ICliPrincipal, ICliProcessEntry, ICliProcessRegisterOptions, ICliProcessRegistry, ICliProcessorHook, ICliProgressBar, ICliProtectedResource, ICliServerAuthService, ICliServerAuthTokenProvider, ICliServerManager, ICliServiceContext, ICliServiceEvent, ICliServiceLogEntry, ICliServiceProvider, ICliSessionInfo, ICliSessionsService, ICliSpinner, ICliStateStore, ICliTerminalWriter, ICliTextAnimator, ICliTranslationService, ICliUser, ICliUserCredentials, ICliUserEvent, ICliUserEventService, ICliUserSession, ICliUserSessionService, ICliUsersStoreService, ISyntaxHighlightRule, ISyntaxHighlighter, ISyntaxTheme, LineState, Package, ServerVersionInfo, WorkerServiceContext };

package/public-api.js

@@ -2599,7 +2599,7 @@ function satisfiesVersionRange(installed, range) {
 }
 
 // src/lib/version.ts
-var LIBRARY_VERSION = "2.0.0";
+var LIBRARY_VERSION = "2.1.0";
 var API_VERSION = 2;
 
 // src/lib/utils/server-version-negotiator.ts
@@ -2661,13 +2661,61 @@ function buildAuthenticatedWebSocketUrl(wsUrl, headers) {
   ).join("&");
   return `${wsUrl}${separator}${params}`;
 }
-async function resolveServerWebSocketUrl(services, serverName, wsUrl, configHeaders) {
+var CLI_WS_TICKET_PATH = "/api/v1/qcli/sessions/ws-ticket";
+var warnedServers = /* @__PURE__ */ new Set();
+async function buildServerWebSocketUrl(wsUrl, headers, options) {
+  const resolved = resolveHeaders(headers);
+  if (Object.keys(resolved).length === 0) {
+    return wsUrl;
+  }
+  if (options?.unsafeHeadersInWebSocketUrl) {
+    return buildAuthenticatedWebSocketUrl(wsUrl, resolved);
+  }
+  const httpBase = toHttpBaseUrl(wsUrl);
+  const ticket = await fetchWebSocketTicket(httpBase, resolved);
+  if (ticket) {
+    return appendQueryParams(wsUrl, { ticket });
+  }
+  if (!warnedServers.has(httpBase)) {
+    warnedServers.add(httpBase);
+    console.warn(
+      `[qodalis-cli] ${httpBase} issued no WebSocket ticket (${CLI_WS_TICKET_PATH}), so its sockets connect without credentials. Configured headers are never copied into WebSocket URLs; enable the users plugin on the server, or set \`unsafeHeadersInWebSocketUrl: true\` on the server config to keep the old behaviour.`
+    );
+  }
+  return wsUrl;
+}
+async function resolveServerWebSocketUrl(services, serverName, wsUrl, configHeaders, options) {
   const authService = services?.get(ICliServerAuthService_TOKEN);
   const params = await authService?.getWebSocketParams?.(serverName);
   if (params) {
     return appendQueryParams(wsUrl, params);
   }
-  return buildAuthenticatedWebSocketUrl(wsUrl, () => resolveServerHeaders(services, serverName, configHeaders));
+  return buildServerWebSocketUrl(
+    wsUrl,
+    () => resolveServerHeaders(services, serverName, configHeaders),
+    options
+  );
+}
+function toHttpBaseUrl(wsUrl) {
+  const url = new URL(wsUrl);
+  const wsSegment = url.pathname.indexOf("/ws/");
+  const basePath = wsSegment >= 0 ? url.pathname.slice(0, wsSegment) : "";
+  const protocol = url.protocol === "wss:" || url.protocol === "https:" ? "https:" : "http:";
+  return `${protocol}//${url.host}${basePath}`;
+}
+async function fetchWebSocketTicket(httpBase, headers) {
+  try {
+    const response = await fetch(`${httpBase}${CLI_WS_TICKET_PATH}`, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: "{}"
+    });
+    if (!response.ok) return void 0;
+    const body = await response.json();
+    return typeof body?.ticket === "string" && body.ticket ? body.ticket : void 0;
+  } catch {
+    return void 0;
+  }
 }
 function appendQueryParams(url, params) {
   const entries = Object.entries(params);
@@ -4211,6 +4259,7 @@ exports.API_VERSION = API_VERSION;
 exports.BrowserFileTransferService = BrowserFileTransferService;
 exports.CANCELLATION_ERROR_MESSAGE = CANCELLATION_ERROR_MESSAGE;
 exports.CLI_CONFIGURE_STORE_NAME = CLI_CONFIGURE_STORE_NAME;
+exports.CLI_WS_TICKET_PATH = CLI_WS_TICKET_PATH;
 exports.CancellablePromise = CancellablePromise;
 exports.CliAccessDeniedError = CliAccessDeniedError;
 exports.CliBackgroundColor = CliBackgroundColor;
@@ -4255,6 +4304,7 @@ exports.ServerVersionNegotiator = ServerVersionNegotiator;
 exports.appendQueryParams = appendQueryParams;
 exports.bootCliModule = bootCliModule;
 exports.buildAuthenticatedWebSocketUrl = buildAuthenticatedWebSocketUrl;
+exports.buildServerWebSocketUrl = buildServerWebSocketUrl;
 exports.clearTerminalLine = clearTerminalLine;
 exports.cliAccessMetadataGuards = cliAccessMetadataGuards;
 exports.cliAuthorize = cliAuthorize;