@pubinfo/module-pinia-crypto

为 Pinia 持久化状态提供一层统一的加/解密能力。模块通过 pinia:persist:* 钩子在写入浏览器存储前后注入处理逻辑，既可以直接使用内置 AES 加密器，也支持自定义算法。

特性

• 🔐 开箱即用的 AES-CBC/ECB 加密器
• 🎯 按 store 维度 include/exclude，精确控制作用范围
• 🧱 基于 Pinia 持久化插件的同步钩子，零异步依赖
• 🛠️ 自定义 Cipher 接口，可自由替换为公司内部算法
• 🧪 完善的调试日志，便于排查存储数据

安装

pnpm add @pubinfo/module-pinia-crypto

快速上手

// 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 加密器：

const cipher = createPiniaAesCipher({
  secret: '32chars-long-secret-key----',
  iv: '16chars-long-iv',
  mode: 'cbc',
});

自定义 Cipher

PiniaCryptoCipher 的签名十分简单，只需要同步地返回字符串即可：

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