Initial Commit

docs/architecture.md

@@ -0,0 +1,56 @@
+# Architecture
+
+`format/` holds reusable binary-format parsing; `patch/` holds the patch
+logic. Patch modules depend on `format/`, `android/` and `util/`, never on
+each other.
+
+## format/
+
+All reads are bounds-checked; malformed input returns an error instead of
+panicking.
+
+- **bytes** — little/big-endian integer reads and writes, slicing,
+  power-of-two alignment.
+- **pe** — PE32+ (x86-64) reader. Validates headers and section ranges;
+  provides section lookup, RVA→offset mapping, data directories, export
+  lookup, and a stricter image-bound check used by ACE and HoYoKProtect.
+  Patches add their own layout checks on top.
+- **elf** — ARM64 shared-object reader. Validates headers and
+  section/segment ranges; provides sections, segments, `.dynsym` symbols,
+  RELA entries, and address→file-offset mapping through `PT_LOAD`.
+- **dex** — field access, checksum recompute (SHA-1 + Adler-32), string
+  and `const-string` lookup, and `append_string`, which inserts a
+  `string_data_item` before the annotations section and relocates every
+  later offset, map entry and header field.
+- **unity** — UnityFS v6 bundles and serialized-file `TextAsset`s.
+  `rebuild` re-encodes only changed blocks and re-verifies the result.
+  `replace_script` and `Bundle::replace_node` resize a TextAsset or
+  bundle node, rewriting object offsets, the header size and the node
+  directory. Blocks may be uncompressed or LZ4.
+
+## patch/
+
+`region` maps the Windows client's `ChannelConfig`
+(`ChannelName`/`BundleIdentifier`) to one of six PC regions
+(CN/GLB/JP/KR/TW/SEA) with its SDK key and environment id.
+
+Single-file Windows writes (RSA, ACE, HoYoKProtect) use
+`util::replace::verified`: write a sibling temporary file, flush, read it
+back, re-check the target for concurrent changes, persist, re-verify. The
+dispatch patch replaces its three files together and rolls back on
+failure.
+
+## android/
+
+`toolchain` finds Build-Tools and Java 17+, or downloads them (SHA-256
+verified). `sign::signed_patch` runs a patch's repack, which drops the old
+signature entries, into a temporary APK, then zip-aligns it
+(`-P 16 -f 4`), signs and verifies it with `apksigner`, and writes
+`<name>_patched.apk`.
+
+## cli/
+
+`interactive` is the terminal menu (no arguments). `args` parses
+`<command> --flag value` (or `--flag=value`) and validates the whole
+command line before running the patch, then reports via exit code and
+optional JSON.