# Milestone: 정책, 이력, 감사

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/control-plane-portal-ops/PHASE.md`

## 목표

권한, 정책, 실행 이력, 감사 로그를 제품 운영에 필요한 수준으로 확장한다.
특히 원격 터미널 브리지와 agent bootstrap은 보안/감사 요구사항을 필수 전제로 둔다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 해제 근거: 2026-06-03 실행 요청에 따라 아래 `정책 기준`을 보수적 기본값으로 채택한다.

## 정책 기준

- Audit 기록 수준과 보존
  - terminal session, bootstrap, enrollment는 actor, source, target, request/session id, policy decision, credential reference id, command metadata, lifecycle timestamp, exit status/error, redaction marker를 구조화 이벤트로 기록한다.
  - terminal raw input/output payload와 secret 원문은 기본 저장하지 않는다.
  - session transcript 저장이 필요하면 opt-in, redaction, retention override를 갖춘 별도 정책으로만 허용한다.
  - 기본 보존은 Edge local audit/history 30일, Control Plane 집계 metadata 90일로 둔다. 배포 환경 설정으로 축소 또는 연장할 수 있다.
- Policy enforcement 위치
  - Control Plane은 사용자/조직 정책 preflight, fleet policy 배포, 집계 리포트 경계를 담당한다.
  - Edge는 Node dispatch 전 local effective policy를 적용하는 authoritative enforcement 지점이다. Control Plane이 없어도 Edge는 로컬 정책을 집행한다.
  - Node는 runtime guardrail, target/credential scope 검증, 실행 제한의 최종 방어선을 담당하며 제품 정책의 소유자가 아니다.
- Credential과 target allowlist 소유
  - Control Plane은 fleet policy template과 운영자 workflow를 소유한다.
  - Edge는 runtime source of truth로 local effective allowlist와 credential reference를 소유한다.
  - Node는 scoped, ephemeral credential material만 소비하며 장기 secret 원본을 저장하지 않는다.
- History와 audit 부착 경계
  - 기존 실행 파이프라인의 adapter/runtime 계약을 깨지 않고 request accepted, policy evaluated, dispatched, started, streamed, completed, failed/canceled lifecycle hook에 audit 기록을 붙인다.
  - Edge는 실행 이력과 audit event 원본을 보관하고, Control Plane은 조회/집계 projection만 유지한다.
  - Node는 실행 결과와 runtime guardrail event를 Edge로 보고하지만 Edge 상태 소유권을 대체하지 않는다.
- Audit event 초안
  - `execution.requested`, `execution.policy_evaluated`, `execution.dispatched`, `execution.started`, `execution.completed`, `execution.failed`, `execution.canceled`
  - `terminal.session_requested`, `terminal.session_started`, `terminal.command_submitted`, `terminal.command_completed`, `terminal.session_closed`
  - `bootstrap.enrollment_requested`, `bootstrap.credential_issued`, `bootstrap.node_registered`, `bootstrap.enrollment_failed`, `bootstrap.revoked`

## 범위

- permission model과 policy enforcement 지점 정리
- Edge/Node 실행 이력과 Control Plane aggregation 경계
- command/session audit 구조 설계
- credential 관리와 target allowlist 모델
- timeout, 동시 실행 제한, 입력/출력 기록 정책
- metrics/event API와 운영 리포트 후보

## 기능

### Epic: [policy-audit-boundary] Policy and Audit Boundary

- [x] [edge-source] Edge는 로컬 런타임 상태와 실행 이력의 원본을 유지한다.
- [x] [cp-aggregation] Control Plane은 Edge 데이터를 조회/집계하되 Edge 내부 상태 소유권을 대체하지 않는다.
- [x] [terminal-audit] 원격 터미널 브리지는 target allowlist, credential 관리, command/session audit를 필수로 요구하고, 실행 요청, command, terminal session, bootstrap/enrollment audit event 초안을 포함한다.
- [x] [policy-location] 권한과 policy가 Edge/Control Plane/Node 경계 중 어디에서 적용되는지 문서화된다.
- [x] [history-attach] 기존 실행 파이프라인을 깨지 않고 history/audit 수집을 붙일 수 있는 경계를 정의한다.
- [x] [schema-evidence] policy/audit 상세 schema는 구현 단계에서 명확한 evidence와 함께 확정한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-03
- 완료 근거: 정책 기준 문서화로 `edge-source`, `cp-aggregation`, `terminal-audit`, `policy-location`, `history-attach`가 충족되었다. `schema-evidence`는 tracked `packages/go/audit/audit.go`의 공통 audit event schema와 `packages/go/audit/audit_test.go`의 event type, required field, retention/default, metadata copy 검증으로 충족되었다. 검증: `go test ./packages/go/audit`.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-03 사용자 요청으로 완료 승인 후 archive 이동한다.

## 범위 제외

- 상세 DB schema를 근거 없이 선확정
- 모든 이벤트를 Control Plane 단일 저장소로 강제
- 보안 전제가 없는 terminal bridge 또는 insecure bootstrap 기본값

## 작업 컨텍스트

- 관련 경로: `apps/edge`, `apps/node`, `apps/control-plane`, `packages/go/audit`, `packages/go/auth`, `packages/go/jobs`
- 표준선: Edge는 로컬 실행 이력 원본을 유지하고, Control Plane은 필요한 범위에서 조회/집계한다.
- 선행 작업: 원격 터미널 브리지 POC, Agent Bootstrap과 OTO 등록, Control Plane과 Client
- 후속 작업: Multi-Edge 운영
- 활성 계획: 없음
- 계획 필요: 없음. 공통 audit schema 계약은 `packages/go/audit` evidence로 충족되었고, persistence boundary와 metrics/event API 반영은 후속 계획에서 다룬다.
