mqtt-crypto-client 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mqtt-crypto-client",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MQTT over WebSocket client with CryptoJS-compatible AES envelope encryption, heartbeat, message deduplication and request/response helpers.",
   "keywords": [
     "mqtt",
@@ -14,12 +14,14 @@
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./src/index.js",
+  "browser": "./dist/index.browser.js",
   "types": "./types/index.d.ts",
   "unpkg": "./dist/index.iife.js",
   "jsdelivr": "./dist/index.iife.js",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
+      "browser": "./dist/index.browser.js",
       "import": "./src/index.js",
       "require": "./dist/index.cjs"
     },
@@ -37,7 +39,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node scripts/build-cjs.mjs && node scripts/build-iife.mjs && node scripts/check-iife.mjs",
+    "build": "node scripts/build-cjs.mjs && node scripts/build-browser.mjs && node scripts/check-browser.mjs",
     "test": "node --test",
     "typecheck": "tsc -p tsconfig.json",
     "prepack": "npm run build",
@@ -49,6 +51,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "acorn": "^8.19.0",
+    "acorn-walk": "^8.3.5",
     "crypto-js": "^4.2.0",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0"

package/src/config-string.js

@@ -0,0 +1,117 @@
+/**
+ * MQTT 配置字符串（mqtthub 风格）的序列化 / 反序列化。
+ *
+ * 格式：`key=value&key=value`，每个 value 经 encodeURIComponent 编码。整串既可作为 URL
+ * 查询串（如 `?broker=...&topic=...&password=...`），也可原样粘贴进设置框，是跨系统的
+ * 便捷交换格式（不是持久化格式；持久化仍以对象/JSON 保存）。
+ *
+ * 已知 key：
+ *   - broker    (必填) MQTT broker URL，如 `wss://broker.emqx.io:8084/mqtt`
+ *   - topic     (必填) 订阅 / 发布的 topic
+ *   - password  对应本库的 `secret`（AES 口令）；为空表示不加密（encrypt=false）
+ *   - name      (可选) 可读标签，仅用于 UI，不参与连接
+ *
+ * 其它 key 原样保留为扩展字段（不参与连接，但可被 UI 使用）。
+ *
+ * 加密互通说明：本库 `secret` 的加密方案与 CryptoJS `AES.encrypt(payload, passphrase)`
+ * 完全一致（OpenSSL "Salted__" 格式 + EVP_BytesToKey，AES-256-CBC），因此同一 `password`
+ * 在 mqtthub 与本库之间可互解密——只要连接的是同一个 broker/topic 且口令相同。
+ */
+import { InvalidConfigError } from './errors.js';
+
+/** 已知 key：这些 key 在序列化/反序列化时有固定语义，不参与"扩展字段"透传逻辑的特殊处理 */
+const KNOWN_KEYS = new Set(['name', 'broker', 'topic', 'password']);
+
+/**
+ * 解析配置字符串，返回本库 options 子集（broker / topic / secret / encrypt + 扩展字段）。
+ * 与 serializeConfigString 在 broker / topic / secret(password) / name 范围内互逆。
+ *
+ * @param {string} str 配置字符串（`key=value&...`）
+ * @returns {{ broker: string, topic: string, secret: string, encrypt: boolean, [k: string]: any }}
+ */
+export function parseConfigString(str) {
+  if (typeof str !== 'string' || str.trim().length === 0) {
+    throw new InvalidConfigError('配置字符串为空');
+  }
+
+  /** @type {Record<string, string>} */
+  const raw = {};
+  for (const pair of str.trim().split('&')) {
+    if (pair.length === 0) continue;
+    const idx = pair.indexOf('=');
+    if (idx < 0) continue; // 容忍缺少 = 的片段
+    const k = pair.slice(0, idx).trim();
+    if (k.length === 0) continue;
+    const v = decodeURIComponent(pair.slice(idx + 1));
+    raw[k] = v;
+  }
+
+  const broker = raw.broker;
+  const topic = raw.topic;
+  if (!broker || !topic) {
+    throw new InvalidConfigError('配置字符串缺少必填字段 broker 或 topic');
+  }
+
+  const password = raw.password || '';
+  /** @type {{ broker: string, topic: string, secret: string, encrypt: boolean, [k: string]: any }} */
+  const result = {
+    broker,
+    topic,
+    // 库的 secret 对应字符串的 password
+    secret: password,
+    // 口令非空即视为加密；空口令 = 不加密
+    encrypt: password.length > 0,
+  };
+
+  // name 是可选可读标签，原样保留
+  if (raw.name !== undefined) result.name = raw.name;
+
+  // 透传扩展字段（不参与连接，但可被 UI 使用）
+  for (const k of Object.keys(raw)) {
+    if (KNOWN_KEYS.has(k)) continue;
+    result[k] = raw[k];
+  }
+
+  return result;
+}
+
+/**
+ * 将配置对象序列化为 mqtthub 风格配置字符串。
+ * secret 仅在 encrypt !== false 时映射为 password；encrypt=false 时 password 为空（不加密）。
+ *
+ * @param {{ broker: string, topic: string, secret?: string, encrypt?: boolean, name?: string, [k: string]: any }} opts
+ * @returns {string}
+ */
+export function serializeConfigString(opts) {
+  if (!opts || typeof opts !== 'object' || Array.isArray(opts)) {
+    throw new InvalidConfigError('serializeConfigString 需要配置对象');
+  }
+
+  /** @type {string[]} */
+  const entries = [];
+  /**
+   * @param {string} k
+   * @param {any} v
+   */
+  const push = (k, v) => {
+    if (v === undefined || v === null) return;
+    entries.push(`${k}=${encodeURIComponent(String(v))}`);
+  };
+
+  // name 在前，便于人工阅读
+  if (opts.name !== undefined) push('name', opts.name);
+  push('broker', opts.broker);
+  push('topic', opts.topic);
+
+  // 库的 secret 映射为字符串的 password；encrypt=false 时视为不加密（password 为空）
+  const password = opts.encrypt === false ? '' : (opts.secret ?? '');
+  push('password', password);
+
+  // 透传扩展字段（排除已显式映射的字段）
+  for (const k of Object.keys(opts)) {
+    if (['broker', 'topic', 'secret', 'encrypt', 'name'].includes(k)) continue;
+    push(k, opts[k]);
+  }
+
+  return entries.join('&');
+}

package/src/index.js

@@ -31,6 +31,8 @@ export {
   resolveOptions,
 } from './options.js';
 
+export { parseConfigString, serializeConfigString } from './config-string.js';
+
 export { DEFAULT_TOPIC, PRESET_BROKERS, buildTopic, validateTopic } from './topic.js';
 
 export {

package/src/options.js

@@ -5,6 +5,7 @@
 import { InvalidConfigError } from './errors.js';
 import { DEFAULT_CLIENT_ID_PREFIX, DEFAULT_USER, createClientId } from './envelope.js';
 import { DEFAULT_TOPIC, validateTopic } from './topic.js';
+import { parseConfigString } from './config-string.js';
 
 /** 支持的 broker 协议（库以 MQTT over WebSocket 为主，同时保留 TCP/TLS 能力） */
 const SUPPORTED_PROTOCOLS = new Set(['ws:', 'wss:', 'mqtt:', 'mqtts:', 'tcp:', 'tls:']);
@@ -81,8 +82,12 @@ function validateBroker(broker) {
  * @returns {Readonly<Record<string, any>>}
  */
 export function resolveOptions(input = {}) {
+  // 支持直接传入 mqtthub 风格配置字符串（key=value&...）
+  if (typeof input === 'string') {
+    input = parseConfigString(input);
+  }
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new InvalidConfigError('options 必须是对象');
+    throw new InvalidConfigError('options 必须是对象或配置字符串');
   }
 
   const options = { ...DEFAULT_OPTIONS, ...input };

package/types/index.d.ts

@@ -71,8 +71,20 @@ export interface ClientStatus {
   agentOnline: boolean;
 }
 
+export interface ParsedConfigString {
+  broker: string;
+  topic: string;
+  /** AES 口令（对应字符串的 password 字段） */
+  secret: string;
+  /** password 非空为 true，空为 false（不加密） */
+  encrypt: boolean;
+  /** 可选可读标签（对应字符串的 name 字段） */
+  name?: string;
+  [key: string]: any;
+}
+
 export declare class MqttCryptoClient extends EventEmitter {
-  constructor(options?: MqttOptions);
+  constructor(options?: MqttOptions | string);
 
   readonly options: Readonly<Required<Omit<MqttOptions, 'auth' | 'protocolVersion'>> & {
     auth: { username?: string; password?: string } | null;
@@ -119,10 +131,27 @@ export declare class MqttCryptoClient extends EventEmitter {
   on(event: string | symbol, listener: (...args: any[]) => void): this;
 }
 
-export declare function createClient(options?: MqttOptions): MqttCryptoClient;
+export declare function createClient(options?: MqttOptions | string): MqttCryptoClient;
 
-/** 默认值合并并校验；非法配置会抛出 InvalidConfigError */
-export declare function resolveOptions(input?: MqttOptions): Readonly<Record<string, any>>;
+/** 默认值合并并校验；非法配置会抛出 InvalidConfigError。支持直接传入 mqtthub 风格配置字符串 */
+export declare function resolveOptions(input?: MqttOptions | string): Readonly<Record<string, any>>;
+
+/**
+ * 解析 mqtthub 风格 MQTT 配置字符串（key=value&...，value 经 encodeURIComponent 编码）。
+ * 返回 broker/topic/secret/encrypt + 扩展字段。
+ */
+export declare function parseConfigString(str: string): ParsedConfigString;
+/**
+ * 将配置对象序列化为 mqtthub 风格配置字符串。secret 仅在 encrypt !== false 时映射为 password。
+ */
+export declare function serializeConfigString(opts: {
+  broker: string;
+  topic: string;
+  secret?: string;
+  encrypt?: boolean;
+  name?: string;
+  [key: string]: any;
+}): string;
 /** 生成 mqtt.connect 的 options（clientId、reconnectPeriod、connectTimeout、clean、auth 等） */
 export declare function buildMqttOptions(options: Record<string, any>): Record<string, any>;