keywarden

당신의 AI 에이전트는 API 키를 사용할 수 있지만, 절대 읽을 수는 없습니다.

keywarden은 MCP를 지원하는 로컬 암호화 자격 증명 저장소입니다. Claude Code, Claude Desktop, Cursor 또는 모든 MCP 클라이언트가 여기에 연결하여 두 가지 기능을 얻습니다: 인증된 API 호출과 자격 증명을 환경 변수에 넣어 명령어를 실행하는 것입니다. 어느 쪽도 자격 증명 자체를 모델의 컨텍스트에 넣지 않습니다.

get_secret 도구는 없습니다. 그 부재가 바로 이 제품의 전부입니다.

   agent                keywarden                    upstream
     |                     |                          |
     |  "POST /v1/chat     |                          |
     |   using openai/prod"|                          |
     |-------------------->|                          |
     |                     | check policy             |
     |                     | decrypt key              |
     |                     | attach Authorization     |
     |                     |------------------------->|
     |                     |<-------------------------|
     |  response only      | scrub any key from body  |
     |<--------------------| append to audit log      |

왜 필요한가

현재 에이전트가 OpenAI 키를 사용하도록 하는 일반적인 방법은 키를 .env 파일에 넣고 에이전트가 읽게 하는 것입니다. 그 순간 키는 모델의 컨텍스트 창에 들어가게 됩니다. 거기서부터 공급자의 로그, 어쩌면 학습 데이터셋, 어쩌면 크래시 리포트, 그리고 분명히 6개월 후 버그 리포트에 붙여넣게 될 당신의 트랜스크립트 기록에도 남게 됩니다.

키를 교체하는 것은 번거롭습니다. 하지만 유출 여부조차 모르는 것이 더 나쁩니다.

keywarden은 모델이 키를 전혀 볼 수 없게 만드는 단계를 제거합니다.

Related MCP server: AgentPay MCP Server

설치

npm install -g keywarden

Node 20.10 이상. 런타임 의존성은 MCP SDK와 zod 두 가지뿐입니다. 네이티브 모듈도, 컴파일러도, 데몬도 없습니다.

빠른 시작

keywarden init --passphrase
keywarden add openai/prod --provider openai
keywarden mcp-config

init는 암호화된 볼트와 기본 거부 정책이 포함된 ~/.keywarden/를 생성합니다. add는 각 필드를 프롬프트로 입력받으므로 셸 기록에 남지 않습니다. mcp-config는 MCP 클라이언트에 붙여넣을 블록을 출력합니다.

그런 다음 Claude Code에서:

프로덕션 키로 OpenAI 모델 엔드포인트를 호출하고 어떤 모델에 접근할 수 있는지 알려줘.

모델은 ref: "openai/prod"로 http_request를 호출합니다. keywarden이 키를 첨부하고, 호출하고, 응답을 반환합니다. 키를 출력하라고 하면 할 수 없다고 말할 것입니다.

에이전트가 얻는 도구

KEYWARDEN_DISABLE_EXEC=1을 설정하면 run을 완전히 제거하고 HTTP 프록시만 노출합니다.

세 가지 표면, 하나의 권한 부여 모델

동일한 볼트, 정책 엔진, 권한 부여, 감사 로그에 세 가지 방식으로 접근할 수 있습니다. 어떤 것을 사용하든 허용되는 작업은 동일합니다.

HTTP 표면은 MCP를 지원하지 않는 코드에서 keywarden을 사용할 수 있게 해주며, keywarden이 호출자를 구분할 수 있는 첫 번째 지점이기도 합니다:

keywarden apikey create ci-runner --ref 'openai/**' --http --audit --ttl 30d
keywarden serve --port 8787

curl -s http://127.0.0.1:8787/v1/proxy/openai%2Fprod \
  -H "Authorization: Bearer kw_live_..." \
  -H "content-type: application/json" \
  -d '{"method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o","messages":[]}}'

호출자는 openai/**로 범위가 지정된 keywarden 키를 보유하며, 부여된 기능만 수행할 수 있고 30일 후에 만료되며 한 번의 명령으로 취소할 수 있습니다. OpenAI 키는 절대 보유하지 않습니다. 경로: /v1/secrets, /v1/secrets/:ref, /v1/proxy/:ref, /v1/run, /v1/audit, /v1/usage, /v1/whoami, /healthz.

서버는 127.0.0.1에 바인딩되며 --allow-remote 없이는 라우팅 가능한 인터페이스를 거부합니다. 해당 포트에 접근할 수 있는 사람은 키가 커버하는 모든 자격 증명에 대한 권한 부여 오라클을 얻을 수 있기 때문입니다.

누가 무엇을 사용했고, 비용은 얼마인가

감사 로그의 모든 항목은 행위자를 명시하며, 행위자는 해시 안에 포함되어 있어 체인을 깨지 않고는 귀속을 다시 쓸 수 없습니다. 프록시된 모든 응답은 공급자가 보고한 토큰 수를 파싱합니다.

keywarden usage --since 7d

CREDENTIAL        CALLS          IN         OUT       TOTAL
openai/prod         142     418,220      96,410     514,630
anthropic/prod       38      92,004      31,887     123,891

ACTOR             CALLS          IN         OUT       TOTAL
http:ci-runner      118     356,900      74,220     431,120
mcp:mcp-client       62     153,324      54,077     207,401

keywarden은 토큰이 아닌 금액을 기록하지 않습니다. 가격은 변하고, 계약에 따라 다르며, 오래된 하드코딩된 요금은 재무 보고서에 잘못된 숫자를 만들어냅니다. run은 측정할 수 없습니다: 자격 증명이 하위 프로세스에 들어가면 keywarden은 토큰 수가 아닌 종료 코드만 볼 수 있습니다.

자격 증명을 사용하는 두 가지 방법

프록시는 HTTP API용입니다. 에이전트가 요청을 설명하면 keywarden이 자격 증명을 첨부하고 호출합니다. OpenAI, Anthropic, Stripe, GitHub, Slack, Cloudflare, Vercel, Supabase 및 헤더나 쿼리 매개변수로 인증하는 모든 API에서 작동합니다.

// what the agent sends
{ "ref": "openai/prod", "method": "POST", "url": "/v1/chat/completions", "body": { "model": "gpt-4o", "messages": [] } }

주입은 그 외의 모든 경우입니다. AWS는 SigV4 요청 서명이 필요하고, Postgres URL은 HTTP가 아니며, terraform apply는 실제 환경 변수를 원합니다. keywarden이 프로세스 자체를 생성합니다:

{ "command": "aws", "args": ["s3", "ls"], "inject": ["aws/prod"] }

하위 프로세스는 AWS_ACCESS_KEY_ID 등을 받습니다. 모델은 stdout을 받으며, 자격 증명이 나타나면 마스킹되어 나옵니다.

정책

~/.keywarden/policy.json은 어떤 자격 증명을, 어떤 기능으로, 무엇에 대해 사용할 수 있는지 결정합니다. 규칙은 위에서 아래로 평가되며, 첫 번째 일치가 우선하고, 기본값은 거부입니다.

{
  "version": 1,
  "default": "deny",
  "redactResponses": true,
  "rules": [
    {
      "ref": "openai/**",
      "http": { "allow": true, "methods": ["POST"], "paths": ["/v1/**"] },
      "exec": { "allow": false, "commands": [] },
      "rateLimitPerMinute": 30
    },
    {
      "ref": "aws/prod",
      "http": { "allow": false },
      "exec": { "allow": true, "commands": ["aws", "terraform"] },
      "rateLimitPerMinute": 10,
      "expiresAt": "2026-12-31T00:00:00.000Z"
    }
  ]
}

또는 CLI에서:

keywarden policy allow "openai/**" --http --path "/v1/**" --method POST
keywarden policy allow aws/prod --exec aws --exec terraform --arg-deny "s3://*"
keywarden policy test aws/prod exec terraform

*는 한 경로 세그먼트 내에서 일치하고, **는 세그먼트를 가로지릅니다. expiresAt은 규칙을 일시적으로 만듭니다.

명령어 이름을 지정하는 것만으로는 충분하지 않습니다. aws s3 ls에 대해 aws를 허용 목록에 추가하면 동일한 바이너리가 다른 사람이 소유한 버킷에 aws s3 cp를 수행할 수 있습니다. 이것이 MCP 위협 문헌이 계속 지적하는 시퀀스 수준의 격차입니다: 개별 호출은 모두 승인되지만 그 조합이 데이터 유출이 되는 것입니다. 따라서 규칙은 인수도 제한합니다:

"exec": {
  "allow": true,
  "commands": ["aws"],
  "argsDeny": ["s3://*", "--endpoint-url"],   // any match refuses the call
  "argsAllow": ["s3", "ls", "--region", "*"]  // if set, every argument must match
}

권한 부여: 일시적이고, 만료되며, 사용 횟수가 제한된 접근

정책은 상시 구성입니다. "에이전트가 지금 15분 동안 이 한 가지만 하게 해줘"라는 요구에는 적합하지 않습니다. 오늘날 이는 규칙을 넓혔다가 다시 좁히는 것을 잊는 것을 의미합니다.

권한 부여는 자체 제한 사항을 지니는 기능으로, macaroon 및 biscuit 계열에서 차용했으며 터미널에서 발급합니다:

keywarden grant aws/prod --exec aws --ttl 15m --uses 5 --arg-deny "s3://*"
keywarden grant openai/prod --http --path "/v1/chat/**" --method POST --ttl 1h --uses 20
keywarden grant list
keywarden grant revoke <id>

권한 부여는 자체적으로 만료되고, 사용 예산이 소진되면 소멸하며, 볼트에서 파생된 키로 HMAC되므로 수동으로 편집된 grants.json은 수락되지 않고 거부됩니다. 거부된 시도는 사용 횟수를 소모하지 않습니다.

정책 규칙에 "requireGrant": true를 설정하면 상시 구성이 필요하지만 충분하지는 않게 됩니다: 권한 부여를 발급하기 전에는 아무 일도 일어나지 않습니다. 이것이 stdio 서버 내부에서 대화형 프롬프트 없이 사람이 개입하는 승인 단계입니다.

구성 무결성

비밀을 암호화하는 것이 절반입니다. policy.json은 자격 증명을 사용할 수 있는지 여부를 결정하고 providers.json은 어디로 보낼지 결정합니다. 둘 다 일반 파일입니다. 단일 바이트도 해독할 수 없는 사람이라도 호스트가 자신의 것인 공급자를 추가하고 자격 증명을 그쪽으로 돌릴 수 있습니다.

따라서 볼트는 두 파일의 해시를 고정하고, 변경 사항을 확인하기 전에는 어느 쪽에도 작동하지 않습니다:

keywarden trust show    # what drifted
keywarden trust         # review, then pin the current contents

볼트 파일은 필드별이 아닌 전체가 MAC 처리됩니다. provider: "openai"를 다른 것으로 바꾸는 것은 암호문을 건드리지 않으므로 그렇지 않으면 정상적으로 검증되기 때문입니다.

keywarden이 실제로 강제하는 것

• 일반 텍스트 도구 없음. MCP 표면에는 자격 증명 값을 반환하는 코드 경로가 없습니다.

• 이그레스 허용 목록. 자격 증명은 공급자가 선언한 호스트와 정책에 추가한 호스트에만 보낼 수 있습니다. 키를 attacker.example에 POST하라는 프롬프트 주입은 네트워크에 닿기 전에 호스트 검사에서 실패합니다.

• HTTPS 전용, 리디렉션 미준수. 다른 오리진으로의 302는 Authorization 헤더를 오프호스트로 재전송하지 않습니다.

• SSRF 보호. 루프백, 사설 대역, CGNAT, 링크-로컬(169.254.169.254 클라우드 메타데이터 엔드포인트 포함)이 차단되며, 주소는 소켓이 실제로 사용하는 DNS 조회에서 검증되므로 DNS 리바인딩으로 우회할 수 없습니다.

• 셸 없음. run은 shell: false로 spawn에 argv 배열을 전달합니다. 주입할 메타문자 구문 분석이 없습니다.

• 구성된 하위 환경. 하위 프로세스는 상속된 변수의 허용 목록과 주입된 변수만 받습니다. 다른 비밀과 keywarden 자체 암호는 상속되지 않습니다.

• 출력 편집. 모든 도구 결과는 알려진 자격 증명 값, base64 및 URL 인코딩 형식, 약 12가지 잘 알려진 키 형태를 검사합니다. 일차적 통제 수단이 아닌 심층 방어입니다.

• 변조 방지 감사. 허용 또는 거부의 모든 결정은 해시 체인 로그에 추가됩니다. keywarden audit verify는 체인을 다시 계산하고 수정되거나 삭제된 첫 번째 항목을 보고합니다.

• 전체 파일 무결성. 볼트는 메타데이터를 포함하여 MAC 처리되므로 자격 증명을 감지되지 않고 다른 공급자로 돌릴 수 없습니다. policy.json과 providers.json은 볼트에 해시 고정되며 대역 외 변경 시 거부됩니다.

• 환경 강화. 서버는 NODE_TLS_REJECT_UNAUTHORIZED=0, NODE_OPTIONS 또는 SSLKEYLOGFILE이 설정된 경우 시작을 거부하고 NODE_EXTRA_CA_CERTS 및 HTTPS_PROXY에 대해 경고합니다. Claude Code에 대한 CVE-2026-21852는 Authorization 헤더가 포함된 아웃바운드 트래픽을 리디렉션한 환경 변수 하나였습니다. 자격 증부착이 작업인 프로세스는 요청 경로가 다른 사람의 통제 하에 있을 때 시작해서는 안 됩니다.

• 인수 제약. argsAllow / argsDeny는 허용 목록에 있는 명령의 호출을 좁힙니다. 바이너리만이 아니라요.

• 축소된 권한 부여. 만료되고, 사용 횟수가 제한되며, 운영자가 발급하고, 볼트 파생 MAC으로 위조를 방지합니다.

• 신뢰할 수 없는 데이터 프레이밍. 프록시된 응답 본문은 명명된 호스트의 신뢰할 수 없는 콘텐츠로 표시되므로 API 응답의 주입된 지시문이 모델에 데이터로 제시됩니다.

암호화

모두 node:crypto의 봉투 암호화로, 타사 암호화 라이브러리가 없습니다.

• 무작위 256비트 데이터 키가 각 필드를 AES-256-GCM으로 암호화하며, 자격 증명의 ref와 필드 이름을 추가 인증 데이터로 사용하므로 암호문을 볼트 항목 간에 이동할 수 없습니다.

• 데이터 키는 N=2^17, r=8의 scrypt로 암호문에서 파생된 키로 래핑되며, 약 128MiB와 시도당 약 1초가 소요됩니다. 이는 의도적입니다: 볼트 파일은 공격자가 가져가는 것이므로 오프라인 추측을 어렵게 만들어야 합니다.

• 암호를 교체하면 32바이트만 다시 래핑됩니다. 모든 비밀을 다시 암호화하지는 않습니다.

볼트 모드

--passphrase가 강력한 모드입니다. MCP 서버는 프롬프트 없이 잠금을 해제하려면 환경에 KEYWARDEN_PASSPHRASE가 필요합니다.

--keyfile은 무작위 키를 ~/.keywarden/masterkey에 기록하여 프롬프트가 필요 없게 합니다. 편리하지만 홈 디렉토리를 읽을 수 있는 사람은 누구나 볼트를 열 수 있다는 뜻입니다. 그럼에도 프로젝트 전체에 흩어져 있는 일반 텍스트 .env 파일보다 훨씬 낫습니다. 키가 한 곳에 있고, 사용이 정책으로 제어되며, 모든 사용이 기록되기 때문입니다. 어떤 트레이드오프를 선택했는지 알고 있어야 합니다. keywarden doctor가 상기시켜 줄 것입니다.

Windows에서는 파일 모드가 POSIX의 0600처럼 강제되지 않습니다. THREAT_MODEL.md를 참조하세요.

CLI

keywarden init --passphrase|--keyfile   create the vault
keywarden doctor                        check the install, flag weak settings
keywarden trust [show]                  re-pin policy.json + providers.json after reviewing a change
keywarden grant <ref> ...               issue a temporary, use-capped capability
keywarden grant list | revoke <id>
keywarden add <ref> --provider <id>     store a credential (prompts for each field)
keywarden list                          metadata only
keywarden describe <ref>                metadata plus how it can be used
keywarden reveal <ref>                  print plaintext, asks first, always audited
keywarden rm <ref> [--field f]          delete
keywarden exec <ref[,ref]> -- <cmd>     run a command with credentials injected
keywarden policy show|init|allow|deny|test
keywarden audit [tail|verify]
keywarden passphrase                    rotate
keywarden providers                     built-in presets
keywarden mcp-config                    print the MCP client config
keywarden doctor                        check the install, flag weak settings

사용자 지정 공급자

내장되지 않은 것은 ~/.keywarden/providers.json에 넣습니다. docs/PROVIDERS.md를 참조하세요.

{
  "acme": {
    "label": "Acme Internal API",
    "hosts": ["api.acme.internal", "*.acme.io"],
    "baseUrl": "https://api.acme.io",
    "fields": ["token", "tenant"],
    "required": ["token"],
    "auth": { "type": "header", "name": "X-Acme-Key", "template": "{{token}}" },
    "env": { "ACME_TOKEN": "{{token}}", "ACME_TENANT": "{{tenant}}" }
  }
}

keywarden이 보호하지 못하는 것

비용이 많이 드는 일에 신뢰하기 전에 THREAT_MODEL.md를 읽어보세요. 요약하자면:

• 에이전트가 다른 도구를 통해 임의의 로컬 명령을 실행할 수 있다면, 에이전트가 사용자의 vault 파일을 읽을 수 있습니다. 키파일 모드에서는 마스터 키도 읽을 수 있습니다. keywarden은 모델의 컨텍스트가 아닌 사용자의 디스크를 보호합니다.

• run은 실제 프로세스에 자격 증명을 제공합니다. 명령을 허용 목록에 추가할 때, 해당 명령이 환경 변수를 통해 자격 증명을 유출하도록 조작될 수 있다면, 자격 증명은 유출됩니다. 따라서 허용 목록은 좁게 유지하세요.

• redaction은 구멍이 많은 안전망입니다. API가 우리가 인식하지 못하는 방식으로 자격 증명을 반환하면, 자격 증명은 포착되지 않습니다.

• keywarden은 에이전트가 합법적으로 사용하도록 허용된 자격 증명으로 비용이 많이 들거나 파괴적인 작업을 수행하는 것을 막지 못합니다. 이를 위한 것은 정책 범위와 속도 제한입니다.

개발

npm install
npm run build
npm test          # 89 unit tests + 46 end-to-end checks against the real CLI, MCP and HTTP servers

e2e 스위트는 임시 KEYWARDEN_HOME에서 실제 바이너리를 구동하며, 어떤 도구 응답에도 자격 증명이 포함되어 있지 않은지 확인합니다.

참고 자료

• THREAT_MODEL.md — 범위에 포함되는 위협과, 의도적으로 범위에 포함하지 않는 위협

• docs/RESEARCH.md — 이 설계의 기반이 된 2026년 문헌, 채택된 내용과 검토 후 기각된 내용

• docs/COMPETITORS.md — 경쟁 제품들의 현황과, keywarden이 단순한 마케팅 차별화가 아닌 실질적으로 다른 점

• docs/TEAM.md — 다중 개발자 아키텍처: 신원 확인, 읽기 가능한 서버 없이 키 공유, 승인 워크플로, 비용 회계, 빌드 순서

• docs/PROVIDERS.md — 사용자 지정 공급자 작성 방법

호스팅

팀 vault, 브라우저 기반 관리, 기기 간 동기화가 필요한 사용자를 위한 호스팅 버전이 계획되어 있습니다. 동일한 제로 노출 보장을 제공합니다. 이 저장소의 모든 것은 MIT 라이선스로 유지되며, 호스팅 없이도 완전히 사용 가능합니다. docs/HOSTED.md를 참조하세요.

라이선스

MIT