# @drkmttr/sops-age 中文文档

规范地址：https://npmcn.com/package/%40drkmttr/sops-age/

版本：4\.1\.0
npm 元数据更新时间：2026-09-22T22:20:34.122Z
中文译文更新时间：2026-11-13T03:54:04.192Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.2 MB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：9 个
- 首次发布：2026-09-22T22:20:33.355Z
- 最新版本发布：2026-09-22T22:20:33.758Z
- 近 30 天下载量：2363（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

用于 JavaScript — 带有 KMS 加密文件数据Key 选项的暗物质分叉的 sops 年龄解密

## 安装

```sh
npm install @drkmttr/sops-age
```

也可以使用：`pnpm add @drkmttr/sops-age`、`yarn add @drkmttr/sops-age`、`bun add @drkmttr/sops-age`

## README

> **暗物质叉** 联 合 国 [驼峰/高龄](https://github.com/humphd/sops-age),作为 `@drkmttr/sops-age`。 。 。 . 添加 `dataKey` 选项(解密您自己解开的数据密钥的文件,例如通过AWS KMS)并接受没有年龄收件人的文件。 提供上游 [驼峰/羊龄#22](https://github.com/humphd/sops-age/pull/22);这个分叉之所以存在,是因为上游已经安静了一年了. 其他一切都没有改变.

# 索普斯年龄

`sops-age` 是一个 TypeScript 库,旨在解密已加密的文件 [目标](https://github.com/getsops/sops) (保密程序) [年龄](https://github.com/FiloSottile/age) 加密工具。 这个库为解密环境变量,配置文件,以及其它在您的应用程序中用SOPS和年龄加密的敏感数据提供了简单的方法. 它在大多数的JavaScript运行时间(node.js,浏览器,Deno,Bun等)中工作.

## 特征

-   支持加密 SOPS 文件的解密 `age`
-   遵循 SOPS 常规自动时代密钥发现
-   SSH 密钥支持, 自动将 Ed25519 和 RSA SSH 密钥转换为年龄格式
-   兼容各种文件格式,包括 `.env`, (中文(简体) ), `.json`,以及 `.yaml`
-   支持多种输入类型( E)`string`, (中文(简体) ), `Buffer`, (中文(简体) ), `File`, (中文(简体) ), `Blob`,溪流等)
-   跨不同 JavaScript 运行时间的工作( Node.js, Deno, Bun, 浏览器)
-   从文件、 URL 或原始内容中解密 OPS 数据的简单、统一的 API
-   带有可选手动覆盖的文件类型自动检测

## 安装

安装 `sops-age` 使用您首选的软件包管理器 :

```sh
# npm
npm install sops-age

# pnpm
pnpm add sops-age

# yarn
yarn add sops-age
```

## 使用量

库可用于各种 JavaScript 环境并支持多个模块格式:

### 无害环境管理(建议)

```js
import { decryptSops } from "sops-age";

// Decrypt from a local file (keys auto-discovered from env and file system)
const config = await decryptSops({
  path: "./config.enc.json",
});

// Or with explicit age key
const config = await decryptSops({
  path: "./config.enc.json",
  secretKey: "AGE-SECRET-KEY-1qgdy...",
});
```

### 常见JS

```js
const { decryptSops } = require("sops-age");

// Decrypt from a URL
const config = await decryptSops({
  url: "https://example.com/config.enc.yaml",
  secretKey: "AGE-SECRET-KEY-1qgdy...",
});
```

### 浏览器( CDN)

```html
<!-- Add to your HTML -->
<script src="https://unpkg.com/sops-age/dist/index.global.js"></script>

<script>
  // The library is available as window.decryptSops
  async function loadConfig() {
    const config = await decryptSops({
      url: "https://example.com/config.enc.json",
      secretKey: "AGE-SECRET-KEY-1qgdy...",
    });
    console.log(config);
  }
</script>
```

### 类型脚本

库包括 TypeScript 类型定义:

```ts
import { decryptSops, type DecryptSopsOptions } from "sops-age";

const options: DecryptSopsOptions = {
  secretKey: "AGE-SECRET-KEY-1qgdy...",
  fileType: "json",
};

const config = await decryptSops(jsonString, options);
```

### 基本用途

图书馆提供统一的 `decryptSops` 可处理各种输入类型的函数:

```js
import { decryptSops } from "sops-age";

// Decrypt from a local file, auto-discovering age keys
const config = await decryptSops({
  path: "./config.enc.json",
});

// Decrypt from a URL with explicit age key
const remoteConfig = await decryptSops({
  url: "https://example.com/config.enc.yaml",
  secretKey: "AGE-SECRET-KEY-1qgdy...",
});

// Decrypt from string content
const content = '{"sops": {...}}';
const data = await decryptSops(content, {
  secretKey: "AGE-SECRET-KEY-1qgdy...",
  fileType: "json",
});
```

### 支持的文件类型

`sops-age` 支持以下文件类型:

-   `.env`
-   `.json`
-   `.yaml` 编号 : `.yml`

库根据文件扩展名或内容自动检测文件类型. 您也可以使用手动指定文件类型 `fileType` 选项.

## 输入类型

`sops-age` 支持 SOPS 加密内容的各种输入类型 :

-   `string`: SOPS 文件的原始字符串内容
-   `File`: 文件对象( 在浏览器环境中)
-   `Blob`: 二进制数据
-   `ArrayBuffer`: 原始二进制数据
-   `Uint8Array`: 键入的字节数组
-   `Buffer`:Node.js Buffer (在Node.js环境中) 互联网档案馆的存檔,存档日期2013-12-21
-   `ReadableStream<Uint8Array>`: 二进制数据流

## 年龄密钥发现

`sops-age` 使用与SOPS本身相同的逻辑自动发现年龄键. 否时 `secretKey` 图书馆将按以下顺序搜索密钥:

### 1\. SSH 密钥(转换为年龄格式)

库可以自动将 SSH 私钥转换为年龄格式 :

-   **环境变量**数字 : `SOPS_AGE_SSH_PRIVATE_KEY_FILE` - SSH 私钥路径
-   **默认位置**数字 : `~/.ssh/id_ed25519` 财务报告和审定财务报表 `~/.ssh/id_rsa` (按此顺序排列)
-   **支持类型**: Ed25519 和 RSA 密钥

```js
// Set environment variable to use specific SSH key
process.env.SOPS_AGE_SSH_PRIVATE_KEY_FILE = "/path/to/my/ssh/key";

// Keys will be auto-discovered and converted
const config = await decryptSops({ path: "./config.enc.json" });
```

### 2\. 环境变量的年龄键

-   **`SOPS_AGE_KEY`**: 直接年龄的私钥
-   **`SOPS_AGE_KEY_FILE`**: 包含年龄密钥的文件路径
-   **`SOPS_AGE_KEY_CMD`**: 输出时代键的命令

```js
// Direct key
process.env.SOPS_AGE_KEY = "AGE-SECRET-KEY-1qgdy...";

// Key file
process.env.SOPS_AGE_KEY_FILE = "/path/to/keys.txt";

// Command that outputs keys
process.env.SOPS_AGE_KEY_CMD = "my-key-manager get-age-key";
```

### 3\. 默认配置文件

默认 SOPS 配置目录中的年龄密钥库检查 :

-   **Linux/ 团结**数字 : `~/.config/sops/age/keys.txt` (或 `$XDG_CONFIG_HOME/sops/age/keys.txt`(中文(简体) )
-   **马科斯**数字 : `~/Library/Application Support/sops/age/keys.txt` (或 `$XDG_CONFIG_HOME/sops/age/keys.txt` 如果设置)
-   **窗口**数字 : `%APPDATA%\sops\age\keys.txt`

示例 `keys.txt` 文件 :

```text
# Created: 2024-01-15T10:30:00Z
# Public key: age1je6kjhzuhdjy3fqptpttxjh5k8q46vygzlgtpuq3030c947pc5tqz9dqvr
AGE-SECRET-KEY-1QGDY7NWZDM5HG2QMSKQHQZPQF2QJLTQHQZPQF2QJLTQHQZPQF2QJLTQHQZ

# Another key
AGE-SECRET-KEY-1ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOP
```

## 密钥发现优先级

当不明确时 `secretKey` 按此顺序查找密钥 :

1.  **SSH 密钥**数字 : `SOPS_AGE_SSH_PRIVATE_KEY_FILE` → `~/.ssh/id_ed25519` → `~/.ssh/id_rsa`
2.  **年龄键**数字 : `SOPS_AGE_KEY` → `SOPS_AGE_KEY_FILE` → `SOPS_AGE_KEY_CMD`
3.  **默认配置**: 特定平台 `sops/age/keys.txt` 文件

库将尝试所有已发现的密钥, 直到一个成功解密文件 .

## 年龄关键公用事业

库包括用于发现年龄密钥和将SSH密钥转换为年龄格式的公用设备:

```js
import { sshKeyToAge, sshKeyFileToAge, findAllAgeKeys } from "sops-age";

// Convert SSH key content to age format
const sshKeyContent = "-----BEGIN OPENSSH PRIVATE KEY-----\n...";
const ageKey = sshKeyToAge(sshKeyContent);

// Convert SSH key file to age format
const ageKey = await sshKeyFileToAge("/path/to/ssh/key");

// Discover all available age keys
const allKeys = await findAllAgeKeys();
console.log("Found keys:", allKeys);
```

## API 参考

### `decryptSops(input, options?)`

直接从字符串,缓冲或者其他被支持的输入类型解密 OPS-加密内容.

```js
// With auto-discovered keys
const decrypted = await decryptSops(jsonString, {
  fileType: "json",
});

// With explicit key
const decrypted = await decryptSops(jsonString, {
  secretKey: "AGE-SECRET-KEY-1qgdy...",
  fileType: "json",
});
```

### `decryptSops({ path: "...", ... })`

从本地文件系统解密一个 SOPS 加密的文件 .

```js
const decrypted = await decryptSops({
  path: "/path/to/config.enc.json",
  // secretKey optional - will auto-discover
});
```

### `decryptSops({ url: "https://...", ... })`

从 URL 解密一个 SOPS 加密文件 .

```js
const decrypted = await decryptSops({
  url: "https://example.com/config.enc.json",
  secretKey: "AGE-SECRET-KEY-1qgdy...", // or auto-discover
});
```

### `decryptSops(sopsObject, options?)`

直接从预分解的 SOPS 对象解密 SOPS 加密内容.

```js
const sopsObject = {
  secret:
    "ENC[AES256_GCM,data:trrpgezXug4Dq9T/inwkMA==,iv:glPwxoY2UuHO91vlJRaqYtFkPY1VsWvkJtfkEKZJdns=,tag:v7DbOYl7C5gdQRdW6BVoLw==,type:str]",
  sops: {
    // ... SOPS metadata
  },
};

// Auto-discovers keys from environment/config
const decrypted = await decryptSops(sopsObject);
```

### `DecryptSopsOptions`

这个 `decryptSops` 函数接受以下选项:

-   `secretKey`: 解密的年龄密钥( 可选的 - 如果不提供会自动发现)
-   `fileType`:可选文件类型 ("env","json",或"yaml"). 未指定时自动检测
-   `keyPath`: 只解密特定值的可选路径
-   `path`: 本地 SOPS 文件的路径( 当使用基于文件的解密时)
-   `url`: SOPS 文件的 URL( 当使用基于 URL 的解密时)

### 工具函数

#### `findAllAgeKeys()`

使用 SOPS 逻辑发现所有可用的时代密钥(包括已转换的 SSH 密钥):

```js
import { findAllAgeKeys } from "sops-age";

const keys = await findAllAgeKeys();
console.log("Available age keys:", keys);
```

#### `sshKeyToAge(keyContent, filePath)`

将 SSH 私有密钥内容转换为年龄格式 :

```js
import { sshKeyToAge } from "sops-age";

const sshKey = "-----BEGIN OPENSSH PRIVATE KEY-----\n...";
const ageKey = sshKeyToAge(sshKey, "id_ed25519");
// Returns: "AGE-SECRET-KEY-1..." or null for unsupported keys
```

#### `sshKeyFileToAge(filePath)`

将 SSH 私有密钥文件转换为年龄格式 :

```js
import { sshKeyFileToAge } from "sops-age";

const ageKey = await sshKeyFileToAge("~/.ssh/id_ed25519");
// Returns: "AGE-SECRET-KEY-1..." or null
```

## 许可证

`sops-age` 以麻省理工学院的许可证发放。 见 [自由主义](https://npmcn.com/package/%40drkmttr/sops-age/LICENSE.md) 以备详细文件.

## 文件加密到其他主密钥( AWS KMS,...)

`sops-age` 只打开 SOPS 数据密钥 **年龄**。如果一个文件被加密 到另一个主密钥, 自己解开数据密钥并交给它 `dataKey`; 值解密( AES-256- GCM 有 SOPS 路径附加) 每个主密钥都是一样的:

```ts
import { decryptSops } from "sops-age";

// e.g. kms:Decrypt of sops.kms[0].enc → 32-byte data key
const dataKey: Uint8Array = await unwrapWithKms(encrypted.sops.kms[0]);

const secrets = await decryptSops(encryptedJson, { dataKey, fileType: "json" });
```

何时 `dataKey` 设置, 没有查找年龄键, 并且 `secretKey` 被忽略. 文件为 `"age": null` (完全没有年龄领取者) `dataKey`。 。 。 .

## 常见问题

### @drkmttr/sops-age 是什么？

用于 JavaScript — 带有 KMS 加密文件数据Key 选项的暗物质分叉的 sops 年龄解密

### 如何安装 @drkmttr/sops-age？

在项目目录运行 npm install @drkmttr/sops-age，或使用 pnpm add / yarn add / bun add。

### @drkmttr/sops-age 支持 TypeScript 吗？

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

### @drkmttr/sops-age 支持 ESM 还是 CommonJS？

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

### @drkmttr/sops-age 需要什么版本的 Node\.js？

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

### @drkmttr/sops-age 可以商用吗？

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

### @drkmttr/sops-age 的下载量有多少？

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

### @drkmttr/sops-age 还在维护吗？

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