642d5a256791
asar.rs
//! Electron ASAR archives: a Chromium pickle holding a JSON directory tree, followed by file data.
//!
//! Layout: `u32 4` (size of the first pickle's payload), `u32 header_pickle_size`, then the header
//! pickle: `u32 payload_size`, `u32 json_len`, JSON. File data starts at `8 + header_pickle_size`;
//! each file's `offset` (a decimal string) is relative to that point.
use crate::bytes::Reader;
use serde_json::Value;
/// Headers bigger than this are refused (real ones are a few MiB at most).
pub const MAX_HEADER_BYTES: usize = 16 * 1024 * 1024;
/// Total bytes retained in entry paths and rejected names after expanding directory prefixes.
pub const MAX_PATH_BYTES: usize = 8 * 1024 * 1024;
/// Deepest directory nesting we walk.
pub const MAX_DEPTH: usize = 128;
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum AsarError {
#[error("not an ASAR archive: {0}")]
NotAsar(&'static str),
#[error("ASAR header is {0} bytes; the limit is {MAX_HEADER_BYTES}")]
HeaderTooLarge(usize),
#[error("ASAR header JSON is invalid: {0}")]
BadJson(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AsarKind {
File,
Directory,
Link,
}
/// Per-file integrity block (Electron's ASAR integrity feature).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct AsarIntegrity {
pub algorithm: String,
/// Lowercase hex digest of the whole file.
pub hash: String,
pub block_size: Option<u64>,
pub blocks: usize,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct AsarEntry {
/// Slash-separated path inside the archive.
pub path: String,
pub kind: AsarKind,
pub size: u64,
/// Offset relative to the data area (files only, not for unpacked files).
pub offset: Option<u64>,
/// Stored next to the archive in `<name>.asar.unpacked/` rather than inside it.
pub unpacked: bool,
pub executable: bool,
pub link: Option<String>,
pub integrity: Option<AsarIntegrity>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize)]
pub struct AsarArchive {
pub json_bytes: usize,
/// Absolute offset in the archive where file data starts.
pub data_offset: u64,
pub entries: Vec<AsarEntry>,
pub truncated: bool,
/// Entries skipped because their names could escape the tree (`..`, `/`, empty).
pub rejected_names: Vec<String>,
}
impl AsarArchive {
pub fn get(&self, path: &str) -> Option<&AsarEntry> {
self.entries.iter().find(|e| e.path == path)
}
}
/// Parse the header and list entries (at most `max_entries`).
pub fn parse(data: &[u8], max_entries: usize) -> Result<AsarArchive, AsarError> {
let r = Reader::new(data);
if r.u32_le(0) != Some(4) {
return Err(AsarError::NotAsar("first pickle size is not 4"));
}
let header_pickle = r.u32_le(4).ok_or(AsarError::NotAsar("truncated"))? as usize;
let json_len = r.u32_le(12).ok_or(AsarError::NotAsar("truncated"))? as usize;
if json_len > MAX_HEADER_BYTES {
return Err(AsarError::HeaderTooLarge(json_len));
}
let payload_size = r.u32_le(8).ok_or(AsarError::NotAsar("truncated"))? as usize;
if header_pickle < json_len.saturating_add(8) || payload_size.checked_add(4) != Some(header_pickle) {
return Err(AsarError::NotAsar("header sizes disagree"));
}
if r.slice(8, header_pickle).is_none() {
return Err(AsarError::NotAsar("header runs past the end"));
}
let json = r.slice(16, json_len).ok_or(AsarError::NotAsar("header runs past the end"))?;
if json.first() != Some(&b'{') {
return Err(AsarError::NotAsar("header is not a JSON object"));
}
let v: Value = serde_json::from_slice(json).map_err(|e| AsarError::BadJson(e.to_string()))?;
let mut out = AsarArchive { json_bytes: json_len, data_offset: 8 + header_pickle as u64, ..Default::default() };
let files = v.get("files").ok_or_else(|| AsarError::BadJson("no \"files\" object".into()))?;
let mut remaining = MAX_PATH_BYTES;
walk(files, "", 0, max_entries, &mut remaining, &mut out)?;
Ok(out)
}
fn walk(files: &Value, prefix: &str, depth: usize, max: usize, remaining: &mut usize, out: &mut AsarArchive) -> Result<(), AsarError> {
let map = files.as_object().ok_or_else(|| AsarError::BadJson(format!("files at {prefix:?} is not an object")))?;
if depth > MAX_DEPTH {
out.truncated = true;
return Ok(());
}
for (name, node) in map {
if out.entries.len() + out.rejected_names.len() >= max {
out.truncated = true;
return Ok(());
}
// A compact tree can repeat one long directory prefix in thousands of paths. Charge
// the complete expanded identity before allocating it, including rejected names.
let Some(bytes) = prefix.len().checked_add(name.len()).filter(|bytes| *bytes <= *remaining) else {
out.truncated = true;
return Ok(());
};
*remaining -= bytes;
let path = format!("{prefix}{name}");
if name.is_empty() || name == "." || name == ".." || name.contains('/') || name.contains('\\') || name.contains('\0') {
out.rejected_names.push(path);
continue;
}
if !node.is_object() {
return Err(AsarError::BadJson(format!("node at {path:?} is not an object")));
}
if node.get("files").is_some() && node.get("link").is_some() {
return Err(AsarError::BadJson(format!("node at {path:?} is both a directory and a link")));
}
if let Some(children) = node.get("files") {
out.entries.push(AsarEntry {
path: path.clone(),
kind: AsarKind::Directory,
size: 0,
offset: None,
unpacked: false,
executable: false,
link: None,
integrity: None,
});
walk(children, &format!("{path}/"), depth + 1, max, remaining, out)?;
} else if let Some(link) = node.get("link") {
let link = link.as_str().ok_or_else(|| AsarError::BadJson(format!("link at {path:?} is not a string")))?;
out.entries.push(AsarEntry {
path,
kind: AsarKind::Link,
size: 0,
offset: None,
unpacked: false,
executable: false,
link: Some(link.to_string()),
integrity: None,
});
} else {
let size = node.get("size").and_then(Value::as_u64).ok_or_else(|| AsarError::BadJson(format!("file at {path:?} has no unsigned size")))?;
let unpacked = match node.get("unpacked") {
None => false,
Some(value) => value.as_bool().ok_or_else(|| AsarError::BadJson(format!("unpacked at {path:?} is not a boolean")))?,
};
let offset = node.get("offset").and_then(|o| o.as_str().and_then(|s| s.parse::<u64>().ok()).or_else(|| o.as_u64()));
if !unpacked && offset.is_none() {
return Err(AsarError::BadJson(format!("packed file at {path:?} has no unsigned offset")));
}
let integrity = node.get("integrity").map(|i| AsarIntegrity {
algorithm: i.get("algorithm").and_then(Value::as_str).unwrap_or_default().to_string(),
hash: i.get("hash").and_then(Value::as_str).unwrap_or_default().to_ascii_lowercase(),
block_size: i.get("blockSize").and_then(Value::as_u64),
blocks: i.get("blocks").and_then(Value::as_array).map_or(0, Vec::len),
});
out.entries.push(AsarEntry {
path,
kind: AsarKind::File,
size,
offset: if unpacked { None } else { offset },
unpacked,
executable: node.get("executable").and_then(Value::as_bool).unwrap_or(false),
link: None,
integrity,
});
}
}
Ok(())
}
/// The bytes of a packed file, or `None` when it is unpacked, out of range or not a file.
pub fn file_bytes<'a>(data: &'a [u8], archive: &AsarArchive, entry: &AsarEntry) -> Option<&'a [u8]> {
if entry.kind != AsarKind::File || entry.unpacked {
return None;
}
let start = archive.data_offset.checked_add(entry.offset?)?;
let start = usize::try_from(start).ok()?;
let len = usize::try_from(entry.size).ok()?;
Reader::new(data).slice(start, len)
}
/// True when the bytes start like an ASAR (pickle size 4, JSON object at 16).
pub fn looks_like_asar(data: &[u8]) -> bool {
let r = Reader::new(data);
r.u32_le(0) == Some(4) && data.get(16) == Some(&b'{')
}
fn insert_node(map: &mut serde_json::Map<String, Value>, parts: &[&str], leaf: Value) {
match parts {
[] => {}
[last] => {
map.insert((*last).to_string(), leaf);
}
[dir, rest @ ..] => {
let entry = map.entry((*dir).to_string()).or_insert_with(|| serde_json::json!({"files": {}}));
if let Some(next) = entry.get_mut("files").and_then(Value::as_object_mut) {
insert_node(next, rest, leaf);
}
}
}
}
/// Build an ASAR from (path, bytes) pairs. Used by tests and fixture builders.
pub fn build(files: &[(&str, &[u8])]) -> Vec<u8> {
let mut root = serde_json::Map::new();
let mut data = Vec::new();
for (path, body) in files {
let parts: Vec<&str> = path.split('/').filter(|p| !p.is_empty()).collect();
insert_node(&mut root, &parts, serde_json::json!({"size": body.len(), "offset": data.len().to_string()}));
data.extend_from_slice(body);
}
let json = serde_json::to_vec(&serde_json::json!({"files": root})).unwrap_or_default();
let pad = (4 - json.len() % 4) % 4;
let payload = json.len() + 4 + pad;
let mut out = Vec::new();
out.extend_from_slice(&4u32.to_le_bytes());
out.extend_from_slice(&((payload + 4) as u32).to_le_bytes());
out.extend_from_slice(&(payload as u32).to_le_bytes());
out.extend_from_slice(&(json.len() as u32).to_le_bytes());
out.extend_from_slice(&json);
out.extend(std::iter::repeat_n(0u8, pad));
out.extend_from_slice(&data);
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn invalid_names_consume_the_listing_budget() {
let files = serde_json::json!({"../a": {}, "../b": {}, "ok": {"size": 0, "offset": "0"}});
let mut archive = AsarArchive::default();
let mut remaining = MAX_PATH_BYTES;
walk(&files, "", 0, 1, &mut remaining, &mut archive).unwrap();
assert_eq!(archive.rejected_names.len(), 1);
assert!(archive.entries.is_empty());
assert!(archive.truncated);
}
fn archive_header(value: Value) -> Vec<u8> {
let json = serde_json::to_vec(&value).unwrap();
let mut data = 4u32.to_le_bytes().to_vec();
data.extend_from_slice(&((json.len() + 8) as u32).to_le_bytes());
data.extend_from_slice(&((json.len() + 4) as u32).to_le_bytes());
data.extend_from_slice(&(json.len() as u32).to_le_bytes());
data.extend_from_slice(&json);
data
}
#[test]
fn malformed_nodes_do_not_become_empty_files() {
for files in [serde_json::json!([]), serde_json::json!(null), serde_json::json!(42)] {
assert!(matches!(parse(&archive_header(serde_json::json!({"files": files})), 10), Err(AsarError::BadJson(_))));
}
for node in [
serde_json::json!(null),
serde_json::json!(false),
serde_json::json!([]),
serde_json::json!({}),
serde_json::json!({"files": []}),
serde_json::json!({"files": {}, "link": "target"}),
serde_json::json!({"link": 42}),
serde_json::json!({"size": -1, "offset": "0"}),
serde_json::json!({"size": "1", "offset": "0"}),
serde_json::json!({"size": 0}),
serde_json::json!({"size": 0, "offset": "-1"}),
serde_json::json!({"size": 0, "offset": "18446744073709551616"}),
serde_json::json!({"size": 0, "offset": "0", "unpacked": "false"}),
] {
let data = archive_header(serde_json::json!({"files": {"bad": node}}));
assert!(matches!(parse(&data, 10), Err(AsarError::BadJson(_))), "{node}");
}
}
#[test]
fn valid_empty_unpacked_and_link_nodes_keep_their_kinds() {
let data = archive_header(serde_json::json!({"files": {
"directory": {"files": {}},
"empty": {"size": 0, "offset": "0"},
"numeric": {"size": 0, "offset": 0},
"external": {"size": 10, "unpacked": true},
"link": {"link": "empty"}
}}));
let archive = parse(&data, 10).unwrap();
assert_eq!(archive.entries.len(), 5);
assert_eq!(archive.get("directory").unwrap().kind, AsarKind::Directory);
assert_eq!(archive.get("link").unwrap().kind, AsarKind::Link);
assert_eq!(file_bytes(&data, &archive, archive.get("empty").unwrap()), Some(&b""[..]));
assert_eq!(file_bytes(&data, &archive, archive.get("numeric").unwrap()), Some(&b""[..]));
assert!(archive.get("external").unwrap().unpacked);
assert_eq!(file_bytes(&data, &archive, archive.get("external").unwrap()), None);
}
#[test]
fn round_trip() {
let a = build(&[("package.json", b"{\"main\":\"main.js\"}"), ("src/main.js", b"require('electron')")]);
assert!(looks_like_asar(&a));
let p = parse(&a, 100).unwrap();
let main = p.get("src/main.js").unwrap();
assert_eq!(file_bytes(&a, &p, main).unwrap(), b"require('electron')");
assert_eq!(p.get("src").unwrap().kind, AsarKind::Directory);
}
#[test]
fn rejects_escaping_names_and_bounds() {
let json = br#"{"files":{"..":{"size":1,"offset":"0"},"a/b":{"size":1,"offset":"0"},"ok":{"size":99,"offset":"0"}}}"#;
let mut a = 4u32.to_le_bytes().to_vec();
a.extend_from_slice(&((json.len() + 8) as u32).to_le_bytes());
a.extend_from_slice(&((json.len() + 4) as u32).to_le_bytes());
a.extend_from_slice(&(json.len() as u32).to_le_bytes());
a.extend_from_slice(json);
let p = parse(&a, 10).unwrap();
assert_eq!(p.rejected_names.len(), 2);
let ok = p.get("ok").unwrap();
assert!(file_bytes(&a, &p, ok).is_none(), "size runs past the end");
}
#[test]
fn hostile_inputs_do_not_panic() {
let a = build(&[("x/y/z.js", b"1"), ("q", b"22")]);
for cut in 0..a.len() {
if let Ok(p) = parse(&a[..cut], 10) {
for e in &p.entries {
let _ = file_bytes(&a[..cut], &p, e);
}
}
}
let mut deep = String::from("{\"files\":");
for _ in 0..300 {
deep.push_str("{\"d\":{\"files\":");
}
let mut a = 4u32.to_le_bytes().to_vec();
a.extend_from_slice(&((deep.len() + 8) as u32).to_le_bytes());
a.extend_from_slice(&((deep.len() + 4) as u32).to_le_bytes());
a.extend_from_slice(&(deep.len() as u32).to_le_bytes());
a.extend_from_slice(deep.as_bytes());
assert!(parse(&a, 10).is_err());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.