From 018cb67e509e891231a5ab26f2694d8d6622396f Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sat, 1 Aug 2026 20:50:13 +0000
Subject: [PATCH] =?UTF-8?q?=EB=B3=B4=EC=95=88=20=ED=96=A5=EC=83=81:=20?=
 =?UTF-8?q?=EC=9B=90=EC=9E=90=EC=A0=81=20=ED=8C=8C=EC=9D=BC=20=EC=A1=B0?=
 =?UTF-8?q?=EC=9E=91(Atomic=20File=20Operations)=EC=9D=84=20=ED=86=B5?=
 =?UTF-8?q?=ED=95=9C=20TOCTOU=20=EC=B7=A8=EC=95=BD=EC=A0=90=20=EC=99=84?=
 =?UTF-8?q?=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `index.html` 생성 시 임시 파일 덮어쓰기 도중 발생할 수 있는 경합 조건(Race Condition)을 방지하기 위해 `StandardCopyOption.ATOMIC_MOVE`를 사용합니다.
- 파일 시스템이 원자적 이동을 지원하지 않는 경우 `AtomicMoveNotSupportedException`을 잡아 기존처럼 `REPLACE_EXISTING`으로 폴백(Fallback)하도록 우아하게 처리합니다.
- 테스트 커버리지를 100%로 유지하기 위해 파일 조작 람다를 주입받아 예외 상황을 시뮬레이션하는 테스트를 추가했습니다.
- 관련 내용을 `.jules/sentinel.md`에 한국어로 기록했습니다.
---
 .jules/sentinel.md                    |  5 +++++
 src/main/kotlin/html4tree/main.kt     | 15 +++++++++++++--
 src/test/kotlin/html4tree/MainTest.kt | 14 ++++++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/.jules/sentinel.md b/.jules/sentinel.md
index 6ecf72f1..37e3eecf 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] 원자적 파일 조작(Atomic File Operations)을 통한 TOCTOU 완화
+**Vulnerability:** index.html 생성 시 임시 파일 덮어쓰기 도중 경합 조건(Race Condition)으로 인한 불완전한 상태 노출.
+**Learning:** 파일 교체 시 단순 `REPLACE_EXISTING`을 사용하면 덮어쓰는 찰나에 파일을 읽는 프로세스가 불완전하거나 손상된 데이터를 볼 수 있는 TOCTOU(Time-of-Check to Time-of-Use) 문제가 발생할 수 있습니다. 특히 정적 파일 생성기에서는 일관성이 중요합니다.
+**Prevention:** `Files.move` 시 `StandardCopyOption.ATOMIC_MOVE`를 시도하여 교체가 원자적으로 이루어지도록 보장하고, 파일 시스템 지원이 없는 경우에만(`AtomicMoveNotSupportedException`) 일반 교체로 우아하게 대체(Fallback)하십시오.
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index b4558624..cbcc1d69 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -6,6 +6,9 @@ import java.nio.file.Files
 import java.nio.file.LinkOption
 import java.nio.file.StandardCopyOption
 import java.nio.file.attribute.BasicFileAttributes
+import java.nio.file.AtomicMoveNotSupportedException
+import java.nio.file.CopyOption
+import java.nio.file.Path
 import java.util.Base64
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.options.option
@@ -229,12 +232,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,
+    moveFile: (Path, Path, Array<out CopyOption>) -> Path = { src, dest, options -> Files.move(src, dest, *options) }
+) {
     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 {
+            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE))
+        } catch (e: AtomicMoveNotSupportedException) {
+            moveFile(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 13494714..af8c90e6 100644
--- a/src/test/kotlin/html4tree/MainTest.kt
+++ b/src/test/kotlin/html4tree/MainTest.kt
@@ -705,4 +705,18 @@ class MainTest {
         assertFalse(processed, "fileKey mismatch should skip directory processing")
         assertFalse(listed, "fileKey mismatch should skip child listing")
     }
+
+    @Test
+    fun testWriteIndexFileAtomicMoveFallback() {
+        var fallbackCalled = false
+        write_index_file(tempDir, "content") { src, dest, options ->
+            if (options.contains(java.nio.file.StandardCopyOption.ATOMIC_MOVE)) {
+                throw java.nio.file.AtomicMoveNotSupportedException(src.toString(), dest.toString(), "Mocked exception")
+            }
+            fallbackCalled = true
+            java.nio.file.Files.move(src, dest, *options)
+        }
+        assertTrue(fallbackCalled, "Fallback to regular move should be called on AtomicMoveNotSupportedException")
+        assertTrue(File(tempDir, "index.html").exists())
+    }
 }