frida 16.2.1 → 16.2.3

package/lib/script.ts

@@ -0,0 +1,352 @@
+import { Cancellable } from "./cancellable";
+import { Signals, Signal, SignalHandler, SignalAdapter } from "./signals";
+
+import { inspect } from "util";
+
+export class Script {
+    destroyed: Signal<ScriptDestroyedHandler>;
+    message: Signal<ScriptMessageHandler>;
+
+    private exportsProxy: any;
+    private logHandlerImpl: ScriptLogHandler = log;
+
+    constructor(private impl: any) {
+        const services = new ScriptServices(this, impl.signals);
+
+        const rpcController: RpcController = services;
+        this.exportsProxy = new ScriptExportsProxy(rpcController);
+
+        const signals: Signals = services;
+        this.destroyed = new Signal<ScriptDestroyedHandler>(signals, "destroyed");
+        this.message = new Signal<ScriptMessageHandler>(signals, "message");
+    }
+
+    get isDestroyed(): boolean {
+        return this.impl.isDestroyed;
+    }
+
+    get exports(): ScriptExports {
+        return this.exportsProxy;
+    }
+
+    get logHandler(): ScriptLogHandler {
+        return this.logHandlerImpl;
+    }
+
+    set logHandler(handler: ScriptLogHandler) {
+        this.logHandlerImpl = handler;
+    }
+
+    get defaultLogHandler(): ScriptLogHandler {
+        return log;
+    }
+
+    load(cancellable?: Cancellable): Promise<void> {
+        return this.impl.load(cancellable);
+    }
+
+    unload(cancellable?: Cancellable): Promise<void> {
+        return this.impl.unload(cancellable);
+    }
+
+    eternalize(cancellable?: Cancellable): Promise<void> {
+        return this.impl.eternalize(cancellable);
+    }
+
+    post(message: any, data: Buffer | null = null): void {
+        this.impl.post(message, data);
+    }
+
+    enableDebugger(options: EnableDebuggerOptions = {}, cancellable?: Cancellable): Promise<void> {
+        const { port = 0 } = options;
+
+        return this.impl.enableDebugger(port, cancellable);
+    }
+
+    disableDebugger(cancellable?: Cancellable): Promise<void> {
+        return this.impl.disableDebugger(cancellable);
+    }
+
+    [inspect.custom](depth, options) {
+        return "Script {}";
+    }
+}
+
+export interface ScriptOptions {
+    name?: string;
+    snapshot?: Buffer;
+    runtime?: ScriptRuntime;
+}
+
+export interface SnapshotOptions {
+    warmupScript?: string;
+    runtime?: ScriptRuntime;
+}
+
+export enum ScriptRuntime {
+    Default = "default",
+    QJS = "qjs",
+    V8 = "v8"
+}
+
+export type ScriptDestroyedHandler = () => void;
+export type ScriptMessageHandler = (message: Message, data: Buffer | null) => void;
+export type ScriptLogHandler = (level: LogLevel, text: string) => void;
+
+export type Message = SendMessage | ErrorMessage;
+
+export enum MessageType {
+    Send = "send",
+    Error = "error"
+}
+
+export interface SendMessage {
+    type: MessageType.Send;
+    payload: any;
+}
+
+export interface ErrorMessage {
+    type: MessageType.Error;
+    description: string;
+    stack?: string;
+    fileName?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+
+interface LogMessage {
+    type: "log";
+    level: LogLevel;
+    payload: string;
+}
+
+export interface ScriptExports {
+    [name: string]: (...args: any[]) => Promise<any>;
+}
+
+export enum LogLevel {
+    Info = "info",
+    Warning = "warning",
+    Error = "error"
+}
+
+export interface EnableDebuggerOptions {
+    port?: number;
+}
+
+class ScriptServices extends SignalAdapter implements RpcController {
+    private pendingRequests: { [id: string]: (error: Error | null, result?: any) => void } = {};
+    private nextRequestId: number = 1;
+
+    constructor(private script: Script, signals: Signals) {
+        super(signals);
+
+        this.signals.connect("destroyed", this.onDestroyed);
+        this.signals.connect("message", this.onMessage);
+    }
+
+    protected getProxy(name: string, userHandler: SignalHandler): SignalHandler | null {
+        if (name === "message") {
+            return (message, data) => {
+                if (!isInternalMessage(message)) {
+                    userHandler(message, data);
+                }
+            };
+        }
+
+        return null;
+    }
+
+    private onDestroyed = () => {
+        this.signals.disconnect("destroyed", this.onDestroyed);
+        this.signals.disconnect("message", this.onMessage);
+    }
+
+    private onMessage = (message: Message, data: Buffer | null) => {
+        if (message.type === MessageType.Send && isRpcSendMessage(message)) {
+            const [ , id, operation, ...params ] = message.payload;
+            this.onRpcMessage(id, operation, params, data);
+        } else if (isLogMessage(message)) {
+            const opaqueMessage: any = message;
+            const logMessage: LogMessage = opaqueMessage;
+            this.script.logHandler(logMessage.level, logMessage.payload);
+        }
+    }
+
+    request(operation: string, params: any[], cancellable?: Cancellable): Promise<any> {
+        return new Promise((resolve, reject) => {
+            const id = this.nextRequestId++;
+
+            const complete = (error: Error | null, result?: any): void => {
+                if (cancellable !== undefined) {
+                    cancellable.cancelled.disconnect(onOperationCancelled);
+                }
+                this.signals.disconnect("destroyed", onScriptDestroyed);
+
+                delete this.pendingRequests[id];
+
+                if (error === null) {
+                    resolve(result);
+                } else {
+                    reject(error);
+                }
+            };
+
+            function onScriptDestroyed(): void {
+                complete(new Error("Script is destroyed"));
+            }
+
+            function onOperationCancelled(): void {
+                complete(new Error("Operation was cancelled"));
+            }
+
+            this.pendingRequests[id] = complete;
+
+            this.script.post(["frida:rpc", id, operation].concat(params));
+            this.signals.connect("destroyed", onScriptDestroyed);
+            if (cancellable !== undefined) {
+                cancellable.cancelled.connect(onOperationCancelled);
+                if (cancellable.isCancelled) {
+                    onOperationCancelled();
+                    return;
+                }
+            }
+            if (this.script.isDestroyed) {
+                onScriptDestroyed();
+            }
+        });
+    }
+
+    onRpcMessage(id: number, operation: RpcOperation, params: any[], data: Buffer | null) {
+        if (operation === RpcOperation.Ok || operation === RpcOperation.Error) {
+            const callback = this.pendingRequests[id];
+            if (callback === undefined) {
+                return;
+            }
+
+            let value = null;
+            let error = null;
+            if (operation === RpcOperation.Ok) {
+                value = (data !== null) ? data : params[0];
+            } else {
+                const [message, name, stack, rawErr] = params;
+                error = new Error(message);
+                error.name = name;
+                error.stack = stack;
+                Object.assign(error, rawErr);
+            }
+
+            callback(error, value);
+        }
+    }
+}
+
+function ScriptExportsProxy(rpcController: RpcController): void {
+    return new Proxy(this, {
+        has(target, property) {
+            return !isReservedMethodName(property);;
+        },
+        get(target, property, receiver) {
+            if (property in target) {
+                return target[property];
+            }
+
+            if (property === inspect.custom) {
+                return inspectProxy;
+            }
+
+            if (isReservedMethodName(property)) {
+                return undefined;
+            }
+
+            return (...args: any[]): Promise<any> => {
+                let cancellable: Cancellable | undefined;
+                if (args[args.length - 1] instanceof Cancellable) {
+                    cancellable = args.pop();
+                }
+
+                return rpcController.request("call", [property, args], cancellable);
+            };
+        },
+        set(target, property, value, receiver) {
+            target[property] = value;
+            return true;
+        },
+        ownKeys(target) {
+            return Object.getOwnPropertyNames(target);
+        },
+        getOwnPropertyDescriptor(target, property) {
+            if (property in target) {
+                return Object.getOwnPropertyDescriptor(target, property);
+            }
+
+            if (isReservedMethodName(property)) {
+                return undefined;
+            }
+
+            return {
+                writable: true,
+                configurable: true,
+                enumerable: true
+            };
+        },
+    });
+}
+
+function inspectProxy() {
+    return "ScriptExportsProxy {}";
+}
+
+interface RpcController {
+    request(operation: string, params: any[], cancellable?: Cancellable): Promise<any>;
+}
+
+enum RpcOperation {
+    Ok = "ok",
+    Error = "error"
+}
+
+function isInternalMessage(message: Message): boolean {
+    return isRpcMessage(message) || isLogMessage(message);
+}
+
+function isRpcMessage(message: Message): boolean {
+    return message.type === MessageType.Send && isRpcSendMessage(message);
+}
+
+function isRpcSendMessage(message: SendMessage): boolean {
+    const payload = message.payload;
+    if (!Array.isArray(payload)) {
+        return false;
+    }
+
+    return payload[0] === "frida:rpc";
+}
+
+function isLogMessage(message: Message): boolean {
+    return message.type as string === "log";
+}
+
+function log(level: LogLevel, text: string): void {
+    switch (level) {
+        case LogLevel.Info:
+            console.log(text);
+            break;
+        case LogLevel.Warning:
+            console.warn(text);
+            break;
+        case LogLevel.Error:
+            console.error(text);
+            break;
+    }
+}
+
+const reservedMethodNames = new Set<string>([
+    "then",
+    "catch",
+    "finally",
+]);
+
+function isReservedMethodName(name: string | number | symbol): boolean {
+    return reservedMethodNames.has(name.toString());
+}

package/lib/session.ts

@@ -0,0 +1,113 @@
+import { Cancellable } from "./cancellable";
+import { Crash } from "./crash";
+import { PortalMembership } from "./portal_membership";
+import { Relay } from "./relay";
+import { Script, ScriptOptions, SnapshotOptions } from "./script";
+import { Signal } from "./signals";
+
+import { inspect } from "util";
+
+export class Session {
+    detached: Signal<SessionDetachedHandler>;
+
+    constructor(private impl: any) {
+        const { signals } = impl;
+        this.detached = new Signal<SessionDetachedHandler>(signals, "detached");
+    }
+
+    get pid(): number {
+        return this.impl.pid;
+    }
+
+    get persistTimeout(): number {
+        return this.impl.persistTimeout;
+    }
+
+    get isDetached(): boolean {
+        return this.impl.isDetached;
+    }
+
+    detach(cancellable?: Cancellable): Promise<void> {
+        return this.impl.detach(cancellable);
+    }
+
+    resume(cancellable?: Cancellable): Promise<void> {
+        return this.impl.resume(cancellable);
+    }
+
+    enableChildGating(cancellable?: Cancellable): Promise<void> {
+        return this.impl.enableChildGating(cancellable);
+    }
+
+    disableChildGating(cancellable?: Cancellable): Promise<void> {
+        return this.impl.disableChildGating(cancellable);
+    }
+
+    async createScript(source: string, options: ScriptOptions = {}, cancellable?: Cancellable): Promise<Script> {
+        const { name = null, snapshot = null, runtime = null } = options;
+
+        return new Script(await this.impl.createScript(source, name, snapshot, runtime, cancellable));
+    }
+
+    async createScriptFromBytes(bytes: Buffer, options: ScriptOptions = {}, cancellable?: Cancellable): Promise<Script> {
+        const { name = null, snapshot = null, runtime = null } = options;
+
+        return new Script(await this.impl.createScriptFromBytes(bytes, name, snapshot, runtime, cancellable));
+    }
+
+    compileScript(source: string, options: ScriptOptions = {}, cancellable?: Cancellable): Promise<Buffer> {
+        const { name = null, runtime = null } = options;
+
+        return this.impl.compileScript(source, name, runtime, cancellable);
+    }
+
+    snapshotScript(embedScript: string, options: SnapshotOptions = {}, cancellable?: Cancellable): Promise<Buffer> {
+        const { warmupScript = null, runtime = null } = options;
+
+        return this.impl.snapshotScript(embedScript, warmupScript, runtime, cancellable);
+    }
+
+    setupPeerConnection(options: PeerOptions = {}, cancellable?: Cancellable): Promise<void> {
+        const {
+            stunServer = null,
+            relays = [],
+        } = options;
+        return this.impl.setupPeerConnection(stunServer, relays, cancellable);
+    }
+
+    async joinPortal(address: string, options: PortalOptions = {}, cancellable?: Cancellable): Promise<PortalMembership> {
+        const {
+            certificate = null,
+            token = null,
+            acl = null,
+        } = options;
+        return new PortalMembership(await this.impl.joinPortal(address, certificate, token, acl, cancellable));
+    }
+
+    [inspect.custom](depth, options) {
+        return "Session " + inspect({
+            pid: this.pid
+        }, options);
+    }
+}
+
+export type SessionDetachedHandler = (reason: SessionDetachReason, crash: Crash | null) => void;
+
+export enum SessionDetachReason {
+    ApplicationRequested = "application-requested",
+    ProcessReplaced = "process-replaced",
+    ProcessTerminated = "process-terminated",
+    ConnectionTerminated = "connection-terminated",
+    DeviceLost = "device-lost"
+}
+
+export interface PeerOptions {
+    stunServer?: string;
+    relays?: Relay[];
+}
+
+export interface PortalOptions {
+    certificate?: string;
+    token?: string;
+    acl?: string[];
+}

package/lib/signals.ts

@@ -0,0 +1,45 @@
+export interface Signals {
+    connect(name: string, handler: SignalHandler): void;
+    disconnect(name: string, handler: SignalHandler): void;
+}
+
+export class Signal<T extends SignalHandler> {
+    constructor(private signals: Signals, private name: string) {
+    }
+
+    connect(handler: T): void {
+        this.signals.connect(this.name, handler);
+    }
+
+    disconnect(handler: T): void {
+        this.signals.disconnect(this.name, handler);
+    }
+}
+
+export type SignalHandler = (...args: any[]) => void;
+
+export class SignalAdapter implements Signals {
+    private proxyHandlers: Map<SignalHandler, SignalHandler> = new Map();
+
+    constructor(protected signals: Signals) {
+    }
+
+    connect(name: string, handler: SignalHandler): void {
+        const proxyHandler = this.getProxy(name, handler);
+        if (proxyHandler !== null) {
+            this.proxyHandlers.set(handler, proxyHandler);
+            this.signals.connect(name, proxyHandler);
+        } else {
+            this.signals.connect(name, handler);
+        }
+    }
+
+    disconnect(name: string, handler: SignalHandler): void {
+        const proxyHandler = this.proxyHandlers.get(handler);
+        this.signals.disconnect(name, (proxyHandler !== undefined) ? proxyHandler : handler);
+    }
+
+    protected getProxy(name: string, userHandler: SignalHandler): SignalHandler | null {
+        return null;
+    }
+}

package/lib/socket_address.ts

@@ -0,0 +1,35 @@
+export type SocketAddress =
+    | IPV4SocketAddress
+    | IPV6SocketAddress
+    | AnonymousUnixSocketAddress
+    | PathUnixSocketAddress
+    | AbstractUnixSocketAddress
+    ;
+
+export interface IPV4SocketAddress {
+    family: "ipv4";
+    address: string;
+    port: number;
+}
+
+export interface IPV6SocketAddress {
+    family: "ipv6";
+    address: string;
+    port: number;
+    flowlabel: number;
+    scopeid: number;
+}
+
+export interface AnonymousUnixSocketAddress {
+    family: "unix:anonymous";
+}
+
+export interface PathUnixSocketAddress {
+    family: "unix:path";
+    path: string;
+}
+
+export interface AbstractUnixSocketAddress {
+    family: "unix:abstract";
+    path: Buffer;
+}

package/lib/spawn.ts

@@ -0,0 +1,4 @@
+export interface Spawn {
+    pid: number;
+    identifier: string | null;
+}

package/lib/system_parameters.ts

@@ -0,0 +1,78 @@
+export interface SystemParameters {
+    /**
+     * Operating System details.
+     */
+    os: {
+        /**
+         * ID, e.g.: windows, macos, linux, ios, android, qnx, fedora, ubuntu, etc.
+         */
+        id: string;
+
+        /**
+         * Human-readable name, e.g. `"macOS"`.
+         */
+        name: string;
+
+        /**
+         * Human-readable version string, e.g. `"11.2.2"`.
+         */
+        version?: string;
+    }
+
+    /**
+     * Platform, same as `Process.platform` in GumJS.
+     */
+    platform: "windows" | "darwin" | "linux" | "qnx";
+
+    /**
+     * Architecture, same as `Process.arch` in GumJS.
+     */
+    arch: "ia32" | "x64" | "arm" | "arm64" | "mips";
+
+    /**
+     * Level of access.
+     */
+    access: "full" | "jailed";
+
+    /**
+     * System name, e.g. `"Ole André’s iPhone"`.
+     */
+    name?: string;
+
+    /**
+     * iOS UDID (Unique Device ID).
+     */
+    udid?: string;
+
+    /**
+     * Details about cellular and networking interfaces.
+     */
+    interfaces?: SystemInterface[];
+
+    /**
+     * Android API level, e.g.: `30`.
+     */
+    apiLevel?: number;
+
+    [name: string]: any;
+}
+
+export type SystemInterface = NetworkInterface | CellularInterface;
+
+export interface NetworkInterface {
+    type: "ethernet" | "wifi" | "bluetooth";
+
+    /**
+     * MAC address, e.g.: `"aa:bb:cc:dd:ee:ff"`.
+     */
+    address: string;
+}
+
+export interface CellularInterface {
+    type: "cellular";
+
+    /**
+     * Phone number, e.g. `"+47 123 45 678"`.
+     */
+    phoneNumber: string;
+}

package/make.bat

@@ -0,0 +1,23 @@
+@setlocal
+@echo off
+rem:: Based on: https://github.com/microsoft/terminal/issues/217#issuecomment-737594785
+goto :_start_
+
+:set_real_dp0
+set dp0=%~dp0
+set "dp0=%dp0:~0,-1%"
+goto :eof
+
+:_start_
+call :set_real_dp0
+
+if not exist "%dp0%\releng\meson\meson.py" (
+  pushd "%dp0%" & git submodule update --init --recursive --depth 1 & popd
+  if %errorlevel% neq 0 exit /b %errorlevel%
+)
+
+endlocal & goto #_undefined_# 2>nul || title %COMSPEC% & python ^
+    -c "import sys; sys.path.insert(0, sys.argv[1]); from releng.meson_make import main; main()" ^
+    "%dp0%" ^
+    .\build ^
+    %*