Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs(archive): record the comparison against the real CFW archives

Lakrdbd10ed28300
diff --git a/research/archive_extraction_contracts.md b/research/archive_extraction_contracts.md
index 97a2e1bb..58707ac7 100644
--- a/research/archive_extraction_contracts.md
+++ b/research/archive_extraction_contracts.md
@@ -106,6 +106,37 @@ written. That is **stronger** than the flag, which only asks whether a stored
path begins with a slash; the check asks where the path actually lands. There
is a test with a hand-built `../escaped` member, checksum and all.
+## Measured against the real CFW archives
+
+`scripts/resources/cfw_input.tar.zst` and `cfw_jb_input.tar.zst`, unpacked by
+GNU tar with the flags `cfw_install*.sh` passes and by `vphone-archive`, then
+compared with `vphone-archive fingerprint`. Same entry counts, and **one
+difference each, of the same kind**:
+
+```
+cfw_input/jb: mtime 1790104701863394309 vs 1772464479000000000
+cfw_jb_input/basebin: mtime 1790104702288353311 vs 1772341940000000000
+```
+
+A directory's mtime. `vphone-archive` restores the value recorded in the
+archive (2026-03-03); GNU tar leaves it at the moment of extraction
+(2026-09-23). Checked with and without `--no-overwrite-dir`: GNU tar behaves
+the same either way, so the flag is not what causes it — GNU tar simply is not
+restoring these directories' mtimes, and libarchive's deferred fixup is.
+
+Everything else matches: modes, numeric uid/gid, symlink targets, hardlink
+grouping, xattrs, ACLs, occupancy and content digests.
+
+**So the switch is a behaviour change, in the direction of being more faithful
+to the archive.** A directory's mtime on an iOS volume should be cosmetic, but
+"should be" is not "is", and this has not been through a boot. It is the one
+thing to look at on the first real install.
+
+Not covered here: ownership restoration, which only happens as root. The
+comparison above ran unprivileged, so `ARCHIVE_EXTRACT_OWNER` never came into
+play. That is the remaining gap before scenario A can be switched with
+confidence.
+
## Known wart
libarchive leaves zero-byte `tar.XXXXXXXX` files in the process's **working
diff --git a/research/intg_update_status.md b/research/intg_update_status.md
index aa104c67..9c9395b8 100644
--- a/research/intg_update_status.md
+++ b/research/intg_update_status.md
@@ -17,6 +17,7 @@
| 4 | `custom-firmware-kit` → `cfw-kit/` | done, as-is |
| 5a | admission gates 1–3 (`make check-aux`) | done; fails on bundled ldid, as designed |
| 5b | `VPhoneArchive` + `vphone-archive` | library and binary done; **call sites not switched** |
+| 5c | `vphone-archive fingerprint` (the plan's tree-fingerprint) | done; already found and drove a hardlink fix |
Tests: `VPhoneCoreTests` 152/152, `VPhoneArchiveTests` 13/13. The 14
`FirmwarePatcherTests` failures are pre-existing — they need
@@ -42,12 +43,24 @@ Nothing below could be done without root or a real guest.
## Next, in order
1. **Switch the archive call sites.** `vphone-archive` is built, bundled and
- tested, and nothing calls it yet. The IPSW unzip in `fw_prepare.sh` and the
- host-side temp extractions are low risk. The `$TAR` calls in
- `cfw_install*.sh` are not: they write to a mounted guest volume as root,
- and want the tree-fingerprint comparison (uid/gid, ACLs, xattrs, hardlink
- grouping, `st_blocks`) against GNU tar before being switched. See
- `research/archive_extraction_contracts.md`.
+ tested, and nothing calls it yet.
+
+ The comparison the plan asks for has been run, on the real
+ `cfw_input.tar.zst` and `cfw_jb_input.tar.zst`: everything matches GNU tar
+ except **one directory mtime per archive**, where `vphone-archive` restores
+ the archive's recorded value and GNU tar leaves the extraction time. More
+ faithful, but still a behaviour change, and it has not been through a boot.
+
+ What is still untested is **ownership restoration**, which only happens as
+ root — the comparison ran unprivileged, so `ARCHIVE_EXTRACT_OWNER` never
+ came into play. That is the gap to close before the `$TAR` calls in
+ `cfw_install*.sh` are switched, since those write to a mounted guest volume
+ as root and getting ownership wrong there produces a guest that does not
+ boot. The IPSW unzip in `fw_prepare.sh` and the host-side temp extractions
+ have neither problem and can go first.
+
+ Re-run it yourself with:
+ `vphone-archive fingerprint <gtar-output> <vphone-output>`
2. **`VPhoneSign`**, which is what clears the last two admission-gate
failures. `ldid` is the only binary we ship that is already
non-self-contained. The plan's §3.11 has the measurements; the