@qodalis/cli-core 2.0.0-beta.13 → 2.0.0-beta.14

package/public-api.d.mts

@@ -637,6 +637,32 @@ declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
  * Token for the HTTP client service.
  */
 declare const ICliHttpClient_TOKEN = "cli-http-client";
+/**
+ * Token for the user event service (lifecycle events).
+ */
+declare const ICliUserEventService_TOKEN = "cli-user-event-service";
+/**
+ * Token for the audit service (persistent event logging).
+ */
+declare const ICliAuditService_TOKEN = "cli-audit-service";
+/**
+ * Token for the authorization service ({@link ICliAuthorizationService}).
+ * Provided by an auth module (e.g. `@qodalis/cli-users`); absent otherwise.
+ */
+declare const ICliAuthorizationService_TOKEN = "cli-authorization-service";
+/**
+ * Token for the permission registry ({@link ICliPermissionRegistry}).
+ * Always provided by the CLI engine.
+ */
+declare const ICliPermissionRegistry_TOKEN = "cli-permission-registry";
+/**
+ * Token for the sessions service ({@link ICliSessionsService}).
+ */
+declare const ICliSessionsService_TOKEN = "cli-sessions-service";
+/**
+ * Token for the persistent key-value store used by modules (setup state, etc.).
+ */
+declare const ICliKeyValueStore_TOKEN = "cli-key-value-store";
 
 /**
  * Abstract permission service for checking rwx permissions on resources.
@@ -990,6 +1016,235 @@ interface ICliTextAnimator extends ICliProgressBar {
     showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
 }
 
+/**
+ * Result of a guard check.
+ *
+ * - `true` or `undefined`: allow the command.
+ * - `false`: block it with the generic message `<command>: permission denied`.
+ * - a non-empty `string`: block it and print this message.
+ * - `{ allowed, message }`: explicit form; `message` is used when `allowed` is false.
+ */
+type CliCommandGuardResult = boolean | string | void | {
+    allowed: boolean;
+    message?: string;
+};
+/**
+ * A global command guard: a check that runs before **every** command, across
+ * all processors and modules, and can block it.
+ *
+ * Use guards for cross-cutting policies such as authentication, permission
+ * checks, feature flags, maintenance windows or rate limiting, instead of
+ * repeating the check inside each processor.
+ *
+ * ## When guards run
+ *
+ * For each command the executor:
+ * 1. parses the input and resolves the processor (and sub-processor);
+ * 2. handles global parameters such as `--help` (help is never guarded);
+ * 3. extracts the positional value into `command.value`;
+ * 4. **runs the guards**;
+ * 5. validates required values/parameters, runs processor hooks and finally
+ *    calls `processCommand`.
+ *
+ * Guards run in ascending `priority` (default `0`). For each guard the executor
+ * calls `appliesTo` (if defined) and skips the guard when it returns `false`;
+ * otherwise it awaits `canActivate`. The **first** guard that blocks stops the
+ * chain: its message is written as an error and the command exits with code
+ * `-1`. A guard that throws (in `appliesTo` or `canActivate`) also blocks the
+ * command, so a broken guard fails closed.
+ *
+ * ## Access to the context
+ *
+ * Both `appliesTo` and `canActivate` receive the {@link ICliExecutionContext}
+ * of the command about to run, so a guard can:
+ * - resolve services with `context.services.get(...)` / `getRequired(...)`
+ *   (e.g. a policy, feature-flag or permission service registered by any
+ *   module) to decide **what** should be guarded and **whether** it may run;
+ * - inspect `context.userSession` for the signed-in user and their groups;
+ * - read the processor's `metadata` (for example `requireAuth` or
+ *   `requiredGroups`) and the parsed `command` (`command.value`, `command.args`);
+ * - prompt the user via `context.reader` (e.g. a confirmation guard).
+ *
+ * Guards should not write to the terminal to report a denial; return a message
+ * instead so the executor prints it consistently.
+ *
+ * ## Registering guards
+ *
+ * The preferred way is the module's `guards` array; the boot sequence
+ * registers each entry as a multi-provider under {@link ICliCommandGuard_TOKEN}.
+ * Several modules can contribute guards; all of them run.
+ *
+ * ```ts
+ * const billingModule: ICliModule = {
+ *     apiVersion: 2,
+ *     name: 'billing',
+ *     processors: [new InvoiceProcessor()],
+ *     guards: [billingGuard],
+ * };
+ * ```
+ *
+ * Guards can also be added at runtime (e.g. from `onInit`):
+ *
+ * ```ts
+ * context.services.set({ provide: ICliCommandGuard_TOKEN, useValue: myGuard, multi: true });
+ * ```
+ *
+ * ## Example: policy resolved from a service
+ *
+ * ```ts
+ * const featureFlagGuard: ICliCommandGuard = {
+ *     name: 'feature-flags',
+ *     // Only guard commands that are behind a flag; the flag list comes from a service
+ *     appliesTo: (processor, _command, context) =>
+ *         context.services.get<FeatureFlags>(FeatureFlags_TOKEN)?.isFlagged(processor.command) ?? false,
+ *     canActivate: async (_command, processor, context) => {
+ *         const flags = context.services.getRequired<FeatureFlags>(FeatureFlags_TOKEN);
+ *         return (await flags.isEnabled(processor.command, context.userSession?.user))
+ *             ? true
+ *             : `${processor.command}: not available for your account`;
+ *     },
+ * };
+ * ```
+ *
+ * ## Without a guard-providing module
+ *
+ * Guards are opt-in. When no guard is registered every command runs as before.
+ * The engine registers three built-in guards that enforce the processor access
+ * metadata (`requireAuth`, `requiredGroups`, `requiredPermissions`); they stay
+ * inactive until an auth module (e.g. `@qodalis/cli-users`) registers an
+ * `ICliAuthorizationService`, so without one that metadata is informational.
+ */
+interface ICliCommandGuard {
+    /** Unique name, shown in diagnostics when the guard throws. */
+    name: string;
+    /** Execution order; lower runs first. Defaults to `0`. */
+    priority?: number;
+    /**
+     * Optional filter deciding whether this guard is relevant for the command.
+     * Return `false` to skip the guard. When omitted the guard applies to
+     * every command. May be async, and may use `context` to resolve services.
+     */
+    appliesTo?(processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
+    /**
+     * Decide whether the command may run. See {@link CliCommandGuardResult}
+     * for the accepted return values.
+     */
+    canActivate(command: CliProcessCommand, processor: ICliCommandProcessor, context: ICliExecutionContext): CliCommandGuardResult | Promise<CliCommandGuardResult>;
+}
+/** DI token for {@link ICliCommandGuard}; register guards as multi-providers. */
+declare const ICliCommandGuard_TOKEN = "cli-command-guard";
+
+/**
+ * A permission an extension uses, declared so tools (`perms --list`,
+ * `groupmod --grant` completion, docs) can show it. Declaring is optional:
+ * any `resource:action` string can be granted and checked.
+ */
+interface CliPermissionDefinition {
+    /** Permission string, `resource:action` (e.g. `files:chown`). */
+    name: string;
+    /** Human readable description. */
+    description?: string;
+    /** Module that declared it (filled in at registration). */
+    module?: string;
+}
+/** Registry of permissions declared by modules (`ICliModule.permissions`). */
+interface ICliPermissionRegistry {
+    register(definitions: CliPermissionDefinition[], module?: string): void;
+    list(): CliPermissionDefinition[];
+    get(name: string): CliPermissionDefinition | undefined;
+}
+/** The identity checks are made against. */
+interface ICliPrincipal {
+    /** User id */
+    id: string;
+    /** Login name (used as file owner) */
+    name: string;
+    /** Group (role) names */
+    groups: string[];
+    /** Effective permissions (union of the groups' permissions) */
+    permissions: string[];
+}
+/** rwx-style protected resource (files, directories, or anything an extension owns). */
+interface ICliProtectedResource {
+    ownership?: ICliOwnership;
+    /** 9-char mode string, e.g. `rwxr-x---` */
+    permissions?: string;
+}
+type CliAccessAction = 'read' | 'write' | 'execute';
+/**
+ * Authorization service. Provided by an auth module (the users module provides
+ * one in local and in server mode). Extensions should use the helpers
+ * {@link cliAuthorize} / {@link cliCanAccess}, which allow everything when no
+ * authorization service is registered.
+ */
+interface ICliAuthorizationService {
+    /** The signed-in principal, or undefined when nobody is signed in. */
+    getPrincipal(): ICliPrincipal | undefined;
+    /** Does the current principal hold `permission` (wildcards honoured)? */
+    can(permission: string): boolean;
+    /**
+     * rwx check on a resource for the current principal (owner / group / other).
+     * Principals holding `*` or any of `bypassPermissions` are always allowed.
+     * Resources without a mode or ownership are allowed.
+     */
+    canAccess(resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
+}
+/** Thrown when an operation is not permitted. The message is user facing. */
+declare class CliAccessDeniedError extends Error {
+    readonly code = "EACCES";
+    constructor(message?: string);
+}
+/** True for {@link CliAccessDeniedError} (also across bundle copies). */
+declare function isCliAccessDeniedError(error: unknown): error is CliAccessDeniedError;
+/**
+ * Check a permission for the current principal. Returns `true` when no
+ * authorization service is registered (no auth module loaded).
+ */
+declare function cliAuthorize(context: Pick<ICliExecutionContext, 'services'>, permission: string): boolean;
+/**
+ * rwx check for the current principal. Returns `true` when no authorization
+ * service is registered.
+ */
+declare function cliCanAccess(context: Pick<ICliExecutionContext, 'services'>, resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
+/**
+ * Reference rwx evaluation shared by implementations of
+ * {@link ICliAuthorizationService.canAccess}.
+ */
+declare function cliEvaluateAccess(principal: ICliPrincipal | undefined, resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
+
+/** A sign-in session as listed by {@link ICliSessionsService}. Never carries a token. */
+interface ICliSessionInfo {
+    id: string;
+    userId: string;
+    userName: string;
+    createdAt: number;
+    lastActivity: number;
+    /** When the session expires if idle; undefined when there is no timeout */
+    expiresAt?: number;
+    /** True for the caller's own session */
+    current?: boolean;
+    metadata?: {
+        userAgent?: string;
+        remoteAddress?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Lists and revokes sign-in sessions. Implemented locally (sessions of this
+ * browser) and by servers (all sessions). Used by `sessions` / `session-kick`.
+ */
+interface ICliSessionsService {
+    /** All sessions visible to the caller */
+    list(): Promise<ICliSessionInfo[]>;
+    /** Revoke a session by id */
+    revoke(sessionId: string, reason?: string): Promise<void>;
+    /** Revoke every session of a user (optionally keeping one) */
+    revokeUser(userId: string, options?: {
+        exceptSessionId?: string;
+        reason?: string;
+    }): Promise<void>;
+}
+
 /**
  * Represents a service that manages user sessions in the CLI
  */
@@ -1032,8 +1287,17 @@ interface ICliGroupsStoreService {
     getGroups(): Observable<ICliGroup[]>;
     /** Gets a group by id or name */
     getGroup(id: string): Observable<ICliGroup | undefined>;
-    /** Creates a new group */
-    createGroup(name: string, description?: string): Promise<ICliGroup>;
+    /** Creates a new group (role), optionally with permissions */
+    createGroup(name: string, description?: string, permissions?: string[]): Promise<ICliGroup>;
+    /** Updates a group's description and/or permissions (by id or name) */
+    updateGroup(id: string, updates: {
+        description?: string;
+        permissions?: string[];
+    }): Promise<ICliGroup>;
+    /** Adds a user (id or name) to a group (id or name) */
+    addMember(groupId: string, userId: string): Promise<void>;
+    /** Removes a user (id or name) from a group (id or name) */
+    removeMember(groupId: string, userId: string): Promise<void>;
     /** Deletes a group by id */
     deleteGroup(id: string): Promise<void>;
     /** Gets all users that belong to a group */
@@ -1043,16 +1307,32 @@ interface ICliGroupsStoreService {
  * Represents a service that handles authentication in the CLI
  */
 interface ICliAuthService {
-    /** Authenticates a user and returns a session */
-    login(username: string, password: string): Promise<ICliUserSession>;
-    /** Ends the current session */
+    /**
+     * Authenticates a user and returns a session. `password` may be omitted
+     * only when the implementation allows passwordless sign-in.
+     */
+    login(username: string, password?: string): Promise<ICliUserSession>;
+    /** Ends the current session (the CLI is left signed out) */
     logout(): Promise<void>;
-    /** Sets or updates a user's password */
-    setPassword(userId: string, password: string): Promise<void>;
+    /**
+     * Switch to another user (`su`). Requires the target's password unless
+     * the caller may skip it (implementation-defined, e.g. `users:update`).
+     * Goes through the same lockout, events and audit as `login`.
+     */
+    switchUser?(username: string, password?: string): Promise<ICliUserSession>;
+    /**
+     * Sets or updates a user's password.
+     * @param currentPassword The user's current password, when changing one's own
+     * password. Server-backed implementations forward it so the server can
+     * re-check it; local implementations may ignore it.
+     */
+    setPassword(userId: string, password: string, currentPassword?: string): Promise<void>;
     /** Verifies a password against stored credentials */
     verifyPassword(userId: string, password: string): Promise<boolean>;
     /** Hashes a password with a salt using Web Crypto SHA-256 */
     hashPassword(password: string, salt: string): Promise<string>;
+    /** Validate password against policy. Returns error message or null if valid. */
+    validatePassword?(password: string): string | null;
 }
 
 /**
@@ -1434,6 +1714,24 @@ type CliProcessorMetadata = Record<string, any> & {
      * If the installed CLI version is lower, the processor will be skipped during boot.
      */
     requiredCliVersion?: string;
+    /**
+     * If true, the command requires a signed-in user. Enforced by a
+     * core guard that activates when an auth module registers an
+     * `ICliAuthorizationService` (e.g. `@qodalis/cli-users`); without one the
+     * flag is informational.
+     */
+    requireAuth?: boolean;
+    /**
+     * The signed-in user must belong to at least one of these groups
+     * (e.g. `['admin']`). Implies `requireAuth`. Enforced like `requireAuth`.
+     */
+    requiredGroups?: string[];
+    /**
+     * The signed-in user must hold **all** of these permissions
+     * (e.g. `['users:create']`), granted through their groups (roles).
+     * Implies `requireAuth`. Enforced like `requireAuth`.
+     */
+    requiredPermissions?: string[];
     /**
      * If true, the processor is hidden from the help command listing.
      * The command still works when typed directly and `help <command>` still shows its details.
@@ -1670,6 +1968,39 @@ interface ICliHttpClient {
      */
     options<T = any>(url: string, options?: CliHttpRequestOptions): Promise<T>;
 }
+/**
+ * Error thrown by `ICliHttpClient` JSON helpers (`get`, `post`, `put`,
+ * `patch`, `delete`, `options`) when the server responds with a non-2xx status.
+ *
+ * Exposes the HTTP status so callers can react to specific responses
+ * (for example, clearing a stored session token on `401`).
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await context.http.get(url);
+ * } catch (e) {
+ *     if (e instanceof CliHttpError && e.status === 401) {
+ *         // token expired or revoked
+ *     }
+ * }
+ * ```
+ */
+declare class CliHttpError extends Error {
+    /** HTTP status code of the failed response */
+    readonly status: number;
+    /** HTTP status text of the failed response */
+    readonly statusText: string;
+    /** Parsed JSON error body, when the server returned one */
+    readonly body?: unknown | undefined;
+    constructor(message: string, 
+    /** HTTP status code of the failed response */
+    status: number, 
+    /** HTTP status text of the failed response */
+    statusText?: string, 
+    /** Parsed JSON error body, when the server returned one */
+    body?: unknown | undefined);
+}
 
 type CliNotificationLevel = 'info' | 'success' | 'warn' | 'error';
 interface CliNotification {
@@ -1695,6 +2026,64 @@ interface ICliNotifier {
     readonly change$: Observable<CliNotification | undefined>;
 }
 
+/** Represents a user lifecycle event */
+interface ICliUserEvent {
+    /** The type of event that occurred */
+    type: 'login' | 'logout' | 'login_failed' | 'user_created' | 'user_deleted' | 'user_updated' | 'password_changed' | 'user_switched' | 'user_disabled' | 'user_enabled' | 'group_created' | 'group_updated' | 'group_deleted' | 'group_member_added' | 'group_member_removed' | 'session_revoked' | 'audit_cleared';
+    /** The user involved in the event (for group events: the acting user) */
+    user: ICliUser;
+    /** The acting user's name, when different from `user` (e.g. an admin) */
+    actor?: string;
+    /** When the event occurred */
+    timestamp: number;
+    /** Optional additional details */
+    details?: string;
+    /** `user_updated`: the user's name before a rename (set only when the name changed) */
+    previousName?: string;
+}
+/** Service that emits user lifecycle events for plugins to subscribe to */
+interface ICliUserEventService {
+    /** Observable stream of user events */
+    readonly events$: Observable<ICliUserEvent>;
+    /** Emit a user event */
+    emit(event: ICliUserEvent): void;
+}
+
+/** A single audit log entry */
+interface ICliAuditEntry {
+    /** Entry id (server-assigned in server mode) */
+    id?: string;
+    /** When the event occurred */
+    timestamp: number;
+    /** Event type (e.g., 'login', 'logout', 'login_failed') */
+    event: string;
+    /** Username involved */
+    username: string;
+    /** Optional additional details */
+    details?: string;
+    /** Id of the user the entry is about, when known */
+    userId?: string;
+    /** The user who performed the action, when different from `username` */
+    actor?: string;
+    /** Id of the acting user, when different from the subject */
+    actorId?: string;
+    /** Extra data (e.g. remote address) */
+    metadata?: Record<string, unknown>;
+}
+/** Service for persistent audit logging */
+interface ICliAuditService {
+    /** Log an audit entry (timestamp is added automatically) */
+    log(entry: Omit<ICliAuditEntry, 'timestamp'>): Promise<void>;
+    /** Retrieve audit entries with optional filtering */
+    getEntries(options?: {
+        limit?: number;
+        event?: string;
+        username?: string;
+    }): Promise<ICliAuditEntry[]>;
+    /** Clear all audit entries */
+    clear(): Promise<void>;
+}
+
 /**
  * A managed timer handle returned by createInterval/createTimeout.
  * Managed timers are automatically cleared when full-screen mode exits
@@ -2227,6 +2616,17 @@ interface ICliModule {
     processors?: ICliCommandProcessor[];
     /** Services registered into the shared service container */
     services?: CliProvider[];
+    /**
+     * Global command guards contributed by this module. They are registered
+     * when the module boots and run before every command (across all modules),
+     * e.g. authentication or permission checks. See {@link ICliCommandGuard}.
+     */
+    guards?: ICliCommandGuard[];
+    /**
+     * Permissions this module uses (`resource:action`), registered in the
+     * {@link ICliPermissionRegistry} at boot so they can be listed and granted.
+     */
+    permissions?: CliPermissionDefinition[];
     /** Module configuration, set via configure() */
     config?: Record<string, any>;
     /**
@@ -2435,7 +2835,35 @@ interface ICliServerAuthTokenProvider {
      * @returns Headers to merge into the request, or an empty object
      */
     getHeaders(serverName: string): Record<string, string>;
+    /**
+     * Optional: query parameters for WebSocket upgrades to this server (e.g. a
+     * short-lived single-use ticket). Called right before each connection.
+     * Return `undefined` when this provider does not handle the server.
+     * When any provider returns params, headers are NOT copied into the URL
+     * (so bearer tokens never appear in WebSocket URLs).
+     */
+    getWebSocketParams?(serverName: string): Promise<Record<string, string> | undefined>;
+}
+/**
+ * Minimal view of the CLI server manager (token `ICliServerManager_TOKEN`),
+ * e.g. for auth modules that must refresh a server after sign-in.
+ */
+interface ICliServerManager {
+    /** Reconnect a server: re-fetch its commands and reopen its event socket. */
+    reconnect(name: string): Promise<{
+        success: boolean;
+        commandCount: number;
+    }>;
+    /**
+     * The server a command should target when the user names none: the
+     * default server (`server default`) when connected, otherwise the first
+     * connected server. `null` when no server is connected (for example every
+     * server requires a login the user has not done yet).
+     */
+    preferredServer?(): string | null;
 }
+/** Token for {@link ICliServerManager} */
+declare const ICliServerManager_TOKEN = "cli-server-manager";
 /**
  * Internal service that resolves auth headers for a server by merging:
  * 1. Static/dynamic headers from `CliServerConfig.headers`
@@ -2453,6 +2881,11 @@ interface ICliServerAuthService {
      * @returns Merged headers ready for use in fetch/WebSocket calls
      */
     getHeaders(serverName: string, configHeaders?: CliHeadersProvider): Record<string, string>;
+    /**
+     * WebSocket upgrade query params from the registered token providers, or
+     * `undefined` when no provider handles this server.
+     */
+    getWebSocketParams?(serverName: string): Promise<Record<string, string> | undefined>;
 }
 
 /**
@@ -2616,6 +3049,12 @@ interface ICliUser {
     updatedAt: number;
     /** Whether the account is locked */
     disabled?: boolean;
+    /** The user must set a new password before doing anything else */
+    mustChangePassword?: boolean;
+    /** Extensible metadata (department, phone, preferences, etc.) */
+    data?: Record<string, any>;
+    /** Timestamp of last successful login */
+    lastLoginAt?: number;
 }
 /**
  * Represents user credentials (shadow pattern — stored separately from ICliUser)
@@ -2642,6 +3081,16 @@ interface ICliGroup {
     description?: string;
     /** Group creation timestamp */
     createdAt: number;
+    /**
+     * Permissions granted to every member of the group. Groups act as roles.
+     * Permission strings are `resource:action` (e.g. `users:create`), with
+     * `*` wildcards (`users:*`, `*`). See {@link cliPermissionMatches}.
+     */
+    permissions?: string[];
+    /** Built-in groups (`admin`, `users`) cannot be deleted */
+    builtIn?: boolean;
+    /** Last modification timestamp */
+    updatedAt?: number;
 }
 /**
  * Represents an active user session
@@ -2655,6 +3104,11 @@ interface ICliUserSession {
     loginTime: number;
     /** Timestamp of last activity */
     lastActivity: number;
+    /**
+     * Effective permissions of the user (union of their groups' permissions),
+     * resolved by the users module at login and refreshed when groups change.
+     */
+    permissions?: string[];
     /** Extensible data (tokens, metadata, etc.) */
     data?: Record<string, any>;
 }
@@ -2861,6 +3315,15 @@ declare class ServerVersionNegotiator {
  * @returns The WebSocket URL with auth credentials appended as query parameters
  */
 declare function buildAuthenticatedWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider): 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}).
+ */
+declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider): Promise<string>;
+/** Append query params to a URL that may already have some. */
+declare function appendQueryParams(url: string, params: Record<string, string>): string;
 
 /**
  * Derives CLI panel CSS custom property values from an xterm ITheme object.
@@ -2910,6 +3373,85 @@ declare function stripAnsi(text: string): string;
  */
 declare function visibleLength(text: string): number;
 
+/**
+ * Permission strings are `resource:action` (for example `users:create`).
+ * A trailing `*` segment matches anything at that level and below; a `*`
+ * in any other position matches exactly one segment:
+ *
+ * | granted       | matches                               |
+ * |---------------|---------------------------------------|
+ * | `*`           | every permission                      |
+ * | `users:*`     | `users:create`, `users:delete`, ...   |
+ * | `*:read`      | `users:read`, `groups:read`, ...      |
+ * | `users:read`  | only `users:read`                     |
+ *
+ * Matching is case-insensitive.
+ */
+declare function cliPermissionMatches(granted: string, required: string): boolean;
+/** True when any granted permission matches `required`. */
+declare function cliHasPermission(granted: readonly string[] | undefined, required: string): boolean;
+/** The subset of `required` permissions not covered by `granted`. */
+declare function cliMissingPermissions(granted: readonly string[] | undefined, required: readonly string[]): string[];
+/** Union of permissions, de-duplicated, preserving first-seen order. */
+declare function cliMergePermissions(...lists: (readonly string[] | undefined)[]): string[];
+/**
+ * Built-in permissions used by the users module. Other modules define their
+ * own (e.g. `deploy:run`); any string in `resource:action` form works.
+ */
+/** Permissions for remote CLI server features. */
+declare const CliServerPermissions: {
+    /** Open a remote shell on a server (`ssh`) */
+    readonly ShellExecute: "shell:execute";
+};
+declare const CliUsersPermissions: {
+    readonly UsersRead: "users:read";
+    readonly UsersCreate: "users:create";
+    readonly UsersUpdate: "users:update";
+    readonly UsersDelete: "users:delete";
+    readonly GroupsRead: "groups:read";
+    readonly GroupsCreate: "groups:create";
+    readonly GroupsUpdate: "groups:update";
+    readonly GroupsDelete: "groups:delete";
+    readonly SessionsRead: "sessions:read";
+    readonly SessionsRevoke: "sessions:revoke";
+    readonly AuditRead: "audit:read";
+    readonly AuditClear: "audit:clear";
+};
+
+/**
+ * `metadata.requireAuth` (also implied by `requiredGroups` /
+ * `requiredPermissions`): the command needs a signed-in principal.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequireAuthGuard: ICliCommandGuard;
+/**
+ * `metadata.requiredGroups`: the principal must belong to at least one group.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequiredGroupsGuard: ICliCommandGuard;
+/**
+ * `metadata.requiredPermissions`: the principal must hold all permissions.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequiredPermissionsGuard: ICliCommandGuard;
+/**
+ * Guards enforcing access metadata on processors. Registered by the CLI
+ * engine; they do nothing until an auth module registers an
+ * {@link ICliAuthorizationService}.
+ */
+declare const cliAccessMetadataGuards: ICliCommandGuard[];
+
+/**
+ * The server a command should use when the user does not name one.
+ *
+ * Prefers the server manager's choice (the default server, else the first
+ * connected one) so a command does not pick a server that is down or that
+ * rejects the user (a protected server they have not signed in to). Falls
+ * back to the first configured server when no manager is available or
+ * nothing is connected, so callers still get a clear error from that server.
+ */
+declare function cliDefaultServer(context: Pick<ICliExecutionContext, 'services' | 'options'>): CliServerConfig | undefined;
+
 /**
  * Retrieve a parameter's value from the parsed arguments, checking aliases.
  * @param p The parameter descriptor
@@ -3062,7 +3604,7 @@ interface CliThemeInfo {
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.13";
+declare const LIBRARY_VERSION = "2.0.0-beta.14";
 declare const API_VERSION = 2;
 
 /**
@@ -3123,4 +3665,4 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, type CliFullScreenOptions, type CliHeadersProvider, type CliHttpRequestOptions, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNotification, type CliNotificationLevel, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPaneState, type CliPanelPosition, type CliPanelState, type CliPanelTabState, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliServiceLogLevel, type CliState, type CliStateConfiguration, type CliTableOptions, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type DefaultThemesType, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurableModule, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, ICliFilePickerProvider_TOKEN, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliHttpClient, ICliHttpClient_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliNotifier, type ICliOwnership, type ICliPanelRef, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServerAuthService, ICliServerAuthService_TOKEN, type ICliServerAuthTokenProvider, ICliServerAuthTokenProvider_TOKEN, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, buildAuthenticatedWebSocketUrl, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };
+export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAccessAction, CliAccessDeniedError, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliCommandGuardResult, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, type CliFullScreenOptions, type CliHeadersProvider, CliHttpError, type CliHttpRequestOptions, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNotification, type CliNotificationLevel, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPaneState, type CliPanelPosition, type CliPanelState, type CliPanelTabState, type CliPercentageProgressBarUpdateValueOptions, type CliPermissionDefinition, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, CliServerPermissions, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliServiceLogLevel, type CliState, type CliStateConfiguration, type CliTableOptions, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, CliUsersPermissions, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type DefaultThemesType, type ICliAuditEntry, type ICliAuditService, ICliAuditService_TOKEN, type ICliAuthService, ICliAuthService_TOKEN, type ICliAuthorizationService, ICliAuthorizationService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandGuard, ICliCommandGuard_TOKEN, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurableModule, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, ICliFilePickerProvider_TOKEN, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliHttpClient, ICliHttpClient_TOKEN, type ICliInputReader, type ICliKeyValueStore, ICliKeyValueStore_TOKEN, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliNotifier, type ICliOwnership, type ICliPanelRef, type ICliPercentageProgressBar, type ICliPermissionRegistry, ICliPermissionRegistry_TOKEN, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliPrincipal, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliProtectedResource, type ICliServerAuthService, ICliServerAuthService_TOKEN, type ICliServerAuthTokenProvider, ICliServerAuthTokenProvider_TOKEN, type ICliServerManager, ICliServerManager_TOKEN, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSessionInfo, type ICliSessionsService, ICliSessionsService_TOKEN, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserEvent, type ICliUserEventService, ICliUserEventService_TOKEN, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, appendQueryParams, bootCliModule, bootUmdModule, buildAuthenticatedWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };