# Edge bootstrap 계약

## 목표

Jenkins node 연결식 UX를 Edge 중심 bootstrap 경험으로 재해석한다.
Edge에서 OTO agent를 생성하고 대상 머신에서 실행할 bootstrap command를 발급하는 UX와 설치/등록 계약을 정의한다.

## 단계

Edge 직접 연결 기반 `oto-agent`

## 상태

완료

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- Jenkins node를 연결하듯 Edge에서 OTO agent를 생성하고 대상 Linux 머신에서 실행할 bootstrap script를 발급하는 사용자 흐름을 정의한다.
- 대상 머신에는 OTO가 없다고 가정하고, bootstrap script가 OTO repo release asset URL에서 Linux용 OTO 바이너리를 다운로드해 실행 가능한 상태로 만든다.
- Edge는 bootstrap script에 다운로드 URL, agent 식별 값, Edge 연결 정보를 포함해 제공한다.
- 다운로드된 OTO는 `~/.oto/agent/config.yaml`을 생성하거나 갱신하고, 백그라운드 등록/실행을 기본 방향으로 한다.
- Edge 등록 완료와 최초 heartbeat 도착을 online 판정 기준으로 둔다.
- HTTPS, checksum, signature, fingerprint 같은 보안 강화 항목은 MVP 구현 차단 조건이 아니라 후속 강화 범위로 분리한다.

## 필수 기능

- [x] [edge-user-flow] Edge에서 agent 생성 후 bootstrap command를 발급하는 사용자 흐름이 정의되어 있다.
- [x] [command-shape] bootstrap command 형식과 필수 인자가 정의되어 있다.
- [x] [binary-select] Linux 대상 OTO repo release asset 다운로드와 arch 선택 규칙이 정의되어 있다.
- [x] [config-path] agent 설정 생성 경로와 필수 설정 값이 정의되어 있다.
- [x] [background-start] 다운로드 후 `oto-agent`를 백그라운드 등록/실행하는 기준이 정의되어 있다.
- [x] [security-modes] 보안 강화 항목이 MVP 차단 조건과 후속 강화 범위로 분리되어 있다.

## 완료 기준

- [x] Jenkins node 연결식 경험과 비교해 사용자가 Edge bootstrap 흐름을 이해할 수 있다.
- [x] 사용자가 Edge에서 발급받은 script 하나로 OTO가 없는 Linux 대상 머신에서 OTO 다운로드와 실행을 시작할 수 있는 흐름이 설명된다.
- [x] `~/.oto/agent/config.yaml` 기준 설정 생성과 백그라운드 실행 기준이 설명된다.
- [x] Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 상태 기준이 설명된다.
- [x] 보안 강화 항목이 MVP 범위와 후속 강화 범위로 구분되어 구현을 막지 않는다.

## 범위 제외

- 실제 Edge 서버 API를 구현하지 않는다.
- 메시지 기반 run request 프로토콜을 구현하지 않는다.
- iop-node 연동을 추가하지 않는다.
- Linux 외 OS의 bootstrap script를 정의하지 않는다.
- checksum, signature, Edge fingerprint, credential rotation 같은 운영 보안 강화 구현을 포함하지 않는다.

## 작업 컨텍스트

- 기존 packaging 자료와 설치 스크립트(`assets/package/**`, `assets/script/**`)를 먼저 확인한다.
- 표준선(선택): Linux MVP는 사용자 홈 기반 설치를 우선하고, 설정 파일은 `~/.oto/agent/config.yaml`을 사용한다.
- 표준선(선택): Edge는 OTO repo release asset URL을 bootstrap script에 포함해 제공하며, 나중에 필요하면 같은 계약을 유지한 채 artifact 서버나 Edge download URL 뒤로 옮길 수 있다.
- 표준선(선택): 백그라운드 실행은 사용자 권한으로 가능한 등록 방식을 우선하고, 등록 실패 시 사용자가 실행 상태를 확인할 수 있는 fallback을 둔다.
- 표준선(선택): 보안은 최소 agent 식별 값과 Edge 연결 정보 전달을 먼저 두고, checksum/signature/fingerprint/credential rotation은 후속 강화로 둔다.
- MVP 계약 기준(확정): Edge는 agent 생성 후 Linux 대상에서 바로 실행할 one-line bootstrap command를 발급한다.
  - 표준 command 형식:
    ```bash
    curl -fsSL "${OTO_BOOTSTRAP_URL}" | bash -s -- \
      --edge-url "${EDGE_URL}" \
      --agent-id "${AGENT_ID}" \
      --enrollment-token "${ENROLLMENT_TOKEN}" \
      --release-base-url "${OTO_RELEASE_BASE_URL}" \
      --agent-alias "${AGENT_ALIAS}"
    ```
  - 필수 인자: `--edge-url`, `--agent-id`, `--enrollment-token`, `--release-base-url`.
  - 선택 인자: `--agent-alias`, `--install-dir`, `--config-path`, `--workspace-root`, `--log-dir`, `--no-background`.
  - 기본 경로: `--install-dir=$HOME/.oto/bin`, `--config-path=$HOME/.oto/agent/config.yaml`, `--workspace-root=$HOME/.oto/workspace`, `--log-dir=$HOME/.oto/agent/log`.
- MVP 계약 기준(확정): Linux arch 선택은 대상 머신에서 `uname -m`으로 수행한다.
  - `x86_64`, `amd64`는 `oto-linux-x64.tar.gz` release asset을 사용한다.
  - `aarch64`, `arm64`는 `oto-linux-arm64.tar.gz` release asset을 사용한다.
  - 그 외 arch는 다운로드 전에 실패하고, 지원되지 않는 arch 값을 출력한다.
  - release asset archive에는 실행 파일 `oto`가 포함되어 있어야 한다.
- MVP 계약 기준(확정): bootstrap script는 `~/.oto/agent/config.yaml`을 생성하거나 갱신한다.
  - 필수 설정 값: `agent.id`, `agent.alias`, `agent.enrollment_token`, `edge.url`, `runtime.install_dir`, `runtime.workspace_root`, `runtime.log_dir`.
  - 설정 파일과 상위 디렉터리는 사용자 홈 기준으로 만들고, 설정 파일 권한은 가능하면 `600`으로 제한한다.
- MVP 계약 기준(확정): background 실행은 사용자 권한의 best-effort 방식으로 시작한다.
  - 기본 실행은 `oto agent run --config "$config_path"`를 background로 시작하고, stdout/stderr는 `log_dir` 아래 로그 파일로 보낸다.
  - 시작한 프로세스 pid는 `~/.oto/agent/oto-agent.pid`에 기록한다.
  - `--no-background`가 있으면 foreground 실행 command만 출력하거나 그대로 실행해 디버깅 가능하게 둔다.
  - background 시작 실패는 등록 실패와 구분해 사용자에게 로그 경로와 재실행 command를 출력한다.
- MVP 계약 기준(확정): 보안 강화는 MVP 차단 조건과 후속 강화로 분리한다.
  - MVP 차단 조건: bootstrap URL과 release base URL은 HTTPS를 기본으로 요구하고, enrollment token은 command 출력 이후 재출력하지 않는다.
  - MVP best-effort: 설정 파일 권한 제한, 임시 다운로드 파일 정리, token이 포함된 shell trace 비활성화.
  - 후속 강화: checksum/signature 검증, Edge fingerprint pinning, 단기 enrollment token 만료/회전, systemd user service 설치.
- framework, cli 도메인 rule이 관련될 수 있다.
- 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
- 선행 iop Milestone: `../iop/agent-roadmap/milestones/agent-bootstrap-oto-enrollment.md`
- 책임 경계: iop는 Edge의 agent 생성, bootstrap script 발급 표면, registry, credential 원천을 소유한다.
- 책임 경계: OTO는 release asset, Linux 설치 산출물, 설정 파일 생성, 백그라운드 실행 시작 기준을 소유한다.
- 재개 기준: 사용자 결정으로 Jenkins node식 Linux bootstrap 흐름을 기준선으로 확정했으므로 OTO 계약 정리를 진행할 수 있다.
- 구현 근거: 실제 Linux bootstrap script는 `assets/script/shell/oto_agent_bootstrap.sh`, 검증은 `test/oto_agent_bootstrap_script_test.dart`에 있다.
