# 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 = 400 if header missing/invalid 405 if method != PUT ``` ### 메타데이터 조회 ``` GET /latest/meta-data/... Headers: X-aws-ec2-metadata-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/ → 해당 키의 값 (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` - 토큰 발급: `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:`** (기본 `8675`) — 호스트 LAN IP. 컨테이너에서 호스트 IP로 접근 - Linux 컨테이너 (bridge): `http://: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/`: 캐시에서 조회, 없으면 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`) 지원