Files
2026-05-02 02:30:12 -07:00

9.0 KiB

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