Credential Proxy

凭证代理

一个MCP（模型上下文协议）服务器，它允许AI代理发出经过验证的API请求并运行经过验证的命令，而不会看到凭据值。

凭证处理在 编译的Swift二进制文件 嵌入在macOS应用程序中。代理通过一个精简的Node.js MCP中继进行通信，该中继将工具调用转发到本机HTTP服务器。由于代理可以修改JavaScript，但不能编译Swift，因此安全边界是在二进制级别强制执行的。

运作原理

┌─────────────────────────────────────────────────────────────────────┐
│                    SECRET NEVER CROSSES THIS LINE                   │
├─────────────────────────────────────────────────────────────────────┤
│  Agent Context              │      Native Swift Server (Compiled)   │
│  (Untrusted)                │                                       │
│  • Sees secret NAMES only   │  • Stores values in macOS Keychain   │
│  • Uses {{PLACEHOLDER}}     │  • Validates domain allowlist        │
│  • Receives sanitized resp  │  • Executes actual requests          │
│  • Cannot exfiltrate        │  • Redacts leaked values from output │
└─────────────────────────────────────────────────────────────────────┘

Claude Code → MCP stdio relay (Node.js, thin) → HTTP :11111 (Swift, compiled) → Keychain

代理人问： *“POST到 https://api.linear.app/graphql 带标题 Authorization: Bearer {{LINEAR_API_KEY}}"*

服务器：

1. 确认 LINEAR_API_KEY 允许 *.linear.app
2. 验证位置(header)是允许的
3. 从macOS Keychain检索值并替换它
4. 执行请求
5. 扫描响应以查找泄露的秘密值并对其进行编辑
6. 将经过净化的响应返回给代理

安装

要求： macOS 13+、Node.js 20+、Swift（Xcode命令行工具）

git clone https://github.com/ddfourtwo/credential-proxy.git
cd credential-proxy
bash install.sh

安装程序：

1. 构建MCP中继（Node.js stdio→ HTTP网桥）
2. 构建本地macOS应用程序（Swift HTTP服务器）
3. 创建 ~/Applications/Credential Proxy.app
4. 在中注册MCP服务器 ~/.claude.json
5. 设置LaunchAgent（登录时自动启动）
6. 启动应用程序

安装后重新启动Claude Code以加载MCP服务器。

更新

# 1. Click "Prepare for Update" in the menu bar (required — script blocks without it)
# 2. Run:
./reinstall.sh
# 3. Enter your PIN in the menu bar to complete migration
# 4. Restart Claude Code

快速开始

# 1. Add a credential with domain restrictions
npx credential-proxy add LINEAR_API_KEY -d "*.linear.app"
# You'll be prompted to enter (and confirm) the secret value

# 2. The agent can now use it via MCP tools:
#    proxy_request({
#      method: "POST",
#      url: "https://api.linear.app/graphql",
#      headers: { "Authorization": "Bearer {{LINEAR_API_KEY}}" },
#      body: { "query": "{ viewer { id name } }" }
#    })

CLI参考

add --存储凭据

# Basic: enter value interactively
npx credential-proxy add SECRET_NAME -d "*.example.com"

# With multiple domains and placement types
npx credential-proxy add GITHUB_TOKEN -d "*.github.com,api.github.com" -p "header,env,arg"

# With command restrictions for exec proxy
npx credential-proxy add GIT_TOKEN -d "*.github.com" -p "arg,env" -c "git *"

# Using 1Password instead of local storage
npx credential-proxy add GITHUB_TOKEN --1password "op://Private/GitHub/token" -d "*.github.com"

选项：

机密名称必须为 SCREAMING_SNAKE_CASE （例如。， API_KEY, GITHUB_TOKEN).

list --显示配置的凭据

npx credential-proxy list          # human-readable
npx credential-proxy list --json   # JSON output

remove --删除凭据

npx credential-proxy remove LINEAR_API_KEY

rotate --替换凭据值

npx credential-proxy rotate LINEAR_API_KEY
# Prompts for a new value; preserves domain/placement config

test --验证凭据是否可读

npx credential-proxy test LINEAR_API_KEY

export / import --备份和传输

# Export (includes decrypted values!)
npx credential-proxy export ~/secrets-backup.json

# Import
npx credential-proxy import ~/secrets-backup.json
npx credential-proxy import ~/secrets-backup.json --overwrite   # replace existing

# Transfer between machines via SSH
credential-proxy export --stdout | ssh dest 'credential-proxy import --stdin'

警告： 导出文件包含解密的机密。使用后立即删除。

MCP工具参考

MCP服务器向代理提供三个工具：

list_credentials

发现可用凭据。仅返回名称和元数据，从不返回值。

// Response
{
  "secrets": [
    {
      "name": "LINEAR_API_KEY",
      "sourceType": "keychain",
      "allowedDomains": ["*.linear.app"],
      "allowedPlacements": ["header"],
      "configured": true,
      "usageCount": 42
    }
  ]
}

proxy_request

使用凭据替换发出HTTP请求。使用 {{SECRET_NAME}} URL、标题或正文中的占位符。

示例-线性GraphQL API：

proxy_request({
  "method": "POST",
  "url": "https://api.linear.app/graphql",
  "headers": {
    "Authorization": "Bearer {{LINEAR_API_KEY}}",
    "Content-Type": "application/json"
  },
  "body": {
    "query": "{ issues(first: 10) { nodes { id title state { name } } } }"
  }
})

示例-GitHub REST API：

proxy_request({
  "method": "GET",
  "url": "https://api.github.com/user/repos?per_page=5",
  "headers": {
    "Authorization": "Bearer {{GITHUB_TOKEN}}"
  }
})

错误响应：

// Domain not allowed
{ "error": "SECRET_DOMAIN_BLOCKED", "message": "Secret 'KEY' cannot be used with domain 'evil.com'" }

// Placement not allowed
{ "error": "SECRET_PLACEMENT_BLOCKED", "message": "Secret 'KEY' cannot be used in 'body'" }

// Secret not configured
{ "error": "SECRET_NOT_FOUND", "message": "Secret 'MISSING' is not configured" }

proxy_exec

执行带有凭据替换的shell命令。秘密可以注入到命令参数或环境变量中。

示例——带有令牌的Git克隆：

proxy_exec({
  "command": ["git", "clone", "https://{{GITHUB_TOKEN}}@github.com/org/private-repo.git"]
})

示例——带有env var的GitHub CLI：

proxy_exec({
  "command": ["gh", "api", "/user"],
  "env": { "GH_TOKEN": "{{GITHUB_TOKEN}}" }
})

建筑

安全模型

• 秘密存储 --macOS Keychain中的值（通过Security.framework），JSON中的元数据
• 编译服务器 --HTTP服务器是Swift二进制文件；代理无法修改它
• 域名满配列表 --每个秘密都指定了它可以发送到哪些域。支持通配符(*.github.com)
• 位置验证 --控制机密是否可以出现在标头、正文、查询参数、环境变量或命令参数中
• 响应编辑 --所有输出都扫描了秘密值（>=6个字符），并替换为 [REDACTED:SECRET_NAME]
• 审计日志 --所有使用记录到 ~/Library/Application Support/credential-proxy/audit.log 以10MB的速度旋转
• 仅限本地主机 --HTTP服务器绑定到 127.0.0.1:11111，无法从网络访问

1密码集成

参考机密存储在1Password中，而不是macOS Keychain中。通过以下方式按需获取值 op CLI。

npx credential-proxy add GITHUB_TOKEN \
  --1password "op://Private/GitHub Token/password" \
  -d "*.github.com"

需要 1Password命令行界面.

数据位置

发展

npm install
npm run build       # build MCP relay with tsup
npm run dev         # watch mode
npm run test        # run tests (vitest)

# Build the Swift server
cd macos && swift build -c release

# Fresh install (builds everything + creates app bundle)
bash install.sh

# Update existing installation (requires "Prepare for Update" in menu bar)
./reinstall.sh

许可证

麻省理工学院