use std::io::{Read as _, Seek as _, Write as _};
use std::path::{Component, Path, PathBuf};
use anyhow::{Context as _, bail};
use nitr::Config;
const MAGIC: &[u8; 8] = b"NITRBNDL";
const TRAILER: u64 = 16;
const CONFIG_NAME: &str = "nitr.toml";
pub(crate) fn read_appended(exe: &Path) -> anyhow::Result<Option<Vec<u8>>> {
let mut file = std::fs::File::open(exe)
.with_context(|| format!("cannot open the executable {}", exe.display()))?;
let len = file.metadata()?.len();
if len < TRAILER {
return Ok(None);
}
file.seek(std::io::SeekFrom::End(-(TRAILER as i64)))?;
let mut trailer = [0u8; TRAILER as usize];
file.read_exact(&mut trailer)?;
if &trailer[8..] != MAGIC {
return Ok(None);
}
#[allow(clippy::expect_used)]
let tar_len = u64::from_le_bytes(trailer[..8].try_into().expect("8 bytes"));
if tar_len == 0 || tar_len > len - TRAILER {
bail!("the appended application archive is corrupt (bad length)");
}
file.seek(std::io::SeekFrom::End(-((TRAILER + tar_len) as i64)))?;
let mut tar = vec![0u8; tar_len as usize];
file.read_exact(&mut tar)?;
Ok(Some(tar))
}
pub fn seal(cfg: &mut Config) -> Option<String> {
let warning = cfg
.dev_mode
.then(|| "dev_mode is forced off in a bundled build (no sources to watch)".to_string());
cfg.dev_mode = false;
warning
}
pub fn load() -> anyhow::Result<Option<(Config, Vec<String>)>> {
let mut warnings = Vec::new();
let exe = std::env::current_exe().context("cannot locate the running executable")?;
let Some(tar) = read_appended(&exe)? else {
return Ok(None);
};
let key = {
use std::hash::{Hash as _, Hasher as _};
let mut h = std::hash::DefaultHasher::new();
tar.hash(&mut h);
h.finish()
};
let root = match cache_root() {
Some(cache) => {
let root = cache.join(format!("app-{key:016x}"));
if !root.join(MARKER).is_file() {
let staging = fresh_private_dir(&cache, &format!("app-{key:016x}"))?;
extract(&tar, &staging)?;
std::fs::File::create(staging.join(MARKER))?;
match std::fs::rename(&staging, &root) {
Ok(()) => sweep_stale_staging(&cache, &format!("app-{key:016x}.")),
Err(_) if root.join(MARKER).is_file() => {
let _ = std::fs::remove_dir_all(&staging);
}
Err(err) => {
return Err(err).context("cannot finalize the bundle extraction");
}
}
}
root
}
None => {
let root = fresh_private_dir(&std::env::temp_dir(), "nitr-app")?;
warnings.push(format!(
"no writable cache directory ($XDG_CACHE_HOME or $HOME/.cache); \
extracting the bundle to {} for this run only",
root.display()
));
extract(&tar, &root)?;
root
}
};
let mut cfg = Config::from_file(&root.join(CONFIG_NAME))?;
cfg.rebase(&root);
if let Some(db) = &mut cfg.database
&& db.migrations_dir.is_none()
&& root.join("migrations").is_dir()
{
db.migrations_dir = Some(root.join("migrations"));
}
if let Some(output) = cfg.openapi.output.take() {
warnings.push(format!(
"[openapi] output = \"{}\" is ignored in a bundled build (no sources to follow; \
use `nitr openapi --output` instead)",
output.display()
));
}
Ok(Some((cfg, warnings)))
}
const MARKER: &str = ".nitr-extracted";
fn cache_root() -> Option<PathBuf> {
let base = std::env::var_os("XDG_CACHE_HOME")
.map(PathBuf::from)
.filter(|p| p.is_absolute())
.or_else(|| {
std::env::var_os("HOME")
.map(|home| PathBuf::from(home).join(".cache"))
.filter(|p| p.is_absolute())
})?;
let root = base.join("nitr").join("apps");
let mut builder = std::fs::DirBuilder::new();
builder.recursive(true);
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt as _;
builder.mode(0o700);
}
builder.create(&root).ok()?;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
let mode = std::fs::metadata(&root).ok()?.permissions().mode();
if mode & 0o077 != 0 {
std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).ok()?;
}
}
Some(root)
}
fn sweep_stale_staging(cache: &Path, prefix: &str) {
let Ok(entries) = std::fs::read_dir(cache) else {
return;
};
for entry in entries.flatten() {
if entry.file_name().to_string_lossy().starts_with(prefix) {
let _ = std::fs::remove_dir_all(entry.path());
}
}
}
fn fresh_private_dir(parent: &Path, prefix: &str) -> anyhow::Result<PathBuf> {
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |d| d.as_nanos());
for attempt in 0..16u32 {
let dir = parent.join(format!(
"{prefix}.{}.{nanos:x}.{attempt}",
std::process::id()
));
let mut builder = std::fs::DirBuilder::new();
builder.recursive(false);
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt as _;
builder.mode(0o700);
}
match builder.create(&dir) {
Ok(()) => return Ok(dir),
Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(err) => {
return Err(err)
.with_context(|| format!("cannot create {} for the bundle", dir.display()));
}
}
}
bail!(
"cannot find a free extraction directory under {}",
parent.display()
)
}
fn extract(tar: &[u8], staging: &Path) -> anyhow::Result<()> {
let mut archive = tar::Archive::new(tar);
let entries = archive
.entries()
.context("cannot read the bundled application archive")?;
for entry in entries {
let mut entry = entry.context("cannot read a bundle archive entry")?;
let path = entry
.path()
.context("a bundle archive entry has an unreadable name")?
.into_owned();
if !path
.components()
.all(|c| matches!(c, Component::Normal(_) | Component::CurDir))
{
bail!(
"the bundled archive names `{}`, which would land outside \
the extraction directory; the bundle is corrupt or tampered with",
path.display()
);
}
let kind = entry.header().entry_type();
if !matches!(kind, tar::EntryType::Regular | tar::EntryType::Directory) {
bail!(
"the bundled archive contains `{}` as a {kind:?} entry; a bundle \
holds only regular files and directories, so the bundle is \
corrupt or tampered with",
path.display()
);
}
let unpacked = entry
.unpack_in(staging)
.with_context(|| format!("cannot extract `{}`", path.display()))?;
if !unpacked {
bail!(
"the archive entry `{}` was refused by the extractor",
path.display()
);
}
}
Ok(())
}
fn archivable(path: &Path, what: &str) -> anyhow::Result<()> {
let ok = path.is_relative()
&& path
.components()
.all(|c| matches!(c, Component::Normal(_) | Component::CurDir));
if !ok {
bail!(
"{what} points at {}, which is outside the application directory: \
a bundle can only contain files under the directory it is built from",
path.display()
);
}
Ok(())
}
fn append(builder: &mut tar::Builder<Vec<u8>>, path: &Path) -> anyhow::Result<()> {
if path.is_dir() {
builder
.append_dir_all(path, path)
.with_context(|| format!("cannot archive {}", path.display()))?;
} else {
builder
.append_path(path)
.with_context(|| format!("cannot archive {}", path.display()))?;
}
Ok(())
}
pub fn build(cfg_path: &Path, cfg: &Config, output: &Path) -> anyhow::Result<()> {
let exe = std::env::current_exe().context("cannot locate the running executable")?;
if read_appended(&exe)?.is_some() {
bail!("this executable already carries a bundle; build from the plain `nitr` binary");
}
let mut builder = tar::Builder::new(Vec::new());
builder.mode(tar::HeaderMode::Deterministic);
let mut header = tar::Header::new_gnu();
let cfg_bytes =
std::fs::read(cfg_path).with_context(|| format!("cannot read {}", cfg_path.display()))?;
header.set_size(cfg_bytes.len() as u64);
header.set_mode(0o644);
header.set_cksum();
builder.append_data(&mut header, CONFIG_NAME, cfg_bytes.as_slice())?;
let package_dir = cfg
.handler_script
.parent()
.filter(|p| !p.as_os_str().is_empty())
.map(Path::to_path_buf)
.unwrap_or_else(|| PathBuf::from("."));
archivable(&cfg.handler_script, "handler_script")?;
let mut seen = std::collections::BTreeSet::new();
for lua in lua_files(&package_dir)? {
if seen.insert(lua.clone()) {
append(&mut builder, &lua)?;
}
}
if seen.is_empty() {
append(&mut builder, &cfg.handler_script)?;
}
if let Some(script) = &cfg.config_script {
archivable(script, "config_script")?;
if seen.iter().all(|p| p != script) {
append(&mut builder, script)?;
}
}
let migrations = cfg.database.as_ref().and_then(|db| db.migrations());
for (what, dir) in [
("[templating] dir", cfg.templating.dir.as_ref()),
("[static] dir", cfg.static_files.dir.as_ref()),
("migrations", migrations.as_ref()),
] {
let Some(dir) = dir else { continue };
archivable(dir, what)?;
append(&mut builder, dir)?;
}
let tar = builder.into_inner().context("cannot finish the archive")?;
let exe_bytes = std::fs::read(&exe)?;
let mut out = std::fs::File::create(output)
.with_context(|| format!("cannot create {}", output.display()))?;
out.write_all(&exe_bytes)?;
out.write_all(&tar)?;
out.write_all(&(tar.len() as u64).to_le_bytes())?;
out.write_all(MAGIC)?;
drop(out);
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
std::fs::set_permissions(output, std::fs::Permissions::from_mode(0o755))?;
}
println!(
"built {} ({} file(s), {} archived)",
output.display(),
seen.len() + 1,
human_size(tar.len() as u64),
);
println!("run it anywhere: the database path still resolves against the working directory");
Ok(())
}
fn lua_files(dir: &Path) -> anyhow::Result<Vec<PathBuf>> {
let mut out = Vec::new();
let mut stack = vec![(dir.to_path_buf(), Vec::<PathBuf>::new())];
while let Some((dir, ancestors)) = stack.pop() {
let real = dir
.canonicalize()
.with_context(|| format!("cannot resolve the directory {}", dir.display()))?;
if ancestors.contains(&real) {
continue;
}
let entries = std::fs::read_dir(&dir)
.with_context(|| format!("cannot read the directory {}", dir.display()))?;
let mut chain = ancestors;
chain.push(real);
for entry in entries {
let path = entry?.path();
if path.is_dir() {
stack.push((path, chain.clone()));
} else if path.extension().is_some_and(|ext| ext == "lua") {
out.push(path);
}
}
}
out.sort();
Ok(out)
}
fn human_size(bytes: u64) -> String {
if bytes >= 1024 * 1024 {
format!("{:.1} MiB", bytes as f64 / (1024.0 * 1024.0))
} else {
format!("{:.1} KiB", bytes as f64 / 1024.0)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn only_paths_inside_the_root_are_archivable() {
assert!(archivable(Path::new("app.lua"), "x").is_ok());
assert!(archivable(Path::new("./sub/dir"), "x").is_ok());
assert!(archivable(Path::new("../escape.lua"), "x").is_err());
assert!(archivable(Path::new("/etc/passwd"), "x").is_err());
assert!(archivable(Path::new("a/../../b"), "x").is_err());
}
struct Scratch {
root: PathBuf,
}
impl Scratch {
fn new(label: &str) -> Self {
use std::sync::atomic::{AtomicU32, Ordering};
static NEXT: AtomicU32 = AtomicU32::new(0);
let id = NEXT.fetch_add(1, Ordering::Relaxed);
let root = std::env::temp_dir()
.join(format!("nitr-bundle-{label}-{}-{id}", std::process::id()));
std::fs::create_dir_all(&root).expect("create scratch dir");
Self { root }
}
}
impl Drop for Scratch {
fn drop(&mut self) {
if std::thread::panicking() {
eprintln!("[test] failed; keeping {}", self.root.display());
} else {
let _ = std::fs::remove_dir_all(&self.root);
}
}
}
fn raw_entry(builder: &mut tar::Builder<Vec<u8>>, name: &str, data: &[u8]) {
let mut header = tar::Header::new_gnu();
header.set_size(data.len() as u64);
header.set_mode(0o644);
header.as_gnu_mut().expect("gnu header").name[..name.len()]
.copy_from_slice(name.as_bytes());
header.set_cksum();
builder.append(&header, data).expect("append raw entry");
}
#[test]
fn wellformed_archives_extract_fully() {
let scratch = Scratch::new("extract-ok");
let staging = scratch.root.join("staging");
std::fs::create_dir_all(&staging).expect("mkdir");
let mut builder = tar::Builder::new(Vec::new());
raw_entry(&mut builder, "nitr.toml", b"listen = \"127.0.0.1:0\"");
raw_entry(&mut builder, "./app.lua", b"return {}");
let mut dir = tar::Header::new_gnu();
dir.set_entry_type(tar::EntryType::Directory);
dir.set_size(0);
dir.set_mode(0o755);
dir.as_gnu_mut().expect("gnu header").name[..7].copy_from_slice(b"routes/");
dir.set_cksum();
builder.append(&dir, &[][..]).expect("append dir");
raw_entry(&mut builder, "routes/notes.lua", b"return {}");
let tar = builder.into_inner().expect("finish");
extract(&tar, &staging).expect("a well-formed bundle extracts");
assert_eq!(
std::fs::read(staging.join("nitr.toml")).expect("config"),
b"listen = \"127.0.0.1:0\""
);
assert!(staging.join("app.lua").is_file());
assert!(staging.join("routes/notes.lua").is_file());
}
#[test]
fn hostile_archives_are_refused_and_write_nothing_outside() {
{
let scratch = Scratch::new("slip-dotdot");
let staging = scratch.root.join("staging");
std::fs::create_dir_all(&staging).expect("mkdir");
let mut builder = tar::Builder::new(Vec::new());
raw_entry(&mut builder, "ok.lua", b"return {}");
raw_entry(&mut builder, "../escape.txt", b"pwned");
let tar = builder.into_inner().expect("finish");
let err = extract(&tar, &staging).expect_err("a `..` entry must refuse");
assert!(
err.to_string().contains("../escape.txt"),
"the refusal must name the entry: {err}"
);
assert!(
!scratch.root.join("escape.txt").exists(),
"the traversal entry must not have landed above staging"
);
assert!(
!staging.join("escape.txt").exists(),
"the traversal entry must not have been re-rooted either"
);
}
{
let scratch = Scratch::new("slip-absolute");
let staging = scratch.root.join("staging");
std::fs::create_dir_all(&staging).expect("mkdir");
let forbidden = std::env::temp_dir().join(format!(
"nitr-bundle-absolute-escape-{}",
std::process::id()
));
let _ = std::fs::remove_file(&forbidden);
let mut builder = tar::Builder::new(Vec::new());
raw_entry(&mut builder, &forbidden.to_string_lossy(), b"pwned");
let tar = builder.into_inner().expect("finish");
extract(&tar, &staging).expect_err("an absolute entry must refuse");
assert!(
!forbidden.exists(),
"an absolute entry name must never be honored as written"
);
}
#[cfg(unix)]
{
let scratch = Scratch::new("slip-symlink");
let staging = scratch.root.join("staging");
std::fs::create_dir_all(&staging).expect("mkdir");
let mut builder = tar::Builder::new(Vec::new());
let mut link = tar::Header::new_gnu();
link.set_entry_type(tar::EntryType::Symlink);
link.set_size(0);
link.set_mode(0o777);
link.set_cksum();
builder
.append_link(&mut link, "link", "..")
.expect("append symlink");
raw_entry(&mut builder, "link/pwned.txt", b"pwned");
let tar = builder.into_inner().expect("finish");
let err = extract(&tar, &staging).expect_err("a symlink entry must refuse");
assert!(
err.to_string().contains("Symlink"),
"the refusal must name the entry type: {err}"
);
assert!(
!scratch.root.join("pwned.txt").exists(),
"the file behind the symlink must not have landed above staging"
);
assert!(
!staging.join("link").exists(),
"the link itself must not have been created before the refusal"
);
}
{
let scratch = Scratch::new("slip-hardlink");
let staging = scratch.root.join("staging");
std::fs::create_dir_all(&staging).expect("mkdir");
let mut builder = tar::Builder::new(Vec::new());
let mut link = tar::Header::new_gnu();
link.set_entry_type(tar::EntryType::Link);
link.set_size(0);
link.set_mode(0o644);
link.set_cksum();
builder
.append_link(&mut link, "alias", "../outside.txt")
.expect("append hard link");
let tar = builder.into_inner().expect("finish");
let err = extract(&tar, &staging).expect_err("a hard-link entry must refuse");
assert!(err.to_string().contains("Link"), "got: {err}");
}
}
#[test]
fn trailer_detection_ignores_plain_files() {
let dir = std::env::temp_dir();
let plain = dir.join(format!("nitr-bundle-test-plain-{}", std::process::id()));
std::fs::write(&plain, b"just a small file").expect("write");
assert!(read_appended(&plain).expect("read").is_none());
let bundled = dir.join(format!("nitr-bundle-test-tar-{}", std::process::id()));
let payload = b"PAYLOAD-BYTES";
let mut bytes = b"binary-part".to_vec();
bytes.extend_from_slice(payload);
bytes.extend_from_slice(&(payload.len() as u64).to_le_bytes());
bytes.extend_from_slice(MAGIC);
std::fs::write(&bundled, &bytes).expect("write");
let read = read_appended(&bundled).expect("read").expect("bundle");
assert_eq!(read, payload);
let mut corrupt = b"tiny".to_vec();
corrupt.extend_from_slice(&u64::MAX.to_le_bytes());
corrupt.extend_from_slice(MAGIC);
let path = dir.join(format!("nitr-bundle-test-corrupt-{}", std::process::id()));
std::fs::write(&path, &corrupt).expect("write");
assert!(read_appended(&path).is_err());
for p in [plain, bundled, path] {
std::fs::remove_file(p).ok();
}
}
}