use std::{collections::HashSet, fmt, path::Path};
use serde::{de::Error as _, Deserialize, Deserializer, Serialize, Serializer};
use url::Url;
use crate::{Error, Result};
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct SafeRelativePath(String);
impl SafeRelativePath {
pub fn new(path: impl Into<String>) -> Result<Self> {
let path = path.into();
validate_relative_path(&path)?;
Ok(Self(path))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn join_under(&self, root: &Path) -> std::path::PathBuf {
self.0
.split('/')
.fold(root.to_path_buf(), |path, part| path.join(part))
}
}
impl fmt::Display for SafeRelativePath {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.0)
}
}
impl TryFrom<String> for SafeRelativePath {
type Error = Error;
fn try_from(value: String) -> Result<Self> {
Self::new(value)
}
}
impl Serialize for SafeRelativePath {
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(&self.0)
}
}
impl<'de> Deserialize<'de> for SafeRelativePath {
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::new(value).map_err(D::Error::custom)
}
}
fn validate_relative_path(path: &str) -> Result<()> {
let invalid = |reason| Error::InvalidRelativePath {
path: path.to_owned(),
reason,
};
if path.is_empty() {
return Err(invalid("path is empty"));
}
if path.starts_with('/') || path.starts_with('\\') {
return Err(invalid("absolute paths are forbidden"));
}
if path.contains('\\') {
return Err(invalid("backslash separators are forbidden"));
}
if path.contains('\0') {
return Err(invalid("NUL bytes are forbidden"));
}
for component in path.split('/') {
if component.is_empty() || component == "." || component == ".." {
return Err(invalid(
"empty, current, and parent components are forbidden",
));
}
if component.chars().any(|character| {
character.is_control() || matches!(character, '<' | '>' | ':' | '"' | '|' | '?' | '*')
}) {
return Err(invalid("component contains a non-portable character"));
}
if component.ends_with('.') || component.ends_with(' ') {
return Err(invalid("component has a non-portable suffix"));
}
let stem = component.split('.').next().unwrap_or_default();
let reserved = matches!(
stem.to_ascii_uppercase().as_str(),
"CON"
| "PRN"
| "AUX"
| "NUL"
| "COM1"
| "COM2"
| "COM3"
| "COM4"
| "COM5"
| "COM6"
| "COM7"
| "COM8"
| "COM9"
| "LPT1"
| "LPT2"
| "LPT3"
| "LPT4"
| "LPT5"
| "LPT6"
| "LPT7"
| "LPT8"
| "LPT9"
);
if reserved {
return Err(invalid("component is a reserved Windows device name"));
}
}
Ok(())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum HashAlgorithm {
Sha1,
Sha256,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct FileHash {
algorithm: HashAlgorithm,
value: String,
}
impl<'de> Deserialize<'de> for FileHash {
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct SerializedHash {
algorithm: HashAlgorithm,
value: String,
}
let value = SerializedHash::deserialize(deserializer)?;
Self::new(value.algorithm, value.value).map_err(D::Error::custom)
}
}
impl FileHash {
pub fn new(algorithm: HashAlgorithm, value: impl Into<String>) -> Result<Self> {
let value = value.into().to_ascii_lowercase();
let expected_len = match algorithm {
HashAlgorithm::Sha1 => 40,
HashAlgorithm::Sha256 => 64,
};
if value.len() != expected_len || !value.bytes().all(|byte| byte.is_ascii_hexdigit()) {
return Err(Error::InvalidConfig(format!(
"invalid {algorithm:?} digest"
)));
}
Ok(Self { algorithm, value })
}
#[must_use]
pub const fn algorithm(&self) -> HashAlgorithm {
self.algorithm
}
#[must_use]
pub fn value(&self) -> &str {
&self.value
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileEntry {
pub path: SafeRelativePath,
pub url: Url,
pub size: Option<u64>,
pub hash: Option<FileHash>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileManifest {
pub format_version: u32,
pub files: Vec<FileEntry>,
}
impl FileManifest {
pub const FORMAT_VERSION: u32 = 1;
pub fn validate(&self) -> Result<()> {
if self.format_version != Self::FORMAT_VERSION {
return Err(Error::UnsupportedFormat {
kind: "file manifest",
version: self.format_version,
});
}
let mut paths = HashSet::with_capacity(self.files.len());
for file in &self.files {
if !paths.insert(file.path.clone()) {
return Err(Error::InvalidConfig(format!(
"duplicate manifest path `{}`",
file.path
)));
}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_path_traversal_and_absolute_paths() {
for candidate in [
"../secret",
"mods/../../secret",
"/etc/passwd",
r"C:\\Windows",
r"mods\\evil.jar",
"mods/CON.txt",
] {
assert!(
SafeRelativePath::new(candidate).is_err(),
"accepted {candidate}"
);
}
}
#[test]
fn accepts_portable_nested_paths() {
let path = SafeRelativePath::new("mods/example-1.0.jar").expect("valid path");
assert_eq!(path.as_str(), "mods/example-1.0.jar");
}
#[test]
fn validates_hash_length_and_hexadecimal_content() {
assert!(FileHash::new(HashAlgorithm::Sha1, "a".repeat(40)).is_ok());
assert!(FileHash::new(HashAlgorithm::Sha256, "z".repeat(64)).is_err());
}
#[test]
fn deserialization_preserves_hash_validation() {
let invalid = r#"{"algorithm":"sha256","value":"not-a-digest"}"#;
assert!(serde_json::from_str::<FileHash>(invalid).is_err());
}
#[test]
fn manifest_rejects_duplicate_paths() {
let path = SafeRelativePath::new("mods/example.jar").expect("path");
let entry = FileEntry {
path,
url: Url::parse("https://example.test/mod.jar").expect("URL"),
size: None,
hash: None,
};
let manifest = FileManifest {
format_version: FileManifest::FORMAT_VERSION,
files: vec![entry.clone(), entry],
};
assert!(manifest.validate().is_err());
}
#[test]
fn generated_paths_preserve_containment_invariant() {
let root = Path::new("sandbox-root");
for index in 0..1_000 {
let candidate = format!("mods/group-{}/file-{index}.jar", index % 17);
let validated = SafeRelativePath::new(&candidate).expect("generated safe path");
assert!(validated.join_under(root).starts_with(root));
for hostile in [
format!("../{candidate}"),
format!("mods/{index}/../../escape"),
format!(r"mods\{index}\escape.jar"),
] {
assert!(SafeRelativePath::new(hostile).is_err());
}
}
}
}