AriWeb-Suite/docs/HAL-SETTINGS.md

# HAL 통합 설정 관제 (Ariweb Suite 0.4.0)

HAL 이 도입 모듈·Node Agent 의 **서버 단위 설정**을 대신 관리한다. 개발 지시 `Ariweb-Suitle_Dev-Order_v0.4.0.md`(Oz).

## 1. 무엇을 관리하나
| 모듈 | 묶음 | 대표 항목 |
|---|---|---|
| Webmaker 1.9.0 | API 키·인증 | `auth.mode`·`auth.apiKey`·`auth.oauthToken`·`serviceApiKey`·`backlogKey`·`mail.apiKey`·`source.token`·`ariweb.secret`·`mail.adminPassword` |
| | 마진·가격 정책 | `marginPct`·`fx.mode/manualRate/spreadPct`·`signupCredit`·`maxEdits`·`defaultTier`·`tiers.*`·`signupApproval` |
| | 모델 | `internalRef`·`defaultModel`·`claudeModels`·`ai.*MaxTurns`·`ai.maxJobMinutes`·`ai.maxConcurrentJobs`·`ai.codexSandbox` |
| | 전체 적용 서비스 | `service.allowSignup`·`letsEncryptEmail`·`mail.fromName/defaultDomain/formBase`·`ariweb.portalUrl`·`endpoints.*`·`limits.*`·`ssl.acmeWaitMin` |
| | 서버별 설정(서버 범위만) | `service.publicBaseUrl/formBaseUrl/siteOrigin/trustedProxies/internalAllow`·`ai.claudeBin/codexBin`·`source.*`·`mail.provider/url/apiUrl/domain/adminLogin/nickname/ip`·`ssl.acmeDir` |
| AriMail 1.1.0 | 서버 단위 | 수·발신 방식, Resend, DNS 제공자, SMTP 중계, 내장 Haraka(서버 범위), 표시·동기화, 사용량 API, Ariweb SSO |
| Node Agent 0.4.0 | Agent | `heartbeatMs` |

- **관리하지 않는 것**: AriMail 도메인별 관리(추가 도메인 설정·`LIMIT_*`·계정·메일함 — 메일 서버 사용자가 직접), Webmaker 사이트·회원·템플릿·테마 등 콘텐츠.
- 목록 정의: `hal/settings/catalog.mjs`(형식 text·int·number·bool·enum·list·url·path·secret, 범위, 재시작 필요).

## 2. 저장·유효값
- `managed_settings(scope, module, key, value_json, is_secret)` — scope `global` | `server:<서버 id>`. 비밀값은 HAL Vault `managed:<scope>:<module>:<key>` 에만, 행에는 참조만(마이그레이션 `hal_0010_managed_settings`).
- 유효값 = 전체 ← 서버 덮어쓰기. hash = `sha256:` + 모듈·유효값(비밀값 포함)의 정규 JSON sha256.
- `managed_settings_state(server_id, module, applied_hash, applied_at, status, error, job_id)` — 적용 상태. `upToDate` = 마지막 적용 hash 가 지금 유효값 hash 와 같음.

## 3. API(운영자 세션·CSRF)
| 경로 | 설명 |
|---|---|
| `GET /ops/api/settings` | 모듈 목록·설정 목록·모듈별 개요(배치 서버·적용 상태·적용 필요 수) |
| `GET /ops/api/settings/:module?scope=` | 저장된 값(비밀값은 있음/없음), 서버 범위면 유효값·적용 상태 |
| `PUT /ops/api/settings/:module {scope, values}` | 저장(재인증 10분). null·빈 값 = 지정 삭제. 형식 오류·모르는 항목 400 `bad_setting` |
| `DELETE /ops/api/settings/:module/:key?scope=` | 지정 삭제(재인증) |
| `POST /ops/api/settings/:module/apply {serverIds, restart}` | 적용 작업(재인증). 대상 비우면 배치 서버 전체, 없으면 400 `no_targets`, 배치 안 된 서버 400 `not_placed` |
| `GET /agent/v1/settings/:module` | Agent HMAC. 자기 서버 범위의 유효값(비밀값 포함)·hash |

감사 기록(`settings.set`·`settings.apply`)에는 키 이름만 남는다.

## 4. 적용 흐름
`settings.apply`(부모) → 서버마다 `settings.apply.target` → Agent `module.configure`:
1. 작업 payload 에는 hash 만(비밀값 없음). Agent 가 `/agent/v1/settings/:module` 에서 직접 받고 hash 가 다르면 `settings_hash_mismatch`(그 사이 설정이 바뀜).
2. `<configDir>/hal-managed.json`(0600) 원자 교체. 실행 계정이 다르면 `module-as-user.sh write --mode 600`. configDir: Webmaker `/data/webmaker`(DATA_ROOT), AriMail `<appDir>/data`(설정 파일 옆), Agent `<dataDir>`. 서버 facts `configDirs` 로 바꿀 수 있다.
3. `restart` 면 서비스 재시작·건강 확인(Agent 자신은 결과 보고 뒤 재시작).
4. 모듈이 파일을 적용하고 `hal-managed.applied.json`(hash·시각·항목·오류, 비밀값 없음)을 남기면 Agent 가 기다려(최대 45초) 결과에 싣는다. 모듈이 다른 hash·오류를 보고하면 `module_apply_failed`.

## 5. 모듈 쪽(HAL 0.4.0 대응)
- Webmaker 1.9.0 `lib/hal-managed.js`: 기동·파일 변경(10초 확인) 때 settings/config/보관소에 적용(auth·fx·tiers·mail 은 묶음 저장). 관리자 콘솔 설정·보관소·설정 페이지에서 관리 항목 409 `managed_by_hal`, 설정 탭 "HAL 관리" 안내.
- AriMail 1.1.0 `server/hal-managed.mjs`: 기본 도메인(서버) 설정에만 적용, `LIMIT_*`·설치 항목 제외. 설정 페이지에서 관리 항목 값 변경 409, 사용량 키 생성 잠금, "HAL 관리" 카드.
- 두 모듈 `package.json` 에 `ariwebSuite.halCompat = "0.4.0"`. 파일이 없으면 동작 변화 없음(단독 운영).

## 6. 화면·AI
- 운영자 콘솔 `/ops/settings` "통합 설정": 모듈 탭 → 범위(전체/서버) → 묶음별 입력 → 저장 → "서버에 적용"(서버 선택·재시작) → 서버별 적용 상태. 운영 현황 서버 카드에 "설정 적용 필요".
- AI 도구: `hal_settings_get`(읽기) · `hal_settings_set`(고위험, 비밀값 거부 `secret_not_allowed`) · `hal_settings_apply`(고위험).

## 7. 알려진 제한
- HAL 에서 지정을 지워도 모듈에 이미 적용된 값은 그대로 남는다(잠금만 풀린다). 되돌리려면 HAL 에서 원하는 값을 지정해 다시 적용한다.
- Webmaker 의 등급·내부 호출 모델은 그 서버에서 "사용 가능"인 모델만 저장된다 — 아니면 `module_apply_failed` 로 보고된다.