@git-stunts/vault

中文文档
1.0.1发布于 2026/03/04Apache-2.0ES Module近 30 天下载 6928

A secure interface to OS-native keychains (macOS, Linux, Windows) for "Zero-Secret Architecture."

原始使用文档
文档目录8 节
  1. Why Vault?
  2. Features
  3. Requirements
  4. Runtime-specific adapters
  5. Docker-based tests
  6. Usage
  7. Docker images
  8. License

@git-stunts/vault

A secure interface to OS-native keychains (macOS, Linux, Windows) for "Zero-Secret Architecture."

Why Vault?

Storing API keys or encryption secrets in .env files is a security risk. vault offloads this responsibility to the operating system's native secure storage. Your application never "owns" the secret—it simply requests it when needed.

Features

  • Cross-Platform: Supports macOS Keychain, Linux Secret Service, and Windows Credential Manager.
  • Zero-Secret: No plain-text keys on disk.
  • Interactive: Can prompt the user for missing secrets and store them automatically.

Requirements

  • macOS: Works out of the box (uses security).
  • Linux: Requires libsecret (e.g., sudo apt install libsecret-tools).
  • Windows: Requires the CredentialManager PowerShell module.

Runtime-specific adapters

  • Node (default): Vault auto-detects Bun and Deno globals and falls back to the Node adapter when neither is present.
  • Bun: Import createBunKeychainAdapter (or rely on the auto-detection) to execute commands with Bun.spawnSync when running under Bun.
  • Deno: Import createDenoKeychainAdapter and run via Deno.Command. See deno.json and Dockerfile.deno for a working setup.

The plumbing/ folder contains the reference Dockerfiles for each runtime (Dockerfile.bun, Dockerfile.deno, etc.), so you can see how the ports are wired together in an end-to-end image.

Docker-based tests

  • npm test runs scripts/run-multi-runtime-tests.sh, which in turn brings up the node-test, bun-test, and deno-test containers defined in docker-compose.yml.
  • Each container uses the respective Dockerfile (Dockerfile, Dockerfile.bun, Dockerfile.deno) so you can reproduce the same setup locally or in CI.

Usage

import Vault from '@git-stunts/vault';

const vault = new Vault({ account: 'my-app' });

// Get a secret (returns undefined if missing)
const key = vault.getSecret({ target: 'CHUNK_ENC_KEY' });

// Ensure a secret exists (prompts user if missing)
const secret = await vault.ensureSecret({ 
  target: 'API_TOKEN', 
  promptMessage: 'Enter your API Token' 
});

// Resolve with Env Var priority
const apiKey = vault.resolveSecret({ 
  envKey: 'MY_API_KEY', 
  vaultTarget: 'api-key' 
});

Docker images

  • Dockerfile (Node) mirrors the repository root workflow and runs npm test.
  • Dockerfile.bun copies both projects, installs with Bun, and runs bun run vitest test/unit.
  • Dockerfile.deno relies on deno task test defined in deno.json, which proxies back to the npm test stack via the shared script.

License

Apache-2.0 Copyright © 2026 James Ross

版本与发布记录

@git-stunts/vault 共发布 2 个版本,首次发布于 2026/01/13;过去 12 个月发布了 2 个版本。

版本发布日期距今
1.0.1latest2026/03/048 个月前
1.0.02026/01/1310 个月前

关于 @git-stunts/vault 的常见问题

@git-stunts/vault 是什么?

A secure interface to OS-native keychains (macOS, Linux, Windows) for "Zero-Secret Architecture."

如何安装 @git-stunts/vault?

在项目目录运行 npm install @git-stunts/vault,或使用 pnpm add / yarn add / bun add。

@git-stunts/vault 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/git-stunts__vault 是否存在。

@git-stunts/vault 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@git-stunts/vault 需要什么版本的 Node.js?

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

@git-stunts/vault 可以商用吗?

@git-stunts/vault 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@git-stunts/vault 的下载量有多少?

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

@git-stunts/vault 还在维护吗?

最新版本 1.0.1 发布于 2026/03/04(8 个月前);至今共发布 2 个版本,其中过去 12 个月发布了 2 个;首次发布于 2026/01/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。