This commit is contained in:
dahyeon committed 2026-05-02 02:30:12 -07:00
commit 08c0e9c107
33 files changed
+4312

No files matched your search

+6
View File
@@ -0,0 +1,6 @@
node_modules/
dist/
env
env-vars/*.env
env-vars/.env.*
*.log
+211
View File
@@ -0,0 +1,211 @@
# 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`) 지원
+439
View File
@@ -0,0 +1,439 @@
# Machine Env Service
IMDSv2-compatible local metadata daemon for homelab machines. Each machine runs one daemon, and local processes or containers can fetch machine-scoped metadata and allowlisted Infisical secrets through HTTP without holding Infisical credentials.
## What It Exposes
Token endpoint:
```text
PUT /latest/api/token
```
Metadata endpoints require `X-aws-ec2-metadata-token`:
```text
/latest/meta-data/
/latest/meta-data/hostname
/latest/meta-data/local-hostname
/latest/meta-data/local-ipv4
/latest/meta-data/mac
/latest/meta-data/machine-id
/latest/meta-data/environment
/latest/meta-data/role
/latest/meta-data/tags/
/latest/meta-data/tags/<KEY>
/latest/meta-data/tags/instance/
/latest/meta-data/tags/instance/<KEY>
/latest/meta-data/secrets/
/latest/meta-data/secrets/<KEY>
/latest/dynamic/instance-identity/document
/latest/user-data
```
`/latest/meta-data/secrets-bundle` is available only when `ALLOW_SECRETS_BUNDLE=true`.
## Configuration
The daemon reads its own dotenv-style config file.
Default paths:
```text
Linux: /etc/machine-env-service/env
macOS: /usr/local/etc/machine-env-service/env
```
Override with:
```bash
MACHINE_ENV_CONFIG=/path/to/env
```
Minimum config:
```env
INFISICAL_ACCESS_TOKEN=
INFISICAL_PROJECT_ID=
INFISICAL_ENVIRONMENT=prod
KNOWN_SECRET_KEYS=FOO,BAR
METADATA_PORT=8675
REFRESH_INTERVAL_SEC=60
```
Optional machine metadata:
```env
MACHINE_ID=
MACHINE_HOSTNAME=
MACHINE_LOCAL_HOSTNAME=
MACHINE_LOCAL_IPV4=
MACHINE_MAC=
MACHINE_ROLE=homelab-node
MACHINE_TAGS=site=home,tier=prod
USER_DATA=
USER_DATA_FILE=
```
If machine fields are empty, the daemon derives hostname, IPv4, MAC, and machine-id from the OS where possible.
Secret allowlist variables are checked in this order:
```text
KNOWN_SECRET_KEYS
EXPOSED_SECRET_KEYS
SECRET_ALLOWLIST
SECRET_WHITELIST
```
Values can be comma-separated or whitespace-separated.
## Local Development
Build:
```bash
npm ci
npm run build
```
Run locally without binding `169.254.169.254:80`:
```bash
NODE_ENV=dev LINK_LOCAL_LISTENER_ENABLED=false npm start
```
Request a token:
```bash
TOKEN=$(
curl -fsS -X PUT \
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
http://127.0.0.1:8675/latest/api/token
)
```
Fetch metadata:
```bash
curl -fsS \
-H "X-aws-ec2-metadata-token: $TOKEN" \
http://127.0.0.1:8675/latest/meta-data/hostname
```
Fetch a secret:
```bash
curl -fsS \
-H "X-aws-ec2-metadata-token: $TOKEN" \
http://127.0.0.1:8675/latest/meta-data/secrets/FOO
```
Or use:
```bash
METADATA_BASE_URL=http://127.0.0.1:8675 ./examples/fetch-secret.sh FOO
```
## Ubuntu Install
The included systemd units assume the app lives at `/opt/machine-env-service`.
Install files:
```bash
sudo mkdir -p /opt/machine-env-service
sudo chown -R "$USER:$USER" /opt/machine-env-service
rsync -a \
--exclude .git \
--exclude node_modules \
--exclude dist \
--exclude env-vars \
./ /opt/machine-env-service/
cd /opt/machine-env-service
npm ci
npm run build
```
Create service user:
```bash
sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin machine-env || true
```
Create config:
```bash
sudo install -d -o machine-env -g machine-env -m 0700 /etc/machine-env-service
sudo cp deploy/systemd/machine-env-service.env.example /etc/machine-env-service/env
sudo nano /etc/machine-env-service/env
sudo chown machine-env:machine-env /etc/machine-env-service/env
sudo chmod 0600 /etc/machine-env-service/env
```
Install and start systemd units:
```bash
sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now machine-env-setup-link-local.service
sudo systemctl enable --now machine-env-service.service
```
Check logs:
```bash
systemctl status machine-env-service.service
journalctl -u machine-env-service.service -f
```
Test the link-local endpoint:
```bash
TOKEN=$(
curl -fsS -X PUT \
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
http://169.254.169.254/latest/api/token
)
curl -fsS \
-H "X-aws-ec2-metadata-token: $TOKEN" \
http://169.254.169.254/latest/meta-data/
```
## macOS Install
The included launchd plists assume:
```text
App path: /opt/machine-env-service
Node path: /usr/local/bin/node
Config path: /usr/local/etc/machine-env-service/env
```
Check your Node path first:
```bash
command -v node
```
If it is not `/usr/local/bin/node`, either update `deploy/launchd/us.dahyeon.machine-env-service.plist` before installing or create a system-visible symlink:
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf "$(command -v node)" /usr/local/bin/node
```
When Node comes from `nvm`, the symlink is the quickest local setup. A Homebrew Node installed at a stable path is usually better for a long-lived daemon.
Install files:
```bash
sudo mkdir -p /opt/machine-env-service
sudo chown -R "$(id -un):admin" /opt/machine-env-service
rsync -a \
--exclude .git \
--exclude node_modules \
--exclude dist \
--exclude env-vars \
./ /opt/machine-env-service/
cd /opt/machine-env-service
npm ci
npm run build
```
Create config:
```bash
sudo install -d -m 0700 /usr/local/etc/machine-env-service
sudo cp deploy/launchd/machine-env-service.env.example /usr/local/etc/machine-env-service/env
sudo nano /usr/local/etc/machine-env-service/env
sudo chown root:wheel /usr/local/etc/machine-env-service/env
sudo chmod 0600 /usr/local/etc/machine-env-service/env
```
Install and start launchd daemons:
```bash
sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
```
Check logs:
```bash
sudo launchctl print system/us.dahyeon.machine-env-service
tail -f /var/log/machine-env-service.log
tail -f /var/log/machine-env-service.err.log
```
Test:
```bash
TOKEN=$(
curl -fsS -X PUT \
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
http://169.254.169.254/latest/api/token
)
curl -fsS \
-H "X-aws-ec2-metadata-token: $TOKEN" \
http://169.254.169.254/latest/meta-data/hostname
```
Docker Desktop on macOS usually cannot route container traffic to host `169.254.169.254`. Use the LAN listener instead:
```text
http://host.docker.internal:8675/latest/meta-data/...
```
## Update
Restarting the daemon invalidates issued IMDSv2 tokens. Clients should request a new token after an update.
If `/opt/machine-env-service` is a git checkout:
```bash
cd /opt/machine-env-service
git pull
npm ci
npm run build
```
If you deploy from another checkout:
```bash
rsync -a --delete \
--exclude .git \
--exclude node_modules \
--exclude dist \
--exclude env-vars \
./ /opt/machine-env-service/
cd /opt/machine-env-service
npm ci
npm run build
```
Do not overwrite the machine config file:
```text
Linux: /etc/machine-env-service/env
macOS: /usr/local/etc/machine-env-service/env
```
Restart after code-only updates:
```bash
sudo systemctl restart machine-env-service.service
```
```bash
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
```
If systemd unit files changed:
```bash
sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl restart machine-env-setup-link-local.service
sudo systemctl restart machine-env-service.service
```
If launchd plist files changed:
```bash
sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist 2>/dev/null || true
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist 2>/dev/null || true
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
```
Check after updating:
```bash
systemctl status machine-env-service.service
journalctl -u machine-env-service.service -n 100
```
```bash
sudo launchctl print system/us.dahyeon.machine-env-service
tail -n 100 /var/log/machine-env-service.err.log
```
## Operations
Restart:
```bash
sudo systemctl restart machine-env-service.service
```
```bash
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
```
Stop:
```bash
sudo systemctl stop machine-env-service.service
```
```bash
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
```
## Troubleshooting
If `curl http://169.254.169.254/latest/api/token` fails with `Couldn't connect to server`, check the link-local alias and daemon separately:
```bash
ifconfig lo0 | grep 169.254.169.254
sudo launchctl print system/us.dahyeon.machine-env-service
```
If launchd shows `last exit code = 78: EX_CONFIG` and the plist points to `/usr/local/bin/node`, verify that Node exists there:
```bash
ls -l /usr/local/bin/node
command -v node
```
Fix a missing `/usr/local/bin/node` with:
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf "$(command -v node)" /usr/local/bin/node
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
```
Then retry token issuance.
## Security Notes
- Keep the config file mode at `0600`.
- Do not commit `env-vars/*.env`, production config files, or access tokens.
- Only allowlist secrets that should be readable by local machine workloads.
- Block `METADATA_PORT` from untrusted networks.
- Requests with `X-Forwarded-For` are rejected.
- Metadata requests require IMDSv2-style tokens; token TTL is `1..21600` seconds.
@@ -0,0 +1,18 @@
INFISICAL_ACCESS_TOKEN=
INFISICAL_PROJECT_ID=
INFISICAL_ENVIRONMENT=prod
INFISICAL_SITE_URL=https://secret-manager.dahyeon.us/
METADATA_PORT=8675
REFRESH_INTERVAL_SEC=60
ALLOW_SECRETS_BUNDLE=false
KNOWN_SECRET_KEYS=EXAMPLE_SECRET
MACHINE_ID=
MACHINE_HOSTNAME=
MACHINE_LOCAL_HOSTNAME=
MACHINE_LOCAL_IPV4=
MACHINE_MAC=
MACHINE_ROLE=homelab-node
MACHINE_TAGS=site=home,tier=dev
USER_DATA=
@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>us.dahyeon.machine-env-service</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/node</string>
<string>/opt/machine-env-service/dist/daemon/main.js</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>MACHINE_ENV_CONFIG</key>
<string>/usr/local/etc/machine-env-service/env</string>
</dict>
<key>WorkingDirectory</key>
<string>/opt/machine-env-service</string>
<key>UserName</key>
<string>root</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/var/log/machine-env-service.log</string>
<key>StandardErrorPath</key>
<string>/var/log/machine-env-service.err.log</string>
</dict>
</plist>
@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>us.dahyeon.machine-env-setup-link-local</string>
<key>ProgramArguments</key>
<array>
<string>/opt/machine-env-service/deploy/scripts/setup-link-local-macos.sh</string>
</array>
<key>UserName</key>
<string>root</string>
<key>RunAtLoad</key>
<true/>
<key>LaunchOnlyOnce</key>
<false/>
<key>StandardOutPath</key>
<string>/var/log/machine-env-setup-link-local.log</string>
<key>StandardErrorPath</key>
<string>/var/log/machine-env-setup-link-local.err.log</string>
</dict>
</plist>
+20
View File
@@ -0,0 +1,20 @@
#!/usr/bin/env bash
set -euo pipefail
IFACE="${IMDS_DUMMY_INTERFACE:-imds-dummy}"
ADDR="${IMDS_LINK_LOCAL_ADDRESS:-169.254.169.254/32}"
if ! command -v ip >/dev/null 2>&1; then
echo "ip command is required" >&2
exit 1
fi
if ! ip link show "$IFACE" >/dev/null 2>&1; then
ip link add dev "$IFACE" type dummy
fi
if ! ip addr show dev "$IFACE" | grep -q "169.254.169.254"; then
ip addr add "$ADDR" dev "$IFACE"
fi
ip link set "$IFACE" up
+15
View File
@@ -0,0 +1,15 @@
#!/usr/bin/env bash
set -euo pipefail
ADDR="${IMDS_LINK_LOCAL_ADDRESS:-169.254.169.254}"
if ! command -v ifconfig >/dev/null 2>&1; then
echo "ifconfig command is required" >&2
exit 1
fi
if ifconfig lo0 | grep -q "$ADDR"; then
exit 0
fi
ifconfig lo0 alias "$ADDR/32" up
@@ -0,0 +1,18 @@
INFISICAL_ACCESS_TOKEN=
INFISICAL_PROJECT_ID=
INFISICAL_ENVIRONMENT=prod
INFISICAL_SITE_URL=https://secret-manager.dahyeon.us/
METADATA_PORT=8675
REFRESH_INTERVAL_SEC=60
ALLOW_SECRETS_BUNDLE=false
KNOWN_SECRET_KEYS=EXAMPLE_SECRET
MACHINE_ID=
MACHINE_HOSTNAME=
MACHINE_LOCAL_HOSTNAME=
MACHINE_LOCAL_IPV4=
MACHINE_MAC=
MACHINE_ROLE=homelab-node
MACHINE_TAGS=site=home,tier=dev
USER_DATA=
@@ -0,0 +1,26 @@
[Unit]
Description=Machine Env Metadata Service
Documentation=https://github.com/dahyeon/machine-env-service
After=network-online.target machine-env-setup-link-local.service
Wants=network-online.target
Requires=machine-env-setup-link-local.service
[Service]
Type=simple
User=machine-env
Group=machine-env
WorkingDirectory=/opt/machine-env-service
Environment=MACHINE_ENV_CONFIG=/etc/machine-env-service/env
ExecStart=/usr/bin/node /opt/machine-env-service/dist/daemon/main.js
Restart=on-failure
RestartSec=5
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/etc/machine-env-service
[Install]
WantedBy=multi-user.target
@@ -0,0 +1,13 @@
[Unit]
Description=Configure link-local IMDS address for Machine Env Service
DefaultDependencies=no
After=local-fs.target
Before=network-online.target machine-env-service.service
[Service]
Type=oneshot
RemainAfterExit=true
ExecStart=/opt/machine-env-service/deploy/scripts/setup-link-local-linux.sh
[Install]
WantedBy=multi-user.target
+16
View File
@@ -0,0 +1,16 @@
#!/usr/bin/env bash
set -euo pipefail
BASE_URL="${METADATA_BASE_URL:-http://169.254.169.254}"
SECRET_KEY="${1:-EXAMPLE_SECRET}"
TOKEN="$(
curl -fsS \
-X PUT \
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
"$BASE_URL/latest/api/token"
)"
curl -fsS \
-H "X-aws-ec2-metadata-token: $TOKEN" \
"$BASE_URL/latest/meta-data/secrets/$SECRET_KEY"
+2012
View File
File diff suppressed because it is too large. Load diff
+24
View File
@@ -0,0 +1,24 @@
{
"name": "machine-env-service",
"version": "1.0.0",
"description": "Local IMDSv2-compatible metadata daemon for machine-scoped environment secrets.",
"license": "ISC",
"author": "",
"type": "module",
"main": "dist/daemon/main.js",
"bin": {
"machine-env-service": "./dist/daemon/main.js"
},
"scripts": {
"build": "tsc -p tsconfig.json",
"start": "node dist/daemon/main.js",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"devDependencies": {
"@types/node": "^25.6.0",
"typescript": "^6.0.3"
},
"dependencies": {
"@infisical/sdk": "^5.0.2"
}
}
+78
View File
@@ -0,0 +1,78 @@
export type EnvTarget = Record<string, string | undefined>;
function unquoteValue(value: string): string {
const trimmed = value.trim();
if (trimmed.length < 2) return trimmed;
const quote = trimmed[0];
if ((quote !== `"` && quote !== `'`) || trimmed[trimmed.length - 1] !== quote) {
return trimmed;
}
const inner = trimmed.slice(1, -1);
if (quote === `'`) return inner;
return inner
.replace(/\\n/g, "\n")
.replace(/\\r/g, "\r")
.replace(/\\t/g, "\t")
.replace(/\\"/g, `"`)
.replace(/\\\\/g, "\\");
}
function stripInlineComment(value: string): string {
let inSingleQuote = false;
let inDoubleQuote = false;
for (let i = 0; i < value.length; i += 1) {
const char = value[i];
const previous = value[i - 1];
if (char === `'` && !inDoubleQuote && previous !== "\\") {
inSingleQuote = !inSingleQuote;
} else if (char === `"` && !inSingleQuote && previous !== "\\") {
inDoubleQuote = !inDoubleQuote;
} else if (char === "#" && !inSingleQuote && !inDoubleQuote) {
const before = value[i - 1];
if (before === undefined || /\s/.test(before)) {
return value.slice(0, i).trimEnd();
}
}
}
return value;
}
export function parseDotenv(contents: string): Record<string, string> {
const parsed: Record<string, string> = {};
const lines = contents.split(/\r?\n/);
for (const rawLine of lines) {
const line = rawLine.trim();
if (!line || line.startsWith("#")) continue;
const normalized = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
const separator = normalized.indexOf("=");
if (separator <= 0) continue;
const key = normalized.slice(0, separator).trim();
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
const rawValue = normalized.slice(separator + 1);
parsed[key] = unquoteValue(stripInlineComment(rawValue));
}
return parsed;
}
export function mergeDotenv(
target: EnvTarget,
parsed: Record<string, string>,
options: { override?: boolean } = {},
): void {
const override = options.override ?? false;
for (const [key, value] of Object.entries(parsed)) {
if (!override && target[key] !== undefined) continue;
target[key] = value;
}
}
+89
View File
@@ -0,0 +1,89 @@
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { mergeDotenv, parseDotenv } from "./dotenv.js";
type NodeEnvMode = "dev" | "test" | "prod";
const VALID_MODES = new Set<NodeEnvMode>(["dev", "test", "prod"]);
const DEFAULT_MODE: NodeEnvMode = "dev";
let loaded = false;
function normalizeMode(raw: string | undefined): NodeEnvMode {
const input = (raw ?? "").trim().toLowerCase();
if (input === "development") return "dev";
if (input === "testing") return "test";
if (input === "production") return "prod";
if (VALID_MODES.has(input as NodeEnvMode)) return input as NodeEnvMode;
return DEFAULT_MODE;
}
function resolveEnvFile(mode: NodeEnvMode): string | null {
const moduleDir = path.dirname(fileURLToPath(import.meta.url));
const candidates = [
path.resolve(process.cwd(), "env-vars", `${mode}.env`),
path.resolve(process.cwd(), "env-vars", `.env.${mode}`),
path.resolve(moduleDir, "../../env-vars", `${mode}.env`),
path.resolve(moduleDir, "../../env-vars", `.env.${mode}`),
];
for (const candidate of candidates) {
if (fs.existsSync(candidate)) return candidate;
}
return null;
}
function resolveGlobalEnvFile(): { explicit: boolean; path: string } | null {
const explicitPath = process.env["DAHYEON_GLOBAL_ENVIRONMENT_FILE"]?.trim();
if (explicitPath) {
return { explicit: true, path: path.resolve(explicitPath) };
}
const homeDir = process.env["HOME"] ?? process.env["USERPROFILE"];
if (!homeDir) return null;
return {
explicit: false,
path: path.resolve(homeDir, "source/global-env-vars.txt"),
};
}
function loadDotenvFile(filePath: string, label: string): void {
try {
mergeDotenv(process.env, parseDotenv(fs.readFileSync(filePath, "utf8")));
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
console.warn(`[Env] Failed to load ${label} (${filePath}): ${message}`);
}
}
export function loadEnvironmentFromNodeEnv(): void {
if (loaded) return;
loaded = true;
const mode = normalizeMode(process.env["NODE_ENV"]);
process.env["NODE_ENV"] = mode;
const envFile = resolveEnvFile(mode);
if (!envFile) {
console.warn(`[Env] env-vars/${mode}.env not found. Skipping dotenv load.`);
return;
}
loadDotenvFile(envFile, `env-vars/${mode}.env`);
const globalEnvFile = resolveGlobalEnvFile();
if (!globalEnvFile) return;
if (!fs.existsSync(globalEnvFile.path)) {
if (globalEnvFile.explicit) {
console.warn(
`[Env] DAHYEON_GLOBAL_ENVIRONMENT_FILE not found: ${globalEnvFile.path}`,
);
}
return;
}
loadDotenvFile(globalEnvFile.path, "global env file");
}
+6
View File
@@ -0,0 +1,6 @@
// Add machine-scoped secret names here to expose them through the metadata daemon.
// You can also set KNOWN_SECRET_KEYS, EXPOSED_SECRET_KEYS, or SECRET_ALLOWLIST
// in the daemon env file to configure the allowlist without rebuilding.
export const KNOWN_SECRET_KEYS = [] as const satisfies readonly string[];
export type KnownSecretKey = string;
+72
View File
@@ -0,0 +1,72 @@
import { InfisicalSDK } from "@infisical/sdk";
import { KNOWN_SECRET_KEYS, type KnownSecretKey } from "./known-secret-keys.js";
export type InfisicalEnvironment = "dev" | "staging" | "prod";
export type SecretMap = Partial<Record<KnownSecretKey, string>>;
export type RawSecretMap = Record<string, string>;
export interface InfisicalSecretConfig {
accessToken: string;
projectId: string;
environment: InfisicalEnvironment;
siteUrl: string;
}
export interface FetchedSecrets {
known: SecretMap;
raw: RawSecretMap;
}
export const DEFAULT_INFISICAL_SITE_URL = "https://secret-manager.dahyeon.us/";
let secrets: SecretMap = {};
let rawSecrets: RawSecretMap = {};
function toSecretMap(
raw: RawSecretMap,
allowlist: readonly string[],
): SecretMap {
const allowed = new Set(allowlist);
const known: SecretMap = {};
for (const [key, value] of Object.entries(raw)) {
if (allowed.has(key)) known[key] = value;
}
return known;
}
export function getSecret(key: KnownSecretKey): string | undefined {
return secrets[key] ?? process.env[key];
}
export function getRawSecret(key: string): string | undefined {
return rawSecrets[key] ?? process.env[key];
}
export function getKnownSecretKeys(): readonly string[] {
return KNOWN_SECRET_KEYS;
}
export async function fetchInfisicalSecrets(
config: InfisicalSecretConfig,
allowlist: readonly string[] = KNOWN_SECRET_KEYS,
): Promise<FetchedSecrets> {
const infisicalClient = new InfisicalSDK({ siteUrl: config.siteUrl });
infisicalClient.auth().accessToken(config.accessToken);
const res = await infisicalClient.secrets().listSecrets({
environment: config.environment,
projectId: config.projectId,
viewSecretValue: true,
});
rawSecrets = {};
for (const secret of res.secrets) {
if (!secret.secretKey) continue;
rawSecrets[secret.secretKey] = secret.secretValue ?? "";
}
secrets = toSecretMap(rawSecrets, allowlist);
return { known: { ...secrets }, raw: { ...rawSecrets } };
}
+261
View File
@@ -0,0 +1,261 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import {
DEFAULT_INFISICAL_SITE_URL,
type InfisicalEnvironment,
type InfisicalSecretConfig,
} from "../common/secret-manager.js";
import { getKnownSecretKeys } from "../common/secret-manager.js";
import { mergeDotenv, parseDotenv, type EnvTarget } from "../common/dotenv.js";
import {
buildMachineMetadata,
type MachineMetadata,
} from "./machine-metadata.js";
export interface ListenerConfig {
enabled: boolean;
host: string;
port: number;
}
export interface DaemonConfig {
infisical: InfisicalSecretConfig;
metadataPort: number;
refreshIntervalMs: number;
tokenSweepIntervalMs: number;
allowSecretsBundle: boolean;
secretAllowlist: readonly string[];
allowedHosts: readonly string[];
lanListener: ListenerConfig;
linkLocalListener: ListenerConfig;
machineEnvConfigPath: string;
machineMetadata: MachineMetadata;
}
const DEFAULT_METADATA_PORT = 8675;
const DEFAULT_REFRESH_INTERVAL_SEC = 60;
const DEFAULT_TOKEN_SWEEP_INTERVAL_SEC = 60;
const LINK_LOCAL_ADDRESS = "169.254.169.254";
function defaultConfigPath(platform: NodeJS.Platform): string {
if (platform === "darwin") return "/usr/local/etc/machine-env-service/env";
return "/etc/machine-env-service/env";
}
function boolFromEnv(
value: string | undefined,
defaultValue: boolean,
): boolean {
if (value === undefined || value.trim() === "") return defaultValue;
const normalized = value.trim().toLowerCase();
if (["1", "true", "yes", "on"].includes(normalized)) return true;
if (["0", "false", "no", "off"].includes(normalized)) return false;
throw new Error(`Invalid boolean value: ${value}`);
}
function intFromEnv(
key: string,
value: string | undefined,
defaultValue: number,
options: { min: number; max?: number },
): number {
if (value === undefined || value.trim() === "") return defaultValue;
const parsed = Number.parseInt(value, 10);
if (!Number.isInteger(parsed)) throw new Error(`${key} must be an integer`);
if (parsed < options.min) throw new Error(`${key} must be >= ${options.min}`);
if (options.max !== undefined && parsed > options.max) {
throw new Error(`${key} must be <= ${options.max}`);
}
return parsed;
}
function required(env: EnvTarget, key: string): string {
const value = env[key]?.trim();
if (!value) throw new Error(`Missing required environment variable: ${key}`);
return value;
}
function parseEnvironment(value: string | undefined): InfisicalEnvironment {
const normalized = value?.trim();
if (
normalized === "dev" ||
normalized === "staging" ||
normalized === "prod"
) {
return normalized;
}
throw new Error("INFISICAL_ENVIRONMENT must be one of: dev, staging, prod");
}
function parseList(value: string | undefined): string[] {
if (!value) return [];
return value
.split(/[,\s]+/)
.map((item) => item.trim())
.filter(Boolean);
}
function firstConfiguredList(
env: EnvTarget,
keys: readonly string[],
): string[] {
for (const key of keys) {
const parsed = parseList(env[key]);
if (parsed.length > 0) return parsed;
}
return [];
}
function currentIpv4Hosts(): string[] {
const hosts = new Set<string>();
for (const addresses of Object.values(os.networkInterfaces())) {
for (const address of addresses ?? []) {
if (address.family !== "IPv4") continue;
hosts.add(address.address);
}
}
return [...hosts];
}
function normalizeHost(host: string): string {
const trimmed = host.trim().toLowerCase();
if (!trimmed) return trimmed;
if (trimmed.startsWith("[")) {
const closingBracket = trimmed.indexOf("]");
return closingBracket === -1 ? trimmed : trimmed.slice(1, closingBracket);
}
const colon = trimmed.lastIndexOf(":");
if (colon === -1) return trimmed;
const maybePort = trimmed.slice(colon + 1);
if (/^\d+$/.test(maybePort)) return trimmed.slice(0, colon);
return trimmed;
}
function buildAllowedHosts(env: EnvTarget, metadataPort: number): string[] {
const configured = firstConfiguredList(env, [
"METADATA_ALLOWED_HOSTS",
"ALLOWED_HOSTS",
]);
const hosts = new Set(
[
LINK_LOCAL_ADDRESS,
"localhost",
"127.0.0.1",
"host.docker.internal",
...currentIpv4Hosts(),
...configured,
].map(normalizeHost),
);
hosts.add(normalizeHost(`${LINK_LOCAL_ADDRESS}:80`));
hosts.add(normalizeHost(`127.0.0.1:${metadataPort}`));
return [...hosts].filter(Boolean).sort();
}
function warnIfWeakConfigFilePermissions(filePath: string): void {
try {
const stat = fs.statSync(filePath);
if ((stat.mode & 0o077) !== 0) {
console.warn(
`[Config] ${filePath} is readable by group/others. Recommended mode is 0600.`,
);
}
} catch {
// Permission checks are best effort only; required values are validated below.
}
}
function loadMachineEnvFile(env: EnvTarget): string {
const configuredPath = env["MACHINE_ENV_CONFIG"]?.trim();
const filePath = path.resolve(
configuredPath || defaultConfigPath(process.platform),
);
if (!fs.existsSync(filePath)) {
if (configuredPath) {
console.warn(`[Config] MACHINE_ENV_CONFIG not found: ${filePath}`);
}
return filePath;
}
mergeDotenv(env, parseDotenv(fs.readFileSync(filePath, "utf8")));
warnIfWeakConfigFilePermissions(filePath);
return filePath;
}
export function loadConfig(env: EnvTarget = process.env): DaemonConfig {
const machineEnvConfigPath = loadMachineEnvFile(env);
const metadataPort = intFromEnv(
"METADATA_PORT",
env["METADATA_PORT"],
DEFAULT_METADATA_PORT,
{
min: 1,
max: 65535,
},
);
const refreshIntervalSec = intFromEnv(
"REFRESH_INTERVAL_SEC",
env["REFRESH_INTERVAL_SEC"],
DEFAULT_REFRESH_INTERVAL_SEC,
{ min: 1 },
);
const tokenSweepIntervalSec = intFromEnv(
"TOKEN_SWEEP_INTERVAL_SEC",
env["TOKEN_SWEEP_INTERVAL_SEC"],
DEFAULT_TOKEN_SWEEP_INTERVAL_SEC,
{ min: 1 },
);
const configuredAllowlist = firstConfiguredList(env, [
"KNOWN_SECRET_KEYS",
"EXPOSED_SECRET_KEYS",
"SECRET_ALLOWLIST",
"SECRET_WHITELIST",
]);
const secretAllowlist =
configuredAllowlist.length > 0
? configuredAllowlist
: [...getKnownSecretKeys()];
if (secretAllowlist.length === 0) {
console.warn(
"[Config] No secret allowlist configured; metadata secret routes will be empty.",
);
}
const infisicalEnvironment = parseEnvironment(env["INFISICAL_ENVIRONMENT"]);
return {
infisical: {
accessToken: required(env, "INFISICAL_ACCESS_TOKEN"),
projectId: required(env, "INFISICAL_PROJECT_ID"),
environment: infisicalEnvironment,
siteUrl: env["INFISICAL_SITE_URL"]?.trim() || DEFAULT_INFISICAL_SITE_URL,
},
metadataPort,
refreshIntervalMs: refreshIntervalSec * 1000,
tokenSweepIntervalMs: tokenSweepIntervalSec * 1000,
allowSecretsBundle: boolFromEnv(env["ALLOW_SECRETS_BUNDLE"], false),
secretAllowlist,
allowedHosts: buildAllowedHosts(env, metadataPort),
lanListener: {
enabled: boolFromEnv(env["LAN_LISTENER_ENABLED"], true),
host: env["LAN_LISTENER_HOST"]?.trim() || "0.0.0.0",
port: metadataPort,
},
linkLocalListener: {
enabled: boolFromEnv(env["LINK_LOCAL_LISTENER_ENABLED"], true),
host: env["LINK_LOCAL_HOST"]?.trim() || LINK_LOCAL_ADDRESS,
port: intFromEnv("LINK_LOCAL_PORT", env["LINK_LOCAL_PORT"], 80, {
min: 1,
max: 65535,
}),
},
machineEnvConfigPath,
machineMetadata: buildMachineMetadata(env, infisicalEnvironment),
};
}
+34
View File
@@ -0,0 +1,34 @@
import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
export function getSingleHeader(headers: IncomingHttpHeaders, name: string): string | undefined {
const value = headers[name.toLowerCase()];
if (Array.isArray(value)) return value[0];
return value;
}
export function sendText(
res: ServerResponse,
statusCode: number,
body = "",
headers: Record<string, string> = {},
): void {
res.writeHead(statusCode, {
"Content-Type": "text/plain; charset=utf-8",
"Cache-Control": "no-store",
...headers,
});
res.end(body);
}
export function sendJson(res: ServerResponse, statusCode: number, body: unknown): void {
res.writeHead(statusCode, {
"Content-Type": "application/json; charset=utf-8",
"Cache-Control": "no-store",
});
res.end(JSON.stringify(body));
}
export function requestPath(req: IncomingMessage): string {
const url = new URL(req.url ?? "/", "http://metadata.local");
return url.pathname;
}
+152
View File
@@ -0,0 +1,152 @@
import fs from "node:fs";
import os from "node:os";
import crypto from "node:crypto";
import type { InfisicalEnvironment } from "../common/secret-manager.js";
import type { EnvTarget } from "../common/dotenv.js";
export interface MachineMetadata {
hostname: string;
localHostname: string;
localIpv4: string;
mac: string;
machineId: string;
environment: InfisicalEnvironment;
role: string | undefined;
tags: Record<string, string>;
userData: string | undefined;
}
export interface InstanceIdentityDocument {
documentVersion: string;
service: "machine-env-service";
machineId: string;
hostname: string;
localHostname: string;
localIpV4: string;
mac: string;
environment: InfisicalEnvironment;
role?: string;
tags: Record<string, string>;
}
interface PrimaryNetworkIdentity {
localIpv4: string;
mac: string;
}
function readFirstExistingFile(paths: readonly string[]): string | undefined {
for (const filePath of paths) {
try {
const value = fs.readFileSync(filePath, "utf8").trim();
if (value) return value;
} catch {
// Missing OS-specific identity files are expected on some platforms.
}
}
return undefined;
}
function resolvePrimaryNetworkIdentity(): PrimaryNetworkIdentity {
for (const addresses of Object.values(os.networkInterfaces())) {
for (const address of addresses ?? []) {
if (address.family !== "IPv4" || address.internal) continue;
return {
localIpv4: address.address,
mac: address.mac || "00:00:00:00:00:00",
};
}
}
return {
localIpv4: "127.0.0.1",
mac: "00:00:00:00:00:00",
};
}
function fallbackMachineId(hostname: string, localIpv4: string, mac: string): string {
return crypto
.createHash("sha256")
.update(`${hostname}|${localIpv4}|${mac}`)
.digest("hex");
}
function parseTags(value: string | undefined): Record<string, string> {
const tags: Record<string, string> = {};
if (!value) return tags;
for (const rawPair of value.split(/[,\n]/)) {
const pair = rawPair.trim();
if (!pair) continue;
const separator = pair.indexOf("=");
if (separator <= 0) continue;
const key = pair.slice(0, separator).trim();
const tagValue = pair.slice(separator + 1).trim();
if (!key || key.includes("/")) continue;
tags[key] = tagValue;
}
return tags;
}
function readUserData(env: EnvTarget): string | undefined {
const inline = env["USER_DATA"] ?? env["MACHINE_USER_DATA"] ?? env["METADATA_USER_DATA"];
if (inline !== undefined) return inline;
const filePath = env["USER_DATA_FILE"] ?? env["MACHINE_USER_DATA_FILE"] ?? env["METADATA_USER_DATA_FILE"];
if (!filePath?.trim()) return undefined;
try {
return fs.readFileSync(filePath.trim(), "utf8");
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
console.warn(`[Config] Failed to read user-data file ${filePath}: ${message}`);
return undefined;
}
}
export function buildMachineMetadata(
env: EnvTarget,
environment: InfisicalEnvironment,
): MachineMetadata {
const hostname = env["MACHINE_HOSTNAME"]?.trim() || os.hostname();
const network = resolvePrimaryNetworkIdentity();
const localIpv4 = env["MACHINE_LOCAL_IPV4"]?.trim() || network.localIpv4;
const mac = env["MACHINE_MAC"]?.trim() || network.mac;
const machineId =
env["MACHINE_ID"]?.trim() ||
readFirstExistingFile(["/etc/machine-id", "/var/lib/dbus/machine-id"]) ||
fallbackMachineId(hostname, localIpv4, mac);
return {
hostname,
localHostname: env["MACHINE_LOCAL_HOSTNAME"]?.trim() || hostname,
localIpv4,
mac,
machineId,
environment,
role: env["MACHINE_ROLE"]?.trim() || env["METADATA_ROLE"]?.trim() || undefined,
tags: parseTags(env["MACHINE_TAGS"] ?? env["METADATA_TAGS"]),
userData: readUserData(env),
};
}
export function buildInstanceIdentityDocument(
metadata: MachineMetadata,
): InstanceIdentityDocument {
return {
documentVersion: "2026-05-01",
service: "machine-env-service",
machineId: metadata.machineId,
hostname: metadata.hostname,
localHostname: metadata.localHostname,
localIpV4: metadata.localIpv4,
mac: metadata.mac,
environment: metadata.environment,
...(metadata.role ? { role: metadata.role } : {}),
tags: metadata.tags,
};
}
+54
View File
@@ -0,0 +1,54 @@
#!/usr/bin/env node
import { loadEnvironmentFromNodeEnv } from "../common/env-loader.js";
import { loadConfig } from "./config.js";
import { MetadataServer } from "./server.js";
import { SecretCache } from "./store/secret-cache.js";
import { TokenStore } from "./store/token-store.js";
async function run(): Promise<void> {
if (!process.env["MACHINE_ENV_CONFIG"]) {
loadEnvironmentFromNodeEnv();
}
const config = loadConfig();
const secretCache = new SecretCache({
infisical: config.infisical,
allowlist: config.secretAllowlist,
refreshIntervalMs: config.refreshIntervalMs,
});
const tokenStore = new TokenStore(config.tokenSweepIntervalMs);
const server = new MetadataServer({ config, secretCache, tokenStore });
tokenStore.start();
await secretCache.start();
await server.start();
const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
console.info(`[Main] Received ${signal}; shutting down.`);
process.off("SIGTERM", onSigterm);
process.off("SIGINT", onSigint);
try {
await server.stop();
secretCache.stop();
tokenStore.stop();
process.exitCode = 0;
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
console.error(`[Main] Shutdown failed: ${message}`);
process.exitCode = 1;
}
};
const onSigterm = (): void => void shutdown("SIGTERM");
const onSigint = (): void => void shutdown("SIGINT");
process.on("SIGTERM", onSigterm);
process.on("SIGINT", onSigint);
}
run().catch((error: unknown) => {
const message = error instanceof Error ? error.message : String(error);
console.error(`[Main] Failed to start: ${message}`);
process.exitCode = 1;
});
+47
View File
@@ -0,0 +1,47 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { getSingleHeader, requestPath, sendText } from "../http-utils.js";
export interface SsrfGuardOptions {
allowedHosts: readonly string[];
}
function normalizeHost(host: string): string {
const trimmed = host.trim().toLowerCase();
if (!trimmed) return trimmed;
if (trimmed.startsWith("[")) {
const closingBracket = trimmed.indexOf("]");
return closingBracket === -1 ? trimmed : trimmed.slice(1, closingBracket);
}
const colon = trimmed.lastIndexOf(":");
if (colon === -1) return trimmed;
const maybePort = trimmed.slice(colon + 1);
if (/^\d+$/.test(maybePort)) return trimmed.slice(0, colon);
return trimmed;
}
export function ssrfGuard(
req: IncomingMessage,
res: ServerResponse,
options: SsrfGuardOptions,
): boolean {
if (getSingleHeader(req.headers, "x-forwarded-for") !== undefined) {
sendText(res, 403);
return false;
}
const host = getSingleHeader(req.headers, "host");
if (!host || !options.allowedHosts.includes(normalizeHost(host))) {
sendText(res, 403);
return false;
}
if (requestPath(req) === "/latest/api/token" && req.method !== "PUT") {
res.setHeader("Allow", "PUT");
sendText(res, 405);
return false;
}
return true;
}
+19
View File
@@ -0,0 +1,19 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { getSingleHeader, sendText } from "../http-utils.js";
import type { TokenStore } from "../store/token-store.js";
const TOKEN_HEADER = "x-aws-ec2-metadata-token";
export function requireMetadataToken(
req: IncomingMessage,
res: ServerResponse,
tokenStore: TokenStore,
): boolean {
const token = getSingleHeader(req.headers, TOKEN_HEADER);
if (!tokenStore.validate(token)) {
sendText(res, 401);
return false;
}
return true;
}
+49
View File
@@ -0,0 +1,49 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { requestPath, sendJson, sendText } from "../http-utils.js";
import {
buildInstanceIdentityDocument,
type MachineMetadata,
} from "../machine-metadata.js";
const DYNAMIC_ROOT = "/latest/dynamic/";
const INSTANCE_IDENTITY_ROOT = "/latest/dynamic/instance-identity/";
export function handleDynamicRequest(
req: IncomingMessage,
res: ServerResponse,
metadata: MachineMetadata,
): void {
if (req.method !== "GET") {
res.setHeader("Allow", "GET");
sendText(res, 405);
return;
}
const pathname = requestPath(req);
if (pathname === "/latest/dynamic") {
sendText(res, 301, "", { Location: DYNAMIC_ROOT });
return;
}
if (pathname === DYNAMIC_ROOT) {
sendText(res, 200, "instance-identity/\n");
return;
}
if (pathname === "/latest/dynamic/instance-identity") {
sendText(res, 301, "", { Location: INSTANCE_IDENTITY_ROOT });
return;
}
if (pathname === INSTANCE_IDENTITY_ROOT) {
sendText(res, 200, "document\n");
return;
}
if (pathname === "/latest/dynamic/instance-identity/document") {
sendJson(res, 200, buildInstanceIdentityDocument(metadata));
return;
}
sendText(res, 404);
}
+186
View File
@@ -0,0 +1,186 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { requestPath, sendText } from "../http-utils.js";
import type { MachineMetadata } from "../machine-metadata.js";
import type { SecretCache } from "../store/secret-cache.js";
import {
handleSecretsBundle,
handleSecretsDirectory,
handleSecretValue,
} from "./secrets.js";
const META_DATA_ROOT = "/latest/meta-data/";
const SECRETS_PREFIX = "/latest/meta-data/secrets/";
const TAGS_PREFIX = "/latest/meta-data/tags/";
const INSTANCE_TAGS_PREFIX = "/latest/meta-data/tags/instance/";
export interface MetadataRouteOptions {
cache: SecretCache;
allowSecretsBundle: boolean;
machineMetadata: MachineMetadata;
}
function listRootEntries(options: MetadataRouteOptions): string {
const entries = [
"environment",
"hostname",
"local-hostname",
"local-ipv4",
"mac",
"machine-id",
"secrets/",
"tags/",
];
if (options.machineMetadata.role) entries.push("role");
if (options.allowSecretsBundle) entries.push("secrets-bundle");
return `${entries.sort().join("\n")}\n`;
}
function decodePathSegment(segment: string): string | null {
try {
const decoded = decodeURIComponent(segment);
if (!decoded || decoded.includes("/")) return null;
return decoded;
} catch {
return null;
}
}
function sendOptionalText(res: ServerResponse, value: string | undefined): void {
if (value === undefined) {
sendText(res, 404);
return;
}
sendText(res, 200, value);
}
function handleTagsRequest(
pathname: string,
res: ServerResponse,
metadata: MachineMetadata,
): boolean {
if (pathname === "/latest/meta-data/tags") {
sendText(res, 301, "", { Location: TAGS_PREFIX });
return true;
}
if (pathname === TAGS_PREFIX) {
sendText(res, 200, "instance/\n");
return true;
}
if (pathname === "/latest/meta-data/tags/instance") {
sendText(res, 301, "", { Location: INSTANCE_TAGS_PREFIX });
return true;
}
if (pathname === INSTANCE_TAGS_PREFIX) {
const keys = Object.keys(metadata.tags).sort();
sendText(res, 200, keys.length === 0 ? "" : `${keys.join("\n")}\n`);
return true;
}
if (pathname.startsWith(INSTANCE_TAGS_PREFIX)) {
const key = decodePathSegment(pathname.slice(INSTANCE_TAGS_PREFIX.length));
if (!key) {
sendText(res, 404);
return true;
}
sendOptionalText(res, metadata.tags[key]);
return true;
}
if (pathname.startsWith(TAGS_PREFIX)) {
const key = decodePathSegment(pathname.slice(TAGS_PREFIX.length));
if (!key || key === "instance") {
sendText(res, 404);
return true;
}
sendOptionalText(res, metadata.tags[key]);
return true;
}
return false;
}
export function handleMetadataRequest(
req: IncomingMessage,
res: ServerResponse,
options: MetadataRouteOptions,
): void {
if (req.method !== "GET") {
res.setHeader("Allow", "GET");
sendText(res, 405);
return;
}
const pathname = requestPath(req);
if (pathname === "/latest/meta-data") {
sendText(res, 301, "", { Location: META_DATA_ROOT });
return;
}
if (pathname === META_DATA_ROOT) {
sendText(res, 200, listRootEntries(options));
return;
}
if (pathname === "/latest/meta-data/environment") {
sendText(res, 200, options.machineMetadata.environment);
return;
}
if (pathname === "/latest/meta-data/hostname") {
sendText(res, 200, options.machineMetadata.hostname);
return;
}
if (pathname === "/latest/meta-data/local-hostname") {
sendText(res, 200, options.machineMetadata.localHostname);
return;
}
if (pathname === "/latest/meta-data/local-ipv4") {
sendText(res, 200, options.machineMetadata.localIpv4);
return;
}
if (pathname === "/latest/meta-data/mac") {
sendText(res, 200, options.machineMetadata.mac);
return;
}
if (pathname === "/latest/meta-data/machine-id") {
sendText(res, 200, options.machineMetadata.machineId);
return;
}
if (pathname === "/latest/meta-data/role") {
sendOptionalText(res, options.machineMetadata.role);
return;
}
if (handleTagsRequest(pathname, res, options.machineMetadata)) {
return;
}
if (pathname === SECRETS_PREFIX) {
handleSecretsDirectory(res, options.cache);
return;
}
if (pathname.startsWith(SECRETS_PREFIX)) {
handleSecretValue(pathname, res, options.cache);
return;
}
if (pathname === "/latest/meta-data/secrets-bundle") {
handleSecretsBundle(res, options.cache, options.allowSecretsBundle);
return;
}
sendText(res, 404);
}
+50
View File
@@ -0,0 +1,50 @@
import type { ServerResponse } from "node:http";
import { sendJson, sendText } from "../http-utils.js";
import type { SecretCache } from "../store/secret-cache.js";
const SECRETS_PREFIX = "/latest/meta-data/secrets/";
function decodeSecretKey(rawKey: string): string | null {
try {
const decoded = decodeURIComponent(rawKey);
if (!decoded || decoded.includes("/")) return null;
return decoded;
} catch {
return null;
}
}
export function handleSecretsDirectory(res: ServerResponse, cache: SecretCache): void {
const keys = cache.list();
sendText(res, 200, keys.length === 0 ? "" : `${keys.join("\n")}\n`);
}
export function handleSecretValue(pathname: string, res: ServerResponse, cache: SecretCache): void {
const rawKey = pathname.slice(SECRETS_PREFIX.length);
const key = decodeSecretKey(rawKey);
if (!key || !cache.isAllowed(key)) {
sendText(res, 404);
return;
}
const value = cache.get(key);
if (value === undefined) {
sendText(res, 404);
return;
}
sendText(res, 200, value);
}
export function handleSecretsBundle(
res: ServerResponse,
cache: SecretCache,
enabled: boolean,
): void {
if (!enabled) {
sendText(res, 404);
return;
}
sendJson(res, 200, cache.bundle());
}
+39
View File
@@ -0,0 +1,39 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { getSingleHeader, sendText } from "../http-utils.js";
import {
MAX_TOKEN_TTL_SECONDS,
MIN_TOKEN_TTL_SECONDS,
type TokenStore,
} from "../store/token-store.js";
const TTL_HEADER = "x-aws-ec2-metadata-token-ttl-seconds";
function parseTokenTtl(req: IncomingMessage): number | null {
const raw = getSingleHeader(req.headers, TTL_HEADER);
if (!raw) return null;
const ttl = Number.parseInt(raw, 10);
if (!Number.isInteger(ttl) || String(ttl) !== raw.trim()) return null;
if (ttl < MIN_TOKEN_TTL_SECONDS || ttl > MAX_TOKEN_TTL_SECONDS) return null;
return ttl;
}
export function handleTokenRequest(
req: IncomingMessage,
res: ServerResponse,
tokenStore: TokenStore,
): void {
if (req.method !== "PUT") {
res.setHeader("Allow", "PUT");
sendText(res, 405);
return;
}
const ttl = parseTokenTtl(req);
if (ttl === null) {
sendText(res, 400);
return;
}
sendText(res, 200, tokenStore.issue(ttl));
}
+22
View File
@@ -0,0 +1,22 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { sendText } from "../http-utils.js";
import type { MachineMetadata } from "../machine-metadata.js";
export function handleUserDataRequest(
req: IncomingMessage,
res: ServerResponse,
metadata: MachineMetadata,
): void {
if (req.method !== "GET") {
res.setHeader("Allow", "GET");
sendText(res, 405);
return;
}
if (metadata.userData === undefined) {
sendText(res, 404);
return;
}
sendText(res, 200, metadata.userData);
}
+120
View File
@@ -0,0 +1,120 @@
import http, { type IncomingMessage, type Server, type ServerResponse } from "node:http";
import type { DaemonConfig, ListenerConfig } from "./config.js";
import { requestPath, sendText } from "./http-utils.js";
import { ssrfGuard } from "./middleware/ssrf-guard.js";
import { requireMetadataToken } from "./middleware/token-auth.js";
import { handleDynamicRequest } from "./routes/dynamic.js";
import { handleMetadataRequest } from "./routes/metadata.js";
import { handleTokenRequest } from "./routes/token.js";
import { handleUserDataRequest } from "./routes/user-data.js";
import type { SecretCache } from "./store/secret-cache.js";
import type { TokenStore } from "./store/token-store.js";
export interface MetadataServerOptions {
config: DaemonConfig;
secretCache: SecretCache;
tokenStore: TokenStore;
}
interface RunningServer {
name: string;
server: Server;
}
export class MetadataServer {
private readonly servers: RunningServer[] = [];
private closing = false;
constructor(private readonly options: MetadataServerOptions) {}
async start(): Promise<void> {
const listeners = [
{ name: "link-local", config: this.options.config.linkLocalListener },
{ name: "lan", config: this.options.config.lanListener },
];
for (const listener of listeners) {
if (!listener.config.enabled) continue;
await this.listen(listener.name, listener.config);
}
}
async stop(): Promise<void> {
this.closing = true;
await Promise.all(
this.servers.map(
({ server }) =>
new Promise<void>((resolve, reject) => {
server.close((error) => {
if (error) reject(error);
else resolve();
});
}),
),
);
this.servers.length = 0;
}
private async listen(name: string, config: ListenerConfig): Promise<void> {
const server = http.createServer((req, res) => this.handleRequest(req, res));
await new Promise<void>((resolve, reject) => {
const onError = (error: Error): void => {
server.off("listening", onListening);
reject(error);
};
const onListening = (): void => {
server.off("error", onError);
resolve();
};
server.once("error", onError);
server.once("listening", onListening);
server.listen(config.port, config.host);
});
this.servers.push({ name, server });
console.info(`[Server] ${name} listener ready on ${config.host}:${config.port}`);
}
private handleRequest(req: IncomingMessage, res: ServerResponse): void {
if (this.closing) {
sendText(res, 503);
return;
}
if (!ssrfGuard(req, res, { allowedHosts: this.options.config.allowedHosts })) {
return;
}
const pathname = requestPath(req);
if (pathname === "/latest/api/token") {
handleTokenRequest(req, res, this.options.tokenStore);
return;
}
if (pathname === "/latest/meta-data" || pathname.startsWith("/latest/meta-data/")) {
if (!requireMetadataToken(req, res, this.options.tokenStore)) return;
handleMetadataRequest(req, res, {
cache: this.options.secretCache,
allowSecretsBundle: this.options.config.allowSecretsBundle,
machineMetadata: this.options.config.machineMetadata,
});
return;
}
if (pathname === "/latest/dynamic" || pathname.startsWith("/latest/dynamic/")) {
if (!requireMetadataToken(req, res, this.options.tokenStore)) return;
handleDynamicRequest(req, res, this.options.config.machineMetadata);
return;
}
if (pathname === "/latest/user-data") {
if (!requireMetadataToken(req, res, this.options.tokenStore)) return;
handleUserDataRequest(req, res, this.options.config.machineMetadata);
return;
}
sendText(res, 404);
}
}
+88
View File
@@ -0,0 +1,88 @@
import {
fetchInfisicalSecrets,
type InfisicalSecretConfig,
type RawSecretMap,
} from "../../common/secret-manager.js";
export interface SecretCacheOptions {
infisical: InfisicalSecretConfig;
allowlist: readonly string[];
refreshIntervalMs: number;
}
export class SecretCache {
private readonly allowedKeys: Set<string>;
private secrets = new Map<string, string>();
private refreshTimer: NodeJS.Timeout | undefined;
private refreshInFlight: Promise<void> | undefined;
lastRefreshAt: Date | undefined;
lastError: Error | undefined;
constructor(private readonly options: SecretCacheOptions) {
this.allowedKeys = new Set(options.allowlist);
}
async start(): Promise<void> {
await this.refresh();
if (this.refreshTimer) return;
this.refreshTimer = setInterval(() => {
void this.refresh();
}, this.options.refreshIntervalMs);
this.refreshTimer.unref();
}
stop(): void {
if (!this.refreshTimer) return;
clearInterval(this.refreshTimer);
this.refreshTimer = undefined;
}
async refresh(): Promise<void> {
if (this.refreshInFlight) return this.refreshInFlight;
this.refreshInFlight = this.fetchAndSwap()
.catch((error: unknown) => {
this.lastError = error instanceof Error ? error : new Error(String(error));
console.error(`[SecretCache] Refresh failed: ${this.lastError.message}`);
})
.finally(() => {
this.refreshInFlight = undefined;
});
return this.refreshInFlight;
}
get(key: string): string | undefined {
if (!this.allowedKeys.has(key)) return undefined;
return this.secrets.get(key);
}
isAllowed(key: string): boolean {
return this.allowedKeys.has(key);
}
list(): string[] {
return [...this.secrets.keys()].sort();
}
bundle(): RawSecretMap {
return Object.fromEntries([...this.secrets.entries()].sort(([left], [right]) => left.localeCompare(right)));
}
private async fetchAndSwap(): Promise<void> {
const fetched = await fetchInfisicalSecrets(this.options.infisical, this.options.allowlist);
const next = new Map<string, string>();
for (const key of this.allowedKeys) {
const value = fetched.raw[key];
if (value !== undefined) next.set(key, value);
}
this.secrets = next;
this.lastError = undefined;
this.lastRefreshAt = new Date();
console.info(`[SecretCache] Loaded ${this.secrets.size} allowed secret(s).`);
}
}
+59
View File
@@ -0,0 +1,59 @@
import crypto from "node:crypto";
export const MIN_TOKEN_TTL_SECONDS = 1;
export const MAX_TOKEN_TTL_SECONDS = 21_600;
export class TokenStore {
private readonly tokens = new Map<string, number>();
private sweepTimer: NodeJS.Timeout | undefined;
constructor(private readonly sweepIntervalMs: number) {}
start(): void {
if (this.sweepTimer) return;
this.sweepTimer = setInterval(() => this.sweepExpired(), this.sweepIntervalMs);
this.sweepTimer.unref();
}
stop(): void {
if (!this.sweepTimer) return;
clearInterval(this.sweepTimer);
this.sweepTimer = undefined;
this.tokens.clear();
}
issue(ttlSeconds: number): string {
if (ttlSeconds < MIN_TOKEN_TTL_SECONDS || ttlSeconds > MAX_TOKEN_TTL_SECONDS) {
throw new Error(
`Token TTL must be between ${MIN_TOKEN_TTL_SECONDS} and ${MAX_TOKEN_TTL_SECONDS} seconds`,
);
}
const token = crypto.randomBytes(32).toString("base64url");
this.tokens.set(token, Date.now() + ttlSeconds * 1000);
return token;
}
validate(token: string | undefined): boolean {
if (!token) return false;
const expiresAt = this.tokens.get(token);
if (!expiresAt) return false;
if (expiresAt <= Date.now()) {
this.tokens.delete(token);
return false;
}
return true;
}
sweepExpired(now = Date.now()): number {
let removed = 0;
for (const [token, expiresAt] of this.tokens) {
if (expiresAt > now) continue;
this.tokens.delete(token);
removed += 1;
}
return removed;
}
}
+15
View File
@@ -0,0 +1,15 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"skipLibCheck": true,
"types": ["node"]
},
"include": ["src/**/*.ts"]
}