Add createFileAtomically and owner-only staging

A caller that publishes a file for others to read may need to create it
only when nobody else has, and to stage a secret where nobody else can
read it on the way. Neither was available.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: kitbellew

io/src/main/scala/sbt/io/IO.scala

@@ -14,7 +14,13 @@ package sbt.io
 import java.io._
 import java.net.{ URI, URISyntaxException, URL }
 import java.nio.charset.Charset
-import java.nio.file.attribute.PosixFilePermissions
+import java.nio.file.attribute.{
+  AclEntry,
+  AclEntryPermission,
+  AclEntryType,
+  PosixFilePermissions,
+  UserPrincipal
+}
 import java.nio.file.{ Path => NioPath, _ }
 import java.util.{ Locale, Properties, UUID }
 import java.util.concurrent.ForkJoinPool
@@ -475,7 +481,35 @@ object IO {
    * `write` returns successfully. If `write` throws, `to` is left untouched and the
    * staging file is removed.
    */
-  def writeFileAtomically[T](to: File)(write: File => T): T = {
+  def writeFileAtomically[T](to: File)(write: File => T): T =
+    writeFileAtomically(to, ownerOnly = false)(write)
+
+  /**
+   * Stages a write to a sibling temp file and atomically replaces `to` only after
+   * `write` returns successfully. If `write` throws, `to` is left untouched and the
+   * staging file is removed.
+   *
+   * @param ownerOnly
+   *   if true, no content written out could be read by anyone other than its owner
+   */
+  def writeFileAtomically[T](to: File, ownerOnly: Boolean)(write: File => T): T =
+    writeStaged(to, ownerOnly, replace = true)(write)
+
+  /**
+   * Like `writeFileAtomically`, except that it refuses a `to` that already exists and
+   * throws `FileAlreadyExistsException`.
+   *
+   * @param ownerOnly
+   *   if true, no content written out could be read by anyone other than its owner
+   */
+  def createFileAtomically[T](to: File, ownerOnly: Boolean)(write: File => T): T =
+    writeStaged(to, ownerOnly, replace = false)(write)
+
+  private def writeStaged[T](
+      to: File,
+      ownerOnly: Boolean,
+      replace: Boolean
+  )(write: File => T): T = {
     val parent = Option(to.getAbsoluteFile.getParentFile).getOrElse(new File("."))
     createDirectory(parent)
 
@@ -488,7 +522,7 @@ object IO {
 
     val toPath = to.toPath
     val staging = stagingFile.toPath
-    touch(stagingFile)
+    if (ownerOnly) createForOwner(staging) else touch(stagingFile)
 
     def retry(func: => NioPath): NioPath = Retry(
       func,
@@ -498,19 +532,50 @@ object IO {
     )
     def move(options: CopyOption*): NioPath = retry(Files.move(staging, toPath, options*))
     def replaceFile(): NioPath =
+      // ATOMIC_MOVE uses POSIX rename, so it can only be used with `replace`
       try move(StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING)
       catch { case _: AtomicMoveNotSupportedException => move(StandardCopyOption.REPLACE_EXISTING) }
+    def createLink(): NioPath =
+      // Files.move with ATOMIC_MOVE possibly replaces and without has a race condition
+      try retry(Files.createLink(toPath, staging)) // try this first
+      catch {
+        case e @ (_: UnsupportedOperationException | _: IOException)
+            if !e.isInstanceOf[FileAlreadyExistsException] =>
+          move()
+      }
 
     try {
       val result = write(stagingFile)
-      replaceFile()
+      if (replace)
+        replaceFile()
+      else
+        createLink()
       result
     } finally {
       Files.deleteIfExists(staging)
       ()
     }
   }
 
+  /** Creates `path` such that only its owner can read and write it. */
+  private def createForOwner(path: NioPath): Unit = {
+    if (isPosix) {
+      val ownerOnly = PosixFilePermissions.fromString("rw-------")
+      Files.createFile(path, PosixFilePermissions.asFileAttribute(ownerOnly))
+    } else {
+      Files.createFile(path)
+      if (hasAclFileAttributeView) {
+        val view = Path(path.toFile).aclFileAttributeView
+        val acl = AclEntry.newBuilder
+        acl.setPrincipal(view.getOwner)
+        acl.setPermissions(AclEntryPermission.values()*)
+        acl.setType(AclEntryType.ALLOW)
+        view.setAcl(java.util.Collections.singletonList(acl.build))
+      }
+    }
+    ()
+  }
+
   /**
    * Copies all bytes from the given input stream to the given output stream.
    * Neither stream is closed.

io/src/test/scala/sbt/io/IOSpec.scala

@@ -12,12 +12,83 @@
 package sbt.io
 
 import java.io.File
-import java.nio.file.Files
+import java.nio.file.{ FileAlreadyExistsException, Files }
+import java.nio.file.attribute.PosixFilePermission.{ OWNER_READ, OWNER_WRITE }
+import scala.collection.JavaConverters._
 import org.scalatest.funsuite.AnyFunSuite
 import sbt.io.syntax._
 
 class IOSpec extends AnyFunSuite {
 
+  test("createFileAtomically should write a file that is not there") {
+    IO.withTemporaryDirectory { dir =>
+      val target = new File(dir, "out.json")
+      IO.createFileAtomically(target, ownerOnly = false)(staging => IO.write(staging, "content"))
+      assert(IO.read(target) === "content")
+      assert(dir.listFiles.map(_.getName).toList === List("out.json"))
+    }
+  }
+
+  test("createFileAtomically should refuse a file that is there") {
+    IO.withTemporaryDirectory { dir =>
+      val target = new File(dir, "out.json")
+      IO.write(target, "first")
+      assertThrows[FileAlreadyExistsException] {
+        IO.createFileAtomically(target, ownerOnly = false)(staging => IO.write(staging, "second"))
+      }
+      assert(IO.read(target) === "first")
+      assert(dir.listFiles.map(_.getName).toList === List("out.json"))
+    }
+  }
+
+  test("createFileAtomically should let one writer of many create the file") {
+    IO.withTemporaryDirectory { dir =>
+      val writers = 8
+      val pool = java.util.concurrent.Executors.newFixedThreadPool(writers)
+      try {
+        val winners = (0 until 20).map { round =>
+          val target = new File(dir, s"target$round")
+          val go = new java.util.concurrent.CountDownLatch(1)
+          val won = new java.util.concurrent.atomic.AtomicInteger
+          val running = (0 until writers).map { writer =>
+            pool.submit(new Runnable {
+              def run(): Unit = {
+                go.await()
+                try {
+                  IO.createFileAtomically(target, ownerOnly = false)(staging =>
+                    IO.write(staging, s"writer $writer")
+                  )
+                  won.incrementAndGet()
+                  ()
+                } catch { case _: FileAlreadyExistsException => () }
+              }
+            })
+          }
+          go.countDown()
+          running.foreach(_.get())
+          assert(IO.read(target).startsWith("writer "))
+          won.get
+        }
+        assert(winners.toList === List.fill(20)(1))
+      } finally {
+        pool.shutdown()
+        ()
+      }
+    }
+  }
+
+  test("writeFileAtomically should keep a file to its owner when asked") {
+    if (IO.isPosix) {
+      IO.withTemporaryDirectory { dir =>
+        val target = new File(dir, "secret.json")
+        IO.writeFileAtomically(target, ownerOnly = true)(staging => IO.write(staging, "hush"))
+        val permissions = Files.getPosixFilePermissions(target.toPath).asScala.toSet
+        assert(permissions === Set(OWNER_READ, OWNER_WRITE))
+        assert(IO.read(target) === "hush")
+      }
+    }
+  }
+
   test("IO should relativize") {
     // Given:
     // io-relativize/