From a153851d7972df8d2ad0eadd00ef23361953d3c7 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 26 Jul 2026 21:18:50 +0000
Subject: [PATCH] =?UTF-8?q?=EB=B3=B4=EC=95=88=20=ED=96=A5=EC=83=81:=20inde?=
 =?UTF-8?q?x.html=20=EC=83=9D=EC=84=B1=20=EC=8B=9C=20=EC=9B=90=EC=9E=90?=
 =?UTF-8?q?=EC=A0=81=20=EA=B5=90=EC=B2=B4(Atomic=20Move)=20=EC=A0=81?=
 =?UTF-8?q?=EC=9A=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

파일 쓰기 중 발생할 수 있는 Race Condition 및 TOCTOU 취약점을 방지하기 위해 파일 교체를 `StandardCopyOption.ATOMIC_MOVE`로 수행합니다. 시스템 미지원 시 기존 `REPLACE_EXISTING`으로 fallback 하도록 구현했습니다. 테스트 커버리지 100%를 달성하기 위해 람다 기반의 디폴트 파라미터를 사용했습니다.
---
 .jules/sentinel.md                    |  5 +++
 src/main/kotlin/html4tree/main.kt     | 17 ++++++++-
 src/test/kotlin/html4tree/MainTest.kt | 54 +++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/.jules/sentinel.md b/.jules/sentinel.md
index 6ecf72f1..055281eb 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-25 - [html4tree] 원자적 파일 교체를 통한 경합 조건(Race Condition) 방지
+**Vulnerability:** 파일 교체 시 `REPLACE_EXISTING`만 사용하면 교체 순간에 불완전한 파일 상태가 노출되거나 TOCTOU 취약점이 발생할 수 있습니다.
+**Learning:** 파일 교체 작업은 원자적(Atomic)으로 수행되어야 하며, 시스템에서 지원하지 않을 경우에만 일반 복사/이동으로 폴백해야 안전한 상태 전환을 보장할 수 있습니다.
+**Prevention:** 파일 업데이트 시 `StandardCopyOption.ATOMIC_MOVE`를 우선적으로 시도하고, 실패(`AtomicMoveNotSupportedException`)할 경우에만 `REPLACE_EXISTING`으로 폴백하도록 구현하십시오.
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index b4558624..3f484199 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -229,12 +229,25 @@ 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,
+    moveAtomic: (java.nio.file.Path, java.nio.file.Path) -> Unit = { src, dest ->
+        Files.move(src, dest, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE)
+    },
+    moveFallback: (java.nio.file.Path, java.nio.file.Path) -> Unit = { src, dest ->
+        Files.move(src, dest, StandardCopyOption.REPLACE_EXISTING)
+    }
+) {
     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 {
+            moveAtomic(tempPath, indexPath)
+        } catch (e: java.nio.file.AtomicMoveNotSupportedException) {
+            moveFallback(tempPath, indexPath)
+        }
     } finally {
         Files.deleteIfExists(tempPath)
     }
diff --git a/src/test/kotlin/html4tree/MainTest.kt b/src/test/kotlin/html4tree/MainTest.kt
index 13494714..4ce99051 100644
--- a/src/test/kotlin/html4tree/MainTest.kt
+++ b/src/test/kotlin/html4tree/MainTest.kt
@@ -345,6 +345,60 @@ class MainTest {
         assertTrue(htmlContent.contains("margin: 0 auto;"))
     }
 
+    @Test
+    fun testWriteIndexFileAtomicMoveFallback() {
+        var atomicMoveAttempted = false
+        var fallbackMoveAttempted = false
+
+        write_index_file(
+            curr_dir = tempDir,
+            content = "content",
+            moveAtomic = { src, dest ->
+                atomicMoveAttempted = true
+                throw java.nio.file.AtomicMoveNotSupportedException(src.toString(), dest.toString(), "Mocked")
+            },
+            moveFallback = { src, dest ->
+                fallbackMoveAttempted = true
+                Files.move(src, dest, java.nio.file.StandardCopyOption.REPLACE_EXISTING)
+            }
+        )
+
+        assertTrue(atomicMoveAttempted)
+        assertTrue(fallbackMoveAttempted)
+        assertTrue(File(tempDir, "index.html").exists())
+    }
+
+    @Test
+    fun testWriteIndexFileDefaultLambdas() {
+        val testDir = File(tempDir, "testWriteIndexFileDefault")
+        testDir.mkdir()
+        val expectedContent = "default-lambda-content"
+        write_index_file(testDir, expectedContent)
+        val indexFile = File(testDir, "index.html")
+        assertTrue(indexFile.exists())
+        assertEquals(expectedContent, indexFile.readText())
+    }
+
+    @Test
+    fun testWriteIndexFileDefaultFallbackLambda() {
+        var atomicMoveAttempted = false
+        val testDir = File(tempDir, "testWriteIndexFileDefaultFallback")
+        testDir.mkdir()
+
+        write_index_file(
+            curr_dir = testDir,
+            content = "fallback-content",
+            moveAtomic = { src, dest ->
+                atomicMoveAttempted = true
+                throw java.nio.file.AtomicMoveNotSupportedException(src.toString(), dest.toString(), "Mocked")
+            }
+        )
+        assertTrue(atomicMoveAttempted)
+        val indexFile = File(testDir, "index.html")
+        assertTrue(indexFile.exists())
+        assertEquals("fallback-content", indexFile.readText())
+    }
+
     @Test
     fun testWriteIndexFileCleansUpTempFileOnFailure() {
         // Files.move cannot replace a non-empty directory, so this drives the