212 lines
9.0 KiB
Markdown
212 lines
9.0 KiB
Markdown
# Machine Env Service — 구현 Plan
|
|
|
|
홈랩 머신마다 동작하는 로컬 메타데이터 데몬. AWS IMDSv2와 동일한 프로토콜로 머신 스코프 시크릿/환경변수를 노출한다. 클라이언트(컨테이너/프로세스)는 Infisical 자격증명 없이 데몬에 HTTP로 fetch.
|
|
|
|
## 1. 목표
|
|
|
|
- 각 머신에 systemd 서비스 1개로 상주하는 데몬
|
|
- IMDSv2 프로토콜(PUT 토큰 → GET 메타데이터) 그대로 구현
|
|
- 머신 스코프 시크릿은 데몬이 Infisical에서 가져와서 노출
|
|
- 데몬만 Infisical machine identity 자격증명을 보유 (클라는 0개)
|
|
|
|
## 2. 인터페이스 (IMDSv2 호환)
|
|
|
|
### 토큰 발급
|
|
```
|
|
PUT /latest/api/token
|
|
Headers:
|
|
X-aws-ec2-metadata-token-ttl-seconds: <1..21600>
|
|
Response:
|
|
200 OK, body = <opaque token string>
|
|
400 if header missing/invalid
|
|
405 if method != PUT
|
|
```
|
|
|
|
### 메타데이터 조회
|
|
```
|
|
GET /latest/meta-data/...
|
|
Headers:
|
|
X-aws-ec2-metadata-token: <token>
|
|
Response:
|
|
200 + body
|
|
401 if token missing/expired/invalid
|
|
```
|
|
|
|
### SSRF 방어 규칙 (IMDSv2와 동일)
|
|
- `PUT`이 아닌 메서드로 토큰 요청 시 `405`
|
|
- `X-Forwarded-For` 헤더가 있으면 모든 요청 거부 (`403`)
|
|
- `Host` 헤더 검증 (`169.254.169.254` 또는 listen 중인 호스트 IP)
|
|
|
|
## 3. 시크릿 엔드포인트
|
|
|
|
```
|
|
GET /latest/meta-data/secrets/ → 키 목록 (개행 구분, IMDS 컨벤션)
|
|
GET /latest/meta-data/secrets/<KEY> → 해당 키의 값 (plain text)
|
|
```
|
|
|
|
추가로 전체 dump (편의용, 기본 비활성, 설정으로 켜기):
|
|
```
|
|
GET /latest/meta-data/secrets-bundle → JSON {key: value}
|
|
```
|
|
|
|
기존 `KNOWN_SECRET_KEYS`는 노출 화이트리스트로 활용. 화이트리스트에 없는 키는 `404`.
|
|
|
|
## 4. 머신 식별 / 자격증명
|
|
|
|
- 데몬이 부팅 시 **자체적으로** dotenv 파일을 읽는다 (OS-agnostic, systemd `EnvironmentFile`과 launchd plist `EnvironmentVariables` 차이 회피)
|
|
- 경로: `MACHINE_ENV_CONFIG` env로 override 가능, 기본값 OS별
|
|
- Linux: `/etc/machine-env-service/env`
|
|
- macOS: `/usr/local/etc/machine-env-service/env`
|
|
- 파일 내용:
|
|
- `INFISICAL_CLIENT_ID`
|
|
- `INFISICAL_CLIENT_SECRET`
|
|
- `INFISICAL_PROJECT_ID`
|
|
- `INFISICAL_ENVIRONMENT` (`dev` | `staging` | `prod`)
|
|
- `INFISICAL_SITE_URL` (기본 `https://secret-manager.dahyeon.us/`)
|
|
- 머신마다 별도의 Infisical machine identity를 부여 → 그 자격증명이 곧 머신 식별자
|
|
- 자격증명 파일 권한은 `0600`, root 소유
|
|
|
|
## 5. 캐시 / 갱신
|
|
|
|
- 데몬 부팅 시 1회 `listSecrets` 호출 → 인메모리 맵 채움
|
|
- 백그라운드 타이머로 TTL마다 재조회 (기본 60초, `REFRESH_INTERVAL_SEC`로 설정)
|
|
- Infisical 호출 실패 시: 마지막 성공 값 유지, 로그만 남김
|
|
- 캐시는 read-mostly이므로 swap 갱신 시 잠시 락 또는 atomic 참조 교체
|
|
|
|
## 6. 토큰 저장소 (인메모리)
|
|
|
|
- `Map<tokenString, expiresAtEpochMs>`
|
|
- 토큰 발급: `crypto.randomBytes(32).toString("base64url")`
|
|
- 만료된 토큰은 lazy 청소 (요청 들어올 때 + 주기적 sweep)
|
|
- 데몬 재시작 시 모든 토큰 무효화 (의도된 동작, IMDSv2와 동일)
|
|
|
|
## 7. 네트워크 / 컨테이너 접근
|
|
|
|
데몬은 두 곳에 동시에 listen한다:
|
|
|
|
1. **`169.254.169.254:80`** — link-local. 호스트 자체에서 동작하는 프로세스용
|
|
- **Linux**: dummy interface로 link-local 주소 추가
|
|
```
|
|
ip link add dev imds-dummy type dummy
|
|
ip addr add 169.254.169.254/32 dev imds-dummy
|
|
ip link set imds-dummy up
|
|
```
|
|
- **macOS**: `lo0` alias로 추가
|
|
```
|
|
ifconfig lo0 alias 169.254.169.254/32 up
|
|
```
|
|
- 두 경우 모두 재부팅 시 사라지므로 service manager가 부팅 시 setup 실행
|
|
2. **`0.0.0.0:<METADATA_PORT>`** (기본 `8675`) — 호스트 LAN IP. 컨테이너에서 호스트 IP로 접근
|
|
- Linux 컨테이너 (bridge): `http://<host-ip>:8675/latest/...`
|
|
- **Docker Desktop on macOS**: link-local이 VM 안에서 호스트로 라우팅 안 됨 → `http://host.docker.internal:8675/latest/...` 필수
|
|
- host network 강제 불필요
|
|
|
|
**80 포트 바인딩**:
|
|
- Linux: systemd unit에서 `AmbientCapabilities=CAP_NET_BIND_SERVICE` (root 아닌 user로 실행 가능)
|
|
- macOS: `CAP_NET_BIND_SERVICE` 같은 메커니즘 없음 → launchd plist `UserName=root`로 실행
|
|
|
|
## 8. 보안
|
|
|
|
- `127.0.0.1`/`169.254.169.254`/LAN IP는 모두 신뢰 경계 안 (홈랩 내부망 전제)
|
|
- 외부 노출 금지 — 방화벽에서 metadata 포트는 LAN 외부 차단
|
|
- 자격증명 파일은 `0600`, 데몬 user(`machine-env`)만 접근
|
|
- 응답 본문에 시크릿 외 다른 정보 절대 포함 금지 (IMDS 스타일)
|
|
|
|
## 9. 디렉토리 구조
|
|
|
|
```
|
|
src/
|
|
common/
|
|
secret-manager.ts # 기존 — Infisical fetch 로직 추출/재사용
|
|
known-secret-keys.ts # 기존
|
|
env-loader.ts # 기존
|
|
daemon/
|
|
main.ts # 엔트리포인트
|
|
server.ts # HTTP 서버 (node:http)
|
|
routes/
|
|
token.ts # PUT /latest/api/token
|
|
metadata.ts # GET /latest/meta-data/...
|
|
secrets.ts # GET /latest/meta-data/secrets/...
|
|
middleware/
|
|
ssrf-guard.ts # X-Forwarded-For, Host, method 검증
|
|
token-auth.ts # 토큰 헤더 검증
|
|
store/
|
|
token-store.ts # 인메모리 토큰 저장소
|
|
secret-cache.ts # Infisical 캐시 + 백그라운드 갱신
|
|
config.ts # 환경변수 파싱
|
|
deploy/
|
|
systemd/ # Linux (Ubuntu)
|
|
machine-env-service.service
|
|
machine-env-setup-link-local.service # 부팅 시 dummy interface 셋업
|
|
machine-env-service.env.example
|
|
launchd/ # macOS
|
|
us.dahyeon.machine-env-service.plist
|
|
us.dahyeon.machine-env-setup-link-local.plist
|
|
machine-env-service.env.example
|
|
scripts/
|
|
setup-link-local-linux.sh
|
|
setup-link-local-macos.sh
|
|
```
|
|
|
|
## 10. 구현 단계 (codex용 체크리스트)
|
|
|
|
1. **config 모듈** — `src/daemon/config.ts`
|
|
- 필수 env(`INFISICAL_*`) 검증, 누락 시 즉시 종료
|
|
- 선택 env(`METADATA_PORT`, `REFRESH_INTERVAL_SEC`, 화이트리스트 모드 등) 기본값 처리
|
|
|
|
2. **secret-cache** — `src/daemon/store/secret-cache.ts`
|
|
- `secret-manager.ts`의 Infisical fetch 로직을 클래스/함수로 추출
|
|
- `start()` / `stop()` / `get(key)` / `list()` API
|
|
- 부팅 시 첫 fetch는 동기적으로 await, 실패해도 빈 캐시로 계속 진행
|
|
- TTL 기반 백그라운드 재조회 (`setInterval`)
|
|
|
|
3. **token-store** — `src/daemon/store/token-store.ts`
|
|
- `issue(ttlSec): string`
|
|
- `validate(token): boolean`
|
|
- 만료 sweep
|
|
|
|
4. **middleware**
|
|
- `ssrf-guard`: 메서드/X-Forwarded-For/Host 검증
|
|
- `token-auth`: `X-aws-ec2-metadata-token` 헤더 검증
|
|
|
|
5. **routes**
|
|
- `PUT /latest/api/token`: TTL 헤더 파싱 → `token-store.issue()` → 응답
|
|
- `GET /latest/meta-data/secrets/`: 화이트리스트 키 목록 (개행 구분)
|
|
- `GET /latest/meta-data/secrets/<KEY>`: 캐시에서 조회, 없으면 404
|
|
- `GET /latest/meta-data/secrets-bundle`: 설정으로 enable됐을 때만, JSON 응답
|
|
|
|
6. **server** — `src/daemon/server.ts`
|
|
- `node:http`로 라우팅 (외부 의존 최소화)
|
|
- 두 listener 동시 기동 (`169.254.169.254:80`, `0.0.0.0:METADATA_PORT`)
|
|
- graceful shutdown (SIGTERM → 새 요청 거부 → 인플라이트 대기 → 캐시 타이머 정리)
|
|
|
|
7. **main** — `src/daemon/main.ts`
|
|
- config 로드 → secret-cache 초기화 → token-store 초기화 → server 기동
|
|
- SIGTERM/SIGINT 핸들링
|
|
|
|
8. **deploy 자산**
|
|
- **Linux (systemd)**:
|
|
- `machine-env-service.service`: `Type=simple`, `User=machine-env`, `AmbientCapabilities=CAP_NET_BIND_SERVICE`, `CapabilityBoundingSet=CAP_NET_BIND_SERVICE`, `Restart=on-failure`
|
|
- `machine-env-setup-link-local.service`: `Type=oneshot`, `RemainAfterExit=true`, 부팅 시 `setup-link-local-linux.sh` 실행
|
|
- `machine-env-service.service`는 `After=machine-env-setup-link-local.service`, `Requires=...`
|
|
- **macOS (launchd)**:
|
|
- `us.dahyeon.machine-env-service.plist`: `RunAtLoad=true`, `KeepAlive=true`, `UserName=root`, `ProgramArguments`에 node + 빌드 산출물 경로
|
|
- `us.dahyeon.machine-env-setup-link-local.plist`: `RunAtLoad=true`, `LaunchOnlyOnce=false`, `setup-link-local-macos.sh` 실행
|
|
- 설치 위치: `/Library/LaunchDaemons/`
|
|
- link-local 설정 스크립트는 idempotent (이미 alias/interface 있으면 skip)
|
|
|
|
9. **package.json 업데이트**
|
|
- `"bin"` 또는 `"scripts"`에 데몬 실행 엔트리
|
|
- 빌드 스크립트 (tsc)
|
|
|
|
10. **간단한 클라이언트 예제** — `examples/fetch-secret.sh`
|
|
- `curl -X PUT -H "...ttl-seconds: 60" .../latest/api/token` → 토큰
|
|
- `curl -H "X-aws-ec2-metadata-token: $TOKEN" .../latest/meta-data/secrets/FOO`
|
|
|
|
## 11. 추후 (이번 범위 밖)
|
|
|
|
- mTLS 또는 호출자 식별 기반 시크릿 범위 제한
|
|
- Infisical webhook 연동으로 즉시 갱신
|
|
- 머신별 dynamic 메타데이터(hostname, IP 등) 노출 (`/latest/meta-data/hostname` 등)
|
|
- IPv6 link-local (`fe80::a9fe:a9fe`) 지원
|