# KeyringSeam

[![Self-test](https://github.com/fieldnote-ops/keyringseam/actions/workflows/self-test.yml/badge.svg?branch=main)](https://github.com/fieldnote-ops/keyringseam/actions/workflows/self-test.yml)

KeyringSeam 是面向 DeepSeek Harness `ctx.credentials` 接缝的独立 macOS 凭证提供方。`0.2.0-rc.1` 候选版本用 Developer ID 签名并经 Apple 公证的 Broker app 替换旧的 file-Keychain helper：受管值写入私有 Data Protection Keychain access group，执行 `get`、`set`、`unset` 前都要求设备所有者明确认证。

> **发布状态：** `v0.2.0-rc.1` 已作为公开候选版发布。Agent 隔离本机验收、DSH consumer 启动、Apple 公证、staple、Gatekeeper、quarantine 下的原生/Intel 启动以及公开归档哈希复核均已通过。三台机器/24 小时外部验收暂缓；不宣称独立安全审计或陌生用户已采用。已发布的 v0.1.3 仍是旧的存储增强版本，不能描述为 Agent 隔离。

KeyringSeam 是 **FIELD NOTE** 独立、AI 辅助的开源项目，与 DeepSeek 或 Apple 无隶属、赞助或背书关系。DeepSeek Harness 仅用于说明兼容性；macOS 和 Keychain 是 Apple 商标。

## 首屏证据

| 维度 | 已验证行为 |
| --- | --- |
| Broker 边界 | 持久 stdin/stdout framing、空子进程环境、不使用带 secret 的 argv、有界请求/响应、串行操作与生命周期销毁。 |
| 钥匙串策略 | 私有精确 access group `TU8DF2JWHF.org.fieldnote.keyringseam.broker`、Data Protection Keychain、仅限本机的保护属性，以及每次 secret 操作都显式要求设备所有者认证。 |
| 同 UID 攻击 | 独立 Security.framework reader 返回 `errSecMissingEntitlement (-34018)`；`/usr/bin/security` 找不到项目；复制出的原始 Broker 被拒绝；取消直接调用返回 `-128` 且没有 value。 |
| 二进制来源 | 通用 `arm64 + x86_64` Developer ID、Hardened Runtime、安全时间戳、嵌入 profile、Apple 公证 `8941cae5-75a5-4f1c-bdfb-998d1ce578c3`、staple、Gatekeeper 与 quarantine 启动均已验证。 |
| Harness 集成 | 隔离 DSH `0.1.0-rc.6` 完成 `plugin add`、组合配置替换、Web HTTP 200 启动；DSH bash tool 尝试读取时 fail-closed 且未返回 value。 |

这不是独立安全审计，也不代表陌生用户已采用。

## 安装公开候选版

`dsh` 不是系统全局命令。请在运行 Harness 的环境中安装固定 preview CLI 与 `pnpm`：

```sh
npm install --global pnpm @deepseek-ai/dsh@0.1.0-rc.6
dsh --version
pnpm --version
```

请安装公开的固定候选版本。首次运行建议使用一次性凭证，并在使用生产凭证前检查生成的 profile diff：

```sh
dsh plugin --profile web add github:fieldnote-ops/keyringseam#v0.2.0-rc.1
```

此前的 `v0.1.3` 命令仍可用于回滚，但明确属于旧的文件存储架构：

```sh
dsh plugin --profile web add github:fieldnote-ops/keyringseam#v0.1.3
```

## 安全设计

- provider 生命周期内只启动一个固定、已签名的 Broker app，通过匿名管道通信；不传递 host 环境，也不把 secret 放进命令行参数。
- 每次 `get`、`set`、`unset` 都显式认证。取消、超时、entitlement 缺失、签名无效、钥匙串锁定、framing 损坏和原生错误都会返回错误；没有明文或旧 helper 回退。
- Broker 面向 macOS 13 及以上，包含 Apple Silicon 与 Intel slice。使用者运行时不需要 Swift、Xcode 或 Apple 命令行开发工具。
- 环境变量仍是只读最高优先级；项目与用户 `.env` fallback 仍低于受管 Keychain 来源。
- 用户主动批准意外认证窗口、被攻陷的 macOS 账户、对可信 Harness host 的调试权限，以及可信 host 本身，都不在边界内。

## 维护者验证

```sh
npm ci
npm run check
node scripts/broker-architecture-smoke.mjs native
node scripts/broker-architecture-smoke.mjs x86_64
```

构建新 Broker 必须使用精确 Developer ID 身份与批准的 provisioning profile：

```sh
KEYRINGSEAM_SIGN_IDENTITY='Developer ID Application: Legal Name (TEAMID)' \
KEYRINGSEAM_PROVISIONING_PROFILE='/absolute/path/to/profile.provisionprofile' \
npm run build:broker
```

公证使用本机钥匙串中的 `keyringseam-notary` profile，通过 `scripts/notarize-broker.sh` 完成；不得绕过安全时间戳或 staple 验证。

详见 [Agent 隔离设计](docs/AGENT_ISOLATION.md) 与 [SECURITY.md](SECURITY.md)。