Files
instance-metadata-service/PLAN.md
T
2026-05-02 02:30:12 -07:00

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`) 지원