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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.pynew file mode 100644index 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.jsnew file mode 100644index 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.tsnew file mode 100644index 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.jsnew file mode 100644index 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.tsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.tsindex 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.jsindex 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 neededlocal.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 bycentral.writeUInt16LE(20, 6); // version neededcentral.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'scentral.writeUInt16LE(0, 32); // commentcentral.writeUInt16LE(0, 34); // diskcentral.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.tsnew file mode 100644index 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.inindex 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 ithas the UI thread — see onWindowFocusChanged in platform/android.cpp. -->