chamelion-vault 0.1.0__tar.gz

chamelion_vault-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.env
+.env.*
+!.env.example
+
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+data/
+*.log
+
+.DS_Store
+
+# 클라이언트 배포물 — 만들 때마다 생긴다. 저장소에 두지 않는다.
+clients/python/dist/
+clients/python/uv.lock

chamelion_vault-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: chamelion-vault
+Version: 0.1.0
+Summary: Client for a self-hosted chamelion vault gateway
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<!-- ⚠️ 이 파일은 PyPI 설명란에 그대로 실린다 — 전 세계에 공개된다.
+     볼트 주소·DDNS·포트·조직 이름·실제 시크릿 경로를 적지 않는다.
+     예시는 언제나 명백한 가짜(`myproject/dev/EXAMPLE_KEY`)로 쓴다.
+     저장소의 `tests/test_client_package.py` 가 이 규칙을 검사한다. -->
+
+# chamelion-vault
+
+자체 호스팅 chamelion vault 게이트웨이에서 **시크릿 값을 받아 오는 클라이언트**입니다.
+
+- **의존성이 없습니다.** 표준 라이브러리만 씁니다.
+- **값을 디스크에 쓰지 않고 캐시하지 않습니다.** 받은 값은 프로세스 메모리에만 있습니다.
+- **로깅을 설정하지 않습니다.** 이 패키지는 여러분의 애플리케이션 안에서 돕니다.
+
+> 이 패키지는 **볼트를 운영하는 조직의 구성원**을 위한 것입니다. 볼트 주소·머신 API 키·
+> 터널 접속 정보는 여기 없고 사내 문서에 있습니다. 그것을 모르면 설치까지는 되지만
+> 값을 받는 단계에서 막히는 것이 정상입니다.
+
+## 설치
+
+```bash
+pip install chamelion-vault
+```
+
+## 쓰는 법
+
+```python
+from chamelion_vault import get_secret
+
+secret = get_secret("myproject", "dev", "EXAMPLE_KEY")
+api_key = secret["value"].get_secret_value()
+```
+
+값이 하나뿐인 시크릿은 `["value"]` 에 있습니다. 한 몸인 크리덴셜을 한 경로에 여러
+필드로 둔 것을 **번들**이라 부르고, 그때는 필드가 여럿입니다.
+
+```python
+secret = get_secret("myproject", "dev", "EXAMPLE_BUNDLE")
+sorted(secret)                                  # ['access_key', 'secret_key']
+secret["access_key"].get_secret_value()
+```
+
+프로젝트·환경이 같고 이름만 여럿이면 한 번에 받을 수 있습니다. **요청은 건별로 나가고**,
+하나라도 실패하면 전부 실패로 끝납니다 — 반쪽짜리 설정으로 애플리케이션이 뜨는 것보다
+뜨지 않는 편이 낫기 때문입니다.
+
+```python
+from chamelion_vault import get_secrets
+
+secrets = get_secrets("myproject", "dev", ["EXAMPLE_KEY", "EXAMPLE_DB_URL"])
+secrets["EXAMPLE_KEY"]["value"].get_secret_value()
+```
+
+### 값이 상자에 담겨 옵니다
+
+`get_secret_value()` 로 열기 전까지 값은 어디에도 그대로 나타나지 않습니다.
+
+```python
+print(secret)             # Secret(myproject/dev/EXAMPLE_KEY, fields=['value'])
+print(secret["value"])    # <REDACTED>
+```
+
+무심코 남긴 로그 한 줄에 진짜 키가 찍히는 것을 막습니다. **연 뒤에는 막아 주지 않으니**
+꺼낸 값은 바로 쓰고 변수에 오래 들고 있지 마세요.
+
+## 설정 — 환경변수 둘
+
+| 환경변수 | 뜻 | 기본값 |
+|---|---|---|
+| `CHAMELION_VAULT_KEY` | 머신 API 키 | 없음 (필수) |
+| `CHAMELION_VAULT_URL` | 게이트웨이 주소 | `http://127.0.0.1:8081` |
+
+**설정 파일은 지원하지 않습니다.** 파일을 읽게 만들면 거기에 키를 적게 되고, 그 파일은
+언젠가 저장소에 들어갑니다. 키를 인자로 받는 함수도 두지 않았습니다 — 같은 이유입니다.
+
+머신 API 키는 Slack 에서 받습니다.
+
+```
+/vault machine
+```
+
+관리자 승인 뒤 **한 번만** 표시됩니다. 잃어버리면 다시 요청하세요.
+
+## 터널
+
+게이트웨이는 볼트 호스트의 **루프백에만** 열려 있습니다. 밖에서 값을 받으려면 그
+루프백까지 가는 SSH 터널이 필요하고, **이 패키지는 터널을 대신 띄우지 않습니다.**
+프로세스 수명·키 경로·OS 차이가 전부 따라 들어와, 실패했을 때 터널 문제인지 조회
+문제인지 구분이 안 되기 때문입니다.
+
+`~/.ssh/config` 에 한 번 적어 두면 그 뒤로는 한 줄입니다.
+
+```
+Host vault-tunnel
+    HostName <볼트 호스트>
+    Port <SSH 포트>
+    User <계정>
+    IdentityFile ~/.ssh/<터널 키>
+    IdentitiesOnly yes
+    LocalForward 8081 127.0.0.1:8081
+```
+
+```bash
+ssh -N vault-tunnel
+```
+
+> ⚠️ **`IdentitiesOnly yes` 를 빠뜨리지 마세요.** 이것이 없으면 기본 키(`~/.ssh/id_*`)가
+> 먼저 인증을 시도해, 터널 키에 걸어 둔 제약이 통째로 비껴갑니다. 실패 원인을 찾기
+> 가장 어려운 자리입니다.
+
+`<볼트 호스트>`·`<SSH 포트>`·`<계정>`·`<터널 키>` 는 사내 터널 문서에 있습니다.
+
+## 값을 받지 못했을 때
+
+볼트는 **실패 원인을 알려주지 않습니다.** 키가 틀렸는지·권한이 없는지·그런 시크릿이
+없는지를 응답으로 가르면 그것이 곧 남의 볼트를 훑는 도구가 되기 때문입니다. 그래서
+이 패키지도 추측하지 않고, 대신 확실히 아는 것만 말합니다.
+
+| 예외 | 뜻 | 할 일 |
+|---|---|---|
+| `MissingApiKeyError` | 환경변수가 비었다 | `/vault machine` 으로 키를 받는다 |
+| `VaultUnreachableError` | 연결 자체가 안 됐다 | 터널이 떠 있는지 본다 |
+| `SecretUnavailableError` | 볼트가 값을 주지 않았다 | 아래 셋을 순서대로 확인한다 |
+| `UnexpectedResponseError` | 계약에 없는 응답이 왔다 | 주소가 정말 게이트웨이인지 확인한다 |
+
+`SecretUnavailableError` 의 원인은 셋입니다.
+
+1. **접근 그룹** — 그 시크릿에 접근 그룹이 지정돼 있지 않으면 머신은 값을 받지
+   못합니다. **가장 흔한 원인**이니 소유자에게 먼저 확인하세요.
+2. **머신 키** — 아직 승인 전이거나 폐기됐을 수 있습니다.
+3. **경로** — 프로젝트·환경·이름 중 하나가 틀렸을 수 있습니다.
+
+네 예외는 모두 `VaultError` 를 상속하므로 한 번에 잡을 수 있습니다.
+
+```python
+from chamelion_vault import VaultError
+
+try:
+    secret = get_secret("myproject", "dev", "EXAMPLE_KEY")
+except VaultError as error:
+    print(error)   # 무엇을 해야 하는지가 메시지에 들어 있습니다
+```
+
+## 받을 수 없는 것
+
+- **개인 등급 시크릿.** 소유자 본인만 Slack 으로 받습니다. 머신에게는 열리지 않고,
+  관리자도 값을 볼 수 없습니다. 코드에서 써야 하는 값이라면 개인 등급으로 두면 안 됩니다.
+- **프로젝트에 딸린 시크릿 목록.** 게이트웨이는 이름을 알고 있는 시크릿 한 건을 줄 뿐,
+  "이 프로젝트에 무엇이 있는지" 는 알려주지 않습니다. 목록은 Slack 에서 봅니다.

chamelion_vault-0.1.0/README.md

@@ -0,0 +1,148 @@
+<!-- ⚠️ 이 파일은 PyPI 설명란에 그대로 실린다 — 전 세계에 공개된다.
+     볼트 주소·DDNS·포트·조직 이름·실제 시크릿 경로를 적지 않는다.
+     예시는 언제나 명백한 가짜(`myproject/dev/EXAMPLE_KEY`)로 쓴다.
+     저장소의 `tests/test_client_package.py` 가 이 규칙을 검사한다. -->
+
+# chamelion-vault
+
+자체 호스팅 chamelion vault 게이트웨이에서 **시크릿 값을 받아 오는 클라이언트**입니다.
+
+- **의존성이 없습니다.** 표준 라이브러리만 씁니다.
+- **값을 디스크에 쓰지 않고 캐시하지 않습니다.** 받은 값은 프로세스 메모리에만 있습니다.
+- **로깅을 설정하지 않습니다.** 이 패키지는 여러분의 애플리케이션 안에서 돕니다.
+
+> 이 패키지는 **볼트를 운영하는 조직의 구성원**을 위한 것입니다. 볼트 주소·머신 API 키·
+> 터널 접속 정보는 여기 없고 사내 문서에 있습니다. 그것을 모르면 설치까지는 되지만
+> 값을 받는 단계에서 막히는 것이 정상입니다.
+
+## 설치
+
+```bash
+pip install chamelion-vault
+```
+
+## 쓰는 법
+
+```python
+from chamelion_vault import get_secret
+
+secret = get_secret("myproject", "dev", "EXAMPLE_KEY")
+api_key = secret["value"].get_secret_value()
+```
+
+값이 하나뿐인 시크릿은 `["value"]` 에 있습니다. 한 몸인 크리덴셜을 한 경로에 여러
+필드로 둔 것을 **번들**이라 부르고, 그때는 필드가 여럿입니다.
+
+```python
+secret = get_secret("myproject", "dev", "EXAMPLE_BUNDLE")
+sorted(secret)                                  # ['access_key', 'secret_key']
+secret["access_key"].get_secret_value()
+```
+
+프로젝트·환경이 같고 이름만 여럿이면 한 번에 받을 수 있습니다. **요청은 건별로 나가고**,
+하나라도 실패하면 전부 실패로 끝납니다 — 반쪽짜리 설정으로 애플리케이션이 뜨는 것보다
+뜨지 않는 편이 낫기 때문입니다.
+
+```python
+from chamelion_vault import get_secrets
+
+secrets = get_secrets("myproject", "dev", ["EXAMPLE_KEY", "EXAMPLE_DB_URL"])
+secrets["EXAMPLE_KEY"]["value"].get_secret_value()
+```
+
+### 값이 상자에 담겨 옵니다
+
+`get_secret_value()` 로 열기 전까지 값은 어디에도 그대로 나타나지 않습니다.
+
+```python
+print(secret)             # Secret(myproject/dev/EXAMPLE_KEY, fields=['value'])
+print(secret["value"])    # <REDACTED>
+```
+
+무심코 남긴 로그 한 줄에 진짜 키가 찍히는 것을 막습니다. **연 뒤에는 막아 주지 않으니**
+꺼낸 값은 바로 쓰고 변수에 오래 들고 있지 마세요.
+
+## 설정 — 환경변수 둘
+
+| 환경변수 | 뜻 | 기본값 |
+|---|---|---|
+| `CHAMELION_VAULT_KEY` | 머신 API 키 | 없음 (필수) |
+| `CHAMELION_VAULT_URL` | 게이트웨이 주소 | `http://127.0.0.1:8081` |
+
+**설정 파일은 지원하지 않습니다.** 파일을 읽게 만들면 거기에 키를 적게 되고, 그 파일은
+언젠가 저장소에 들어갑니다. 키를 인자로 받는 함수도 두지 않았습니다 — 같은 이유입니다.
+
+머신 API 키는 Slack 에서 받습니다.
+
+```
+/vault machine
+```
+
+관리자 승인 뒤 **한 번만** 표시됩니다. 잃어버리면 다시 요청하세요.
+
+## 터널
+
+게이트웨이는 볼트 호스트의 **루프백에만** 열려 있습니다. 밖에서 값을 받으려면 그
+루프백까지 가는 SSH 터널이 필요하고, **이 패키지는 터널을 대신 띄우지 않습니다.**
+프로세스 수명·키 경로·OS 차이가 전부 따라 들어와, 실패했을 때 터널 문제인지 조회
+문제인지 구분이 안 되기 때문입니다.
+
+`~/.ssh/config` 에 한 번 적어 두면 그 뒤로는 한 줄입니다.
+
+```
+Host vault-tunnel
+    HostName <볼트 호스트>
+    Port <SSH 포트>
+    User <계정>
+    IdentityFile ~/.ssh/<터널 키>
+    IdentitiesOnly yes
+    LocalForward 8081 127.0.0.1:8081
+```
+
+```bash
+ssh -N vault-tunnel
+```
+
+> ⚠️ **`IdentitiesOnly yes` 를 빠뜨리지 마세요.** 이것이 없으면 기본 키(`~/.ssh/id_*`)가
+> 먼저 인증을 시도해, 터널 키에 걸어 둔 제약이 통째로 비껴갑니다. 실패 원인을 찾기
+> 가장 어려운 자리입니다.
+
+`<볼트 호스트>`·`<SSH 포트>`·`<계정>`·`<터널 키>` 는 사내 터널 문서에 있습니다.
+
+## 값을 받지 못했을 때
+
+볼트는 **실패 원인을 알려주지 않습니다.** 키가 틀렸는지·권한이 없는지·그런 시크릿이
+없는지를 응답으로 가르면 그것이 곧 남의 볼트를 훑는 도구가 되기 때문입니다. 그래서
+이 패키지도 추측하지 않고, 대신 확실히 아는 것만 말합니다.
+
+| 예외 | 뜻 | 할 일 |
+|---|---|---|
+| `MissingApiKeyError` | 환경변수가 비었다 | `/vault machine` 으로 키를 받는다 |
+| `VaultUnreachableError` | 연결 자체가 안 됐다 | 터널이 떠 있는지 본다 |
+| `SecretUnavailableError` | 볼트가 값을 주지 않았다 | 아래 셋을 순서대로 확인한다 |
+| `UnexpectedResponseError` | 계약에 없는 응답이 왔다 | 주소가 정말 게이트웨이인지 확인한다 |
+
+`SecretUnavailableError` 의 원인은 셋입니다.
+
+1. **접근 그룹** — 그 시크릿에 접근 그룹이 지정돼 있지 않으면 머신은 값을 받지
+   못합니다. **가장 흔한 원인**이니 소유자에게 먼저 확인하세요.
+2. **머신 키** — 아직 승인 전이거나 폐기됐을 수 있습니다.
+3. **경로** — 프로젝트·환경·이름 중 하나가 틀렸을 수 있습니다.
+
+네 예외는 모두 `VaultError` 를 상속하므로 한 번에 잡을 수 있습니다.
+
+```python
+from chamelion_vault import VaultError
+
+try:
+    secret = get_secret("myproject", "dev", "EXAMPLE_KEY")
+except VaultError as error:
+    print(error)   # 무엇을 해야 하는지가 메시지에 들어 있습니다
+```
+
+## 받을 수 없는 것
+
+- **개인 등급 시크릿.** 소유자 본인만 Slack 으로 받습니다. 머신에게는 열리지 않고,
+  관리자도 값을 볼 수 없습니다. 코드에서 써야 하는 값이라면 개인 등급으로 두면 안 됩니다.
+- **프로젝트에 딸린 시크릿 목록.** 게이트웨이는 이름을 알고 있는 시크릿 한 건을 줄 뿐,
+  "이 프로젝트에 무엇이 있는지" 는 알려주지 않습니다. 목록은 Slack 에서 봅니다.

chamelion_vault-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+# ⚠️ 이 파일은 PyPI 에 그대로 실린다. 볼트 주소·조직·저장소 URL 을 적지 않는다.
+#    (저장소 URL 은 조직 이름을 드러낸다 — 사내 설치 방법은 사내 문서에 있다.)
+[project]
+name = "chamelion-vault"
+version = "0.1.0"
+description = "Client for a self-hosted chamelion vault gateway"
+readme = "README.md"
+# 개발자 노트북에서 돈다. 서버(3.12+)와 달리 넓게 잡는다 — 받는 쪽 프로젝트의
+# 파이썬을 우리가 고르지 않는다.
+requires-python = ">=3.10"
+# 의존성 0 (D33). `GET` 하나에 헤더 하나라 표준 라이브러리로 끝난다.
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chamelion_vault"]
+
+# 배포물에 소스와 README 만 담는다. 테스트는 저장소 루트의 `tests/` 에 있다 —
+# 공개물 검사(금칙어 목록)가 그 안에 있어서, 함께 실으면 검사 대상이 곧 유출이 된다.
+[tool.hatch.build.targets.sdist]
+include = ["src/chamelion_vault", "README.md"]
+# ⚠️ hatchling 은 저장소의 `.gitignore` 를 sdist 에 **강제로** 담는다(`exclude` 로도
+#    빠지지 않는다). 우리 것은 일반적인 개발 무시 목록뿐이라 그대로 두되, 검사에서
+#    빠지지 않게 `tests/test_client_package.py` 가 배포물의 **모든** 파일을 훑는다.

chamelion_vault-0.1.0/src/chamelion_vault/__init__.py

@@ -0,0 +1,42 @@
+"""chamelion vault — 머신 조회 클라이언트.
+
+```python
+from chamelion_vault import get_secret
+
+secret = get_secret("myproject", "dev", "EXAMPLE_KEY")
+api_key = secret["value"].get_secret_value()
+```
+
+**이 패키지는 서버 코드를 import 하지 않는다.** 같은 저장소에 있지만 다른 프로그램이고
+남의 노트북에서 돈다 — 서버 타입을 가져다 쓰면 그 의존성(sqlalchemy·hvac)이 개발자의
+프로젝트에 함께 설치된다. 공유하는 것은 코드가 아니라 **계약**이다.
+"""
+
+from __future__ import annotations
+
+from ._client import DEFAULT_URL, get_secret, get_secrets
+from ._errors import (
+    KEY_ENV,
+    URL_ENV,
+    MissingApiKeyError,
+    SecretUnavailableError,
+    UnexpectedResponseError,
+    VaultError,
+    VaultUnreachableError,
+)
+from ._secret import Secret, SecretStr
+
+__all__ = [
+    "DEFAULT_URL",
+    "KEY_ENV",
+    "URL_ENV",
+    "MissingApiKeyError",
+    "Secret",
+    "SecretStr",
+    "SecretUnavailableError",
+    "UnexpectedResponseError",
+    "VaultError",
+    "VaultUnreachableError",
+    "get_secret",
+    "get_secrets",
+]

chamelion_vault-0.1.0/src/chamelion_vault/_client.py

@@ -0,0 +1,167 @@
+"""값을 받아 오는 길 — `GET` 하나에 헤더 하나다.
+
+```
+환경변수에서 키·주소 → GET /v1/secrets/{project}/{secret_env}/{name}
+  → JSON 파싱 → SecretStr 로 감싸 반환
+```
+
+**의존성이 없다.** 표준 라이브러리 `urllib.request` 로 끝난다 — 타임아웃도 재시도도
+그것으로 되고, 사내 배포에서 의존성 0 이 가장 싸다(버전 충돌이 없다).
+
+**값을 파일에 쓰지 않고 캐시하지 않는다.** 같은 값을 두 번 받으면 두 번 요청한다.
+
+**로거를 만들지 않는다.** 이 패키지는 남의 애플리케이션 안에서 돈다 — 우리가 로깅을
+설정하면 그 앱의 설정을 덮어쓴다. 값이 새는 것을 막는 가장 확실한 방법이기도 하다.
+
+원인 예외를 `from None` 으로 끊는다. `urllib` 의 프레임을 그대로 달고 올라가면
+요청 객체(헤더에 키가 들어 있다)가 트레이스백의 지역 변수로 노출될 수 있다.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from collections.abc import Iterable
+from typing import Any
+from urllib.parse import quote
+
+from ._errors import (
+    KEY_ENV,
+    URL_ENV,
+    MissingApiKeyError,
+    SecretUnavailableError,
+    UnexpectedResponseError,
+    VaultUnreachableError,
+)
+from ._secret import Secret, SecretStr
+
+DEFAULT_URL = "http://127.0.0.1:8081"
+"""기본 주소 — **터널의 로컬 종단**이다. 볼트 호스트의 주소가 아니다.
+
+터널을 쓰는 사람이 아무것도 설정하지 않아도 되게 하는 값이고, 이 주소로 나간 요청은
+`ssh -L` 이 만든 통로가 없으면 아무 데도 닿지 않는다.
+"""
+
+API_KEY_HEADER = "X-API-Key"
+"""자격증명은 헤더로만 보낸다. URL 에 넣으면 셸 히스토리·프록시 로그에 원문이 남는다."""
+
+TIMEOUT_SECONDS = 10.0
+"""터널을 한 번 왕복하기에 충분하고, 터널이 죽었을 때 오래 매달리지 않는 구간."""
+
+_SECRET_ROUTE = "/v1/secrets"
+
+
+def get_secret(project: str, secret_env: str, name: str) -> Secret:
+    """시크릿 1건을 받는다. **값은 `SecretStr` 로 감싸여 온다.**
+
+    Args:
+        project: 프로젝트 이름.
+        secret_env: 시크릿 환경 (`local`·`dev`·`staging`·`prod`).
+        name: 시크릿 이름.
+
+    Returns:
+        경로와 필드를 담은 `Secret`. 값 하나짜리 시크릿은 `["value"]` 에 있다.
+
+    Raises:
+        MissingApiKeyError: 환경변수에 머신 API 키가 없는 경우.
+        VaultUnreachableError: 게이트웨이에 연결하지 못한 경우(대개 터널이 없다).
+        SecretUnavailableError: 서버가 값을 주지 않은 경우. **원인은 알 수 없다.**
+        UnexpectedResponseError: 계약에 없는 응답이 온 경우.
+    """
+    base = os.environ.get(URL_ENV, "").strip() or DEFAULT_URL
+    key = os.environ.get(KEY_ENV, "").strip()
+    if not key:
+        raise MissingApiKeyError()
+
+    path = _join(project, secret_env, name)
+    url = f"{base.rstrip('/')}{_SECRET_ROUTE}/{path}"
+    payload = _fetch(url=url, key=key, path=path)
+    return _to_secret(url=url, payload=payload, fallback_path=path)
+
+
+def get_secrets(project: str, secret_env: str, names: Iterable[str]) -> dict[str, Secret]:
+    """같은 프로젝트·환경의 시크릿 여러 건을 받는다.
+
+    **서버 계약은 경로 하나에 요청 하나다.** 이 함수는 그 요청을 순서대로 반복할 뿐이고,
+    감사 로그에도 건별로 남는다. 하나라도 실패하면 **전부 실패로 끝낸다** — 반쪽짜리
+    설정으로 애플리케이션이 뜨는 것보다 뜨지 않는 것이 낫다.
+
+    Args:
+        project: 프로젝트 이름.
+        secret_env: 시크릿 환경.
+        names: 받을 시크릿 이름들.
+
+    Returns:
+        시크릿 이름 → `Secret`.
+
+    Raises:
+        MissingApiKeyError: 환경변수에 머신 API 키가 없는 경우.
+        VaultUnreachableError: 게이트웨이에 연결하지 못한 경우.
+        SecretUnavailableError: 한 건이라도 값을 받지 못한 경우.
+        UnexpectedResponseError: 계약에 없는 응답이 온 경우.
+    """
+    return {name: get_secret(project, secret_env, name) for name in names}
+
+
+def _join(project: str, secret_env: str, name: str) -> str:
+    """경로 세그먼트 셋을 잇는다. 값을 다루지 않는다.
+
+    Raises:
+        ValueError: 세그먼트가 비어 있는 경우.
+    """
+    segments = (project, secret_env, name)
+    if not all(segment.strip() for segment in segments):
+        raise ValueError("프로젝트·환경·이름은 모두 있어야 합니다")
+    return "/".join(quote(segment.strip(), safe="") for segment in segments)
+
+
+def _fetch(*, url: str, key: str, path: str) -> Any:
+    """요청 한 번을 보내고 본문을 파싱한다. **본문을 로깅하지 않는다.**
+
+    Raises:
+        VaultUnreachableError: 연결·타임아웃 실패.
+        SecretUnavailableError: `404`.
+        UnexpectedResponseError: 그 밖의 응답이거나 본문이 JSON 이 아닌 경우.
+    """
+    request = urllib.request.Request(url, headers={API_KEY_HEADER: key}, method="GET")
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+            body = response.read()
+    except urllib.error.HTTPError as error:
+        status = error.code
+        error.close()
+        if status == 404:
+            raise SecretUnavailableError(path=path) from None
+        raise UnexpectedResponseError(url=url, detail=f"HTTP {status}") from None
+    except (urllib.error.URLError, TimeoutError, OSError):
+        raise VaultUnreachableError(url=url) from None
+
+    try:
+        return json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        # 본문을 오류에 담지 않는다 — 그 본문이 값일 수 있다.
+        raise UnexpectedResponseError(url=url, detail="본문이 JSON 이 아닙니다") from None
+
+
+def _to_secret(*, url: str, payload: Any, fallback_path: str) -> Secret:
+    """계약대로 온 본문을 `Secret` 으로 옮긴다. 여기서 값이 상자에 들어간다.
+
+    Raises:
+        UnexpectedResponseError: 본문 모양이 계약과 다른 경우.
+    """
+    if not isinstance(payload, dict):
+        raise UnexpectedResponseError(url=url, detail="본문이 객체가 아닙니다")
+
+    fields = payload.get("fields")
+    if not isinstance(fields, dict) or not fields:
+        raise UnexpectedResponseError(url=url, detail="본문에 fields 가 없습니다")
+    if not all(isinstance(value, str) for value in fields.values()):
+        raise UnexpectedResponseError(url=url, detail="fields 값이 문자열이 아닙니다")
+
+    path = payload.get("path")
+    return Secret(
+        path=path if isinstance(path, str) else fallback_path,
+        fields={name: SecretStr(value) for name, value in fields.items()},
+    )

chamelion_vault-0.1.0/src/chamelion_vault/_errors.py

@@ -0,0 +1,88 @@
+"""오류 — 개발자가 **다음에 무엇을 해야 하는지**를 담는다.
+
+서버는 실패 원인을 알려주지 않는다. 키가 틀렸는가·권한이 없는가·그 시크릿이 없는가를
+응답으로 가르면 그것이 곧 탐색 도구가 되기 때문이다. 그래서 이 파일은 **추측하지
+않는다** — 대신 클라이언트가 확실히 아는 것(어디까지 갔는가)으로 셋을 가른다.
+
+| 실패 | 아는 것 | 문안이 하는 일 |
+|---|---|---|
+| 연결 자체가 안 됨 | 터널이 없다 | `ssh` 명령을 그대로 보여준다 |
+| 환경변수가 비었다 | 키가 없다 | 어디서 받는지 알려준다 |
+| `404` | 그 이상 모른다 | 가능한 원인 셋을 나열한다 |
+
+**예외 메시지에 값도 키도 넣지 않는다.** 밖으로 나가는 것은 경로·환경변수 이름·
+설정된 주소뿐이고, 셋 다 비밀이 아니다.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+KEY_ENV = "CHAMELION_VAULT_KEY"
+"""머신 API 키를 받는 환경변수. **인자로 키를 받지 않는다** — 만들면 소스에 박힌다."""
+
+URL_ENV = "CHAMELION_VAULT_URL"
+"""게이트웨이 주소를 덮어쓰는 환경변수. 비어 있으면 터널의 로컬 종단을 쓴다."""
+
+
+class VaultError(Exception):
+    """이 패키지가 내는 모든 오류의 뿌리."""
+
+
+class MissingApiKeyError(VaultError):
+    """환경변수에 머신 API 키가 없다."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            f"머신 API 키가 없습니다. 환경변수 {KEY_ENV} 에 넣어 주세요.\n"
+            "\n"
+            "키는 Slack 에서 받습니다.\n"
+            "\n"
+            "    /vault machine\n"
+            "\n"
+            "관리자 승인 뒤 한 번만 표시되므로, 잃어버렸다면 다시 요청해 주세요."
+        )
+
+
+class VaultUnreachableError(VaultError):
+    """게이트웨이에 연결하지 못했다. 대개 터널이 떠 있지 않다."""
+
+    def __init__(self, *, url: str) -> None:
+        port = urlsplit(url).port or 8081
+        super().__init__(
+            f"볼트에 연결하지 못했습니다 ({url}).\n"
+            "SSH 터널이 떠 있는지 확인해 주세요.\n"
+            "\n"
+            "    ssh -i <터널 키> -o IdentitiesOnly=yes -p <SSH 포트> \\\n"
+            f"        -N -L {port}:127.0.0.1:{port} <계정>@<볼트 호스트>\n"
+            "\n"
+            "SSH 포트·계정·볼트 호스트는 사내 터널 문서에 있습니다.\n"
+            "IdentitiesOnly=yes 를 빠뜨리면 다른 키로 인증돼 연결이 거부됩니다."
+        )
+
+
+class SecretUnavailableError(VaultError):
+    """서버가 값을 주지 않았다. **원인은 서버만 안다.**"""
+
+    def __init__(self, *, path: str) -> None:
+        super().__init__(
+            f"값을 받지 못했습니다: {path}\n"
+            "볼트는 이유를 알려주지 않습니다. 가능한 원인은 셋입니다.\n"
+            "\n"
+            "  1. 접근 그룹 — 이 시크릿에 접근 그룹이 지정돼 있지 않으면 머신은\n"
+            "     값을 받지 못합니다. 가장 흔한 원인이니 소유자에게 먼저 확인해 주세요.\n"
+            "  2. 머신 키 — 아직 승인 전이거나 폐기됐을 수 있습니다.\n"
+            "  3. 경로 — 프로젝트·환경·이름 중 하나가 틀렸을 수 있습니다.\n"
+            "\n"
+            "개인 등급 시크릿은 머신이 받을 수 없습니다. 소유자 본인만 Slack 으로 받습니다."
+        )
+
+
+class UnexpectedResponseError(VaultError):
+    """계약에 없는 응답이 왔다. 서버 쪽 사고이거나 중간에 다른 것이 답한 것이다."""
+
+    def __init__(self, *, url: str, detail: str) -> None:
+        super().__init__(
+            f"볼트가 예상하지 못한 응답을 보냈습니다 ({url}): {detail}\n"
+            "이 주소가 정말 볼트 게이트웨이인지, 관리자에게 확인해 주세요."
+        )

chamelion_vault-0.1.0/src/chamelion_vault/_secret.py

@@ -0,0 +1,74 @@
+"""받은 값을 담는 두 타입 — `SecretStr` 와 `Secret`.
+
+**값은 상자에 담겨 나간다.** 실수로 로그·예외·`print` 에 통째로 섞여도 `<REDACTED>` 만
+남고, 실제로 쓰려면 `get_secret_value()` 로 한 번 열어야 한다. 여는 순간부터는
+받는 쪽 프로그램의 책임이다 — 우리가 막을 수 있는 것은 **실수로 찍는 경우**뿐이다.
+
+서버 쪽 규칙(rules/secrets_handling.md §3)을 클라이언트에도 그대로 적용한 것이고,
+pydantic 의 `SecretStr` 을 쓰지 않은 이유는 **의존성을 0으로 두기 위해서**다(D33).
+마스킹은 암호가 아니므로 "암호 알고리즘을 직접 구현하지 않는다" 와 무관하다.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+
+
+class SecretStr:
+    """평문 시크릿 값 래퍼. `repr`·`str`·`format` 에서 값이 새지 않게 마스킹한다."""
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str) -> None:
+        self._value = value
+
+    def __repr__(self) -> str:
+        return "SecretStr(<REDACTED>)"
+
+    def __str__(self) -> str:
+        return "<REDACTED>"
+
+    def __format__(self, format_spec: str) -> str:
+        return "<REDACTED>"
+
+    def get_secret_value(self) -> str:
+        """실제 값을 꺼낸다. 꺼낸 뒤에는 즉시 쓰고 참조를 버린다."""
+        return self._value
+
+
+class Secret(Mapping[str, SecretStr]):
+    """시크릿 1건 — 경로 하나와 그 안의 필드들.
+
+    값이 하나뿐인 시크릿도 필드 하나짜리 묶음이다(`["value"]`). 한 몸인 크리덴셜을
+    한 경로에 여러 필드로 둔 것이 번들이고, 그때 필드가 여럿이 된다.
+    """
+
+    __slots__ = ("_fields", "_path")
+
+    def __init__(self, *, path: str, fields: Mapping[str, SecretStr]) -> None:
+        """경로와 필드를 받는다.
+
+        Args:
+            path: 서버가 알려준 시크릿 경로. 비밀이 아니다.
+            fields: 필드 이름 → 값. 값은 이미 `SecretStr` 로 감싸여 있다.
+        """
+        self._path = path
+        self._fields = dict(fields)
+
+    @property
+    def path(self) -> str:
+        """시크릿 경로. 값이 아니므로 로그에 남겨도 된다."""
+        return self._path
+
+    def __getitem__(self, key: str) -> SecretStr:
+        return self._fields[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._fields)
+
+    def __len__(self) -> int:
+        return len(self._fields)
+
+    def __repr__(self) -> str:
+        # 경로와 **필드 이름**은 비밀이 아니다. 값은 여기에 등장하지 않는다.
+        return f"Secret({self._path}, fields={sorted(self._fields)})"