Merge PR #7: restore IL2CPP 24.1 method indices

Product docs already live on crackproof-research; keep a minimal README
(usage, legal notice, license) so CI can still extract LEGAL-NOTICE.md.

AGENTS.md

@@ -6,7 +6,7 @@ Guidance for contributors working in this repository.
 
 Senbei is a static unpacker for protected PE files and Android AArch64 shared libraries. The workspace contains `senbei-cli`, `senbei-crypto`, `senbei-elf`, `senbei-engine`, `senbei-io`, `senbei-metadata`, and `senbei-pe`; `senbei-wasm` is a separate crate for the browser frontend.
 
-Read `docs/design.md` before changing architecture or pipeline boundaries.
+Read the [Senbei design notes](https://xn--ri8h.gitbook.io/crackproof-research/senbei) before changing architecture or pipeline boundaries.
 
 ## Commands
 
@@ -37,4 +37,4 @@ The format crates and PE engine remain free of filesystem I/O. Native Android ex
 
 ## Documentation
 
-Use one line for each normal Markdown paragraph. Keep code blocks, table rows, and list items structurally separate. Update `docs/usage.md` when CLI behavior changes.
+Use one line for each normal Markdown paragraph. Keep code blocks, table rows, and list items structurally separate. Product documentation lives at <https://xn--ri8h.gitbook.io/crackproof-research/senbei>; update that site (not this repository) when CLI behavior changes.

README.md

@@ -1,24 +1,10 @@
 # Senbei
 
-A static unpacker for Crackproof-protected 64-bit and 32-bit PE files and protected Android AArch64 shared libraries. Point it at a file, an app package, or a folder and it writes decrypted copies without launching the protected program.
+A static unpacker for CrackProof-protected Windows PE files and Android AArch64 shared libraries.
 
-Senbei reads protected input bytes and replays the unpacking algorithm statically. The command-line tool adds filesystem scanning, progress reporting, and logs; `senbei-wasm` provides the browser binding.
+> _"Crackproof"? It's senbei (煎餅 — rice cracker). Cracks itself._
 
-## Crates
-
-The workspace contains eight crates: `senbei-cli`, `senbei-crypto`, `senbei-io`, `senbei-metadata`, `senbei-pe`, `senbei-elf`, `senbei-engine`, and `senbei-wasm`.
-
-`senbei-pe` and `senbei-elf` contain validated format parsing, address mapping, and ELF dynamic-table helpers. Protection-specific code is in `senbei-engine/src/windows/` and `senbei-engine/src/android/`. Platform-specific crypto is grouped under `senbei-crypto/src/windows/` and `senbei-crypto/src/android/`; metadata code shared by both platforms stays at the `senbei-metadata` root, with seeded Android code under `src/android/`.
-
-## Supported Inputs
-
-- Protected Windows `.exe` and `.dll` files, including external `<name>.exe._` and `<name>.dll._` payloads.
-- `global-metadata.dat` files with supported method-token layouts.
-- Protected Android `.so` files and Android `.apk`, `.apks`, and `.xapk` packages.
-
-Windows scanning probes only `.exe`, `.dll`, and `global-metadata.dat`; companion payloads are consumed through their matching stub and are not counted as skipped files. Android scanning probes only `.so` and `global-metadata.dat`. Android packages are inspected from their ZIP manifests and only matching `.so` and metadata entries are extracted.
-
-## Quick Start
+## Usage
 
 ```cmd
 cargo build --release
@@ -27,30 +13,20 @@ senbei game.apk
 senbei "C:\Games\MyGame"
 ```
 
-Outputs are written below an `unpack` directory unless `--out` is supplied. Every restored PE or ELF image passes a structural validation step before it is reported as successful.
+Outputs are written below an `unpack` directory unless `--out` is supplied.
 
-## Tests
+Full documentation: <https://xn--ri8h.gitbook.io/crackproof-research/senbei>
 
-```cmd
-cargo test --release --workspace
-cargo clippy --workspace --all-targets -- -D warnings
-cargo fmt --all -- --check
-```
+## Legal notice and intended use
 
-The local `test/` corpus can be passed to the CLI for real sample verification. The tracked `samples/` corpus is optional and remains user-managed.
+**Read this before using Senbei.**
 
-## Web Build
-
-```cmd
-cd senbei-wasm
-wasm-pack build --target web --release --out-dir ../web/pkg
-```
-
-The generated package is written to the ignored `web/pkg/` directory and can be served with any static HTTP server.
-
-## Legal Notice
-
-Use Senbei only for software you own or are authorized to analyze. The project is intended for lawful reverse engineering, security research, preservation, and interoperability.
+- Senbei is a research and interoperability tool. It exists to enable lawful reverse engineering, security research, preservation, and interoperability with software you already legitimately possess.
+- **Only process binaries you own or are explicitly authorized to analyze.** Depending on your jurisdiction and license agreements, circumventing technological protection measures may be restricted (for example under DMCA §1201 in the United States, which contains exemptions for security research and interoperability). It is your responsibility to ensure your use is lawful.
+- Senbei does not bypass any access control for you: it performs a purely static transformation of a file already on your disk. It derives everything it needs from the input file itself, contains no vendor code, and distributes no cracks or copyrighted content. (One Android packaging variant's embedded metadata layer is unwrapped with an XOR keystream recovered from a ciphertext/plaintext pair during analysis of a single build; that keystream is research output shipped with the unpacker, not a vendor-distributed key, and builds it doesn't match are left alone.)
+- Senbei does not enable online play, license fraud, or cheating, and must not be used to redistribute decrypted binaries. Do not upload outputs anywhere.
+- The authors provide this software "as is", without warranty of any kind, and accept no liability for misuse. See [LICENSE](LICENSE) (AGPL-3.0).
+- "Crackproof" is a trademark of its respective owner; this project is not affiliated with or endorsed by the protection vendor or any software publisher. Names are used for identification only.
 
 ## License
 

docs/design.md

@@ -1,59 +0,0 @@
-# Design
-
-Senbei is a fully static unpacker. It reads protected bytes, replays the protection algorithm, validates the result, and writes a recovered image without launching or attaching to the protected program.
-
-## Crate Layout
-
-The workspace is organized into eight crates. `senbei-cli` is the command-line entry point, `senbei-io` owns filesystem orchestration, `senbei-wasm` provides browser bindings, `senbei-pe` and `senbei-elf` provide basic format parsing, `senbei-crypto` provides shared primitives, `senbei-metadata` restores metadata, and `senbei-engine` owns protection-specific pipelines.
-
-Single-platform source stays directly under `src/`. Multi-platform crates keep platform code below `src/windows/` and `src/android/`, with shared code directly below `src/`.
-
-```text
-senbei-cli/src/main.rs
-senbei-crypto/src/
-senbei-crypto/src/android/
-senbei-crypto/src/windows/
-senbei-elf/src/
-senbei-engine/src/windows/
-senbei-engine/src/android/
-senbei-io/src/
-senbei-io/src/android/
-senbei-io/src/windows/
-senbei-metadata/src/
-senbei-metadata/src/windows/
-senbei-metadata/src/android/
-senbei-pe/src/
-senbei-wasm/src/
-```
-
-`senbei-pe` and `senbei-elf` own validated format models, address mapping, and ELF dynamic hash helpers. They do not depend on the unpacking engines, filesystem code, or platform protection logic.
-
-## Windows Engine
-
-`senbei-engine/src/windows/` contains PE detection, layout discovery, EXE and DLL restoration, deterministic block parallelism, and structural integrity checks. Candidate layouts are trial-decrypted and validated before an output is accepted.
-
-External companion inputs are reconstructed as `stub[..4096]` followed by the matching `._` payload. The stub's export, TLS, and declared CLR regions are overlaid after unpacking because those regions are not present in the encrypted companion. Managed restoration follows the COR20 directory and referenced metadata, resources, and vtable fixups through each file's RVA mapping, preserving the decrypted method bodies.
-
-## Android Engine
-
-`senbei-engine/src/android/extract/` decrypts the stage-1 header and stage-2 record streams and writes a temporary module workspace. `senbei-engine/src/android/restore/` applies decoded image and fixup containers to the hollowed ELF and rebuilds dynamic-linker tables. Both phases validate bounds and table placement before writing output.
-
-Windows protection primitives are in `senbei-crypto/src/windows/`, while Android protection primitives are in `senbei-crypto/src/android/`. Android seeded metadata restoration is in `senbei-metadata/src/android/`; the structural MethodDef transform is shared at the metadata crate root because both platform paths use it.
-
-Android ELF dynamic tables are located from the input section table and its actual file ranges. When the original gap is too small, restoration adds a validated read-only `PT_LOAD` after the existing load image and updates the dynamic tags; it never overwrites an adjacent section or emits a partial image.
-
-## Scanning and Packages
-
-Folder scanning uses platform target names to avoid opening bulk assets: Windows candidates are `.exe`, `.dll`, and `global-metadata.dat`; Android candidates are `.so` and `global-metadata.dat`. The shared walker is in `senbei-io/src/scan.rs`; platform name filters and PE companion byte adaptation are in `senbei-io/src/windows/`, and Android package adaptation is in `senbei-io/src/android/`. A Windows `.exe._` or `.dll._` companion is auxiliary input for its sibling stub and is excluded from the skipped count.
-
-APK, APKS, and XAPK files are containers. Senbei reads their ZIP manifests first, follows nested APK entries when necessary, and extracts only `.so` and exact `global-metadata.dat` entries. Extraction streams directly to temporary files, so compressed and decompressed copies are not held in memory together.
-
-## Validation
-
-Every heuristic layout uses trial-and-validate. A candidate that fails structural checks, checksums, or table bounds is rejected and the next candidate is tried. A failed restore is reported as an error rather than emitting a silently damaged binary.
-
-The PE integrity check verifies headers, section ranges, entry-point mapping, import names, relocation requirements, and managed metadata signatures. Android restoration validates ELF ranges, decoded container sizes, fixup bounds, and rebuilt dynamic tables.
-
-## WebAssembly
-
-The browser binding depends on `senbei-engine` through the I/O byte API. Native filesystem and Android package orchestration remain outside the browser workflow. Each browser unpack runs in a disposable worker because WebAssembly cannot recover from a caught panic in the same way as native code.

docs/development.md

@@ -1,61 +0,0 @@
-# Development
-
-## Building
-
-Rust 1.98.1 is required and pinned in `rust-toolchain.toml`. Build the CLI with `cargo build --release`; the binary is written to `target/release/senbei.exe` on Windows.
-
-The workspace crates are portable where their APIs are pure. The browser binding is outside the workspace and is checked with `cargo check --manifest-path senbei-wasm/Cargo.toml` or built with `wasm-pack`.
-
-## Testing
-
-```cmd
-cargo test --release --workspace
-cargo clippy --workspace --all-targets -- -D warnings
-cargo fmt --all -- --check
-```
-
-The tracked test suite is safe without protected samples. The optional local `samples/` corpus is user-managed and the ignored `test/` folder can be used for real Windows and Android runs.
-
-For an Android package, use one command at a time because a protected `.so` can be hundreds of megabytes. APK, APKS, and XAPK tests read the ZIP manifest first and extract only `.so` and `global-metadata.dat` entries.
-
-## Environment Variables
-
-- `DD8_SHIFT` overrides the PE page-XOR shift; `99` skips that stage.
-- `SEL_DIAG` prints PE layout-selector diagnostics.
-- `SENBEI_THREADS` caps deterministic block fan-out; `1` forces the sequential reference path.
-- `SENBEI_SCAN_ALL` enables probing selected target names below the size floor; it never enables arbitrary filenames.
-- `SENBEI_ANDROID_SAMPLES` overrides the Android sample corpus location.
-
-## Conventions
-
-Format crates stay free of filesystem I/O and protection-specific logic. Windows engine code lives below `senbei-engine/src/windows/`, Android engine code below `senbei-engine/src/android/`, and shared code stays directly under each crate's `src/`.
-
-Layout heuristics must trial and validate every candidate. A failed validation is an error or a fall-through, never a silently accepted offset.
-
-Outputs must remain byte-identical against the available golden corpus. Run the full workspace tests after changing a pipeline or a metadata layout.
-
-Folder scanning uses explicit target names to avoid opening bulk assets. External `.exe._` and `.dll._` files are auxiliary data for their sibling stubs and are not independent scan targets.
-
-## Repository Layout
-
-```text
-senbei-cli/       command-line binary and integration tests
-senbei-crypto/    Windows and Android crypto primitives
-senbei-elf/       ELF parsing, mapping, and dynamic-table helpers
-senbei-engine/    Windows and Android unpacking engines
-senbei-io/        filesystem, package, scanning, and platform adapters
-senbei-metadata/  shared, Windows, and Android metadata restoration
-senbei-pe/        PE parsing, data directories, and RVA mapping
-senbei-wasm/      browser bindings and its own lockfile
-web/              static browser frontend
-samples/          optional local corpus
-```
-
-## Web Build
-
-```cmd
-cd senbei-wasm
-wasm-pack build --target web --release --out-dir ../web/pkg
-```
-
-Serve `web/` with a static HTTP server after the build. The browser never uploads input files.

docs/usage.md

@@ -1,57 +0,0 @@
-# Usage
-
-```text
-senbei <file|folder> [--out DIR] [-v|--verbose] [-q|--quiet]... [--scan-all] [--no-log] [--no-pause] [-V|--version] [-h|--help]
-```
-
-## Single File
-
-The output is written below `<parent>/unpack/` with `.unpack` inserted before the extension. `--out DIR` changes both the output and log directory.
-
-```cmd
-senbei app.exe
-senbei app.exe --out C:\out
-```
-
-For `global-metadata.dat`, Senbei writes `global-metadata.unpack.dat` only when method tokens change. Unsupported metadata versions remain untouched and are reported as skipped.
-
-## Android Targets
-
-Protected `.so` files are restored from their encrypted payload sections and written as `libil2cpp.unpack.so` or the corresponding input name. APK, APKS, and XAPK files are treated as containers: their manifests are read first, nested APKs are followed when necessary, and only `.so` and exact `global-metadata.dat` entries are extracted.
-
-If a restored library contains embedded metadata, the unwrapped blob is written beside it as `global-metadata.unpack.dat`. Identical loose and package entries are restored once, preferring the loose file.
-
-## Folder Mode
-
-Folder mode walks recursively, skips directories named `unpack`, and mirrors recognized outputs below `<root>/unpack/` or `--out DIR`. Windows candidates are `.exe`, `.dll`, and `global-metadata.dat`; Android candidates are `.so` and `global-metadata.dat`. A matching `.exe._` or `.dll._` payload is consumed by its stub and is excluded from the skipped count.
-
-Managed DLL companions retain CLR metadata and related runtime tables in the original DLL. Both the DLL and its matching `._` file must be available; Senbei restores the declared CLR regions from the DLL while retaining method bodies decrypted from the companion. Invalid or missing referenced regions are reported as errors.
-
-The summary has the form `12 unpacked · 3 skipped · 0 errors · 1 suspect · 2 metadata`; the package count is appended when packages were opened. Each file is isolated so one failed target does not stop the folder run.
-
-## Integrity Check
-
-PE outputs are checked for valid headers, section ranges, entry-point mapping, readable import names, relocation requirements, and managed metadata signatures. Android outputs are validated during ELF restoration, including decoded container sizes, fixup bounds, and rebuilt dynamic tables.
-
-A clean report is not a proof of correctness, but a non-clean report is a reliable broken-output signal. Suspect PE files are still written and counted separately.
-
-## Flags
-
-| Flag | Behavior |
-| --- | --- |
-| `--out DIR` | Write outputs and logs below `DIR`. |
-| `-v`, `--verbose` | Print per-stage progress. |
-| `-q`, `--quiet` | Hide progress and per-file lines; repeat to suppress all standard output. |
-| `--no-log` | Do not write a run log. |
-| `--scan-all` | Probe every selected target-name candidate, including files below the size floor. |
-| `--no-pause` | Disable the Explorer-friendly Windows exit prompt. |
-| `-V`, `--version` | Print the version and exit. |
-| `-h`, `--help` | Show usage. |
-
-## Exit Codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | The requested restore completed without errors. |
-| `1` | A target failed, a scan probe was unreadable, or a single-file restore errored. |
-| `2` | The command line was invalid. |

senbei-elf/src/layout.rs

@@ -5,6 +5,8 @@ pub const SHT_STRTAB: u32 = 3;
 pub const SHT_LOUSER: u32 = 0x8000_0000;
 pub const SHF_ALLOC: u64 = 2;
 const PT_LOAD: u32 = 1;
+const PT_NOTE: u32 = 4;
+const PT_PHDR: u32 = 6;
 pub const PF_R: u32 = 4;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -220,7 +222,89 @@ impl ElfLayout {
         Ok(alignment)
     }
 
-    pub fn append_load_segment(&self, output: &mut [u8], segment: LoadSegment) -> Result<Self> {
+    pub fn additional_program_header_reservation(&self) -> Result<usize> {
+        if self.program_header_size != 0x38 {
+            return invalid("unexpected ELF program header size");
+        }
+        let new_count = self
+            .program_header_count
+            .checked_add(1)
+            .ok_or_else(|| Error::Invalid("program header count overflow".to_owned()))?;
+        let header_offset = checked_index(
+            self.program_header_offset,
+            self.program_header_count,
+            self.program_header_size,
+        )?;
+        let header_end = header_offset
+            .checked_add(self.program_header_size)
+            .ok_or_else(|| Error::Invalid("new program header range overflow".to_owned()))?;
+        let first_file_section = self
+            .section_headers
+            .iter()
+            .filter(|section| section.section_type != SHT_NOBITS && section.size != 0)
+            .map(|section| section.offset)
+            .min();
+        if first_file_section.is_none_or(|offset| header_end as u64 <= offset) {
+            return Ok(0);
+        }
+        new_count
+            .checked_mul(self.program_header_size)
+            .ok_or_else(|| Error::Invalid("relocated program header size overflow".to_owned()))
+    }
+
+    fn has_program_header_type(&self, data: &[u8], program_type: u32) -> Result<bool> {
+        for index in 0..self.program_header_count {
+            let offset =
+                checked_index(self.program_header_offset, index, self.program_header_size)?;
+            if read_u32(data, offset)? == program_type {
+                return Ok(true);
+            }
+        }
+        Ok(false)
+    }
+
+    fn reusable_note_program_header(&self, data: &[u8]) -> Result<Option<usize>> {
+        let mut note_count = 0_usize;
+        let mut candidates = Vec::new();
+        for index in 0..self.program_header_count {
+            let offset =
+                checked_index(self.program_header_offset, index, self.program_header_size)?;
+            if read_u32(data, offset)? != PT_NOTE {
+                continue;
+            }
+            note_count += 1;
+            let file_offset = read_u64(data, offset + 8)?;
+            let file_size = read_u64(data, offset + 0x20)?;
+            let file_end = file_offset
+                .checked_add(file_size)
+                .ok_or_else(|| Error::Invalid("PT_NOTE file range overflow".to_owned()))?;
+            let contained = self.program_headers.iter().any(|segment| {
+                segment
+                    .offset
+                    .checked_add(segment.file_size)
+                    .is_some_and(|segment_end| {
+                        segment.offset <= file_offset && file_end <= segment_end
+                    })
+            });
+            if contained {
+                candidates.push((file_offset, index));
+            }
+        }
+        if note_count < 2 {
+            return Ok(None);
+        }
+        Ok(candidates
+            .into_iter()
+            .max_by_key(|(file_offset, _)| *file_offset)
+            .map(|(_, index)| index))
+    }
+
+    pub fn append_load_segment(
+        &self,
+        output: &mut [u8],
+        segment: LoadSegment,
+        reserved_program_header_bytes: usize,
+    ) -> Result<Self> {
         if self.program_header_size != 0x38 {
             return invalid("unexpected ELF program header size");
         }
@@ -274,23 +358,11 @@ impl ElfLayout {
             .ok_or_else(|| Error::Invalid("program header count overflow".to_owned()))?;
         let new_count_u16 = u16::try_from(new_count)
             .map_err(|_| Error::Invalid("program header count exceeds u16".to_owned()))?;
-        let header_offset = checked_index(
-            self.program_header_offset,
-            self.program_header_count,
-            self.program_header_size,
-        )?;
-        let header_end = header_offset
-            .checked_add(self.program_header_size)
-            .ok_or_else(|| Error::Invalid("new program header range overflow".to_owned()))?;
-        slice(output, header_offset, self.program_header_size)?;
-        let first_file_section = self
-            .section_headers
-            .iter()
-            .filter(|section| section.section_type != SHT_NOBITS && section.size != 0)
-            .map(|section| section.offset)
-            .min();
-        if first_file_section.is_some_and(|offset| header_end as u64 > offset) {
-            return invalid("no space for an additional program header");
+        let reservation = self.additional_program_header_reservation()?;
+        if reserved_program_header_bytes != reservation {
+            return invalid(format!(
+                "program-header reservation mismatch: expected 0x{reservation:x}, got 0x{reserved_program_header_bytes:x}"
+            ));
         }
 
         let mut header = [0_u8; 0x38];
@@ -302,17 +374,95 @@ impl ElfLayout {
         header[0x20..0x28].copy_from_slice(&segment.file_size.to_le_bytes());
         header[0x28..0x30].copy_from_slice(&segment.memory_size.to_le_bytes());
         header[0x30..0x38].copy_from_slice(&segment.alignment.to_le_bytes());
+
+        let old_table_size = self
+            .program_header_count
+            .checked_mul(self.program_header_size)
+            .ok_or_else(|| Error::Invalid("program header table size overflow".to_owned()))?;
+        let new_table_size = new_count
+            .checked_mul(self.program_header_size)
+            .ok_or_else(|| Error::Invalid("program header table size overflow".to_owned()))?;
+        let mut updated_program_header_offset = self.program_header_offset;
+        let mut updated_program_header_count = new_count;
+        if reservation == 0 {
+            let header_offset = checked_index(
+                self.program_header_offset,
+                self.program_header_count,
+                self.program_header_size,
+            )?;
+            let header_end = header_offset
+                .checked_add(self.program_header_size)
+                .ok_or_else(|| Error::Invalid("new program header range overflow".to_owned()))?;
             output
                 .get_mut(header_offset..header_end)
                 .ok_or_else(|| Error::Invalid("new program header exceeds output".to_owned()))?
                 .copy_from_slice(&header);
+            update_pt_phdr(
+                output,
+                self.program_header_offset,
+                self.program_header_count,
+                self.program_header_size,
+                None,
+                new_table_size as u64,
+            )?;
+        } else if let Some(note_index) = self.reusable_note_program_header(output)? {
+            let header_offset = checked_index(
+                self.program_header_offset,
+                note_index,
+                self.program_header_size,
+            )?;
+            let header_end = header_offset
+                .checked_add(self.program_header_size)
+                .ok_or_else(|| Error::Invalid("reused program header range overflow".to_owned()))?;
+            output
+                .get_mut(header_offset..header_end)
+                .ok_or_else(|| Error::Invalid("reused program header exceeds output".to_owned()))?
+                .copy_from_slice(&header);
+            updated_program_header_count = self.program_header_count;
+        } else {
+            if !self.has_program_header_type(output, PT_PHDR)? {
+                return invalid(
+                    "cannot safely relocate program headers without PT_PHDR or a redundant PT_NOTE",
+                );
+            }
+            if reservation != new_table_size {
+                return invalid("relocated program-header reservation has unexpected size");
+            }
+            if segment.file_size < reservation as u64 {
+                return invalid("new PT_LOAD is too small for relocated program headers");
+            }
+            let relocated = usize_from_u64(segment.offset, "relocated program header offset")?;
+            let relocated_end = relocated.checked_add(new_table_size).ok_or_else(|| {
+                Error::Invalid("relocated program header range overflow".to_owned())
+            })?;
+            slice(output, relocated, new_table_size)?;
+            let old_table = slice(output, self.program_header_offset, old_table_size)?.to_vec();
+            output[relocated..relocated + old_table_size].copy_from_slice(&old_table);
+            output[relocated + old_table_size..relocated_end].copy_from_slice(&header);
+            output
+                .get_mut(0x20..0x28)
+                .ok_or_else(|| Error::Invalid("ELF header is truncated".to_owned()))?
+                .copy_from_slice(&segment.offset.to_le_bytes());
+            update_pt_phdr(
+                output,
+                relocated,
+                self.program_header_count,
+                self.program_header_size,
+                Some((segment.offset, segment.virtual_address)),
+                new_table_size as u64,
+            )?;
+            updated_program_header_offset = relocated;
+        }
+        if updated_program_header_count == new_count {
             output
                 .get_mut(0x38..0x3a)
                 .ok_or_else(|| Error::Invalid("ELF header is truncated".to_owned()))?
                 .copy_from_slice(&new_count_u16.to_le_bytes());
+        }
 
         let mut updated = self.clone();
-        updated.program_header_count = new_count;
+        updated.program_header_offset = updated_program_header_offset;
+        updated.program_header_count = updated_program_header_count;
         updated.program_headers.push(segment);
         Ok(updated)
     }
@@ -394,6 +544,47 @@ impl ElfLayout {
     }
 }
 
+fn update_pt_phdr(
+    output: &mut [u8],
+    table_offset: usize,
+    old_count: usize,
+    entry_size: usize,
+    relocated: Option<(u64, u64)>,
+    table_size: u64,
+) -> Result<()> {
+    for index in 0..old_count {
+        let offset = checked_index(table_offset, index, entry_size)?;
+        if read_u32(output, offset)? != PT_PHDR {
+            continue;
+        }
+        if let Some((file_offset, virtual_address)) = relocated {
+            output
+                .get_mut(offset + 8..offset + 0x10)
+                .ok_or_else(|| Error::Invalid("PT_PHDR file offset exceeds output".to_owned()))?
+                .copy_from_slice(&file_offset.to_le_bytes());
+            output
+                .get_mut(offset + 0x10..offset + 0x18)
+                .ok_or_else(|| Error::Invalid("PT_PHDR virtual address exceeds output".to_owned()))?
+                .copy_from_slice(&virtual_address.to_le_bytes());
+            output
+                .get_mut(offset + 0x18..offset + 0x20)
+                .ok_or_else(|| {
+                    Error::Invalid("PT_PHDR physical address exceeds output".to_owned())
+                })?
+                .copy_from_slice(&virtual_address.to_le_bytes());
+        }
+        output
+            .get_mut(offset + 0x20..offset + 0x28)
+            .ok_or_else(|| Error::Invalid("PT_PHDR file size exceeds output".to_owned()))?
+            .copy_from_slice(&table_size.to_le_bytes());
+        output
+            .get_mut(offset + 0x28..offset + 0x30)
+            .ok_or_else(|| Error::Invalid("PT_PHDR memory size exceeds output".to_owned()))?
+            .copy_from_slice(&table_size.to_le_bytes());
+    }
+    Ok(())
+}
+
 pub fn slice(data: &[u8], offset: usize, size: usize) -> Result<&[u8]> {
     let end = offset
         .checked_add(size)
@@ -585,6 +776,7 @@ mod tests {
                     flags: PF_R,
                     alignment: 0x1000,
                 },
+                0,
             )
             .expect("append segment");
         assert_eq!(updated.program_header_count, 1);
@@ -594,7 +786,7 @@ mod tests {
     }
 
     #[test]
-    fn append_load_segment_rejects_program_header_overlap() {
+    fn append_load_segment_fails_closed_when_no_safe_phdr_slot() {
         let mut elf_layout = ElfLayout {
             entrypoint: 0,
             program_header_offset: 0,
@@ -617,20 +809,157 @@ mod tests {
             alignment: 1,
             entry_size: 0,
         });
-        let mut output = vec![0_u8; 0x100];
+        let reservation = elf_layout
+            .additional_program_header_reservation()
+            .expect("reservation");
+        assert_eq!(reservation, 0x38);
+        let mut output = vec![0_u8; 0x200];
         let error = elf_layout
             .append_load_segment(
                 &mut output,
                 LoadSegment {
                     offset: 0x80,
                     virtual_address: 0x1080,
-                    file_size: 0x20,
-                    memory_size: 0x20,
+                    file_size: 0x80,
+                    memory_size: 0x80,
                     flags: PF_R,
                     alignment: 0x1000,
                 },
+                reservation,
             )
-            .expect_err("overlapping program header");
-        assert!(error.to_string().contains("additional program header"));
+            .expect_err("unsafe relocation must fail");
+        assert!(error.to_string().contains("cannot safely relocate"));
+    }
+
+    #[test]
+    fn append_load_segment_reuses_redundant_note_when_no_slack() {
+        let mut elf_layout = ElfLayout {
+            entrypoint: 0,
+            program_header_offset: 0x40,
+            program_header_size: 0x38,
+            program_header_count: 3,
+            program_headers: vec![LoadSegment {
+                offset: 0,
+                virtual_address: 0,
+                file_size: 0x400,
+                memory_size: 0x400,
+                flags: PF_R,
+                alignment: 0x1000,
+            }],
+            section_headers: Vec::new(),
+            section_name_index: 0,
+            private_section_index: usize::MAX,
+        };
+        elf_layout.section_headers.push(SectionHeader {
+            name: 0,
+            section_type: 1,
+            flags: 0,
+            address: 0,
+            offset: 0xe8,
+            size: 1,
+            link: 0,
+            info: 0,
+            alignment: 1,
+            entry_size: 0,
+        });
+        let mut output = vec![0_u8; 0x2000];
+        output[0x38..0x3a].copy_from_slice(&3_u16.to_le_bytes());
+        output[0x40..0x44].copy_from_slice(&PT_LOAD.to_le_bytes());
+        output[0x78..0x7c].copy_from_slice(&PT_NOTE.to_le_bytes());
+        output[0x80..0x88].copy_from_slice(&0x100_u64.to_le_bytes());
+        output[0x98..0xa0].copy_from_slice(&0x20_u64.to_le_bytes());
+        output[0xb0..0xb4].copy_from_slice(&PT_NOTE.to_le_bytes());
+        output[0xb8..0xc0].copy_from_slice(&0x200_u64.to_le_bytes());
+        output[0xd0..0xd8].copy_from_slice(&0x20_u64.to_le_bytes());
+
+        let reservation = elf_layout
+            .additional_program_header_reservation()
+            .expect("reservation");
+        assert_eq!(reservation, 0xe0);
+        let updated = elf_layout
+            .append_load_segment(
+                &mut output,
+                LoadSegment {
+                    offset: 0x1000,
+                    virtual_address: 0x2000,
+                    file_size: 0x100,
+                    memory_size: 0x100,
+                    flags: PF_R,
+                    alignment: 0x1000,
+                },
+                reservation,
+            )
+            .expect("reuse redundant PT_NOTE");
+
+        assert_eq!(updated.program_header_offset, 0x40);
+        assert_eq!(updated.program_header_count, 3);
+        assert_eq!(updated.program_headers.len(), 2);
+        assert_eq!(&output[0x38..0x3a], &3_u16.to_le_bytes());
+        assert_eq!(&output[0x78..0x7c], &PT_NOTE.to_le_bytes());
+        assert_eq!(&output[0xb0..0xb4], &PT_LOAD.to_le_bytes());
+        assert_eq!(&output[0xb8..0xc0], &0x1000_u64.to_le_bytes());
+        assert_eq!(&output[0xc0..0xc8], &0x2000_u64.to_le_bytes());
+    }
+
+    #[test]
+    fn relocated_program_headers_update_pt_phdr() {
+        let mut elf_layout = ElfLayout {
+            entrypoint: 0,
+            program_header_offset: 0x40,
+            program_header_size: 0x38,
+            program_header_count: 1,
+            program_headers: Vec::new(),
+            section_headers: Vec::new(),
+            section_name_index: 0,
+            private_section_index: usize::MAX,
+        };
+        elf_layout.section_headers.push(SectionHeader {
+            name: 0,
+            section_type: 1,
+            flags: 0,
+            address: 0,
+            offset: 0x78,
+            size: 1,
+            link: 0,
+            info: 0,
+            alignment: 1,
+            entry_size: 0,
+        });
+        let mut output = vec![0_u8; 0x2000];
+        output[0x20..0x28].copy_from_slice(&0x40_u64.to_le_bytes());
+        output[0x40..0x44].copy_from_slice(&PT_PHDR.to_le_bytes());
+        output[0x48..0x50].copy_from_slice(&0x40_u64.to_le_bytes());
+        output[0x50..0x58].copy_from_slice(&0x40_u64.to_le_bytes());
+        output[0x58..0x60].copy_from_slice(&0x40_u64.to_le_bytes());
+        output[0x60..0x68].copy_from_slice(&0x38_u64.to_le_bytes());
+        output[0x68..0x70].copy_from_slice(&0x38_u64.to_le_bytes());
+
+        let reservation = elf_layout
+            .additional_program_header_reservation()
+            .expect("reservation");
+        assert_eq!(reservation, 0x70);
+        let updated = elf_layout
+            .append_load_segment(
+                &mut output,
+                LoadSegment {
+                    offset: 0x1000,
+                    virtual_address: 0x2000,
+                    file_size: 0x100,
+                    memory_size: 0x100,
+                    flags: PF_R,
+                    alignment: 0x1000,
+                },
+                reservation,
+            )
+            .expect("relocate program headers");
+
+        assert_eq!(updated.program_header_offset, 0x1000);
+        assert_eq!(&output[0x20..0x28], &0x1000_u64.to_le_bytes());
+        assert_eq!(&output[0x1000..0x1004], &PT_PHDR.to_le_bytes());
+        assert_eq!(&output[0x1008..0x1010], &0x1000_u64.to_le_bytes());
+        assert_eq!(&output[0x1010..0x1018], &0x2000_u64.to_le_bytes());
+        assert_eq!(&output[0x1020..0x1028], &0x70_u64.to_le_bytes());
+        assert_eq!(&output[0x1028..0x1030], &0x70_u64.to_le_bytes());
+        assert_eq!(&output[0x1038..0x103c], &PT_LOAD.to_le_bytes());
     }
 }

senbei-elf/src/lib.rs

@@ -15,26 +15,23 @@ pub use layout::{
 /// ELF machine identifier for AArch64.
 pub const AARCH64_MACHINE: u16 = EM_AARCH64;
 
-/// Dynamic sections required by the restored AArch64 loader image.
-pub const DYNAMIC_SECTION_NAMES: [&str; 8] = [
+/// Dynamic sections required by every restored AArch64 loader image.
+pub const DYNAMIC_SECTION_NAMES: [&str; 7] = [
     ".dynsym",
     ".gnu.version",
     ".gnu.version_r",
-    ".gnu.hash",
     ".dynstr",
     ".rela.dyn",
     ".rela.plt",
     ".dynamic",
 ];
 
+/// Supported dynamic symbol-hash sections. At least one must be present.
+pub const SYMBOL_HASH_SECTION_NAMES: [&str; 2] = [".gnu.hash", ".hash"];
+
 /// Dynamic sections needed to identify a protected image before extraction.
-pub const PROBE_SECTION_NAMES: [&str; 5] = [
-    ".dynsym",
-    ".dynstr",
-    ".gnu.hash",
-    ".gnu.version",
-    ".gnu.version_r",
-];
+/// Hash tables are checked separately because either GNU or SysV hashing is valid.
+pub const PROBE_SECTION_NAMES: [&str; 4] = [".dynsym", ".dynstr", ".gnu.version", ".gnu.version_r"];
 
 /// ELF64 dynamic table record sizes.
 pub const ELF64_SYMBOL_SIZE: usize = 0x18;

senbei-engine/src/android/extract/stage1.rs

@@ -70,6 +70,16 @@ pub(crate) fn inspect(
             return invalid(format!("protected ELF lacks required section {wanted}"));
         }
     }
+    let has_symbol_hash = senbei_elf::SYMBOL_HASH_SECTION_NAMES.iter().any(|wanted| {
+        elf.section_headers.iter().any(|section| {
+            elf.shdr_strtab
+                .get_at(section.sh_name)
+                .is_some_and(|name| name == *wanted)
+        })
+    });
+    if !has_symbol_hash {
+        return invalid("protected ELF lacks a .gnu.hash or .hash symbol-hash section");
+    }
     let (section_index, section) = matches[0];
     let section_offset = usize::try_from(section.sh_offset)
         .map_err(|_| Error::Invalid("SHT_LOUSER offset exceeds usize".to_owned()))?;

senbei-engine/src/android/restore/pipeline.rs

@@ -757,7 +757,18 @@ fn dynamic_contains_tag(output: &[u8], dynamic: SectionHeader, wanted: u64) -> R
 }
 
 fn required_section_indices(names: &[String]) -> Result<HashMap<&'static str, usize>> {
-    let mut result = HashMap::with_capacity(senbei_elf::DYNAMIC_SECTION_NAMES.len());
+    let present = senbei_elf::SYMBOL_HASH_SECTION_NAMES
+        .iter()
+        .filter(|name| names.iter().any(|section| section == *name))
+        .count();
+    if present == 0 {
+        return invalid(
+            "ELF must carry at least one of the .gnu.hash / .hash symbol-hash sections",
+        );
+    }
+    let mut result = HashMap::with_capacity(
+        senbei_elf::DYNAMIC_SECTION_NAMES.len() + senbei_elf::SYMBOL_HASH_SECTION_NAMES.len(),
+    );
     for required in senbei_elf::DYNAMIC_SECTION_NAMES {
         let indices = names
             .iter()
@@ -772,17 +783,19 @@ fn required_section_indices(names: &[String]) -> Result<HashMap<&'static str, us
             _ => return invalid(format!("ELF contains duplicate section {required}")),
         }
     }
-    let sysv_hash = names
+    for hash_table in senbei_elf::SYMBOL_HASH_SECTION_NAMES {
+        let indices = names
             .iter()
             .enumerate()
-        .filter_map(|(index, name)| (name == ".hash").then_some(index))
+            .filter_map(|(index, name)| (name == hash_table).then_some(index))
             .collect::<Vec<_>>();
-    match sysv_hash.as_slice() {
+        match indices.as_slice() {
             [index] => {
-            result.insert(".hash", *index);
+                result.insert(hash_table, *index);
             }
             [] => {}
-        _ => return invalid("ELF contains duplicate section .hash"),
+            _ => return invalid(format!("ELF contains duplicate section {hash_table}")),
+        }
     }
     Ok(result)
 }
@@ -862,7 +875,8 @@ fn metadata_mapping_length(
         usize_from_u64(rela_plt.size / ELF64_RELA_SIZE as u64, ".rela.plt count")?
             .checked_add(auxiliary.relocation2_count as usize)
             .ok_or_else(|| Error::Invalid("merged .rela.plt count overflow".to_owned()))?;
-    let gnu_hash_size = 28_usize
+    let gnu_hash_size = if indices.contains_key(".gnu.hash") {
+        28_usize
             .checked_add(
                 new_symbol_count
                     .checked_sub(1)
@@ -872,7 +886,10 @@ fn metadata_mapping_length(
                     .checked_mul(4)
                     .ok_or_else(|| Error::Invalid("GNU hash size overflow".to_owned()))?,
             )
-        .ok_or_else(|| Error::Invalid("GNU hash size overflow".to_owned()))?;
+            .ok_or_else(|| Error::Invalid("GNU hash size overflow".to_owned()))?
+    } else {
+        0
+    };
     let sysv_hash_size = indices.contains_key(".hash").then(|| {
         new_symbol_count
             .checked_mul(2)
@@ -884,7 +901,9 @@ fn metadata_mapping_length(
         Some(size) => size?,
         None => 0,
     };
-    let mut cursor = 0_u64;
+    let program_header_reservation = u64::try_from(layout.additional_program_header_reservation()?)
+        .map_err(|_| Error::Invalid("program-header reservation exceeds u64".to_owned()))?;
+    let mut cursor = program_header_reservation;
     for (size, alignment) in [
         (
             new_symbol_count
@@ -1029,7 +1048,10 @@ fn materialize_static_elf_tables(
         .contains_key(".hash")
         .then(|| build_sysv_hash(&merged_names))
         .transpose()?;
-    let gnu_hash_table = build_gnu_hash(&merged_names)?;
+    let gnu_hash_table = indices
+        .contains_key(".gnu.hash")
+        .then(|| build_gnu_hash(&merged_names))
+        .transpose()?;
     let new_symbol_count = merged_names.len();
     let new_dynstr_size = merged_strings.len();
 
@@ -1100,6 +1122,11 @@ fn materialize_static_elf_tables(
     let rela_dyn_count = merged_rela_dyn.len() / ELF64_RELA_SIZE;
     let rela_plt_count = merged_rela_plt.len() / ELF64_RELA_SIZE;
 
+    let gnu_hash = gnu_hash_table.map(|data| TablePayload {
+        name: ".gnu.hash",
+        alignment: 8,
+        data,
+    });
     let mut tables = vec![
         TablePayload {
             name: ".dynsym",
@@ -1116,12 +1143,10 @@ fn materialize_static_elf_tables(
             alignment: 4,
             data: version_requirements,
         },
-        TablePayload {
-            name: ".gnu.hash",
-            alignment: 8,
-            data: gnu_hash_table,
-        },
     ];
+    if let Some(payload) = gnu_hash {
+        tables.push(payload);
+    }
     if let Some(data) = sysv_hash {
         tables.push(TablePayload {
             name: ".hash",
@@ -1152,8 +1177,12 @@ fn materialize_static_elf_tables(
     let mut capacity_end = metadata_capacity_end(layout, &indices, metadata_start)?;
     if cursor > capacity_end {
         let alignment = layout.load_alignment()?;
+        let program_header_reservation = layout.additional_program_header_reservation()?;
         let extension_start = align_up(layout.private_section()?.offset, alignment)?;
-        let extension_end = table_end(&tables, extension_start)?;
+        let extension_metadata_start = extension_start
+            .checked_add(program_header_reservation as u64)
+            .ok_or_else(|| Error::Invalid("dynamic-table extension start overflow".to_owned()))?;
+        let extension_end = table_end(&tables, extension_metadata_start)?;
         let extension_size = extension_end
             .checked_sub(extension_start)
             .ok_or_else(|| Error::Invalid("dynamic-table extension underflow".to_owned()))?;
@@ -1168,8 +1197,9 @@ fn materialize_static_elf_tables(
                 flags: PF_R,
                 alignment,
             },
+            program_header_reservation,
         )?;
-        metadata_start = extension_start;
+        metadata_start = extension_metadata_start;
         (placements, cursor) = table_placements(&tables, metadata_start)?;
         capacity_end = cursor;
     }
@@ -1224,10 +1254,12 @@ fn materialize_static_elf_tables(
         (DT_RELASZ, (rela_dyn_count * ELF64_RELA_SIZE) as u64),
         (DT_STRSZ, new_dynstr_size as u64),
         (DT_JMPREL, section_address(".rela.plt")),
-        (DT_GNU_HASH, section_address(".gnu.hash")),
         (DT_VERSYM, section_address(".gnu.version")),
         (DT_VERNEED, section_address(".gnu.version_r")),
     ]);
+    if indices.contains_key(".gnu.hash") {
+        dynamic_values.insert(DT_GNU_HASH, section_address(".gnu.hash"));
+    }
     if dynamic_contains_tag(output, dynamic, DT_RELACOUNT)? {
         dynamic_values.insert(DT_RELACOUNT, relative_count as u64);
     }
@@ -1720,4 +1752,34 @@ mod tests {
         let error = AuxiliaryElfImage::parse(&auxiliary_image(0)).expect_err("missing null symbol");
         assert!(error.to_string().contains("no null entry"));
     }
+
+    fn dynamic_section_names(hash_sections: &[&str]) -> Vec<String> {
+        senbei_elf::DYNAMIC_SECTION_NAMES
+            .into_iter()
+            .chain(hash_sections.iter().copied())
+            .map(str::to_owned)
+            .collect()
+    }
+
+    #[test]
+    fn required_sections_accept_each_hash_layout() {
+        for hashes in [
+            [".gnu.hash"].as_slice(),
+            [".hash"].as_slice(),
+            [".gnu.hash", ".hash"].as_slice(),
+        ] {
+            let indices = required_section_indices(&dynamic_section_names(hashes))
+                .expect("valid hash layout");
+            for hash in hashes {
+                assert!(indices.contains_key(hash));
+            }
+        }
+    }
+
+    #[test]
+    fn required_sections_reject_missing_symbol_hash() {
+        let error =
+            required_section_indices(&dynamic_section_names(&[])).expect_err("missing hash");
+        assert!(error.to_string().contains("at least one"));
+    }
 }

senbei-io/src/android/mod.rs

@@ -1,6 +1,6 @@
 //! Android target orchestration: protected AArch64 shared libraries (`.so`),
 //! app packages (`.apk` / `.apks` / `.xapk`), and the Android variant of the
-//! il2cpp method-token obfuscation.
+//! il2cpp method-token/method-index obfuscation.
 //!
 //! The protection scheme hollows out an ELF64/AArch64 shared object and moves
 //! the original bytes into an encrypted payload appended as a `SHT_LOUSER`
@@ -100,14 +100,32 @@ pub fn file_content_identity(path: &Path) -> std::io::Result<String> {
 /// implementation detail of the two-phase restore, not user-facing output).
 /// Returns the unwrapped embedded metadata blob when the restored image
 /// carries one (see the module docs); the caller decides where to write it.
-pub fn restore_so_file(input: &Path, dest: &Path, verbose: bool) -> Result<Option<Vec<u8>>> {
+struct SoRestoreContext {
+    embedded_metadata: Option<Vec<u8>>,
+    method_index_module: Option<Vec<u8>>,
+}
+
+fn restore_so_file_with_context(
+    input: &Path,
+    dest: &Path,
+    verbose: bool,
+) -> Result<SoRestoreContext> {
     let temporary = tempfile::tempdir().context("create stage-2 workspace")?;
     let stage2_dir = temporary.path().join("stage2");
-    extract_stage2(&ExtractOptions::with_defaults(
+    let extraction = extract_stage2(&ExtractOptions::with_defaults(
         input.to_path_buf(),
         stage2_dir.clone(),
     ))
     .context("extract stage-1/stage-2 payload")?;
+    let method_index_module = extraction
+        .module_registry
+        .iter()
+        .find(|module| module.command_id == 0x0c)
+        .map(|module| {
+            std::fs::read(stage2_dir.join(&module.image_path))
+                .with_context(|| format!("read decoded module 0x0C `{}`", module.image_path))
+        })
+        .transpose()?;
     restore_libil2cpp(&RestoreOptions {
         input: input.to_path_buf(),
         output: dest.to_path_buf(),
@@ -120,9 +138,28 @@ pub fn restore_so_file(input: &Path, dest: &Path, verbose: bool) -> Result<Optio
     .context("restore protected library")?;
     let restored =
         std::fs::read(dest).with_context(|| format!("read restored `{}`", dest.display()))?;
-    Ok(senbei_metadata::android::extract_embedded_metadata(
-        &restored,
-    ))
+    Ok(SoRestoreContext {
+        embedded_metadata: senbei_metadata::android::extract_embedded_metadata(&restored),
+        method_index_module,
+    })
+}
+
+pub fn restore_so_file(input: &Path, dest: &Path, verbose: bool) -> Result<Option<Vec<u8>>> {
+    let mut method_index_module = None;
+    restore_so_file_with_method_index_module(input, dest, verbose, &mut method_index_module)
+}
+
+pub(crate) fn restore_so_file_with_method_index_module(
+    input: &Path,
+    dest: &Path,
+    verbose: bool,
+    method_index_module: &mut Option<Vec<u8>>,
+) -> Result<Option<Vec<u8>>> {
+    let restored = restore_so_file_with_context(input, dest, verbose)?;
+    if let Some(module) = restored.method_index_module {
+        *method_index_module = Some(module);
+    }
+    Ok(restored.embedded_metadata)
 }
 
 /// Content identity for cross-source deduplication: the same library may
@@ -134,8 +171,10 @@ pub fn content_identity(data: &[u8]) -> String {
     hex_digest(&digest.finalize())
 }
 
-/// Restore an il2cpp metadata blob (Android seeded permutation first, then the
-/// structural remap used by the Windows builds).
+/// Restore an il2cpp metadata blob. Paired v24.1 Android packages use the
+/// method-index profile recovered from module 0x0C; later Android layouts use
+/// the seeded MethodDef RID permutation before falling back to the structural
+/// remap used by the Windows builds.
 ///
 /// The Android variant obfuscates MethodDef RIDs with a keyed five-round
 /// permutation; the correct seed is recovered by intersecting per-image key
@@ -145,6 +184,32 @@ pub fn content_identity(data: &[u8]) -> String {
 /// canonical form. Both paths are no-ops (`remapped == 0`) on an
 /// already-clean blob.
 pub fn restore_metadata_bytes(data: &[u8]) -> anyhow::Result<(Vec<u8>, senbei_metadata::Report)> {
+    restore_metadata_bytes_with_module(data, None)
+}
+
+pub(crate) fn restore_metadata_bytes_with_module(
+    data: &[u8],
+    method_index_module: Option<&[u8]>,
+) -> anyhow::Result<(Vec<u8>, senbei_metadata::Report)> {
+    let version = data
+        .get(4..8)
+        .and_then(|bytes| <[u8; 4]>::try_from(bytes).ok())
+        .map(u32::from_le_bytes);
+    if version == Some(24)
+        && let Some(module) = method_index_module
+    {
+        let (out, report) = senbei_metadata::android::restore_method_indices_v24_1(data, module)
+            .map_err(anyhow::Error::new)?;
+        return Ok((
+            out,
+            senbei_metadata::Report {
+                version: report.version,
+                methods: report.methods,
+                remapped: report.changed_indices,
+                modules: 0,
+            },
+        ));
+    }
     if let Ok(discovery) = senbei_metadata::android::discover_method_token_seeds(data)
         && matches!(discovery.version, 29 | 31 | 39)
     {
@@ -190,7 +255,7 @@ pub struct EntryOutcome {
 pub enum EntryKind {
     /// A protected shared library, restored.
     So,
-    /// An il2cpp metadata blob, de-obfuscated (`remapped` tokens changed).
+    /// An il2cpp metadata blob, de-obfuscated (`remapped` method fields changed).
     Metadata { remapped: usize },
     /// A metadata blob unwrapped from a restored library's data section.
     EmbeddedMetadata,
@@ -204,12 +269,30 @@ pub enum EntryStatus {
     Duplicate,
     /// Content-probed but not a target (unprotected library).
     NotTarget,
-    /// A metadata blob whose tokens were already canonical; no copy written.
+    /// A metadata blob whose protected method fields were already canonical; no copy written.
     Unchanged,
     /// Recognised as a target but the restore failed.
     Failed(anyhow::Error),
 }
 
+struct PackageRestoreContext<'a> {
+    method_index_module: &'a mut Option<Vec<u8>>,
+    verbose: bool,
+}
+
+impl<'a> PackageRestoreContext<'a> {
+    fn new(verbose: bool, method_index_module: &'a mut Option<Vec<u8>>) -> Self {
+        Self {
+            method_index_module,
+            verbose,
+        }
+    }
+}
+
+fn package_entry_priority(path: &Path) -> u8 {
+    if is_so_name(path) { 0 } else { 1 }
+}
+
 /// Restore every protected library and metadata blob inside one app package.
 ///
 /// `rel` is the package's path relative to the scanned root (or its bare file
@@ -223,6 +306,25 @@ pub fn restore_package(
     out_root: &Path,
     seen: &mut HashSet<String>,
     verbose: bool,
+) -> Result<Vec<EntryOutcome>> {
+    let mut method_index_module = None;
+    restore_package_with_method_index_module(
+        package,
+        rel,
+        out_root,
+        seen,
+        verbose,
+        &mut method_index_module,
+    )
+}
+
+pub(crate) fn restore_package_with_method_index_module(
+    package: &Path,
+    rel: &Path,
+    out_root: &Path,
+    seen: &mut HashSet<String>,
+    verbose: bool,
+    method_index_module: &mut Option<Vec<u8>>,
 ) -> Result<Vec<EntryOutcome>> {
     let bundle = package
         .extension()
@@ -233,6 +335,7 @@ pub fn restore_package(
     let mut archive = open_package(package)?;
     let temporary = tempfile::tempdir().context("create package workspace")?;
     let mut outcomes = Vec::new();
+    let mut context = PackageRestoreContext::new(verbose, method_index_module);
 
     let mut direct = Vec::new();
     let mut nested = Vec::new();
@@ -261,6 +364,7 @@ pub fn restore_package(
             }
         }
     }
+    direct.sort_by_key(|(_, name)| package_entry_priority(name));
     for (index, name) in direct {
         let label = format!("{}::{}", rel.display(), name.display());
         let dest = out_root.join(rel).join(crate::job::out_name(&name));
@@ -271,11 +375,19 @@ pub fn restore_package(
             &dest,
             &temporary,
             seen,
-            verbose,
+            &mut context,
         )
         .with_context(|| format!("extract `{label}`"))?;
         outcomes.append(&mut entry_outcomes);
     }
+    struct NestedPackage {
+        label: PathBuf,
+        path: PathBuf,
+        base: PathBuf,
+        entries: Vec<(usize, PathBuf)>,
+    }
+
+    let mut nested_packages = Vec::with_capacity(nested.len());
     for (index, name) in nested {
         let nested_label = rel.join(&name);
         let nested_path = extract_entry(&mut archive, index, &temporary, &nested_label)
@@ -296,25 +408,47 @@ pub fn restore_package(
                 }
             }
         }
-        // Keep the nested package's stem in the output layout so two splits
-        // carrying same-named entries cannot collide.
-        let base = rel.join(name.with_extension(""));
-        for (nested_index, entry_name) in entries {
-            let label = format!("{}::{}", nested_label.display(), entry_name.display());
-            let dest = out_root.join(&base).join(crate::job::out_name(&entry_name));
+        nested_packages.push(NestedPackage {
+            label: nested_label,
+            path: nested_path,
+            base: rel.join(name.with_extension("")),
+            entries,
+        });
+    }
+
+    // A bundle can put libil2cpp.so in an ABI split while metadata stays in
+    // base.apk. Share one context across the whole bundle and process all SOs
+    // before any metadata, regardless of which nested APK owns each entry.
+    for priority in [0_u8, 1_u8] {
+        for nested_package in &nested_packages {
+            let mut nested_archive = open_package(&nested_package.path)?;
+            for (nested_index, entry_name) in nested_package
+                .entries
+                .iter()
+                .filter(|(_, entry_name)| package_entry_priority(entry_name) == priority)
+            {
+                let label = format!(
+                    "{}::{}",
+                    nested_package.label.display(),
+                    entry_name.display()
+                );
+                let dest = out_root
+                    .join(&nested_package.base)
+                    .join(crate::job::out_name(entry_name));
                 let mut entry_outcomes = restore_package_entry(
                     &mut nested_archive,
-                nested_index,
+                    *nested_index,
                     &label,
                     &dest,
                     &temporary,
                     seen,
-                verbose,
+                    &mut context,
                 )
                 .with_context(|| format!("extract `{label}`"))?;
                 outcomes.append(&mut entry_outcomes);
             }
         }
+    }
     Ok(outcomes)
 }
 
@@ -328,7 +462,7 @@ fn restore_package_entry<R: Read + Seek>(
     dest: &Path,
     temporary: &tempfile::TempDir,
     seen: &mut HashSet<String>,
-    verbose: bool,
+    context: &mut PackageRestoreContext<'_>,
 ) -> Result<Vec<EntryOutcome>> {
     let entry_path = extract_entry(archive, index, temporary, Path::new(label))?;
     let entry_file =
@@ -358,10 +492,14 @@ fn restore_package_entry<R: Read + Seek>(
     if is_so {
         drop(entry_data);
         drop(entry_file);
-        return Ok(match restore_so_file(&entry_path, dest, verbose) {
-            Ok(embedded) => {
+        return Ok(
+            match restore_so_file_with_context(&entry_path, dest, context.verbose) {
+                Ok(restored) => {
+                    if let Some(module) = restored.method_index_module {
+                        *context.method_index_module = Some(module);
+                    }
                     let mut outcomes = vec![outcome(EntryKind::So, EntryStatus::Restored)];
-                if let Some(blob) = embedded {
+                    if let Some(blob) = restored.embedded_metadata {
                         let meta_dest = embedded_metadata_dest(dest);
                         let status = match write_metadata_blob(&meta_dest, &blob) {
                             Ok(()) => EntryStatus::Restored,
@@ -377,12 +515,16 @@ fn restore_package_entry<R: Read + Seek>(
                     outcomes
                 }
                 Err(error) => vec![outcome(EntryKind::So, EntryStatus::Failed(error))],
-        });
+            },
+        );
     }
 
-    // Metadata entry: write only when the restore actually changed tokens —
+    // Metadata entry: write only when the restore actually changed protected method fields —
     // a clean blob needs no copy (same contract as loose metadata files).
-    let kind_and_status = match restore_metadata_bytes(&entry_data) {
+    let kind_and_status = match restore_metadata_bytes_with_module(
+        &entry_data,
+        context.method_index_module.as_deref(),
+    ) {
         Ok((out, report)) if report.remapped > 0 => {
             let kind = EntryKind::Metadata {
                 remapped: report.remapped,

senbei-io/src/job.rs

@@ -15,7 +15,7 @@ pub struct Summary {
     /// — likely to crash at runtime (e.g. 0xC0000005). Counted in addition to
     /// `unpacked` (a suspect file is still written).
     pub suspect: usize,
-    /// il2cpp `global-metadata.dat` files de-obfuscated (method tokens remapped),
+    /// il2cpp `global-metadata.dat` files de-obfuscated (protected method fields remapped),
     /// including blobs unwrapped from restored Android libraries.
     pub metadata: usize,
     /// Android app packages (`.apk`/`.apks`/`.xapk`) opened and searched.
@@ -221,6 +221,7 @@ pub fn run_folder_opts(
     // files restore first so the cross-source dedup keeps them over a copy
     // inside a package (loose beats `.apk` beats `.apks`/`.xapk` bundle).
     let mut android_seen = std::collections::HashSet::new();
+    let mut android_method_index_module = None;
     // Hashing a protected library costs a full read, so only pay it when a
     // duplicate source can actually exist in this run.
     let android_dedup = scan.android_so.len() > 1 || !scan.android_packages.is_empty();
@@ -242,7 +243,12 @@ pub fn run_folder_opts(
         let input_owned = input.clone();
         let dest_owned = dest.clone();
         let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            crate::android::restore_so_file(&input_owned, &dest_owned, verbose_steps)
+            crate::android::restore_so_file_with_method_index_module(
+                &input_owned,
+                &dest_owned,
+                verbose_steps,
+                &mut android_method_index_module,
+            )
         }));
         match result {
             Ok(Ok(embedded)) => {
@@ -310,12 +316,13 @@ pub fn run_folder_opts(
         let out_root_owned = out_root.clone();
         let mut seen_taken = std::mem::take(&mut android_seen);
         let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            let outcomes = crate::android::restore_package(
+            let outcomes = crate::android::restore_package_with_method_index_module(
                 &package_owned,
                 &rel_owned,
                 &out_root_owned,
                 &mut seen_taken,
                 verbose_steps,
+                &mut android_method_index_module,
             );
             (outcomes, seen_taken)
         }));
@@ -361,7 +368,12 @@ pub fn run_folder_opts(
         let meta_owned = meta.clone();
         let dest_owned = dest.clone();
         let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            deobfuscate_metadata_to(&meta_owned, &dest_owned, verbose_steps)
+            deobfuscate_metadata_to_with_module(
+                &meta_owned,
+                &dest_owned,
+                verbose_steps,
+                android_method_index_module.as_deref(),
+            )
         }));
         match result {
             Ok(Ok(report)) if report.remapped > 0 => {
@@ -369,7 +381,7 @@ pub fn run_folder_opts(
                 crate::ui::metadata(&bar, suppress_file_lines, &rel, report.remapped, &dest);
                 if let Some(log) = &log {
                     log.step(&format!(
-                        "META {rel:?} -> {dest:?}: v{} remapped {} method tokens",
+                        "META {rel:?} -> {dest:?}: v{} remapped {} method fields",
                         report.version, report.remapped
                     ));
                 }
@@ -506,13 +518,13 @@ pub fn run_file_v(
                 s.metadata = 1;
                 if let Some(log) = &log {
                     log.step(&format!(
-                        "META {:?} -> {:?}: v{} remapped {} method tokens",
+                        "META {:?} -> {:?}: v{} remapped {} method fields",
                         input, dest, report.version, report.remapped
                     ));
                 }
                 if quiet == 0 {
                     println!(
-                        "✓ metadata v{} -> {:?} ({} method tokens remapped)",
+                        "✓ metadata v{} -> {:?} ({} method fields remapped)",
                         report.version, dest, report.remapped
                     );
                 }
@@ -735,6 +747,15 @@ pub fn deobfuscate_metadata_to(
     input: &Path,
     dest: &Path,
     verbose: bool,
+) -> anyhow::Result<senbei_metadata::Report> {
+    deobfuscate_metadata_to_with_module(input, dest, verbose, None)
+}
+
+fn deobfuscate_metadata_to_with_module(
+    input: &Path,
+    dest: &Path,
+    verbose: bool,
+    method_index_module: Option<&[u8]>,
 ) -> anyhow::Result<senbei_metadata::Report> {
     let data = std::fs::read(input)?;
     // The Android seeded-permutation variant is tried first (it validates
@@ -742,7 +763,8 @@ pub fn deobfuscate_metadata_to(
     // Windows path. The [`senbei_metadata::Error`] is preserved in the chain
     // (rather than stringified) so the folder driver can apply its
     // unsupported-version policy.
-    let (out, report) = crate::android::restore_metadata_bytes(&data)
+    let (out, report) =
+        crate::android::restore_metadata_bytes_with_module(&data, method_index_module)
             .map_err(|e| e.context(format!("{input:?}")))?;
     if report.remapped > 0 {
         if let Some(parent) = dest.parent() {

senbei-io/src/ui.rs

@@ -39,13 +39,13 @@ pub fn ok_label(bar: &ProgressBar, quiet: bool, rel: &str, label: &str, dest: &P
 }
 
 /// Print a green success line for a de-obfuscated il2cpp `global-metadata.dat`,
-/// reporting how many method tokens were remapped.
+/// reporting how many protected method fields were remapped.
 pub fn metadata(bar: &ProgressBar, quiet: bool, rel: &Path, remapped: usize, dest: &Path) {
     if quiet {
         return;
     }
     let msg = format!(
-        "{} metadata  {}  ->  {}  ({} method tokens remapped)",
+        "{} metadata  {}  ->  {}  ({} method fields remapped)",
         "✓".green(),
         rel.display(),
         dest.display(),

senbei-metadata/src/android/method_indices.rs

@@ -0,0 +1,467 @@
+//! Restoration of IL2CPP v24.1 `Il2CppMethodDefinition.methodIndex` values.
+//!
+//! CrackProof's v24.1 Android module rewrites the global method-index permutation
+//! at runtime. The transform parameters are carried by the decoded module `0x0C`,
+//! so the restore derives them from that module instead of hard-coding a
+//! game-specific table.
+
+use serde::Serialize;
+
+use crate::common::MAGIC;
+
+const RAW_VERSION_24: u32 = 24;
+const HDR_METHODS: usize = 0x30;
+const V24_1_METHOD_STRIDE: usize = 0x34;
+const V24_1_METHOD_INDEX_OFFSET: usize = 0x14;
+const V24_1_SELECTOR: u32 = 1;
+const EXCEPTION_COUNT: usize = 256;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct MethodIndexReport {
+    pub version: u32,
+    pub methods: usize,
+    pub active_methods: usize,
+    pub changed_indices: usize,
+    pub exception_count: usize,
+    pub seed: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum MethodIndexError {
+    #[error("not an IL2CPP global-metadata.dat")]
+    NotMetadata,
+    #[error("unsupported metadata version {0}")]
+    UnsupportedVersion(u32),
+    #[error("malformed v24.1 metadata: {0}")]
+    Malformed(String),
+    #[error("v24.1 method-index profile was not found in module 0x0C")]
+    ProfileNotFound,
+    #[error("multiple v24.1 method-index profiles matched module 0x0C")]
+    AmbiguousProfile,
+    #[error("v24.1 method-index restoration failed validation: {0}")]
+    Validation(String),
+}
+
+type Result<T> = std::result::Result<T, MethodIndexError>;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Profile {
+    seed: u32,
+    exception_values: [u32; EXCEPTION_COUNT],
+}
+
+fn bytes(data: &[u8], offset: usize, size: usize) -> Result<&[u8]> {
+    let end = offset
+        .checked_add(size)
+        .ok_or_else(|| MethodIndexError::Malformed("byte range overflow".to_owned()))?;
+    data.get(offset..end).ok_or_else(|| {
+        MethodIndexError::Malformed(format!(
+            "byte range 0x{offset:x}..0x{end:x} is out of bounds"
+        ))
+    })
+}
+
+fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
+    let value: [u8; 4] = bytes(data, offset, 4)?
+        .try_into()
+        .map_err(|_| MethodIndexError::Malformed("invalid u32 range".to_owned()))?;
+    Ok(u32::from_le_bytes(value))
+}
+
+fn read_i32(data: &[u8], offset: usize) -> Result<i32> {
+    let value: [u8; 4] = bytes(data, offset, 4)?
+        .try_into()
+        .map_err(|_| MethodIndexError::Malformed("invalid i32 range".to_owned()))?;
+    Ok(i32::from_le_bytes(value))
+}
+
+fn write_i32(data: &mut [u8], offset: usize, value: i32) -> Result<()> {
+    let destination = data.get_mut(offset..offset + 4).ok_or_else(|| {
+        MethodIndexError::Malformed("method-index write is out of bounds".to_owned())
+    })?;
+    destination.copy_from_slice(&value.to_le_bytes());
+    Ok(())
+}
+
+fn method_table(data: &[u8]) -> Result<(usize, usize)> {
+    if read_u32(data, 0)? != MAGIC {
+        return Err(MethodIndexError::NotMetadata);
+    }
+    let version = read_u32(data, 4)?;
+    if version != RAW_VERSION_24 {
+        return Err(MethodIndexError::UnsupportedVersion(version));
+    }
+    let offset = read_u32(data, HDR_METHODS)? as usize;
+    let size = read_u32(data, HDR_METHODS + 4)? as usize;
+    bytes(data, offset, size)?;
+    if !size.is_multiple_of(V24_1_METHOD_STRIDE) {
+        return Err(MethodIndexError::Malformed(format!(
+            "method table size 0x{size:x} is not divisible by v24.1 stride 0x{V24_1_METHOD_STRIDE:x}"
+        )));
+    }
+    Ok((offset, size / V24_1_METHOD_STRIDE))
+}
+
+fn method_indices(data: &[u8]) -> Result<(usize, Vec<Option<u32>>)> {
+    let (offset, count) = method_table(data)?;
+    let mut indices = Vec::with_capacity(count);
+    for method in 0..count {
+        let value = read_i32(
+            data,
+            offset + method * V24_1_METHOD_STRIDE + V24_1_METHOD_INDEX_OFFSET,
+        )?;
+        indices.push((value >= 0).then_some(value as u32));
+    }
+    Ok((offset, indices))
+}
+
+fn is_complete_permutation(indices: &[Option<u32>]) -> bool {
+    let active_count = indices.iter().filter(|value| value.is_some()).count();
+    if active_count == 0 || active_count > u32::MAX as usize {
+        return false;
+    }
+    let mut seen = vec![false; active_count];
+    for value in indices.iter().flatten().copied() {
+        let Ok(index) = usize::try_from(value) else {
+            return false;
+        };
+        if index >= active_count || seen[index] {
+            return false;
+        }
+        seen[index] = true;
+    }
+    seen.into_iter().all(|value| value)
+}
+
+fn permutation_key(seed: u32, count: u32) -> Result<u32> {
+    if count < 2 {
+        return Err(MethodIndexError::Validation(
+            "method-index permutation requires at least two active methods".to_owned(),
+        ));
+    }
+    if count > u32::MAX / 2 {
+        return Err(MethodIndexError::Validation(
+            "active method count is too large for the permutation mirror".to_owned(),
+        ));
+    }
+    let half = count / 2;
+    if half == 0 {
+        return Err(MethodIndexError::Validation(
+            "method-index permutation has a zero divisor".to_owned(),
+        ));
+    }
+    Ok(seed % half + count / 4)
+}
+
+fn permutation_round(mut value: u32, count: u32, key: u32) -> u32 {
+    let mirror = count * 2 - 1;
+    if value & 1 != 0 {
+        value = mirror - value;
+    }
+    value >>= 1;
+    if value >= count {
+        value = mirror - value;
+    }
+    let adjusted = i64::from(value) - i64::from(key);
+    if adjusted < 0 {
+        (adjusted + i64::from(count)) as u32
+    } else {
+        adjusted as u32
+    }
+}
+
+fn transform_index(mut value: u32, count: u32, seed: u32) -> Result<u32> {
+    let key = permutation_key(seed, count)?;
+    for _ in 0..5 {
+        value = permutation_round(value, count, key);
+    }
+    Ok(value)
+}
+
+fn transformed_values(indices: &[Option<u32>], seed: u32) -> Result<Vec<Option<u32>>> {
+    let active_count = indices.iter().filter(|value| value.is_some()).count();
+    let count = u32::try_from(active_count)
+        .map_err(|_| MethodIndexError::Validation("active method count exceeds u32".to_owned()))?;
+    indices
+        .iter()
+        .map(|value| {
+            value
+                .map(|value| transform_index(value, count, seed))
+                .transpose()
+        })
+        .collect()
+}
+
+fn missing_values(indices: &[Option<u32>]) -> Option<Vec<u32>> {
+    let active_count = indices.iter().filter(|value| value.is_some()).count();
+    let mut seen = vec![false; active_count];
+    for value in indices.iter().flatten().copied() {
+        let index = usize::try_from(value).ok()?;
+        if index >= active_count {
+            return None;
+        }
+        seen[index] = true;
+    }
+    Some(
+        seen.into_iter()
+            .enumerate()
+            .filter_map(|(index, present)| (!present).then_some(index as u32))
+            .collect(),
+    )
+}
+
+fn find_exception_table(
+    module: &[u8],
+    count: u32,
+    missing: &[u32],
+) -> Option<[u32; EXCEPTION_COUNT]> {
+    if missing.len() != EXCEPTION_COUNT || count == 0 {
+        return None;
+    }
+    let mut wanted = vec![false; count as usize];
+    for &value in missing {
+        let slot = wanted.get_mut(value as usize)?;
+        *slot = true;
+    }
+    let table_bytes = EXCEPTION_COUNT * 4;
+    for offset in (8..=module.len().checked_sub(table_bytes)?).step_by(4) {
+        if read_u32(module, offset - 8).ok()? != V24_1_SELECTOR
+            || read_u32(module, offset - 4).ok()? != count - 1
+        {
+            continue;
+        }
+        let mut values = [0_u32; EXCEPTION_COUNT];
+        let mut seen = vec![false; count as usize];
+        let mut matches = true;
+        for (index, slot) in values.iter_mut().enumerate() {
+            let value = read_u32(module, offset + index * 4).ok()?;
+            let Some(is_wanted) = wanted.get(value as usize) else {
+                matches = false;
+                break;
+            };
+            if !*is_wanted || seen[value as usize] {
+                matches = false;
+                break;
+            }
+            seen[value as usize] = true;
+            *slot = value;
+        }
+        if matches {
+            return Some(values);
+        }
+    }
+    None
+}
+
+fn profile_candidates(module: &[u8], indices: &[Option<u32>]) -> Result<Vec<Profile>> {
+    let active_count = indices.iter().filter(|value| value.is_some()).count();
+    let count = u32::try_from(active_count)
+        .map_err(|_| MethodIndexError::Validation("active method count exceeds u32".to_owned()))?;
+    if count <= EXCEPTION_COUNT as u32 {
+        return Err(MethodIndexError::Validation(format!(
+            "active method count {count} is too small for the v24.1 exception table"
+        )));
+    }
+
+    let mut profiles = Vec::new();
+    for offset in (0..module.len().saturating_sub(8)).step_by(4) {
+        let Ok(version) = read_u32(module, offset + 4) else {
+            continue;
+        };
+        if version != RAW_VERSION_24 {
+            continue;
+        }
+        let seed = read_u32(module, offset)?;
+        let transformed = transformed_values(indices, seed)?;
+        let Some(missing) = missing_values(&transformed) else {
+            continue;
+        };
+        let Some(exception_values) = find_exception_table(module, count, &missing) else {
+            continue;
+        };
+        let mut candidate = transformed;
+        let mut exception = exception_values.iter().copied();
+        for value in candidate.iter_mut().flatten() {
+            if let Some(replacement) = exception.next() {
+                *value = replacement;
+            } else {
+                break;
+            }
+        }
+        if exception.next().is_none() && is_complete_permutation(&candidate) {
+            profiles.push(Profile {
+                seed,
+                exception_values,
+            });
+        }
+    }
+    profiles.sort_by_key(|profile| profile.seed);
+    profiles.dedup();
+    Ok(profiles)
+}
+
+/// Restore the v24.1 `methodIndex` permutation using the decoded CrackProof
+/// module `0x0C` that accompanied the protected library.
+///
+/// The profile is accepted only when the module supplies a seed plus a
+/// 256-entry exception table that turns the restored non-negative indices into
+/// the exact permutation `0..active_method_count`. This makes a wrong module or
+/// incompatible v24 sub-layout fail without mutating the metadata.
+pub fn restore_method_indices_v24_1(
+    data: &[u8],
+    module_0c: &[u8],
+) -> Result<(Vec<u8>, MethodIndexReport)> {
+    let (method_offset, indices) = method_indices(data)?;
+    let active_count = indices.iter().filter(|value| value.is_some()).count();
+    if is_complete_permutation(&indices) {
+        return Ok((
+            data.to_vec(),
+            MethodIndexReport {
+                version: RAW_VERSION_24,
+                methods: indices.len(),
+                active_methods: active_count,
+                changed_indices: 0,
+                exception_count: 0,
+                seed: "clean".to_owned(),
+            },
+        ));
+    }
+
+    let profiles = profile_candidates(module_0c, &indices)?;
+    let profile = match profiles.as_slice() {
+        [] => return Err(MethodIndexError::ProfileNotFound),
+        [profile] => profile,
+        _ => return Err(MethodIndexError::AmbiguousProfile),
+    };
+
+    let mut restored = transformed_values(&indices, profile.seed)?;
+    let mut exception = profile.exception_values.iter().copied();
+    for value in restored.iter_mut().flatten() {
+        if let Some(replacement) = exception.next() {
+            *value = replacement;
+        } else {
+            break;
+        }
+    }
+    if exception.next().is_some() {
+        return Err(MethodIndexError::Validation(
+            "metadata has fewer active methods than the exception table".to_owned(),
+        ));
+    }
+    if !is_complete_permutation(&restored) {
+        return Err(MethodIndexError::Validation(
+            "restored methodIndex values are not a complete permutation".to_owned(),
+        ));
+    }
+
+    let mut output = data.to_vec();
+    let mut changed_indices = 0_usize;
+    for (method, value) in restored.iter().enumerate() {
+        let Some(value) = value else {
+            continue;
+        };
+        let offset = method_offset + method * V24_1_METHOD_STRIDE + V24_1_METHOD_INDEX_OFFSET;
+        let old = read_i32(data, offset)?;
+        let new = i32::try_from(*value).map_err(|_| {
+            MethodIndexError::Validation("restored methodIndex exceeds i32".to_owned())
+        })?;
+        if old != new {
+            write_i32(&mut output, offset, new)?;
+            changed_indices += 1;
+        }
+    }
+
+    Ok((
+        output,
+        MethodIndexReport {
+            version: RAW_VERSION_24,
+            methods: indices.len(),
+            active_methods: active_count,
+            changed_indices,
+            exception_count: EXCEPTION_COUNT,
+            seed: format!("0x{:08X}", profile.seed),
+        },
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn inverse_map(count: u32, seed: u32) -> Vec<u32> {
+        let mut inverse = vec![u32::MAX; count as usize];
+        for value in 0..count {
+            let transformed = transform_index(value, count, seed).unwrap();
+            inverse[transformed as usize] = value;
+        }
+        assert!(inverse.iter().all(|value| *value != u32::MAX));
+        inverse
+    }
+
+    fn fixture() -> (Vec<u8>, Vec<u8>) {
+        let active_count = 512_u32;
+        let seed = 0x7770_0dcc;
+        let inverse = inverse_map(active_count, seed);
+        let header_size = 0x100usize;
+        let method_size = active_count as usize * V24_1_METHOD_STRIDE;
+        let mut metadata = vec![0_u8; header_size + method_size];
+        metadata[0..4].copy_from_slice(&MAGIC.to_le_bytes());
+        metadata[4..8].copy_from_slice(&RAW_VERSION_24.to_le_bytes());
+        metadata[HDR_METHODS..HDR_METHODS + 4].copy_from_slice(&(header_size as u32).to_le_bytes());
+        metadata[HDR_METHODS + 4..HDR_METHODS + 8]
+            .copy_from_slice(&(method_size as u32).to_le_bytes());
+
+        // Before the exception patch the first half duplicates the second half,
+        // leaving 0..255 missing. The module's 256-entry table fills exactly
+        // those first active methods after the five-round transform.
+        for method in 0..active_count as usize {
+            let transformed = 256 + (method % 256) as u32;
+            let protected = inverse[transformed as usize];
+            let offset = header_size + method * V24_1_METHOD_STRIDE + V24_1_METHOD_INDEX_OFFSET;
+            metadata[offset..offset + 4].copy_from_slice(&(protected as i32).to_le_bytes());
+        }
+
+        let mut module = vec![0_u8; 0x1000];
+        module[0x100..0x104].copy_from_slice(&seed.to_le_bytes());
+        module[0x104..0x108].copy_from_slice(&RAW_VERSION_24.to_le_bytes());
+        module[0x3f8..0x3fc].copy_from_slice(&V24_1_SELECTOR.to_le_bytes());
+        module[0x3fc..0x400].copy_from_slice(&(active_count - 1).to_le_bytes());
+        for value in 0..EXCEPTION_COUNT as u32 {
+            let offset = 0x400 + value as usize * 4;
+            module[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
+        }
+        (metadata, module)
+    }
+
+    #[test]
+    fn restores_v24_1_method_index_permutation() {
+        let (metadata, module) = fixture();
+        let (restored, report) = restore_method_indices_v24_1(&metadata, &module).unwrap();
+        assert_eq!(report.active_methods, 512);
+        assert_eq!(report.exception_count, 256);
+        assert_eq!(report.seed, "0x77700DCC");
+        let (offset, indices) = method_indices(&restored).unwrap();
+        assert_eq!(offset, 0x100);
+        assert!(is_complete_permutation(&indices));
+        for (method, value) in indices.into_iter().enumerate() {
+            assert_eq!(value, Some(method as u32));
+        }
+    }
+
+    #[test]
+    fn clean_v24_1_metadata_is_idempotent() {
+        let (metadata, module) = fixture();
+        let (restored, _) = restore_method_indices_v24_1(&metadata, &module).unwrap();
+        let (again, report) = restore_method_indices_v24_1(&restored, &module).unwrap();
+        assert_eq!(again, restored);
+        assert_eq!(report.changed_indices, 0);
+        assert_eq!(report.seed, "clean");
+    }
+
+    #[test]
+    fn rejects_unrelated_module() {
+        let (metadata, _) = fixture();
+        let error = restore_method_indices_v24_1(&metadata, &[0_u8; 0x1000]).unwrap_err();
+        assert_eq!(error, MethodIndexError::ProfileNotFound);
+    }
+}

senbei-metadata/src/android/mod.rs

@@ -2,9 +2,11 @@
 
 mod embedded;
 mod keystream;
+mod method_indices;
 mod method_tokens;
 
 pub use embedded::{embedded_metadata_size, extract_embedded_metadata};
+pub use method_indices::{MethodIndexError, MethodIndexReport, restore_method_indices_v24_1};
 pub use method_tokens::{
     DEFAULT_METHOD_TOKEN_SEED, Error, ImageKeyDiscovery, Report, SeedDiscoveryReport,
     discover_method_token_seeds, restore_method_tokens,