use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::{
fs,
path::{Path, PathBuf},
};
use crate::template::Template;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HookOrigin {
Interview { index: usize },
TopLevel { index: usize },
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScriptDigest {
pub rel: String,
pub sha256: [u8; 32],
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HookView {
pub origin: HookOrigin,
pub node: Value,
pub scripts: Vec<ScriptDigest>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HookSurface {
hooks: Vec<HookView>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ReviewDigest(String);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Trust {
Trusted,
NeedsReview,
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct HookSurfaceDiff {
pub added: Vec<HookView>,
pub removed: Vec<HookView>,
pub changed: Vec<(HookView, HookView)>,
}
#[derive(Debug, thiserror::Error)]
pub enum ReviewError {
#[error("{path}: {source}")]
Io {
path: PathBuf,
source: std::io::Error,
},
#[error("{0}: executed file escapes the template root")]
Escape(PathBuf),
}
impl ReviewDigest {
pub fn parse(value: &str) -> Result<Self, String> {
if is_digest(value) {
Ok(Self(value.to_owned()))
} else {
Err(format!("invalid review digest: {value}"))
}
}
pub fn as_str(&self) -> &str {
&self.0
}
}
fn is_digest(value: &str) -> bool {
value.strip_prefix("sha256:").is_some_and(|hex| {
hex.len() == 64
&& hex
.bytes()
.all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
})
}
impl<'de> Deserialize<'de> for ReviewDigest {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let value = String::deserialize(deserializer)?;
Self::parse(&value).map_err(serde::de::Error::custom)
}
}
pub fn evaluate_trust(approved: Option<&ReviewDigest>, live: &ReviewDigest) -> Trust {
match approved {
Some(approved) if approved == live => Trust::Trusted,
_ => Trust::NeedsReview,
}
}
const FILE_REFERENCING_KEYS: &[&str] = &["script", "run", "args"];
#[cfg(test)]
const NODE_ONLY_KEYS: &[&str] = &[
"cwd",
"each",
"when",
"id",
"capture",
"allow-failure",
"parse",
"status-id",
];
impl HookSurface {
pub fn of(template: &Template) -> Result<Self, ReviewError> {
let mut hooks = Vec::new();
for (index, node) in template.interview_hook_nodes.iter().enumerate() {
let command = node.get("hook").unwrap_or(node);
let scripts = executed_files(command, &template.root)?;
hooks.push(HookView {
origin: HookOrigin::Interview { index },
node: node.clone(),
scripts,
});
}
for (index, node) in template.top_hook_nodes.iter().enumerate() {
let scripts = executed_files(node, &template.root)?;
hooks.push(HookView {
origin: HookOrigin::TopLevel { index },
node: node.clone(),
scripts,
});
}
Ok(Self { hooks })
}
pub fn views(&self) -> &[HookView] {
&self.hooks
}
pub fn digest(&self) -> ReviewDigest {
let mut hasher = Sha256::new();
hasher.update(b"toha-hook-surface-v1");
frame_len(&mut hasher, self.hooks.len());
for view in &self.hooks {
let (tag, index) = match view.origin {
HookOrigin::Interview { index } => (0u8, index),
HookOrigin::TopLevel { index } => (1u8, index),
};
hasher.update([tag]);
frame_len(&mut hasher, index);
frame_bytes(&mut hasher, canonical_json(&view.node).as_bytes());
frame_len(&mut hasher, view.scripts.len());
for script in &view.scripts {
frame_bytes(&mut hasher, script.rel.as_bytes());
hasher.update(script.sha256);
}
}
ReviewDigest(format!("sha256:{:x}", hasher.finalize()))
}
pub fn diff(&self, prior: &HookSurface) -> HookSurfaceDiff {
let mut diff = HookSurfaceDiff::default();
for view in &self.hooks {
match prior.hooks.iter().find(|p| p.origin == view.origin) {
None => diff.added.push(view.clone()),
Some(before) if before != view => diff.changed.push((before.clone(), view.clone())),
Some(_) => {}
}
}
for before in &prior.hooks {
if !self.hooks.iter().any(|v| v.origin == before.origin) {
diff.removed.push(before.clone());
}
}
diff
}
}
fn executed_files(command: &Value, root: &Path) -> Result<Vec<ScriptDigest>, ReviewError> {
let mut scripts = Vec::new();
for key in FILE_REFERENCING_KEYS {
match *key {
"script" => {
if let Some(script) = command.get("script").and_then(Value::as_str) {
scripts.push(hash_declared(root, script)?);
}
}
token_vector => {
let tokens = command
.get(token_vector)
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(Value::as_str);
for token in tokens {
if is_literal(token)
&& let Some(script) = hash_literal(root, token)?
{
scripts.push(script);
}
}
}
}
}
Ok(scripts)
}
fn is_literal(token: &str) -> bool {
!token.contains("{{") && !token.contains("{%") && !token.contains("{#")
}
fn hash_declared(root: &Path, token: &str) -> Result<ScriptDigest, ReviewError> {
if Path::new(token).is_absolute() {
return Err(ReviewError::Escape(PathBuf::from(token)));
}
let candidate = root.join(token);
let actual = candidate.canonicalize().map_err(|source| ReviewError::Io {
path: candidate.clone(),
source,
})?;
if !actual.starts_with(root) {
return Err(ReviewError::Escape(actual));
}
hash_file(root, &actual).and_then(|script| {
script.ok_or_else(|| ReviewError::Io {
path: actual,
source: std::io::Error::new(std::io::ErrorKind::InvalidInput, "not a file"),
})
})
}
fn hash_literal(root: &Path, token: &str) -> Result<Option<ScriptDigest>, ReviewError> {
if Path::new(token).is_absolute() {
return Ok(None);
}
let candidate = root.join(token);
let Ok(actual) = candidate.canonicalize() else {
return Ok(None);
};
if !actual.starts_with(root) {
return Ok(None);
}
hash_file(root, &actual)
}
fn hash_file(root: &Path, actual: &Path) -> Result<Option<ScriptDigest>, ReviewError> {
if !actual.is_file() {
return Ok(None);
}
let bytes = fs::read(actual).map_err(|source| ReviewError::Io {
path: actual.to_owned(),
source,
})?;
let rel = actual
.strip_prefix(root)
.unwrap_or(actual)
.to_string_lossy()
.replace('\\', "/");
Ok(Some(ScriptDigest {
rel,
sha256: Sha256::digest(&bytes).into(),
}))
}
fn frame_bytes(hasher: &mut Sha256, bytes: &[u8]) {
frame_len(hasher, bytes.len());
hasher.update(bytes);
}
fn frame_len(hasher: &mut Sha256, len: usize) {
hasher.update((len as u64).to_le_bytes());
}
fn canonical_json(value: &Value) -> String {
let mut out = String::new();
write_canonical(value, &mut out);
out
}
fn write_canonical(value: &Value, out: &mut String) {
match value {
Value::Object(map) => {
let mut keys: Vec<&String> = map.keys().collect();
keys.sort();
out.push('{');
for (i, key) in keys.iter().enumerate() {
if i > 0 {
out.push(',');
}
out.push_str(&serde_json::to_string(key).expect("string key"));
out.push(':');
write_canonical(&map[*key], out);
}
out.push('}');
}
Value::Array(items) => {
out.push('[');
for (i, item) in items.iter().enumerate() {
if i > 0 {
out.push(',');
}
write_canonical(item, out);
}
out.push(']');
}
scalar => out.push_str(&serde_json::to_string(scalar).expect("scalar value")),
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn load(files: &[(&str, &str)]) -> Template {
let dir = tempfile::tempdir().unwrap();
for (rel, contents) in files {
let path = dir.path().join(rel);
fs::create_dir_all(path.parent().unwrap()).unwrap();
fs::write(&path, contents).unwrap();
#[cfg(unix)]
if rel.ends_with(".sh") {
use std::os::unix::fs::PermissionsExt;
fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).unwrap();
}
}
fs::create_dir_all(dir.path().join("template")).unwrap();
let template = Template::load(dir.path()).unwrap();
std::mem::forget(dir);
template
}
fn digest_of(files: &[(&str, &str)]) -> ReviewDigest {
HookSurface::of(&load(files)).unwrap().digest()
}
#[test]
fn digest_is_deterministic_and_valid() {
let files = &[(
"template.yml",
"name: sample\nhooks:\n - run: [ tool, call ]\n",
)];
let first = digest_of(files);
let second = digest_of(files);
assert_eq!(first, second);
assert!(is_digest(first.as_str()), "{}", first.as_str());
}
#[test]
fn answer_and_documentation_changes_do_not_change_the_digest() {
let with_hook = "name: sample\ninterview:\n - id: who\n type: text\n prompt: who\nhooks:\n - run: [ tool, call ]\n";
let more_questions = "name: sample\ndata:\n x: 1\ninterview:\n - id: who\n type: text\n prompt: who\n - id: what\n type: text\n prompt: what\nmessages:\n after-apply: done\nhooks:\n - run: [ tool, call ]\n";
assert_eq!(
digest_of(&[("template.yml", with_hook)]),
digest_of(&[("template.yml", more_questions)]),
);
}
#[test]
fn every_hook_field_changes_the_digest() {
let base = "name: sample\nhooks:\n - run: [ tool, call ]\n";
let base_digest = digest_of(&[("template.yml", base)]);
let variants = [
"name: sample\nhooks:\n - run: [ tool, other ]\n",
"name: sample\nhooks:\n - run: [ tool, call ]\n cwd: sub\n",
"name: sample\nhooks:\n - run: [ tool, call ]\n when: \"true\"\n",
"name: sample\nhooks:\n - run: [ tool, call ]\n each: \"[1] as item\"\n",
"name: sample\nhooks:\n - run: [ tool, call ]\n - run: [ tool, again ]\n",
];
for variant in variants {
assert_ne!(
digest_of(&[("template.yml", variant)]),
base_digest,
"variant did not change the digest:\n{variant}"
);
}
}
#[test]
fn canonical_encoding_is_sensitive_to_every_key() {
let base = json!({"hook": {"run": ["tool", "call"], "cwd": "x"}});
let surface = |node: &Value| {
HookSurface {
hooks: vec![HookView {
origin: HookOrigin::Interview { index: 0 },
node: node.clone(),
scripts: vec![],
}],
}
.digest()
};
let base_digest = surface(&base);
let mutations = [
json!({"hook": {"run": ["tool", "other"], "cwd": "x"}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "y"}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "when": "true"}}),
json!({"hook": {"run": ["tool", "call"]}}),
json!({"when": "true", "hook": {"run": ["tool", "call"], "cwd": "x"}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "id": "t"}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "capture": ["stdout"]}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "allow-failure": true}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "parse": "json"}}),
json!({"hook": {"run": ["tool", "call"], "cwd": "x", "status-id": "s"}}),
];
for mutation in mutations {
assert_ne!(surface(&mutation), base_digest, "{mutation}");
}
}
#[test]
fn declared_script_bytes_are_covered() {
let template = "name: sample\nhooks:\n - script: setup.sh\n";
let before = digest_of(&[("template.yml", template), ("setup.sh", "echo one\n")]);
let after = digest_of(&[("template.yml", template), ("setup.sh", "echo two\n")]);
assert_ne!(before, after, "changed script bytes must change the digest");
}
#[test]
fn literal_in_tree_run_path_bytes_are_covered() {
let template = "name: sample\nhooks:\n - run: [ python, scripts/x.py ]\n";
let before = digest_of(&[("template.yml", template), ("scripts/x.py", "print(1)\n")]);
let after = digest_of(&[("template.yml", template), ("scripts/x.py", "print(2)\n")]);
assert_ne!(
before, after,
"changed run-target bytes must change the digest"
);
}
#[test]
fn jinja_run_path_bytes_are_the_accepted_residual_gap() {
let template = "name: sample\nhooks:\n - run: [ python, \"scripts/{{ 'x' }}.py\" ]\n";
let before = digest_of(&[("template.yml", template), ("scripts/x.py", "print(1)\n")]);
let after = digest_of(&[("template.yml", template), ("scripts/x.py", "print(2)\n")]);
assert_eq!(
before, after,
"a Jinja run target is out of the covered surface"
);
}
#[test]
fn a_missing_declared_script_cannot_be_read() {
let template = load(&[
(
"template.yml",
"name: sample\nhooks:\n - script: setup.sh\n",
),
("setup.sh", "echo one\n"),
]);
fs::remove_file(template.root.join("setup.sh")).unwrap();
assert!(matches!(
HookSurface::of(&template),
Err(ReviewError::Io { .. })
));
}
#[test]
fn parse_rejects_forged_digests() {
assert!(
ReviewDigest::parse(
"sha256:0000000000000000000000000000000000000000000000000000000000000000"
)
.is_ok()
);
for bad in [
"trust me",
"sha256:tooshort",
"sha1:0000000000000000000000000000000000000000",
"sha256:0000000000000000000000000000000000000000000000000000000000ABCDEF",
] {
assert!(ReviewDigest::parse(bad).is_err(), "{bad}");
}
}
#[test]
fn evaluate_trust_is_equality_of_stored_and_live() {
let live = digest_of(&[("template.yml", "name: sample\nhooks:\n - run: [ a ]\n")]);
let other = digest_of(&[("template.yml", "name: sample\nhooks:\n - run: [ b ]\n")]);
assert_eq!(evaluate_trust(Some(&live), &live), Trust::Trusted);
assert_eq!(evaluate_trust(Some(&other), &live), Trust::NeedsReview);
assert_eq!(evaluate_trust(None, &live), Trust::NeedsReview);
}
#[test]
fn diff_reports_added_removed_and_changed_nodes() {
let prior = HookSurface::of(&load(&[(
"template.yml",
"name: sample\nhooks:\n - run: [ tool, call ]\n - run: [ tool, gone ]\n",
)]))
.unwrap();
let live = HookSurface::of(&load(&[(
"template.yml",
"name: sample\nhooks:\n - run: [ tool, changed ]\n",
)]))
.unwrap();
let diff = live.diff(&prior);
assert!(diff.added.is_empty());
assert_eq!(diff.removed.len(), 1);
assert_eq!(diff.changed.len(), 1);
}
fn schema_hook_command_keys() -> std::collections::BTreeSet<String> {
let schema: Value = serde_norway::from_str(include_str!(
"../docs/specifications/template-format.schema.yml"
))
.unwrap();
let mut keys = std::collections::BTreeSet::new();
let defs = &schema["$defs"];
for object in [
&defs["hook-command"],
&defs["hook-node"]["properties"]["hook"],
] {
for key in object["properties"].as_object().into_iter().flatten() {
keys.insert(key.0.clone());
}
}
keys
}
#[test]
fn new_file_referencing_field_forces_a_coverage_decision() {
let classified: std::collections::BTreeSet<String> = FILE_REFERENCING_KEYS
.iter()
.chain(NODE_ONLY_KEYS)
.map(|k| (*k).to_owned())
.collect();
let schema_keys = schema_hook_command_keys();
let unclassified: Vec<_> = schema_keys.difference(&classified).collect();
assert!(
unclassified.is_empty(),
"hook command keys need a coverage decision: {unclassified:?}"
);
let extra: Vec<_> = classified.difference(&schema_keys).collect();
assert!(
extra.is_empty(),
"classified keys absent from schema: {extra:?}"
);
}
#[test]
fn every_hook_key_is_classified_by_executable_reference() {
const EXECUTABLE_REFERENCE: &[&str] = &["run", "script"];
const NO_EXECUTABLE_REFERENCE: &[&str] = &[
"args",
"cwd",
"when",
"each",
"id",
"capture",
"allow-failure",
"parse",
"status-id",
];
let classified: std::collections::BTreeSet<String> = EXECUTABLE_REFERENCE
.iter()
.chain(NO_EXECUTABLE_REFERENCE)
.map(|k| (*k).to_owned())
.collect();
let schema_keys = schema_hook_command_keys();
let unclassified: Vec<_> = schema_keys.difference(&classified).collect();
assert!(
unclassified.is_empty(),
"hook keys need an executable-reference decision (1069 coverage): {unclassified:?}"
);
let extra: Vec<_> = classified.difference(&schema_keys).collect();
assert!(
extra.is_empty(),
"classified keys absent from schema: {extra:?}"
);
}
}