@efffrida/frida-tools 0.0.1

package/src/FridaSession.ts

@@ -0,0 +1,76 @@
+/**
+ * Frida sessions
+ *
+ * @since 1.0.0
+ */
+
+import type * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import type * as Frida from "frida";
+import type * as FridaDevice from "./FridaDevice.js";
+import type * as FridaSessionError from "./FridaSessionError.js";
+
+import * as internal from "./internal/session.js";
+
+/**
+ * @since 1.0.0
+ * @category Type ids
+ */
+export const FridaSessionTypeId: unique symbol = internal.FridaSessionTypeId;
+
+/**
+ * @since 1.0.0
+ * @category Type ids
+ */
+export type FridaSessionTypeId = typeof FridaSessionTypeId;
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export interface FridaSession {
+    readonly session: Frida.Session;
+    readonly [FridaSessionTypeId]: typeof FridaSessionTypeId;
+}
+
+/**
+ * @since 1.0.0
+ * @category Tags
+ */
+export const FridaSession: Context.Tag<FridaSession, FridaSession> = internal.Tag;
+
+/**
+ * @since 1.0.0
+ * @category Predicates
+ */
+export const isFridaSession: (u: unknown) => u is FridaSession = internal.isFridaSession;
+
+/**
+ * @since 1.0.0
+ * @category Frida
+ */
+export const spawn: (
+    program: string | Array<string>,
+    options?: Frida.SpawnOptions | undefined
+) => Effect.Effect<number, FridaSessionError.FridaSessionError, FridaDevice.FridaDevice | Scope.Scope> = internal.spawn;
+
+/**
+ * @since 1.0.0
+ * @category Frida
+ */
+export const attach: (
+    target: Frida.TargetProcess,
+    options?: Frida.SessionOptions | undefined
+) => Effect.Effect<FridaSession, FridaSessionError.FridaSessionError, FridaDevice.FridaDevice | Scope.Scope> =
+    internal.attach;
+
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layer: (
+    target: string,
+    options?: (Frida.SpawnOptions & Frida.SessionOptions) | undefined
+) => Layer.Layer<FridaSession, FridaSessionError.FridaSessionError, FridaDevice.FridaDevice> = internal.layer;

package/src/FridaSessionError.ts

@@ -0,0 +1,42 @@
+/**
+ * Frida session errors
+ *
+ * @since 1.0.0
+ */
+
+import * as PlatformError from "@effect/platform/Error";
+import * as Predicate from "effect/Predicate";
+
+/**
+ * @since 1.0.0
+ * @category Errors
+ */
+export const FridaSessionErrorTypeId: unique symbol = Symbol.for(
+    "@efffrida/FridaError/FridaSessionError"
+) as FridaSessionErrorTypeId;
+
+/**
+ * @since 1.0.0
+ * @category Errors
+ */
+export type FridaSessionErrorTypeId = typeof FridaSessionErrorTypeId;
+
+/**
+ * @since 1.0.0
+ * @category Errors
+ */
+export const isFridaSessionError = (u: unknown): u is FridaSessionError =>
+    Predicate.hasProperty(u, FridaSessionErrorTypeId);
+
+/**
+ * @since 1.0.0
+ * @category Errors
+ */
+export class FridaSessionError extends PlatformError.TypeIdError(FridaSessionErrorTypeId, "FridaSessionError")<{
+    cause: unknown;
+    when: "spawn" | "kill" | "attach" | "detach" | "compile" | "load" | "unload" | "resume" | "message" | "rpcCall";
+}> {
+    get message() {
+        return `A Frida session error occurred on ${this.when}`;
+    }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Frida devices
+ *
+ * @since 1.0.0
+ */
+export * as FridaDevice from "./FridaDevice.js"
+
+/**
+ * Frida device acquisition errors
+ *
+ * @since 1.0.0
+ */
+export * as FridaDeviceAcquisitionError from "./FridaDeviceAcquisitionError.js"
+
+/**
+ * Frida scripts
+ *
+ * @since 1.0.0
+ */
+export * as FridaScript from "./FridaScript.js"
+
+/**
+ * Frida sessions
+ *
+ * @since 1.0.0
+ */
+export * as FridaSession from "./FridaSession.js"
+
+/**
+ * Frida session errors
+ *
+ * @since 1.0.0
+ */
+export * as FridaSessionError from "./FridaSessionError.js"

package/src/internal/device.ts

@@ -0,0 +1,93 @@
+import type * as FridaDevice from "../FridaDevice.js";
+
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Predicate from "effect/Predicate";
+import * as Frida from "frida";
+import * as FridaDeviceAcquisitionError from "../FridaDeviceAcquisitionError.js";
+
+/** @internal */
+export const FridaDeviceTypeId: FridaDevice.FridaDeviceTypeId = Symbol.for(
+    "@efffrida/frida-tools/FridaDevice"
+) as FridaDevice.FridaDeviceTypeId;
+
+/** @internal */
+export const Tag = Context.GenericTag<FridaDevice.FridaDevice>("@efffrida/frida-tools/FridaDevice");
+
+/** @internal */
+export const isFridaDevice = (u: unknown): u is FridaDevice.FridaDevice => Predicate.hasProperty(u, FridaDeviceTypeId);
+
+/** @internal */
+export const acquireUsbDevice = (
+    options?: Frida.GetDeviceOptions | undefined
+): Effect.Effect<FridaDevice.FridaDevice, FridaDeviceAcquisitionError.FridaDeviceAcquisitionError, never> =>
+    Effect.map(
+        Effect.tryPromise({
+            try: () => Frida.getUsbDevice(options),
+            catch: (cause) =>
+                new FridaDeviceAcquisitionError.FridaDeviceAcquisitionError({
+                    cause,
+                    attempts: 1,
+                    acquisitionMethod: "usb",
+                }),
+        }),
+        (device) => ({ device, [FridaDeviceTypeId]: FridaDeviceTypeId }) as const
+    );
+
+/** @internal */
+export const acquireRemoteDevice = (
+    address: string,
+    options?: Frida.RemoteDeviceOptions | undefined
+): Effect.Effect<FridaDevice.FridaDevice, FridaDeviceAcquisitionError.FridaDeviceAcquisitionError, never> =>
+    Effect.map(
+        Effect.tryPromise({
+            try: () => Frida.getDeviceManager().addRemoteDevice(address, options),
+            catch: (cause) =>
+                new FridaDeviceAcquisitionError.FridaDeviceAcquisitionError({
+                    cause,
+                    attempts: 1,
+                    acquisitionMethod: "remote",
+                }),
+        }),
+        (device) => ({ device, [FridaDeviceTypeId]: FridaDeviceTypeId }) as const
+    );
+
+/** @internal */
+export const acquireLocalDevice = (): Effect.Effect<
+    FridaDevice.FridaDevice,
+    FridaDeviceAcquisitionError.FridaDeviceAcquisitionError,
+    never
+> =>
+    Effect.map(
+        Effect.tryPromise({
+            try: () => Frida.getLocalDevice(),
+            catch: (cause) =>
+                new FridaDeviceAcquisitionError.FridaDeviceAcquisitionError({
+                    cause,
+                    attempts: 1,
+                    acquisitionMethod: "local",
+                }),
+        }),
+        (device) => ({ device, [FridaDeviceTypeId]: FridaDeviceTypeId }) as const
+    );
+
+/** @internal */
+export const layerRemoteDevice = (
+    address: string,
+    options?: Frida.RemoteDeviceOptions | undefined
+): Layer.Layer<FridaDevice.FridaDevice, FridaDeviceAcquisitionError.FridaDeviceAcquisitionError, never> =>
+    Layer.effect(Tag, acquireRemoteDevice(address, options));
+
+/** @internal */
+export const layerUsbDevice = (
+    options?: Frida.GetDeviceOptions | undefined
+): Layer.Layer<FridaDevice.FridaDevice, FridaDeviceAcquisitionError.FridaDeviceAcquisitionError, never> =>
+    Layer.effect(Tag, acquireUsbDevice(options));
+
+/** @internal */
+export const layerLocalDevice: Layer.Layer<
+    FridaDevice.FridaDevice,
+    FridaDeviceAcquisitionError.FridaDeviceAcquisitionError,
+    never
+> = Layer.effect(Tag, acquireLocalDevice());

package/src/internal/script.ts

@@ -0,0 +1,208 @@
+import type * as Scope from "effect/Scope";
+import type * as FridaScript from "../FridaScript.js";
+
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Function from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Queue from "effect/Queue";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as Take from "effect/Take";
+import * as Frida from "frida";
+import * as FridaDevice from "../FridaDevice.js";
+import * as FridaSession from "../FridaSession.js";
+import * as FridaSessionError from "../FridaSessionError.js";
+
+/** @internal */
+export const FridaScriptTypeId: FridaScript.FridaScriptTypeId = Symbol.for(
+    "@efffrida/frida-tools/FridaScript"
+) as FridaScript.FridaScriptTypeId;
+
+/** @internal */
+export const Tag = Context.GenericTag<FridaScript.FridaScript>("@efffrida/frida-tools/FridaScript");
+
+/** @internal */
+export const isFridaScript = (u: unknown): u is FridaScript.FridaScript => Predicate.hasProperty(u, FridaScriptTypeId);
+
+/** @internal */
+export const load = Function.dual<
+    (
+        options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+    ) => (
+        source: string | Buffer
+    ) => Effect.Effect<
+        FridaScript.FridaScript,
+        FridaSessionError.FridaSessionError,
+        FridaSession.FridaSession | FridaDevice.FridaDevice | Scope.Scope
+    >,
+    (
+        source: string | Buffer,
+        options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+    ) => Effect.Effect<
+        FridaScript.FridaScript,
+        FridaSessionError.FridaSessionError,
+        FridaSession.FridaSession | FridaDevice.FridaDevice | Scope.Scope
+    >
+>(
+    (arguments_) => Predicate.isString(arguments_[0]) || Buffer.isBuffer(arguments_[0]),
+    Effect.fnUntraced(
+        function* (
+            source: string | Buffer,
+            options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+        ) {
+            const { device } = yield* FridaDevice.FridaDevice;
+            const { session } = yield* FridaSession.FridaSession;
+
+            const script = Predicate.isString(source)
+                ? yield* Effect.tryPromise({
+                      try: () => session.createScript(source, { runtime: Frida.ScriptRuntime.V8, ...options }),
+                      catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "compile" }),
+                  })
+                : yield* Effect.tryPromise({
+                      try: () => session.createScriptFromBytes(source, { runtime: Frida.ScriptRuntime.V8, ...options }),
+                      catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "compile" }),
+                  });
+
+            const messageQueue =
+                yield* Queue.unbounded<
+                    Take.Take<{ message: any; data: Option.Option<Buffer> }, FridaSessionError.FridaSessionError>
+                >();
+
+            let scriptDefectCause: unknown = undefined;
+            const messageHandler: Frida.ScriptMessageHandler = (message: Frida.Message, data: Buffer | null): void => {
+                switch (message.type) {
+                    case Frida.MessageType.Error: {
+                        const error = new Error();
+                        error.name = "FridaScriptDefect";
+                        error.stack = message.stack ?? "";
+                        error.message = message.description.replace(/Error: /, "") ?? "";
+                        scriptDefectCause = error;
+                        const sessionError = new FridaSessionError.FridaSessionError({
+                            when: "message",
+                            cause: error.cause,
+                        });
+                        const asTake = Take.fail(sessionError);
+                        Queue.unsafeOffer(messageQueue, asTake);
+                        break;
+                    }
+
+                    case Frida.MessageType.Send: {
+                        const asTake = Take.of({ message: message.payload, data: Option.fromNullable(data) });
+                        Queue.unsafeOffer(messageQueue, asTake);
+                        break;
+                    }
+
+                    default:
+                        Function.absurd(message);
+                }
+            };
+
+            const disconnectMessageHandler = Effect.sync(() => script.message.disconnect(messageHandler));
+            yield* Effect.addFinalizer(() => Effect.flatMap(messageQueue.shutdown, () => disconnectMessageHandler));
+            script.message.connect(messageHandler);
+
+            const stream = Stream.fromQueue(messageQueue).pipe(Stream.flattenTake);
+            const sink = Sink.forEach<
+                { message: any; data: Option.Option<Buffer> },
+                void,
+                FridaSessionError.FridaSessionError,
+                never
+            >(({ data, message }) => {
+                if (Predicate.isNotUndefined(scriptDefectCause)) {
+                    return Effect.fail(
+                        new FridaSessionError.FridaSessionError({
+                            when: "rpcCall",
+                            cause: scriptDefectCause,
+                        })
+                    );
+                } else {
+                    return Effect.sync(() => script.post(message, Option.getOrNull(data)));
+                }
+            });
+
+            const destroyed = yield* Deferred.make<void, never>();
+            const destroyedHandler = () => Deferred.unsafeDone(destroyed, Effect.void);
+            script.destroyed.connect(destroyedHandler);
+
+            const callExport = (exportName: string) =>
+                Effect.fn(`call frida export ${exportName}`)(function* (...args: Array<any>) {
+                    yield* Effect.annotateCurrentSpan("args", args);
+
+                    const isDestroyed = yield* Deferred.isDone(destroyed);
+                    if (isDestroyed) {
+                        return yield* new FridaSessionError.FridaSessionError({
+                            when: "rpcCall",
+                            cause: "Script is destroyed",
+                        });
+                    }
+
+                    if (Predicate.isNotUndefined(scriptDefectCause)) {
+                        return yield* new FridaSessionError.FridaSessionError({
+                            when: "rpcCall",
+                            cause: scriptDefectCause,
+                        });
+                    }
+
+                    const result = yield* Effect.tryPromise({
+                        try: () => script.exports[exportName](...args) as Promise<unknown>,
+                        catch: (cause) => new FridaSessionError.FridaSessionError({ when: "rpcCall", cause }),
+                    });
+                    yield* Effect.annotateCurrentSpan("result", result);
+                    return result;
+                });
+
+            yield* Effect.tryPromise({
+                try: () => script.load(),
+                catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "load" }),
+            });
+
+            if (options?.resume === true) {
+                yield* Effect.tryPromise({
+                    try: () => device.resume(session.pid),
+                    catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "resume" }),
+                });
+            }
+
+            return {
+                script,
+                stream,
+                sink,
+                destroyed,
+                callExport,
+                [FridaScriptTypeId]: FridaScriptTypeId,
+            } as const;
+        },
+        Effect.acquireRelease(({ script }: FridaScript.FridaScript) => Effect.promise(() => script.unload()))
+    )
+);
+
+/** @internal */
+export const layer = Function.dual<
+    (
+        options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+    ) => (
+        source: string | Buffer
+    ) => Layer.Layer<
+        FridaScript.FridaScript,
+        FridaSessionError.FridaSessionError,
+        FridaSession.FridaSession | FridaDevice.FridaDevice
+    >,
+    (
+        source: string | Buffer,
+        options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+    ) => Layer.Layer<
+        FridaScript.FridaScript,
+        FridaSessionError.FridaSessionError,
+        FridaSession.FridaSession | FridaDevice.FridaDevice
+    >
+>(
+    (arguments_) => Predicate.isString(arguments_[0]),
+    (
+        source: string | Buffer,
+        options?: (Frida.ScriptOptions & { readonly resume?: boolean | undefined }) | undefined
+    ) => Layer.scoped(Tag, load(source, options))
+);

package/src/internal/session.ts

@@ -0,0 +1,73 @@
+import type * as Scope from "effect/Scope";
+import type * as Frida from "frida";
+import type * as FridaSession from "../FridaSession.js";
+
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Predicate from "effect/Predicate";
+import * as FridaDevice from "../FridaDevice.js";
+import * as FridaSessionError from "../FridaSessionError.js";
+
+/** @internal */
+export const FridaSessionTypeId: FridaSession.FridaSessionTypeId = Symbol.for(
+    "@efffrida/frida-tools/FridaSession"
+) as FridaSession.FridaSessionTypeId;
+
+/** @internal */
+export const Tag = Context.GenericTag<FridaSession.FridaSession>("@efffrida/frida-tools/FridaSession");
+
+/** @internal */
+export const isFridaSession = (u: unknown): u is FridaSession.FridaSession =>
+    Predicate.hasProperty(u, FridaSessionTypeId);
+
+/** @internal */
+export const spawn = (
+    program: string | Array<string>,
+    options?: Frida.SpawnOptions | undefined
+): Effect.Effect<number, FridaSessionError.FridaSessionError, FridaDevice.FridaDevice | Scope.Scope> =>
+    Effect.flatMap(FridaDevice.FridaDevice, ({ device }) =>
+        Effect.acquireRelease(
+            Effect.tryPromise({
+                try: () => device.spawn(program, options),
+                catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "spawn" }),
+            }),
+            (pid) => Effect.promise(() => device.kill(pid))
+        )
+    );
+
+/** @internal */
+export const attach = (
+    target: Frida.TargetProcess,
+    options?: Frida.SessionOptions | undefined
+): Effect.Effect<
+    FridaSession.FridaSession,
+    FridaSessionError.FridaSessionError,
+    FridaDevice.FridaDevice | Scope.Scope
+> =>
+    Effect.flatMap(FridaDevice.FridaDevice, ({ device }) =>
+        Effect.acquireRelease(
+            Effect.map(
+                Effect.tryPromise({
+                    try: () => device.attach(target, options),
+                    catch: (cause) => new FridaSessionError.FridaSessionError({ cause, when: "attach" }),
+                }),
+                (session) => ({ session, [FridaSessionTypeId]: FridaSessionTypeId }) as const
+            ),
+            ({ session }: FridaSession.FridaSession) => Effect.promise(() => session.detach())
+        )
+    );
+
+/** @internal */
+export const layer = (
+    target: string,
+    options?: (Frida.SpawnOptions & Frida.SessionOptions) | undefined
+): Layer.Layer<FridaSession.FridaSession, FridaSessionError.FridaSessionError, FridaDevice.FridaDevice> =>
+    Layer.scoped(
+        Tag,
+        Effect.gen(function* () {
+            const pid = yield* spawn(target, options);
+            const session = yield* attach(pid, options);
+            return session;
+        })
+    );