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 = project_root.join(".lean-ctx").join("proofs");
284 if let Ok(rd) = std::fs::read_dir(&proofs_dir) {
285 let mut files = Vec::new();
286 for e in rd.flatten() {
287 let p = e.path();
288 if !p.is_file() {
289 continue;
290 }
291 let name = p
292 .file_name()
293 .map(|n| n.to_string_lossy().to_string())
294 .unwrap_or_default();
295 if name.is_empty() {
296 continue;
297 }
298 let bytes = p.metadata().map_or(0, |m| m.len());
299 let md5 = match std::fs::read(&p) {
300 Ok(b) => crate::core::hasher::hash_hex(&b),
301 Err(e) => {
302 out.warnings
303 .push(format!("proof read failed: {} ({e})", p.display()));
304 continue;
305 }
306 };
307 files.push(ProofFileV1 { name, md5, bytes });
308 }
309 files.sort_by(|a, b| a.name.cmp(&b.name));
310 out.proof_files = files.into_iter().take(MAX_PROOF_FILES).collect();
311 }
312
313 out
314}
315
316fn cap_ledger_in_place(ledger: &mut HandoffLedgerV1) {
317 if ledger.session_snapshot.len() > MAX_LEDGER_SNAPSHOT_CHARS {
318 ledger.session_snapshot =
319 truncate_chars(&ledger.session_snapshot, MAX_LEDGER_SNAPSHOT_CHARS);
320 }
321
322 if let Some(ref mut task) = ledger.session.task {
323 *task = truncate_chars(task, MAX_TASK_CHARS);
324 }
325
326 for d in &mut ledger.session.decisions {
327 *d = truncate_chars(d, MAX_DECISION_CHARS);
328 }
329 for f in &mut ledger.session.findings {
330 *f = truncate_chars(f, MAX_FINDING_CHARS);
331 }
332 for s in &mut ledger.session.next_steps {
333 *s = truncate_chars(s, MAX_NEXT_STEP_CHARS);
334 }
335
336 for r in &mut ledger.curated_refs {
337 if r.content.len() > MAX_CURATED_REF_CHARS {
338 r.content = truncate_chars(&r.content, MAX_CURATED_REF_CHARS);
339 }
340 }
341}
342
343fn redact_ledger_in_place(ledger: &mut HandoffLedgerV1) {
344 ledger.project_root = None;
345 ledger.session_snapshot.clear();
346
347 if let Some(ref mut task) = ledger.session.task {
348 *task = crate::core::redaction::redact_text(task);
349 }
350 for d in &mut ledger.session.decisions {
351 *d = crate::core::redaction::redact_text(d);
352 }
353 for f in &mut ledger.session.findings {
354 *f = crate::core::redaction::redact_text(f);
355 }
356 for s in &mut ledger.session.next_steps {
357 *s = crate::core::redaction::redact_text(s);
358 }
359
360 for fact in &mut ledger.knowledge.facts {
361 fact.value = crate::core::redaction::redact_text(&fact.value);
362 }
363
364 for r in &mut ledger.curated_refs {
365 r.content = crate::core::redaction::redact_text(&r.content);
366 }
367}
368
369fn truncate_chars(s: &str, max: usize) -> String {
370 if s.chars().count() <= max {
371 return s.to_string();
372 }
373 s.chars().take(max).collect::<String>()
374}
375
376#[cfg(test)]
377mod tests {
378 use super::*;
379
380 fn sample_ledger() -> HandoffLedgerV1 {
381 HandoffLedgerV1 {
382 schema_version: crate::core::contracts::HANDOFF_LEDGER_V1_SCHEMA_VERSION,
383 created_at: "20260503T000000Z".to_string(),
384 content_md5: "old".to_string(),
385 manifest_md5: "m".to_string(),
386 project_root: Some("/abs/project".to_string()),
387 agent_id: Some("a".to_string()),
388 client_name: Some("cursor".to_string()),
389 workflow: None,
390 session_snapshot: "snapshot".to_string(),
391 session: crate::core::handoff_ledger::SessionExcerpt {
392 id: "s".to_string(),
393 task: Some("task".to_string()),
394 decisions: vec!["d1".to_string()],
395 findings: vec!["f1".to_string()],
396 next_steps: vec!["n1".to_string()],
397 },
398 tool_calls: crate::core::handoff_ledger::ToolCallsSummary::default(),
399 evidence_keys: vec!["tool:ctx_read".to_string()],
400 knowledge: crate::core::handoff_ledger::KnowledgeExcerpt {
401 project_hash: None,
402 facts: vec![crate::core::handoff_ledger::KnowledgeFactMini {
403 category: "c".to_string(),
404 key: "k".to_string(),
405 value: "secret=abcdef0123456789abcdef0123456789".to_string(),
406 confidence: 0.9,
407 }],
408 },
409 curated_refs: vec![crate::core::handoff_ledger::CuratedRef {
410 path: "src/lib.rs".to_string(),
411 mode: "signatures".to_string(),
412 content_md5: "x".to_string(),
413 content: "fn a() {}".to_string(),
414 }],
415 active_overlays: Vec::new(),
416 }
417 }
418
419 #[test]
420 fn redacted_bundle_removes_sensitive_fields() {
421 let ledger = sample_ledger();
422 let b = build_bundle_v1(ledger, None, BundlePrivacyV1::Redacted);
423 assert_eq!(b.privacy, "redacted");
424 assert!(b.ledger.project_root.is_none());
425 assert!(b.ledger.session_snapshot.is_empty());
426 }
427
428 #[test]
429 fn serialize_parse_roundtrip() {
430 let ledger = sample_ledger();
431 let b = build_bundle_v1(ledger, None, BundlePrivacyV1::Redacted);
432 let json = serialize_bundle_v1_pretty(&b).expect("json");
433 assert!(json.len() < MAX_BUNDLE_BYTES);
434 let parsed = parse_bundle_v1(&json).expect("parse");
435 assert_eq!(parsed.schema_version, b.schema_version);
436 assert_eq!(parsed.privacy, "redacted");
437 }
438}