titanium-apk-recover 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+import { DexFile, DexClassDef } from 'libdex-ts';
+
+/**
+ * Public type definitions for ti_recover.
+ */
+/** Configuration accepted by {@link TiRecover}. */
+interface RecoverConfig {
+    /** Path to the `.apk` file to recover. Relative paths resolve against `cwd`. */
+    apk?: string;
+    /**
+     * Path to an already-extracted APK directory. When provided, the unzip step
+     * is skipped: `classes*.dex` and `AndroidManifest.xml` are read from here.
+     */
+    apkDir?: string;
+    /** Directory where recovered source and assets are written. */
+    outDir?: string;
+    /** Temporary directory used while unpacking the APK. Defaults to `_tmp`. */
+    tmpDir?: string;
+    /** Emit progress logging to the console. Defaults to `false`. */
+    debug?: boolean;
+}
+/** A single recovered source file held in memory. */
+interface RecoveredFile {
+    /** Byte offset of the file inside the encrypted asset blob (0 for dev mode). */
+    offset: number;
+    /** Length in bytes of the recovered content. */
+    bytes: number;
+    /** Recovered file contents. */
+    content: string | Buffer;
+}
+/** Map of relative file path -> recovered file. */
+type MemorySource = Record<string, RecoveredFile>;
+/** Raw values parsed from a decoded `AndroidManifest.xml`. */
+interface ManifestInfo {
+    package?: string;
+    versionCode?: string;
+    versionName?: string;
+    appName?: string;
+    /** Directory the manifest was read from. */
+    dir?: string;
+}
+/** Detected Titanium metadata, returned by {@link TiRecover.info}. */
+interface TitaniumInfo extends ManifestInfo {
+    /** Whether the APK was built in Titanium "development" mode (plain sources). */
+    developmentMode: boolean;
+    /** Coarse Titanium engine version bucket: `"<5"`, `"5.x"` or `"unknown"`. */
+    titaniumVersion: TitaniumVersion;
+    /** Whether the project appears to be built with Alloy. */
+    alloy: boolean;
+    /** Recovered files and their sizes. */
+    files: {
+        name: string;
+        bytes: number;
+    }[];
+    /** Total number of recovered bytes across all files. */
+    totalBytes: number;
+}
+type TitaniumVersion = "<5" | "5.x" | "unknown";
+/** Metadata collected while decrypting the asset blob. */
+interface DecryptMeta {
+    totalBytes: number;
+    titaniumVersion: TitaniumVersion;
+    alloy: boolean;
+}
+/** Result of a decryption pass. */
+interface DecryptResult {
+    files: MemorySource;
+    meta: DecryptMeta;
+}
+
+interface WrittenFile {
+    name: string;
+    bytes: number;
+}
+
+/**
+ * Parses a binary `AndroidManifest.xml` buffer, returning both structured info
+ * and a readable XML serialisation.
+ */
+declare function parseBinaryManifest(bytes: Buffer, dir?: string): {
+    info: ManifestInfo;
+    xml: string;
+};
+/**
+ * Text manifest parser (cheerio) for pre-decoded, human-readable manifests.
+ */
+declare function parseManifest(xml: string, dir?: string): ManifestInfo;
+
+/**
+ * Extract Titanium's encrypted asset data directly from `classes*.dex`,
+ * replacing the apktool (smali) + jadx (java) decompile step.
+ *
+ * The generated `AssetCryptImpl` class has two private static methods:
+ *  - `initAssetsBytes()` builds the encrypted blob by appending a sequence of
+ *    `const-string` literals into a CharBuffer.
+ *  - `initAssets()` fills a HashMap with `put("file", new Range(offset, length))`
+ *    entries.
+ *
+ * Both are ordinary DEX bytecode. We locate the class, then walk each method's
+ * instruction stream: for the blob we collect `const-string`/`const-string/jumbo`
+ * operands in order; for the ranges we do a tiny register trace to recover the
+ * (file, offset, length) triples. A DEX instruction width table lets us step
+ * over every opcode correctly. Since DEX stores real (already-unescaped)
+ * strings, the old Java string-unescape step is gone entirely.
+ */
+
+/** A single file's location inside the decrypted blob, from `initAssets`. */
+interface DexRange {
+    file: string;
+    offset: number;
+    bytes: number;
+}
+interface AssetCrypt {
+    /** The raw encrypted asset blob (last 16 bytes are the AES key). */
+    blob: Buffer;
+    ranges: DexRange[];
+    titaniumVersion: TitaniumVersion;
+}
+type AssetCryptResult = {
+    kind: "classic";
+    data: AssetCrypt;
+} | {
+    kind: "newscheme";
+    salt: Buffer | null;
+} | {
+    kind: "none";
+};
+/** Width, in code units, of the instruction at `idx` (handles payloads). */
+declare function instructionWidth(insns: Uint16Array, idx: number): number;
+/** Collects `const-string` operands from a method in execution order. */
+declare function extractStringChunks(dex: DexFile, insns: Uint16Array): string[];
+/**
+ * Walks `initAssets` with a small register trace to recover the file ranges.
+ * Tracks integer/string constants per register, associates `new Range(off,len)`
+ * with the object register at its `<init>`, and emits an entry when that object
+ * is stored into the map via `put(key, rangeObj)`.
+ */
+declare function extractRanges(dex: DexFile, insns: Uint16Array): DexRange[];
+/**
+ * Extracts static `byte[]` fields (assigned via `fill-array-data` +
+ * `sput-object`) from a method's instruction stream, keyed by field name.
+ */
+declare function extractByteArrayFields(dex: DexFile, insns: Uint16Array): Record<string, Buffer>;
+/** Lifts the ti.cloak `salt` (AES-CBC IV) out of `AssetCryptImpl.<clinit>`. */
+declare function extractCloakSalt(dex: DexFile, classDef: DexClassDef): Buffer | null;
+/**
+ * Locates `AssetCryptImpl` across the given DEX buffers and extracts the
+ * encrypted blob plus file ranges. Returns `newscheme` when the class exists
+ * but lacks `initAssetsBytes` (the ti.cloak/.bin variant), or `none` when the
+ * class is absent entirely.
+ */
+declare function readAssetCrypt(dexBuffers: Uint8Array[], packageHint?: string): AssetCryptResult;
+
+/** A single file's location inside the decrypted asset blob. */
+interface Range {
+    offset: number;
+    bytes: number;
+}
+/** Result of parsing `AssetCryptImpl.smali`'s `initAssetsBytes()`. */
+interface AssetBufferParse {
+    titaniumVersion: TitaniumVersion;
+    bufferLen: number;
+    escaped: string;
+}
+/**
+ * Decodes an integer literal the way `java.lang.Integer.decode` does:
+ * supports optional sign, `0x`/`0X`/`#` hex, leading-zero octal, and decimal.
+ */
+declare function decodeJavaInt(literal: string): number;
+/**
+ * Parses the `hashMap.put("file", new Range(offset, length))` entries from an
+ * `AssetCryptImpl.java` source into an ordered map of file -> range.
+ */
+declare function parseRanges(javaContent: string): Record<string, Range>;
+/**
+ * Parses `AssetCryptImpl.smali`, extracting the declared buffer length, the
+ * concatenated escaped string literal and a coarse Titanium version.
+ */
+declare function parseAssetBuffer(smaliContent: string): AssetBufferParse;
+/** Heuristic: does the recovered file set look like an Alloy project? */
+declare function detectAlloy(files: MemorySource): boolean;
+/**
+ * Decrypts one `[offset, length]` slice of the blob. The key is the last 16
+ * bytes of the blob. Titanium varied two conventions across versions, so we try
+ * the key derived from both `length` and `length - 1`, and the slice from both
+ * `offset` and `offset - 1` (some files have a padded offset).
+ */
+declare function decryptRange(blob: Buffer, offset: number, length: number): string | null;
+interface DecryptRangesResult {
+    files: MemorySource;
+    totalBytes: number;
+}
+/**
+ * Decrypts every range out of the blob into an in-memory source map. Files that
+ * fail to decrypt are skipped rather than aborting the whole run.
+ */
+declare function decryptRanges(blob: Buffer, ranges: DexRange[], debug?: boolean): DecryptRangesResult;
+
+/**
+ * Derives the AES key from a `libti.cloak.so` buffer and the `salt`.
+ * Returns `null` if the buffer is too small or the salt is not 16 bytes.
+ */
+declare function deriveCloakKey(so: Buffer, salt: Buffer): Buffer | null;
+/**
+ * Decrypts one `.bin` asset with AES-128-CBC (IV = salt), transparently
+ * gunzipping the result when it is gzip-compressed. Returns `null` on failure.
+ */
+declare function decryptCloakAsset(bin: Buffer, key: Buffer, salt: Buffer): Buffer | null;
+/** Heuristic: does this buffer look like decoded UTF-8 text (e.g. JS source)? */
+declare function isProbablyText(buf: Buffer): boolean;
+/**
+ * Tries each `libti.cloak.so` buffer, derives a candidate key and confirms it
+ * by decrypting `sampleBin` into readable text. Returns the first working key,
+ * or `null` if none produce a valid decryption.
+ */
+declare function pickCloakKey(cloakLibs: Buffer[], salt: Buffer, sampleBin: Buffer): Buffer | null;
+
+interface BuildInfoInput {
+    manifest: ManifestInfo | null;
+    memorySource: MemorySource;
+    meta?: DecryptMeta;
+    developmentMode: boolean;
+}
+/**
+ * Combines manifest fields, decryption metadata and the recovered file list
+ * into the public {@link TitaniumInfo} shape returned by `TiRecover.info()`.
+ */
+declare function buildInfo(input: BuildInfoInput): TitaniumInfo;
+
+interface ReconstructResult {
+    /** Remapped sources, everything nested under `Resources/`, plus `tiapp.xml`. */
+    memorySource: MemorySource;
+    /** The generated tiapp.xml content. */
+    tiappXml: string;
+    /** Whether the source appears to be an Alloy project. */
+    alloy: boolean;
+    /** Always true; signals that assets should be nested under `Resources/`. */
+    restructured: true;
+}
+/**
+ * Produces a reconstructed, Titanium-openable project from recovered sources.
+ */
+declare function reconstruct(memorySource: MemorySource, info: TitaniumInfo): ReconstructResult;
+/** Builds a minimal but valid classic `tiapp.xml` from recovered metadata. */
+declare function buildTiappXml(info: TitaniumInfo): string;
+
+/**
+ * Thrown when an APK uses Titanium's ti.cloak (.bin) encryption and recovery
+ * could not complete — typically because the hardcoded `salt` or the bundled
+ * `libti.cloak.so` (needed to derive the AES key) is missing.
+ */
+declare class UnsupportedEncryptionError extends Error {
+    constructor(reason?: string);
+}
+/**
+ * Orchestrates recovery of a Titanium APK: unpack, detect, decrypt/extract,
+ * optionally reconstruct a project, and write everything to disk.
+ */
+declare class TiRecover {
+    private readonly cwd;
+    private config;
+    private apkDir;
+    private tmpUsed;
+    private manifest;
+    private dexBuffers;
+    private cloakLibs;
+    private assetCrypt;
+    private developmentMode;
+    private tested;
+    private isTitanium;
+    private memorySource;
+    private meta?;
+    private restructured;
+    constructor(config?: RecoverConfig);
+    /** Absolute output directory (resolved against cwd for relative paths). */
+    private get outDir();
+    private log;
+    /**
+     * Prepares the working directory. If `apkDir` is supplied it is used directly
+     * (reading any `classes*.dex` and manifest found there); otherwise the
+     * configured `apk` is unzipped into `tmpDir`.
+     */
+    init(): Promise<void>;
+    /**
+     * Returns `true` if the prepared APK was built with Titanium (in either
+     * distribution or development mode), populating internal detection state.
+     */
+    test(): Promise<boolean>;
+    /**
+     * Extracts recovered sources into memory. For distribution builds this
+     * decrypts the AES asset blob (from data lifted out of the DEX); for
+     * development builds it reads the plain `assets/Resources` tree.
+     */
+    extract(): Promise<MemorySource>;
+    /**
+     * Attempts ti.cloak (.bin) recovery: derive the AES key from a bundled
+     * `libti.cloak.so` + the `salt` lifted from `AssetCryptImpl`, then AES-128-CBC
+     * decrypt every `Resources/*.bin` asset. Returns the recovered sources, or
+     * `null` when the salt/native lib is missing or no key validates.
+     */
+    private recoverCloak;
+    /**
+     * Returns Titanium metadata for the current APK. Must be called after
+     * {@link extract} to include the recovered file list.
+     */
+    info(): Promise<TitaniumInfo>;
+    /**
+     * Rebuilds the in-memory sources into a Titanium-openable project structure
+     * (everything under `Resources/`, plus a synthesised `tiapp.xml`).
+     */
+    reconstruct(): Promise<MemorySource>;
+    /** Writes the in-memory sources to the configured `outDir`. */
+    writeToDisk(): Promise<WrittenFile[]>;
+    /** Copies the APK's static assets and manifest into `outDir`. */
+    copyAssets(): Promise<void>;
+    /** Removes the temporary directory created during {@link init}. */
+    clean(): Promise<void>;
+}
+interface RecoverOptions extends RecoverConfig {
+    /** Reconstruct an openable Titanium project layout. Defaults to `false`. */
+    reconstruct?: boolean;
+    /** Remove the temporary working directory when finished. Defaults to `true`. */
+    clean?: boolean;
+}
+interface RecoverResult {
+    /** Whether the APK was recognised as a Titanium app and recovered. */
+    recovered: boolean;
+    /** Titanium metadata, present when `recovered` is true. */
+    info?: TitaniumInfo;
+    /** Files written to disk, present when `recovered` is true. */
+    files?: WrittenFile[];
+}
+/**
+ * One-shot recovery: unpack, detect, extract, optionally reconstruct, write to
+ * disk, copy assets and clean up. Returns whether recovery succeeded plus the
+ * gathered info.
+ */
+declare function recover(options: RecoverOptions): Promise<RecoverResult>;
+
+export { type AssetCrypt, type AssetCryptResult, type DecryptMeta, type DecryptResult, type DexRange, type ManifestInfo, type MemorySource, type Range, type RecoverConfig, type RecoverOptions, type RecoverResult, type RecoveredFile, TiRecover, type TitaniumInfo, type TitaniumVersion, UnsupportedEncryptionError, type WrittenFile, buildInfo, reconstruct as buildReconstruct, buildTiappXml, decodeJavaInt, decryptCloakAsset, decryptRange, decryptRanges, deriveCloakKey, detectAlloy, extractByteArrayFields, extractCloakSalt, extractRanges, extractStringChunks, instructionWidth, isProbablyText, parseAssetBuffer, parseBinaryManifest, parseManifest, parseRanges, pickCloakKey, readAssetCrypt, recover };

package/dist/index.js

@@ -0,0 +1,53 @@
+import {
+  TiRecover,
+  UnsupportedEncryptionError,
+  buildInfo,
+  buildTiappXml,
+  decodeJavaInt,
+  decryptCloakAsset,
+  decryptRange,
+  decryptRanges,
+  deriveCloakKey,
+  detectAlloy,
+  extractByteArrayFields,
+  extractCloakSalt,
+  extractRanges,
+  extractStringChunks,
+  instructionWidth,
+  isProbablyText,
+  parseAssetBuffer,
+  parseBinaryManifest,
+  parseManifest,
+  parseRanges,
+  pickCloakKey,
+  readAssetCrypt,
+  reconstruct,
+  recover
+} from "./chunk-ML2DCRT6.js";
+export {
+  TiRecover,
+  UnsupportedEncryptionError,
+  buildInfo,
+  reconstruct as buildReconstruct,
+  buildTiappXml,
+  decodeJavaInt,
+  decryptCloakAsset,
+  decryptRange,
+  decryptRanges,
+  deriveCloakKey,
+  detectAlloy,
+  extractByteArrayFields,
+  extractCloakSalt,
+  extractRanges,
+  extractStringChunks,
+  instructionWidth,
+  isProbablyText,
+  parseAssetBuffer,
+  parseBinaryManifest,
+  parseManifest,
+  parseRanges,
+  pickCloakKey,
+  readAssetCrypt,
+  recover
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "titanium-apk-recover",
+  "version": "2.2.0",
+  "description": "Recover the source code from almost any APK made with Appcelerator Titanium (development, distribution or ti.cloak mode).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "titanium-apk-recover": "./dist/cli.js",
+    "ti_recover": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "appcelerator",
+    "titanium",
+    "apk",
+    "android",
+    "recover",
+    "source",
+    "decompile",
+    "decompiler",
+    "unpack",
+    "extract",
+    "ti.cloak",
+    "reverse-engineering",
+    "cli"
+  ],
+  "author": "Pablo Schaffner",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/puntorigen/ti_recover.git"
+  },
+  "bugs": {
+    "url": "https://github.com/puntorigen/ti_recover/issues"
+  },
+  "homepage": "https://github.com/puntorigen/ti_recover#readme",
+  "dependencies": {
+    "adbkit-apkreader": "^3.2.0",
+    "cheerio": "^1.1.2",
+    "commander": "^15.0.0",
+    "fflate": "^0.8.3",
+    "js-beautify": "^2.0.3",
+    "libdex-ts": "^1.0.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/js-beautify": "^1.14.3",
+    "@types/node": "^26.1.0",
+    "eslint": "^10.6.0",
+    "prettier": "^3.9.4",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.63.0",
+    "vitest": "^4.1.10"
+  }
+}