From 4c56cda5986776f0e51e7fcdbdd471537b77758b Mon Sep 17 00:00:00 2001 From: markmental Date: Wed, 7 Oct 2026 16:22:37 -0400 Subject: [PATCH] Adds ability to export game saves as .cbs codebreaker save files, also adds --version argument --- AGENTS.md | 7 +- README.md | 5 +- src/codebreaker/format.rs | 197 +++++++++++++++++++++++++++++++++++++- src/main.rs | 50 ++++++++-- src/memory_card/card.rs | 156 ++++++++++++++++++++++++++++-- 5 files changed, 395 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9748312..270b211 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ JAPS2ME (Just A PS2 Memory Card Editor) is a Rust CLI and library for managing P - `list ` — list saves as a Unicode table with game titles, file counts, payload sizes, and free space. - `delete ` — remove a save directory. - `add ` — import a Codebreaker or Datel MAX Drive save. +- `export ` — export a save as a Codebreaker file. The project is licensed under GPL-3.0-or-later. `mymcplusplus` is a technical reference for PS2 memory-card filesystem behavior and save formats; see its attribution in `README.md`. @@ -17,9 +18,9 @@ The project is licensed under GPL-3.0-or-later. `mymcplusplus` is a technical re - `src/memory_card/icon_sys.rs` — `icon.sys` title parsing with Shift-JIS decoding. - `src/lib.rs` — crate modules and public exports. - `src/save.rs` — shared imported-save model and format detection. -- `src/codebreaker/format.rs` — Codebreaker RC4/zlib parser. +- `src/codebreaker/format.rs` — Codebreaker RC4/zlib parser and encoder. - `src/max_drive.rs` — MAX Drive header/CRC parser, LZARI decoder, and file-record parser. -- `src/memory_card/card.rs` — memory-card access, directory operations, allocation, FAT chains, and save insertion/removal. +- `src/memory_card/card.rs` — memory-card access, directory operations, allocation, FAT chains, save insertion/removal, summaries, and save export. - `src/memory_card/superblock.rs` — superblock parsing and card geometry. - `src/memory_card/directory.rs` — 512-byte directory-entry encoding and mode bits. - `src/memory_card/fat.rs` — FAT marker constants and helpers. @@ -61,7 +62,7 @@ After changing code, rebuild the executable being invoked. For example, `cargo b ## Save-format details -- Codebreaker files begin with `CFU\0`. Their body is RC4-decrypted using the fixed Codebreaker state, then zlib-decompressed. Header and per-file lengths must be bounds-checked. +- Codebreaker files begin with `CFU\0`. Their body is RC4-decrypted using the fixed Codebreaker state, then zlib-decompressed. Header and per-file lengths must be bounds-checked. The encoder mirrors this layout: 64-byte file records plus raw data, zlib-compressed and RC4-encrypted, with `stored_len` set to the total file length and overlong headers grown past the 124-byte minimum for long titles. - MAX Drive files begin with `Ps2PowerSave` and have a 92-byte header. The CRC is computed over the header with its CRC field zeroed followed by the compressed payload. The LZARI output contains `dirlen` records: little-endian data length, 32-byte name, file bytes, and the format's alignment padding. - The supplied `PES3allunlocked.max` fixture should parse as directory `BESLES-51912PES3OPT`, with `icon.sys` (964 bytes), `icon_view` (33,400 bytes), and `BESLES-51912PES3OPT` (773,120 bytes). Tests use CRCs of the decoded files to catch LZARI regressions. diff --git a/README.md b/README.md index 288a0b6..527c401 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ - List saves as a Unicode table with directory names, game titles, file counts, payload sizes, and free-space footer. - Delete a save directory. +- Export a save directory as a CodeBreaker `.cbs` file. - Import a CodeBreaker `.cbs` save, including its files and metadata. - Import a Datel MAX Drive `.max` save, including LZARI decompression. - Read and update standard PS2 memory-card images with ECC support. @@ -28,6 +29,7 @@ The executable is created at `target/release/japs2me`. japs2me list japs2me delete japs2me add +japs2me export ``` Examples: @@ -37,9 +39,10 @@ target/release/japs2me list Mcd001.ps2 target/release/japs2me add Mcd001.ps2 my-save.cbs target/release/japs2me add Mcd001.ps2 PES3allunlocked.max target/release/japs2me delete Mcd001.ps2 BASLUS-20787SD5 +target/release/japs2me export Mcd001.ps2 BESLES-51912PES3OPT pes3.cbs ``` -`list` displays saves as a Unicode table with the save directory, game title from `icon.sys` (falling back to the directory name), regular-file count, and total payload size. A footer shows free allocatable space. Game titles are decoded from the Shift-JIS `icon.sys` title field; missing or invalid metadata falls back to the directory name. Listed save sizes are summed file payload bytes, not on-card allocated cluster sizes. Free space is unallocated FAT clusters multiplied by the cluster size. `add` detects CodeBreaker and MAX Drive saves by their file signatures, uses the directory name stored in the save, and reports an error if that save already exists on the card. +`list` displays saves as a Unicode table with the save directory, game title from `icon.sys` (falling back to the directory name), regular-file count, and total payload size. A footer shows free allocatable space. Game titles are decoded from the Shift-JIS `icon.sys` title field; missing or invalid metadata falls back to the directory name. Listed save sizes are summed file payload bytes, not on-card allocated cluster sizes. Free space is unallocated FAT clusters multiplied by the cluster size. `add` detects CodeBreaker and MAX Drive saves by their file signatures, uses the directory name stored in the save, and reports an error if that save already exists on the card. `export` writes the save directory's files, modes, and timestamps to a CodeBreaker `.cbs` file, using the `icon.sys` title when available, and refuses to overwrite an existing output file. ## Tests diff --git a/src/codebreaker/format.rs b/src/codebreaker/format.rs index fc23975..0aaf3be 100644 --- a/src/codebreaker/format.rs +++ b/src/codebreaker/format.rs @@ -20,11 +20,15 @@ const RC4S: [u8; 256] = [ use crate::save::{SaveFile, SaveImport}; use anyhow::{anyhow, bail, ensure, Context, Result}; use flate2::read::ZlibDecoder; -use std::io::{Cursor, Read}; +use flate2::write::ZlibEncoder; +use flate2::Compression; +use std::io::{Cursor, Read, Write}; const MAGIC: &[u8; 4] = b"CFU\0"; const HEADER_MIN: usize = 124; const MAX_DECOMPRESSED_BODY: usize = 64 * 1024 * 1024; +const DIRNAME_LEN: usize = 32; +const FILENAME_LEN: usize = 32; pub type CodebreakerFileEntry = SaveFile; pub type CodebreakerSave = SaveImport; @@ -149,9 +153,111 @@ pub fn parse(data: &[u8]) -> Result { }) } +fn validate_entry_name(name: &str, what: &str) -> Result<()> { + ensure!(!name.is_empty(), "Codebreaker {what} name cannot be empty"); + ensure!( + name.len() <= DIRNAME_LEN, + "Codebreaker {what} name must fit in 32 bytes: {name}" + ); + ensure!( + !name.bytes().any(|byte| byte == 0), + "Codebreaker {what} name cannot contain NUL: {name}" + ); + Ok(()) +} + +/// Encode a save as a Codebreaker `.cbs` file. +/// +/// Mirrors [`parse`]: a `CFU\0` header with lengths, directory metadata, +/// and title, followed by the RC4-encrypted zlib body of 64-byte file +/// records plus raw file data. +pub fn encode(save: &SaveImport) -> Result> { + validate_entry_name(&save.directory, "directory")?; + ensure!( + !save.title.bytes().any(|byte| byte == 0), + "Codebreaker title cannot contain NUL" + ); + for file in &save.files { + validate_entry_name(&file.name, "file")?; + ensure!( + file.mode & 0x8030 == 0x8010, + "Codebreaker entry is not a regular file: {}", + file.name + ); + u32::try_from(file.data.len()).context("file is too large for Codebreaker save")?; + } + + let mut body = Vec::new(); + for file in &save.files { + body.extend_from_slice(&file.created); + body.extend_from_slice(&file.modified); + body.extend_from_slice( + &u32::try_from(file.data.len()) + .context("file is too large for Codebreaker save")? + .to_le_bytes(), + ); + body.extend_from_slice(&file.mode.to_le_bytes()); + body.extend_from_slice(&[0u8; 2]); // reserved + body.extend_from_slice(&[0u8; 8]); // reserved + let mut name_field = [0u8; FILENAME_LEN]; + name_field[..file.name.len()].copy_from_slice(file.name.as_bytes()); + body.extend_from_slice(&name_field); + body.extend_from_slice(&file.data); + } + ensure!( + body.len() <= MAX_DECOMPRESSED_BODY, + "Codebreaker body exceeds size limit" + ); + + let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default()); + encoder + .write_all(&body) + .context("compressing Codebreaker save body")?; + let encrypted = crypt( + encoder + .finish() + .context("compressing Codebreaker save body")?, + ); + + let title_bytes = save.title.as_bytes(); + let header_len = HEADER_MIN.max( + 92usize + .checked_add(title_bytes.len()) + .and_then(|len| len.checked_add(1)) + .ok_or_else(|| anyhow!("Codebreaker title is too long"))?, + ); + let stored_len = header_len + .checked_add(encrypted.len()) + .ok_or_else(|| anyhow!("Codebreaker save is too large"))?; + let header_len_u32 = u32::try_from(header_len).context("Codebreaker header is too large")?; + let stored_len_u32 = u32::try_from(stored_len).context("Codebreaker save is too large")?; + let body_len_u32 = u32::try_from(body.len()).context("Codebreaker body is too large")?; + + let directory_mode = if save.directory_mode & 0x8030 == 0x8020 { + u32::from(save.directory_mode) + } else { + 0x8427 // RWX | directory | 0400 | exists + }; + + let mut header = vec![0u8; header_len]; + header[0..4].copy_from_slice(MAGIC); + header[8..12].copy_from_slice(&header_len_u32.to_le_bytes()); + header[12..16].copy_from_slice(&body_len_u32.to_le_bytes()); + header[16..20].copy_from_slice(&stored_len_u32.to_le_bytes()); + header[20..20 + save.directory.len()].copy_from_slice(save.directory.as_bytes()); + header[52..60].copy_from_slice(&save.created); + header[60..68].copy_from_slice(&save.modified); + header[76..80].copy_from_slice(&directory_mode.to_le_bytes()); + header[92..92 + title_bytes.len()].copy_from_slice(title_bytes); + + header.extend_from_slice(&encrypted); + Ok(header) +} + #[cfg(test)] mod tests { - use super::{crypt, parse}; + use super::{crypt, encode, parse}; + use crate::save::{SaveFile, SaveImport}; use flate2::write::ZlibEncoder; use flate2::Compression; use std::io::Write; @@ -203,4 +309,91 @@ mod tests { cbs.truncate(100); assert!(parse(&cbs).is_err()); } + + fn sample_save() -> SaveImport { + SaveImport { + directory: "BASLUS-TEST".to_owned(), + directory_mode: 0x8420, + created: [0, 1, 2, 3, 4, 5, 0xe8, 0x07], + modified: [0, 6, 7, 8, 9, 5, 0xe8, 0x07], + title: "Test Save".to_owned(), + files: vec![ + SaveFile { + name: "DATA.BIN".to_owned(), + data: vec![0xaa, 0xbb, 0xcc], + mode: 0x8017, + created: [0, 1, 2, 3, 4, 5, 0xe8, 0x07], + modified: [0, 6, 7, 8, 9, 5, 0xe8, 0x07], + }, + SaveFile { + name: "EMPTY".to_owned(), + data: vec![], + mode: 0x8417, + created: [0; 8], + modified: [0; 8], + }, + ], + } + } + + fn assert_same_save(expected: &SaveImport, actual: &SaveImport) { + assert_eq!(actual.directory, expected.directory); + assert_eq!(actual.directory_mode, expected.directory_mode); + assert_eq!(actual.created, expected.created); + assert_eq!(actual.modified, expected.modified); + assert_eq!(actual.title, expected.title); + assert_eq!(actual.files.len(), expected.files.len()); + for (actual, expected) in actual.files.iter().zip(expected.files.iter()) { + assert_eq!(actual.name, expected.name); + assert_eq!(actual.data, expected.data); + assert_eq!(actual.mode, expected.mode); + assert_eq!(actual.created, expected.created); + assert_eq!(actual.modified, expected.modified); + } + } + + #[test] + fn encode_round_trips_through_parse() { + let save = sample_save(); + let encoded = encode(&save).unwrap(); + let parsed = parse(&encoded).unwrap(); + assert_same_save(&save, &parsed); + } + + #[test] + fn parsed_save_reencodes_to_equivalent_save() { + let parsed = parse(&sample_cbs()).unwrap(); + let reencoded = encode(&parsed).unwrap(); + let reparsed = parse(&reencoded).unwrap(); + assert_same_save(&parsed, &reparsed); + } + + #[test] + fn encode_grows_header_for_long_titles() { + let mut save = sample_save(); + save.title = "A".repeat(200); + let encoded = encode(&save).unwrap(); + let header_len = u32::from_le_bytes(encoded[8..12].try_into().unwrap()) as usize; + assert_eq!(header_len, 92 + 200 + 1); + assert_eq!(parse(&encoded).unwrap().title, save.title); + } + + #[test] + fn encode_rejects_invalid_names_and_modes() { + let mut save = sample_save(); + save.directory.clear(); + assert!(encode(&save).is_err()); + + let mut save = sample_save(); + save.directory = "X".repeat(33); + assert!(encode(&save).is_err()); + + let mut save = sample_save(); + save.files[0].name = "not-a-file\0name".to_owned(); + assert!(encode(&save).is_err()); + + let mut save = sample_save(); + save.files[0].mode = 0x8427; // directory mode, not a regular file + assert!(encode(&save).is_err()); + } } diff --git a/src/main.rs b/src/main.rs index dfcc163..1e2f37f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,11 +1,13 @@ -use anyhow::Result; +use anyhow::{Context, Result}; use clap::{Parser, Subcommand}; +use japs2me::codebreaker::format::encode as encode_codebreaker; use japs2me::memory_card::transaction::add_directory_atomically; use japs2me::{format_save_table, ImportFile, MemoryCard, SaveImport}; -use std::path::Path; +use std::io::Write; +use std::path::{Path, PathBuf}; #[derive(Parser)] -#[command(name = "japs2me", about = "Just A PS2 Memory Card Editor")] +#[command(name = "japs2me", version, about = "Just A PS2 Memory Card Editor")] struct Cli { #[command(subcommand)] command: Command, @@ -13,9 +15,22 @@ struct Cli { #[derive(Subcommand)] enum Command { - List { card: String }, - Delete { card: String, name: String }, - Add { card: String, save: String }, + List { + card: String, + }, + Delete { + card: String, + name: String, + }, + Add { + card: String, + save: String, + }, + Export { + card: String, + name: String, + output: String, + }, } fn main() -> Result<()> { @@ -53,6 +68,29 @@ fn main() -> Result<()> { &files, )?; } + Command::Export { card, name, output } => { + let mut card = MemoryCard::open(card, false)?; + let save = card.export_save(&name)?; + let data = encode_codebreaker(&save)?; + write_output_atomically(&output, &data)?; + } } Ok(()) } + +fn write_output_atomically(output: &str, data: &[u8]) -> Result<()> { + let output = PathBuf::from(output); + if output.symlink_metadata().is_ok() { + anyhow::bail!("output already exists: {}", output.display()); + } + let parent = output + .parent() + .filter(|parent| !parent.as_os_str().is_empty()); + let mut temp = tempfile::NamedTempFile::new_in(parent.unwrap_or_else(|| Path::new("."))) + .context("creating temporary export file")?; + temp.write_all(data) + .context("writing temporary export file")?; + temp.persist(&output) + .with_context(|| format!("writing {}", output.display()))?; + Ok(()) +} diff --git a/src/memory_card/card.rs b/src/memory_card/card.rs index b33ad97..b9c3ced 100644 --- a/src/memory_card/card.rs +++ b/src/memory_card/card.rs @@ -3,6 +3,7 @@ use super::ecc::page_spare; use super::fat::{ALLOCATED, CHAIN_END, CHAIN_END_UNALLOC}; use super::icon_sys::parse_title; use super::superblock::Superblock; +use crate::save::{SaveFile, SaveImport}; use anyhow::{anyhow, bail, ensure, Context, Result}; use std::collections::HashSet; use std::fs::{File, OpenOptions}; @@ -396,14 +397,7 @@ impl MemoryCard { .checked_add(u64::from(file.length)) .ok_or_else(|| anyhow!("save size overflow"))?; } - let game_title = files - .iter() - .find(|file| file.name.eq_ignore_ascii_case("icon.sys")) - .filter(|icon| icon.length == 964) - .and_then(|icon| self.read_file(icon).ok()) - .as_deref() - .and_then(parse_title) - .unwrap_or_else(|| save.name.clone()); + let game_title = self.icon_title(&children, &save.name); summaries.push(SaveSummary { directory: save.name.clone(), game_title, @@ -414,6 +408,65 @@ impl MemoryCard { Ok(summaries) } + fn icon_title(&mut self, children: &[DirEntry], fallback: &str) -> String { + children + .iter() + .filter(|entry| entry.is_file()) + .find(|file| file.name.eq_ignore_ascii_case("icon.sys")) + .filter(|icon| icon.length == 964) + .and_then(|icon| self.read_file(icon).ok()) + .as_deref() + .and_then(parse_title) + .unwrap_or_else(|| fallback.to_owned()) + } + + /// Read a save directory into the shared save model for exporting. + pub fn export_save(&mut self, name: &str) -> Result { + let save = self + .entries()? + .into_iter() + .find(|entry| entry.name == name) + .ok_or_else(|| anyhow!("save not found: {name}"))?; + ensure!(save.is_dir(), "not a save directory: {name}"); + let children = self.directory_entries(save.first_cluster, save.length)?; + let mut files = Vec::new(); + for child in children.iter().skip(2) { + if child.mode & DF_EXISTS == 0 { + continue; + } + if child.is_dir() { + bail!("refusing to export nested directory {}", child.name); + } + ensure!( + child.is_file(), + "unsupported directory entry: {}", + child.name + ); + let data = self.read_file(child)?; + ensure!( + data.len() == child.length as usize, + "truncated file data: {}", + child.name + ); + files.push(SaveFile { + name: child.name.clone(), + data, + mode: child.mode, + created: child.created, + modified: child.modified, + }); + } + let title = self.icon_title(&children, &save.name); + Ok(SaveImport { + directory: save.name.clone(), + directory_mode: save.mode, + created: save.created, + modified: save.modified, + title, + files, + }) + } + /// Free allocatable space in bytes. pub fn available_bytes(&mut self) -> Result { let mut free_clusters = 0u64; @@ -917,6 +970,93 @@ mod tests { Ok(()) } + #[test] + fn export_save_round_trips_card_data() -> Result<()> { + let temp = tempdir()?; + let path = temp.path().join("card.ps2"); + create_test_card(&path, false); + let icon = sample_icon_sys(b"Test Game", b"Save 1", 16); + let payload = vec![1, 2, 3, 4, 5]; + let files = vec![ + sample_file("icon.sys", icon), + sample_file("DATA.BIN", payload.clone()), + ]; + MemoryCard::open(&path, true)?.add_directory( + "BASLUS-TEST", + 0x8420, + [0; 8], + [0; 8], + &files, + )?; + + let mut card = MemoryCard::open(&path, false)?; + let save = card.export_save("BASLUS-TEST")?; + assert_eq!(save.directory, "BASLUS-TEST"); + assert_eq!(save.title, "Test Game Save 1"); + assert_eq!(save.files.len(), 2); + let data = save + .files + .iter() + .find(|file| file.name == "DATA.BIN") + .unwrap(); + assert_eq!(data.data, payload); + + let encoded = crate::codebreaker::format::encode(&save)?; + let parsed = crate::save::SaveImport::parse(&encoded)?; + assert_eq!(parsed.directory, "BASLUS-TEST"); + assert_eq!(parsed.title, "Test Game Save 1"); + assert_eq!(parsed.files.len(), 2); + assert_eq!( + parsed + .files + .iter() + .find(|file| file.name == "DATA.BIN") + .unwrap() + .data, + payload + ); + Ok(()) + } + + #[test] + fn export_save_rejects_missing_and_nested_saves() -> Result<()> { + let temp = tempdir()?; + let path = temp.path().join("card.ps2"); + create_test_card(&path, false); + let files = vec![sample_file("DATA", vec![1, 2, 3])]; + MemoryCard::open(&path, true)?.add_directory( + "BASLUS-TEST", + 0x8420, + [0; 8], + [0; 8], + &files, + )?; + + let mut card = MemoryCard::open(&path, false)?; + assert!(card.export_save("NO-SUCH-SAVE").is_err()); + drop(card); + + let mut card = MemoryCard::open(&path, true)?; + let save = card + .entries()? + .into_iter() + .find(|entry| entry.name == "BASLUS-TEST") + .unwrap(); + let children = card.directory_entries(save.first_cluster, save.length)?; + let index = children + .iter() + .position(|entry| entry.name == "DATA") + .unwrap(); + let mut nested = children[index].clone(); + nested.mode = DF_RWX | DF_DIR | DF_EXISTS; + card.write_directory_entry(save.first_cluster, index, &nested)?; + drop(card); + + let mut card = MemoryCard::open(&path, false)?; + assert!(card.export_save("BASLUS-TEST").is_err()); + Ok(()) + } + #[test] fn available_bytes_shrink_after_import() -> Result<()> { let temp = tempdir()?;