@cocalc/openat2 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SageMath, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @cocalc/openat2
+
+Linux-only `napi-rs` addon that exposes `openat2`-anchored filesystem operations for race-safe sandbox mutation.
+
+## Why this exists
+
+In CoCalc safe mode, we need a strong guarantee:
+
+- filesystem operations for a project stay inside that project root
+- even if the project owner (or another process) is changing paths concurrently
+
+The subtle failure mode is a classic race:
+
+1. We validate a string path (e.g. `a/b/file.txt`) and it looks safe.
+2. Before the actual mutation syscall runs, an attacker swaps an intermediate path component (or leaf) to a symlink.
+3. The mutation then lands outside the sandbox.
+
+That `validate(path) -> mutate(path)` pattern is fundamentally fragile under concurrency, because validation and mutation happen at different times on a mutable namespace.
+
+`openat2` changes the model from string-based trust to descriptor-based trust:
+
+- we first open a **root directory handle** (`dirfd`) for the sandbox root
+- each operation resolves relative paths under that root via `openat2`
+- kernel-enforced resolve rules (`RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_MAGICLINKS`) prevent escaping during resolution
+- we then mutate via `*at` syscalls (`mkdirat`, `renameat`, `unlinkat`, etc.) anchored to validated dirfds
+
+This is closer to a capability model: possession of the root `dirfd` defines the authority boundary, and every derived operation stays constrained to that boundary. In practice, this removes dependence on ad-hoc deny/allow path filtering as the primary safety mechanism.
+
+Why not just use Node `fs` + file descriptors?
+
+- File descriptors help for **existing-file content I/O** (`read`/`write` on an already opened inode), and we do use that pattern.
+- But many dangerous operations are **path mutators** (`mkdir`, `rename`, `unlink`, `rmdir`, `chmod`, `utimes`, create paths) that still require pathname resolution at operation time.
+- In plain Node, those mutators are path-based. You can pre-check with `realpath`/`lstat`, but that is still a user-space check followed by a later path syscall, so there is still a race window.
+- For create flows, there may be no target inode yet to pin with an fd. The critical security question is whether parent-chain resolution stayed inside the sandbox at the exact syscall boundary.
+- Node does not currently expose a complete `openat2`/`*at` capability API that lets us anchor all resolution to a sandbox dirfd with kernel-enforced constraints.
+
+So fd-only hardening in Node is necessary but not sufficient: it meaningfully improves read/write safety, but it cannot fully eliminate TOCTOU escape classes for path-mutating operations. `openat2` + `*at` is the piece that closes that remaining gap.
+
+Tradeoffs:
+
+- implementation is more tedious than plain Node `fs` path calls
+- Linux-specific (`openat2` is a Linux syscall)
+- existing path-oriented code needs adapter layers for migration
+
+For our situation, that tradeoff is worth it: mutators become fail-closed under symlink/path-swap races, which is exactly the remaining hardening gap in backend sandbox safe mode.
+
+## Current API
+
+```ts
+import { SandboxRoot } from '@cocalc/openat2'
+
+const root = new SandboxRoot('/srv/project')
+root.mkdir('a/b', true)
+root.rename('a/b/file.txt', 'a/b/file2.txt')
+root.unlink('a/b/file2.txt')
+const st = root.stat('a/b')
+```
+
+Methods implemented now:
+
+- `mkdir(path, recursive?, mode?)`
+- `unlink(path)`
+- `rmdir(path)`
+- `rename(oldPath, newPath)`
+- `renameNoReplace(oldPath, newPath)`
+- `link(oldPath, newPath)`
+- `symlink(target, newPath)`
+- `chmod(path, mode)`
+- `truncate(path, len)`
+- `copyFile(src, dest, mode?)`
+- `rm(path, recursive?, force?)`
+- `utimes(path, atimeNs, mtimeNs)`
+- `stat(path)`
+- `openRead(path) -> fd`
+- `openWrite(path, create?, truncate?, append?, mode?) -> fd`
+
+`openRead`/`openWrite` return numeric file descriptors intended for high-frequency
+I/O paths in Node. The caller owns the descriptor and must close it.
+
+## Security model
+
+- Absolute paths are rejected.
+- `..` traversal is rejected.
+- Symlink traversal is blocked by `openat2` resolve flags.
+- Operations are anchored to a root dirfd opened once in constructor.
+
+## Build
+
+```bash
+pnpm install
+pnpm build
+```
+
+Requirements:
+
+- Linux kernel with `openat2` support (>=5.6)
+- Rust toolchain
+- Node 18+
+
+## Test
+
+```bash
+pnpm run test:rust
+```
+
+## Packaging notes
+
+This repository is configured to publish Linux prebuilt binaries for:
+
+- `x86_64-unknown-linux-gnu`
+- `aarch64-unknown-linux-gnu`
+
+Runtime loading prefers:
+
+1. local `cocalc_openat2.linux-*.node` files (for CI/dev artifacts)
+2. optional npm packages (`@cocalc/openat2-linux-x64-gnu` / `@cocalc/openat2-linux-arm64-gnu`)
+3. local `cocalc_openat2.node` fallback for local development
+
+### Release automation
+
+The workflow in [.github/workflows/release.yml](./.github/workflows/release.yml):
+
+1. builds both linux targets
+2. uploads `.node` artifacts
+3. on `v*` tags, downloads artifacts and publishes:
+   - `@cocalc/openat2-linux-x64-gnu`
+   - `@cocalc/openat2-linux-arm64-gnu`
+   - `@cocalc/openat2` (root package)
+
+Publishing relies on the root `prepublishOnly` script:
+
+```bash
+pnpm run create-npm-dirs
+napi prepublish -t npm --tagstyle npm --skip-gh-release
+```

package/index.d.ts

@@ -0,0 +1,38 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface StatResult {
+  dev: number
+  ino: number
+  mode: number
+  nlink: number
+  uid: number
+  gid: number
+  rdev: number
+  size: number
+  blksize: number
+  blocks: number
+  atimeNs: number
+  mtimeNs: number
+  ctimeNs: number
+}
+export declare class SandboxRoot {
+  constructor(root: string)
+  mkdir(path: string, recursive?: boolean | undefined | null, mode?: number | undefined | null): void
+  unlink(path: string): void
+  rmdir(path: string): void
+  rename(oldPath: string, newPath: string): void
+  renameNoReplace(oldPath: string, newPath: string): void
+  link(oldPath: string, newPath: string): void
+  symlink(target: string, newPath: string): void
+  chmod(path: string, mode: number): void
+  truncate(path: string, len: number): void
+  copyFile(src: string, dest: string, mode?: number | undefined | null): void
+  openRead(path: string): number
+  openWrite(path: string, create?: boolean | undefined | null, truncate?: boolean | undefined | null, append?: boolean | undefined | null, mode?: number | undefined | null): number
+  rm(path: string, recursive?: boolean | undefined | null, force?: boolean | undefined | null): void
+  utimes(path: string, atimeNs: number, mtimeNs: number): void
+  stat(path: string): StatResult
+}

package/index.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'cocalc_openat2.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.android-arm64.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'cocalc_openat2.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'cocalc_openat2.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'cocalc_openat2.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'cocalc_openat2.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'cocalc_openat2.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./cocalc_openat2.darwin-universal.node')
+      } else {
+        nativeBinding = require('@cocalc/openat2-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'cocalc_openat2.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.darwin-x64.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'cocalc_openat2.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'cocalc_openat2.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./cocalc_openat2.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@cocalc/openat2-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'cocalc_openat2.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./cocalc_openat2.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@cocalc/openat2-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'cocalc_openat2.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./cocalc_openat2.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@cocalc/openat2-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { SandboxRoot } = nativeBinding
+
+module.exports.SandboxRoot = SandboxRoot

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cocalc/openat2",
+  "version": "0.1.0",
+  "description": "Linux openat2-based filesystem primitives for secure sandboxing",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "artifacts": "napi artifacts -d artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "build:platform": "napi build --platform --release",
+    "build:target": "napi build --platform --release --target",
+    "create-npm-dirs": "napi create-npm-dir -t .",
+    "prepublishOnly": "pnpm run create-npm-dirs && napi prepublish -t npm --tagstyle npm --skip-gh-release",
+    "test:node": "node --test test/*.test.cjs",
+    "test:rust": "cargo test",
+    "test": "pnpm run test:rust && pnpm run test:node",
+    "lint:rust": "cargo clippy --all-targets --all-features -- -D warnings",
+    "version": "napi version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  },
+  "napi": {
+    "name": "cocalc_openat2",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "optionalDependencies": {
+    "@cocalc/openat2-linux-x64-gnu": "0.1.0",
+    "@cocalc/openat2-linux-arm64-gnu": "0.1.0"
+  }
+}