asaihost-nodejs 0.0.1

package/dist/asaihost-nodejs.d.ts

@@ -0,0 +1,406 @@
+import * as ws from 'ws';
+
+/** HTTP/WS Userinfo 解密（us##lv##tk，依赖 AsCode + asaisn） */
+declare function deUserInfoWithAsai(userinfo: string[] | null | undefined, $asai: any): string[] | null;
+
+/** WebSocket Mock — api 单次响应 / listen 定时推送 */
+declare function wsMock($asai: any): {
+    getKeyByData: (reqdata: any, hostdir?: string) => string;
+    wsWorkApi: (workopt: any) => void;
+    wsWorkMock: (workopt: any) => void;
+    wsWorkListen: (workopt: any, reqkey: any) => void;
+    getMockDb: (workopt: any) => any;
+};
+
+declare const index_deUserInfoWithAsai: typeof deUserInfoWithAsai;
+declare const index_wsMock: typeof wsMock;
+declare namespace index {
+  export { index_deUserInfoWithAsai as deUserInfoWithAsai, index_wsMock as wsMock };
+}
+
+declare const _default$1: {
+    ServerApi: ($asai: any, opt?: any) => {
+        apiWork: (req: any, res: any, hostdir: string) => any;
+    };
+    ServerWs: ($asai: any, opt?: any) => {
+        wsWork: (msg: any, ws: any, hostdir: string, req: any) => void;
+        commandwork: ($asai: any) => {
+            commandwork: () => void;
+        };
+    };
+    ServerSys: ($asai: any, opt?: any) => {
+        sysWork: (req: any, res: any, hostdir: string) => void;
+    };
+    WsClient: ($asai: any, wsname: string) => {
+        clientwsInit: () => Promise<unknown>;
+        clientwsSend: (message: string) => void;
+        clientwsApi: (messageData: any) => Promise<unknown>;
+        clientwsWatch: (messageData: any, cb: any) => void;
+        clientwsWatchOff: (messageData: any) => void;
+    };
+};
+
+declare const _default: ($asai: any) => void;
+
+/** 启动前归一化 host 配置 */
+declare function normalizeHostConfig(cfg: Record<string, any>): Record<string, any>;
+/** 启动时合并 security 默认值（向后兼容：未配置时等同旧行为） */
+declare function normalizeSecurityConfig(cfg: Record<string, any>): void;
+declare function validateHostConfig(cfg: Record<string, any>): string[];
+/** IEC 62443-4-2 — 生产环境强制安全配置（开发环境不校验） */
+declare function validateProductionSecurity(cfg: Record<string, any>): string[];
+
+/**
+ * syscom 通信配置 — tcp / grpc / rs485 统一读取、归一化与重连参数
+ *
+ * 配置结构（推荐）:
+ *   hostconfig.syscom.{tcp|grpc|rs485}.default
+ * 兼容旧版顶层 tcp/grpc/rs485/serial485/1tcp 等键名。
+ */
+type TransportKind = 'tcp' | 'grpc' | 'rs485';
+interface ReconnectOptions {
+    enabled?: boolean;
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    factor?: number;
+}
+declare function getTransportBlock(cfg: any, kind: TransportKind): Record<string, any> | null;
+declare function getTransportDefault(cfg: any, kind: TransportKind): Record<string, any> | null;
+declare function hasTransportDefault(cfg: any, kind: TransportKind): boolean;
+/** 默认连接 ID（来自配置 default.id，否则各传输内置默认值） */
+declare function getDefaultConnId(cfg: any, kind: TransportKind): string;
+/** 是否在启动时自动 connect（default.autoConnect !== false 时为 true） */
+declare function shouldAutoConnect(def: Record<string, any> | null | undefined): boolean;
+/** 解析重连参数：default.reconnect > 传输默认值 > tm.maxtry */
+declare function resolveReconnectOptions(def: Record<string, any> | null | undefined, kind: TransportKind, cfg?: Record<string, any>): ReconnectOptions;
+
+interface AsaiSecrets {
+    password: string;
+    asaisn: string;
+    aesKeyBase64: string;
+    sessionSecret: string;
+    httpsKey?: string;
+    httpsCert?: string;
+    wssecToken?: string;
+    siemToken?: string;
+}
+interface SecretsLoadResult {
+    secrets: AsaiSecrets;
+    strippedFromJson: string[];
+    sources: string[];
+}
+/** 轻量 .env 解析（不引入 dotenv 依赖） */
+declare function loadDotEnvFile(envPath: string): Promise<Record<string, string>>;
+/**
+ * 从 asaihost.json 剥离敏感字段（禁止落盘/进仓库）。
+ * 返回被剥离的字段路径列表，供安全审计。
+ */
+declare function stripForbiddenSecretsFromHostConfig(cfg: Record<string, any>): string[];
+declare function loadAsaiSecrets(serverRoot: string): Promise<SecretsLoadResult>;
+/** 将已加载的密钥合并进运行时 hostconfig（仅内存，不写回 JSON） */
+declare function applySecretsToHostConfig(cfg: Record<string, any>, secrets: AsaiSecrets): void;
+declare function resolveHttpsCertFromPaths(serverRoot: string, cfg: Record<string, any>): Promise<void>;
+declare function validateAsaiSecrets(secrets: AsaiSecrets, opts?: {
+    isProduction?: boolean;
+}): string[];
+declare function isDevDefaultPassword(password: string): boolean;
+
+declare class WsRouteIndex {
+    private routes;
+    rebuild(keys: string[]): void;
+    matchTy(ty: string | undefined): string | undefined;
+    matchString(msg: string): string | undefined;
+}
+
+/**
+ * 统一 API / WS 路由注册 — 同步 $lib 与 hostserver*，避免双写遗漏
+ */
+
+type RouteFactory$1 = ($asai: any) => Record<string, unknown>;
+declare function syncApiRouteKeys($asai: any): void;
+declare function syncWsRouteKeys($asai: any): void;
+/** 注册 API：同时写入 $lib.api 与 hostserverapi（若已初始化） */
+declare function registerApi($asai: any, key: string, factory: RouteFactory$1): void;
+/** 注册 WS：同时写入 $lib.ws 与 hostserverws（若已初始化） */
+declare function registerWs($asai: any, key: string, factory: RouteFactory$1): void;
+/** 初始化 hostserverapi（work 层启动时调用） */
+declare function initHostserverApi($asai: any, extra?: Record<string, RouteFactory$1>): void;
+/** 初始化 hostserverws（work 层启动时调用） */
+declare function initHostserverWs($asai: any, extra?: Record<string, RouteFactory$1>): any;
+
+interface TransportBridgeOptions {
+    $asai: any;
+    manager: any;
+    managerKey: string;
+    serversKey: string;
+    transport: TransportKind;
+    buildDefaultConfig: (def: Record<string, any>) => Record<string, any>;
+    apiRoute: string;
+    apiHandler: any;
+    wsRoute: string;
+    wsHandler: any;
+}
+/** 初始化传输管理器：挂 $asai、可选默认连接、注册 API/WS 路由 */
+declare function initTransportBridge(opts: TransportBridgeOptions): any;
+/** 首次 API/WS 调用时再建立默认连接（autoConnect: false 时） */
+declare function ensureDefaultConnection($asai: any, transport: TransportKind): string | null;
+/** 标准 DATA 事件：JSON 解析 + watch 匹配 / WS 广播 */
+declare function createTransportDataHandler($asai: any, manager: any): (event: any) => void;
+/** 连接状态日志（ERROR 由各 manager 内部输出，避免重复） */
+declare function wireTransportConnectionLogs(manager: any, events: {
+    CONNECTED: string;
+    DISCONNECTED: string;
+    ERROR?: string;
+}, logPrefix: string): void;
+
+type RouteFactory = ($asai: AsaiRuntime) => Record<string, unknown>;
+/** IEC 62443-4-2 安全策略（默认全关，不影响现有行为） */
+interface SecurityConfig {
+    /** 1=强制 HTTP Userinfo 鉴权；0=关闭（默认） */
+    requireAuth?: number;
+    /** 1=启用 Content-Security-Policy */
+    csp?: number;
+    /** 自定义 CSP 策略字符串 */
+    cspPolicy?: string;
+    /** 1=记录安全审计事件（默认开启） */
+    auditLog?: number;
+    /** 鉴权白名单路径（支持 * 后缀前缀匹配） */
+    authSkipPaths?: string[];
+    /** 最低用户等级（requireAuth=1 时生效） */
+    minUserLevel?: number;
+    /** 0=禁止开放注册（生产推荐） */
+    allowRegister?: number;
+    lockoutMaxFails?: number;
+    lockoutMinutes?: number;
+    sessionTtlHours?: number;
+    passwordMinLength?: number;
+    /** CR 1.12 登录前系统使用通知 */
+    banner?: {
+        enabled?: number;
+        text?: string;
+    };
+    /** CR 1.7 口令强度策略 */
+    passwordPolicy?: {
+        minLength?: number;
+        requireUpper?: number;
+        requireLower?: number;
+        requireDigit?: number;
+        requireSpecial?: number;
+        maxAgeDays?: number;
+        historyCount?: number;
+    };
+    /** CR 2.5 会话空闲锁定（分钟，0=关闭） */
+    sessionIdleMinutes?: number;
+    /** CR 2.1 SL-2 角色定义 */
+    roles?: Array<{
+        name: string;
+        minLv: number;
+        permissions?: string[];
+    }>;
+    /** CR 3.1 SL-2 生产强制 WSS */
+    forceWss?: number;
+    quota?: {
+        enabled?: number;
+        maxApiConcurrent?: number;
+        maxApiPerIp?: number;
+        maxApiPerIpPerMin?: number;
+        maxWsPerIp?: number;
+        maxLoginSessions?: number;
+        maxSessionsPerUser?: number;
+        onUserSessionOverflow?: string;
+    };
+}
+interface HostConfig {
+    website?: {
+        title?: string;
+        ver?: string;
+    };
+    password?: string;
+    security?: SecurityConfig;
+    ip?: string;
+    index?: string;
+    oncors?: number;
+    asaiport?: number[];
+    guardtm?: ReturnType<typeof setTimeout> | null;
+    hosts?: Record<string, HostSiteConfig>;
+    proxyhosts?: Record<string, ProxySiteConfig>;
+    logger?: LoggerConfig;
+    mimetypes?: Record<string, string>;
+    aes?: {
+        lv?: number;
+        keybase64?: string;
+        aad?: string;
+    };
+    path?: {
+        mock?: string;
+        ip?: string;
+    };
+    tm?: {
+        c?: number;
+        d?: number;
+        maxtry?: number;
+    };
+    pkg?: {
+        type?: number;
+    };
+    [key: string]: unknown;
+}
+interface HostSiteConfig {
+    close?: number;
+    port?: number;
+    ws?: number;
+    ckhttp?: number;
+    ckws?: number;
+    maxhttp?: number;
+    maxws?: number;
+    maxonline?: number;
+    oncors?: number;
+    wstype?: string;
+    httptype?: string;
+    hostdirs?: string[];
+    weburls?: {
+        rewrite?: boolean;
+        webdir?: string;
+        keys?: string[];
+    };
+    mimetypes?: Record<string, string>;
+    cors?: string[];
+    [key: string]: unknown;
+}
+interface ProxySiteConfig {
+    url?: string;
+    port?: number;
+    proxyport?: number;
+    httptype?: string;
+    proxyhttptype?: string;
+    [key: string]: unknown;
+}
+interface LoggerConfig {
+    lv?: {
+        view?: number;
+        record?: number;
+    };
+    path?: {
+        maxsize?: number;
+        client?: string;
+        server?: string;
+    };
+    /** 采样率 0~1，如 { "REQ_OTHER": 0.05 } */
+    sample?: Record<string, number>;
+    /** 不写日志的请求路径（精确匹配；以 * 结尾为前缀匹配） */
+    skip?: string[];
+    /** IEC 62443-4-2 干预日志（CEF 格式，留存≥5年） */
+    intervention?: {
+        path?: string;
+        retentionYears?: number;
+        /** 演示/自动化测试触发的干预动作专用存储目录，与生产留存数据完全隔离，不计入合规审计留存 */
+        testPath?: string;
+    };
+}
+type WorkHandler = (req: unknown, res: unknown, hostdir: string) => void;
+type WsWorkHandler = (msg: unknown, ws: unknown, hostdir: string, req: unknown) => void;
+interface AsaiHostOptions {
+    sysWork: WorkHandler;
+    apiWork: WorkHandler;
+    wsWork: WsWorkHandler;
+    jsonpWork: WorkHandler;
+}
+/** 运行时主对象（与 app.ts 中 $asai 结构一致） */
+interface AsaiRuntime {
+    $lib: Record<string, unknown>;
+    hostconfig: HostConfig;
+    asaizip?: unknown;
+    dataserver?: unknown;
+    asaihost?: Record<string, unknown>;
+    asaimock?: Record<string, unknown>;
+    connectionshttp: Record<string, Set<unknown>>;
+    connectionsws: Record<string, Record<string, unknown>>;
+    taskshttp: Record<string, unknown>;
+    tasksws: Record<string, unknown>;
+    servershttp: Record<string, unknown>;
+    serversws: Record<string, unknown>;
+    hostserverapi?: Record<string, RouteFactory>;
+    hostserverapis?: string[];
+    hostserverws?: Record<string, RouteFactory>;
+    hostserverwss?: string[];
+    hostserversys?: Record<string, RouteFactory>;
+    hostserversyss?: string[];
+    wsRouteIndex?: WsRouteIndex;
+    registerApi?: (key: string, factory: RouteFactory) => void;
+    registerWs?: (key: string, factory: RouteFactory) => void;
+    setAppend?: (src: string, logstr: string) => Promise<void>;
+    getHost?: (hostdir: string) => HostSiteConfig;
+    getHostIP?: (ip?: string | null) => string;
+    startHTTPServer?: (hostdir: string) => unknown;
+    $log?: (...args: unknown[]) => void | Promise<void>;
+    command?: Record<string, unknown>;
+    tmpdata: Record<string, unknown>;
+    tm: number;
+    [key: string]: unknown;
+}
+/** npm 包标识（与 package.json name 一致） */
+declare const PLUGIN_NAME: "asaihost-nodejs";
+/** `fn($asai, opt)` 返回值：启动函数 + ws 模块引用 */
+interface HostBootResult {
+    StartAsaiHost: () => void;
+    asaiWs: typeof ws;
+}
+/** 宿主插件对外 API 形状（具体方法签名见默认导出推断类型 AsaiNodejsHostPlugin） */
+interface AsaiNodejsHostPlugin {
+    readonly name: typeof PLUGIN_NAME;
+    fn: (runtime: AsaiRuntime, options: AsaiHostOptions) => HostBootResult;
+    sysserver: (runtime: AsaiRuntime) => void;
+    AsaiCommon: Record<string, unknown>;
+    AsaiUtils: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+declare function secureCompare(a: unknown, b: unknown): boolean;
+
+/**
+ * 路径安全 — 禁止目录穿越，仅允许落在白名单根目录内（OWASP Path Traversal）
+ */
+
+declare function resolvePathUnderRoots(requestedPath: string, allowedRoots: string[]): string;
+/** 从 hostconfig 推导允许读写的根目录 */
+declare function getHostAllowedRoots(hostconfig: any): string[];
+
+/**
+ * IEC 62443-4-2 CR 6.2 — 安全审计事件记录
+ * 与 GDPR 行为日志分离，专用于鉴权失败、访问拒绝等安全事件。
+ */
+type SecurityEventType = 'AUTH_FAIL' | 'AUTH_MISSING' | 'ACCESS_DENIED' | 'INPUT_REJECTED' | 'RATE_LIMIT' | 'CONFIG_WARN';
+interface SecurityAuditEvent {
+    type: SecurityEventType;
+    path?: string;
+    method?: string;
+    user?: string;
+    level?: string | number;
+    detail?: string;
+    ip?: string;
+}
+declare function logSecurityEvent($asai: any, event: SecurityAuditEvent): void;
+
+declare function sanitizeString(value: unknown, maxLen?: number): string;
+
+interface AuthCheckResult {
+    ok: boolean;
+    code?: number;
+    message?: string;
+}
+/** 校验 Userinfo 头（us##lv##tk），仅在 requireAuth=1 时由路由层调用 */
+declare function validateHttpAuth(req: any, $asai: any, pathname: string): AuthCheckResult;
+
+/**
+ * 统一数据存储注册表 — file / sqlite / mysql 自由切换，全库数据读写经此入口
+ */
+
+type StoreDomain = 'user' | 'log' | (string & {});
+
+declare const initAsaiHost: AsaiNodejsHostPlugin;
+
+/** 构建时注入的版本号（与 package.json version 同步） */
+declare const PLUGIN_VERSION: string;
+
+export { _default$1 as AsaiCommon, type AsaiHostOptions, type AsaiNodejsHostPlugin, type AsaiRuntime, type AsaiSecrets, index as AsaiUtils, type AuthCheckResult, type HostBootResult, type HostConfig, type HostSiteConfig, type LoggerConfig, PLUGIN_NAME, PLUGIN_VERSION, type ProxySiteConfig, type ReconnectOptions, type RouteFactory, type SecurityAuditEvent, type SecurityConfig, type SecurityEventType, type StoreDomain, type TransportKind, type WorkHandler, type WsWorkHandler, applySecretsToHostConfig, createTransportDataHandler, initAsaiHost as default, ensureDefaultConnection, getDefaultConnId, getHostAllowedRoots, getTransportBlock, getTransportDefault, hasTransportDefault, initAsaiHost, initHostserverApi, initHostserverWs, initTransportBridge, isDevDefaultPassword, loadAsaiSecrets, loadDotEnvFile, logSecurityEvent, normalizeHostConfig, normalizeSecurityConfig, registerApi, registerWs, resolveHttpsCertFromPaths, resolvePathUnderRoots, resolveReconnectOptions, sanitizeString, secureCompare, shouldAutoConnect, stripForbiddenSecretsFromHostConfig, syncApiRouteKeys, syncWsRouteKeys, _default as sysserver, validateAsaiSecrets, validateHostConfig, validateHttpAuth, validateProductionSecurity, wireTransportConnectionLogs };