1use chrono::{DateTime, Utc};
2use serde::{Deserialize, Serialize};
3use std::path::Path;
4
5use crate::core::handoff_ledger::HandoffLedgerV1;
6
7const MAX_BUNDLE_BYTES: usize = 350_000;
8const MAX_PROOF_FILES: usize = 50;
9const MAX_ARTIFACT_ITEMS: usize = 80;
10const MAX_LEDGER_SNAPSHOT_CHARS: usize = 80_000;
11const MAX_CURATED_REF_CHARS: usize = 20_000;
12const MAX_DECISION_CHARS: usize = 2_000;
13const MAX_FINDING_CHARS: usize = 2_000;
14const MAX_NEXT_STEP_CHARS: usize = 1_000;
15const MAX_TASK_CHARS: usize = 4_000;
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum BundlePrivacyV1 {
19 Redacted,
20 Full,
21}
22
23impl BundlePrivacyV1 {
24 pub fn parse(s: Option<&str>) -> Self {
25 match s.unwrap_or("redacted").trim().to_lowercase().as_str() {
26 "full" => Self::Full,
27 _ => Self::Redacted,
28 }
29 }
30
31 pub fn as_str(&self) -> &'static str {
32 match self {
33 Self::Redacted => "redacted",
34 Self::Full => "full",
35 }
36 }
37}
38
39#[derive(Debug, Clone, Serialize, Deserialize)]
40pub struct HandoffTransferBundleV1 {
41 pub schema_version: u32,
42 pub exported_at: DateTime<Utc>,
43 pub privacy: String,
44 pub project: ProjectIdentityV1,
45 pub ledger: HandoffLedgerV1,
46 pub artifacts: ArtifactsExcerptV1,
47 #[serde(default, skip_serializing_if = "Option::is_none")]
48 pub signature: Option<String>,
49 #[serde(default, skip_serializing_if = "Option::is_none")]
50 pub signer_public_key: Option<String>,
51 #[serde(default, skip_serializing_if = "Option::is_none")]
52 pub signer_agent_id: Option<String>,
53}
54
55#[derive(Debug, Clone, Serialize, Deserialize)]
56pub struct ProjectIdentityV1 {
57 pub project_root_hash: Option<String>,
58 pub project_identity_hash: Option<String>,
59}
60
61#[derive(Debug, Clone, Serialize, Deserialize, Default)]
62pub struct ArtifactsExcerptV1 {
63 pub resolved: Vec<crate::core::artifacts::ResolvedArtifact>,
64 pub proof_files: Vec<ProofFileV1>,
65 pub warnings: Vec<String>,
66}
67
68#[derive(Debug, Clone, Serialize, Deserialize)]
69pub struct ProofFileV1 {
70 pub name: String,
71 pub md5: String,
72 pub bytes: u64,
73}
74
75pub fn build_bundle_v1(
76 mut ledger: HandoffLedgerV1,
77 project_root: Option<&str>,
78 privacy: BundlePrivacyV1,
79) -> HandoffTransferBundleV1 {
80 let role_name = crate::core::roles::active_role_name();
81 let effective_privacy = match privacy {
82 BundlePrivacyV1::Full
83 if role_name == "admin"
84 && !crate::core::redaction::redaction_enabled_for_active_role() =>
85 {
86 BundlePrivacyV1::Full
87 }
88 _ => BundlePrivacyV1::Redacted,
89 };
90
91 let (project_root_hash, project_identity_hash) = project_root.map_or((None, None), |root| {
92 let root_hash = crate::core::project_hash::hash_project_root(root);
93 let identity = crate::core::project_hash::project_identity(root);
94 let identity_hash = identity.as_deref().map(crate::core::hasher::hash_str);
95 (Some(root_hash), identity_hash)
96 });
97
98 cap_ledger_in_place(&mut ledger);
99
100 match effective_privacy {
101 BundlePrivacyV1::Full => {}
102 BundlePrivacyV1::Redacted => {
103 redact_ledger_in_place(&mut ledger);
104 }
105 }
106
107 ledger.content_md5 = crate::core::handoff_ledger::compute_content_md5_for_ledger(&ledger);
109
110 let artifacts = project_root
111 .map(Path::new)
112 .map(build_artifacts_excerpt_v1)
113 .unwrap_or_default();
114
115 let mut bundle = HandoffTransferBundleV1 {
116 schema_version: crate::core::contracts::HANDOFF_TRANSFER_BUNDLE_V1_SCHEMA_VERSION,
117 exported_at: Utc::now(),
118 privacy: effective_privacy.as_str().to_string(),
119 project: ProjectIdentityV1 {
120 project_root_hash,
121 project_identity_hash,
122 },
123 ledger,
124 artifacts,
125 signature: None,
126 signer_public_key: None,
127 signer_agent_id: None,
128 };
129
130 let agent_id = role_name;
131 sign_bundle(&mut bundle, &agent_id).ok();
132
133 bundle
134}
135
136pub fn sign_bundle(bundle: &mut HandoffTransferBundleV1, agent_id: &str) -> Result<(), String> {
137 bundle.signature = None;
138 bundle.signer_public_key = None;
139 bundle.signer_agent_id = None;
140
141 let canonical =
142 serde_json::to_string(bundle).map_err(|e| format!("serialize for signing: {e}"))?;
143
144 let sig_bytes = crate::core::agent_identity::sign_bytes(agent_id, canonical.as_bytes())?;
145 let pub_key = crate::core::agent_identity::get_public_key(agent_id)?;
146
147 bundle.signature = Some(crate::core::agent_identity::hex_encode(&sig_bytes));
148 bundle.signer_public_key = Some(crate::core::agent_identity::hex_encode(&pub_key.to_bytes()));
149 bundle.signer_agent_id = Some(agent_id.to_string());
150 Ok(())
151}
152
153pub fn verify_bundle_signature(bundle: &HandoffTransferBundleV1) -> Result<String, String> {
154 let sig_hex = bundle
155 .signature
156 .as_deref()
157 .ok_or_else(|| "bundle has no signature".to_string())?;
158 let pk_hex = bundle
159 .signer_public_key
160 .as_deref()
161 .ok_or_else(|| "bundle has no signer_public_key".to_string())?;
162 let agent_id = bundle
163 .signer_agent_id
164 .as_deref()
165 .ok_or_else(|| "bundle has no signer_agent_id".to_string())?;
166
167 let sig_bytes = crate::core::agent_identity::hex_decode(sig_hex)?;
168 let pk_bytes = crate::core::agent_identity::hex_decode(pk_hex)?;
169
170 let mut verify_bundle = bundle.clone();
171 verify_bundle.signature = None;
172 verify_bundle.signer_public_key = None;
173 verify_bundle.signer_agent_id = None;
174
175 let canonical =
176 serde_json::to_string(&verify_bundle).map_err(|e| format!("serialize for verify: {e}"))?;
177
178 if crate::core::agent_identity::verify_signature(&pk_bytes, canonical.as_bytes(), &sig_bytes) {
179 Ok(agent_id.to_string())
180 } else {
181 Err("signature verification failed".to_string())
182 }
183}
184
185pub fn serialize_bundle_v1_pretty(bundle: &HandoffTransferBundleV1) -> Result<String, String> {
186 let json = serde_json::to_string_pretty(bundle).map_err(|e| e.to_string())?;
187 if json.len() > MAX_BUNDLE_BYTES {
188 return Err(format!(
189 "ERROR: bundle too large ({} bytes > max {}). Use privacy=redacted and/or reduce curated refs.",
190 json.len(),
191 MAX_BUNDLE_BYTES
192 ));
193 }
194 Ok(json)
195}
196
197pub fn parse_bundle_v1(json: &str) -> Result<HandoffTransferBundleV1, String> {
198 let b: HandoffTransferBundleV1 = serde_json::from_str(json).map_err(|e| e.to_string())?;
199 if b.schema_version != crate::core::contracts::HANDOFF_TRANSFER_BUNDLE_V1_SCHEMA_VERSION {
200 return Err(format!(
201 "ERROR: unsupported schema_version {} (expected {})",
202 b.schema_version,
203 crate::core::contracts::HANDOFF_TRANSFER_BUNDLE_V1_SCHEMA_VERSION
204 ));
205 }
206 Ok(b)
207}
208
209pub fn write_bundle_v1(path: &Path, json: &str) -> Result<(), String> {
210 let parent = path
211 .parent()
212 .ok_or_else(|| "ERROR: invalid path".to_string())?;
213 if !parent.exists() {
214 std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
215 }
216 let tmp = parent.join(format!(
217 ".{}.tmp",
218 path.file_name()
219 .and_then(|s| s.to_str())
220 .unwrap_or("bundle")
221 ));
222 std::fs::write(&tmp, json).map_err(|e| e.to_string())?;
223 std::fs::rename(&tmp, path).map_err(|e| e.to_string())?;
224 Ok(())
225}
226
227pub fn read_bundle_v1(path: &Path) -> Result<HandoffTransferBundleV1, String> {
228 let json = std::fs::read_to_string(path).map_err(|e| e.to_string())?;
229 if json.len() > MAX_BUNDLE_BYTES {
230 return Err(format!(
231 "ERROR: bundle file too large ({} bytes > max {})",
232 json.len(),
233 MAX_BUNDLE_BYTES
234 ));
235 }
236 parse_bundle_v1(&json)
237}
238
239pub fn project_identity_warning(
240 bundle: &HandoffTransferBundleV1,
241 project_root: &str,
242) -> Option<String> {
243 let current_root_hash = crate::core::project_hash::hash_project_root(project_root);
244 let current_identity_hash = crate::core::project_hash::project_identity(project_root)
245 .as_deref()
246 .map(crate::core::hasher::hash_str);
247
248 if let Some(ref exported) = bundle.project.project_root_hash {
249 if exported != ¤t_root_hash {
250 return Some(
251 "WARNING: project_root_hash mismatch (importing into different project root)."
252 .to_string(),
253 );
254 }
255 }
256
257 if let (Some(exported), Some(current)) = (
258 bundle.project.project_identity_hash.as_ref(),
259 current_identity_hash.as_ref(),
260 ) {
261 if exported != current {
262 return Some(
263 "WARNING: project_identity_hash mismatch (importing into different project identity)."
264 .to_string(),
265 );
266 }
267 }
268
269 None
270}
271
272fn build_artifacts_excerpt_v1(project_root: &Path) -> ArtifactsExcerptV1 {
273 let mut out = ArtifactsExcerptV1::default();
274
275 let resolved = crate::core::artifacts::load_resolved(project_root);
276 out.warnings.extend(resolved.warnings);
277 out.resolved = resolved
278 .artifacts
279 .into_iter()
280 .take(MAX_ARTIFACT_ITEMS)
281 .collect();
282
283 let proofs_dir = match crate::core::pathutil::safe_project_data_dir(project_root) {
284 Ok(d) => d.join("proofs"),
285 Err(_) => return out,
286 };
287 if let Ok(rd) = std::fs::read_dir(&proofs_dir) {
288 let mut files = Vec::new();
289 for e in rd.flatten() {
290 let p = e.path();
291 if !p.is_file() {
292 continue;
293 }
294 let name = p
295 .file_name()
296 .map(|n| n.to_string_lossy().to_string())
297 .unwrap_or_default();
298 if name.is_empty() {
299 continue;
300 }
301 let bytes = p.metadata().map_or(0, |m| m.len());
302 let md5 = match std::fs::read(&p) {
303 Ok(b) => crate::core::hasher::hash_hex(&b),
304 Err(e) => {
305 out.warnings
306 .push(format!("proof read failed: {} ({e})", p.display()));
307 continue;
308 }
309 };
310 files.push(ProofFileV1 { name, md5, bytes });
311 }
312 files.sort_by(|a, b| a.name.cmp(&b.name));
313 out.proof_files = files.into_iter().take(MAX_PROOF_FILES).collect();
314 }
315
316 out
317}
318
319fn cap_ledger_in_place(ledger: &mut HandoffLedgerV1) {
320 if ledger.session_snapshot.len() > MAX_LEDGER_SNAPSHOT_CHARS {
321 ledger.session_snapshot =
322 truncate_chars(&ledger.session_snapshot, MAX_LEDGER_SNAPSHOT_CHARS);
323 }
324
325 if let Some(ref mut task) = ledger.session.task {
326 *task = truncate_chars(task, MAX_TASK_CHARS);
327 }
328
329 for d in &mut ledger.session.decisions {
330 *d = truncate_chars(d, MAX_DECISION_CHARS);
331 }
332 for f in &mut ledger.session.findings {
333 *f = truncate_chars(f, MAX_FINDING_CHARS);
334 }
335 for s in &mut ledger.session.next_steps {
336 *s = truncate_chars(s, MAX_NEXT_STEP_CHARS);
337 }
338
339 for r in &mut ledger.curated_refs {
340 if r.content.len() > MAX_CURATED_REF_CHARS {
341 r.content = truncate_chars(&r.content, MAX_CURATED_REF_CHARS);
342 }
343 }
344}
345
346fn redact_ledger_in_place(ledger: &mut HandoffLedgerV1) {
347 ledger.project_root = None;
348 ledger.session_snapshot.clear();
349
350 if let Some(ref mut task) = ledger.session.task {
351 *task = crate::core::redaction::redact_text(task);
352 }
353 for d in &mut ledger.session.decisions {
354 *d = crate::core::redaction::redact_text(d);
355 }
356 for f in &mut ledger.session.findings {
357 *f = crate::core::redaction::redact_text(f);
358 }
359 for s in &mut ledger.session.next_steps {
360 *s = crate::core::redaction::redact_text(s);
361 }
362
363 for fact in &mut ledger.knowledge.facts {
364 fact.value = crate::core::redaction::redact_text(&fact.value);
365 }
366
367 for r in &mut ledger.curated_refs {
368 r.content = crate::core::redaction::redact_text(&r.content);
369 }
370}
371
372fn truncate_chars(s: &str, max: usize) -> String {
373 if s.chars().count() <= max {
374 return s.to_string();
375 }
376 s.chars().take(max).collect::<String>()
377}
378
379#[cfg(test)]
380mod tests {
381 use super::*;
382
383 fn sample_ledger() -> HandoffLedgerV1 {
384 HandoffLedgerV1 {
385 schema_version: crate::core::contracts::HANDOFF_LEDGER_V1_SCHEMA_VERSION,
386 created_at: "20260503T000000Z".to_string(),
387 content_md5: "old".to_string(),
388 manifest_md5: "m".to_string(),
389 project_root: Some("/abs/project".to_string()),
390 agent_id: Some("a".to_string()),
391 client_name: Some("cursor".to_string()),
392 workflow: None,
393 session_snapshot: "snapshot".to_string(),
394 session: crate::core::handoff_ledger::SessionExcerpt {
395 id: "s".to_string(),
396 task: Some("task".to_string()),
397 decisions: vec!["d1".to_string()],
398 findings: vec!["f1".to_string()],
399 next_steps: vec!["n1".to_string()],
400 },
401 tool_calls: crate::core::handoff_ledger::ToolCallsSummary::default(),
402 evidence_keys: vec!["tool:ctx_read".to_string()],
403 knowledge: crate::core::handoff_ledger::KnowledgeExcerpt {
404 project_hash: None,
405 facts: vec![crate::core::handoff_ledger::KnowledgeFactMini {
406 category: "c".to_string(),
407 key: "k".to_string(),
408 value: "secret=abcdef0123456789abcdef0123456789".to_string(),
409 confidence: 0.9,
410 }],
411 },
412 curated_refs: vec![crate::core::handoff_ledger::CuratedRef {
413 path: "src/lib.rs".to_string(),
414 mode: "signatures".to_string(),
415 content_md5: "x".to_string(),
416 content: "fn a() {}".to_string(),
417 }],
418 active_overlays: Vec::new(),
419 }
420 }
421
422 #[test]
423 fn redacted_bundle_removes_sensitive_fields() {
424 let ledger = sample_ledger();
425 let b = build_bundle_v1(ledger, None, BundlePrivacyV1::Redacted);
426 assert_eq!(b.privacy, "redacted");
427 assert!(b.ledger.project_root.is_none());
428 assert!(b.ledger.session_snapshot.is_empty());
429 }
430
431 #[test]
432 fn serialize_parse_roundtrip() {
433 let ledger = sample_ledger();
434 let b = build_bundle_v1(ledger, None, BundlePrivacyV1::Redacted);
435 let json = serialize_bundle_v1_pretty(&b).expect("json");
436 assert!(json.len() < MAX_BUNDLE_BYTES);
437 let parsed = parse_bundle_v1(&json).expect("parse");
438 assert_eq!(parsed.schema_version, b.schema_version);
439 assert_eq!(parsed.privacy, "redacted");
440 }
441}