# @sealzone/sdk 中文文档

规范地址：https://npmcn.com/package/%40sealzone/sdk/

版本：0\.2\.8
npm 元数据更新时间：2026-11-02T09:13:58.302Z
中文译文更新时间：2026-11-02T10:28:51.485Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：44.2 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-29T01:11:58.558Z
- 最新版本发布：2026-11-02T09:13:57.878Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

封印：使用秘密而不保留秘密。

## 安装

```sh
npm install @sealzone/sdk
```

也可以使用：`pnpm add @sealzone/sdk`、`yarn add @sealzone/sdk`、`bun add @sealzone/sdk`

## README

# @sealzone/sdk: Node.js的Seal sdk

Seal允许应用程序使用它们从未持有的秘密，因为经过认证的enclave会注入每个秘密 进入应用程序的上游流量。

## 安装

```sh
npm install @sealzone/sdk
```

## 例子

```js
import { Client } from "@sealzone/sdk";
import OpenAI from "openai";

const seal = await Client.fromEnv();

// Seal the secret. The destination and the apps are options.
const blob = await seal.seal(process.env.OPENAI_API_KEY, { to: "https://api.openai.com/v1", apps: ["checkout"], header: "x-api-key" });

// Use it. The app gets a stand-in key, and the enclave injects the real one.
const s = await seal.session(blob, { kind: "http" });
try {
  const openai = new OpenAI({ baseURL: s.url, apiKey: s.key });
} finally {
  await s.close(); // ends the session everywhere
}
```

任何人都可以为命名的应用程序密封一个秘密。然后，其中一个应用程序会启动一个会话 封闭的一团，得到一个替身。飞地将真正的秘密注入到通往 上游。

Python中相同的流程是 `seal.seal(secret, to=..., apps=[...])` 和 `seal.session(blob)`. 在Rust中是这样 `seal.seal(secret, to, apps).header(..).await?`． 每个SDK都使用相同的名称， 就每种语言而言。

## 配置

`Client.fromEnv()` 从环境构建客户端：

-   `SEAL_ENDPOINT`，租户的飞地副本，逗号分隔
-   `SEAL_TENANT`,因为 `<tenant>@<root id>` （控制台的Connect页面会显示它）。密封 需要根id；课程也适用于 `<tenant>` 单独，因为一个团命名它的根
-   它找到的第一个工作负载标识： `SEAL_APP_KEY`， Azure管理的身份 `SEAL_AZURE_AUDIENCE`Kubernetes投影令牌、GCP或GitHub Actions

`Client.connect({ endpoints, tenant, rootId, identity, trust })` 设置它们中的任何一个，然后 休息还是来自环境。

每个客户端在发送任何内容之前都会验证enclave。默认情况下，它使用release 相信包裹船。要用另一个，pass `trust: "trust.json"`，取路径或 将JSON作为字符串或缓冲区。

任何人都可以封印。飞地根据租户的授权决定是否可以开始这项工作 会话。每个操作返回一个Promise。

## 会话

`client.session(blob)` 解析为 `HttpSession` （`url`， `key`)或 `DatabaseSession` （`dsn`， `protocol`)，无论这个斑点是什么。 `kind: "http"` 或者 `kind: "database"` 要一个 对结果进行分类并键入。如果blob是另一种类型，则调用失败 `BadRequest` 在发送任何东西之前。每节课都有 `info`， `receipts()`， `extend()` 和 `close()`. 会话也在离开时结束 `await using` block （Node 24+, TypeScript 5.2+）。

```js
await using db = await seal.session(dbBlob, { kind: "database" });
const conn = new pg.Client({ connectionString: db.dsn });
```

-   **隧道。** `url` 和 `dsn` 指向一个本地代理 `127.0.0.1` SDK运行到的 飞地。 `key`而深空网络的密码，在此之外毫无价值 进程的隧道。在会话的生命周期内，它们都不会改变。SDK扩展了 在每次到期前使用新的身份证明。 `extend()` 现在就做。
-   **`close()`** 结束服务器上的会话，从那时起，每个副本都拒绝它的会话 令牌。如果 `close()` 拒绝，结束可能没有到达每一个副本，所以再次调用它。 在没有关闭的情况下进行垃圾收集的会话在后台结束。

会话选项:

-   `minTier` 拒绝较弱的会话。
-   `reloadWith` 当blob返回时再次返回blob `Expired`.
-   `onReseal` 接收在租户当前密钥下重新密封的密钥。它的误差变成 过程的警告。
-   `endpointReporter` 将请求的32字节挑战作为Buffer调用。它返回 这个 `EndpointReport` 在开始和每一个延伸时发送，形成 `{ artifact: { name, sha256 }, evidence: [{ provider, bytes }] }`，以及任何签名的证据 报道挑战。通过 `new HostAgentReporter()` 反而要报什么封主 代理人说这个过程。

默认情况下，会话报告正在运行的可执行文件的哈希值。对于Node，它是 `node` 二进制，所以租户检查工件的应用程序应该报告自己的包或映像摘要。 回调可以是异步的，并且在JavaScript线程上运行。它们从不让Node运行 他们自己。

## 身份，收据，信号

```js
import { AppKeyIdentity, Client, receipts } from "@sealzone/sdk";

const client = await Client.connect({ endpoints: ["https://10.0.1.4:8443"], tenant: "acme",
                                      identity: new AppKeyIdentity(appKey) });

const { blob, receipt } = await client.seal(secret, { to, apps: ["checkout"], withReceipt: true });
await receipts.append("receipts.jsonl", [receipt, ...(await s.receipts())]); // for `seal telemetry --receipts`

await client.signal("edr-alert", "high");
```

恒等式是 `AppKeyIdentity(key)`， `AzureManagedIdentity(audience, { clientId })`， `KubernetesIdentity(path?)`， `GcpIdentity(tenant)`， `GitHubActionsIdentity(tenant)`, `await AwsIdentity.fromEnv()` 在具有AWS支持的构建中。

## 错误

每个错误都是 `SealError` 与 `code` 和 `retryable`. `code` 是一个 `ErrorCode` 这样的价值 作为 `"not_allowed"`． 每个错误都会以其代码命名的子类抛出：

`Expired`， `NotAllowed`， `TierTooLow`， `IntegrityFailed`， `Unavailable`， `PolicyDenied`， `BudgetExceeded`， `SessionExpired`， `SessionEnded`， `VerificationFailed`， `BadRequest`， `Internal`， `ResealRequired`.

`VerificationFailed` 意味着飞地无法被核实。SDK不会重试 默默的。类型错误的实参抛出a `TypeError`.

## 构建和测试

该包是Rust SDK上的一个api-rs插件(`src/`,箱 `seal-node`)，再加一薄 JavaScript层(`index.js`， `index.d.ts`， `errors.js`）。 `build.sh` (或 `npm run build`） 将此机器的附加组件构建为 `seal.<platform>.node`, `native.js` 加载文件 第一。发布后，每个平台的插件都是它自己的包 （`@sealzone/sdk-linux-x64-gnu`，…)，在napi-rs布局中作为可选依赖项列出。 `build.sh` 取这些旗子：

-   `--release` 建造什么船。
-   `--aws` 增加了 `AwsIdentity`.
-   `--sim` 瞄准模拟器。

`build.sh --test` 中运行单元测试 `test/` 与 `node --test`，没有模拟器。 从存储库根目录， `scripts/e2e.sh -k node` 运行 `examples/e2e.mjs` 反对整体 模拟系统(`tests/e2e/test_node_sdk.py`）. 它涵盖了通过隧道的会话和 像任何人一样密封。

## 常见问题

### @sealzone/sdk 是什么？

封印：使用秘密而不保留秘密。

### 如何安装 @sealzone/sdk？

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

### @sealzone/sdk 支持 TypeScript 吗？

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

### @sealzone/sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @sealzone/sdk 需要什么版本的 Node\.js？

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

### @sealzone/sdk 可以商用吗？

@sealzone/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @sealzone/sdk 还在维护吗？

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