irisnb/dsh-credentials-keyring

dsh-credentials-keyring

一个面向 DeepSeek Harness 凭据接缝（ctx.credentials）的操作系统钥匙串凭据提供程序。

它将 API 密钥和其他机密存储在操作系统的原生凭据存储中——Windows 凭据管理器、macOS 钥匙串或 Linux Secret Service——而不是内置的 @deepseek-ai/dsh-credentials-local 所使用的纯文本文件。

中文说明见文末。

为什么

DeepSeek Harness 提供了一个凭据接缝（ctx.credentials），且只有一个提供程序 dsh-credentials-local，它将机密写入 .credentials.yaml / .env 文件。Harness 自己的文档将操作系统钥匙串提供程序标记为推迟：

一个操作系统钥匙串提供程序——一个模型进程完全无法读取的存储——是推迟的答案，并且应作为同级包放在此提供程序旁边。

本包就是那个同级提供程序。它保持相同的四操作接缝（resolve / describe / set / unset），因此挂载它改变的是机密存放的位置，而不是消费者读取它们的方式——LLM 适配器和其他消费者继续以不变的方式调用 ctx.credentials.resolve()。

安装

尚未发布到 npm——直接从 Git 仓库安装：

npm install git+https://github.com/irisnb/dsh-credentials-keyring.git

编译后的 lib/ 输出已提交，因此 Git 安装无需构建步骤即可工作。

对等依赖是 @deepseek-ai/cordis 和 @deepseek-ai/dsh-credentials；请安装与你所运行的 Harness 版本相匹配的版本。

用法

该提供程序实现了 CredentialProvider，因此它接入 credentials 接缝，并为每个凭据引用（一个 POSIX 标识符，例如 DEEPSEEK_API_KEY）存储一个值。

import { Context } from '@deepseek-ai/cordis'
import { KeyringCredentialProvider } from 'dsh-credentials-keyring'

const ctx = new Context()
await ctx.plugin(KeyringCredentialProvider, { service: 'com.your-app.desktop' })

// Consumers then resolve through the seam as usual:
const hit = await ctx.credentials.resolve(credentialRef('DEEPSEEK_API_KEY'))
// { value: 'sk-…', source: 'keyring' } | undefined

配置

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| service | com.deepseek.dsh | 钥匙串服务命名空间。将其设置为你的应用标识符，这样你的机密就永远不会与另一个应用的机密冲突。 |

所有其他值都存放在钥匙串中的 (service, account) 下，其中 account 是凭据引用。

语义

- resolve(ref) → 存储时返回 { value, source: 'keyring' }，不存在或为空时返回 undefined。
- describe(ref) → { configured, source?, writable }——绝不返回值。
- set(ref, value) → 存储；拒绝空值（请使用 unset）。
- unset(ref) → 删除；删除不存在的条目是空操作。
- set / unset 在提交后发出 credentials/updated，与每个提供程序一样。

平台支持与降级
原生层是 @napi-rs/keyring（N-API 绑定背后的 Rust keyring crate）。它惰性加载并探测一次：

- Windows / macOS / Linux（带 Secret Service） — 完全支持。
- 无 Secret Service 的无头 Linux — 提供方仍会挂载，但 describe() 报告 writable: false，resolve() 回答“不存在”，set() 抛出明确的错误。它绝不会静默假装秘密已被存储。

开发

npm install
npm run typecheck   # tsc --noEmit over src + tests
npm test            # vitest: unit tests against an in-memory backend, never the real keychain
npm run build       # tsc emit to lib/

单元测试注入内存中的 KeyringBackend，因此它们可以在任何地方运行，而不会触及操作系统钥匙串。唯一依赖 @napi-rs/keyring 确切 API 的文件是 NapiKeyringBackend；其“未找到”错误映射应在发布前，在真实机器上用一次性冒烟测试对照固定版本重新验证。

安全说明

秘密绝不会作为配置值进入此包的公共 API；它们只在调用方和操作系统钥匙串之间移动。请记住，操作系统钥匙串防范的是机器上的其他进程和磁盘上的明文泄露——它不会对你自己的代码选择信任的调用方隐藏秘密。

许可证

MIT

中文说明

这是给 DeepSeek Harness 凭据接缝（ctx.credentials）写的「系统钥匙串」提供方：把 API Key 等秘密存进操作系统原生凭据存储（Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service），替代内置的明文文件实现 dsh-credentials-local。

它实现与内置提供方完全相同的四个操作（resolve / describe / set / unset），所以挂上去之后，所有读取凭据的消费者（如 LLM 适配器）一行都不用改。唯一可配置项是 service（钥匙串命名空间，默认 com.deepseek.dsh）。

无图形界面的 Linux 上原生层不可用时，插件仍能挂载，但会明确报「不可写」，绝不静默假装存成功。单元测试用内存后端，不碰真实钥匙串。

安装：目前尚未发布到 npm，可直接从 Git 仓库安装：

npm install git+https://github.com/irisnb/dsh-credentials-keyring.git

仓库已提交编译产物 lib/，所以 Git 安装后无需再手动 build。