# CipherStash 堆栈 - 加密使用“@cipherstash/stack”实现字段级加密的综合指南。每个值都通过 ZeroKMS（由 AWS KMS 支持）使用自己的唯一密钥进行加密。在数据离开应用程序之前，加密发生在客户端。 ## 何时使用此技能 * 向 TypeScript/Node.js 项目添加字段级加密 * 定义加密表模式 * 加密和解密单个值或整个模型 * 实现可搜索加密（相等、自由文本、范围、JSON 查询） * 批量加密/解密大型数据集 * 使用基于 JWT 的锁定上下文实现身份感知加密 * 使用密钥集设置多租户加密 * 从“@cipherstash/protect”迁移到“@cipherstash/stack” ## 安装 npm 安装@cipherstash/stack 该软件包包含一个本机 FFI 模块 (`@cipherstash/protect-ffi`)。您必须选择不将其捆绑在 Webpack、esbuild 或 Next.js (`serverExternalPackages`) 等工具中。 ## 配置 ### 环境变量在 `.env` 或您的托管平台中设置这些： CS_WORKSPACE_CRN=crn:ap-southeast-2.aws:您的工作空间 ID CS_CLIENT_ID=您的客户 ID CS_CLIENT_KEY=您的客户端密钥 CS_CLIENT_ACCESS_KEY=您的访问密钥在 [cipherstash.com/signup]() 上注册以生成凭据。 ### 编程配置 const 客户端 = 等待加密({ 模式：[用户]，配置：{ workspaceCrn: "crn:ap-southeast-2.aws:your-workspace-id", clientId: "您的客户 ID", clientKey：“您的客户端密钥”， accessKey: "您的访问密钥", keyset: { name: "my-keyset" }, // 可选：多租户隔离 }, }) 如果省略`config`，客户端会自动读取`CS_*`环境变量。 ### 日志记录默认情况下，日志记录在“错误”级别启用。使用“STASH_STACK_LOG”环境变量配置日志级别： STASH_STACK_LOG=错误#调试|信息 |错误（默认：错误）价值|记录了什么 ---|--- `错误` |仅错误（默认） `信息` |信息和错误 `调试` |调试、信息和错误当未设置“STASH_STACK_LOG”时，SDK 默认为“error”（仅限错误）。 SDK 从不记录明文数据。 ## 子路径导出导入路径|提供 ---|--- `@cipherstash/stack` | `Encryption` 函数、`Secrets` 类、`encryptedTable`、`encryptedColumn`、`encryptedField` （方便重新导出） `@cipherstash/stack/schema` | `加密表`、`加密列`、`加密字段`、模式类型 `@cipherstash/stack/identity` | `LockContext` 类和身份类型 `@cipherstash/stack/secrets` | `Secrets` 类和秘密类型 `@cipherstash/stack/毛毛雨` | Drizzle ORM 的“encryptedType”、“extractEncryptionSchema”、“createEncryptionOperators” `@cipherstash/stack/supabase` | Supabase 的“encryptedSupabase”包装器 `@cipherstash/stack/dynamodb` | DynamoDB 的“encryptedDynamoDB”帮助程序 `@cipherstash/stack/加密` | `EncryptionClient` 类，`Encryption` 函数 `@cipherstash/stack/errors` | `EncryptionErrorTypes`、`StackError`、错误子类型、`getErrorMessage` `@cipherstash/stack/client` |客户端安全导出：架构构建器、架构类型、“EncryptionClient”类型（无本机 FFI） `@cipherstash/stack/types` |所有 TypeScript 类型 ## 模式定义使用“encryptedTable”和“encryptedColumn”定义要加密的表和列：从“@cipherstash/stack/schema”导入{加密表，加密列} const 用户 = 加密表("用户", { 电子邮件：加密列（“电子邮件”） .equality() // 精确匹配查询 .freeTextSearch() // 全文/模糊搜索 .orderAndRange(), // 排序和范围查询年龄：加密列(“年龄”) .dataType("数字") .equality() .orderAndRange(), address: cryptoColumn("address"), // 仅加密，无搜索索引 }) const 文档 = 加密表("文档", { 元数据：加密列（“元数据”） .searchableJson(), // 加密的 JSONB 查询（JSONPath + 包含） }) ### 索引类型方法|目的|查询类型 ---|---|--- `.equality(tokenFilters?)` |精确匹配查找。接受可选的标记过滤器数组（例如，`[{ kind: 'downcase' }]`）以进行不区分大小写的匹配。 | 「平等」 `.freeTextSearch(opts?)` |全文/模糊搜索 | `'免费文本搜索'` `.orderAndRange()` |排序、比较、范围查询 | `'顺序和范围'` `.searchableJson()` |加密的 JSONB 路径和包含查询（自动将 `dataType` 设置为 `'json'`）| `'searchableJson'` `.dataType(cast)` |设置明文数据类型 |不适用 **支持的数据类型：** `'string'`（默认），`'text'`，`'number'`，`'boolean'`，`'date'`，`'bigint'`，`'json'` 方法是可链接的 - 在单个列上调用任意数量的方法。 ### 自由文本搜索选项加密列（“生物”）.freeTextSearch（{ tokenizer: { kind: "ngram", token_length: 3 }, // 或 { kind: "standard" } token_filters: [{ kind: "downcase" }], k：6，米：2048， include_original：真实， }) ### 类型推断从“@cipherstash/stack/schema”导入类型 { InferPlaintext, InferEncrypted } type UserPlaintext = InferPlaintext<用户类型> // { 电子邮件：字符串；年龄：字符串；地址：字符串} type UserEncrypted = InferEncrypted<用户类型> // { 电子邮件：已加密；年龄：加密；地址：加密} ## 客户端初始化从“@cipherstash/stack”导入{加密} const client = wait Encryption({ schemas: [用户, 文档] }) `Encryption()` 函数返回 `Promise` 并抛出错误（例如，错误的凭据、缺少配置、无效的密钥集 UUID）。至少需要一种架构。 // 错误处理尝试{ const client = wait Encryption({ schemas: [users] }) } 捕获（错误）{ console.error("初始化失败:", error.message) } ## 加密和解密单个值 // 加密 const 加密 = 等待 client.encrypt("hello@example.com", { 列：用户.电子邮件，表：用户， }) if (加密.失败) { console.error(加密.失败.消息) } 否则{ console.log(encrypted.data) // 加密的有效负载（不透明对象） } // 解密 const 解密 = 等待 client.decrypt(encrypted.data) if (!decrypted.failure) { console.log(decrypted.data) // "hello@example.com" } 所有明文值必须为非空。空处理由“encryptModel”和“decryptModel”在模型级别进行管理。 ## 模型操作加密或解密整个对象。仅对与您的模式匹配的字段进行加密；其他字段不变地通过。返回类型是 **schema-aware** ：与表模式匹配的字段被键入为“Encrypted”，而其他字段保留其原始类型。为了获得最佳结果，让 TypeScript 从参数推断类型参数，而不是提供显式的“”。类型用户 = { id: 字符串;电子邮件：字符串；创建于：日期 } 常量用户 = { id：“user_123”， email: "alice@example.com", // 在模式中定义 -> 加密 createAt: new Date(), // 不在模式中 -> 未更改 } // 加密模型 — 让 TypeScript 从模式推断返回类型 const encResult = 等待 client.encryptModel(用户, 用户) if (!encResult.failure) { // encResult.data.email 的类型为 Encrypted // encResult.data.id 输入为字符串 // encResult.data.createdAt 的类型为 Date } // 解密模型 const decResult = 等待 client.decryptModel(encResult.data) if (!decResult.failure) { console.log(decResult.data.email) // "alice@example.com" } `Decrypted` 类型将加密字段映射回其明文类型。传递显式类型参数（例如，`client.encryptModel(...)`）仍然可以实现向后兼容性——在这种情况下，返回类型降级为`User`。 ## 批量操作无论记录数量如何，所有批量方法都会对 ZeroKMS 进行一次调用，同时仍然为每个值使用唯一的键。 ### 批量加密/解密（原始值） const 明文 = [ { id: "u1", 明文: "alice@example.com" }, { id: "u2", 明文: "bob@example.com" }, { id: "u3", 明文: "charlie@example.com" }, ] const 加密 = 等待 client.bulkEncrypt(plaintexts, { 列：用户.电子邮件，表：用户， }) // 加密.data = [{ id: "u1", data: EncryptedPayload }, ...] const 解密 = 等待 client.bulkDecrypt(encrypted.data) // 每个项目的错误处理： for (decrypted.data 的 const 项) { if（项目中的“数据”）{ console.log(`${item.id}: ${item.data}`) } 否则{ console.error(`${item.id} 失败: ${item.error}`) } } ### 批量加密/解密模型 const userModels = [ { id: "1", 电子邮件: "alice@example.com" }, { id: "2", 电子邮件: "bob@example.com" }, ] const 加密 = 等待 client.bulkEncryptModels(userModels, users) const 解密 = 等待 client.bulkDecryptModels(encrypted.data) ## 可搜索加密加密查询项，以便您可以在 PostgreSQL 中搜索加密数据。 ### 单查询加密 // 相等查询 const eqQuery = 等待 client.encryptQuery("alice@example.com", { 列：用户.电子邮件，表：用户，查询类型：“相等”， }) // 自由文本搜索 const matchQuery = 等待 client.encryptQuery("alice", { 列：用户.电子邮件，表：用户，查询类型：“自由文本搜索”， }) // 顺序和范围 const rangeQuery = 等待 client.encryptQuery(25, { 列：用户.年龄，表：用户，查询类型：“orderAndRange”， }) // JSON路径查询(steVecSelector) const pathQuery = wait client.encryptQuery("$.user.email", { 列：文档.元数据，表：文档，查询类型：“steVecSelector”， }) // JSON 包含查询 (steVecTerm) const containsQuery = wait client.encryptQuery({ 角色: "admin" }, { 列：文档.元数据，表：文档，查询类型：“steVecTerm”， }) 如果省略“queryType”，则会从列的配置索引自动推断（优先级：unique > match > ore > ste_vec）。 ### 查询结果格式（`returnType`）默认情况下，“encryptQuery”返回一个“Encrypted”对象（原始 EQL JSON 负载）。使用 `returnType` 更改输出格式： `返回类型` |输出|使用案例 ---|---|--- `'eql'`（默认）| “加密”对象 |参数化查询，接受 JSON 的 ORM `'复合文字'` | `字符串` | Supabase `.eq()`，基于字符串的 API `'转义复合文字'` | `字符串` |嵌入另一个字符串或 JSON 值 // 获取与 Supabase 一起使用的复合文字字符串 const term = wait client.encryptQuery("alice@example.com", { 列：用户.电子邮件，表：用户，查询类型：“相等”， returnType: "复合文字", }) // term.data 是一个字符串批次中的每个术语都可以有自己的“returnType”。 ### 可搜索 JSON 对于使用“.searchableJson()”的列，查询类型是从明文自动推断的： // String -> JSONPath 选择器查询 const pathQuery = wait client.encryptQuery("$.user.email", { 列：文档.元数据，表：文档， }) // 对象/数组 -> 包含查询 const containsQuery = wait client.encryptQuery({ 角色: "admin" }, { 列：文档.元数据，表：文档， }) ### 批量查询加密在一次 ZeroKMS 调用中加密多个查询项：常量项 = [ { 值：“alice@example.com”，列：users.email，表：users，queryType：“equality”as const }， { 值：“bob”，列：users.email，表：users，queryType：“freeTextSearch”as const }， ] const 结果 = 等待 client.encryptQuery(terms) // 结果.data = [EncryptedPayload, EncryptedPayload] 数组中的所有值都必须非空。 ## 身份感知加密（锁定上下文）通过要求有效的 JWT 进行解密，将加密锁定到特定用户。从“@cipherstash/stack/identity”导入 { LockContext } // 1. 创建一个锁上下文（默认为“sub”声明） const lc = new LockContext() // 或者使用自定义声明： new LockContext({ context: { IdentityClaim: ["sub", "org_id"] } }) // 或者使用预取的 CTS 令牌： new LockContext({ ctsToken: { accessToken: "...", expiry: 123456 } }) // 2. 使用 JWT 识别用户 const recognizeResult = 等待 lc.identify(userJwt) if (identifyResult.failure) { 抛出新错误（identifyResult.failure.message） } const lockContext = 识别结果.data // 3. 使用锁上下文加密 const 加密 = 等待客户端 .encrypt("敏感数据", { 列: users.email, 表: users }) .withLockContext(lockContext) // 4. 使用相同的锁上下文进行解密 const 解密 = 等待客户端 .decrypt(加密的.数据) .withLockContext(lockContext) 锁定上下文适用于所有操作：“加密”、“解密”、“加密模型”、“解密模型”、“批量加密”、“批量解密”、“批量加密模型”、“批量解密模型”、“加密查询”。 ### CTS 令牌服务锁定上下文将 JWT 交换为 CTS（CipherStash 令牌服务）令牌。设置端点： CS_CTS_ENDPOINT=https://ap-southeast-2.aws.auth.viturhosted.net ## 多租户加密（密钥集）隔离每个租户的加密密钥： // 按名称 const 客户端 = 等待加密({ 模式：[用户]， config: { keyset: { name: "A 公司" } }, }) // 通过UUID const 客户端 = 等待加密({ 模式：[用户]，配置：{键集：{id：“123e4567-e89b-12d3-a456-426614174000”}}， }) 每个密钥集在租户之间提供完全的加密隔离。 ## 操作链所有操作都返回支持链接的thenable对象： const 结果 = 等待客户端 .加密（明文，{列：users.email，表：users}） .withLockContext(lockContext) // 可选：身份感知 .audit({ 元数据: { action: "create" } }) // 可选：审计跟踪 ## 错误处理所有异步方法都返回一个“Result”对象 - 一个与“data”（成功）或“failure”（错误）的可区分联合，但绝不会两者兼而有之。 const result = wait client.encrypt("hello", { 列: users.email, 表: users }) if (结果.失败) { console.error(结果.失败.类型, 结果.失败.消息) // 类型是以下之一： "ClientInitError" | “加密错误” | “解密错误” // | “锁定上下文错误”| “CtsToken错误” } 否则{ 控制台.日志(结果.数据) } ### 错误类型类型 |当 ---|--- `客户端初始化错误` |客户端初始化失败（凭据错误、缺少配置） `加密错误` |加密操作失败（具有可选的“code”字段） `解密错误` |解密操作失败 `LockContextError` |锁定上下文创建或使用失败 `CtsTokenError` |身份令牌交换失败 “StackError”是上述所有错误类型的可区分联合，支持详尽的“switch”处理。 `EncryptionErrorTypes` 为每个错误类型字符串提供运行时常量。使用 getErrorMessage(error:unknown): string 从任何抛出的值中安全地提取消息。从“@cipherstash/stack/errors”导入 { EncryptionErrorTypes, type StackError, getErrorMessage } 函数handleError（错误：StackError）{ 开关（错误类型）{ 案例 EncryptionErrorTypes.ClientInitError： console.error("初始化失败:", error.message) 打破案例 EncryptionErrorTypes.EncryptionError： console.error("加密失败：", error.message, error.code) 打破案例 EncryptionErrorTypes.DecryptionError： console.error("解密失败：", error.message) 打破案例 EncryptionErrorTypes.LockContextError： console.error("锁定上下文失败:", error.message) 打破案例 EncryptionErrorTypes.CtsTokenError： console.error("CTS 令牌失败：", error.message) 打破默认： // TypeScript 确保详尽性 const _exhaustive：从不=错误 } } // 从未知错误中安全提取错误消息尝试{ 等待 client.encrypt("data", { 列: users.email, 表: users }) } 捕获 (e) { 控制台错误（getErrorMessage（e）） } ### 验证规则 * 对于数值，NaN 和 Infinity 被拒绝 * `freeTextSearch` 索引仅支持字符串值 * 必须至少提供一个“encryptedTable”模式 * 密钥集 UUID 必须是有效格式 ## PostgreSQL 存储加密数据存储为 EQL（加密查询语言）JSON 有效负载。在 PostgreSQL 中安装 EQL 扩展：如果不存在则创建扩展 eql_v2；创建表用户（ id BIGINT 始终作为身份主键生成，电子邮件 eql_v2_加密）；如果不直接使用 EQL 扩展，则存储为 JSONB：创建表用户（ id 串行主键，电子邮件 jsonb NOT NULL ）； ## 从@cipherstash/protect 迁移 `@cipherstash/protect` | `@cipherstash/stack` |导入路径 ---|---|--- `保护（配置）` | `加密（配置）` | `@cipherstash/堆栈` `csTable（名称，列）` | `加密表（名称，列）` | `@cipherstash/stack/schema` `csColumn(名称)` | `加密列（名称）` | `@cipherstash/stack/schema` 来自“/identify”的“LockContext” |来自“/identity”的“LockContext” | `@cipherstash/stack/identity` 加密客户端上的所有方法签名保持不变。 “结果”模式保持不变。 ## 完整的 API 参考 ### EncryptionClient 方法方法|签名|退货 ---|---|--- `加密` | `（明文，{列，表}）` | `加密操作` `解密` | `（加密数据）` | `解密操作` `加密查询` | `（明文，{列，表，查询类型？，返回类型？}）` | `加密查询操作` `加密查询` | `（术语：只读 ScalarQueryTerm[]）` | `批量加密查询操作` `加密模型` | `（模型，表格）` | `EncryptModelOperation>` `解密模型` | `（加密模型）` | `DecryptModelOperation` — 解析为 `Decrypted` `批量加密` | `（明文，{列，表}）` | `批量加密操作` `批量解密` | `（加密有效负载）` | `批量解密操作` `bulkEncryptModels` | `（模型，表格）` | `BulkEncryptModelsOperation>` `bulkDecryptModels` | `（加密模型）` | `BulkDecryptModelsOperation` — 解析为 `Decrypted[]` 所有操作都是thenable（可等待）并支持`.withLockContext()`和`.audit()`链接。 ### 模式构建器加密表（表名：字符串，列：记录<字符串，EncryptedColumn | EncryptedField | 嵌套>） cryptoColumn(columnName: string) // 可链接: .equality(), .freeTextSearch(), .orderAndRange(), .searchableJson(), .dataType() cryptoField(valueName: string) // 对于嵌套加密字段（不可搜索），可链接：.dataType()

隐藏加密

包含技能