reverse-skills-max/vendor-new/apk-reverse/docs/tool-verification/EXTENSION-split-apk.md

# Extension verification — split APK / App Bundle sets

Covers the pass that added split-set support to `scripts/repack.py` and wrote
`references/split-apk.md`. Strength labels as defined in this directory's README:
**observed** (exact command + output reproduced here), **inferred** (follows from observed
facts, step not executed), **unverified** (assumed or externally reported, not independently
confirmed).

Reference environment for this pass: Windows 11 host, Python 3.14.0, Java 17.0.4.1
(`keytool` NOT on PATH — it was passed explicitly as
`<jdk>/bin/keytool.exe`), `apksigner` 0.9 run from `lib/apksigner.jar`, `zipalign.exe` from the
same build-tools layout. **No `uber-apk-signer` anywhere on the machine**, which is the condition
that made the signing-route fallback a requirement rather than a nicety. Target: one rooted physical
Android 11 (API 30) arm64-v8a device, written `<DEVICE>` throughout.

All package names, application directory names and file names are replaced with placeholders
(`<PKG>`, `<SET>`, `<SET_A>`, `<SET_B>`). The measurements, byte counts, entry counts and outputs
are unchanged; only the identifiers are.

Fixtures: two **real split sets already installed on the device**, copied out read-only
(`adb pull` of the system directory; nothing on the device was uninstalled, replaced or modified).
They were chosen because one exercises each side of the merge/resign decision:

| | Members | Shape |
|---|---|---|
| Set A | 8 | base + 7 density splits, every density split carrying its own resources |
| Set B | 9 | base + 1 ABI split (native libraries only) + 7 density splits that carry a placeholder table and nothing else |

Neither set is third-party: `pm list packages -3` reported **zero** split sets among ~40 installed
third-party packages, while four preinstalled Google components were split. That distribution is
recorded because "pick a third-party split app off the device" is not reliably available.

## 1. Reading a set: what the members actually contain — observed

`pm path <PKG>` on each package returned one line per member (8 and 9 lines respectively), which is
how the targets were identified in the first place:

```
$ adb shell 'pm path <PKG>'
package:/system/priv-app/<DIR>/<SET>.apk
package:/system/priv-app/<DIR>/<SET>-arm64_v8a.apk
package:/system/priv-app/<DIR>/<SET>-hdpi.apk
... (one line per member)
```

`scripts/repack.py --split-mode analyze` over set A (identifiers replaced):

```
== split set: 8 apk(s), 6629510 bytes total
  density    <SET_A>-hdpi.apk                        49623 B  split=config.hdpi        res=39 entries arsc=9392
  density    <SET_A>-ldpi.apk                        45501 B  split=config.ldpi        res=39 entries arsc=9392
  density    <SET_A>-mdpi.apk                        45501 B  split=config.mdpi        res=39 entries arsc=9392
  density    <SET_A>-tvdpi.apk                       74227 B  split=config.tvdpi       res=78 entries arsc=15124
  density    <SET_A>-xhdpi.apk                       53754 B  split=config.xhdpi       res=39 entries arsc=9432
  density    <SET_A>-xxhdpi.apk                      57878 B  split=config.xxhdpi      res=39 entries arsc=10324
  density    <SET_A>-xxxhdpi.apk                     57876 B  split=config.xxxhdpi     res=39 entries arsc=11200
  base       <SET_A>.apk                           6245150 B  split=-                  dex=classes.dex res=581 entries arsc=1924488 assets=1
[plan] base = <SET_A>.apk (package=<PKG>)
[plan] MERGE BLOCKED: merging is not legal for 7 of 7 splits: config.hdpi, config.ldpi, config.mdpi,
config.tvdpi, config.xhdpi, config.xxhdpi, config.xxxhdpi carry their own resources, and folding those in
means merging resources.arsc (a resource-compiler job). Use --split-mode resign, or pass
--drop-split-resources to accept losing exactly those resources
[plan] resign = legal: one keystore for all 8 members, install the set with
[result] analyze only: nothing was written. Pass --split-mode merge|resign|auto to act on this set.
```

And over set B:

```
== split set: 9 apk(s), 1411272 bytes total
  abi        <SET_B>-arm64_v8a.apk                  255861 B  split=config.arm64_v8a   libs=arm64-v8a
  density    <SET_B>-hdpi.apk                        16797 B  split=config.hdpi        arsc=40
  ... (6 more density members, all 16797 B, all arsc=40)
  base       <SET_B>.apk                           1037832 B  split=-                  dex=classes.dex res=2 entries arsc=71316 assets=1
[plan] base = <SET_B>.apk (package=<PKG>)
[plan] note: every non-base split carries only code/native libraries, so a merged single APK is legal
[plan] note: config.arm64_v8a provides libs for arm64-v8a -- keep only the ABIs the target device runs,
selected with --abi
[plan] merge  = legal: 8 member(s) fold into the base
```

Four facts this pass established with those numbers, and that the reference file now depends on:

- **The ABI member carries no `resources.arsc` at all** (set B: `libs=arm64-v8a`, no arsc column).
  Its two `.so` files are the whole payload. This is the member that folds cleanly.
- **Each density member carries its own table and its own `res/` entries** (set A: 39-78 entries,
  9.0-15.1 KB tables). `resources.arsc` is per member, not per set — the base's 1.88 MB table does
  not contain the density variants.
- **A `resources.arsc` can be a 40-byte placeholder.** All seven density members of set B carry
  `arsc=40` and zero `res/` entries, while still being legally required to carry a table. A
  "has an arsc → owns resources" test would have blocked a merge that is entirely legal here, which
  is why the script's test is *`res/` entries or a table over 1 KB*.
- **Base and split share one package name**, read from the binary AXML `package` attribute of every
  member, and the base is identifiable as the member whose manifest carries **no `split` attribute**
  (set A: `split=-`).

## 2. Unified re-signing — observed

`--split-mode resign` over set A with one keystore, run through the new `apksigner` route:

```
$ python skills/apk-reverse/scripts/repack.py --split-dir <SET_A>/ --split-mode resign \
    --split-out-dir signed_set/ --ks key.jks \
    --keytool <jdk>/bin/keytool.exe --apksigner <build-tools>/lib/apksigner.jar \
    --zipalign <build-tools>/zipalign.exe
[resign] signer route: apksigner
[resign] <SET_A>-hdpi.apk -> signed_set/<SET_A>-hdpi.apk (41298 bytes)
[resign] <SET_A>-ldpi.apk -> signed_set/<SET_A>-ldpi.apk (37202 bytes)
[resign] <SET_A>-mdpi.apk -> signed_set/<SET_A>-mdpi.apk (37202 bytes)
[resign] <SET_A>-tvdpi.apk -> signed_set/<SET_A>-tvdpi.apk (61642 bytes)
[resign] <SET_A>-xhdpi.apk -> signed_set/<SET_A>-xhdpi.apk (41337 bytes)
[resign] <SET_A>-xxhdpi.apk -> signed_set/<SET_A>-xxhdpi.apk (49563 bytes)
[resign] <SET_A>-xxxhdpi.apk -> signed_set/<SET_A>-xxxhdpi.apk (49577 bytes)
[resign] <SET_A>.apk -> signed_set/<SET_A>.apk (4172089 bytes)
[result] OK: 8 members, one certificate (sha256 1eb31d9c…2c44)
```

Every member's independent `apksigner verify --print-certs --verbose --min-sdk-version 21
--max-sdk-version 34` returned `Verifies` with:

```
Verified using v1 scheme (JAR signing): true
Verified using v2 scheme (APK Signature Scheme v2): true
Verified using v3 scheme (APK Signature Scheme v3): true
Signer #1 certificate DN: CN=apkreverse, OU=dev, O=dev, L=NA, ST=NA, C=NA
Signer #1 certificate SHA-256 digest: 1eb31d9c9c81104367a66a0201125aa91d28a6a09eb1dcb5029c36bc0bde2c44
```

All eight printed the **same** SHA-256 — that, not per-file `Verifies`, is the acceptance
criterion for a set, and it is the check the run performs explicitly.

**The signing-route fallback is the load-bearing part of this section.** With no
`uber-apk-signer` on the machine, the pre-change script could not sign anything at all: it exited
with `signer jar not found`, naming a jar the user never had. The new `--signer auto` resolves to
`zipalign -p -f 4` + `apksigner sign --v1 --v2 --v3`, which produced the output above. `--apksigner`
accepts `apksigner.bat` (verified: `rc=0`, `--version` → `0.9`), a `lib/apksigner.jar` value run
through `java -jar` (verified: same), and the extensionless shell wrapper (which is a shell script
and does not run on Windows — that is a fact about the wrapper, not about this script).

### The signing route this pass actually used — and why it had to change

`uber-apk-signer` is `repack.py`'s default signer, and it is **not installed on this machine**
(no `uber-apk-signer.jar`, `APK_SIGNER_JAR` unset). Before this change that made every signed build
impossible here: the script exited with `signer jar not found` and named a jar the user never had.
What actually ran in all four measured routes:

| Item | Value used |
|---|---|
| signer | `zipalign.exe` + `apksigner`, the latter run from `lib/apksigner.jar` through `java -jar` |
| `--apksigner` | `<build-tools>/lib/apksigner.jar`. A `.bat` value was also tested and works (`rc=0`, `--version` → `0.9`); the extensionless wrapper in the same layout is a shell script and does not run on Windows |
| `--zipalign` | `<build-tools>/zipalign.exe` |
| `--keytool` | `<jdk>/bin/keytool.exe` — **not on PATH**, and signing aborts without a way to create the keystore, so this flag is mandatory on such a machine |
| scheme flags | `--v1-signing-enabled true --v2-signing-enabled true --v3-signing-enabled true` |

Alignment is handled **per member, and in this order**:

1. the script writes the archive itself, keeping `AndroidManifest.xml` and `resources.arsc` STORED
   and 4-byte-aligning `resources.arsc` plus uncompressed `lib/**`, then re-reads the file and
   prints the gate (`== alignment gate: resources.arsc STORED and 4-byte aligned (OK)`);
2. `zipalign -p -f 4` runs over that output (`-p` adds the page alignment the loader wants for
   `extractNativeLibs="false"` libraries);
3. `apksigner sign` runs **last** — it adds signature entries without reshuffling the archive,
   whereas a `jarsigner`-style rewrite after aligning destroys the alignment and the install is then
   refused with `[-124]`.

For a split set this is repeated for every member, which is why `resign_split_set()` de-signs and
re-aligns each member individually before signing it: a single member whose `resources.arsc` is
compressed or unaligned is refused by the installer on its own, and the resulting error names that
member's package rather than the set.

## 3. Merging — observed, including the refusal

Set B, where every non-base member is code or native libraries:

```
$ python skills/apk-reverse/scripts/repack.py --split-dir <SET_B>/ --split-mode merge \
    --out merged.apk --abi arm64-v8a --ks key.jks --apksigner <...>/lib/apksigner.jar
[merge] + lib/arm64-v8a/lib<name>_compat_libc++.so  (18944 bytes <- <SET_B>-arm64_v8a.apk)
[merge] + lib/arm64-v8a/lib<name>utilsjni.so       (206680 bytes <- <SET_B>-arm64_v8a.apk)
[merge] folded: dex=0 libs=2 assets=0 conflicts=0
[merge] DROPPED 7 entry/ies. This is a DOWNGRADED build -- say so when you deliver it:
[zip]   classes.dex 872160 bytes method=8 crc=<...>
[zip]   resources.arsc                           STORED                 offset=0x581fc    aligned
== alignment gate: resources.arsc STORED and 4-byte aligned (OK)
[sign:zipalign] rc=0
[sign:apksigner] rc=0
[out] merged.apk (603824 bytes)
[verify:apksigner] rc=0  Verifies / v1 true / v2 true / v3 true
[result] OK
```

`dex=0` is correct rather than suspicious: the base owns `classes.dex` and no member of this set
carries a second one, so no renumbering was needed. The `libs=2` fold is the whole point — a
one-file APK that now carries the native libraries the ABI member used to provide separately.

Set A, where merging is **not** legal, refuses rather than producing a broken artifact:

```
$ python skills/apk-reverse/scripts/repack.py --split-dir <SET_A>/ --split-mode merge \
    --out merged.apk --no-sign
error: refusing to merge <SET_A>-hdpi.apk -- it carries its own resources (39 res entries,
arsc=9392 bytes).
  Folding it in would require merging resources.arsc, which this script does not do.
  Either use --split-mode resign (recommended for a resource split), or pass
  --drop-split-resources to accept that the resources it owns are lost.
exit code 1
```

This is the enforcement the reference file promises: the refusal happens **before** any output is
written (the `--out` path does not exist afterwards), and the escape hatch is explicit, printed, and
required. The mechanism is **observed**; whether a build produced through that hatch merely loses
its density variants or misrenders is **inferred** — it was not exercised, because the only sets
available were a legal-merge set and a refused set, and manufacturing the third case would have
meant hand-editing a resource table.

## 4. Single-APK behaviour is unchanged — observed

Both pre-existing paths were re-run through the same new signing route, on an unmodified sample
APK from `tools/_work/bench/apks/`:

- **zero-change roundtrip** (`--apk … --out … --ks …`, no `--dexdir`): the run dropped exactly the
  three original signature artifacts (`META-INF/CERT.RSA`, `META-INF/CERT.SF`, `META-INF/MANIFEST.MF`),
  wrote a 60964-byte unsigned archive, signed to 70647 bytes, reported `== alignment gate:
  resources.arsc STORED and 4-byte aligned (OK)` and `[result] OK` with v1/v2/v3 all `true`;
- **explicit dex replacement** (`--dexdir` supplying the same `classes.dex`, 5528 bytes):
  `[repl] classes.dex<-…/classes.dex`, the entry re-added at the same size and CRC, alignment gate
  OK, `[result] OK`.

Both were run with `--no-sign` as well, which exits 0 and reports `UNSIGNED (--no-sign)`. `--help`
works, exits 0, and carries the split examples and the route-decision text; `--split-mode analyze`
exits 0; a merge refusal exits 1; a failed verification would exit 2.

The output fix worth recording: `AndroidManifest.xml` used to be printed as `NOT ALIGNED` in the zip
layout (it only has to be STORED, unlike `resources.arsc`). It now prints `-` for entries that need
no alignment, so the report cannot be misread as a failing gate.

## 5. Install and launch on the device — **unverified**

**Not executed.** The device was held by a concurrent device experiment for the whole window
available to this pass (`python tools/_work/devlock.py status` reported the lock held by another
teammate for 1417 s, note naming its own install/launch and Frida work), and the lead's decision was
to ship this gap labelled rather than wait for it. Heavy device work must be serialised
(`tools/_work/ENV.md`), so the honest label for everything below is **unverified** — a claim about
installability that was never installed is exactly the failure `references/verification.md` exists
to prevent.

Prepared, and not run — the sequence is the one in `references/split-apk.md` §4, against the
re-signed renamed fixture:

```
adb install-multiple -r <signed_set>/*.apk
adb shell cmd package resolve-activity --brief <PKG>
adb shell am start -n <PKG>/<launcher-activity>
adb shell 'dumpsys activity activities | grep -m2 ResumedActivity'
adb exec-out screencap -p > launch.png
```

What the pass *did* establish without a device, and what each fact does not cover:

- **The artifacts are installable in principle, not in fact.** All eight members of the re-signed set
  verify with v1/v2/v3 `true` and one identical SHA-256 (§2), and the merged single APK verifies the
  same way (§3, §4). Uniformity of the certificate and a passing `apksigner verify` are necessary
  conditions for a set install; the platform installer accepting the set is the step that was not run.
- **The negative control was not run either.** The signature-conflict text quoted in
  `references/split-apk.md` §6 (a pulled set reinstalled under its own package name) is the
  platform's documented shape and the shape a competing tool reports; no captured output from
  `<DEVICE>` backs it.
- Every statement about **what the archives contain** — split roles, arsc ownership, the 40-byte
  placeholder tables, the fold set, the refusal — is **observed** and device-independent.
- Every statement about **what the package manager does with them** is **inferred**.

**What closing it needs:** one device window that is not shared, then the sequence above (about three
minutes of device time). The two things most likely to show up there, and already accounted for in
the script: an OEM installer interception on `adb install-multiple` (there is a root
`pm install-multiple` path for it) and a launcher activity that needs resolving rather than guessing.

## 6. Maintenance gate — observed

Run at the repository root with the change in place:

```
$ python check_repo.py
== result: 1 problem(s)
  - skills/apk-reverse/scripts/dex_strpatch.py --help crashed:

$ python check_refs.py
== section references: 242 reachable ==
== result: 0 dangling, 0 warning(s)
```

`check_refs.py` is clean, which covers the three `references/repack-and-sign.md` §-references the new
file adds, and `check_repo.py` reports one problem in a **different** file belonging to a different
task; `repack.py` parses and answers `--help` with exit 0.

`check_repo.py` requires every `references/*.md` to be named in `SKILL.md` or the root `README.md`,
and this task was not permitted to edit either, so the reachability step was pre-checked in a **copy**
of the repository (`tools/_work/repo-check/`, workbench only, never in the tree) by running the gate
twice on one snapshot with the index lines as the only variable:

```
without the index lines:  == result: 5 problem(s)   ... UNLISTED references/split-apk.md
with the index lines:     == result: 4 problem(s)   ... (the UNLISTED line is gone)
```

The new file therefore contributes nothing to the gate once listed. The listing itself was added to
`README.md` by the lead, and the run quoted above is the result.

## 7. Deliberately not done — and what stays unverified

- **No `.aab` was processed.** A bundle input would need `bundletool` (absent here, and it is the
  tool that owns the correct resource merge). This pass only ever handled maps of an *installed* set.
- **No fixture was hand-built with `aapt2`/`d8`.** Those became available on this machine only after
  the fixtures were chosen (a build-tools archive was unpacked late in the round), and the two real
  sets already exercised both branches of the decision. Building a minimal split set by hand remains
  the cheapest way to reproduce this topic on a machine with no installed bundle and no device, and
  the route is **inferred** — it was not attempted here. It would not change the resource-merge
  boundary either: `aapt2 link` merges resources when it *builds* an APK from sources, not when it is
  handed two finished ones.
- **No resource merge was implemented or attempted**, by design
  (`references/split-apk.md` §5). The consequence is that a bundle whose resources live in splits
  cannot be reduced to one faithful APK by anything in this repository.
- **`apktool` was not exercised, because it is not usable on this machine.** Measured:
  `apktool.bat d …` fails with `Error: Unable to access jarfile <missing-path>`, while
  `lib/apksigner.jar` and `zipalign.exe` in the same layout work. Any manifest edit that needs
  `apktool` is therefore **unverified** here, and AXML attributes are read-only in this pass (the
  script parses the string pool and the root element's attributes; nothing writes AXML).
- **Feature splits (`isFeatureSplit`) were not measured.** Neither available set has one. The
  handling of `isFeatureSplit` / `configForSplit` in the reference file is **inferred** from the
  platform's documented semantics plus the fact that both attributes are readable through the same
  AXML reader that was verified against real manifests.
- **Split APKs that are not App-Bundle-derived** (the older per-density `-hdpi.apk` naming style,
  or an OEM's own module set) were not available; both sets here use the standard `config.<qualifier>`
  split names, and the reader accepts either because it reads the manifest attribute rather than the
  file name.
- **A XAPK/APKS archive** (a store bundle of bundles, usually a zip holding the split set plus
  `manifest.json`) was not processed. The script's `--split-dir` recursion handles a *directory* of
  APKs, so an unpacked XAPK works; the archive itself is not read.