bgclick-rev

name	bgclick-rev
description	Reverse-engineer a macOS GUI automation app's background-click path and produce a Swift reproduction. Use only when the user provides a target .app and explicitly asks for IDA-backed background-click reverse engineering. Requires IDA Pro with IDA MCP attached.

Background-Click Reverse Engineering

Use this skill only for research on a user-provided macOS .app. If IDA Pro or IDA MCP is unavailable, stop early and explain the blocker. Do not modify Uni-CLI source code from this skill; write research artifacts and reproduction code only after the binary evidence is gathered.

Outputs

Create a research bundle under <workspace>/research/:

• SHARED-CONTEXT.md with target paths, bundle IDs, signing status, IDA MCP instance mapping, and priors to verify.
• findings/<phase-or-question>.md for call-site maps and open questions.
• sub_<addr>-<label>.md for every decompiled function used as evidence.
• frame-map.md for Swift async task-frame offsets.
• FINAL-REPORT.md with behavior spec, evidence table, reproduction diff, and VM test plan.

If asked to build a reproduction, add:

• Sources/<Module>/BackgroundClicker.swift
• EchoApp/main.swift
• impl-research.md with empirical VM runs.

Priors To Verify

Treat these as hypotheses until confirmed in the target binary:

• Events are posted with CGEvent.postToPid(_:).
• The synthetic event starts as NSEvent.mouseEvent(...), then uses event.cgEvent.
• Explicit integer fields are 3 button, 7 subtype value 3, 91 window under pointer, and 92 window that can handle the event.
• Screen location is set, read back, translated by the target window origin, and written with CGEventSetWindowLocation resolved by dlsym.
• Background targets receive CGEventFlags.maskCommand (0x00100000), not the non-coalesced flag.
• CGWindowID comes from CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) filtered by owner PID.
• Do not double-write fields already populated by NSEvent.cgEvent.
• The click path should not activate the target app through AppKit, AX frontmost setters, or SLS/CGS private activation APIs.

Workflow

1. Triage the .app: locate main executable and helper apps, record codesign -d --entitlements -, nm -u, and relevant Mach-O paths.
2. Confirm IDA MCP instances and map each instance to a binary in SHARED-CONTEXT.md.
3. Audit service binary call sites upward from CGWindowListCopyWindowInfo, CGWindowListCreateDescriptionFromArray, AX APIs, screen-capture APIs, dlsym, and dlopen.
4. Identify the dispatch function that logs or formats the click dispatch message, then trace the Swift async continuation chain into the synthesizer.
5. For each decompiled function used, write research/sub_<addr>-<label>.md with a one-line verdict, trimmed evidence, frame writes, and Swift equivalent.
6. Resolve dyld-hash wrappers to concrete CoreGraphics symbols. Verify with dlsym on a comparable macOS host when possible.
7. Produce findings/cgevent-fields.md mapping every explicit setIntegerValueField write to SDK constants and source expressions.
8. Hunt open questions independently. Each finding file starts with a one-sentence verdict and includes evidence addresses.
9. Build BackgroundClicker.swift only from verified behavior. Use public AppKit/CoreGraphics APIs plus dlsym for CGEventSetWindowLocation.
10. Validate in a VM with an EchoApp counter window. Record window number, screen point, window-local point, activation state, and pass/fail in impl-research.md.

Guardrails

• Keep all reverse-engineered evidence in research/; do not paste large decompiler output into chat.
• Mark unknowns as open questions instead of guessing.
• Never label 0x100000 as non-coalesced; it is the Command flag.
• Activation selectors found elsewhere in the binary are not evidence unless they are on the verified click path.