다음 버전의 스킬 API 키 설정과 DPAPI 자격 증명 관리 #321

스킬별 API 키와 OAuth 자격 증명을 식탁보에서 등록하고 필요한 작업에만 제공하는 기능을 다음 버전의 개발 항목으로 추적합니다. 이번 스킬 마켓플레이스 구현에는 자격 증명 설정 기능을 포함하지 않습니다.

현재 마켓플레이스는 PR #320, 카탈로그 계약과 노출 범위는 TableClothCatalog PR #146에서 관리합니다. 초기 목록에는 official-report-skillset, bok-ecos-stats, kosis-stats, korean-law-mcp, korean-jangbu-for를 남깁니다. 외부 공유 서버나 별도 MCP 구성을 사용하는 항목의 실행 조건은 계속 안내합니다.

현재 동작과 개선 범위

전용 Codex 실행 환경은 환경 변수 허용 목록에서 API 키를 제외합니다. 사용자가 Windows 환경 변수 창에서 값을 등록해도 현재 실행 경로에서는 스킬에 전달하지 않습니다. 전용 Node.js와 Python 설치도 서비스 인증이나 스킬 실행 권한을 추가하지 않습니다.

API 키와 토큰은 식탁보 전용 로컬 저장소에서 Windows DPAPI DataProtectionScope.CurrentUser로 보호하는 방향으로 구현합니다. 공개 서비스 주소와 시간 제한 같은 일반 설정은 비밀값과 구분해 관리합니다.

DPAPI 선택 배경

Windows 사용자 또는 시스템 환경 변수에 API 키를 영구 등록하면 일반적으로 평문으로 보관하며 이후 실행하는 프로세스로 전달될 수 있습니다. 자식 프로세스는 기본적으로 부모의 환경 변수를 상속하므로 식탁보와 관계없는 실행 경로까지 키의 전달 범위가 넓어질 수 있습니다. 일반 설정 파일이나 .env 파일로 옮겨도 저장 중 암호화와 작업별 전달 통제는 별도로 구현합니다. 환경 변수의 평문 저장, 프로세스 환경 상속

식탁보는 Windows 데스크톱 앱이므로 Windows가 사용자 로그온 자격 증명에 연결해 암호화 키를 관리하는 DPAPI를 사용할 수 있습니다. CurrentUser 범위로 보호하면 앱에 공통 복호화 키를 내장하거나 별도의 키 관리 서버를 운영하지 않고 사용자별 로컬 암호문 저장소를 구성할 수 있습니다. LocalMachine 범위는 같은 컴퓨터의 다른 계정도 복호화할 수 있으므로 개인 API 키 저장의 기본값으로 사용하지 않습니다. Windows DPAPI의 보호 범위와 키 관리

기대 효과

• 저장 중 노출 감소: 앱 전용 파일에는 암호문만 남겨 일반 설정 파일, 소스, 환경 변수 설정과 진단 자료에 평문 키를 보관하는 경로를 줄입니다. 암호문 파일의 접근 권한도 함께 제한합니다.
• 사용자별 보호: Windows 사용자 자격 증명에 복호화를 연결하고 다른 계정으로 암호문 파일만 복사해 키를 사용하는 위험을 줄입니다. 사용자 프로필과 DPAPI 복구 환경에 의존하므로 다른 PC로의 파일 복사만으로 복원을 보장하지 않습니다.
• 작업별 전달 통제: 앱이 승인한 서비스와 작업을 확인한 뒤 필요한 키만 복호화합니다. API 어댑터가 키를 보유하거나 해당 작업 프로세스에만 전달해 전체 Codex 환경과 다른 스킬로의 불필요한 상속을 줄입니다. 이 효과는 DPAPI 저장과 별도의 실행 및 전달 정책을 함께 구현할 때 성립합니다.
• 앱 안에서의 수명 관리: 등록 여부, 연결 확인, 교체, 사용 권한 해제와 삭제를 한 화면에서 관리하고 변경한 키는 다음 작업부터 적용합니다. 복호화 실패 시 재등록으로 복구하며 발급처에서의 회전과 폐기는 별도로 안내합니다.

DPAPI는 저장 중 보호를 담당합니다. 키를 사용하는 동안의 평문 메모리, 승인한 코드의 외부 전송, 같은 Windows 계정의 악성 프로세스와 관리자 권한 탈취까지 차단하지는 않습니다. 따라서 DPAPI만으로 임의 스킬을 신뢰하거나 실행 격리를 보장하지 않으며 아래 구현 범위와 수용 조건을 함께 검증합니다.

구현 범위

• 설치된 스킬 상세의 연결 설정에서 필요한 자격 증명의 이름, 용도와 발급처를 안내하고 등록, 연결 테스트, 교체와 삭제를 제공합니다.
• 실제 키를 채팅으로 입력받지 않습니다. 화면과 AI에는 등록 여부와 오류 상태만 제공하며 비밀값을 로그, 진단, 명령행, 카탈로그, 일반 설정 파일이나 Sandbox 공유 폴더에 남기지 않습니다.
• 앱 전용 경로에 암호문만 저장하고 사용자별 파일 접근 권한과 원자적 저장을 적용합니다. 전역 환경 변수, 전역 PATH와 사용자 전역 Codex 설정은 변경하지 않습니다.
• 실행에 필요한 시점에만 복호화합니다. 앱이 관리하는 API 어댑터가 키를 보유하는 방식을 우선 검토하고 외부 실행에 키가 필요한 경우 승인한 작업 프로세스에 해당 키만 전달합니다. 전체 Codex 부모 프로세스에 모든 키를 일괄 제공하지 않습니다.
• 서비스와 스킬의 출처 및 원본 버전에 자격 증명 사용 승인을 연결합니다. 출처, 실행 코드, 의존 패키지 또는 요구 권한이 바뀌는 업데이트에서는 기존 승인을 재검토합니다. npx 등으로 실행 중 내려받는 패키지도 정확한 버전과 integrity를 고정하거나 앱 소유 API 어댑터로 대체합니다. 설치한 SKILL.md의 커밋만으로 실제 실행 코드의 고정을 보장하지 않습니다.
• 스킬 제거 시 사용 권한을 해제합니다. 여러 스킬이 공유하는 자격 증명의 보존과 삭제를 구분하고 사용 중인 작업의 종료 및 교체 정책을 제공합니다.
• 복호화 실패 시 재등록으로 복구합니다. 평문, LocalMachine 또는 시스템 환경 변수로 자동 전환하지 않습니다. 로컬 삭제와 발급처의 키 폐기 및 회전을 구분해 안내합니다.

수용 조건

• 누락, 등록 완료, 잘못된 키, 연결 실패와 복호화 실패 상태를 UI에서 구분할 수 있습니다.
• 등록, 교체와 삭제를 다시 시작한 앱에서도 검증하며 취소나 저장 실패 시 기존 값을 보존합니다.
• 승인한 서비스와 작업에만 키를 제공하고 다른 스킬 또는 전체 Codex 환경으로 전달하지 않는지 합성 비밀값으로 검사합니다.
• 프롬프트, 오류 메시지, 로그, 진단과 프로세스 인자에 비밀값이 포함되지 않는지 검사합니다.
• 업데이트, 로컬 파일 변경, 의존 패키지 변경, 스킬 비활성화 및 제거와 실행 취소에 따른 자격 증명 사용 권한과 작업 수명을 검증합니다.
• Windows x64와 ARM64 및 Native AOT 배포에서 저장, 복호화와 복구 경로를 검증합니다.
• API 키 관리와 별개로 필요한 스킬 실행 권한과 MCP 또는 API 어댑터 연결을 실제 서비스별로 검증합니다.

보호 범위

DPAPI CurrentUser는 저장 중 보호를 제공하며 같은 Windows 계정으로 실행하는 악성 코드와 임의 스킬을 격리하지는 않습니다. 프로세스별 환경 변수 전달도 별도의 OS 격리 경계를 대신하지 않습니다. 암호문 파일 복사만으로 다른 환경에서 복구할 수 있다고 보장하지 않으며 재등록 경로를 제공합니다.

설계 근거: Windows DPAPI, 환경 변수 상속.