mirrors/k-skill
2
0
Fork 0
mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00
Code Issues Projects Releases Packages Wiki Activity
k-skill/docs/security-and-secrets.md
Jeffrey (Dongkyu) Kim 397d0eea84 Expose official nearby fuel prices for location-based gas station lookups 
Add the first cheap-gas-nearby skill/package pair so nearby gas-price
queries can resolve a user-supplied location, translate it into Opinet's
KATEC search contract, and return the cheapest nearby stations with
address and facility detail. The docs and setup surfaces now advertise
the new skill and its Opinet API key requirement.

Constraint: Nearby fuel prices must come from the official KNOC Opinet API when available
Constraint: No new external dependencies were allowed for coordinate conversion or location resolution
Rejected: Map-only gas price scraping | official Opinet Open API exists and is the preferred source
Rejected: Require lat/lng input only | poorer UX than supporting landmark/station queries through anchor resolution
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep `OPINET_API_KEY` as the only supported official-price credential unless the repo adopts an Opinet proxy later
Tested: npm run ci; node --test packages/cheap-gas-nearby/test/index.test.js; offline fixture smoke via searchCheapGasStationsByLocationQuery('서울역', ...)
Not-tested: Live Opinet API call with a real `OPINET_API_KEY` (no non-placeholder key was configured locally)
Related: #54
2026-04-05 19:46:09 +09:00

3.9 KiB
Raw Blame History

Security And Secrets

k-skill은 필요한 환경변수 이름만 선언하고, 그 값을 어떻게 공급하느냐는 에이전트의 자유에 맡긴다.

Credential resolution order

모든 credential-bearing 스킬은 아래 우선순위를 따른다.

  1. 이미 환경변수에 있으면 그대로 사용한다.
  2. 에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.
  3. ~/.config/k-skill/secrets.env (기본 fallback) — plain dotenv 파일, 퍼미션 0600.
  4. 아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.

기본 경로에 저장하는 것은 fallback일 뿐, 강제가 아니다.

Default secrets file

  • 경로: ~/.config/k-skill/secrets.env
  • 형식: plain dotenv (KEY=value, 한 줄에 하나)
  • 퍼미션: 0600 (owner-only read/write)
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
LAW_OC=replace-me
DATA_GO_KR_API_KEY=replace-me
OPINET_API_KEY=replace-me
AIR_KOREA_OPEN_API_KEY=replace-me
KSKILL_PROXY_BASE_URL=https://your-proxy.example.com

서울 지하철 도착정보는 hosted public route rollout 이 끝나기 전까지 self-host 또는 배포 확인이 끝난 proxy URL 만 넣는다. 미세먼지만 hosted proxy 로 쓸 때는 이 값을 비워 두고 skill 기본값을 써도 된다.

Missing secret handling policy

인증이 필요한 스킬에서 필요한 값이 없으면 우회하지 않는다.

  • 어떤 값이 비어 있는지 정확한 환경변수 이름으로 사용자에게 알려준다
  • credential resolution order에 따라 확보한다
  • 대체 사이트, 대체 API, 하드코딩 같은 우회 경로를 찾지 않는다
  • 시크릿이 없다는 이유로 다른 서비스나 비공식 우회 수단을 자동 채택하지 않는다

Forbidden patterns

  • 실제 비밀값이 들어있는 파일을 git에 두기
  • 스킬 문서 안에 예시용 실비밀번호를 쓰기
  • 시크릿이 없다는 이유로 다른 서비스나 비공식 우회 수단을 자동 채택하기

Threat model

  • ~/.config/k-skill/secrets.env는 plain dotenv 파일이다
  • 파일 퍼미션 0600으로 같은 머신의 다른 유저로부터 보호한다
  • .gitignore로 git 노출을 방지한다
  • 에이전트는 이 파일을 읽고 쓸 수 있다 — 이것은 의도된 동작이다
  • OpenClaw/에이전트 환경에서 유저는 에이전트에게 credential을 위임하는 것을 전제로 사용한다

Standard variable names

  • KSKILL_SRT_ID
  • KSKILL_SRT_PASSWORD
  • KSKILL_KTX_ID
  • KSKILL_KTX_PASSWORD
  • LAW_OC
  • DATA_GO_KR_API_KEY
  • OPINET_API_KEY
  • AIR_KOREA_OPEN_API_KEY
  • KSKILL_PROXY_BASE_URL

LAW_OC 는 korean-law-mcp 가 법제처 Open API 를 호출할 때 쓰는 표준 변수명이다. 이 값은 로컬 CLI/로컬 MCP server 경로에서만 사용자 쪽에 필요하고, upstream remote MCP endpoint 예시는 사용자 LAW_OC 없이 url만 등록한다. DATA_GO_KR_API_KEY 는 upstream real-estate-mcp 의 로컬/stdio/self-host 경로에서 쓰는 표준 변수명이다. OPINET_API_KEY 는 한국석유공사 Opinet Open API 인증키로, 근처 가장 싼 주유소 찾기 skill/package 의 공식 nearby 가격 조회에 사용한다. public 공유용 Cloudflare Tunnel/Auth0/operator secret은 사용자 기본 secrets 파일에 넣지 않는다. 프록시 운영자 문맥에서는 upstream 환경변수 SEOUL_OPEN_API_KEY 도 사용할 수 있다. 다만 일반 사용자/client 쪽 기본 secrets 파일에는 넣지 않는다. KSKILL_PROXY_BASE_URL 도 서울 지하철 route가 실제 배포된 proxy URL 로만 넣는다.

이 레포의 credential-bearing skill은 전부 이 정책을 전제로 작성한다. 자세한 공통 설치 절차는 공통 설정 가이드를 본다.