diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 1311506eb..f772eede2 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -137,3 +137,7 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. ## JSONC span-preserving editing `crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. + +## HTTP Archive reader + +`crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned. diff --git a/Cargo.lock b/Cargo.lock index e481367c9..da0654156 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2129,6 +2129,14 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-har" +version = "0.1.0" +dependencies = [ + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-heif" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 50ec3c917..c8cd94409 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-har = { path = "crates/har" } craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } craft-score = { path = "crates/score" } diff --git a/crates/har/Cargo.toml b/crates/har/Cargo.toml new file mode 100644 index 000000000..c9a1b9f0b --- /dev/null +++ b/crates/har/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "craft-har" +description = "Typed HTTP Archive capture reader with explicit input admission" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde_json = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/har/src/lib.rs b/crates/har/src/lib.rs new file mode 100644 index 000000000..8f8fba2cb --- /dev/null +++ b/crates/har/src/lib.rs @@ -0,0 +1,230 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! HTTP Archive (HAR 1.2) captures, read into typed records. No redaction happens here; callers +//! decide what to keep. Capture headers and bodies can contain secrets: redact before display or sharing. +//! `parse` preserves compatibility and parses the whole JSON before limiting returned entries. +//! Use `parse_bounded` to cap admitted bytes; this is not a precise allocator or output-byte limit. + +use serde_json::Value; + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum HarError { + #[error("not valid JSON: {0}")] + BadJson(String), + #[error("not a HAR capture: {0}")] + NotHar(&'static str), +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct Har { + pub version: Option, + pub creator: Option, + pub pages: usize, + pub entries: Vec, + pub declared_entries: usize, + pub truncated: bool, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarEntry { + /// 0-based position in `log.entries`. + pub ordinal: usize, + pub started: Option, + pub time_ms: Option, + pub resource_type: Option, + pub server_ip: Option, + pub request: HarRequest, + pub response: HarResponse, + /// blocked, dns, connect, send, wait, receive, ssl (negative values mean "not applicable"). + pub timings: Vec<(String, f64)>, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarRequest { + pub method: String, + pub url: String, + pub http_version: Option, + pub headers: Vec<(String, String)>, + pub cookie_names: Vec, + pub post: Option, + pub body_size: Option, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarBody { + pub mime: Option, + pub text: Option, + /// Form parameter names (values are deliberately not surfaced by this type's users). + pub params: Vec<(String, Option)>, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarResponse { + pub status: i64, + pub status_text: Option, + pub http_version: Option, + pub headers: Vec<(String, String)>, + pub cookie_names: Vec, + pub redirect_url: Option, + pub content_size: Option, + pub mime: Option, + pub text: Option, + /// `base64` when `text` is base64-encoded. + pub encoding: Option, + pub body_size: Option, +} + +fn s(v: &Value, k: &str) -> Option { + v.get(k).and_then(Value::as_str).map(String::from) +} + +fn pairs(v: Option<&Value>) -> Vec<(String, String)> { + v.and_then(Value::as_array) + .map(|a| { + a.iter() + .filter_map(|h| Some((h.get("name")?.as_str()?.to_string(), h.get("value").and_then(Value::as_str).unwrap_or_default().to_string()))) + .collect() + }) + .unwrap_or_default() +} + +fn names(v: Option<&Value>) -> Vec { + v.and_then(Value::as_array).map(|a| a.iter().filter_map(|c| c.get("name")?.as_str().map(String::from)).collect()).unwrap_or_default() +} + +/// Parse a HAR document, keeping at most `max_entries` entries. +pub fn parse(json: &[u8], max_entries: usize) -> Result { + let json = json.strip_prefix(&[0xef, 0xbb, 0xbf]).unwrap_or(json); + let v: Value = serde_json::from_slice(json).map_err(|e| HarError::BadJson(e.to_string()))?; + let log = v.get("log").ok_or(HarError::NotHar("no \"log\" object"))?; + let entries = log.get("entries").and_then(Value::as_array).ok_or(HarError::NotHar("no \"log.entries\" array"))?; + let mut har = Har { + version: s(log, "version"), + creator: log + .get("creator") + .map(|c| format!("{} {}", s(c, "name").unwrap_or_default(), s(c, "version").unwrap_or_default()).trim().to_string()), + pages: log.get("pages").and_then(Value::as_array).map_or(0, Vec::len), + declared_entries: entries.len(), + ..Default::default() + }; + for (i, e) in entries.iter().enumerate() { + if har.entries.len() >= max_entries { + har.truncated = true; + break; + } + let req = e.get("request").unwrap_or(&Value::Null); + let res = e.get("response").unwrap_or(&Value::Null); + let content = res.get("content").unwrap_or(&Value::Null); + let post = req.get("postData").filter(|p| p.is_object()).map(|p| HarBody { + mime: s(p, "mimeType"), + text: s(p, "text"), + params: p + .get("params") + .and_then(Value::as_array) + .map(|a| a.iter().filter_map(|x| Some((x.get("name")?.as_str()?.to_string(), s(x, "value")))).collect()) + .unwrap_or_default(), + }); + let timings = e + .get("timings") + .and_then(Value::as_object) + .map(|m| m.iter().filter_map(|(k, v)| Some((k.clone(), v.as_f64()?))).collect()) + .unwrap_or_default(); + har.entries.push(HarEntry { + ordinal: i, + started: s(e, "startedDateTime"), + time_ms: e.get("time").and_then(Value::as_f64), + resource_type: s(e, "_resourceType"), + server_ip: s(e, "serverIPAddress"), + request: HarRequest { + method: s(req, "method").unwrap_or_default(), + url: s(req, "url").unwrap_or_default(), + http_version: s(req, "httpVersion"), + headers: pairs(req.get("headers")), + cookie_names: names(req.get("cookies")), + post, + body_size: req.get("bodySize").and_then(Value::as_i64), + }, + response: HarResponse { + status: res.get("status").and_then(Value::as_i64).unwrap_or(0), + status_text: s(res, "statusText"), + http_version: s(res, "httpVersion"), + headers: pairs(res.get("headers")), + cookie_names: names(res.get("cookies")), + redirect_url: s(res, "redirectURL").filter(|u| !u.is_empty()), + content_size: content.get("size").and_then(Value::as_i64), + mime: s(content, "mimeType"), + text: s(content, "text"), + encoding: s(content, "encoding"), + body_size: res.get("bodySize").and_then(Value::as_i64), + }, + timings, + }); + } + Ok(har) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_a_har_with_a_utf8_bom() { + let capture = br#"{"log":{"entries":[]}}"#; + let mut encoded = vec![0xef, 0xbb, 0xbf]; + encoded.extend_from_slice(capture); + assert_eq!(parse(&encoded, 1).unwrap(), parse(capture, 1).unwrap()); + assert!(parse(&[0xef, 0xbb], 1).is_err()); + } + + #[test] + fn parses_minimal_har() { + let j = br#"{"log":{"version":"1.2","creator":{"name":"x","version":"1"},"entries":[ + {"startedDateTime":"2026-01-01T00:00:00Z","time":12.5, + "request":{"method":"POST","url":"https://api.example.test/v1/items/42","headers":[{"name":"Cookie","value":"s=1"}],"cookies":[{"name":"s","value":"1"}], + "postData":{"mimeType":"application/json","text":"{\"a\":1}"}}, + "response":{"status":201,"headers":[],"content":{"size":2,"mimeType":"application/json","text":"{}"}}, + "timings":{"wait":10,"receive":2.5}}]}}"#; + let h = parse(j, 10).unwrap(); + assert_eq!(h.entries.len(), 1); + let e = &h.entries[0]; + assert_eq!(e.request.method, "POST"); + assert_eq!(e.response.status, 201); + assert_eq!(e.request.cookie_names, vec!["s"]); + assert_eq!(e.timings.len(), 2); + } + + #[test] + fn rejects_non_har() { + assert!(parse(b"{}", 1).is_err()); + assert!(parse(b"nope", 1).is_err()); + assert!(parse(br#"{"log":{"entries":[1,null,"x"]}}"#, 10).is_ok()); + } +} + +/// Reject oversized input before parsing its JSON. `max_entries` only limits returned records. +pub fn parse_bounded(json: &[u8], max_entries: usize, max_bytes: usize) -> Result { + if json.len() > max_bytes { + return Err(HarError::NotHar("input byte limit exceeded")); + } + parse(json, max_entries) +} + +#[cfg(test)] +mod admission_tests { + use super::*; + #[test] + fn input_admission_and_entry_limits_are_independent() { + let input = br#"{"log":{"entries":[null,{}]}}"#; + assert_eq!(parse_bounded(input, 2, input.len()).unwrap(), parse(input, 2).unwrap()); + assert_eq!(parse_bounded(b"bad JSON", 1, 0), Err(HarError::NotHar("input byte limit exceeded"))); + let empty = parse_bounded(input, 0, input.len()).unwrap(); + assert!(empty.truncated && empty.entries.is_empty()); + assert_eq!(empty.declared_entries, 2); + let one = parse_bounded(input, 1, input.len()).unwrap(); + assert!(one.truncated); + assert_eq!(one.entries.len(), 1); + assert_eq!(one.entries[0].ordinal, 0); + assert!(!parse_bounded(input, 2, input.len()).unwrap().truncated); + } +}