frida-ui-runtime 2.0.0

package/README.md

@@ -0,0 +1,181 @@
+# frida-ui-runtime
+
+Lifecycle-safe Android overlay UI runtime for Frida scripts.
+
+The runtime creates native Android views through the consumer-installed
+`frida-java-bridge` peer dependency. The consumer selects the bridge version;
+the runtime validates the capabilities it needs and never depends on a
+REPL-provided global `Java` object.
+
+## Requirements
+
+- Frida with Java support in the target Android process
+- Overlay permission for the target application
+- Android `WindowManager` access
+- `frida-compile` for bundling TypeScript entrypoints
+
+## Install
+
+```bash
+npm install frida-ui-runtime frida-java-bridge
+```
+
+## Quick Start
+
+```typescript
+import {
+  Button,
+  FloatMenu,
+  Slider,
+  Switch,
+  TextView,
+} from "frida-ui-runtime";
+
+async function main(): Promise<void> {
+  const menu = await FloatMenu.launch({
+    title: "Runtime Tools",
+    width: 820,
+    height: 1100,
+    icon: {
+      base64: iconBase64,
+      width: 160,
+      height: 160,
+    },
+    tabs: [
+      { id: "controls", label: "Controls" },
+      { id: "status", label: "Status" },
+    ],
+    activeTab: "controls",
+  }, async menu => {
+    await menu.addComponent(
+      new Switch("enabled", "Enabled", false),
+      "controls",
+    );
+    await menu.addComponent(
+      new Slider("level", "Level", 0, 10, 3),
+      "controls",
+    );
+    await menu.addComponent(
+      new Button("run", "Run", "primary", () => console.log("run")),
+      "controls",
+    );
+    await menu.addComponent(
+      new TextView("status", "Ready"),
+      "status",
+    );
+  });
+
+  // Components remain dynamic after the floating icon is visible.
+  await menu.addComponent(new TextView("late", "Added later"), "status");
+}
+
+void main().catch(error => console.error(error));
+```
+
+The entrypoint runs directly in a Gadget local script and does not require a
+REPL. `FloatMenu.launch()` waits for the consumer-provided Java Bridge, Android
+application context, and main thread. It shows the floating icon only after the
+setup callback completes.
+
+`frida-java-bridge` is an unrestricted peer dependency. Install one bridge
+version in the consuming project and let the package manager resolve both the
+application and this runtime to that instance. Version `7.0.4` is only the
+library's development and regression-test baseline.
+
+At startup the runtime checks for `use`, `scheduleOnMainThread`, and either
+`performNow` or `perform`. An incompatible bridge fails early with
+`JavaBridgeCompatibilityError` and a list of missing capabilities.
+
+## Lifecycle
+
+`FloatMenu` serializes lifecycle operations so concurrent calls cannot attach or detach the same window twice.
+
+```typescript
+await menu.mount();          // Create and attach both windows, initially hidden
+await menu.present("icon"); // Show only the floating icon
+await menu.present("menu"); // Show only the menu
+await menu.conceal();        // Hide visually; keep the icon hotspot touchable
+await menu.toggle();         // Toggle icon/menu presentation
+await menu.dispose();        // Remove windows and release listeners/components
+```
+
+`FloatMenu.create()` remains available as a low-level API that returns a hidden
+menu. Prefer `FloatMenu.launch()` for Gadget entrypoints. Calling `present()`
+without a mode defaults to the floating icon.
+
+The minimize button returns to the visible icon. The close button calls
+`conceal()`: both surfaces disappear visually, but the icon window stays
+transparent and touchable at its previous position. Tapping that location opens
+the menu directly. The close interaction also shows a Toast explaining where to
+tap. The views and component state remain mounted throughout.
+
+Use `dispose()` only when the overlay is no longer needed and its state may be
+released.
+
+## State
+
+```typescript
+const snapshot = menu.captureState();
+await menu.conceal();
+
+await menu.present("menu");
+menu.restoreState(snapshot);
+```
+
+Component IDs must be unique. Duplicate IDs are rejected instead of silently replacing an existing component.
+
+Components can be added or removed after launch, including while the overlay is
+concealed:
+
+```typescript
+await menu.conceal();
+await menu.addComponent(new TextView("dynamic", "Added while hidden"));
+await menu.removeComponent("dynamic");
+await menu.present();
+```
+
+## Overlay Permission
+
+Permission is checked before any window is attached. If permission is missing,
+the runtime shows a Toast and throws `OverlayPermissionError`. Override the
+Toast text with `permissionDeniedMessage` when needed.
+
+## Custom Icon
+
+`icon.base64` accepts raw Base64 or a `data:image/...;base64,` value. File paths
+and network URLs are intentionally unsupported. Invalid image data fails launch
+with `InvalidOverlayIconError` instead of creating a blank icon window.
+
+## Components
+
+The root package exports:
+
+- `Button`
+- `Category`
+- `CheckBoxGroup`
+- `Collapsible`
+- `NumberInput`
+- `Selector`
+- `Slider`
+- `Switch`
+- `TextInput`
+- `TextView` (`Text` alias)
+- `UIComponent` for custom controls
+
+All component callbacks are isolated from the Java listener boundary. Callback failures are logged instead of escaping into Android's UI thread.
+
+## Build And Test
+
+```bash
+npm test
+npx frida-compile tests/device/overlay-smoke.ts -o tests/device/overlay-smoke.js
+```
+
+The repository includes an independent Android host app in `android-test-app`. Device testing does not load an application's production Frida script.
+
+## Compatibility Notes
+
+- Window type selection checks available framework fields instead of trusting spoofable `SDK_INT` values.
+- Application context lookup falls back across `ActivityThread` and `AppGlobals`.
+- `WindowManager` wrappers are validated for `addView`, `updateViewLayout`, and `removeView`. This handles environments where a module such as Guise allows an interface cast but hides the inherited `ViewManager` methods.
+- Display metrics are validated before use and fall back to real display metrics when spoofed values are invalid.

package/lib/android-listener.d.ts

@@ -0,0 +1,20 @@
+type JavaCallback = (...args: any[]) => any;
+export interface JavaListenerHandle {
+    readonly instance: any;
+    $new(): any;
+    dispose(): void;
+}
+export interface JavaListenerOptions {
+    key: string;
+    owner?: string;
+    interfaceClass: any;
+    callbacks: Record<string, JavaCallback>;
+    fallback?: Record<string, any>;
+}
+export declare function createJavaListener(options: JavaListenerOptions): JavaListenerHandle;
+export declare function disposeJavaListenerOwner(owner: string): void;
+export declare function getJavaListenerDiagnostics(): {
+    pools: number;
+    callbacks: number;
+};
+export {};

package/lib/android-listener.js

@@ -0,0 +1,92 @@
+import Java from "./java-runtime.js";
+import { Logger } from "./logger.js";
+const pools = new Map();
+const owners = new Map();
+const sessionSuffix = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
+let nextListenerId = 1;
+function sanitizeClassSegment(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9_]/g, "_");
+    return /^[A-Za-z_]/.test(sanitized) ? sanitized : `L_${sanitized}`;
+}
+function createPool(options) {
+    const callbacks = new Map();
+    const fallback = options.fallback ?? {};
+    const methods = {};
+    for (const methodName of Object.keys(options.callbacks)) {
+        methods[methodName] = function (...args) {
+            const callbackId = String(this.callbackId.value);
+            const callback = callbacks.get(callbackId)?.[methodName];
+            if (!callback)
+                return fallback[methodName];
+            try {
+                return callback(...args);
+            }
+            catch (error) {
+                Logger.instance.error(`[JavaListener:${options.key}.${methodName}] callback failed:`, error);
+                return fallback[methodName];
+            }
+        };
+    }
+    const listenerClass = Java.registerClass({
+        name: `com.fridauiruntime.listener.${sanitizeClassSegment(options.key)}_${sessionSuffix}`,
+        implements: [options.interfaceClass],
+        fields: { callbackId: "java.lang.String" },
+        methods,
+    });
+    return { listenerClass, callbacks, fallback };
+}
+export function createJavaListener(options) {
+    const methodNames = Object.keys(options.callbacks).sort().join(",");
+    const poolKey = `${options.key}:${methodNames}`;
+    let pool = pools.get(poolKey);
+    if (!pool) {
+        pool = createPool(options);
+        pools.set(poolKey, pool);
+    }
+    const callbackId = String(nextListenerId++);
+    pool.callbacks.set(callbackId, options.callbacks);
+    const instance = pool.listenerClass.$new();
+    instance.callbackId.value = callbackId;
+    let disposed = false;
+    const handle = {
+        instance,
+        $new: () => instance,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            pool.callbacks.delete(callbackId);
+            const owned = options.owner ? owners.get(options.owner) : undefined;
+            owned?.delete(handle.dispose);
+            if (options.owner && owned?.size === 0)
+                owners.delete(options.owner);
+            try {
+                instance.callbackId.value = "";
+            }
+            catch { }
+        },
+    };
+    if (options.owner) {
+        let owned = owners.get(options.owner);
+        if (!owned) {
+            owned = new Set();
+            owners.set(options.owner, owned);
+        }
+        owned.add(handle.dispose);
+    }
+    return handle;
+}
+export function disposeJavaListenerOwner(owner) {
+    const owned = owners.get(owner);
+    if (!owned)
+        return;
+    owners.delete(owner);
+    for (const dispose of Array.from(owned))
+        dispose();
+}
+export function getJavaListenerDiagnostics() {
+    let callbacks = 0;
+    for (const pool of pools.values())
+        callbacks += pool.callbacks.size;
+    return { pools: pools.size, callbacks };
+}

package/lib/android-runtime.d.ts

@@ -0,0 +1,25 @@
+export interface JavaRuntime {
+    available?: boolean;
+    use(name: string): any;
+    cast?(value: any, klass: any): any;
+    perform?(callback: () => void): void;
+    performNow?(callback: () => void): void;
+    scheduleOnMainThread?(callback: () => void): void;
+}
+export declare class JavaBridgeCompatibilityError extends Error {
+    constructor(missingCapabilities: string[]);
+}
+export declare function assertJavaBridgeCompatible(java: Partial<JavaRuntime> | null | undefined): asserts java is JavaRuntime;
+export declare function waitForJavaAvailable(java: JavaRuntime, timeoutMs?: number, intervalMs?: number): Promise<void>;
+export declare function runWhenJavaReady<T>(java: JavaRuntime, operation: () => T, timeoutMs?: number, label?: string): Promise<T>;
+export declare function scheduleOnMainThread<T>(java: JavaRuntime, operation: () => T, timeoutMs?: number, label?: string): Promise<T>;
+export declare function getApplicationContext(java: JavaRuntime): any;
+export declare function waitForApplicationContext(java: JavaRuntime, timeoutMs?: number, intervalMs?: number): Promise<any>;
+export declare function getWindowManager(java: JavaRuntime, context: any): any;
+export declare function readDisplaySize(context: any, windowManager: any): {
+    width: number;
+    height: number;
+};
+export declare function readDisplayDensity(context: any): number;
+export declare function getOverlayWindowType(layoutParams: any): number;
+export declare function ensureWindowNotFocusable(params: any, layoutParams: any): boolean;

package/lib/android-runtime.js

@@ -0,0 +1,310 @@
+export class JavaBridgeCompatibilityError extends Error {
+    constructor(missingCapabilities) {
+        super(`The selected frida-java-bridge is missing required capabilities: ${missingCapabilities.join(", ")}`);
+        this.name = "JavaBridgeCompatibilityError";
+    }
+}
+export function assertJavaBridgeCompatible(java) {
+    const missing = [];
+    if (!java || typeof java.use !== "function")
+        missing.push("use");
+    if (!java
+        || (typeof java.performNow !== "function" && typeof java.perform !== "function")) {
+        missing.push("performNow or perform");
+    }
+    if (!java || typeof java.scheduleOnMainThread !== "function") {
+        missing.push("scheduleOnMainThread");
+    }
+    if (missing.length > 0)
+        throw new JavaBridgeCompatibilityError(missing);
+}
+function performImmediately(java, callback) {
+    const performNow = java.performNow;
+    if (performNow) {
+        performNow.call(java, callback);
+        return;
+    }
+    const perform = java.perform;
+    if (perform)
+        perform.call(java, callback);
+    else
+        callback();
+}
+export function waitForJavaAvailable(java, timeoutMs = 30000, intervalMs = 50) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return Promise.reject(new RangeError("timeoutMs must be greater than zero"));
+    }
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve, reject) => {
+        let timer = null;
+        const check = () => {
+            try {
+                if (java.available !== false) {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve();
+                    return;
+                }
+            }
+            catch { }
+            if (Date.now() >= deadline) {
+                reject(new Error("Timed out waiting for Frida Java Bridge"));
+                return;
+            }
+            timer = setTimeout(check, intervalMs);
+        };
+        check();
+    });
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function runWhenJavaReady(java, operation, timeoutMs = 30000, label = "Java operation") {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Timed out waiting for ${label}`));
+        }, timeoutMs);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            callback();
+        };
+        const run = () => {
+            try {
+                const value = operation();
+                finish(() => resolve(value));
+            }
+            catch (error) {
+                finish(() => reject(error));
+            }
+        };
+        try {
+            performImmediately(java, run);
+        }
+        catch (error) {
+            finish(() => reject(error));
+        }
+    });
+}
+export function scheduleOnMainThread(java, operation, timeoutMs = 30000, label = "Android main thread") {
+    if (!java.scheduleOnMainThread) {
+        return Promise.reject(new Error("Java.scheduleOnMainThread is unavailable"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Timed out waiting for Android main thread: ${label}`));
+        }, timeoutMs);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            callback();
+        };
+        try {
+            java.scheduleOnMainThread(() => {
+                try {
+                    const value = operation();
+                    finish(() => resolve(value));
+                }
+                catch (error) {
+                    finish(() => reject(error));
+                }
+            });
+        }
+        catch (error) {
+            finish(() => reject(error));
+        }
+    });
+}
+function readNumber(value) {
+    const number = Number(value?.value ?? value);
+    return Number.isFinite(number) ? number : Number.NaN;
+}
+function tryCall(callback) {
+    try {
+        return callback() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function getApplication(java) {
+    const activityThread = tryCall(() => java.use("android.app.ActivityThread"));
+    const current = activityThread
+        ? tryCall(() => activityThread.currentApplication())
+        : null;
+    if (current)
+        return current;
+    const appGlobals = tryCall(() => java.use("android.app.AppGlobals"));
+    const initial = appGlobals
+        ? tryCall(() => appGlobals.getInitialApplication())
+        : null;
+    if (initial)
+        return initial;
+    const thread = activityThread
+        ? tryCall(() => activityThread.currentActivityThread())
+        : null;
+    return thread ? tryCall(() => thread.getApplication()) : null;
+}
+export function getApplicationContext(java) {
+    const application = getApplication(java);
+    if (!application) {
+        throw new Error("Android Application is not ready. Call FloatMenu.waitForReady() before constructing the menu.");
+    }
+    const context = tryCall(() => application.getApplicationContext());
+    return context || application;
+}
+export function waitForApplicationContext(java, timeoutMs = 30000, intervalMs = 100) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return Promise.reject(new RangeError("timeoutMs must be greater than zero"));
+    }
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let lastError = null;
+        let retryTimer = null;
+        const hardTimeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            if (retryTimer)
+                clearTimeout(retryTimer);
+            const suffix = lastError == null ? "" : `: ${describeError(lastError)}`;
+            reject(new Error(`Timed out waiting for Android Application context${suffix}`));
+        }, timeoutMs);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(hardTimeout);
+            if (retryTimer)
+                clearTimeout(retryTimer);
+            callback();
+        };
+        const check = () => {
+            const run = () => {
+                try {
+                    const context = getApplicationContext(java);
+                    finish(() => resolve(context));
+                }
+                catch (error) {
+                    lastError = error;
+                    if (Date.now() >= deadline) {
+                        finish(() => reject(new Error(`Timed out waiting for Android Application context: ${describeError(error)}`)));
+                        return;
+                    }
+                    retryTimer = setTimeout(check, intervalMs);
+                }
+            };
+            try {
+                performImmediately(java, run);
+            }
+            catch (error) {
+                lastError = error;
+                if (Date.now() >= deadline) {
+                    finish(() => reject(new Error(`Timed out waiting for Android Application context: ${describeError(error)}`)));
+                    return;
+                }
+                retryTimer = setTimeout(check, intervalMs);
+            }
+        };
+        check();
+    });
+}
+function hasWindowManagerMethods(service) {
+    return service != null
+        && typeof service.addView === "function"
+        && typeof service.updateViewLayout === "function"
+        && typeof service.removeView === "function";
+}
+export function getWindowManager(java, context) {
+    const service = tryCall(() => context.getSystemService("window"));
+    if (!service)
+        throw new Error("Android WindowManager service is unavailable");
+    if (java.cast) {
+        for (const className of ["android.view.WindowManager", "android.view.ViewManager"]) {
+            const klass = tryCall(() => java.use(className));
+            const casted = klass ? tryCall(() => java.cast(service, klass)) : null;
+            if (hasWindowManagerMethods(casted))
+                return casted;
+        }
+    }
+    if (hasWindowManagerMethods(service))
+        return service;
+    throw new Error("Android WindowManager service cannot be used as a ViewManager");
+}
+function readSize(metrics) {
+    const width = readNumber(metrics?.widthPixels);
+    const height = readNumber(metrics?.heightPixels);
+    if (width <= 0 || height <= 0 || width > 32768 || height > 32768)
+        return null;
+    return { width: Math.round(width), height: Math.round(height) };
+}
+export function readDisplaySize(context, windowManager) {
+    const metrics = tryCall(() => context.getResources().getDisplayMetrics());
+    const resourceSize = readSize(metrics);
+    if (resourceSize)
+        return resourceSize;
+    if (metrics) {
+        const display = tryCall(() => windowManager.getDefaultDisplay());
+        if (display) {
+            tryCall(() => display.getRealMetrics(metrics));
+            const realSize = readSize(metrics);
+            if (realSize)
+                return realSize;
+            tryCall(() => display.getMetrics(metrics));
+            const displaySize = readSize(metrics);
+            if (displaySize)
+                return displaySize;
+        }
+    }
+    throw new Error("Android display metrics are invalid or unavailable");
+}
+export function readDisplayDensity(context) {
+    const metrics = tryCall(() => context.getResources().getDisplayMetrics());
+    const density = readNumber(metrics?.density);
+    return density >= 0.25 && density <= 8 ? density : 1;
+}
+export function getOverlayWindowType(layoutParams) {
+    for (const fieldName of [
+        "TYPE_APPLICATION_OVERLAY",
+        "TYPE_PHONE",
+        "TYPE_SYSTEM_ALERT",
+    ]) {
+        const type = readNumber(layoutParams?.[fieldName]);
+        if (Number.isInteger(type) && type > 0)
+            return type;
+    }
+    throw new Error("No supported Android overlay window type is available");
+}
+export function ensureWindowNotFocusable(params, layoutParams) {
+    if (!params)
+        throw new Error("Window layout params are unavailable");
+    const flag = readNumber(layoutParams?.FLAG_NOT_FOCUSABLE);
+    if (!Number.isInteger(flag) || flag <= 0) {
+        throw new Error("FLAG_NOT_FOCUSABLE is unavailable");
+    }
+    const current = readNumber(params.flags);
+    const normalizedCurrent = Number.isInteger(current) ? current : 0;
+    const next = normalizedCurrent | flag;
+    if (next === normalizedCurrent)
+        return false;
+    if (params.flags && typeof params.flags === "object" && "value" in params.flags) {
+        params.flags.value = next;
+    }
+    else {
+        params.flags = next;
+    }
+    return true;
+}

package/lib/api.d.ts

@@ -0,0 +1 @@
+export declare const API: Record<string, any>;