@pubinfo-nightly/module-pinia-crypto 2025.11.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PUBINFO 腾龙框架
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @pubinfo/module-pinia-crypto
+
+为 Pinia 持久化状态提供一层统一的加/解密能力。模块通过 `pinia:persist:*` 钩子在写入浏览器存储前后注入处理逻辑，既可以直接使用内置 AES 加密器，也支持自定义算法。
+
+## 特性
+
+- 🔐 **开箱即用的 AES-CBC/ECB 加密器**
+- 🎯 **按 store 维度 include/exclude，精确控制作用范围**
+- 🧱 **基于 Pinia 持久化插件的同步钩子，零异步依赖**
+- 🛠️ **自定义 Cipher 接口，可自由替换为公司内部算法**
+- 🧪 **完善的调试日志，便于排查存储数据**
+
+## 安装
+
+```bash
+pnpm add @pubinfo/module-pinia-crypto
+```
+
+## 快速上手
+
+```ts
+// src/modules/pinia-crypto.ts
+import { createPiniaAesCipher, piniaCrypto } from '@pubinfo/module-pinia-crypto';
+
+export function setupPiniaCrypto() {
+  return piniaCrypto({
+    cipher: createPiniaAesCipher({
+      secret: 'demo-secret-key',
+      iv: 'demo-secret-iv',
+      mode: 'cbc',
+    }),
+    include: ['user', /^settings/],
+    debug: import.meta.env.DEV,
+  });
+}
+
+// main.ts
+createPubinfo({
+  /* ... */
+  modules: [
+    piniaCrypto(/* options */),
+  ],
+});
+```
+
+> 提醒：只有声明了 `persist` 选项的 Pinia store 才会触发该模块的加解密流程。
+
+## API
+
+### `piniaCrypto(options?: PiniaCryptoOptions)`
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enable` | `boolean` | `true` | 关闭后不做任何处理 |
+| `include` | `StoreMatcher \| StoreMatcher[]` | `[]` | 需要加密的 store 名称/正则/函数（为空表示全部） |
+| `exclude` | `StoreMatcher \| StoreMatcher[]` | `[]` | 需要排除的 store |
+| `cipher` | `PiniaCryptoCipher` | - | 自定义加密器（若提供将覆盖 secret/iv 配置） |
+| `secret` | `string` | `'pubinfo-pinia-secret'` | 默认 AES 密钥，自动补齐/截断至 32 字节 |
+| `iv` | `string` | `'pubinfo-pinia-iv'` | CBC 模式下使用的 IV，自动补齐/截断至 16 字节 |
+| `mode` | `'cbc' \| 'ecb'` | `'cbc'` | 默认 Cipher 模式 |
+| `debug` | `boolean` | `false` | 控制台输出错误日志 |
+
+`StoreMatcher` 支持三种写法：
+
+```
+type StoreMatcher =
+  | string            // 完全匹配 storeId
+  | RegExp            // 正则匹配 storeId
+  | (payload) => boolean // 自定义判断逻辑
+```
+
+### `createPiniaAesCipher(options?: PiniaAesCipherOptions)`
+
+返回一个符合 `PiniaCryptoCipher` 接口的 AES 加密器：
+
+```ts
+const cipher = createPiniaAesCipher({
+  secret: '32chars-long-secret-key----',
+  iv: '16chars-long-iv',
+  mode: 'cbc',
+});
+```
+
+### 自定义 Cipher
+
+`PiniaCryptoCipher` 的签名十分简单，只需要同步地返回字符串即可：
+
+```ts
+import type { PiniaCryptoCipher } from '@pubinfo/module-pinia-crypto';
+
+const rot13Cipher: PiniaCryptoCipher = {
+  encrypt: ({ value }) => rot13(value),
+  decrypt: ({ value }) => rot13(value),
+};
+
+piniaCrypto({ cipher: rot13Cipher });
+```
+
+## 调试技巧
+
+1. 先为 store 开启 `persist`。
+2. 打开 DevTools → Application → Local Storage，找到 `storagePrefix + storeId` 的键值。
+3. 修改值后观察 Pinia DevTools，确认状态被自动解密。
+4. 如遇解析失败，开启 `debug` 获取详细日志。
+
+## License
+
+MIT

package/dist/cipher.d.ts

@@ -0,0 +1,2 @@
+import { PiniaAesCipherOptions, PiniaCryptoCipher } from './types';
+export declare function createPiniaAesCipher(options?: PiniaAesCipherOptions): PiniaCryptoCipher;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { ModuleOptions } from 'pubinfo-nightly';
+import { PiniaCryptoOptions } from './types';
+import 'uno.css';
+export declare function piniaCrypto(options?: PiniaCryptoOptions): ModuleOptions;
+export { createPiniaAesCipher } from './cipher';
+export type { PiniaAesCipherOptions, PiniaCryptoCipher, PiniaCryptoOptions, StoreMatcher } from './types';