Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(native): assemble and sign an APK with no Android SDK

esengine0ed0439b7df1
diff --git a/build-tools/tests/verify-apk.py b/build-tools/tests/verify-apk.py
new file mode 100644
index 000000000..7ea843e09
--- /dev/null
+++ b/build-tools/tests/verify-apk.py
@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#
+# An independent APK verifier — the oracle for build-tools/utils/apk.js.
+#
+# We write the signature ourselves, so checking it with our own code would prove
+# nothing. This is a second implementation of APK Signature Scheme v2, written
+# from the spec and sharing no code with the signer: it finds the signing block,
+# re-derives the chunked digest from the file's bytes, and verifies the RSA
+# signature by hand (modular exponentiation + PKCS#1 v1.5 unpadding).
+#
+# Python 3 standard library only, so it runs wherever the tests do. If androguard
+# happens to be installed it also decodes the binary manifest, which checks the
+# other format we write ourselves.
+#
+# Usage: python3 verify-apk.py <apk> → JSON on stdout, non-zero exit on failure.
+
+import hashlib
+import json
+import struct
+import sys
+
+MAGIC = b"APK Sig Block 42"
+V2_BLOCK_ID = 0x7109871A
+SIG_RSA_PKCS1_SHA256 = 0x0103
+CHUNK = 1048576
+SHA256_DIGESTINFO = bytes.fromhex("3031300d060960864801650304020105000420")
+
+
+def find_eocd(data):
+ for i in range(len(data) - 22, max(-1, len(data) - 22 - 0xFFFF), -1):
+ if data[i:i + 4] == b"PK\x05\x06":
+ return i
+ raise SystemExit("no end-of-central-directory record")
+
+
+def read_len_prefixed(buf, at):
+ (n,) = struct.unpack_from("<I", buf, at)
+ return buf[at + 4:at + 4 + n], at + 4 + n
+
+
+def iter_sequence(buf):
+ at = 0
+ while at < len(buf):
+ item, at = read_len_prefixed(buf, at)
+ yield item
+
+
+def der_items(buf):
+ """Walk DER TLVs, yielding (tag, content, whole TLV)."""
+ at = 0
+ while at < len(buf):
+ start = at
+ tag = buf[at]
+ length = buf[at + 1]
+ at += 2
+ if length & 0x80:
+ count = length & 0x7F
+ length = int.from_bytes(buf[at:at + count], "big")
+ at += count
+ yield tag, buf[at:at + length], buf[start:at + length]
+ at += length
+
+
+def rsa_public_numbers(spki):
+ """(n, e) from a SubjectPublicKeyInfo — the key is a BIT STRING holding
+ RSAPublicKey ::= SEQUENCE { modulus INTEGER, publicExponent INTEGER }."""
+ _, body, _ = next(der_items(spki))
+ bit_string = [c for t, c, _ in der_items(body) if t == 0x03][0]
+ _, rsa_key, _ = next(der_items(bit_string[1:])) # [1:] drops the unused-bit count
+ modulus, exponent = [int.from_bytes(c, "big") for t, c, _ in der_items(rsa_key) if t == 0x02][:2]
+ return modulus, exponent
+
+
+def verify_rsa_pkcs1_sha256(spki, signed, signature):
+ n, e = rsa_public_numbers(spki)
+ size = (n.bit_length() + 7) // 8
+ decrypted = pow(int.from_bytes(signature, "big"), e, n).to_bytes(size, "big")
+ expected = b"\x00\x01" + b"\xff" * (size - 3 - len(SHA256_DIGESTINFO) - 32) + b"\x00" \
+ + SHA256_DIGESTINFO + hashlib.sha256(signed).digest()
+ return decrypted == expected
+
+
+def apk_digest(sections):
+ chunks = []
+ for section in sections:
+ for at in range(0, len(section), CHUNK):
+ chunks.append(section[at:at + CHUNK])
+ digests = b"".join(
+ hashlib.sha256(b"\xa5" + struct.pack("<I", len(c)) + c).digest() for c in chunks)
+ return hashlib.sha256(b"\x5a" + struct.pack("<I", len(chunks)) + digests).digest()
+
+
+def verify(path):
+ data = open(path, "rb").read()
+ eocd = find_eocd(data)
+ cd_offset = struct.unpack_from("<I", data, eocd + 16)[0]
+ cd_size = struct.unpack_from("<I", data, eocd + 12)[0]
+
+ if data[cd_offset - 16:cd_offset] != MAGIC:
+ raise SystemExit("no APK Signing Block before the central directory")
+ block_size = struct.unpack_from("<Q", data, cd_offset - 24)[0]
+ block_start = cd_offset - block_size - 8
+ if struct.unpack_from("<Q", data, block_start)[0] != block_size:
+ raise SystemExit("APK Signing Block size fields disagree")
+
+ v2 = None
+ at = block_start + 8
+ while at < cd_offset - 24:
+ (pair_len,) = struct.unpack_from("<Q", data, at)
+ (pair_id,) = struct.unpack_from("<I", data, at + 8)
+ if pair_id == V2_BLOCK_ID:
+ v2 = data[at + 12:at + 8 + pair_len]
+ at += 8 + pair_len
+ if v2 is None:
+ raise SystemExit("no v2 signature block")
+
+ # The digest covers the entries, the central directory, and the EOCD with its
+ # central-directory pointer moved back to where the signing block starts.
+ eocd_for_digest = bytearray(data[eocd:])
+ struct.pack_into("<I", eocd_for_digest, 16, block_start)
+ computed = apk_digest([data[:block_start], data[cd_offset:cd_offset + cd_size], bytes(eocd_for_digest)])
+
+ signers = list(iter_sequence(list(iter_sequence(v2))[0]))
+ if len(signers) != 1:
+ raise SystemExit(f"expected exactly one signer, got {len(signers)}")
+
+ signer = signers[0]
+ signed_data, at = read_len_prefixed(signer, 0)
+ signatures, at = read_len_prefixed(signer, at)
+ public_key, at = read_len_prefixed(signer, at)
+
+ digests, sat = read_len_prefixed(signed_data, 0)
+ certificates, sat = read_len_prefixed(signed_data, sat)
+
+ claimed = None
+ for item in iter_sequence(digests):
+ (algo,) = struct.unpack_from("<I", item, 0)
+ if algo == SIG_RSA_PKCS1_SHA256:
+ claimed, _ = read_len_prefixed(item, 4)
+ if claimed is None:
+ raise SystemExit("no SHA-256/RSA digest in the signed data")
+ if claimed != computed:
+ raise SystemExit(f"digest mismatch: signed {claimed.hex()} but the file digests to {computed.hex()}")
+
+ verified = False
+ for item in iter_sequence(signatures):
+ (algo,) = struct.unpack_from("<I", item, 0)
+ if algo != SIG_RSA_PKCS1_SHA256:
+ continue
+ signature, _ = read_len_prefixed(item, 4)
+ if not verify_rsa_pkcs1_sha256(public_key, signed_data, signature):
+ raise SystemExit("the signature does not verify against the signer's public key")
+ verified = True
+ if not verified:
+ raise SystemExit("no SHA-256/RSA signature in the block")
+
+ certs = list(iter_sequence(certificates))
+ # The certificate has to certify the key that signed, or the signature proves
+ # nothing about the identity the device records.
+ _, certificate, _ = next(der_items(certs[0]))
+ tbs = next(c for t, c, _ in der_items(certificate) if t == 0x30)
+ # With no extensions, the last SEQUENCE in the TBS is the public key info.
+ cert_spki = [f for t, c, f in der_items(tbs) if t == 0x30][-1]
+ if rsa_public_numbers(public_key) != rsa_public_numbers(cert_spki):
+ raise SystemExit("the certificate does not carry the signer's public key")
+
+ result = {
+ "signedV2": True,
+ "signers": len(signers),
+ "certificates": len(certs),
+ "digestBytes": len(computed),
+ "entries": struct.unpack_from("<H", data, eocd + 10)[0],
+ }
+
+ try:
+ import os
+ os.environ.setdefault("LOGURU_LEVEL", "CRITICAL")
+ from androguard.core.apk import APK
+ apk = APK(path)
+ result["manifest"] = {
+ "package": apk.get_package(),
+ "label": apk.get_app_name(),
+ "versionName": apk.get_androidversion_name(),
+ "versionCode": apk.get_androidversion_code(),
+ "minSdk": apk.get_min_sdk_version(),
+ "targetSdk": apk.get_target_sdk_version(),
+ "mainActivity": apk.get_main_activity(),
+ "valid": apk.is_valid_APK(),
+ }
+ except ImportError:
+ result["manifest"] = None
+ return result
+
+
+if __name__ == "__main__":
+ print(json.dumps(verify(sys.argv[1]), indent=2))
diff --git a/build-tools/utils/androidBinaryXml.js b/build-tools/utils/androidBinaryXml.js
new file mode 100644
index 000000000..5f0789ce1
--- /dev/null
+++ b/build-tools/utils/androidBinaryXml.js
@@ -0,0 +1,348 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// AndroidManifest.xml, compiled — the format aapt2 produces and the platform
+// parses (binary XML: a string pool, a resource map, and one chunk per node).
+//
+// Written rather than shelled out to, because `aapt2` is the reason packaging an
+// APK used to need the whole Android SDK. Everything else the assembler does is a
+// zip and a signature; this was the last external tool in the path between an
+// editor export and an installable app.
+//
+// The scope is deliberately OUR manifest: elements, attributes, and the four value
+// kinds it uses. Nothing here compiles resources — an APK with no resources of its
+// own is what the native host ships, and the one reference it makes
+// (@android:style/Theme.NoTitleBar.Fullscreen) is a FRAMEWORK id, resolved by the
+// platform rather than by a table we would have to emit.
+//
+// The platform resolves a framework attribute BY ITS RESOURCE ID, not by the name
+// string — a wrong id is silently ignored rather than rejected — so the ids below
+// are pinned against AOSP's public.xml by `desktop/tests/android-manifest.test.ts`.
+
+/** The namespace every framework attribute lives in. */
+export const ANDROID_NS = 'http://schemas.android.com/apk/res/android';
+
+/** AOSP public attribute ids, for the attributes our manifest uses. */
+export const ANDROID_ATTR_IDS = {
+ theme: 0x01010000,
+ label: 0x01010001,
+ icon: 0x01010002,
+ name: 0x01010003,
+ hasCode: 0x0101000c,
+ exported: 0x01010010,
+ screenOrientation: 0x0101001e,
+ configChanges: 0x0101001f,
+ value: 0x01010024,
+ minSdkVersion: 0x0101020c,
+ versionCode: 0x0101021b,
+ versionName: 0x0101021c,
+ targetSdkVersion: 0x01010270,
+ required: 0x0101028e,
+ extractNativeLibs: 0x010104ea,
+ version: 0x01010519,
+};
+
+/** AOSP public style ids, for the `@android:style/...` a manifest may name. */
+export const ANDROID_STYLE_IDS = {
+ 'Theme.NoTitleBar': 0x01030006,
+ 'Theme.NoTitleBar.Fullscreen': 0x01030007,
+};
+
+// Res_value data types.
+const TYPE_REFERENCE = 0x01;
+const TYPE_STRING = 0x03;
+const TYPE_INT_DEC = 0x10;
+const TYPE_INT_HEX = 0x11;
+const TYPE_INT_BOOLEAN = 0x12;
+
+const NO_ENTRY = 0xffffffff;
+
+// =============================================================================
+// A very small XML reader
+// =============================================================================
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+function unescape(text) {
+ return text.replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (m, ref) => {
+ if (ref[0] === '#') return String.fromCodePoint(parseInt(ref[1] === 'x' ? ref.slice(2) : ref.slice(1), ref[1] === 'x' ? 16 : 10));
+ return ref in ENTITIES ? ENTITIES[ref] : m;
+ });
+}
+
+/**
+ * Parse the XML subset a manifest is written in: elements, attributes, comments
+ * and the declaration. Text nodes are ignored — a manifest has none that matter,
+ * and accepting them silently would hide a typo.
+ *
+ * @returns {{name: string, attrs: Array<{prefix: string|null, name: string, value: string}>,
+ * children: Array<object>, line: number}} the root element
+ */
+export function parseXml(text) {
+ let i = 0;
+ let line = 1;
+ const advance = (to) => {
+ for (let k = i; k < to; k++) if (text[k] === '\n') line++;
+ i = to;
+ };
+ const skipSpace = () => { while (i < text.length && /\s/.test(text[i])) { if (text[i] === '\n') line++; i++; } };
+
+ let root = null;
+ const stack = [];
+ const attach = (node) => {
+ if (stack.length > 0) stack[stack.length - 1].children.push(node);
+ else if (!root) root = node;
+ else throw new Error(`XML: a second root element <${node.name}> (line ${node.line})`);
+ };
+
+ while (i < text.length) {
+ const lt = text.indexOf('<', i);
+ if (lt < 0) break;
+ advance(lt);
+ if (text.startsWith('<?', i)) { advance(text.indexOf('?>', i) + 2); continue; }
+ if (text.startsWith('<!--', i)) { advance(text.indexOf('-->', i) + 3); continue; }
+ if (text.startsWith('</', i)) {
+ const end = text.indexOf('>', i);
+ const name = text.slice(i + 2, end).trim();
+ const open = stack.pop();
+ if (!open || open.name !== name) throw new Error(`XML: </${name}> does not close <${open?.name}> (line ${line})`);
+ advance(end + 1);
+ continue;
+ }
+
+ // <name attr="value" ... > or <name ... />
+ advance(i + 1);
+ const nameStart = i;
+ while (i < text.length && !/[\s/>]/.test(text[i])) i++;
+ const node = { name: text.slice(nameStart, i), attrs: [], children: [], line };
+ for (;;) {
+ skipSpace();
+ if (text.startsWith('/>', i)) { advance(i + 2); attach(node); break; }
+ if (text[i] === '>') { advance(i + 1); attach(node); stack.push(node); break; }
+ const attrStart = i;
+ while (i < text.length && !/[\s=]/.test(text[i])) i++;
+ const qualified = text.slice(attrStart, i);
+ skipSpace();
+ if (text[i] !== '=') throw new Error(`XML: attribute ${qualified} has no value (line ${line})`);
+ advance(i + 1);
+ skipSpace();
+ const quote = text[i];
+ if (quote !== '"' && quote !== "'") throw new Error(`XML: unquoted value for ${qualified} (line ${line})`);
+ const valueEnd = text.indexOf(quote, i + 1);
+ const value = unescape(text.slice(i + 1, valueEnd));
+ advance(valueEnd + 1);
+ const colon = qualified.indexOf(':');
+ node.attrs.push(colon < 0
+ ? { prefix: null, name: qualified, value }
+ : { prefix: qualified.slice(0, colon), name: qualified.slice(colon + 1), value });
+ }
+ }
+ if (stack.length > 0) throw new Error(`XML: <${stack[stack.length - 1].name}> is never closed`);
+ if (!root) throw new Error('XML: no root element');
+ return root;
+}
+
+// =============================================================================
+// The string pool
+// =============================================================================
+
+class StringPool {
+ constructor() {
+ this.strings = [];
+ this.index = new Map();
+ }
+
+ /** @returns the pool index, adding the string if it is new. */
+ add(s) {
+ const known = this.index.get(s);
+ if (known !== undefined) return known;
+ const at = this.strings.length;
+ this.strings.push(s);
+ this.index.set(s, at);
+ return at;
+ }
+
+ /**
+ * UTF-16 rather than UTF-8: every parser accepts it, and its length rules have
+ * no surrogate-vs-code-unit subtlety to get wrong. A manifest is a few hundred
+ * bytes either way.
+ */
+ encode() {
+ const bodies = this.strings.map((s) => {
+ const chars = Buffer.from(s, 'utf16le');
+ const units = chars.length / 2;
+ if (units > 0x7fff) throw new Error('string pool entry too long');
+ const out = Buffer.alloc(2 + chars.length + 2);
+ out.writeUInt16LE(units, 0);
+ chars.copy(out, 2);
+ return out; // trailing UTF-16 NUL is the zero-filled tail
+ });
+ const offsets = Buffer.alloc(this.strings.length * 4);
+ let at = 0;
+ bodies.forEach((b, n) => { offsets.writeUInt32LE(at, n * 4); at += b.length; });
+ const data = Buffer.concat(bodies);
+ const padding = (4 - (data.length % 4)) % 4;
+ const headerSize = 28;
+ const stringsStart = headerSize + offsets.length;
+ const size = stringsStart + data.length + padding;
+
+ const header = Buffer.alloc(headerSize);
+ header.writeUInt16LE(0x0001, 0); // RES_STRING_POOL_TYPE
+ header.writeUInt16LE(headerSize, 2);
+ header.writeUInt32LE(size, 4);
+ header.writeUInt32LE(this.strings.length, 8);
+ header.writeUInt32LE(0, 12); // no styles
+ header.writeUInt32LE(0, 16); // flags: UTF-16, unsorted
+ header.writeUInt32LE(stringsStart, 20);
+ header.writeUInt32LE(0, 24); // stylesStart
+ return Buffer.concat([header, offsets, data, Buffer.alloc(padding)]);
+ }
+}
+
+// =============================================================================
+// Values
+// =============================================================================
+
+/** How a manifest attribute's text is typed. Order matters: `@android:style/...`
+ * before anything, then the two integer spellings, then booleans, then string. */
+function typedValue(value, pool) {
+ const style = /^@android:style\/(.+)$/.exec(value);
+ if (style) {
+ const id = ANDROID_STYLE_IDS[style[1]];
+ if (id === undefined) throw new Error(`Unknown framework style @android:style/${style[1]}`);
+ return { type: TYPE_REFERENCE, data: id, raw: NO_ENTRY };
+ }
+ if (value === 'true' || value === 'false') {
+ return { type: TYPE_INT_BOOLEAN, data: value === 'true' ? 0xffffffff : 0, raw: NO_ENTRY };
+ }
+ if (/^0x[0-9a-fA-F]+$/.test(value)) {
+ return { type: TYPE_INT_HEX, data: Number.parseInt(value, 16) >>> 0, raw: NO_ENTRY };
+ }
+ if (/^-?\d+$/.test(value)) {
+ return { type: TYPE_INT_DEC, data: Number.parseInt(value, 10) >>> 0, raw: NO_ENTRY };
+ }
+ const at = pool.add(value);
+ return { type: TYPE_STRING, data: at, raw: at };
+}
+
+// =============================================================================
+// The encoder
+// =============================================================================
+
+function chunk(type, headerExtra, body) {
+ const headerSize = 8 + headerExtra.length;
+ const header = Buffer.alloc(8);
+ header.writeUInt16LE(type, 0);
+ header.writeUInt16LE(headerSize, 2);
+ header.writeUInt32LE(headerSize + body.length, 4);
+ return Buffer.concat([header, headerExtra, body]);
+}
+
+/** The 8 bytes every XML node chunk carries after its header: line + comment. */
+function nodeHeaderExtra(line) {
+ const extra = Buffer.alloc(8);
+ extra.writeUInt32LE(line, 0);
+ extra.writeUInt32LE(NO_ENTRY, 4);
+ return extra;
+}
+
+/**
+ * Compile a parsed manifest to binary XML.
+ *
+ * Attribute-name strings are pooled FIRST, in the order the resource map lists
+ * their ids: the platform reads an attribute's id by its position in that map, so
+ * the two are one structure written as two.
+ *
+ * @param {object} root The element from {@link parseXml}.
+ * @returns {Buffer}
+ */
+export function encodeBinaryXml(root) {
+ const pool = new StringPool();
+
+ // Pass 1: every framework attribute name, in first-use order.
+ const attrIds = [];
+ const walkNames = (node) => {
+ for (const attr of node.attrs) {
+ if (attr.prefix !== 'android') continue;
+ const id = ANDROID_ATTR_IDS[attr.name];
+ if (id === undefined) {
+ throw new Error(`No public resource id known for android:${attr.name} — add it to `
+ + 'ANDROID_ATTR_IDS (the platform resolves attributes by id, so guessing is not an option).');
+ }
+ if (pool.index.has(attr.name)) continue;
+ pool.add(attr.name);
+ attrIds.push(id);
+ }
+ node.children.forEach(walkNames);
+ };
+ walkNames(root);
+ // Nothing else may take a slot the resource map covers.
+ const mapSize = pool.strings.length;
+
+ const nsPrefix = pool.add('android');
+ const nsUri = pool.add(ANDROID_NS);
+
+ // Pass 2: the node chunks. Values and element names join the pool as they are
+ // reached, which is why the map's slots had to be claimed first.
+ const nodes = [];
+ const emit = (node) => {
+ const attrs = node.attrs
+ .filter((a) => a.name !== 'xmlns' && a.prefix !== 'xmlns')
+ .map((a) => ({
+ ns: a.prefix === 'android' ? nsUri : NO_ENTRY,
+ name: pool.add(a.name),
+ value: typedValue(a.value, pool),
+ }));
+ const name = pool.add(node.name);
+
+ const ext = Buffer.alloc(20 + attrs.length * 20);
+ ext.writeUInt32LE(NO_ENTRY, 0); // element namespace
+ ext.writeUInt32LE(name, 4);
+ ext.writeUInt16LE(20, 8); // attributeStart
+ ext.writeUInt16LE(20, 10); // attributeSize
+ ext.writeUInt16LE(attrs.length, 12);
+ ext.writeUInt16LE(0, 14); // idIndex — no android:id in a manifest
+ ext.writeUInt16LE(0, 16); // classIndex
+ ext.writeUInt16LE(0, 18); // styleIndex
+ attrs.forEach((a, n) => {
+ const at = 20 + n * 20;
+ ext.writeUInt32LE(a.ns, at);
+ ext.writeUInt32LE(a.name, at + 4);
+ ext.writeUInt32LE(a.value.raw, at + 8);
+ ext.writeUInt16LE(8, at + 12); // Res_value size
+ ext.writeUInt8(0, at + 14); // res0
+ ext.writeUInt8(a.value.type, at + 15);
+ ext.writeUInt32LE(a.value.data, at + 16);
+ });
+ nodes.push(chunk(0x0102, nodeHeaderExtra(node.line), ext));
+
+ node.children.forEach(emit);
+
+ const end = Buffer.alloc(8);
+ end.writeUInt32LE(NO_ENTRY, 0);
+ end.writeUInt32LE(name, 4);
+ nodes.push(chunk(0x0103, nodeHeaderExtra(node.line), end));
+ };
+
+ const namespace = (type) => {
+ const body = Buffer.alloc(8);
+ body.writeUInt32LE(nsPrefix, 0);
+ body.writeUInt32LE(nsUri, 4);
+ return chunk(type, nodeHeaderExtra(root.line), body);
+ };
+
+ const startNs = namespace(0x0100);
+ emit(root);
+ const endNs = namespace(0x0101);
+
+ const map = Buffer.alloc(mapSize * 4);
+ attrIds.forEach((id, n) => map.writeUInt32LE(id, n * 4));
+
+ const body = Buffer.concat([pool.encode(), chunk(0x0180, Buffer.alloc(0), map), startNs, ...nodes, endNs]);
+ return chunk(0x0003, Buffer.alloc(0), body); // RES_XML_TYPE
+}
+
+/** Compile manifest SOURCE (the filled template) to the bytes an APK carries. */
+export function compileManifest(xml) {
+ return encodeBinaryXml(parseXml(xml));
+}
diff --git a/build-tools/utils/androidKeystore.d.ts b/build-tools/utils/androidKeystore.d.ts
new file mode 100644
index 000000000..1df7696ab
--- /dev/null
+++ b/build-tools/utils/androidKeystore.d.ts
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// Types for androidKeystore.js — the module is plain ESM so the CLI can run it
+// unbuilt, and this is how the editor's TypeScript sees it.
+
+import type { KeyObject } from 'node:crypto';
+
+/** What an APK is signed with: the key, and the certificate that goes inside. */
+export interface SigningKey {
+ privateKey: KeyObject;
+ /** DER-encoded X.509. */
+ certificate: Buffer;
+ /** Who it says signed — for the line the packager prints. */
+ name: string;
+}
+
+export function debugKeyDir(): string;
+export function debugSigningKey(): SigningKey;
+export function signingKeyFromPem(files: { key: string; cert: string; passphrase?: string }): SigningKey;
diff --git a/build-tools/utils/androidKeystore.js b/build-tools/utils/androidKeystore.js
new file mode 100644
index 000000000..a0369d00e
--- /dev/null
+++ b/build-tools/utils/androidKeystore.js
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The key an APK is signed with.
+//
+// Android needs every package signed, including one you only sideload to try it.
+// That used to mean keytool, a JKS file and a JDK; here it is an RSA key and a
+// self-signed certificate in PEM, which Node's crypto reads and writes and which
+// `openssl x509 -in cert.pem -text` will show you.
+//
+// PEM rather than JKS/PKCS#12 deliberately: those are container formats Node
+// cannot open, and the one thing worse than an unfamiliar file is one you cannot
+// inspect. A developer with an existing store exports it once
+// (`keytool -importkeystore` / `openssl pkcs12`) and points --key/--cert at it.
+
+import path from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as cryptoSign, X509Certificate } from 'crypto';
+import { estellaDataDir } from './nativeTemplate.js';
+import { selfSignedCertificate } from './asn1.js';
+
+/** Where the generated development key lives. */
+export function debugKeyDir() {
+ return process.env.ESTELLA_ANDROID_KEYS || path.join(estellaDataDir(), 'android-keys');
+}
+
+const PEM_BODY = /-----BEGIN CERTIFICATE-----([\s\S]*?)-----END CERTIFICATE-----/;
+
+/** DER bytes of a PEM certificate (the first one in the file). */
+function certificateDer(pem) {
+ const body = PEM_BODY.exec(pem);
+ if (!body) throw new Error('not a PEM certificate (no -----BEGIN CERTIFICATE-----)');
+ return Buffer.from(body[1].replace(/\s+/g, ''), 'base64');
+}
+
+/**
+ * A signing identity: the private key, and the certificate that goes in the APK.
+ *
+ * @typedef {{privateKey: import('crypto').KeyObject, certificate: Buffer, name: string}} SigningKey
+ */
+
+/**
+ * The development key, generated on first use.
+ *
+ * A game you are testing has to install, and stopping to ask for credentials to
+ * do that is how packaging becomes a chore. This key is exactly as trustworthy as
+ * Android Studio's debug keystore: fine for a device, never for a store.
+ *
+ * @returns {SigningKey}
+ */
+export function debugSigningKey() {
+ const dir = debugKeyDir();
+ const keyFile = path.join(dir, 'debug.key.pem');
+ const certFile = path.join(dir, 'debug.cert.pem');
+
+ if (existsSync(keyFile) && existsSync(certFile)) {
+ return {
+ privateKey: createPrivateKey(readFileSync(keyFile, 'utf8')),
+ certificate: certificateDer(readFileSync(certFile, 'utf8')),
+ name: 'Estella debug key',
+ };
+ }
+
+ const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+ const certificate = selfSignedCertificate(publicKey, {
+ commonName: 'Estella Debug',
+ organization: 'Estella',
+ // Longer than any app that was only ever sideloaded will live, and past
+ // the point where a store would accept it anyway.
+ days: 365 * 30,
+ notBefore: new Date(Date.now() - 86400000),
+ sign: (data) => cryptoSign('sha256', data, privateKey),
+ });
+
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(keyFile, privateKey.export({ type: 'pkcs8', format: 'pem' }));
+ // The key is the app's identity: an update signed by another key is refused by
+ // every device that has the old one installed.
+ try { chmodSync(keyFile, 0o600); } catch { /* best effort — Windows has no mode */ }
+ writeFileSync(certFile, `-----BEGIN CERTIFICATE-----\n${
+ certificate.toString('base64').replace(/(.{64})/g, '$1\n').replace(/\n$/, '')}\n-----END CERTIFICATE-----\n`);
+ return { privateKey, certificate, name: 'Estella debug key' };
+}
+
+/**
+ * A release identity from the developer's own PEM key + certificate.
+ *
+ * @param {{key: string, cert: string, passphrase?: string}} files
+ * @returns {SigningKey}
+ */
+export function signingKeyFromPem(files) {
+ const privateKey = createPrivateKey({
+ key: readFileSync(files.key, 'utf8'),
+ ...(files.passphrase ? { passphrase: files.passphrase } : {}),
+ });
+ const certificate = certificateDer(readFileSync(files.cert, 'utf8'));
+ // The pair has to match, and finding out on the device ("app not installed")
+ // is the worst possible time.
+ const cert = new X509Certificate(certificate);
+ if (!cert.publicKey.export({ type: 'spki', format: 'der' })
+ .equals(createPublicKey(privateKey).export({ type: 'spki', format: 'der' }))) {
+ throw new Error(`${path.basename(files.cert)} does not certify the key in ${path.basename(files.key)}.`);
+ }
+ return { privateKey, certificate, name: cert.subject.replace(/\n/g, ', ') };
+}
diff --git a/build-tools/utils/apk.d.ts b/build-tools/utils/apk.d.ts
new file mode 100644
index 000000000..87bec3007
--- /dev/null
+++ b/build-tools/utils/apk.d.ts
@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// Types for apk.js — the module is plain ESM so the CLI can run it unbuilt, and
+// this is how the editor's TypeScript sees it.
+
+import type { SigningKey } from './androidKeystore';
+
+export interface ApkAppIdentity {
+ id: string;
+ name: string;
+ version: string;
+ versionCode: number;
+ orientation: 'landscape' | 'portrait';
+}
+
+export function assembleApk(options: {
+ /** An installed android runtime template. */
+ templateDir: string;
+ /** The export: cooked content plus the two configs. */
+ contentDir: string;
+ app: ApkAppIdentity;
+ key: SigningKey;
+ abi: string;
+}): Buffer;
+
+export function signApkV2(zip: Buffer, key: SigningKey): Buffer;
+export function apkFileName(appId: string): string;
diff --git a/build-tools/utils/apk.js b/build-tools/utils/apk.js
new file mode 100644
index 000000000..c8c6c572f
--- /dev/null
+++ b/build-tools/utils/apk.js
@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The APK assembler — an installable Android package with no Android SDK.
+//
+// What packaging actually is, once the engine ships as a prebuilt runtime
+// template: compile the manifest, put four kinds of file in a zip, and sign it.
+// The tools that used to do those steps (aapt2, zipalign, apksigner, plus a JDK to
+// run the last one) are ~6 GB of Android Studio for three well-specified formats,
+// and they are the reason a developer with a finished game still could not press
+// one button. Each has a written spec; each is implemented here, and each is
+// checked against an independent implementation in the tests.
+//
+// Native libraries are STORED and 16 KiB-aligned, with extractNativeLibs=false:
+// the OS maps them straight out of the package, which halves the install and is
+// the posture Android 15's 16 KiB page size requires anyway.
+
+import path from 'path';
+import { createHash, createPublicKey, sign as cryptoSign } from 'crypto';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { makeZip, zipLayout } from './zip.js';
+import { compileManifest } from './androidBinaryXml.js';
+import { fillTemplate, androidScreenOrientation } from './nativeApp.js';
+
+/** The boundary a mapped `.so` must start on — a 16 KiB page, which every
+ * smaller page size also divides. */
+const PAGE_ALIGNMENT = 16384;
+
+/** APK Signature Scheme v2. minSdk 26 is well past the API 24 that introduced it,
+ * so v1 (JAR signing) would be dead weight — and its PKCS#7 is the only part of
+ * APK signing that is genuinely hard to write. */
+const V2_BLOCK_ID = 0x7109871a;
+const SIG_ALGO_RSA_PKCS1_SHA256 = 0x0103;
+const APK_SIG_BLOCK_MAGIC = Buffer.from('APK Sig Block 42', 'latin1');
+const DIGEST_CHUNK = 1048576;
+
+const u32 = (n) => { const b = Buffer.alloc(4); b.writeUInt32LE(n >>> 0, 0); return b; };
+const u64 = (n) => { const b = Buffer.alloc(8); b.writeBigUInt64LE(BigInt(n), 0); return b; };
+const lenPrefixed = (buf) => Buffer.concat([u32(buf.length), buf]);
+/** A length-prefixed sequence of length-prefixed items — the shape the spec
+ * repeats at every level. */
+const seq = (items) => lenPrefixed(Buffer.concat(items.map(lenPrefixed)));
+
+/**
+ * The APK digest: 1 MiB chunks of the three sections, each digested with a 0xa5
+ * prefix, then one digest over all of them with 0x5a. Verbatim from the scheme —
+ * chunking is what lets a device verify an APK without reading it twice.
+ */
+function apkDigest(sections) {
+ const chunks = [];
+ for (const section of sections) {
+ for (let at = 0; at < section.length; at += DIGEST_CHUNK) {
+ chunks.push(section.subarray(at, Math.min(at + DIGEST_CHUNK, section.length)));
+ }
+ }
+ const digests = chunks.map((chunk) => createHash('sha256')
+ .update(Buffer.from([0xa5])).update(u32(chunk.length)).update(chunk).digest());
+ return createHash('sha256')
+ .update(Buffer.from([0x5a])).update(u32(chunks.length)).update(Buffer.concat(digests)).digest();
+}
+
+/**
+ * Sign a finished zip, returning the APK.
+ *
+ * The signing block goes between the entries and the central directory, so the
+ * end-of-central-directory record's pointer moves. The digest is taken over the
+ * EOCD as if the central directory sat where the block now starts — the verifier
+ * makes the same substitution, which is what lets the signature cover a record
+ * that the signature's own insertion changes.
+ *
+ * @param {Buffer} zip
+ * @param {{privateKey: import('crypto').KeyObject, certificate: Buffer}} key
+ * @returns {Buffer}
+ */
+export function signApkV2(zip, key) {
+ const { centralDirOffset, centralDirSize, eocdOffset } = zipLayout(zip);
+ const contents = zip.subarray(0, centralDirOffset);
+ const centralDir = zip.subarray(centralDirOffset, centralDirOffset + centralDirSize);
+ const eocd = Buffer.from(zip.subarray(eocdOffset));
+ eocd.writeUInt32LE(contents.length, 16);
+
+ const digest = apkDigest([contents, centralDir, eocd]);
+ const publicKey = createPublicKey(key.privateKey).export({ type: 'spki', format: 'der' });
+
+ const signedData = Buffer.concat([
+ seq([Buffer.concat([u32(SIG_ALGO_RSA_PKCS1_SHA256), lenPrefixed(digest)])]),
+ seq([key.certificate]),
+ seq([]), // no additional attributes
+ ]);
+ const signature = cryptoSign('sha256', signedData, key.privateKey);
+ const signer = Buffer.concat([
+ lenPrefixed(signedData),
+ seq([Buffer.concat([u32(SIG_ALGO_RSA_PKCS1_SHA256), lenPrefixed(signature)])]),
+ lenPrefixed(publicKey),
+ ]);
+
+ const pair = Buffer.concat([u64(4 + seq([signer]).length), u32(V2_BLOCK_ID), seq([signer])]);
+ const blockSize = pair.length + 8 + APK_SIG_BLOCK_MAGIC.length;
+ const block = Buffer.concat([u64(blockSize), pair, u64(blockSize), APK_SIG_BLOCK_MAGIC]);
+
+ const signedEocd = Buffer.from(eocd);
+ signedEocd.writeUInt32LE(contents.length + block.length, 16);
+ return Buffer.concat([contents, block, centralDir, signedEocd]);
+}
+
+/** Every file under `dir`, as `{ name, data }` entries named `<prefix>/<rel>`. */
+function treeEntries(dir, prefix) {
+ const out = [];
+ const walk = (abs, rel) => {
+ for (const e of readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+ const child = path.join(abs, e.name);
+ const name = `${rel}/${e.name}`;
+ if (e.isDirectory()) walk(child, name);
+ // Dotfiles are build-machine litter (.DS_Store, .gitkeep); a package is
+ // not the place to find out they shipped. Neither is a package: the
+ // finished APK lands in the export directory, and a re-export must not
+ // swallow the last one.
+ else if (e.isFile() && !e.name.startsWith('.') && !e.name.endsWith('.apk')) {
+ out.push({ name, data: readFileSync(child) });
+ }
+ }
+ };
+ walk(dir, prefix);
+ return out;
+}
+
+/**
+ * Assemble a signed APK from a runtime template and an editor export.
+ *
+ * @param {object} options
+ * @param {string} options.templateDir An installed android runtime template.
+ * @param {string} options.contentDir The export (cooked content + the configs).
+ * @param {{id: string, name: string, version: string, versionCode: number,
+ * orientation: 'landscape'|'portrait'}} options.app
+ * @param {{privateKey: import('crypto').KeyObject, certificate: Buffer}} options.key
+ * @param {string} options.abi
+ * @returns {Buffer} the signed package.
+ */
+export function assembleApk(options) {
+ const { templateDir, contentDir, app, abi } = options;
+ const dex = path.join(templateDir, 'classes.dex');
+ const hasDex = existsSync(dex);
+
+ const manifest = compileManifest(fillTemplate(
+ readFileSync(path.join(templateDir, 'AndroidManifest.xml.in'), 'utf8'), {
+ APP_ID: app.id,
+ APP_NAME: app.name,
+ VERSION_NAME: app.version,
+ VERSION_CODE: app.versionCode,
+ SCREEN_ORIENTATION: androidScreenOrientation(app.orientation),
+ HAS_CODE: hasDex ? 'true' : 'false',
+ }));
+
+ const libDir = path.join(templateDir, 'lib', abi);
+ if (!existsSync(libDir)) throw new Error(`The runtime template has no lib/${abi}.`);
+ const templateAssets = path.join(templateDir, 'assets');
+
+ const entries = [
+ { name: 'AndroidManifest.xml', data: manifest },
+ ...(hasDex ? [{ name: 'classes.dex', data: readFileSync(dex) }] : []),
+ ...treeEntries(libDir, `lib/${abi}`).map((e) => ({ ...e, store: true, align: PAGE_ALIGNMENT })),
+ // The template's assets (the SDK bytecode) first, so a project cannot
+ // shadow them by accident and quietly change what the host boots.
+ ...(existsSync(templateAssets) ? treeEntries(templateAssets, 'assets') : []),
+ ...treeEntries(contentDir, 'assets'),
+ ];
+
+ const seen = new Set();
+ for (const entry of entries) {
+ if (seen.has(entry.name)) throw new Error(`Two files claim ${entry.name} in the package.`);
+ seen.add(entry.name);
+ }
+
+ return signApkV2(makeZip(entries), options.key);
+}
+
+/** The APK is named after the app it holds, so packaging a second project does not
+ * quietly replace the first one's file. */
+export function apkFileName(appId) {
+ return `${appId.split('.').pop() || 'estella'}.apk`;
+}
diff --git a/build-tools/utils/asn1.js b/build-tools/utils/asn1.js
new file mode 100644
index 000000000..14d486e9f
--- /dev/null
+++ b/build-tools/utils/asn1.js
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// DER, and the one certificate we have to write ourselves.
+//
+// Signing an APK needs a private key AND an X.509 certificate. Node's crypto can
+// generate the key and produce the signature, but it cannot make a certificate —
+// which is the only reason the whole Java toolchain (keytool, apksigner) used to
+// be on the path between an editor and an installable app. A self-signed leaf is
+// a few DER structures; they are here.
+
+import { createHash } from 'crypto';
+
+/** A DER TLV: tag, definite length, contents. */
+export function der(tag, contents) {
+ const body = Buffer.isBuffer(contents) ? contents : Buffer.concat(contents);
+ if (body.length < 0x80) return Buffer.concat([Buffer.from([tag, body.length]), body]);
+ const len = [];
+ for (let n = body.length; n > 0; n >>>= 8) len.unshift(n & 0xff);
+ return Buffer.concat([Buffer.from([tag, 0x80 | len.length]), Buffer.from(len), body]);
+}
+
+export const sequence = (...items) => der(0x30, items.flat());
+export const set = (...items) => der(0x31, items.flat());
+export const octetString = (buf) => der(0x04, buf);
+export const nullValue = () => der(0x05, Buffer.alloc(0));
+export const utf8String = (s) => der(0x0c, Buffer.from(s, 'utf8'));
+export const printableString = (s) => der(0x13, Buffer.from(s, 'latin1'));
+export const explicit = (n, inner) => der(0xa0 | n, inner);
+
+/** A positive INTEGER; a leading 0x00 keeps it from reading as negative. */
+export function integer(value) {
+ let bytes = Buffer.isBuffer(value) ? value : (() => {
+ const out = [];
+ let n = BigInt(value);
+ do { out.unshift(Number(n & 0xffn)); n >>= 8n; } while (n > 0n);
+ return Buffer.from(out);
+ })();
+ while (bytes.length > 1 && bytes[0] === 0 && (bytes[1] & 0x80) === 0) bytes = bytes.subarray(1);
+ return der(0x02, bytes[0] & 0x80 ? Buffer.concat([Buffer.from([0]), bytes]) : bytes);
+}
+
+/** A BIT STRING with no unused trailing bits — the only kind a certificate uses. */
+export const bitString = (buf) => der(0x03, Buffer.concat([Buffer.from([0]), buf]));
+
+export function oid(dotted) {
+ const parts = dotted.split('.').map(Number);
+ const bytes = [parts[0] * 40 + parts[1]];
+ for (const part of parts.slice(2)) {
+ const chunk = [part & 0x7f];
+ for (let n = part >>> 7; n > 0; n >>>= 7) chunk.unshift((n & 0x7f) | 0x80);
+ bytes.push(...chunk);
+ }
+ return der(0x06, Buffer.from(bytes));
+}
+
+const OID_SHA256_RSA = '1.2.840.113549.1.1.11';
+const OID_COMMON_NAME = '2.5.4.3';
+const OID_ORGANIZATION = '2.5.4.10';
+
+/** RFC 5280: UTCTime through 2049, GeneralizedTime from 2050. */
+function time(date) {
+ const p = (n, w = 2) => String(n).padStart(w, '0');
+ const y = date.getUTCFullYear();
+ const rest = `${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}${p(date.getUTCHours())}`
+ + `${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}Z`;
+ return y < 2050
+ ? der(0x17, Buffer.from(`${p(y % 100)}${rest}`, 'latin1'))
+ : der(0x18, Buffer.from(`${p(y, 4)}${rest}`, 'latin1'));
+}
+
+const name = (commonName, organization) => sequence(
+ set(sequence(oid(OID_COMMON_NAME), utf8String(commonName))),
+ set(sequence(oid(OID_ORGANIZATION), utf8String(organization))),
+);
+
+/**
+ * A self-signed X.509 certificate for @p publicKey, signed with @p privateKey.
+ *
+ * Deliberately minimal — no extensions. Android identifies an app by the signing
+ * certificate's bytes and public key; it does not build or validate a chain, so a
+ * basicConstraints/keyUsage set here would be decoration that some other tool
+ * might then hold us to.
+ *
+ * @param {import('crypto').KeyObject} privateKey
+ * @param {import('crypto').KeyObject} publicKey
+ * @param {{commonName: string, organization: string, days: number, notBefore: Date,
+ * serial?: bigint, sign: (data: Buffer) => Buffer}} options
+ * @returns {Buffer} the certificate, DER-encoded.
+ */
+export function selfSignedCertificate(publicKey, options) {
+ const spki = publicKey.export({ type: 'spki', format: 'der' });
+ const algorithm = sequence(oid(OID_SHA256_RSA), nullValue());
+ const notBefore = options.notBefore;
+ const notAfter = new Date(notBefore.getTime() + options.days * 86400000);
+ const subject = name(options.commonName, options.organization);
+
+ const tbs = sequence(
+ explicit(0, integer(2)), // v3
+ integer(options.serial ?? BigInt(`0x${createHash('sha256').update(spki).digest('hex').slice(0, 16)}`)),
+ algorithm,
+ subject, // issuer == subject: self-signed
+ sequence(time(notBefore), time(notAfter)),
+ subject,
+ spki,
+ );
+ return sequence(tbs, algorithm, bitString(options.sign(tbs)));
+}
diff --git a/build-tools/utils/zip.d.ts b/build-tools/utils/zip.d.ts
index 73b4915f8..3746c1887 100644
--- a/build-tools/utils/zip.d.ts
+++ b/build-tools/utils/zip.d.ts
@@ -8,9 +8,21 @@ export interface ZipEntry {
/** Path inside the archive, with forward slashes. */
name: string;
data: Buffer;
+ /** Store uncompressed — for an entry the OS mmaps out of the package. */
+ store?: boolean;
+ /** Byte boundary the entry's data must start on (stored entries only). */
+ align?: number;
+}
+
+export interface ZipLayout {
+ eocdOffset: number;
+ centralDirOffset: number;
+ centralDirSize: number;
+ entryCount: number;
}
export function makeZip(entries: readonly ZipEntry[]): Buffer;
+export function zipLayout(buf: Buffer): ZipLayout;
export function zipTree(dir: string, prefix?: string): ZipEntry[];
export function readZip(buf: Buffer): ZipEntry[];
export function extractZip(buf: Buffer, destDir: string): string[];
diff --git a/build-tools/utils/zip.js b/build-tools/utils/zip.js
index 5bb100ece..6aec23515 100644
--- a/build-tools/utils/zip.js
+++ b/build-tools/utils/zip.js
@@ -40,9 +40,16 @@ const DOS_TIME = 0;
const DOS_DATE = 0x0021;
/**
- * Build a ZIP archive holding `entries` ({ name, data }), each deflated.
+ * Build a ZIP archive holding `entries`, each deflated unless it asks to be
+ * stored.
*
- * @param {ReadonlyArray<{name: string, data: Buffer}>} entries
+ * `store` and `align` are what an APK needs: an entry the OS wants to mmap out of
+ * the package (an uncompressed `.so`, a resource table) must be stored AND start
+ * at an aligned offset, which is achieved by padding the local header's extra
+ * field — the same thing `zipalign` does, done while writing rather than by
+ * rewriting the archive afterwards.
+ *
+ * @param {ReadonlyArray<{name: string, data: Buffer, store?: boolean, align?: number}>} entries
* @returns {Buffer}
*/
export function makeZip(entries) {
@@ -52,36 +59,44 @@ export function makeZip(entries) {
for (const entry of entries) {
const name = Buffer.from(entry.name, 'utf8');
- const compressed = deflateRawSync(entry.data, { level: 9 });
+ const stored = entry.store === true;
+ const payload = stored ? entry.data : deflateRawSync(entry.data, { level: 9 });
const crc = crc32(entry.data);
+ // Padding goes in the extra field, so the entry's DATA lands on the
+ // boundary. Only meaningful for stored entries — nothing can mmap a
+ // deflated one — so alignment is not silently promised where it is a lie.
+ const align = stored ? (entry.align ?? 0) : 0;
+ const dataAt = offset + 30 + name.length;
+ const extra = align > 1 ? Buffer.alloc((align - (dataAt % align)) % align) : Buffer.alloc(0);
+
const local = Buffer.alloc(30);
local.writeUInt32LE(0x04034b50, 0);
local.writeUInt16LE(20, 4); // version needed
local.writeUInt16LE(0x0800, 6); // UTF-8 names
- local.writeUInt16LE(8, 8); // deflate
+ local.writeUInt16LE(stored ? 0 : 8, 8);
local.writeUInt16LE(DOS_TIME, 10);
local.writeUInt16LE(DOS_DATE, 12);
local.writeUInt32LE(crc, 14);
- local.writeUInt32LE(compressed.length, 18);
+ local.writeUInt32LE(payload.length, 18);
local.writeUInt32LE(entry.data.length, 22);
local.writeUInt16LE(name.length, 26);
- local.writeUInt16LE(0, 28); // no extra field
- locals.push(local, name, compressed);
+ local.writeUInt16LE(extra.length, 28);
+ locals.push(local, name, extra, payload);
const central = Buffer.alloc(46);
central.writeUInt32LE(0x02014b50, 0);
central.writeUInt16LE(20, 4); // version made by
central.writeUInt16LE(20, 6); // version needed
central.writeUInt16LE(0x0800, 8);
- central.writeUInt16LE(8, 10);
+ central.writeUInt16LE(stored ? 0 : 8, 10);
central.writeUInt16LE(DOS_TIME, 12);
central.writeUInt16LE(DOS_DATE, 14);
central.writeUInt32LE(crc, 16);
- central.writeUInt32LE(compressed.length, 20);
+ central.writeUInt32LE(payload.length, 20);
central.writeUInt32LE(entry.data.length, 24);
central.writeUInt16LE(name.length, 28);
- central.writeUInt16LE(0, 30); // extra
+ central.writeUInt16LE(0, 30); // extra — local only; the reader uses the local header's
central.writeUInt16LE(0, 32); // comment
central.writeUInt16LE(0, 34); // disk
central.writeUInt16LE(0, 36); // internal attrs
@@ -89,7 +104,7 @@ export function makeZip(entries) {
central.writeUInt32LE(offset, 42);
centrals.push(central, name);
- offset += local.length + name.length + compressed.length;
+ offset += local.length + name.length + extra.length + payload.length;
}
const centralSize = centrals.reduce((n, b) => n + b.length, 0);
@@ -130,22 +145,39 @@ export function zipTree(dir, prefix = '') {
}
/**
- * Read an archive's entries, through its central directory (the authority on what
- * an archive contains — trailing local headers may be stale).
+ * Where an archive's three sections are.
+ *
+ * The APK signature covers them separately (and rewrites the central directory's
+ * offset), so the layout has to be readable rather than assumed.
*
* @param {Buffer} buf
- * @returns {Array<{name: string, data: Buffer}>}
+ * @returns {{eocdOffset: number, centralDirOffset: number, centralDirSize: number, entryCount: number}}
*/
-export function readZip(buf) {
+export function zipLayout(buf) {
// The end-of-central-directory record is last, but a comment may follow it.
let eocd = -1;
for (let i = buf.length - 22; i >= 0 && i >= buf.length - 22 - 0xffff; i--) {
if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
}
if (eocd < 0) throw new Error('not a ZIP archive (no end-of-central-directory record)');
+ return {
+ eocdOffset: eocd,
+ centralDirOffset: buf.readUInt32LE(eocd + 16),
+ centralDirSize: buf.readUInt32LE(eocd + 12),
+ entryCount: buf.readUInt16LE(eocd + 10),
+ };
+}
- const count = buf.readUInt16LE(eocd + 10);
- let p = buf.readUInt32LE(eocd + 16);
+/**
+ * Read an archive's entries, through its central directory (the authority on what
+ * an archive contains — trailing local headers may be stale).
+ *
+ * @param {Buffer} buf
+ * @returns {Array<{name: string, data: Buffer}>}
+ */
+export function readZip(buf) {
+ const { centralDirOffset, entryCount: count } = zipLayout(buf);
+ let p = centralDirOffset;
const out = [];
for (let i = 0; i < count; i++) {
if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error('corrupt ZIP central directory');
diff --git a/desktop/tests/android-apk.test.ts b/desktop/tests/android-apk.test.ts
new file mode 100644
index 000000000..990983a61
--- /dev/null
+++ b/desktop/tests/android-apk.test.ts
@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The APK assembler: a binary manifest, an aligned zip and an APK Signature
+// Scheme v2 block, all written here rather than shelled out to the Android SDK.
+//
+// Three formats we implement ourselves means three places where "it looked right
+// to us" is worth nothing, so every claim is checked by something that is not us:
+//
+// * the signature, by build-tools/tests/verify-apk.py — a second implementation
+// of the scheme, from the spec, on Python's standard library alone;
+// * the manifest, by androguard's decoder (skipped where it isn't installed),
+// and its resource ids against AOSP's own public.xml table;
+// * the archive, by a real `unzip`.
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assembleApk, apkFileName } from '../../build-tools/utils/apk.js';
+import { debugSigningKey } from '../../build-tools/utils/androidKeystore.js';
+import { compileManifest, ANDROID_ATTR_IDS } from '../../build-tools/utils/androidBinaryXml.js';
+import { zipLayout } from '../../build-tools/utils/zip.js';
+
+const REPO = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const VERIFIER = path.join(REPO, 'build-tools', 'tests', 'verify-apk.py');
+const MANIFEST_TEMPLATE = path.join(REPO, 'native', 'android', 'host', 'AndroidManifest.xml.in');
+
+const APP = {
+ id: 'com.example.demo', name: 'My Game', version: '1.2', versionCode: 7,
+ orientation: 'portrait' as const,
+};
+
+let scratch: string;
+let templateDir: string;
+let contentDir: string;
+
+/** python3 ships with macOS and most Linux; skip rather than fail where it doesn't. */
+let hasPython = true;
+/** androguard is an optional deeper oracle — the signature check needs neither it
+ * nor any other package. */
+let hasAndroguard = false;
+
+beforeAll(() => {
+ try {
+ execFileSync('python3', ['-c', 'pass'], { stdio: 'ignore' });
+ } catch {
+ hasPython = false;
+ }
+ if (hasPython) {
+ try {
+ execFileSync('python3', ['-c', 'import androguard'], { stdio: 'ignore' });
+ hasAndroguard = true;
+ } catch { /* the stdlib checks still run */ }
+ }
+});
+
+beforeEach(() => {
+ scratch = mkdtempSync(path.join(tmpdir(), 'es-apk-'));
+ process.env.ESTELLA_ANDROID_KEYS = path.join(scratch, 'keys');
+
+ // A stand-in template: the assembler cares about the layout, not about what is
+ // inside a .so. Big enough that alignment has something to align.
+ templateDir = path.join(scratch, 'template');
+ mkdirSync(path.join(templateDir, 'lib', 'arm64-v8a'), { recursive: true });
+ mkdirSync(path.join(templateDir, 'assets'), { recursive: true });
+ writeFileSync(path.join(templateDir, 'AndroidManifest.xml.in'), readFileSync(MANIFEST_TEMPLATE));
+ writeFileSync(path.join(templateDir, 'lib/arm64-v8a/libestella_js_host.so'), Buffer.alloc(120_000, 7));
+ writeFileSync(path.join(templateDir, 'lib/arm64-v8a/libwebgpu_dawn.so'), Buffer.alloc(90_000, 9));
+ writeFileSync(path.join(templateDir, 'classes.dex'), Buffer.from('dex\n035\0stand-in'));
+ writeFileSync(path.join(templateDir, 'assets', 'esengine.native.qjsbc'), Buffer.alloc(2048, 3));
+
+ contentDir = path.join(scratch, 'dist-android');
+ mkdirSync(path.join(contentDir, 'assets', 'scenes'), { recursive: true });
+ writeFileSync(path.join(contentDir, 'game.config.json'), '{"entryScene":"main"}');
+ writeFileSync(path.join(contentDir, 'assets/scenes/main.esscene'), '{"entities":[]}');
+ writeFileSync(path.join(contentDir, '.DS_Store'), 'litter');
+});
+
+afterEach(() => {
+ delete process.env.ESTELLA_ANDROID_KEYS;
+ rmSync(scratch, { recursive: true, force: true });
+});
+
+function build(app = APP): string {
+ const apk = assembleApk({ templateDir, contentDir, app, abi: 'arm64-v8a', key: debugSigningKey() });
+ const file = path.join(contentDir, apkFileName(app.id));
+ writeFileSync(file, apk);
+ return file;
+}
+
+function verify(apk: string): {
+ signedV2: boolean; entries: number;
+ manifest: null | Record<string, unknown>;
+} {
+ return JSON.parse(execFileSync('python3', [VERIFIER, apk], { encoding: 'utf8' }));
+}
+
+describe('the manifest is compiled, not shelled out to aapt2', () => {
+ it('uses the resource ids AOSP publishes — the platform resolves attributes by id', () => {
+ if (!hasAndroguard) return;
+ const dump = execFileSync('python3', ['-c',
+ 'from androguard.core.resources.public import SYSTEM_RESOURCES;'
+ + 'import json;print(json.dumps(SYSTEM_RESOURCES["attributes"]["forward"]))',
+ ], { encoding: 'utf8' });
+ const aosp: Record<string, number> = JSON.parse(dump);
+
+ for (const [attribute, id] of Object.entries(ANDROID_ATTR_IDS)) {
+ expect(`${attribute}=${id}`).toBe(`${attribute}=${aosp[attribute]}`);
+ }
+ });
+
+ it('round-trips through an independent decoder with every value intact', () => {
+ if (!hasAndroguard) return;
+ const file = path.join(scratch, 'AndroidManifest.xml');
+ writeFileSync(file, compileManifest(readFileSync(MANIFEST_TEMPLATE, 'utf8')
+ .replace(/@APP_ID@/g, 'com.example.demo').replace(/@APP_NAME@/g, 'My Game')
+ .replace(/@VERSION_NAME@/g, '1.2').replace(/@VERSION_CODE@/g, '7')
+ .replace(/@SCREEN_ORIENTATION@/g, 'sensorPortrait').replace(/@HAS_CODE@/g, 'true')));
+
+ const xml = execFileSync('python3', ['-c',
+ 'import sys,os;os.environ["LOGURU_LEVEL"]="CRITICAL";'
+ + 'from androguard.core.axml import AXMLPrinter;'
+ + 'print(AXMLPrinter(open(sys.argv[1],"rb").read()).get_xml().decode())', file,
+ ], { encoding: 'utf8' });
+
+ expect(xml).toContain('package="com.example.demo"');
+ expect(xml).toContain('android:versionCode="7"');
+ expect(xml).toContain('android:label="My Game"');
+ expect(xml).toContain('android:screenOrientation="sensorPortrait"');
+ // A framework style survives as a REFERENCE to the id, not as its text.
+ expect(xml).toContain('android:theme="@android:01030007"');
+ expect(xml).toContain('android:name="android.app.NativeActivity"');
+ expect(xml).toContain('android.intent.category.LAUNCHER');
+ });
+
+ it('refuses an attribute whose id it does not know, rather than dropping it', () => {
+ expect(() => compileManifest(
+ '<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:invented="1"/>',
+ )).toThrow(/android:invented/);
+ });
+});
+
+describe('assembling an APK', () => {
+ it('produces an archive a real unzip accepts, carrying every part of the app', () => {
+ const apk = build();
+ expect(execFileSync('unzip', ['-t', apk], { encoding: 'utf8' })).toContain('No errors detected');
+
+ const names = execFileSync('unzip', ['-Z1', apk], { encoding: 'utf8' }).trim().split('\n');
+ expect(names).toContain('AndroidManifest.xml');
+ expect(names).toContain('classes.dex');
+ expect(names).toContain('lib/arm64-v8a/libestella_js_host.so');
+ expect(names).toContain('lib/arm64-v8a/libwebgpu_dawn.so');
+ expect(names).toContain('assets/esengine.native.qjsbc');
+ // The export directory BECOMES assets/, so the cooked tree keeps the
+ // project-relative paths the host's readAsset() asks for.
+ expect(names).toContain('assets/game.config.json');
+ expect(names).toContain('assets/assets/scenes/main.esscene');
+ // Build-machine litter stays out of the package.
+ expect(names).not.toContain('assets/.DS_Store');
+ });
+
+ it('stores native libraries uncompressed on a 16 KiB boundary, so the OS can map them', () => {
+ const apk = readFileSync(build());
+ const { centralDirOffset } = zipLayout(apk);
+
+ let checked = 0;
+ // Entries run until the signing block, which sits just before the central
+ // directory — so walk while local headers keep appearing.
+ for (let at = 0; at < centralDirOffset && apk.readUInt32LE(at) === 0x04034b50;) {
+ const method = apk.readUInt16LE(at + 8);
+ const compressedSize = apk.readUInt32LE(at + 18);
+ const nameLen = apk.readUInt16LE(at + 26);
+ const extraLen = apk.readUInt16LE(at + 28);
+ const name = apk.toString('utf8', at + 30, at + 30 + nameLen);
+ const dataAt = at + 30 + nameLen + extraLen;
+ if (name.endsWith('.so')) {
+ expect(method).toBe(0); // stored
+ expect(dataAt % 16384).toBe(0);
+ checked++;
+ }
+ at = dataAt + compressedSize;
+ }
+ expect(checked).toBe(2);
+ });
+
+ it('is named after the app, so a second project does not replace the first', () => {
+ expect(path.basename(build())).toBe('demo.apk');
+ expect(apkFileName('com.acme.spaceGame')).toBe('spaceGame.apk');
+ });
+
+ it('does not swallow the APK a previous export left in the directory', () => {
+ build();
+ const again = build();
+
+ const names = execFileSync('unzip', ['-Z1', again], { encoding: 'utf8' });
+ expect(names).not.toContain('assets/demo.apk');
+ });
+});
+
+describe('the v2 signature, checked by an independent implementation', () => {
+ it('verifies: the digest covers the file and the certificate carries the signing key', () => {
+ if (!hasPython) return;
+ const result = verify(build());
+
+ expect(result.signedV2).toBe(true);
+ expect(result.entries).toBeGreaterThan(6);
+ if (hasAndroguard) {
+ expect(result.manifest).toMatchObject({
+ package: 'com.example.demo',
+ label: 'My Game',
+ versionName: '1.2',
+ versionCode: '7',
+ mainActivity: 'android.app.NativeActivity',
+ valid: true,
+ });
+ }
+ });
+
+ it('fails once a single byte of the payload changes', () => {
+ if (!hasPython) return;
+ const apk = readFileSync(build());
+ // Somewhere inside the first entry's data, well before the signing block.
+ const tampered = Buffer.from(apk);
+ tampered[600] ^= 0xff;
+ const file = path.join(scratch, 'tampered.apk');
+ writeFileSync(file, tampered);
+
+ expect(() => verify(file)).toThrow();
+ });
+
+ it('reuses the development key, so an update installs over the app it replaces', () => {
+ const first = debugSigningKey();
+ const second = debugSigningKey();
+
+ expect(second.certificate.equals(first.certificate)).toBe(true);
+ expect(existsSync(path.join(scratch, 'keys', 'debug.cert.pem'))).toBe(true);
+ });
+
+ it('writes a certificate openssl reads back as the identity it claims', () => {
+ const pem = path.join(scratch, 'keys', 'debug.cert.pem');
+ debugSigningKey();
+
+ const text = execFileSync('openssl', ['x509', '-in', pem, '-noout', '-subject', '-issuer'], { encoding: 'utf8' });
+
+ // Self-signed: the issuer line and the subject line say the same thing.
+ // (Spacing differs between OpenSSL and the LibreSSL macOS ships.)
+ expect(text).toMatch(/subject=.*CN\s?=\s?Estella Debug/);
+ expect(text).toMatch(/issuer=.*CN\s?=\s?Estella Debug/);
+ });
+});
diff --git a/native/android/host/AndroidManifest.xml.in b/native/android/host/AndroidManifest.xml.in
index 19738a07e..bca415711 100644
--- a/native/android/host/AndroidManifest.xml.in
+++ b/native/android/host/AndroidManifest.xml.in
@@ -15,7 +15,7 @@
android:versionName="@VERSION_NAME@">
<uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" />
<uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
- <application android:label="@APP_NAME@" android:hasCode="@HAS_CODE@" android:extractNativeLibs="true">
+ <application android:label="@APP_NAME@" android:hasCode="@HAS_CODE@" android:extractNativeLibs="false">
<!-- A game's window, stated before any code runs: no title, no status bar.
The host asks for the rest (navigation bar, display cutout) once it
has the UI thread — see onWindowFocusChanged in platform/android.cpp. -->