# @cipherstash/stack 中文文档

规范地址：https://npmcn.com/package/%40cipherstash/stack/

版本：1\.2\.1
npm 元数据更新时间：2026-10-02T22:33:55.515Z
中文译文更新时间：2026-11-09T19:23:30.267Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cipherstash/stack
原文对照：https://npmcn.com/package/%40cipherstash/stack/?lang=original
项目主页：https://github.com/cipherstash/stack#readme
源码仓库：https://github.com/cipherstash/stack

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.9 MB，112 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2026-02-24T12:03:20.409Z
- 最新版本发布：2026-10-02T22:33:55.242Z
- 近 30 天下载量：1803（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

用于 TypeScript 和 JavaScript 的 CipherStash 堆栈

## 安装

```sh
npm install @cipherstash/stack
```

也可以使用：`pnpm add @cipherstash/stack`、`yarn add @cipherstash/stack`、`bun add @cipherstash/stack`

## README

[![CipherStash](https://cipherstash.com/brand/cipherstash-logo-dark.svg)](https://cipherstash.com/?utm_source=github&utm_medium=stack_readme)

# TypeScript 的加密存储

**可搜索,可应用级加密建设隐私-第一应用.**

[![npm version](https://img.shields.io/npm/v/@cipherstash/stack.svg?style=for-the-badge&labelColor=000000)](https://www.npmjs.com/package/@cipherstash/stack) [![npm downloads](https://img.shields.io/npm/dm/@cipherstash/stack.svg?style=for-the-badge&labelColor=000000)](https://www.npmjs.com/package/@cipherstash/stack) [![GitHub stars](https://img.shields.io/github/stars/cipherstash/stack?style=for-the-badge&labelColor=000000)](https://github.com/cipherstash/stack/stargazers) [![Docs](https://img.shields.io/badge/Docs-333333.svg?style=for-the-badge&logo=readthedocs&labelColor=333)](https://cipherstash.com/docs/stack?utm_source=github&utm_medium=stack_readme) [![Discord](https://img.shields.io/badge/Join%20the%20community-blueviolet.svg?style=for-the-badge&logo=Discord&labelColor=000000)](https://discord.gg/5qwXUFb6PB) [![License](https://img.shields.io/npm/l/@cipherstash/stack.svg?style=for-the-badge&labelColor=000000)](https://github.com/cipherstash/stack/blob/main/LICENSE.md)

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}如果加密的话 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你就能问了!

## 加密级别安全,没有痛苦

场级加密是保护数据的最强方法. 但如果DB功能或性能受损,你需要证明疼痛是合理的. 可搜索加密核 权衡:加密级安全无痛.

-   包括Supabase、RDS、Aurora、Prisma Postgres和Neon在内的任何Postgres的可搜索加密
-   与Supabase.js、Prisma Next、Drizzle或平地SQL合作
-   内置密钥管理——自动旋转,审计,最高快于AWS KMS
-   与Supabase Auth、办事员、Auth0和Okta合并

  

## 快速开始

### 使用向导

5到10分钟后开始 **自由开发者级** (单位:千美元)[注册](https://cipherstash.com/signup?utm_source=github&utm_medium=stack_readme)),包括代理人交接.

```bash
# Run this to start (or just ask Claude to)
npx stash init
```

### ORM/数据库专用指南

| 快开始 | 指南 |
| --- | --- |
| **苏巴基地** | [Supabase快速启动](https://cipherstash.com/docs/stack/cipherstash/encryption/supabase?utm_source=github&utm_medium=stack_readme) |
| **Prisma 下一个** | [Prisma 下一个快速启动 ~](https://cipherstash.com/docs/stack/cipherstash/encryption/prisma-next?utm_source=github&utm_medium=stack_readme) |
| **滴入外科手术** | [滴滴快起动 ~](https://cipherstash.com/docs/stack/cipherstash/encryption/drizzle?utm_source=github&utm_medium=stack_readme) |
| **原始 PostgreSQL (英语:`pg`(中文(简体) )** | [快速启动](https://cipherstash.com/docs/stack/cipherstash/encryption?utm_source=github&utm_medium=stack_readme) |
| **迪纳摩DB** | [迪纳摩DB快速启动 ~](https://cipherstash.com/docs/stack/cipherstash/encryption/dynamodb?utm_source=github&utm_medium=stack_readme) |

> 斯塔克号也运载了a `stash` 用于认证、计划和数据库设置的CLI。 见 [SDK 参考](https://cipherstash.com/docs/stack/reference?utm_source=github&utm_medium=stack_readme)。 。 。 .

## 堆栈里有什么

### QQ 可搜索加密

在 PostgreSQL 中, 加密单个字段, 并仍然运行针对它们的真实的查询

| 查询类型 | 业务 | 文档 |
| --- | --- | --- |
| **平等** | `=`, (中文(简体) ), `IN` | [平等问题查询](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption?utm_source=github&utm_medium=stack_readme#equality) |
| **自由文本搜索** | 模糊 `matches` | [文本搜索 •](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption?utm_source=github&utm_medium=stack_readme#free-text-search) |
| **范围排序( R)** | `<`, (中文(简体) ), `>`, (中文(简体) ), `BETWEEN`, (中文(简体) ), `ORDER BY`, (中文(简体) ), `MIN`编号 :`MAX` | [范围查询](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption?utm_source=github&utm_medium=stack_readme#range-and-ordering) |
| **加密的 JSON** | 封装( e)`@>`), JSONPath 选择器 | [JSON查询 ∗](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption?utm_source=github&utm_medium=stack_readme#json) |

与 [EQL v3 数据](https://github.com/cipherstash/encrypt-query-language),列类型 _实值_ 组合。 声明带有加密类型的列 来命名它的数据类型和它支持的操作,它准备查询——没有每栏 要维护客户端的搜索配置 :

```sql
CREATE TABLE users (
  id          serial PRIMARY KEY,
  username    text,                    -- plaintext — business as usual
  email       eql_v3_text_match,       -- encrypted · free-text search
  ssn         eql_v3_text_eq,          -- encrypted · equality
  salary      eql_v3_integer_ord,      -- encrypted · range + ORDER BY
  preferences eql_v3_json_search       -- encrypted · containment + selectors
);
```

加密类型存在于文本,整数,浮出水面,数字,日期,时间戳,布林斯和JSON,所以 您的图案文档本身 —— 加密数据仍可使用标准的 Postgres 索引索引 。 没有 特殊的索引引擎,没有SQL重写. ORM 透明取出类型: 声明列为 加密为 `schema.prisma` 或者你的Drizzle桌子 和Stack处理其余的。 仅生 `pg` 需求 客户端 [计划](https://cipherstash.com/docs/stack/cipherstash/encryption/schema?utm_source=github&utm_medium=stack_readme) - 以同类型名称申报:

```typescript
import { encryptedTable, types } from "@cipherstash/stack/v3";

const users = encryptedTable("users", {
  email: types.TextMatch("email"),       // ↔ eql_v3_text_match
  salary: types.IntegerOrd("salary"),    // ↔ eql_v3_integer_ord
});
```

→ [可搜索加密](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption?utm_source=github&utm_medium=stack_readme) • 妇女 [司马](https://cipherstash.com/docs/stack/cipherstash/encryption/schema?utm_source=github&utm_medium=stack_readme) • 妇女 [加密解密( D)](https://cipherstash.com/docs/stack/cipherstash/encryption/encrypt-decrypt?utm_source=github&utm_medium=stack_readme) • 妇女 [散装和模型操作](https://cipherstash.com/docs/stack/cipherstash/encryption/encrypt-decrypt?utm_source=github&utm_medium=stack_readme#model-operations)

### 认证

您如何认证到 ZeroKMS 取决于谁要钥匙:

-   **设备认证** ——基于浏览器的本地开发登录: `npx stash auth login` 打开您的 浏览器并保存证书到您的本地 CipherStash 配置文件 。 收回和壳里没有秘密.
-   **访问密钥认证** - 服务器、工人和CI的服务级别证书,通过 `CS_*` 环境变量.
-   **OIDC联合会** 联合你的身份提供商的JWT 所以每个关键请求都认证 _作为 注册用户_而不是你的应用。 支助提供者: **苏柏碱 Auth**, (中文(简体) ), **办事员**, (中文(简体) ), **奥克塔**,以及 **自动 0** (任何符合OIDC的供应商的作品).

```typescript
// Access key (default) — reads CS_* env vars, no config needed
const client = await Encryption({ schemas: [users] });

// OIDC federation — every ZeroKMS request authenticates as the end user
const client = await Encryption({
  schemas: [users],
  config: { authStrategy: OidcFederationStrategy.create(workspaceCrn, () => getUserJwt()) },
});
```

→ [认证](https://cipherstash.com/docs/stack/cipherstash/encryption/identity?utm_source=github&utm_medium=stack_readme)

### \* 内置密钥管理

密钥管理由下列设备组成: [零KMS (零KMS)](https://cipherstash.com/docs/stack/cipherstash/kms?utm_source=github&utm_medium=stack_readme) 没有AWS KMS可以监听 没有钥匙库可以运行, 没有轮回时间表 :

-   **每个值的独有密钥** ——每表或每个数据库没有一把钥匙.
-   **自动按键旋转** 为你处理,零故障时间.
-   **CipherStash永远看不到你的钥匙.** 键是 _在应用程序中生成_; 既不是简写 键或纯文本数据永远离开您的基础设施.
-   **速成规模** ——大宗密钥操作在一次呼叫中可处理多达一万个密钥,最高可14×更快 高于峰值时的 AWS KMS([基准](https://github.com/cipherstash/benches)) (中文(简体) ).
-   **每个解密都记录下来了** ——谁解密什么,何时解密的内置审计线索.

> **CipherStash从不看你的平话——或你的钥匙.** 数据在您的应用程序中被加密 每个值的密钥,并且密钥在您的应用程序中通过 [零KMS (零KMS)](https://cipherstash.com/docs/stack/cipherstash/kms?utm_source=github&utm_medium=stack_readme) - 所以一个数据库 漏洞只泄露密码. [见安全架构](https://cipherstash.com/docs/stack/reference/security-architecture?utm_source=github&utm_medium=stack_readme)

## 高级特性

### 身份锁定加密

在OIDC联合会的基础上,你可以将记录的加密密钥绑入终端用户的身份,所以只有 _那个_ 用户可以解密其数据 : `.withLockContext({ identityClaim })` 将数据密钥与索赔连接到 用户的JWT,由ZeroKMS强制加密.

```typescript
// Bind the data key to a claim — the same claim is required to decrypt
await client
  .encrypt("alice@example.com", { table: users, column: users.email })
  .withLockContext({ identityClaim: ["sub"] });
```

→ [身份锁定加密](https://cipherstash.com/docs/stack/cipherstash/encryption/identity?utm_source=github&utm_medium=stack_readme)

### 用于多重租赁和主权的密钥集

将您的密钥分区到 **键盘** ——单一工作空间内独立的关键等级. 各给 租户自有钥匙套(`config.keyset`密码租户隔离:每加密、解密和 查询被设定到一个密钥集, 因此取消客户对密钥集的访问使得租户的数据 无法读取, 直至补助金被恢复 —— 不重新存档您的应用 . [密钥集](https://cipherstash.com/docs/stack/cipherstash/kms?utm_source=github&utm_medium=stack_readme#keysets)

## 加密的字段 。 真正的询问。 你的工具.

这个 `email` 下面一栏以每行独有的密钥存储为密码文本——搜索仍然有效, 因为查询运行在密码上。 没有解密和扫描, 没有重写查询 .

**苏巴基地** – 相同的 Supabase.js 调用; 包装器内观您的方案, 在路上加密过滤器 并解密出场结果:

```typescript
const db = await encryptedSupabase(supabaseUrl, supabaseKey);

const { data } = await db.from("users")
  .select("id, name, email")
  .eq("email", "alice@acme.com"); // encrypted equality — runs on ciphertext
```

**Prisma 下一个** —— 宣布加密列为 `schema.prisma`,询问类型安全操作符 :

```prisma
model User {
  id    String @id
  email cipherstash.TextSearch()
}
```

```typescript
const rows = await db.orm.public.User
  .where((u) => u.email.eqlMatch("acme.com"))
  .all();
```

**滴水龙头** ——表格中的加密列类型,查询中的自动加密运算符:

```typescript
export const usersTable = pgTable("users", {
  id: integer("id").primaryKey(),
  email: types.TextSearch("email"), // → eql_v3_text_search — the type is the config
});

const results = await db.select().from(usersTable)
  .where(await ops.matches(usersTable.email, "acme.com"));
```

## 如何运作

![CipherStash architecture: encryption and decryption happen in your TypeScript app; only ciphertext (EQL JSON) is stored in your PostgreSQL database. ZeroKMS issues a unique key per value, derived in your app. Plaintext and keys never reach CipherStash, and every decryption is logged for audit.](https://raw.githubusercontent.com/cipherstash/stack/main/docs/images/architecture-light.svg)

加密发生在您的应用程序中 。 密码文本被存储为 [电子质量L](https://github.com/cipherstash/encrypt-query-language) 数据库中的有效载荷; 纯文本和密钥永远无法到达 CipherStash. 按价值计的密钥由ZeroKMS批量发行(共计百万) ),每个解密都记录在遵守记录中.

→ [安保结构](https://cipherstash.com/docs/stack/reference/security-architecture?utm_source=github&utm_medium=stack_readme) • 妇女 [零KMS (零KMS)](https://cipherstash.com/docs/stack/cipherstash/kms?utm_source=github&utm_medium=stack_readme)

## 业绩

被加密的查询保持快速——延迟从10k行到10M行平. 以 EQL v3 计算 [密码/管](https://github.com/cipherstash/benches)数字 :

| 运行 | 中位纬度(最多10M行) |
| --- | --- |
| 平等查询 | ~0.1毫秒(秒) |
| 区域查询 | ~0.5 ms (单位:千米) |
| JSON 实地平等 | ~0.1毫秒(秒) |

## 为什么SepherStash

-   **信任的数据访问** ——只有你的终端用户才能通过强制加密的方式访问他们的敏感数据.
-   **缩小爆炸半径** ——被突破的脆弱性只会暴露一个用户能够解密的东西,而不是你的整个表格.
-   **审计线索** ——每一次解密事件都会被记录,没有额外的工具可以栓上.
-   **更快地达到合规状态** ——超过SOC 2和ISO 27001的加密要求,符合FIPS要求 密码学和BYOK 对于需要的团队.

## 财务问题

**CepherStash能看到我的数据还是加密钥匙吗?**

不,从来没有。 加密和解密发生在您的应用程序中,密钥在您自己内部生成 环境。 Plaintext和密钥永远不会离开你的控制 也永远不会到达 CipherStash.

**其规模有多高?**

随着数据的增长,纬度保持不变——精确匹配的检查按~0.1 ms进行,范围查询按~0.5 ms进行 10k至 10M 行数[密码/管](https://github.com/cipherstash/benches)ZeroKMS处理批量键(每台最多10 000个) 所以关键管理不是瓶颈.

**移徙是什么样子?**

在您的 Postgres 数据库中安装 EQL(`npx stash init` 编辑 [快点开始](https://npmcn.com/package/%40cipherstash/stack/#readme-quick-starts) 控件 ,以此来声明您想要保护的列,并使用符合每个类型的加密类型(例如 `eql_v3_text_match` 可搜索文本或 `eql_v3_integer_ord` 区域查询),并加密数值 写之前的应用程序。 你可以逐行采用它——不重写大爆炸——和现有的 Postgres指数继续工作.

**我一定要改变我写问题的方式吗?**

勉强. 您保留您的查询构建器: Supabase.js 过滤器工作不变, Drizzle 和 Prisma Next 添加加密意识运算符( e)`ops.eq`, (中文(简体) ), `ops.matches`, (中文(简体) ), `eqlMatch`,...),取出正文并加密 给你的 没有 SQL 重写 .

**我需要运行一个KMS或钥匙库?**

没有 关键管理通过ZeroKMS构建. 如果您想要控制根键, 请带上自己的键 让你把它根植在自己的KMS.

**它与Supabase Auth 和 Row Level Security合作吗?**

对 它与Supabase Auth结合,并与RLS并列运行——它补充它们,不替换 他们.

**我已经使用行级安全——我需要这个吗?**

RLS和CepherStash解决了不同的问题,它们在一起最强. RLS 决定行 a 角色可以查询,但下面的数据是纯文本——所以绕过 RLS 的任何东西都会在 清除: 泄漏 `service_role` 键,一个配置错误的政策,一个 SQL 注入作为提升角色运行, 被盗备份,或数据库主机本身。 CipherStash 只存储密码文本并保存密钥 在数据库之外,所以这些相同的绕道 显示什么都无法读取。 保留 RLS 授权; 添加 密码系统 这样绕道就永远无法突破.

**有免费的等级吗?**

是的,一个免费的开发者级, 这样您就可以从第一天开始构建加密.

## 免费开始

加密比改造便宜得多 也就是解锁和企业 顾客。 开发者级别是 **免费**,这样您就可以从您的第一次迁移中添加加密:

```bash
npx stash init
```

签名是巫师的第一步,如果你还没有账户——或者 [创建您的自由账户](https://cipherstash.com/signup?utm_source=github&utm_medium=stack_readme) 首先在浏览器中,以及 `stash init` 我会捡起它.

## 安装

```bash
npm install @cipherstash/stack   # or: yarn / pnpm / bun add @cipherstash/stack
```

> \[大 **选择退出捆绑 `@cipherstash/stack`。 。 。 .** 它使用本地的Node.js特性(一个 Rust FFI 模块)和 本地语言 `require`。对于边缘和无服务器运行时间(Cloudflare Workers, Deno, Bun),使用方便捆绑器 `@cipherstash/stack/wasm-inline` 输入. [Bundling 指南 +](https://cipherstash.com/docs/stack/deploy/bundling?utm_source=github&utm_medium=stack_readme)

**所需经费:** 节点.js 22.

## 文档社区( C)

-   📚 [文档](https://cipherstash.com/docs/stack?utm_source=github&utm_medium=stack_readme) • 妇女 [快速启动](https://cipherstash.com/docs/stack/quickstart?utm_source=github&utm_medium=stack_readme) • 妇女 [SDK 参考](https://cipherstash.com/docs/stack/reference?utm_source=github&utm_medium=stack_readme)
-   🧩 [示例应用程序](https://github.com/cipherstash/stack/tree/main/languages/typescript/examples)
-   💬 [Discord 社区](https://discord.gg/5qwXUFb6PB)

## · 许可证

欢迎捐款——见 [捐款额](https://github.com/cipherstash/stack/blob/main/CONTRIBUTING.md)对我们的安全政策和责任 披露,见 [警卫](https://github.com/cipherstash/stack/blob/main/SECURITY.md)。 。 。 . [麻省理工学院执照](https://github.com/cipherstash/stack/blob/main/LICENSE.md)。 。 。 .

## 常见问题

### @cipherstash/stack 是什么？

用于 TypeScript 和 JavaScript 的 CipherStash 堆栈

### 如何安装 @cipherstash/stack？

在项目目录运行 npm install @cipherstash/stack，或使用 pnpm add / yarn add / bun add。

### @cipherstash/stack 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cipherstash/stack 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cipherstash/stack 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cipherstash/stack 可以商用吗？

@cipherstash/stack 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cipherstash/stack 的下载量有多少？

根据 npm 官方下载统计，@cipherstash/stack 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,803 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cipherstash/stack 还在维护吗？

最新版本 1\.2\.1 发布于 2026/10/03（1 个月前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。