@composy/crypto-vue

@composy/crypto-vue

@composy/crypto-vue 是 @composy/crypto-core 的 Vue 3 适配层，提供 composables、原生 Vue plugin，以及适配 @composy/engine-core 的 Vue engine plugin。

✨ 核心能力

• 12 个组合式函数:useCrypto、useEncryption、useHash、useKeyManager、useSignature、useToken 等,自带响应式 loading/error 状态
• 原生 Vue 插件:一次 app.use() 注册 $crypto 全局属性、provide 注入与 v-mask / v-hash 指令
• Engine 插件:createCryptoEnginePlugin 与 @composy/engine-core 生命周期集成,复用 core 的 state/container 注册
• 安全存储注入:plugin 提供 storage 时自动注入,也可独立传入 SecureStorageOptions
• 零算法复制:全部加解密能力来自 core,适配层只做响应式桥接

📦 安装

pnpm add @composy/crypto-vue

Peer 依赖:vue ^3.5.32 与 @composy/crypto-core ^0.0.1(后者已随依赖自动安装)。

🚀 快速开始

在组件中使用组合式函数:

<script setup lang="ts">
import { useEncryption, useHash } from '@composy/crypto-vue'
import { ref } from 'vue'

const { encryptAES, decryptAES, loading, error } = useEncryption()
const { sha256 } = useHash()
const cipher = ref('')

async function run() {
  // AES 加密成功返回密文字符串，失败返回 null 并写入 error
  cipher.value = (await encryptAES('hello', 'secret-key')) ?? ''
  const decrypted = await decryptAES(cipher.value, 'secret-key')
  console.info('decrypted:', decrypted, 'sha256:', sha256('hello'))
}
</script>

<template>
  <button type="button" :disabled="loading" @click="run">加密并解密</button>
  <output>{{ cipher }}</output>
  <p v-if="error">
    {{ error }}
  </p>
</template>

适配层维护约定

• 所有加密、解密、哈希、Token、存储、Worker 和性能逻辑都来自 @composy/crypto-core。
• composable 只负责 Vue 响应式状态、错误状态、loading 状态和生命周期清理。
• plugin 只负责 provide/inject、globalProperties、指令注册和 engine 生命周期桥接。
• 新增 Vue 能力时，先确认 core 是否已有公共 API；没有公共 API 时先补 core，再做 Vue 封装。
• 类型增强文件放在 src/types，用于 Vue 全局属性声明和对外类型转发，不参与运行时代码。
• 构建使用 @composy/builder 内置的 rolldown，并在构建后归一化、检查 dist、es、esm、lib 与 exports。
• 验证命令：pnpm run lint:check、pnpm run type-check、pnpm run test:run、pnpm run build、pnpm run check:outputs、pnpm run check:consumer。

@composy/crypto-vue 是 @composy/crypto-core 的 Vue 3 适配层，提供 composables、原生 Vue plugin，以及适配 @composy/engine-core 的 Vue engine plugin。

支持两种接入方式

1. 原生 Vue Plugin

import { createCryptoPlugin } from '@composy/crypto-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.use(
  createCryptoPlugin({
    storage: { key: 'app-secret', prefix: 'crypto_' },
  })
)
app.mount('#app')

安装后会提供：

• app.config.globalProperties.$crypto
• provide(CRYPTO_API_KEY, api)
• provide('crypto', api)
• provide('crypto:storage', storage)（仅在配置 storage 时）
• v-mask
• v-hash

卸载 Vue 应用时，插件会自动恢复原有的 $crypto 全局属性；外部传入的 manager/storage 由调用方拥有，插件不会销毁。

2. @composy/engine-core Plugin

import { createCryptoEnginePlugin } from '@composy/crypto-vue'

const enginePlugin = createCryptoEnginePlugin({
  storage: { key: 'engine-secret', prefix: 'crypto_' },
})

await engine.use(enginePlugin)

这个入口会同时：

• 复用 @composy/crypto-core/engine 的 state / container 注册
• 在 Vue app 创建后自动安装同一份 crypto API

Composables

• useCrypto
• useEncryption
• useHash
• useKeyManager
• useSignature
• useWorker
• usePasswordStrength
• useEncoding
• useSecureStorage
• useDataMasking
• useChecksum
• useToken

useSecureStorage() 支持两种模式：

• plugin 已提供 storage 时，直接使用注入实例
• 未安装 plugin 时，显式传入 SecureStorageOptions

目录约定

src/
  composables/  Vue 组合式 API
  constants/    injection key
  directives/   v-mask / v-hash
  plugins/      native plugin 与 engine plugin
  runtime/      公共安装与注入逻辑
  types/        对外类型转发

命名约定

• createCryptoPlugin
  • 原生 Vue plugin 的规范入口
• createCryptoVuePlugin
  • 兼容别名，行为等同于 createCryptoPlugin
• createCryptoEnginePlugin
  • @composy/engine-core 场景入口

🔨 构建产物与验证

构建使用 @composy/builder 内置的 rolldown,生成 dist(UMD)、es(ESM)、esm、lib(CJS)四类产物,并在构建后归一化声明文件、校验 exports 与真实产物一一对应。

pnpm run type-check    # 类型检查
pnpm run lint:check    # 代码规范
pnpm run test:run      # 单元测试
pnpm run build         # 构建 + 产物检查
pnpm run check:consumer # 真实 tarball consumer：Vue plugin、Core 联动和 TypeScript 类型

🔗 相关链接

• @composy/crypto-core —— 框架无关的核心实现层
• crypto 子模块总览 —— 家族结构、聚合构建与测试说明