From 8ab597cf43231c882517e5a5af60c063409cb676 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Fri, 17 Jul 2026 20:46:41 +0000
Subject: [PATCH] =?UTF-8?q?=EB=B3=B4=EC=95=88:=20=EC=9D=B8=EB=8D=B1?=
 =?UTF-8?q?=EC=8A=A4=20=ED=8C=8C=EC=9D=BC=20=EA=B5=90=EC=B2=B4=20=EC=8B=9C?=
 =?UTF-8?q?=20=EC=9B=90=EC=9E=90=EC=A0=81=20=EC=9D=B4=EB=8F=99(Atomic=20Mo?=
 =?UTF-8?q?ve)=20=EC=A7=80=EC=9B=90=20=EC=B6=94=EA=B0=80=20=EB=B0=8F=20?=
 =?UTF-8?q?=EC=9D=98=EC=A1=B4=EC=84=B1=20=EC=97=85=EB=8D=B0=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 임시 파일에서 `index.html`로 교체할 때 `StandardCopyOption.ATOMIC_MOVE`를 사용하여 TOCTOU 및 부분 읽기 방지
- 파일 시스템 지원 불가 시 `REPLACE_EXISTING`으로 안전하게 폴백(fallback)되도록 예외 처리 구현
- `mockFilesMove`를 주입받아 예외 및 폴백을 검증하는 100% 커버리지 유닛 테스트 추가
- 알려진 보안 취약점(CVE-2020-15250) 해결을 위해 `build.gradle`에서 JUnit 4를 `4.11`에서 `4.13.2`로 업데이트
- 학습된 보안 패턴을 `.jules/sentinel.md` 저널에 기록 (한국어)
---
 .jules/sentinel.md                    |  5 +++++
 build.gradle                          |  2 +-
 src/main/kotlin/html4tree/main.kt     | 12 ++++++++++--
 src/test/kotlin/html4tree/MainTest.kt | 27 +++++++++++++++++++++++++++
 4 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/.jules/sentinel.md b/.jules/sentinel.md
index 6ecf72f..f4b696a 100644
--- a/.jules/sentinel.md
+++ b/.jules/sentinel.md
@@ -83,3 +83,8 @@
 **Vulnerability:** 정적 HTML 생성 도구에서 매번 다른 Nonce를 동적으로 생성하여 CSP에 적용하는 것은, 캐싱 효율을 저하시킬 뿐만 아니라 정적 배포 환경(예: GitHub Pages 등)에서 올바른 보안 정책 수립을 방해할 수 있는 안티 패턴입니다.
 **Learning:** 정적으로 고정된 인라인 스타일이나 스크립트에는 난수화된 Nonce보다 콘텐츠 자체의 해시(SHA-256 등)를 사용하는 것이 안전하고 일관된 방식임을 배웠습니다.
 **Prevention:** 자동 생성되는 정적 HTML의 콘텐츠 보안 정책(CSP)에는 `style-src 'sha256-<HASH>'` 방식을 적용하고, `<style>` 태그에서 불필요한 `nonce` 속성을 제거하여 브라우저의 무결성 검증 기능을 적극 활용하십시오.
+
+## 2024-07-17 - [html4tree] 원자적 파일 이동을 통한 보안 및 안정성 강화
+**Vulnerability:** 기존 `write_index_file`은 임시 파일을 `REPLACE_EXISTING`만 사용하여 대상 위치로 이동시켰습니다. 이는 파일 교체 중 불완전한 상태(부분 읽기)가 노출되거나, 교체 직전 대상 경로가 악의적인 심볼릭 링크로 변경되는 TOCTOU(Time-of-Check to Time-of-Use) 공격에 취약할 수 있습니다.
+**Learning:** 파일 교체 작업에서 원자성(Atomicity)을 보장하는 것은 데이터 손상 방지 및 동시성 관련 보안 문제를 예방하는 핵심 요소입니다. Java/Kotlin에서 파일 시스템이 지원하는 경우 `StandardCopyOption.ATOMIC_MOVE`를 사용하면 이러한 위험을 줄일 수 있습니다.
+**Prevention:** 정적 파일이나 구성 파일을 작성할 때는 임시 파일을 먼저 작성한 후, `StandardCopyOption.ATOMIC_MOVE`와 `REPLACE_EXISTING`을 함께 사용하여 대상 파일로 이동시킵니다. 대상 파일 시스템에서 원자적 이동을 지원하지 않는 경우(`AtomicMoveNotSupportedException` 발생)에 대비해 `REPLACE_EXISTING`만 사용하는 안전한 폴백(fallback) 메커니즘을 구현하십시오.
diff --git a/build.gradle b/build.gradle
index 33cc784..bc408aa 100644
--- a/build.gradle
+++ b/build.gradle
@@ -23,7 +23,7 @@ repositories {
 
 dependencies {
     compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-    testCompile 'junit:junit:4.11'
+    testCompile 'junit:junit:4.13.2'
     testCompile "org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version"
     compile "com.github.ajalt:clikt:2.7.1"
 }
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index b455862..de27d2e 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -229,12 +229,20 @@ fun process_ignore_file(curr_dir: File, dirFilesNames: Array<String>? = null): S
     return files_to_exclude
 }
 
-fun write_index_file(curr_dir: File, content: String) {
+fun write_index_file(
+    curr_dir: File,
+    content: String,
+    filesMove: (java.nio.file.Path, java.nio.file.Path, Array<out java.nio.file.CopyOption>) -> java.nio.file.Path = Files::move
+) {
     val indexPath = curr_dir.toPath().resolve("index.html")
     val tempPath = Files.createTempFile(curr_dir.toPath(), ".index-", ".html")
     try {
         Files.write(tempPath, content.toByteArray(Charsets.UTF_8))
-        Files.move(tempPath, indexPath, StandardCopyOption.REPLACE_EXISTING)
+        try {
+            filesMove(tempPath, indexPath, arrayOf(StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING))
+        } catch (e: java.nio.file.AtomicMoveNotSupportedException) {
+            filesMove(tempPath, indexPath, arrayOf(StandardCopyOption.REPLACE_EXISTING))
+        }
     } finally {
         Files.deleteIfExists(tempPath)
     }
diff --git a/src/test/kotlin/html4tree/MainTest.kt b/src/test/kotlin/html4tree/MainTest.kt
index 1349471..cc943cf 100644
--- a/src/test/kotlin/html4tree/MainTest.kt
+++ b/src/test/kotlin/html4tree/MainTest.kt
@@ -443,6 +443,33 @@ class MainTest {
         assertFalse(File(gitDir, "index.html").exists())
     }
 
+    @Test
+    fun testWriteIndexFileAtomicMoveFallback() {
+        val content = "atomic fallback content"
+
+        var atomicMoveAttempted = false
+        var fallbackExecuted = false
+
+        val mockFilesMove: (java.nio.file.Path, java.nio.file.Path, Array<out java.nio.file.CopyOption>) -> java.nio.file.Path = { source, target, options ->
+            if (options.contains(java.nio.file.StandardCopyOption.ATOMIC_MOVE)) {
+                atomicMoveAttempted = true
+                throw java.nio.file.AtomicMoveNotSupportedException(source.toString(), target.toString(), "Mocked ATOMIC_MOVE not supported")
+            } else {
+                fallbackExecuted = true
+                java.nio.file.Files.move(source, target, *options)
+            }
+        }
+
+        write_index_file(tempDir, content, mockFilesMove)
+
+        assertTrue(atomicMoveAttempted, "ATOMIC_MOVE should have been attempted")
+        assertTrue(fallbackExecuted, "Fallback to normal move should have been executed")
+
+        val indexFile = File(tempDir, "index.html")
+        assertTrue(indexFile.exists())
+        assertEquals(content, indexFile.readText())
+    }
+
     @Test
     fun testProcessDirHandlesNonDirectoryWithoutThrowing() {
         val notADirectory = File(tempDir, "not-a-directory")