@e-xi/xion 0.0.6

package/dist/main/auth/jwt-auth-manager.d.ts

@@ -0,0 +1,302 @@
+import type { XoAppAbstract } from '../app/xo-app-abstract';
+import type { JwtAuthProviderAbstract } from './jwt-auth-provider-abstract';
+import type { JwtAuthorizationContext } from './types/jwt-auth-manager';
+/** 任意业务 JWT Provider */
+type AnyJwtAuthProvider = JwtAuthProviderAbstract<any, any, any, any, any>;
+/**
+ * JWT 认证管理器
+ * <p>访问令牌只保存在主进程内存，刷新令牌通过 safeStorage 加密持久化</p>
+ * @class JwtAuthManager
+ */
+export declare class JwtAuthManager {
+    /** Xion 应用 */
+    private readonly xoApp;
+    /** 业务 JWT Provider */
+    private readonly provider?;
+    /** JWT 加密存储 */
+    private readonly store;
+    /** 是否已初始化 */
+    private initialized;
+    /** 当前认证状态 */
+    private state;
+    /** 访问令牌（内存中管理） */
+    private accessToken?;
+    /** 访问令牌绝对过期时间戳（内存中管理） */
+    private accessTokenExpiresAt?;
+    /** 内存中的刷新会话 */
+    private storedRefreshSession?;
+    /** 自动刷新定时器 */
+    private refreshTimer?;
+    /** 当前刷新任务，用于合并并发刷新 */
+    private refreshPromise?;
+    /** 当前退出任务，用于合并并发退出并阻止登录与退出交错执行 */
+    private logoutPromise?;
+    /** 认证操作版本号，用于阻止旧登录或刷新请求回写新会话 */
+    private authRevision;
+    /** 上一次观察到的远程服务连接状态 */
+    private remoteConnected;
+    /** 是否已输出安全存储不可用警告 */
+    private encryptionWarningLogged;
+    /**
+     * 构造函数
+     * @param {XoAppAbstract}      xoApp    Xion 应用
+     * @param {AnyJwtAuthProvider} provider 业务 JWT Provider
+     */
+    constructor(xoApp: XoAppAbstract, provider?: AnyJwtAuthProvider);
+    /**
+     * 是否已配置 JWT 认证
+     * @returns {boolean}
+     */
+    enabled(): boolean;
+    /**
+     * 获取当前认证操作版本
+     * @returns {number}
+     */
+    getAuthRevision(): number;
+    /**
+     * 获取由主进程管理的认证请求头名称
+     * <p>远程服务层使用这些名称阻止渲染进程伪造认证请求头</p>
+     * @returns {readonly string[]}
+     */
+    getAuthenticationHeaderNames(): readonly string[];
+    /**
+     * 获取远程服务管理器
+     * @returns {RemoteServiceManagerAbstract}
+     * @private
+     */
+    private getRemoteService;
+    /**
+     * 获取 Electron 默认会话
+     * @returns {Electron.Session}
+     * @private
+     */
+    private electronSession;
+    /**
+     * 初始化认证模块
+     * <p>启动时存在有效刷新会话则自动刷新；远程服务暂不可用时保留会话并等待恢复</p>
+     * @returns {boolean} 是否启动了认证模块
+     */
+    initialize(): boolean;
+    /**
+     * 获取可暴露给渲染进程的认证状态
+     * @returns {XoAuth.State}
+     */
+    getState(): XoAuth.State;
+    /**
+     * 登录
+     * @param {XoAuth.LoginRequest} request 登录请求
+     * @returns {Promise<XoAuth.State>}
+     */
+    login(request: XoAuth.LoginRequest): Promise<XoAuth.State>;
+    /**
+     * 退出登录
+     * <p>无论服务端退出是否成功，都会清除本地令牌</p>
+     * @returns {Promise<XoAuth.State>}
+     */
+    logout(): Promise<XoAuth.State>;
+    /**
+     * 执行一次退出登录请求
+     * @returns {Promise<XoAuth.State>}
+     * @private
+     */
+    private executeLogout;
+    /**
+     * 使用刷新令牌更新令牌对（强制刷新，即使访问令牌未过期也刷新）
+     * @returns {Promise<void>}
+     */
+    refreshAccessToken(): Promise<void>;
+    /**
+     * 在存在刷新会话且访问令牌需要刷新时更新令牌对
+     * @returns {Promise<void>}
+     */
+    refreshAccessTokenIfNeeded(): Promise<void>;
+    /**
+     * 执行一次刷新请求
+     * @returns {Promise<void>}
+     * @private
+     */
+    private executeRefresh;
+    /**
+     * 获取请求使用的 Authorization 上下文
+     * <p>访问令牌即将过期时先自动刷新；刷新暂时失败但旧令牌仍有效时继续使用旧令牌</p>
+     * @returns {Promise<JwtAuthorizationContext | undefined>}
+     */
+    getAuthorizationContext(): Promise<JwtAuthorizationContext | undefined>;
+    /**
+     * 处理携带访问令牌的请求返回 401
+     * <p>若其他并发请求已经完成令牌轮换，则直接返回新令牌，不重复刷新</p>
+     * @param {JwtAuthorizationContext} failedAuthorization 失败请求使用的 Authorization 上下文
+     * @returns {Promise<JwtAuthorizationContext | undefined>}
+     */
+    refreshAfterUnauthorized(failedAuthorization: JwtAuthorizationContext): Promise<JwtAuthorizationContext | undefined>;
+    /**
+     * 恢复磁盘中的加密刷新会话
+     * @returns {Promise<void>}
+     * @private
+     */
+    private restoreRefreshSession;
+    /**
+     * 应用并保存服务端返回的认证结果
+     * @param {XoAuth.AuthResult} authResult 认证结果
+     * @returns {void}
+     * @private
+     */
+    private applyAuthResult;
+    /**
+     * 校验令牌对
+     * @param {XoAuth.TokenPair} tokenPair 令牌对
+     * @returns {void}
+     * @private
+     */
+    private validateTokenPair;
+    /**
+     * 持久化刷新会话
+     * <p>持久化失败时保留内存会话，避免将服务端已经成功的登录误判为失败</p>
+     * @param {XoAuth.StoredRefreshSession} session 刷新会话
+     * @returns {void}
+     * @private
+     */
+    private persistRefreshSession;
+    /**
+     * 安排访问令牌到期前自动刷新
+     * @returns {void}
+     * @private
+     */
+    private scheduleRefresh;
+    /**
+     * 安排刷新失败后的重试
+     * @returns {void}
+     * @private
+     */
+    private scheduleRefreshRetry;
+    /**
+     * 清除本地会话
+     * @param {string} error 可选状态提示
+     * @returns {void}
+     * @private
+     */
+    private clearSession;
+    /**
+     * 清除自动刷新定时器
+     * @returns {void}
+     * @private
+     */
+    private clearRefreshTimer;
+    /**
+     * 当前访问令牌是否有效
+     * @returns {boolean}
+     * @private
+     */
+    private hasValidAccessToken;
+    /**
+     * 判断访问令牌是否需要刷新
+     * <p>访问令牌缺失、已经过期或进入 Provider 配置的提前刷新窗口时返回 true</p>
+     * @returns {boolean}
+     * @private
+     */
+    private shouldRefreshAccessToken;
+    /**
+     * 构建 Authorization 请求头
+     * @param {string} accessToken 访问令牌
+     * @returns {string}
+     * @private
+     */
+    private buildAuthorizationHeader;
+    /**
+     * 构建设备标识请求头
+     * @returns {Readonly<Record<string, string>> | undefined}
+     * @private
+     */
+    getDeviceIdHeaders(): Readonly<Record<string, string>> | undefined;
+    /**
+     * 构建访问令牌请求头上下文
+     * @param {number} revision     认证操作版本
+     * @param {string} accessHeader 可选访问令牌请求头值
+     * @returns {JwtAuthorizationContext}
+     * @private
+     */
+    private buildAuthorizationContext;
+    /**
+     * 获取业务 Provider，未配置时抛出错误
+     * @returns {AnyJwtAuthProvider}
+     * @private
+     */
+    private requireProvider;
+    /**
+     * 校验刷新接口响应状态，确保 HTTP 状态码为 200
+     * @param {XoRemoteService.Response} response 响应
+     * @returns {void}
+     * @private
+     */
+    private requireRefreshResponseStatusOK;
+    /**
+     * 更新状态并同步全部窗口
+     * @param {Partial<XoAuth.State>} state 状态变更
+     * @returns {void}
+     * @private
+     */
+    private updateState;
+    /**
+     * 更新为初始化状态
+     * @param {XoAuth.User} user 持久化的用户快照
+     * @returns {void}
+     * @private
+     */
+    private updateStateInitializing;
+    /**
+     * 更新为认证中状态
+     * @returns {void}
+     * @private
+     */
+    private updateStateAuthenticating;
+    /**
+     * 更新为刷新中状态
+     * @returns {void}
+     * @private
+     */
+    private updateStateRefreshing;
+    /**
+     * 更新为已认证状态
+     * @param {XoAuth.User} user 认证用户
+     * @param {string}      error 可选错误信息
+     * @returns {void}
+     * @private
+     */
+    private updateStateAuthenticated;
+    /**
+     * 更新为未认证状态
+     * @param {string} error 可选错误信息
+     * @returns {void}
+     * @private
+     */
+    private updateStateUnauthenticated;
+    /**
+     * 更新为错误状态
+     * @param {string} error 错误信息
+     * @returns {void}
+     * @private
+     */
+    private updateStateError;
+    /**
+     * 校验接口响应状态，确保 HTTP 状态码为 200
+     * @param {XoRemoteService.Response} response 响应
+     * @param {string}                   action   操作名称
+     * @returns {void}
+     * @private
+     */
+    private requireResponseStatusOK;
+    /**
+     * 仅输出一次安全存储不可用警告
+     * @returns {void}
+     * @private
+     */
+    private onceLogEncryptionWarning;
+    /**
+     * 获取错误信息
+     * @param {unknown} error 错误
+     * @returns {string}
+     * @private
+     */
+    private errorMessage;
+}
+export {};

package/dist/main/auth/jwt-auth-provider-abstract.d.ts

@@ -0,0 +1,100 @@
+/**
+ * JWT 认证业务提供器抽象类
+ * <p>Xion 负责令牌生命周期和安全存储，业务项目负责接口路径、请求结构与响应解析。</p>
+ * @template TUser            用户类型
+ * @template TLoginRequest    登录请求类型
+ * @template TLoginResponse   登录响应类型
+ * @template TRefreshResponse 刷新响应类型
+ * @template TLogoutResponse  退出响应类型
+ * @class JwtAuthProviderAbstract
+ */
+export declare abstract class JwtAuthProviderAbstract<TUser = XoAuth.User, TLoginRequest = XoAuth.LoginRequest, TLoginResponse = unknown, TRefreshResponse = unknown, TLogoutResponse = unknown> {
+    /** 访问令牌提前刷新的时间，单位毫秒 */
+    readonly refreshBeforeExpiration: number;
+    /** 刷新失败后的重试间隔，单位毫秒 */
+    readonly refreshRetryDelay: number;
+    /** 访问令牌请求头使用的认证方案名称 */
+    readonly authorizationScheme: string;
+    /** 访问令牌使用的请求头名称 */
+    readonly authorizationHeaderName: string;
+    /** 刷新令牌使用的请求头名称 */
+    readonly refreshTokenHeaderName: string;
+    /** JWT 生命周期请求是否使用设备标识请求头 */
+    readonly useDeviceIdHeader: boolean;
+    /** 设备标识使用的请求头名称 */
+    readonly deviceIdHeaderName: string;
+    /** 登录接口方法 */
+    readonly loginMethod: XoRemoteService.Method;
+    /** 登录接口路径 */
+    abstract readonly loginPath: string;
+    /** 刷新令牌接口方法 */
+    readonly refreshMethod: XoRemoteService.Method;
+    /** 刷新令牌接口路径 */
+    abstract readonly refreshPath: string;
+    /** 退出登录接口方法 */
+    readonly logoutMethod: XoRemoteService.Method;
+    /** 退出登录接口路径 */
+    abstract readonly logoutPath: string;
+    /**
+     * 构建登录请求
+     * @param {TLoginRequest} request 登录请求数据
+     * @returns {XoRemoteService.JwtRequest<TLoginRequest>}
+     */
+    abstract loginRequest(request: TLoginRequest): XoRemoteService.JwtRequest<TLoginRequest>;
+    /**
+     * 解析登录响应
+     * @param {XoRemoteService.Response<TLoginResponse>} response 登录响应数据
+     * @returns {XoAuth.AuthResult<TUser>}
+     */
+    abstract loginResponse(response: XoRemoteService.Response<TLoginResponse>): XoAuth.AuthResult<TUser>;
+    /**
+     * 构建刷新请求
+     * @returns {XoRemoteService.JwtRequest}
+     */
+    abstract refreshRequest(): XoRemoteService.JwtRequest;
+    /**
+     * 解析刷新响应
+     * @param {XoRemoteService.Response<TRefreshResponse>} response 刷新响应
+     * @returns {XoAuth.AuthResult<TUser>}
+     */
+    abstract refreshResponse(response: XoRemoteService.Response<TRefreshResponse>): XoAuth.AuthResult<TUser>;
+    /**
+     * 构建退出登录请求
+     * @returns {XoRemoteService.JwtRequest}
+     */
+    abstract logoutRequest(): XoRemoteService.JwtRequest;
+    /**
+     * 解析退出登录响应
+     * @param {XoRemoteService.Response<TLogoutResponse>} response 退出登录响应
+     * @returns {void}
+     */
+    abstract logoutResponse(response: XoRemoteService.Response<TLogoutResponse>): void;
+    /**
+     * 校验业务接口路径
+     * @returns {void}
+     */
+    requireValidate(): void;
+    /**
+     * 校验单个业务接口路径
+     * @param {string} name 接口名称
+     * @param {string} path 接口路径
+     * @returns {void}
+     * @private
+     */
+    private validatePath;
+    /**
+     * 校验单个业务接口方法
+     * @param {string}                 name   接口名称
+     * @param {XoRemoteService.Method} method 接口方法
+     * @private
+     */
+    private validateMethod;
+    /**
+     * 校验认证请求头名称
+     * @param {string} name       认证头名称描述
+     * @param {string} headerName 认证请求头名称
+     * @returns {void}
+     * @private
+     */
+    private validateHeaderName;
+}

package/dist/main/auth/jwt-auth-refresh-rejected-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 刷新令牌被服务端拒绝错误
+ * <p>业务响应使用 HTTP 200 表示请求完成，但业务状态表示令牌失效时应抛出此错误。</p>
+ * @class JwtAuthRefreshRejectedError
+ */
+export declare class JwtAuthRefreshRejectedError extends Error {
+    /**
+     * 构造函数
+     * @param {string} message 错误信息
+     */
+    constructor(message?: string);
+}

package/dist/main/auth/jwt-auth-session-changed-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * JWT 认证会话已变化错误
+ * <p>用于阻止旧会话请求使用新会话令牌或向新会话返回旧响应</p>
+ * @class JwtAuthSessionChangedError
+ */
+export declare class JwtAuthSessionChangedError extends Error {
+    /**
+     * 构造函数
+     * @param {string} message 错误信息
+     */
+    constructor(message?: string);
+}

package/dist/main/auth/types/jwt-auth-manager.d.ts

@@ -0,0 +1,13 @@
+/**
+ * JWT Authorization 上下文
+ * <p>认证操作版本用于确保远程请求只能在同一登录会话内刷新令牌并重试</p>
+ * @interface JwtAuthorizationContext
+ */
+export interface JwtAuthorizationContext {
+    /** 访问令牌请求头名称 */
+    readonly headerName: string
+    /** 访问令牌请求头值 */
+    readonly header: string
+    /** 生成请求头时的认证操作版本 */
+    readonly revision: number
+}

package/dist/main/banner/banner-abstract.d.ts

@@ -0,0 +1,38 @@
+import type { XoAppAbstract } from '../app/xo-app-abstract';
+/**
+ * Banner 抽象类
+ * @class BannerAbstract
+ */
+export declare abstract class BannerAbstract {
+    /**
+     * Xion 应用
+     * @type {XoAppAbstract}
+     */
+    readonly xoApp: XoAppAbstract;
+    /**
+     * 构造函数
+     * @param {XoAppAbstract} xoApp Xion 应用
+     */
+    constructor(xoApp: XoAppAbstract);
+    /**
+     * Banner 配置
+     * @returns {XoBanner.Config}
+     * @protected
+     */
+    protected abstract config(): XoBanner.Config;
+    /**
+     * 设置 Banner
+     * @returns {string}
+     */
+    protected abstract banner(): string;
+    /**
+     * 获取 Banner
+     * @returns {string | undefined}
+     */
+    protected getBanner(): string[] | undefined;
+    /**
+     * 打印 Banner 行
+     * @param {(line: string) => void} writer 写入器
+     */
+    printBannerLines(writer: (line: string) => void): void;
+}

package/dist/main/banner/banner-manager.d.ts

@@ -0,0 +1,20 @@
+import { BannerAbstract } from './banner-abstract';
+/**
+ * 内置 Banner
+ * @class BannerManager
+ */
+export declare class BannerManager extends BannerAbstract {
+    /**
+     * 获取 Banner 配置
+     * @returns {XoBanner.Config}
+     * @protected
+     */
+    protected config(): XoBanner.Config;
+    /**
+     * 设置 Banner
+     * https://patorjk.com/software/taag/
+     * font: Sub-Zero
+     * @returns {string}
+     */
+    protected banner(): string;
+}

package/dist/main/banner/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Automatically generated by scripts/gen-exports.ts
+ */
+export * from './banner-abstract';
+export * from './banner-manager';
+export type * from './types/banner';

package/dist/main/banner/index.js

@@ -0,0 +1,10 @@
+import {
+  BannerAbstract,
+  BannerManager
+} from "../../chunk-files/chunk-5PKWVAQP.js";
+import "../../chunk-files/chunk-YLZRRUY7.js";
+import "../../chunk-files/chunk-P4CX6I4J.js";
+export {
+  BannerAbstract,
+  BannerManager
+};

package/dist/main/banner/types/banner.d.ts

@@ -0,0 +1,17 @@
+declare global {
+
+    // Banner
+    namespace XoBanner {
+
+        // 配置
+        interface Config {
+            // Banner 颜色
+            color?: keyof XoColor.Ansi
+
+            // 是否显示版本号
+            showVersion?: boolean
+        }
+    }
+}
+
+export {}

package/dist/main/config/app-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 定义应用配置
+ * @param {XoApp.Config} config 应用配置
+ * @returns {XoApp.Config}
+ */
+export declare const defineAppConfig: (config?: XoApp.Config) => XoApp.Config;

package/dist/main/config/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Automatically generated by scripts/gen-exports.ts
+ */
+export * from './app-config';
+export * from './logger-config';
+export * from './remote-service-config';
+export * from './tray-config';
+export * from './updater-config';
+export * from './window/main-window-config';
+export * from './window/setting-window-config';
+export type * from './types/app';
+export type * from './types/logger';
+export type * from './types/window';

package/dist/main/config/index.js

@@ -0,0 +1,33 @@
+import {
+  defineAppConfig,
+  defineRemoteServiceConfig,
+  defineUpdaterConfig
+} from "../../chunk-files/chunk-34OODP7M.js";
+import {
+  defineTrayConfig
+} from "../../chunk-files/chunk-Q7YMMN7J.js";
+import {
+  defineMainWindowConfig,
+  defineSettingWindowConfig
+} from "../../chunk-files/chunk-F7YTK2MY.js";
+import "../../chunk-files/chunk-3S5OTD47.js";
+import "../../chunk-files/chunk-DEODEAKM.js";
+import "../../chunk-files/chunk-6X74EPRM.js";
+import "../../chunk-files/chunk-VGDNICVG.js";
+import "../../chunk-files/chunk-KFK47PDH.js";
+import {
+  defineLoggerConfig
+} from "../../chunk-files/chunk-3KBZWBNP.js";
+import "../../chunk-files/chunk-RODB64YF.js";
+import "../../chunk-files/chunk-GN2FNR3Z.js";
+import "../../chunk-files/chunk-3RVKOFMP.js";
+import "../../chunk-files/chunk-FMQTZ3QV.js";
+export {
+  defineAppConfig,
+  defineLoggerConfig,
+  defineMainWindowConfig,
+  defineRemoteServiceConfig,
+  defineSettingWindowConfig,
+  defineTrayConfig,
+  defineUpdaterConfig
+};

package/dist/main/config/logger-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 定义日志配置
+ * @param {XoLogger.Config} config 日志配置
+ * @returns {XoLogger.Config}
+ */
+export declare const defineLoggerConfig: (config?: XoLogger.Config) => XoLogger.Config;

package/dist/main/config/remote-service-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 定义远程服务配置
+ * @param {XoRemoteService.Config} config 远程服务配置
+ * @returns {XoRemoteService.Config}
+ */
+export declare const defineRemoteServiceConfig: (config?: XoRemoteService.Config) => XoRemoteService.Config;

package/dist/main/config/tray-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 定义托盘配置
+ * @param {XoTray.Config} config 托盘配置
+ * @returns {XoTray.Config}
+ */
+export declare const defineTrayConfig: (config?: XoTray.Config) => XoTray.Config;

package/dist/main/config/types/app.d.ts

@@ -0,0 +1,38 @@
+import type {WindowMaterials} from '../../../shared/app/consts/window-material'
+
+declare global {
+
+    // App
+    namespace XoApp {
+
+        // 快捷窗口材质，可以快捷设置窗口样式
+        type WindowMaterial = typeof WindowMaterials[number]
+
+        // App 配置
+        interface Config {
+            // electron 应用构建选项
+            eletronAppConfig: XoVite.ElectronAppOptions,
+            // 是否单例模式
+            singleInstance?: boolean
+            // 是否在渲染进程使用上下文菜单
+            useContextMenuInRenderer?: boolean
+            // 是否接管链接跳转
+            takeOverLinkNavigation?: boolean
+            // 链接跳转白名单正则
+            linkNavigationWhiteList?: RegExp[]
+            // 快捷窗口材质（会强制设置 browserOptions 中的选项）
+            // - transparent 窗口透明无边框 {backgroundMaterial: 'none'， transparent: true, backgroundColor: '#00000000', frame: false, thickFrame: false}
+            // - none        不使用材质 {backgroundMaterial: 'none', transparent: false}
+            // - mica        Windows 11 云母材质（带系统色调的柔和背景） {transparent: false, backgroundColor: '#00000000'}
+            // - acrylic     Windows 10 亚克力材质（毛玻璃，有半透明、模糊、透出背后内容的效果） {transparent: false, backgroundColor: '#00000000'}
+            // - tabbed      窗口背景使用 tabbed 风格的系统材质 {transparent: false, backgroundColor: '#00000000'}
+            windowMaterial?: WindowMaterial
+            // 标题栏覆盖配置
+            titleBarOverlayConfig?: XoTheme.TitleBarOverlayConfig
+            // 托盘"检查更新"点击后跳转的设置路由（如版本更新页面），未配置时不跳转
+            updaterSettingsRoute?: XoWindow.RouteRedirectRequestWithoutWindow
+        }
+    }
+}
+
+export {}