Ariweb Suite 개발 지시 — 작성자: Neo · v0.2.1

작성자: Neo 작성일: 2026-10-29 이전 버전: v0.2.0(Webmaker 직접 편집 — 시각 편집기, Neo, 2026-10-28) · v0.1.4(미반영 오류 수정·HAL AI 대시보드·다중 AI 공동 작업창 지시, Neo) · v0.1.1(최초 통합 개발 지시, Hera) 이번 개정: HAL 운영자 콘솔의 고위험 재인증 안내 위치 수정. 모든 일반 화면에 늘 떠 있던 전역 배너를 없애고, 그 안내는 backend 가 고위험 요청을 실제로 거부한 바로 그 때 여는 재인증 창 안에만 둔다. 사용자 기능 추가가 아닌 운영자 화면 수정이므로 끝 버전 번호만 올린다 — Suite 0.2.0 → 0.2.1. v0.1.1·v0.1.4·v0.2.0 의 모든 기준과 지시는 그대로 유효하며, 이 문서는 추가 요구만 적는다(v0.1.4 항목은 이번 구현 범위가 아니다).

개정 이력

v0.1.1 · Hera · 2026-10-26: 최초 통합 개발 지시, Webmaker·AriMail 재사용 원칙, 사용량 경고 70·80·90·95%.
v0.1.4 · Neo · 2026-10-27: patch 자동 증가 규칙, 미반영 오류 수정 전수 반영, HAL AI 대시보드, 다중 AI 공동 작업창.
v0.2.0 · Neo · 2026-10-28: Webmaker 직접 편집(끌어다 놓기 시각 편집기) — Suite modules/webmaker 와 기존 Webmaker 저장소 양쪽에 반영.
v0.2.1 · Neo · 2026-10-29: HAL 운영자 콘솔 고위험 재인증 안내를 전역 배너에서 거부 시점 재인증 창으로 옮김. 엄격한 TDD, 격리 작업 트리(feature/hal-risk-banner-v0.2.1, 기준 origin/main 0a56d4612c86dddfcbe644e775980d3c5b413b2e), 커밋·push·병합·배포는 Neo 가 별도 검토 뒤 수행.

1. 목표

HAL 운영자 콘솔의 모든 일반 화면에 항상 보이던 다음 전역 배너를 제거한다: ! 고위험 작업(서버 삭제·되돌리기·인증 키 변경·복구)은 최근 10분 안의 재인증이 필요합니다 — 재인증.
이 안내는 backend 가 고위험 작업 요청을 reauth_required 로 거부하여 재인증이 필요한 바로 그 시점에만, 재인증 창(modal) 안에서 보인다.
backend 보안 경계(requireRecent, CSRF, 3단계 확인, 고위험 작업 분류와 거부 동작)는 한 글자도 약화하지 않는다.
Suite 버전을 0.2.1 로 올리고 package/runtime/release 표기와 VERSION_HISTORY.md 를 일관되게 갱신한다.

2. 사용자 요구(약화 금지)

운영자는 단순 화면 조회, 로그인 직후, 로그인 10분 경과, 일반 화면 이동 중에 고위험 재인증 안내를 보지 않는다. 안내는 실제로 고위험 작업을 시도해 서버가 거부한 순간에만 뜬다.
계정 화면의 수동 계정 재인증 단추와 동작은 유지한다. 수동 재인증 창에는 고위험 안내를 억지로 붙이지 않는다(비밀번호만 묻는다).
다른 전역 배너(접근권 만료 안내·HAL 자체 건강 비정상·긴급 복구 세션 진행·부트스트랩 미완료·비밀번호 변경 필요)는 그대로 둔다 — 배너 영역 자체를 없애는 것이 아니다.

3. 보안 불변조건

hal/app.mjs 의 requireRecent(최근 10분 재인증), CSRF 검사, 3단계 확인(confirmImpact → confirmIdentifiers → confirmExecute), 고위험 작업 분류(서버 삭제·격리·역할 변경, 모듈 되돌리기·배포·재조정, 작업 revert, 운영자 계정·접근권 발급, MFA 해제, 설정 변경, 메일 가져오기 적용·되돌리기, 릴리스 승인, 긴급 복구 선언·승인·자격, DR 설정·복원)과 403 reauth_required 거부 동작은 변경 금지.
재인증 창을 취소하거나 재인증이 실패하면 원래 고위험 요청은 실행되지 않고, 원래 오류가 호출자에게 그대로 전파된다.
재인증에 성공하면 원 요청을 기존처럼 딱 한 번 재시도한다. 재시도도 거부되면 다시 묻지 않고 오류를 올린다(무한 반복 금지). reauth_required 가 아닌 오류는 재인증을 묻지 않는다.
판단은 전부 서버가 한다. 브라우저 쪽 변경은 "거부됐을 때 어떻게 묻고 몇 번 다시 보내는가"와 안내 문구 위치에 한정한다. 재인증 API(POST /ops/api/reauth)의 CSRF 요구도 그대로다.
비밀번호·토큰·키·개인정보를 파일·출력·commit 에 넣지 않는다.

4. TDD·검증

production code 보다 먼저 최소 회귀 테스트를 쓰고 실제로 실행해 RED(예상 이유로 실패)를 확인한 뒤 최소 구현으로 GREEN. 그 다음 targeted HAL UI/auth 테스트, 마지막에 전체 Suite 테스트(node test/run.mjs).
다뤄야 할 계약: (가) 일반 화면(운영 현황·서버·릴리스·작업·복구·중계 화면·계정)에 로그인 직후·10분 경과·화면 이동 모두 전역 고위험 배너 없음, 계정 화면 수동 재인증 단추 유지·고위험 안내 없음, 다른 배너 유지; (나) backend 경계 그대로 — 10분 경과 뒤 고위험 API 403 reauth_required·거부된 요청 미실행·CSRF 없는 재인증 거부·틀린 비밀번호 거부·재인증 뒤 통과·3단계 확인 별도 요구; (다) 재인증 창 문구 — 거부 시점에만 고위험 안내, 수동은 없음; (라) 취소 시 원 요청 미실행·오류 전파, 성공 시 딱 한 번 재시도, 재시도 거부 시 재질문 없음, 다른 오류는 재인증 질문 없음; (마) 정적 계약 — hal/ui.mjs 에 배너 코드 없음, hal/ui/public/ops.js 가 순수 helper 를 쓰고 안내 문구를 직접 품지 않음.
브라우저 스크립트는 DOM 없이 돌지 않으므로, 재인증 흐름·창 문구를 테스트 가능한 순수 helper(hal/ui/public/reauth.mjs)로 분리하고 ops.js 가 그것을 쓰는지는 정적 계약으로 못 박는다. 큰 dependency 를 더하지 않는다(외부 npm 의존성 0 유지).
기존 test runner 가 만드는 docs/verification/local-e2e-* 임시 파일은 최종 diff 에 남기지 않는다(이미 커밋된 2026-10-26·27 기록은 그대로).

5. 범위·저장소 규율

수정 허용: HAL UI(hal/ui.mjs, hal/ui/render.mjs(공개 사본은 심볼릭 링크), hal/ui/public/ops.js, 새 hal/ui/public/reauth.mjs), 관련 테스트, Suite 0.2.1 버전/이력(package.json·README.md·VERSION_HISTORY.md·버전을 검사하는 테스트), 이 개발 지시.
금지: Webmaker standalone 기능, 보안 경계, 승인 artifact 불변성(0.2.0 검토 수정), 다른 모듈. commit·push·merge·release build·운영 배포 금지 — Neo 가 독립 검토 뒤 수행한다.
코딩은 Claude Fable 5.1 로만 수행한다. 기존 v0.2.0 문서는 덮어쓰지 않는다. 파일 이름의 Suitle 철자는 식별자이므로 그대로 보존한다.

6. 완료 조건(이번 구현의 인도 기준)

변경 파일 목록, RED 명령과 실패 이유, GREEN·targeted·전체 테스트의 실제 결과, 보안 결정, 남은 제한을 정확히 보고하고 프롬프트로 돌아온다. 구현 결과와 증거: VERSION_HISTORY.md 0.2.1 절(작성자·이전 버전·요구·수정한 기존 기능·운영자 화면·보안 결정·테스트·알려진 제한·미확정 정책값), 회귀 테스트 test/hal-reauth-banner.test.mjs.

7.2 KiB Raw Blame History