Merge remote-tracking branch 'origin/main' into feat/signature-posture
# Conflicts: # docs/product-catalog.json # docs/verification/managed-conformance-manifest.json # skills/reverse-engineer-anything/SKILL.md # src/generatedMcpToolCatalog.ts
This commit is contained in:
@@ -6,6 +6,7 @@ on:
|
||||
paths:
|
||||
- "website/**"
|
||||
- "scripts/verify-website.py"
|
||||
- "scripts/prepare-website.py"
|
||||
- ".github/workflows/**"
|
||||
workflow_dispatch:
|
||||
|
||||
@@ -24,5 +25,7 @@ jobs:
|
||||
steps:
|
||||
- name: Check out the repository
|
||||
uses: actions/checkout@v4
|
||||
- name: Prepare the example download
|
||||
run: python3 scripts/prepare-website.py
|
||||
- name: Check website links and publishing configuration
|
||||
run: python3 scripts/verify-website.py
|
||||
|
||||
@@ -21,6 +21,8 @@ jobs:
|
||||
steps:
|
||||
- name: Check out the repository
|
||||
uses: actions/checkout@v4
|
||||
- name: Prepare the example download
|
||||
run: python3 scripts/prepare-website.py
|
||||
- name: Check website links and publishing configuration
|
||||
run: python3 scripts/verify-website.py
|
||||
- name: Configure Pages
|
||||
|
||||
@@ -45,3 +45,6 @@ Thumbs.db
|
||||
|
||||
# Local reference sources and analysis artifacts
|
||||
/_reference/
|
||||
|
||||
# Generated website download
|
||||
/website/public/examples/notes-example.zip
|
||||
|
||||
@@ -96,9 +96,11 @@ The components also list:
|
||||
|
||||
Symlinks are reported by path in `symlinks`. Their targets are not inventoried,
|
||||
so a versioned framework is described through its real `Versions/<version>/`
|
||||
directories rather than `Versions/Current`. When a framework has zero or several
|
||||
`Versions/*/Resources/Info.plist` files, its `info_plist_path` is `null` and a
|
||||
limitation explains why.
|
||||
directories rather than `Versions/Current`. A framework's `info_plist_path` is
|
||||
`null`, with a limitation explaining why, when it has more than one real
|
||||
`Versions/<version>/` directory (even if only one of them holds a plist,
|
||||
because `Versions/Current` decides which one applies) or when its single
|
||||
version directory has no `Resources/Info.plist`.
|
||||
|
||||
AppleDouble sidecar files (`._*` and `__MACOSX/`) are inventory facts, but they
|
||||
describe neighbouring files. They are excluded from roots, bundle roles, and the
|
||||
|
||||
@@ -67,9 +67,20 @@ explicit limitation; architecture inventory locations remain available.
|
||||
vtable descriptors. Records include exact virtual addresses/file offsets and
|
||||
artifact evidence. Vtable indexes are metadata word offsets; witness indexes
|
||||
start after the conformance header. Names unavailable in metadata remain null.
|
||||
Chained fixups, external bindings, authenticated pointers, categories,
|
||||
properties, generic/resilient/async/coroutine tables and inherited overrides
|
||||
have explicit unsupported or partial coverage. Other providers retain the
|
||||
Pointers are decoded through the image's fixups:
|
||||
- `LC_DYLD_CHAINED_FIXUPS` rebases and binds, including the authenticated
|
||||
arm64e formats;
|
||||
- legacy `LC_DYLD_INFO` bind opcodes.
|
||||
|
||||
So an external superclass resolves from its `_OBJC_CLASS_$_` bind (for
|
||||
example `NSObject`). The `pointer_fixups` coverage facet names the mechanism.
|
||||
Class properties, with parsed attributes, and `__objc_catlist` categories are
|
||||
also decoded. Categories record the extended class, local or external, plus
|
||||
their methods, protocols and properties; category methods appear as
|
||||
implementations with a `category`. Swift field-offset globals that are only
|
||||
initialized at runtime stay unresolved. Generic, resilient, async and
|
||||
coroutine tables, and inherited overrides, have explicit unsupported or
|
||||
partial coverage. Other providers retain the
|
||||
existing symbol-based inventory with its narrower coverage.
|
||||
|
||||
## Native instruction, call and type primitives
|
||||
@@ -193,8 +204,10 @@ GUI authority, and REA never falls back automatically to Hopper.
|
||||
instruction/call facts, value dependencies and process/project cleanup.
|
||||
- `npm run verify:ghidra:aarch64-jump-table`: optimized ELF and byte/halfword
|
||||
relative tables, plus ARM64 Mach-O on an ARM64 macOS host.
|
||||
- `npm run verify:apple-dispatch`: source-built Objective-C protocols/classes and
|
||||
Swift conformances/vtables, repeated after stripping local symbols.
|
||||
- `npm run verify:apple-dispatch`: source-built Objective-C protocols, classes,
|
||||
properties and categories, and Swift conformances and vtables. Each is linked
|
||||
with legacy `LC_DYLD_INFO` and with chained fixups (and as arm64e on Apple
|
||||
silicon), then repeated after stripping local symbols.
|
||||
- `npm run verify:native-ui`: one source-owned fixture window, successful
|
||||
selected-window capture and actions, changed-target rejection, and cleanup.
|
||||
Missing OS permissions fail this lane.
|
||||
|
||||
@@ -669,9 +669,9 @@
|
||||
"mcp_prompts": 6
|
||||
},
|
||||
"digests": {
|
||||
"tools_sha256": "be1e9960aa3f883718336cdef7ea8e3230afb92bc1066410a90f7768c3e76a65",
|
||||
"tools_sha256": "3dc09705a3d22b1ba6e4824a6df4ebc32d5f17c433bb735ccb2fdbf78bb39655",
|
||||
"prompts_sha256": "ef2de8814390b340623c32001610aa2709d90bed51537b6e562ab3abf144ab4d",
|
||||
"combined_sha256": "7b69d46ec74998e90d856f650b8f24affa362fbc6c48e49f0b8ddbb836125d8a",
|
||||
"combined_sha256": "3d064d152322519d05eb8c561c30d560d4b7c1930f15bbb9803fa5189b0746ed",
|
||||
"providers_sha256": "a7d885531ee25d42c51385444faec544d34cd7eba6250a7dc75c4faedd4454a3"
|
||||
}
|
||||
}
|
||||
|
||||
+18
-11
@@ -470,17 +470,24 @@ that explicit lane, not the routine iteration requirement.
|
||||
|
||||
## Apple native metadata and UI
|
||||
|
||||
`npm run verify:apple-dispatch` compiles Objective-C class/protocol and Swift
|
||||
conformance/vtable fixtures, inspects their bytes and repeats after stripping
|
||||
local symbols. It requires macOS and the host Xcode toolchain; targets are not
|
||||
executed. `npm run verify:native-ui` launches exactly one source-owned fixture
|
||||
window and requires successful selected-window capture and selected actions.
|
||||
An OS permission denial fails the positive lane. `npm run verify:native-ui:permissions`
|
||||
allows a host-permission-boundary-only result and explicitly reports
|
||||
`positive_e2e: false`; it must not be reported as capture/action proof.
|
||||
Both commands reject a changed executable digest and clean up the fixture
|
||||
process and helper. These lanes require an interactive macOS desktop. See [native investigation](native-investigation.md)
|
||||
for the exact ABI, authority, graph and observation boundaries.
|
||||
`npm run verify:apple-dispatch` compiles the Objective-C fixture (classes,
|
||||
protocols, a property and an `NSString` category) and the Swift
|
||||
conformance/vtable fixture.
|
||||
|
||||
- Each fixture is linked with legacy `LC_DYLD_INFO` binds and with chained
|
||||
fixups; on Apple silicon the ObjC fixture is also built as arm64e, which uses
|
||||
authenticated pointers.
|
||||
- The lane inspects the bytes and repeats after stripping local symbols.
|
||||
- It requires the bound `NSObject` superclass, the external category, and the
|
||||
matching `pointer_fixups` coverage. It requires macOS and the host Xcode toolchain; targets are not
|
||||
executed. `npm run verify:native-ui` launches exactly one source-owned fixture
|
||||
window and requires successful selected-window capture and selected actions.
|
||||
An OS permission denial fails the positive lane. `npm run verify:native-ui:permissions`
|
||||
allows a host-permission-boundary-only result and explicitly reports
|
||||
`positive_e2e: false`; it must not be reported as capture/action proof.
|
||||
Both commands reject a changed executable digest and clean up the fixture
|
||||
process and helper. These lanes require an interactive macOS desktop. See [native investigation](native-investigation.md)
|
||||
for the exact ABI, authority, graph and observation boundaries.
|
||||
|
||||
### Firmware adapters
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"manifest_id": "ecm_b9deaf8c476e6ab8b2ca20046190ea1538c863d9a25763ed0b637fe2bd316467",
|
||||
"manifest_id": "ecm_6390d1c83574170d9946b19164838f78020b08516ff28fff26892fec1979fed2",
|
||||
"verifier": {
|
||||
"id": "rea-managed-conformance",
|
||||
"version": "1"
|
||||
@@ -13,7 +13,7 @@
|
||||
"skill_digests": [
|
||||
{
|
||||
"skill_id": "reverse-engineer-anything",
|
||||
"sha256": "cad8005182fc760894e956db9865a746b725a7e0a11e2c223fccc9e8c1797368"
|
||||
"sha256": "951de5dd3e3f402b25a086bb0253522e1f993ad4f6bbc0729ed683d37f2a08ba"
|
||||
}
|
||||
],
|
||||
"claims": [
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
"""Package the public Notes example for the static website."""
|
||||
|
||||
from io import BytesIO
|
||||
from pathlib import Path
|
||||
from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
|
||||
|
||||
|
||||
EXAMPLE_FILES = (
|
||||
"package.json",
|
||||
"main.js",
|
||||
"preload.js",
|
||||
"renderer.js",
|
||||
"csv.js",
|
||||
"index.html",
|
||||
)
|
||||
|
||||
|
||||
def prepare_notes_example(site):
|
||||
"""Create a ZIP with public source only and reproducible metadata."""
|
||||
source = site / "examples/notes-electron"
|
||||
contents = BytesIO()
|
||||
with ZipFile(contents, "w") as archive:
|
||||
for name in EXAMPLE_FILES:
|
||||
entry = ZipInfo(f"notes-example/{name}", (1980, 1, 1, 0, 0, 0))
|
||||
entry.create_system = 3
|
||||
entry.external_attr = 0o100644 << 16
|
||||
archive.writestr(
|
||||
entry,
|
||||
(source / name).read_bytes(),
|
||||
compress_type=ZIP_DEFLATED,
|
||||
compresslevel=9,
|
||||
)
|
||||
destination = site / "examples/notes-example.zip"
|
||||
destination.write_bytes(contents.getvalue())
|
||||
print(f"Prepared examples/notes-example.zip ({len(EXAMPLE_FILES)} files).")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
root = Path(__file__).resolve().parent.parent
|
||||
prepare_notes_example(root / "website/public")
|
||||
+181
-109
@@ -12,118 +12,190 @@ if (process.platform !== "darwin")
|
||||
"Apple dispatch verification requires macOS with a host Objective-C compiler and Foundation SDK",
|
||||
);
|
||||
const exec = promisify(execFile);
|
||||
const source = (name) =>
|
||||
fileURLToPath(
|
||||
new URL(`../tests/conformance/native/${name}`, import.meta.url),
|
||||
);
|
||||
|
||||
/** Both link modes: legacy LC_DYLD_INFO binds and the default chained fixups. */
|
||||
const LINK_MODES = [
|
||||
{
|
||||
mode: "dyld-info",
|
||||
flags: ["-Wl,-no_fixup_chains"],
|
||||
fixups: "LC_DYLD_INFO bind opcodes",
|
||||
swift: true,
|
||||
},
|
||||
{ mode: "chained", flags: [], fixups: "chained fixups:", swift: true },
|
||||
// arm64e uses authenticated chained pointers (DYLD_CHAINED_PTR_ARM64E_*).
|
||||
...(process.arch === "arm64"
|
||||
? [
|
||||
{
|
||||
mode: "chained-arm64e",
|
||||
flags: ["-arch", "arm64e"],
|
||||
fixups: "chained fixups: DYLD_CHAINED_PTR_ARM64E",
|
||||
swift: false,
|
||||
},
|
||||
]
|
||||
: []),
|
||||
];
|
||||
|
||||
const fixupCoverage = (metadata) =>
|
||||
metadata.coverage.find(({ facet }) => facet === "pointer_fixups");
|
||||
|
||||
const inspect = async (path) => {
|
||||
const target = await parseBinaryTarget(path);
|
||||
if (!target.ok) throw target.error;
|
||||
return {
|
||||
target: target.value,
|
||||
metadata: (await inspectAppleDispatchMetadata(target.value, 5000)).result,
|
||||
};
|
||||
};
|
||||
|
||||
const checkObjc = (metadata, mode) => {
|
||||
const fixture = metadata.objc_classes.find(
|
||||
({ name, is_meta_class: meta }) => name === "ReaDispatchFixture" && !meta,
|
||||
);
|
||||
const category = metadata.objc_categories.find(
|
||||
({ name }) => name === "ReaDispatchAdditions",
|
||||
);
|
||||
const objcCoverage = metadata.coverage.find(
|
||||
({ facet }) => facet === "objc_class_method_ivar_metadata",
|
||||
);
|
||||
if (
|
||||
!metadata.objc_dispatch_implementations.some(
|
||||
(item) =>
|
||||
item.class_name === "ReaDispatchFixture" &&
|
||||
item.selector === "performAction:" &&
|
||||
item.implementation_address !== null,
|
||||
) ||
|
||||
!metadata.objc_dispatch_implementations.some(
|
||||
(item) =>
|
||||
item.selector === "fixtureVersion" && item.method_type === "class",
|
||||
) ||
|
||||
!metadata.objc_ivars.some(
|
||||
(item) => item.name === "state" && item.offset !== null,
|
||||
) ||
|
||||
!metadata.objc_protocol_records.some(
|
||||
(protocol) =>
|
||||
protocol.name === "ReaDispatchProtocol" &&
|
||||
protocol.methods.some(
|
||||
(method) => method.selector === "performAction:",
|
||||
) &&
|
||||
protocol.optional_methods.some(
|
||||
(method) => method.selector === "optionalFixtureValue",
|
||||
),
|
||||
) ||
|
||||
// The superclass lives in libobjc, so it comes from a bind fixup.
|
||||
fixture?.super_class !== "NSObject" ||
|
||||
fixture.decode.status !== "decoded" ||
|
||||
!fixture.properties.some(
|
||||
(property) =>
|
||||
property.name === "fixtureName" &&
|
||||
property.type_encoding === '@"NSString"' &&
|
||||
property.attributes.some(({ name }) => name === "C"),
|
||||
) ||
|
||||
category?.class_name !== "NSString" ||
|
||||
category.class_source !== "external" ||
|
||||
!category.instance_methods.includes("reaFixtureLength") ||
|
||||
!metadata.objc_dispatch_implementations.some(
|
||||
(item) =>
|
||||
item.class_name === "NSString" &&
|
||||
item.category === "ReaDispatchAdditions" &&
|
||||
item.selector === "reaFixtureLength",
|
||||
) ||
|
||||
objcCoverage?.status !== "complete" ||
|
||||
fixupCoverage(metadata)?.reason?.startsWith(mode.fixups) !== true
|
||||
)
|
||||
throw new Error(
|
||||
`Apple metadata fixture drifted (${mode.mode}): ${JSON.stringify(metadata)}`,
|
||||
);
|
||||
};
|
||||
|
||||
const checkSwift = (metadata, mode) => {
|
||||
if (
|
||||
!metadata.swift_dispatch_slots.some(
|
||||
(slot) =>
|
||||
slot.table_kind === "class_vtable" &&
|
||||
slot.owner === "ReaVtableFixture" &&
|
||||
slot.decode.status === "decoded",
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Swift class vtable fixture unavailable (${mode.mode}): ${JSON.stringify(metadata.coverage)}`,
|
||||
);
|
||||
if (
|
||||
!metadata.swift_conformances.some(
|
||||
(item) =>
|
||||
item.type_name === "ReaWitnessFixture" &&
|
||||
item.protocol_name === "ReaWitnessFixtureProtocol",
|
||||
) ||
|
||||
!metadata.swift_dispatch_slots.some(
|
||||
(item) =>
|
||||
item.owner === "ReaWitnessFixture: ReaWitnessFixtureProtocol" &&
|
||||
item.implementation_address !== null,
|
||||
) ||
|
||||
fixupCoverage(metadata)?.reason?.startsWith(mode.fixups) !== true
|
||||
)
|
||||
throw new Error(
|
||||
`Swift metadata fixture drifted (${mode.mode}): ${JSON.stringify(metadata)}`,
|
||||
);
|
||||
};
|
||||
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-dispatch-"));
|
||||
try {
|
||||
const targetPath = join(root, "fixture");
|
||||
await exec("/usr/bin/xcrun", [
|
||||
"clang",
|
||||
"-O2",
|
||||
"-framework",
|
||||
"Foundation",
|
||||
"-Wl,-no_fixup_chains",
|
||||
fileURLToPath(
|
||||
new URL("../tests/conformance/native/dispatch.m", import.meta.url),
|
||||
),
|
||||
"-o",
|
||||
targetPath,
|
||||
]);
|
||||
const results = [];
|
||||
for (const variant of ["symbols", "stripped"]) {
|
||||
if (variant === "stripped")
|
||||
await exec("/usr/bin/strip", ["-x", targetPath]);
|
||||
const target = await parseBinaryTarget(targetPath);
|
||||
if (!target.ok) throw target.error;
|
||||
const observation = await inspectAppleDispatchMetadata(target.value, 5000);
|
||||
const metadata = observation.result;
|
||||
if (
|
||||
!metadata.objc_dispatch_implementations.some(
|
||||
(item) =>
|
||||
item.class_name === "ReaDispatchFixture" &&
|
||||
item.selector === "performAction:" &&
|
||||
item.implementation_address !== null,
|
||||
) ||
|
||||
!metadata.objc_dispatch_implementations.some(
|
||||
(item) =>
|
||||
item.selector === "fixtureVersion" && item.method_type === "class",
|
||||
) ||
|
||||
!metadata.objc_ivars.some(
|
||||
(item) => item.name === "state" && item.offset !== null,
|
||||
) ||
|
||||
!metadata.objc_protocol_records.some(
|
||||
(protocol) =>
|
||||
protocol.name === "ReaDispatchProtocol" &&
|
||||
protocol.methods.some(
|
||||
(method) => method.selector === "performAction:",
|
||||
) &&
|
||||
protocol.optional_methods.some(
|
||||
(method) => method.selector === "optionalFixtureValue",
|
||||
),
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Apple metadata fixture drifted: ${JSON.stringify(observation)}`,
|
||||
);
|
||||
results.push({
|
||||
variant,
|
||||
target_sha256: target.value.sha256,
|
||||
implementations: metadata.objc_dispatch_implementations.length,
|
||||
ivars: metadata.objc_ivars.length,
|
||||
coverage: metadata.coverage,
|
||||
});
|
||||
}
|
||||
const swiftPath = join(root, "libReaWitnessFixture.dylib");
|
||||
await exec("/usr/bin/xcrun", [
|
||||
"swiftc",
|
||||
"-emit-library",
|
||||
"-O",
|
||||
"-Xlinker",
|
||||
"-no_fixup_chains",
|
||||
fileURLToPath(
|
||||
new URL("../tests/conformance/native/dispatch.swift", import.meta.url),
|
||||
),
|
||||
"-o",
|
||||
swiftPath,
|
||||
]);
|
||||
for (const variant of ["swift-symbols", "swift-stripped"]) {
|
||||
if (variant === "swift-stripped")
|
||||
await exec("/usr/bin/strip", ["-x", swiftPath]);
|
||||
const target = await parseBinaryTarget(swiftPath);
|
||||
if (!target.ok) throw target.error;
|
||||
const observation = await inspectAppleDispatchMetadata(target.value, 5000);
|
||||
const metadata = observation.result;
|
||||
if (
|
||||
!metadata.swift_dispatch_slots.some(
|
||||
(slot) =>
|
||||
slot.table_kind === "class_vtable" &&
|
||||
slot.owner === "ReaVtableFixture" &&
|
||||
slot.decode.status === "decoded",
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Swift class vtable fixture unavailable: ${JSON.stringify(metadata.coverage)}`,
|
||||
);
|
||||
if (
|
||||
!metadata.swift_conformances.some(
|
||||
(item) =>
|
||||
item.type_name === "ReaWitnessFixture" &&
|
||||
item.protocol_name === "ReaWitnessFixtureProtocol",
|
||||
) ||
|
||||
!metadata.swift_dispatch_slots.some(
|
||||
(item) =>
|
||||
item.owner === "ReaWitnessFixture: ReaWitnessFixtureProtocol" &&
|
||||
item.implementation_address !== null,
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Swift metadata fixture drifted: ${JSON.stringify(observation)}`,
|
||||
);
|
||||
results.push({
|
||||
variant,
|
||||
target_sha256: target.value.sha256,
|
||||
conformances: metadata.swift_conformances.length,
|
||||
slots: metadata.swift_dispatch_slots.length,
|
||||
coverage: metadata.coverage,
|
||||
});
|
||||
for (const mode of LINK_MODES) {
|
||||
const objcPath = join(root, `fixture-${mode.mode}`);
|
||||
await exec("/usr/bin/xcrun", [
|
||||
"clang",
|
||||
"-O2",
|
||||
"-framework",
|
||||
"Foundation",
|
||||
...mode.flags,
|
||||
source("dispatch.m"),
|
||||
"-o",
|
||||
objcPath,
|
||||
]);
|
||||
for (const variant of ["symbols", "stripped"]) {
|
||||
if (variant === "stripped")
|
||||
await exec("/usr/bin/strip", ["-x", objcPath]);
|
||||
const { target, metadata } = await inspect(objcPath);
|
||||
checkObjc(metadata, mode);
|
||||
results.push({
|
||||
variant: `objc-${mode.mode}-${variant}`,
|
||||
target_sha256: target.sha256,
|
||||
classes: metadata.objc_classes.length,
|
||||
categories: metadata.objc_categories.length,
|
||||
implementations: metadata.objc_dispatch_implementations.length,
|
||||
fixups: fixupCoverage(metadata)?.reason,
|
||||
});
|
||||
}
|
||||
if (!mode.swift) continue;
|
||||
const swiftPath = join(root, `libReaWitnessFixture-${mode.mode}.dylib`);
|
||||
await exec("/usr/bin/xcrun", [
|
||||
"swiftc",
|
||||
"-emit-library",
|
||||
"-O",
|
||||
...mode.flags
|
||||
.map((flag) => flag.replace(/^-Wl,/u, "-Xlinker\0"))
|
||||
.flatMap((flag) => flag.split("\0")),
|
||||
source("dispatch.swift"),
|
||||
"-o",
|
||||
swiftPath,
|
||||
]);
|
||||
for (const variant of ["symbols", "stripped"]) {
|
||||
if (variant === "stripped")
|
||||
await exec("/usr/bin/strip", ["-x", swiftPath]);
|
||||
const { target, metadata } = await inspect(swiftPath);
|
||||
checkSwift(metadata, mode);
|
||||
results.push({
|
||||
variant: `swift-${mode.mode}-${variant}`,
|
||||
target_sha256: target.sha256,
|
||||
conformances: metadata.swift_conformances.length,
|
||||
slots: metadata.swift_dispatch_slots.length,
|
||||
fixups: fixupCoverage(metadata)?.reason,
|
||||
});
|
||||
}
|
||||
}
|
||||
process.stdout.write(
|
||||
`${JSON.stringify({ ok: true, target_executed: false, fixtures: results })}\n`,
|
||||
|
||||
@@ -6,6 +6,7 @@ import re
|
||||
import sys
|
||||
from urllib.parse import unquote, urlsplit
|
||||
import xml.etree.ElementTree as ET
|
||||
from zipfile import BadZipFile, ZipFile
|
||||
|
||||
|
||||
class HtmlReferences(HTMLParser):
|
||||
@@ -89,15 +90,39 @@ def check_publisher(root):
|
||||
return []
|
||||
|
||||
|
||||
def check_example_archive(site):
|
||||
"""Verify the downloadable ZIP contains the current six source files."""
|
||||
source = site / "examples/notes-electron"
|
||||
expected = {
|
||||
f"notes-example/{name}": source / name
|
||||
for name in ("package.json", "main.js", "preload.js", "renderer.js", "csv.js", "index.html")
|
||||
}
|
||||
path = site / "examples/notes-example.zip"
|
||||
if not path.is_file():
|
||||
return ["Notes example ZIP is missing; run python3 scripts/prepare-website.py."]
|
||||
try:
|
||||
with ZipFile(path) as archive:
|
||||
if sorted(archive.namelist()) != sorted(expected):
|
||||
return ["Notes example ZIP must contain exactly the six files in notes-example/."]
|
||||
return [
|
||||
f"Notes example ZIP has stale source: {name}"
|
||||
for name, original in expected.items()
|
||||
if archive.read(name) != original.read_bytes()
|
||||
]
|
||||
except (BadZipFile, RuntimeError) as error:
|
||||
return [f"Notes example ZIP cannot be read: {error}"]
|
||||
|
||||
|
||||
def main():
|
||||
"""Run the same checks locally, on website PRs and before publishing."""
|
||||
root = Path(__file__).resolve().parent.parent
|
||||
pages, references, errors = check_site(root / "website/public")
|
||||
errors.extend(check_example_archive(root / "website/public"))
|
||||
errors.extend(check_publisher(root))
|
||||
if errors:
|
||||
print("Website checks failed:\n" + "\n".join(errors), file=sys.stderr)
|
||||
return 1
|
||||
print(f"Verified {pages} HTML pages, {references} local references and SVG XML.")
|
||||
print(f"Verified {pages} HTML pages, {references} local references, SVG XML and the example ZIP.")
|
||||
print("website-pages.yml is the sole GitHub Pages publisher.")
|
||||
return 0
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Reverse engineer native, managed, Electron/JavaScript, packaged, fi
|
||||
metadata:
|
||||
version: "28"
|
||||
tool_count: 131
|
||||
catalog_digest: "7b69d46ec74998e90d856f650b8f24affa362fbc6c48e49f0b8ddbb836125d8a"
|
||||
catalog_digest: "3d064d152322519d05eb8c561c30d560d4b7c1930f15bbb9803fa5189b0746ed"
|
||||
---
|
||||
|
||||
# REA
|
||||
|
||||
@@ -309,6 +309,29 @@ describe("Apple bundle layouts and containers", () => {
|
||||
expect(
|
||||
result.bundles.find(({ path }) => path === framework)?.info_plist_path,
|
||||
).toBeNull();
|
||||
// Files beside the only real version are not versions.
|
||||
const withFiles = project(
|
||||
inventoryEvidence("zip", "Fixture.zip", [
|
||||
macho("Fixture.app/Contents/MacOS/Fixture"),
|
||||
{ path: `${framework}/Versions/A/Resources/Info.plist` },
|
||||
{ path: `${framework}/Versions/.DS_Store` },
|
||||
{ path: `${framework}/Versions/Current`, kind: "symlink" },
|
||||
]),
|
||||
);
|
||||
expect(
|
||||
withFiles.bundles.find(({ path }) => path === framework)?.info_plist_path,
|
||||
).toBe(`${framework}/Versions/A/Resources/Info.plist`);
|
||||
// Only A has a plist, but Versions/Current may select B.
|
||||
const onlyA = project(
|
||||
inventoryEvidence("zip", "Fixture.zip", [
|
||||
macho("Fixture.app/Contents/MacOS/Fixture"),
|
||||
{ path: `${framework}/Versions/A/Resources/Info.plist` },
|
||||
macho(`${framework}/Versions/B/Core`),
|
||||
]),
|
||||
);
|
||||
expect(
|
||||
onlyA.bundles.find(({ path }) => path === framework)?.info_plist_path,
|
||||
).toBeNull();
|
||||
expect(result.limitations).toContainEqual(
|
||||
expect.stringContaining("Versions/Current selects is unknown"),
|
||||
);
|
||||
@@ -438,3 +461,37 @@ describe("macOS application scope", () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("Apple application bridge candidates", () => {
|
||||
it("pairs scripts and native code only within one application root", () => {
|
||||
const result = project(
|
||||
inventoryEvidence("zip", "Suite.zip", [
|
||||
macho("First.app/Contents/MacOS/First"),
|
||||
{
|
||||
path: "First.app/Contents/Resources/first.js",
|
||||
format: "javascript-bundle",
|
||||
},
|
||||
macho("Second.app/Contents/MacOS/Second"),
|
||||
{
|
||||
path: "Second.app/Contents/Resources/second.js",
|
||||
format: "javascript-bundle",
|
||||
},
|
||||
]),
|
||||
);
|
||||
expect(result.application_roots).toEqual(["First.app", "Second.app"]);
|
||||
expect(
|
||||
result.bridge_candidates.map(
|
||||
({ source_path: source, native_path: target }) => [source, target],
|
||||
),
|
||||
).toEqual([
|
||||
[
|
||||
"First.app/Contents/Resources/first.js",
|
||||
"First.app/Contents/MacOS/First",
|
||||
],
|
||||
[
|
||||
"Second.app/Contents/Resources/second.js",
|
||||
"Second.app/Contents/MacOS/Second",
|
||||
],
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -149,6 +149,7 @@ export const projectAppleApplication = (
|
||||
...classified.executables,
|
||||
...classified.native_libraries,
|
||||
]),
|
||||
roots,
|
||||
);
|
||||
const uninventoriedImage =
|
||||
rootFormat === "dmg" && inventory.occurrences.length === 1;
|
||||
@@ -305,18 +306,27 @@ const identifyRuntimeFamilies = (all: readonly Component[]) => {
|
||||
return [...families].sort(compare);
|
||||
};
|
||||
|
||||
/** Pair scripts and native code only within the same application root. */
|
||||
const identifyBridgeCandidates = (
|
||||
scripts: readonly Component[],
|
||||
native: readonly Component[],
|
||||
) => ({
|
||||
candidates: scripts.flatMap((script) =>
|
||||
native.map((item) => ({
|
||||
source_path: script.path,
|
||||
native_path: item.path,
|
||||
basis: bridgeBasis(item.path),
|
||||
})),
|
||||
),
|
||||
});
|
||||
roots: readonly string[],
|
||||
) => {
|
||||
const owner = (path: string): string | null =>
|
||||
roots.find((root) => isWithin(path, root)) ?? null;
|
||||
return {
|
||||
candidates: scripts.flatMap((script) => {
|
||||
const root = owner(script.path);
|
||||
return native
|
||||
.filter(({ path }) => owner(path) === root)
|
||||
.map((item) => ({
|
||||
source_path: script.path,
|
||||
native_path: item.path,
|
||||
basis: bridgeBasis(item.path),
|
||||
}));
|
||||
}),
|
||||
};
|
||||
};
|
||||
|
||||
const bridgeBasis = (
|
||||
path: string,
|
||||
@@ -360,7 +370,7 @@ const projectionLimitations = (facts: {
|
||||
layout === "versioned-framework" && plist === null,
|
||||
)
|
||||
? [
|
||||
"A versioned framework has zero or several Versions/*/Resources/Info.plist files; the one Versions/Current selects is unknown because symlink targets are not inventoried.",
|
||||
"A versioned framework has several version directories or no Versions/*/Resources/Info.plist; the Info.plist that Versions/Current selects is unknown because symlink targets are not inventoried.",
|
||||
]
|
||||
: []),
|
||||
...(facts.symlinks
|
||||
|
||||
@@ -141,14 +141,18 @@ export const detectBundles = (
|
||||
interface Tree {
|
||||
readonly children: ReadonlyMap<string, ReadonlySet<string>>;
|
||||
readonly files: ReadonlyMap<string, Component>;
|
||||
/** Paths observed as directories, or implied by a deeper path. */
|
||||
readonly directories: ReadonlySet<string>;
|
||||
}
|
||||
|
||||
const indexTree = (entries: readonly Entry[]): Tree => {
|
||||
const children = new Map<string, Set<string>>();
|
||||
const files = new Map<string, Component>();
|
||||
const directories = new Set<string>();
|
||||
for (const { path, kind, component } of entries) {
|
||||
if (isSidecar(path)) continue;
|
||||
if (kind === "file" && component !== undefined) files.set(path, component);
|
||||
if (kind === "directory") directories.add(path);
|
||||
const segments = path.split("/");
|
||||
let parent = "";
|
||||
for (const segment of segments) {
|
||||
@@ -156,9 +160,10 @@ const indexTree = (entries: readonly Entry[]): Tree => {
|
||||
names.add(segment);
|
||||
children.set(parent, names);
|
||||
parent = joinPath(parent, segment);
|
||||
if (parent !== path) directories.add(parent);
|
||||
}
|
||||
}
|
||||
return { children, files };
|
||||
return { children, files, directories };
|
||||
};
|
||||
|
||||
const joinPath = (directory: string, name: string): string =>
|
||||
@@ -223,9 +228,12 @@ const contentDirectories = (
|
||||
if (layout === "macos-deep") return [joinPath(directory, "Contents")];
|
||||
if (layout === "shallow") return [directory];
|
||||
const versions = joinPath(directory, "Versions");
|
||||
// Only real version directories count: Current is a symlink, and files
|
||||
// such as .DS_Store are not versions.
|
||||
return [...(tree.children.get(versions) ?? [])]
|
||||
.filter((version) => version !== "Current")
|
||||
.map((version) => joinPath(versions, version))
|
||||
.filter((version) => tree.directories.has(version))
|
||||
.sort(compare);
|
||||
};
|
||||
|
||||
@@ -234,7 +242,11 @@ const infoPlistPath = (
|
||||
layout: Bundle["layout"],
|
||||
tree: Tree,
|
||||
): string | null => {
|
||||
const candidates = contentDirectories(bundle, layout, tree)
|
||||
const directories = contentDirectories(bundle, layout, tree);
|
||||
// With several real versions, Versions/Current (a symlink outside the
|
||||
// inventory) decides which plist applies, so the plist stays unknown.
|
||||
if (directories.length !== 1) return null;
|
||||
const candidates = directories
|
||||
.map((directory) =>
|
||||
joinPath(
|
||||
directory,
|
||||
|
||||
@@ -166,6 +166,7 @@ describe("Interface Builder dispatch joins", () => {
|
||||
const joined = joinInterfaceBuilderDispatch(ui.graph, {
|
||||
objc_classes: [],
|
||||
objc_protocols: [],
|
||||
objc_categories: [],
|
||||
swift_decls: [],
|
||||
objc_ivars: [],
|
||||
objc_protocol_records: [],
|
||||
@@ -227,6 +228,7 @@ describe("Interface Builder dispatch joins", () => {
|
||||
const metadata = {
|
||||
objc_classes: [],
|
||||
objc_protocols: [],
|
||||
objc_categories: [],
|
||||
swift_decls: [],
|
||||
objc_ivars: [],
|
||||
objc_protocol_records: [],
|
||||
@@ -304,6 +306,7 @@ describe("placeholder dispatch joins", () => {
|
||||
const joined = joinInterfaceBuilderDispatch(ui.graph, {
|
||||
objc_classes: [],
|
||||
objc_protocols: [],
|
||||
objc_categories: [],
|
||||
swift_decls: [],
|
||||
objc_ivars: [],
|
||||
objc_protocol_records: [],
|
||||
|
||||
@@ -156,6 +156,8 @@ export const objcDispatchImplementationSchema = z.strictObject({
|
||||
selector: z.string().min(1),
|
||||
method_type: z.enum(["instance", "class"]),
|
||||
implementation_address: z.string().nullable(),
|
||||
/** Category that adds this method, when it is not defined by the class itself. */
|
||||
category: z.string().nullable().optional(),
|
||||
location: nativeMetadataLocationSchema,
|
||||
decode: nativeMetadataDecodeSchema,
|
||||
evidence: z.array(nativeMetadataEvidenceSchema).min(1),
|
||||
@@ -164,6 +166,21 @@ export type ObjcDispatchImplementation = z.infer<
|
||||
typeof objcDispatchImplementationSchema
|
||||
>;
|
||||
|
||||
/** Objective-C category: methods, protocols and properties added to a class. */
|
||||
export const objcCategorySchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
/** Extended class; external classes come from the category's bind symbol. */
|
||||
class_name: z.string().min(1).nullable(),
|
||||
class_source: z.enum(["local", "external", "unresolved"]),
|
||||
instance_methods: z.array(z.string()),
|
||||
class_methods: z.array(z.string()),
|
||||
protocols: z.array(z.string()),
|
||||
properties: z.array(objcPropertySchema),
|
||||
location: nativeMetadataLocationSchema,
|
||||
decode: nativeMetadataDecodeSchema,
|
||||
evidence: z.array(nativeMetadataEvidenceSchema).min(1),
|
||||
});
|
||||
|
||||
/** Swift protocol conformance and its associated witness-table location. */
|
||||
export const swiftConformanceSchema = z.strictObject({
|
||||
type_name: z.string().min(1),
|
||||
@@ -279,6 +296,7 @@ export type DbSaveResult = z.infer<typeof dbSaveResultSchema>;
|
||||
export const objcSwiftMetadataSchema = z.strictObject({
|
||||
objc_classes: z.array(objcClassSchema).default([]),
|
||||
objc_protocols: z.array(objcProtocolSchema).default([]),
|
||||
objc_categories: z.array(objcCategorySchema).default([]),
|
||||
swift_decls: z.array(swiftDeclSchema).default([]),
|
||||
objc_ivars: z.array(objcIvarSchema).default([]),
|
||||
objc_protocol_records: z.array(objcProtocolRecordSchema).default([]),
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,82 @@
|
||||
import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";
|
||||
import type { PointerFixups } from "./AppleMachoFixups.js";
|
||||
|
||||
const describeFixups = (fixups: PointerFixups): string => {
|
||||
if (fixups.kind === "chained")
|
||||
return `chained fixups: ${fixups.formats.join(", ") || "no fixup segments"}`;
|
||||
return fixups.kind === "dyld-info"
|
||||
? "LC_DYLD_INFO bind opcodes"
|
||||
: "no fixup load commands";
|
||||
};
|
||||
|
||||
/** Append the per-facet coverage of one Apple dispatch metadata decode. */
|
||||
export const pushDispatchCoverage = (input: {
|
||||
readonly result: ObjcSwiftMetadata;
|
||||
readonly failures: readonly string[];
|
||||
readonly examined: number;
|
||||
readonly categoriesExamined: number;
|
||||
readonly truncated: boolean;
|
||||
readonly fixups: PointerFixups;
|
||||
}): void => {
|
||||
const { result, failures, examined, categoriesExamined, truncated, fixups } =
|
||||
input;
|
||||
result.coverage.push({
|
||||
facet: "objc_class_method_ivar_metadata",
|
||||
status: failures.length > 0 || truncated ? "partial" : "complete",
|
||||
reason:
|
||||
[...failures, ...(truncated ? ["max_records_reached"] : [])].join("; ") ||
|
||||
null,
|
||||
examined,
|
||||
decoded: result.objc_classes.length,
|
||||
});
|
||||
result.coverage.push({
|
||||
facet: "binary_relative_pointers",
|
||||
status:
|
||||
truncated ||
|
||||
result.relative_pointers.some((item) => item.decode.status !== "decoded")
|
||||
? "partial"
|
||||
: "complete",
|
||||
reason: truncated
|
||||
? "max_records_reached"
|
||||
: result.relative_pointers.some(
|
||||
(item) => item.decode.status !== "decoded",
|
||||
)
|
||||
? "relative_pointer_targets_unresolved"
|
||||
: null,
|
||||
examined: result.relative_pointers.length,
|
||||
decoded: result.relative_pointers.filter(
|
||||
(item) => item.decode.status === "decoded",
|
||||
).length,
|
||||
});
|
||||
const categoryFailures = failures.filter((failure) =>
|
||||
/^(?:Properties of|Category at)/u.test(failure),
|
||||
);
|
||||
result.coverage.push({
|
||||
facet: "objc_properties_categories",
|
||||
status:
|
||||
categoryFailures.length > 0 ||
|
||||
result.objc_categories.some(({ decode }) => decode.status !== "decoded")
|
||||
? "partial"
|
||||
: "complete",
|
||||
reason: categoryFailures.join("; ") || null,
|
||||
examined: categoriesExamined,
|
||||
decoded: result.objc_categories.filter(
|
||||
({ decode }) => decode.status === "decoded",
|
||||
).length,
|
||||
});
|
||||
result.coverage.push({
|
||||
facet: "pointer_fixups",
|
||||
status: fixups.failures.length > 0 ? "partial" : "complete",
|
||||
reason: [describeFixups(fixups), ...fixups.failures].join("; "),
|
||||
examined: 0,
|
||||
decoded: 0,
|
||||
});
|
||||
result.coverage.push({
|
||||
facet: "swift_generic_resilient_witnesses_overrides_async_coroutines",
|
||||
status: "unsupported",
|
||||
reason:
|
||||
"This reader admits simple Swift conformance/static witness records and non-generic, non-resilient class vtables; generic/resilient tables and other Swift metadata families are not decoded",
|
||||
examined: 0,
|
||||
decoded: 0,
|
||||
});
|
||||
};
|
||||
@@ -9,6 +9,8 @@ import {
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
|
||||
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
|
||||
import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";
|
||||
import { parsePointerFixups } from "./AppleMachoFixups.js";
|
||||
import { parseMachoLayout } from "./AppleMachoSelection.js";
|
||||
import { decodeObjcDispatchFacets } from "./AppleObjcDispatchFacets.js";
|
||||
import {
|
||||
@@ -25,10 +27,26 @@ export const decodeAppleDispatchMetadata = (
|
||||
provenance: { path: string; sha256: string },
|
||||
architecture = "arm64",
|
||||
): ObjcSwiftMetadata => {
|
||||
const { segments, sections, offset } = parseMachoLayout(bytes, architecture);
|
||||
const layout = parseMachoLayout(bytes, architecture);
|
||||
const { segments, sections, offset } = layout;
|
||||
const fixups = parsePointerFixups(
|
||||
bytes,
|
||||
layout.fixups,
|
||||
segments,
|
||||
layout.baseAddress,
|
||||
);
|
||||
const u32 = (address: bigint) => bytes.readUInt32LE(offset(address, 4));
|
||||
const pointer = (address: bigint) =>
|
||||
bytes.readBigUInt64LE(offset(address, 8));
|
||||
const decodePointer = (address: bigint) =>
|
||||
fixups.decode(address, bytes.readBigUInt64LE(offset(address, 8)));
|
||||
/** Rebased target of a pointer; a bind to another image reads as 0. */
|
||||
const pointer = (address: bigint) => {
|
||||
const decodedPointer = decodePointer(address);
|
||||
return decodedPointer.kind === "rebase" ? decodedPointer.target : 0n;
|
||||
};
|
||||
const bound = (address: bigint) => {
|
||||
const decodedPointer = decodePointer(address);
|
||||
return decodedPointer.kind === "bind" ? decodedPointer : undefined;
|
||||
};
|
||||
const location = (address: bigint) => ({
|
||||
address: `0x${address.toString(16)}`,
|
||||
file_offset: offset(address),
|
||||
@@ -73,13 +91,15 @@ export const decodeAppleDispatchMetadata = (
|
||||
const readers = {
|
||||
u32,
|
||||
i32: (address: bigint) => bytes.readInt32LE(offset(address, 4)),
|
||||
u64: (address: bigint) => bytes.readBigUInt64LE(offset(address, 8)),
|
||||
pointer,
|
||||
bound,
|
||||
string,
|
||||
location,
|
||||
evidence,
|
||||
offset,
|
||||
};
|
||||
const { failures, examined } = decodeObjcDispatchFacets({
|
||||
const { failures, examined, categoriesExamined } = decodeObjcDispatchFacets({
|
||||
bytes,
|
||||
sections,
|
||||
segments,
|
||||
@@ -130,47 +150,14 @@ export const decodeAppleDispatchMetadata = (
|
||||
),
|
||||
},
|
||||
});
|
||||
result.coverage.push({
|
||||
facet: "objc_class_method_ivar_metadata",
|
||||
status: failures.length > 0 || budget.truncated ? "partial" : "complete",
|
||||
reason:
|
||||
[...failures, ...(budget.truncated ? ["max_records_reached"] : [])].join(
|
||||
"; ",
|
||||
) || null,
|
||||
pushDispatchCoverage({
|
||||
result,
|
||||
failures,
|
||||
examined,
|
||||
decoded: result.objc_classes.length,
|
||||
categoriesExamined,
|
||||
truncated: budget.truncated,
|
||||
fixups,
|
||||
});
|
||||
result.coverage.push({
|
||||
facet: "binary_relative_pointers",
|
||||
status:
|
||||
budget.truncated ||
|
||||
result.relative_pointers.some((item) => item.decode.status !== "decoded")
|
||||
? "partial"
|
||||
: "complete",
|
||||
reason: budget.truncated
|
||||
? "max_records_reached"
|
||||
: result.relative_pointers.some(
|
||||
(item) => item.decode.status !== "decoded",
|
||||
)
|
||||
? "relative_pointer_targets_unresolved"
|
||||
: null,
|
||||
examined: result.relative_pointers.length,
|
||||
decoded: result.relative_pointers.filter(
|
||||
(item) => item.decode.status === "decoded",
|
||||
).length,
|
||||
});
|
||||
for (const facet of [
|
||||
"objc_properties_categories",
|
||||
"swift_generic_resilient_witnesses_overrides_async_coroutines",
|
||||
])
|
||||
result.coverage.push({
|
||||
facet,
|
||||
status: "unsupported",
|
||||
reason:
|
||||
"This reader admits validated 64-bit Objective-C class/ivar/method lists and simple Swift conformance/static witness records; chained fixups, generic/resilient tables and other metadata families are not decoded",
|
||||
examined: 0,
|
||||
decoded: 0,
|
||||
});
|
||||
return objcSwiftMetadataSchema.parse(result);
|
||||
};
|
||||
|
||||
|
||||
@@ -0,0 +1,275 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
decodeChainedPointer,
|
||||
parsePointerFixups,
|
||||
} from "./AppleMachoFixups.js";
|
||||
import { parsePropertyAttributes } from "./AppleObjcProperties.js";
|
||||
import type { Segment } from "./AppleMachoSelection.js";
|
||||
|
||||
const BASE = 0x100000000n;
|
||||
const IMPORTS = [
|
||||
{
|
||||
symbol: "_OBJC_CLASS_$_NSObject",
|
||||
library: "/usr/lib/libobjc.A.dylib",
|
||||
weak: false,
|
||||
addend: 0n,
|
||||
},
|
||||
{
|
||||
symbol: "_free",
|
||||
library: "/usr/lib/libSystem.B.dylib",
|
||||
weak: true,
|
||||
addend: 4n,
|
||||
},
|
||||
];
|
||||
|
||||
const field = (value: bigint, from: number): bigint => value << BigInt(from);
|
||||
|
||||
describe("chained pointer decoding", () => {
|
||||
it("decodes DYLD_CHAINED_PTR_64 and _64_OFFSET rebases and binds", () => {
|
||||
const rebase = 0x4000n | field(0x80n, 36) | field(3n, 51);
|
||||
expect(decodeChainedPointer(BASE + 0x4000n, 2, BASE, IMPORTS)).toEqual({
|
||||
kind: "rebase",
|
||||
target: BASE + 0x4000n,
|
||||
});
|
||||
expect(decodeChainedPointer(rebase, 6, BASE, IMPORTS)).toEqual({
|
||||
kind: "rebase",
|
||||
target: (0x80n << 56n) + BASE + 0x4000n,
|
||||
});
|
||||
const bind = 1n | field(2n, 24) | field(1n, 63);
|
||||
expect(decodeChainedPointer(bind, 6, BASE, IMPORTS)).toEqual({
|
||||
kind: "bind",
|
||||
symbol: "_free",
|
||||
library: "/usr/lib/libSystem.B.dylib",
|
||||
weak: true,
|
||||
addend: 6n,
|
||||
});
|
||||
});
|
||||
|
||||
it("decodes arm64e plain, authenticated and 24-bit binds", () => {
|
||||
expect(decodeChainedPointer(0x8000n, 9, BASE, IMPORTS)).toEqual({
|
||||
kind: "rebase",
|
||||
target: BASE + 0x8000n,
|
||||
});
|
||||
expect(decodeChainedPointer(BASE + 0x8000n, 1, BASE, IMPORTS)).toEqual({
|
||||
kind: "rebase",
|
||||
target: BASE + 0x8000n,
|
||||
});
|
||||
const authRebase = 0x8000n | field(0x1234n, 32) | field(1n, 63);
|
||||
expect(decodeChainedPointer(authRebase, 1, BASE, IMPORTS)).toEqual({
|
||||
kind: "rebase",
|
||||
target: BASE + 0x8000n,
|
||||
});
|
||||
const authBind = 0n | field(1n, 62) | field(1n, 63);
|
||||
expect(decodeChainedPointer(authBind, 9, BASE, IMPORTS)).toMatchObject({
|
||||
kind: "bind",
|
||||
symbol: "_OBJC_CLASS_$_NSObject",
|
||||
addend: 0n,
|
||||
});
|
||||
const bind24 = 1n | field(0x7ffffn, 32) | field(1n, 62);
|
||||
expect(decodeChainedPointer(bind24, 12, BASE, IMPORTS)).toMatchObject({
|
||||
kind: "bind",
|
||||
symbol: "_free",
|
||||
addend: 3n,
|
||||
});
|
||||
expect(() =>
|
||||
decodeChainedPointer(field(1n, 62) | 9n, 9, BASE, IMPORTS),
|
||||
).toThrow("Chained bind ordinal 9 has no import");
|
||||
expect(() => decodeChainedPointer(1n, 3, BASE, IMPORTS)).toThrow(
|
||||
"Unsupported chained pointer format 3",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
/** Build `LC_DYLD_CHAINED_FIXUPS` data with one fixup segment and the given imports. */
|
||||
const chainedData = (format: 1 | 2 | 3): Buffer => {
|
||||
const symbols = Buffer.from("\0_OBJC_CLASS_$_NSObject\0_free\0");
|
||||
const importSize = format === 3 ? 16 : format === 2 ? 8 : 4;
|
||||
const imports = Buffer.alloc(importSize * 2);
|
||||
const entry = (
|
||||
index: number,
|
||||
{
|
||||
ordinal,
|
||||
weak,
|
||||
nameOffset,
|
||||
addend,
|
||||
}: {
|
||||
ordinal: number;
|
||||
weak: boolean;
|
||||
nameOffset: number;
|
||||
addend: number;
|
||||
},
|
||||
) => {
|
||||
const at = index * importSize;
|
||||
if (format === 3) {
|
||||
imports.writeBigUInt64LE(
|
||||
BigInt(ordinal & 0xffff) |
|
||||
(BigInt(weak ? 1 : 0) << 16n) |
|
||||
(BigInt(nameOffset) << 32n),
|
||||
at,
|
||||
);
|
||||
imports.writeBigInt64LE(BigInt(addend), at + 8);
|
||||
} else {
|
||||
imports.writeUInt32LE(
|
||||
((nameOffset << 9) | ((weak ? 1 : 0) << 8) | (ordinal & 0xff)) >>> 0,
|
||||
at,
|
||||
);
|
||||
if (format === 2) imports.writeInt32LE(addend, at + 4);
|
||||
}
|
||||
};
|
||||
entry(0, { ordinal: 1, weak: false, nameOffset: 1, addend: 0 });
|
||||
entry(1, { ordinal: 2, weak: true, nameOffset: 24, addend: 7 });
|
||||
// starts_in_image: two segments, only the second has fixups.
|
||||
const starts = Buffer.alloc(12 + 24);
|
||||
starts.writeUInt32LE(2, 0);
|
||||
starts.writeUInt32LE(0, 4);
|
||||
starts.writeUInt32LE(12, 8);
|
||||
starts.writeUInt32LE(24, 12);
|
||||
starts.writeUInt16LE(0x4000, 16);
|
||||
starts.writeUInt16LE(6, 18);
|
||||
const header = Buffer.alloc(28);
|
||||
header.writeUInt32LE(0, 0);
|
||||
header.writeUInt32LE(28, 4);
|
||||
header.writeUInt32LE(28 + starts.length, 8);
|
||||
header.writeUInt32LE(28 + starts.length + imports.length, 12);
|
||||
header.writeUInt32LE(2, 16);
|
||||
header.writeUInt32LE(format, 20);
|
||||
header.writeUInt32LE(0, 24);
|
||||
return Buffer.concat([header, starts, imports, symbols]);
|
||||
};
|
||||
|
||||
const SEGMENTS: Segment[] = [
|
||||
{ address: BASE, size: 0x4000n, offset: 0, executable: true },
|
||||
{ address: BASE + 0x4000n, size: 0x4000n, offset: 0x4000, executable: false },
|
||||
];
|
||||
|
||||
describe("pointer fixup tables", () => {
|
||||
for (const format of [1, 2, 3] as const)
|
||||
it(`reads chained import format ${format}`, () => {
|
||||
const data = chainedData(format);
|
||||
const fixups = parsePointerFixups(
|
||||
data,
|
||||
{
|
||||
chained: { offset: 0, size: data.length },
|
||||
binds: [],
|
||||
dylibs: ["/usr/lib/libobjc.A.dylib", "/usr/lib/libSystem.B.dylib"],
|
||||
},
|
||||
SEGMENTS,
|
||||
BASE,
|
||||
);
|
||||
expect(fixups).toMatchObject({
|
||||
kind: "chained",
|
||||
formats: ["DYLD_CHAINED_PTR_64_OFFSET"],
|
||||
});
|
||||
expect(fixups.decode(BASE + 0x4008n, 1n | field(1n, 63))).toMatchObject({
|
||||
kind: "bind",
|
||||
symbol: "_free",
|
||||
library: "/usr/lib/libSystem.B.dylib",
|
||||
weak: true,
|
||||
addend: format === 1 ? 0n : 7n,
|
||||
});
|
||||
// Pointers outside fixup segments are stored plainly.
|
||||
expect(fixups.decode(BASE + 0x10n, 0x1234n)).toEqual({
|
||||
kind: "rebase",
|
||||
target: 0x1234n,
|
||||
});
|
||||
});
|
||||
|
||||
it("interprets legacy bind, weak-bind and lazy-bind opcodes", () => {
|
||||
const opcodes = Buffer.from([
|
||||
0x11, // SET_DYLIB_ORDINAL_IMM 1
|
||||
0x40,
|
||||
...Buffer.from("_OBJC_CLASS_$_NSObject\0"),
|
||||
0x51, // SET_TYPE_IMM pointer
|
||||
0x71,
|
||||
0x08, // SET_SEGMENT_AND_OFFSET segment 1 + 8
|
||||
0x90, // DO_BIND
|
||||
0xc0,
|
||||
0x02,
|
||||
0x08, // DO_BIND_ULEB_TIMES_SKIPPING_ULEB 2 times, skip 8
|
||||
0x00,
|
||||
]);
|
||||
const lazy = Buffer.from([
|
||||
0x71,
|
||||
0x30,
|
||||
0x12,
|
||||
0x40,
|
||||
...Buffer.from("_free\0"),
|
||||
0x90,
|
||||
0x00,
|
||||
0x71,
|
||||
0x38,
|
||||
0x12,
|
||||
0x40,
|
||||
...Buffer.from("_malloc\0"),
|
||||
0x90,
|
||||
0x00,
|
||||
]);
|
||||
const data = Buffer.concat([opcodes, lazy]);
|
||||
const fixups = parsePointerFixups(
|
||||
data,
|
||||
{
|
||||
chained: null,
|
||||
binds: [
|
||||
{ offset: 0, size: opcodes.length, stream: "bind" },
|
||||
{ offset: opcodes.length, size: lazy.length, stream: "lazy" },
|
||||
],
|
||||
dylibs: ["/usr/lib/libobjc.A.dylib", "/usr/lib/libSystem.B.dylib"],
|
||||
},
|
||||
SEGMENTS,
|
||||
BASE,
|
||||
);
|
||||
expect(fixups.kind).toBe("dyld-info");
|
||||
expect(fixups.failures).toEqual([]);
|
||||
for (const offset of [0x08n, 0x10n, 0x20n])
|
||||
expect(fixups.decode(BASE + 0x4000n + offset, 0n)).toMatchObject({
|
||||
kind: "bind",
|
||||
symbol: "_OBJC_CLASS_$_NSObject",
|
||||
library: "/usr/lib/libobjc.A.dylib",
|
||||
});
|
||||
expect(fixups.decode(BASE + 0x4038n, 0n)).toMatchObject({
|
||||
symbol: "_malloc",
|
||||
library: "/usr/lib/libSystem.B.dylib",
|
||||
});
|
||||
expect(fixups.decode(BASE + 0x4018n, 0x99n)).toEqual({
|
||||
kind: "rebase",
|
||||
target: 0x99n,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("Objective-C property attributes", () => {
|
||||
it("parses type, ownership, accessors and quoted class names", () => {
|
||||
expect(
|
||||
parsePropertyAttributes(
|
||||
"title",
|
||||
'T@"NSString<NSCopying, NSSecureCoding>",C,N,GcustomTitle,V_title',
|
||||
),
|
||||
).toEqual({
|
||||
name: "title",
|
||||
type_encoding: '@"NSString<NSCopying, NSSecureCoding>"',
|
||||
attributes: [
|
||||
expect.objectContaining({
|
||||
name: "T",
|
||||
value: '@"NSString<NSCopying, NSSecureCoding>"',
|
||||
}),
|
||||
expect.objectContaining({ name: "C", is_copy: true }),
|
||||
expect.objectContaining({ name: "N" }),
|
||||
expect.objectContaining({ name: "G", value: "customTitle" }),
|
||||
expect.objectContaining({ name: "V", value: "_title" }),
|
||||
],
|
||||
is_readonly: false,
|
||||
getter: "customTitle",
|
||||
setter: null,
|
||||
});
|
||||
expect(parsePropertyAttributes("count", "Tq,R,N")).toMatchObject({
|
||||
type_encoding: "q",
|
||||
is_readonly: true,
|
||||
});
|
||||
expect(
|
||||
parsePropertyAttributes("delegate", "T@,W,N,V_delegate").attributes[1],
|
||||
).toMatchObject({
|
||||
is_weak: true,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,414 @@
|
||||
import type { Segment } from "./AppleMachoSelection.js";
|
||||
|
||||
/** Where a Mach-O stores pointer fixups, from its load commands. */
|
||||
export interface FixupCommands {
|
||||
/** Absolute file range of `LC_DYLD_CHAINED_FIXUPS` data. */
|
||||
readonly chained: { readonly offset: number; readonly size: number } | null;
|
||||
/** Absolute file ranges of `LC_DYLD_INFO(_ONLY)` bind streams. */
|
||||
readonly binds: readonly {
|
||||
readonly offset: number;
|
||||
readonly size: number;
|
||||
readonly stream: "bind" | "weak" | "lazy";
|
||||
}[];
|
||||
/** Install names of dependent dylibs, in library-ordinal order. */
|
||||
readonly dylibs: readonly string[];
|
||||
}
|
||||
|
||||
/** One decoded pointer: a rebase to an in-image address or a bind to a symbol. */
|
||||
export type DecodedPointer =
|
||||
| { readonly kind: "rebase"; readonly target: bigint }
|
||||
| {
|
||||
readonly kind: "bind";
|
||||
readonly symbol: string;
|
||||
readonly library: string | null;
|
||||
readonly weak: boolean;
|
||||
readonly addend: bigint;
|
||||
};
|
||||
|
||||
/** Pointer decoding for one Mach-O slice. */
|
||||
export interface PointerFixups {
|
||||
readonly kind: "chained" | "dyld-info" | "none";
|
||||
/** Chained pointer formats in use, such as `DYLD_CHAINED_PTR_64_OFFSET`. */
|
||||
readonly formats: readonly string[];
|
||||
readonly failures: readonly string[];
|
||||
/** Decode the pointer stored at `address` whose raw 64-bit value is `raw`. */
|
||||
decode(address: bigint, raw: bigint): DecodedPointer;
|
||||
}
|
||||
|
||||
const POINTER_FORMATS: Readonly<Record<number, string>> = {
|
||||
1: "DYLD_CHAINED_PTR_ARM64E",
|
||||
2: "DYLD_CHAINED_PTR_64",
|
||||
6: "DYLD_CHAINED_PTR_64_OFFSET",
|
||||
9: "DYLD_CHAINED_PTR_ARM64E_USERLAND",
|
||||
12: "DYLD_CHAINED_PTR_ARM64E_USERLAND24",
|
||||
};
|
||||
|
||||
const bits = (value: bigint, from: number, width: number): bigint =>
|
||||
(value >> BigInt(from)) & ((1n << BigInt(width)) - 1n);
|
||||
|
||||
const signed = (value: bigint, width: number): bigint =>
|
||||
value >= 1n << BigInt(width - 1) ? value - (1n << BigInt(width)) : value;
|
||||
|
||||
interface Import {
|
||||
readonly symbol: string;
|
||||
readonly library: string | null;
|
||||
readonly weak: boolean;
|
||||
readonly addend: bigint;
|
||||
}
|
||||
|
||||
/** Library ordinal to install name; 0 and negative ordinals are special lookups. */
|
||||
const libraryName = (
|
||||
ordinal: number,
|
||||
dylibs: readonly string[],
|
||||
): string | null => {
|
||||
if (ordinal > 0) return dylibs[ordinal - 1] ?? null;
|
||||
return null;
|
||||
};
|
||||
|
||||
const cString = (bytes: Buffer, offset: number, end: number): string => {
|
||||
const stop = bytes.indexOf(0, offset);
|
||||
if (offset < 0 || offset >= end || stop < 0 || stop >= end)
|
||||
throw new RangeError("Fixup symbol name is outside the symbol pool");
|
||||
return bytes.toString("utf8", offset, stop);
|
||||
};
|
||||
|
||||
const readImports = (
|
||||
data: {
|
||||
readonly bytes: Buffer;
|
||||
readonly base: number;
|
||||
readonly end: number;
|
||||
readonly dylibs: readonly string[];
|
||||
},
|
||||
header: {
|
||||
readonly offset: number;
|
||||
readonly count: number;
|
||||
readonly format: number;
|
||||
readonly symbols: number;
|
||||
},
|
||||
): Import[] => {
|
||||
const { bytes, base, end, dylibs } = data;
|
||||
const size = header.format === 3 ? 16 : header.format === 2 ? 8 : 4;
|
||||
if (header.format < 1 || header.format > 3)
|
||||
throw new RangeError(`Unsupported chained import format ${header.format}`);
|
||||
if (base + header.offset + header.count * size > end)
|
||||
throw new RangeError("Chained import table exceeds the fixup data");
|
||||
return Array.from({ length: header.count }, (_, index) => {
|
||||
const at = base + header.offset + index * size;
|
||||
if (header.format === 3) {
|
||||
const word = bytes.readBigUInt64LE(at);
|
||||
const ordinal = Number(signed(bits(word, 0, 16), 16));
|
||||
return {
|
||||
symbol: cString(
|
||||
bytes,
|
||||
base + header.symbols + Number(bits(word, 32, 32)),
|
||||
end,
|
||||
),
|
||||
library: libraryName(ordinal, dylibs),
|
||||
weak: bits(word, 16, 1) === 1n,
|
||||
addend: bytes.readBigInt64LE(at + 8),
|
||||
};
|
||||
}
|
||||
const word = bytes.readUInt32LE(at);
|
||||
const ordinal = Number(signed(BigInt(word & 0xff), 8));
|
||||
return {
|
||||
symbol: cString(bytes, base + header.symbols + (word >>> 9), end),
|
||||
library: libraryName(ordinal, dylibs),
|
||||
weak: ((word >>> 8) & 1) === 1,
|
||||
addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,
|
||||
};
|
||||
});
|
||||
};
|
||||
|
||||
/** Decode one raw chained pointer for its segment's pointer format. */
|
||||
export const decodeChainedPointer = (
|
||||
raw: bigint,
|
||||
format: number,
|
||||
baseAddress: bigint,
|
||||
imports: readonly Import[],
|
||||
): DecodedPointer => {
|
||||
const bind = (ordinal: bigint, addend: bigint): DecodedPointer => {
|
||||
const target = imports[Number(ordinal)];
|
||||
if (target === undefined)
|
||||
throw new RangeError(`Chained bind ordinal ${ordinal} has no import`);
|
||||
return { kind: "bind", ...target, addend: target.addend + addend };
|
||||
};
|
||||
if (format === 2 || format === 6) {
|
||||
if (bits(raw, 63, 1) === 1n)
|
||||
return bind(bits(raw, 0, 24), bits(raw, 24, 8));
|
||||
const target = bits(raw, 0, 36) | (bits(raw, 36, 8) << 56n);
|
||||
return {
|
||||
kind: "rebase",
|
||||
target: format === 6 ? target + baseAddress : target,
|
||||
};
|
||||
}
|
||||
if (format === 1 || format === 9 || format === 12) {
|
||||
const auth = bits(raw, 63, 1) === 1n;
|
||||
if (bits(raw, 62, 1) === 1n)
|
||||
return bind(
|
||||
bits(raw, 0, format === 12 ? 24 : 16),
|
||||
auth ? 0n : signed(bits(raw, 32, 19), 19),
|
||||
);
|
||||
if (auth) return { kind: "rebase", target: bits(raw, 0, 32) + baseAddress };
|
||||
const target = bits(raw, 0, 43) | (bits(raw, 43, 8) << 56n);
|
||||
return {
|
||||
kind: "rebase",
|
||||
target: format === 1 ? target : target + baseAddress,
|
||||
};
|
||||
}
|
||||
throw new RangeError(`Unsupported chained pointer format ${format}`);
|
||||
};
|
||||
|
||||
/** The slice bytes and load-command facts that fixup decoding reads. */
|
||||
interface FixupImage {
|
||||
readonly bytes: Buffer;
|
||||
readonly segments: readonly Segment[];
|
||||
readonly dylibs: readonly string[];
|
||||
readonly baseAddress: bigint;
|
||||
}
|
||||
|
||||
const chainedFixups = (
|
||||
image: FixupImage,
|
||||
range: { readonly offset: number; readonly size: number },
|
||||
): PointerFixups => {
|
||||
const { bytes, segments, dylibs, baseAddress } = image;
|
||||
const base = range.offset;
|
||||
const end = range.offset + range.size;
|
||||
if (range.size < 28 || end > bytes.length)
|
||||
throw new RangeError("Chained fixup header exceeds the target");
|
||||
const startsOffset = bytes.readUInt32LE(base + 4);
|
||||
const imports = readImports(
|
||||
{ bytes, base, end, dylibs },
|
||||
{
|
||||
offset: bytes.readUInt32LE(base + 8),
|
||||
symbols: bytes.readUInt32LE(base + 12),
|
||||
count: bytes.readUInt32LE(base + 16),
|
||||
format: bytes.readUInt32LE(base + 20),
|
||||
},
|
||||
);
|
||||
if (bytes.readUInt32LE(base + 24) !== 0)
|
||||
throw new RangeError(
|
||||
"Compressed chained-fixup symbol names are not supported",
|
||||
);
|
||||
const starts = base + startsOffset;
|
||||
const segmentCount = bytes.readUInt32LE(starts);
|
||||
const ranges: {
|
||||
readonly from: bigint;
|
||||
readonly to: bigint;
|
||||
readonly format: number;
|
||||
}[] = [];
|
||||
for (let index = 0; index < segmentCount; index++) {
|
||||
const infoOffset = bytes.readUInt32LE(starts + 4 + index * 4);
|
||||
if (infoOffset === 0) continue;
|
||||
const segment = segments[index];
|
||||
if (segment === undefined || starts + infoOffset + 22 > end)
|
||||
throw new RangeError("Chained fixup segment table is out of range");
|
||||
ranges.push({
|
||||
from: segment.address,
|
||||
to: segment.address + segment.size,
|
||||
format: bytes.readUInt16LE(starts + infoOffset + 6),
|
||||
});
|
||||
}
|
||||
const formats = [
|
||||
...new Set(
|
||||
ranges.map(({ format }) => POINTER_FORMATS[format] ?? `format-${format}`),
|
||||
),
|
||||
];
|
||||
return {
|
||||
kind: "chained",
|
||||
formats,
|
||||
failures: [],
|
||||
decode(address, raw) {
|
||||
const segment = ranges.find(
|
||||
({ from, to }) => address >= from && address < to,
|
||||
);
|
||||
// Pointers outside fixup segments, such as in __TEXT, are stored plainly.
|
||||
if (segment === undefined) return { kind: "rebase", target: raw };
|
||||
if (raw === 0n) return { kind: "rebase", target: 0n };
|
||||
return decodeChainedPointer(raw, segment.format, baseAddress, imports);
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
const uleb = (bytes: Buffer, cursor: { at: number }, end: number): bigint => {
|
||||
let value = 0n;
|
||||
let shift = 0n;
|
||||
for (;;) {
|
||||
if (cursor.at >= end) throw new RangeError("Truncated bind opcode operand");
|
||||
const byte = bytes[cursor.at++] ?? 0;
|
||||
value |= BigInt(byte & 0x7f) << shift;
|
||||
shift += 7n;
|
||||
if ((byte & 0x80) === 0) return value;
|
||||
if (shift > 63n) throw new RangeError("Oversized bind opcode operand");
|
||||
}
|
||||
};
|
||||
|
||||
const sleb = (bytes: Buffer, cursor: { at: number }, end: number): bigint => {
|
||||
let value = 0n;
|
||||
let shift = 0n;
|
||||
let byte = 0;
|
||||
do {
|
||||
if (cursor.at >= end) throw new RangeError("Truncated bind opcode operand");
|
||||
byte = bytes[cursor.at++] ?? 0;
|
||||
value |= BigInt(byte & 0x7f) << shift;
|
||||
shift += 7n;
|
||||
} while ((byte & 0x80) !== 0 && shift <= 63n);
|
||||
return (byte & 0x40) !== 0 ? value - (1n << shift) : value;
|
||||
};
|
||||
|
||||
/** Registers of the `LC_DYLD_INFO` bind state machine. */
|
||||
interface BindState {
|
||||
ordinal: number;
|
||||
symbol: string;
|
||||
weak: boolean;
|
||||
addend: bigint;
|
||||
address: bigint;
|
||||
}
|
||||
|
||||
/** Apply a bind opcode that sets a register; false when the opcode is not one. */
|
||||
const setBindRegister = (
|
||||
image: FixupImage,
|
||||
stream: { readonly cursor: { at: number }; readonly end: number },
|
||||
state: BindState,
|
||||
byte: number,
|
||||
): boolean => {
|
||||
const { bytes } = image;
|
||||
const { cursor, end } = stream;
|
||||
const immediate = byte & 0x0f;
|
||||
switch (byte & 0xf0) {
|
||||
case 0x10:
|
||||
state.ordinal = immediate;
|
||||
return true;
|
||||
case 0x20:
|
||||
state.ordinal = Number(uleb(bytes, cursor, end));
|
||||
return true;
|
||||
case 0x30:
|
||||
state.ordinal = immediate === 0 ? 0 : immediate - 16;
|
||||
return true;
|
||||
case 0x40: {
|
||||
const stop = bytes.indexOf(0, cursor.at);
|
||||
if (stop < 0 || stop >= end)
|
||||
throw new RangeError("Unterminated bind symbol");
|
||||
state.symbol = bytes.toString("utf8", cursor.at, stop);
|
||||
state.weak = (immediate & 0x1) !== 0;
|
||||
cursor.at = stop + 1;
|
||||
return true;
|
||||
}
|
||||
case 0x50:
|
||||
return true;
|
||||
case 0x60:
|
||||
state.addend = sleb(bytes, cursor, end);
|
||||
return true;
|
||||
case 0x70: {
|
||||
const segment = image.segments[immediate];
|
||||
if (segment === undefined)
|
||||
throw new RangeError("Bind segment index is out of range");
|
||||
state.address = segment.address + uleb(bytes, cursor, end);
|
||||
return true;
|
||||
}
|
||||
case 0x80:
|
||||
// ULEB deltas wrap at 64 bits to encode negative steps.
|
||||
state.address =
|
||||
(state.address + uleb(bytes, cursor, end)) & 0xffffffffffffffffn;
|
||||
return true;
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
/** Interpret one `LC_DYLD_INFO` bind opcode stream into address -> import. */
|
||||
const readBindStream = (
|
||||
image: FixupImage,
|
||||
range: FixupCommands["binds"][number],
|
||||
binds: Map<bigint, Import>,
|
||||
): void => {
|
||||
const { bytes } = image;
|
||||
const end = range.offset + range.size;
|
||||
if (end > bytes.length)
|
||||
throw new RangeError("Bind opcodes exceed the target");
|
||||
const cursor = { at: range.offset };
|
||||
const state: BindState = {
|
||||
ordinal: 0,
|
||||
symbol: "",
|
||||
weak: false,
|
||||
addend: 0n,
|
||||
address: 0n,
|
||||
};
|
||||
const bind = (skip: bigint): void => {
|
||||
binds.set(state.address, {
|
||||
symbol: state.symbol,
|
||||
library:
|
||||
range.stream === "weak"
|
||||
? null
|
||||
: libraryName(state.ordinal, image.dylibs),
|
||||
weak: state.weak,
|
||||
addend: state.addend,
|
||||
});
|
||||
state.address += 8n + skip;
|
||||
};
|
||||
while (cursor.at < end) {
|
||||
const byte = bytes[cursor.at++] ?? 0;
|
||||
if (setBindRegister(image, { cursor, end }, state, byte)) continue;
|
||||
switch (byte & 0xf0) {
|
||||
case 0x00:
|
||||
// DONE separates lazy-bind entries; other streams end here.
|
||||
if (range.stream !== "lazy") return;
|
||||
break;
|
||||
case 0x90:
|
||||
bind(0n);
|
||||
break;
|
||||
case 0xa0:
|
||||
bind(uleb(bytes, cursor, end));
|
||||
break;
|
||||
case 0xb0:
|
||||
bind(BigInt(byte & 0x0f) * 8n);
|
||||
break;
|
||||
case 0xc0: {
|
||||
const count = uleb(bytes, cursor, end);
|
||||
const skip = uleb(bytes, cursor, end);
|
||||
for (let index = 0n; index < count; index++) bind(skip);
|
||||
break;
|
||||
}
|
||||
default:
|
||||
throw new RangeError(`Unsupported bind opcode 0x${byte.toString(16)}`);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/** Build pointer decoding for one slice from its fixup load commands. */
|
||||
export const parsePointerFixups = (
|
||||
bytes: Buffer,
|
||||
commands: FixupCommands,
|
||||
segments: readonly Segment[],
|
||||
baseAddress: bigint,
|
||||
): PointerFixups => {
|
||||
const image = { bytes, segments, dylibs: commands.dylibs, baseAddress };
|
||||
if (commands.chained !== null) return chainedFixups(image, commands.chained);
|
||||
if (commands.binds.length === 0)
|
||||
return {
|
||||
kind: "none",
|
||||
formats: [],
|
||||
failures: [],
|
||||
decode: (_address, raw) => ({ kind: "rebase", target: raw }),
|
||||
};
|
||||
const binds = new Map<bigint, Import>();
|
||||
const failures: string[] = [];
|
||||
for (const stream of commands.binds)
|
||||
try {
|
||||
readBindStream(image, stream, binds);
|
||||
} catch (cause: unknown) {
|
||||
failures.push(
|
||||
`${stream.stream} bind opcodes: ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
);
|
||||
}
|
||||
return {
|
||||
kind: "dyld-info",
|
||||
formats: [],
|
||||
failures,
|
||||
decode(address, raw) {
|
||||
const bound = binds.get(address);
|
||||
return bound === undefined
|
||||
? { kind: "rebase", target: raw }
|
||||
: { kind: "bind", ...bound };
|
||||
},
|
||||
};
|
||||
};
|
||||
@@ -1,3 +1,5 @@
|
||||
import type { FixupCommands } from "./AppleMachoFixups.js";
|
||||
|
||||
/** One mapped Mach-O segment with file-backed VA range. */
|
||||
export interface Segment {
|
||||
address: bigint;
|
||||
@@ -23,6 +25,10 @@ export interface MachoSlice {
|
||||
export interface MachoLayout {
|
||||
segments: Segment[];
|
||||
sections: Section[];
|
||||
/** Fixup load commands and dependent dylibs of the selected slice. */
|
||||
fixups: FixupCommands;
|
||||
/** VM address of the segment that maps file offset 0 (the preferred load address). */
|
||||
baseAddress: bigint;
|
||||
/** Map a virtual address range onto a file offset within the selected slice. */
|
||||
offset(address: bigint, size?: number): number;
|
||||
}
|
||||
@@ -112,48 +118,31 @@ export const parseMachoLayout = (
|
||||
const commandEnd = slice + 32 + bytes.readUInt32LE(slice + 20);
|
||||
if (commands > 4096 || commandEnd > sliceEnd)
|
||||
throw new RangeError("Malformed Mach-O command bounds");
|
||||
const segments: Segment[] = [];
|
||||
const sections: Section[] = [];
|
||||
const state: LayoutState = {
|
||||
slice,
|
||||
sliceEnd,
|
||||
segments: [],
|
||||
sections: [],
|
||||
dylibs: [],
|
||||
binds: [],
|
||||
chained: null,
|
||||
baseAddress: undefined,
|
||||
};
|
||||
let cursor = slice + 32;
|
||||
for (let index = 0; index < commands; index++) {
|
||||
if (cursor + 8 > commandEnd) throw new RangeError("Truncated load command");
|
||||
const kind = bytes.readUInt32LE(cursor),
|
||||
size = bytes.readUInt32LE(cursor + 4);
|
||||
if (size < 8 || cursor + size > commandEnd)
|
||||
const command = {
|
||||
cursor,
|
||||
kind: bytes.readUInt32LE(cursor),
|
||||
size: bytes.readUInt32LE(cursor + 4),
|
||||
};
|
||||
if (command.size < 8 || cursor + command.size > commandEnd)
|
||||
throw new RangeError("Invalid load command size");
|
||||
if (kind === 0x19) {
|
||||
if (size < 72) throw new RangeError("Truncated segment command");
|
||||
const address = bytes.readBigUInt64LE(cursor + 24),
|
||||
fileSize = bytes.readBigUInt64LE(cursor + 48),
|
||||
fileOffset = bytes.readBigUInt64LE(cursor + 40);
|
||||
if (fileOffset + fileSize > BigInt(sliceEnd - slice))
|
||||
throw new RangeError("Segment file range exceeds target bytes");
|
||||
segments.push({
|
||||
address,
|
||||
size: fileSize,
|
||||
offset: slice + Number(fileOffset),
|
||||
executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,
|
||||
});
|
||||
const count = bytes.readUInt32LE(cursor + 64);
|
||||
if (72 + count * 80 > size)
|
||||
throw new RangeError("Truncated section table");
|
||||
for (let section = 0; section < count; section++) {
|
||||
const position = cursor + 72 + section * 80;
|
||||
const sectionSize = bytes.readBigUInt64LE(position + 40);
|
||||
if (sectionSize > BigInt(Number.MAX_SAFE_INTEGER))
|
||||
throw new RangeError("Section size exceeds exact numeric range");
|
||||
sections.push({
|
||||
name: bytes
|
||||
.subarray(position, position + 16)
|
||||
.toString("ascii")
|
||||
.replace(/\0.*$/u, ""),
|
||||
address: bytes.readBigUInt64LE(position + 32),
|
||||
size: Number(sectionSize),
|
||||
});
|
||||
}
|
||||
}
|
||||
cursor += size;
|
||||
if (command.kind === 0x19) collectSegment(bytes, command, state);
|
||||
else collectFixupCommand(bytes, command, state);
|
||||
cursor += command.size;
|
||||
}
|
||||
const { segments, sections, chained, binds, dylibs } = state;
|
||||
const offset = (address: bigint, size = 1): number => {
|
||||
const matches = segments.filter(
|
||||
(segment) =>
|
||||
@@ -168,5 +157,109 @@ export const parseMachoLayout = (
|
||||
if (segment === undefined) throw new RangeError("Missing metadata segment");
|
||||
return segment.offset + Number(address - segment.address);
|
||||
};
|
||||
return { segments, sections, offset };
|
||||
return {
|
||||
segments,
|
||||
sections,
|
||||
offset,
|
||||
fixups: { chained, binds, dylibs },
|
||||
baseAddress: state.baseAddress ?? 0n,
|
||||
};
|
||||
};
|
||||
|
||||
/** Load commands and fixup ranges collected while walking one slice. */
|
||||
interface LayoutState {
|
||||
readonly slice: number;
|
||||
readonly sliceEnd: number;
|
||||
readonly segments: Segment[];
|
||||
readonly sections: Section[];
|
||||
readonly dylibs: string[];
|
||||
readonly binds: FixupCommands["binds"][number][];
|
||||
chained: FixupCommands["chained"];
|
||||
baseAddress: bigint | undefined;
|
||||
}
|
||||
|
||||
/** One load command header inside the selected slice. */
|
||||
interface LoadCommand {
|
||||
readonly cursor: number;
|
||||
readonly kind: number;
|
||||
readonly size: number;
|
||||
}
|
||||
|
||||
/** Record an `LC_SEGMENT_64` and its section table. */
|
||||
const collectSegment = (
|
||||
bytes: Buffer,
|
||||
{ cursor, size }: LoadCommand,
|
||||
state: LayoutState,
|
||||
): void => {
|
||||
if (size < 72) throw new RangeError("Truncated segment command");
|
||||
const address = bytes.readBigUInt64LE(cursor + 24),
|
||||
fileSize = bytes.readBigUInt64LE(cursor + 48),
|
||||
fileOffset = bytes.readBigUInt64LE(cursor + 40);
|
||||
if (fileOffset + fileSize > BigInt(state.sliceEnd - state.slice))
|
||||
throw new RangeError("Segment file range exceeds target bytes");
|
||||
state.segments.push({
|
||||
address,
|
||||
size: fileSize,
|
||||
offset: state.slice + Number(fileOffset),
|
||||
executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,
|
||||
});
|
||||
if (fileOffset === 0n && fileSize > 0n) state.baseAddress ??= address;
|
||||
const count = bytes.readUInt32LE(cursor + 64);
|
||||
if (72 + count * 80 > size) throw new RangeError("Truncated section table");
|
||||
for (let section = 0; section < count; section++) {
|
||||
const position = cursor + 72 + section * 80;
|
||||
const sectionSize = bytes.readBigUInt64LE(position + 40);
|
||||
if (sectionSize > BigInt(Number.MAX_SAFE_INTEGER))
|
||||
throw new RangeError("Section size exceeds exact numeric range");
|
||||
state.sections.push({
|
||||
name: bytes
|
||||
.subarray(position, position + 16)
|
||||
.toString("ascii")
|
||||
.replace(/\0.*$/u, ""),
|
||||
address: bytes.readBigUInt64LE(position + 32),
|
||||
size: Number(sectionSize),
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
const LC_DYLD_INFO = 0x22;
|
||||
const LC_DYLD_INFO_ONLY = 0x80000022;
|
||||
const LC_DYLD_CHAINED_FIXUPS = 0x80000034;
|
||||
const DYLIB_COMMANDS: readonly number[] = [
|
||||
0xc, 0x80000018, 0x8000001f, 0x20, 0x80000023,
|
||||
];
|
||||
|
||||
/** Record fixup data ranges and dylib install names from one load command. */
|
||||
const collectFixupCommand = (
|
||||
bytes: Buffer,
|
||||
{ cursor, kind, size }: LoadCommand,
|
||||
state: LayoutState,
|
||||
): void => {
|
||||
const range = (at: number): { offset: number; size: number } => {
|
||||
const offset = state.slice + bytes.readUInt32LE(at);
|
||||
const length = bytes.readUInt32LE(at + 4);
|
||||
if (offset + length > state.sliceEnd)
|
||||
throw new RangeError("Fixup data exceeds the Mach-O slice");
|
||||
return { offset, size: length };
|
||||
};
|
||||
if (kind === LC_DYLD_CHAINED_FIXUPS && size >= 16)
|
||||
state.chained = range(cursor + 8);
|
||||
else if ((kind === LC_DYLD_INFO || kind === LC_DYLD_INFO_ONLY) && size >= 48)
|
||||
for (const [at, stream] of [
|
||||
[cursor + 16, "bind"],
|
||||
[cursor + 24, "weak"],
|
||||
[cursor + 32, "lazy"],
|
||||
] as const) {
|
||||
const bound = range(at);
|
||||
if (bound.size > 0) state.binds.push({ ...bound, stream });
|
||||
}
|
||||
else if (DYLIB_COMMANDS.includes(kind) && size >= 24) {
|
||||
const nameOffset = bytes.readUInt32LE(cursor + 8);
|
||||
const end = bytes.indexOf(0, cursor + nameOffset);
|
||||
state.dylibs.push(
|
||||
nameOffset >= size || end < 0 || end > cursor + size
|
||||
? ""
|
||||
: bytes.toString("utf8", cursor + nameOffset, end),
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";
|
||||
import type { Section } from "./AppleMachoSelection.js";
|
||||
import type { ObjcDispatchReaders } from "./AppleObjcDispatchFacets.js";
|
||||
import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
|
||||
|
||||
const CLASS_SYMBOL = /^_OBJC_(?:META)?CLASS_\$_(.+)$/u;
|
||||
|
||||
/** External class name from a bound `_OBJC_CLASS_$_Name` symbol. */
|
||||
export const boundClassName = (
|
||||
read: Pick<ObjcDispatchReaders, "bound">,
|
||||
field: bigint,
|
||||
): string | undefined => {
|
||||
const bound = read.bound(field);
|
||||
return bound === undefined ? undefined : CLASS_SYMBOL.exec(bound.symbol)?.[1];
|
||||
};
|
||||
|
||||
/**
|
||||
* Decode `__objc_catlist` `category_t` records:
|
||||
* name, cls, instanceMethods, classMethods, protocols, instanceProperties.
|
||||
*/
|
||||
export const decodeObjcCategories = (input: {
|
||||
readonly sections: readonly Section[];
|
||||
readonly read: ObjcDispatchReaders;
|
||||
readonly result: ObjcSwiftMetadata;
|
||||
readonly failures: string[];
|
||||
readonly admit: () => boolean;
|
||||
/** Decode a method list into implementations attributed to the category. */
|
||||
readonly methods: (
|
||||
list: bigint,
|
||||
className: string,
|
||||
methodType: "instance" | "class",
|
||||
category: string,
|
||||
) => string[];
|
||||
readonly protocols: (list: bigint) => string[];
|
||||
/** Name of a class defined in this image, from its class_ro_t. */
|
||||
readonly localClassName: (address: bigint) => string;
|
||||
}): number => {
|
||||
const { read, result, failures } = input;
|
||||
let examined = 0;
|
||||
for (const section of input.sections.filter(
|
||||
({ name }) => name === "__objc_catlist",
|
||||
)) {
|
||||
if (section.size % 8 !== 0)
|
||||
throw new RangeError("Misaligned Objective-C category list");
|
||||
for (let index = 0; index < section.size / 8; index++) {
|
||||
if (!input.admit()) break;
|
||||
examined++;
|
||||
const field = section.address + BigInt(index * 8);
|
||||
try {
|
||||
const category = read.pointer(field);
|
||||
const name = read.string(read.pointer(category));
|
||||
const external = boundClassName(read, category + 8n);
|
||||
const local = read.pointer(category + 8n);
|
||||
const className =
|
||||
external ?? (local === 0n ? null : input.localClassName(local));
|
||||
const owner = className ?? `(${name})`;
|
||||
result.objc_categories.push({
|
||||
name,
|
||||
class_name: className,
|
||||
class_source:
|
||||
external !== undefined
|
||||
? "external"
|
||||
: className === null
|
||||
? "unresolved"
|
||||
: "local",
|
||||
instance_methods: input.methods(
|
||||
read.pointer(category + 16n),
|
||||
owner,
|
||||
"instance",
|
||||
name,
|
||||
),
|
||||
class_methods: input.methods(
|
||||
read.pointer(category + 24n),
|
||||
owner,
|
||||
"class",
|
||||
name,
|
||||
),
|
||||
protocols: input.protocols(read.pointer(category + 32n)),
|
||||
properties: readObjcPropertiesOf(read, read.pointer(category + 40n), {
|
||||
owner: `category ${name}`,
|
||||
admit: input.admit,
|
||||
failures,
|
||||
}),
|
||||
location: read.location(category),
|
||||
decode:
|
||||
className === null
|
||||
? { status: "partial", reason: "category_class_unresolved" }
|
||||
: { status: "decoded", reason: null },
|
||||
evidence: read.evidence(category, "Objective-C category_t record"),
|
||||
});
|
||||
} catch (cause: unknown) {
|
||||
failures.push(
|
||||
`Category at ${`0x${field.toString(16)}`}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
return examined;
|
||||
};
|
||||
@@ -1,5 +1,7 @@
|
||||
import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";
|
||||
import type { Segment, Section } from "./AppleMachoSelection.js";
|
||||
import { boundClassName, decodeObjcCategories } from "./AppleObjcCategories.js";
|
||||
import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
|
||||
import { createObjcProtocolReader } from "./AppleObjcProtocols.js";
|
||||
import type {
|
||||
BinaryMetadataEvidence,
|
||||
@@ -10,8 +12,14 @@ import type {
|
||||
/** Byte readers shared by Objective-C class/method/ivar decode facets. */
|
||||
export interface ObjcDispatchReaders {
|
||||
u32(address: bigint): number;
|
||||
/** Plain 64-bit data, never a fixup. */
|
||||
u64(address: bigint): bigint;
|
||||
i32(address: bigint): number;
|
||||
pointer(address: bigint): bigint;
|
||||
/** The symbol a pointer at `address` is bound to, when it is a bind fixup. */
|
||||
bound(
|
||||
address: bigint,
|
||||
): { readonly symbol: string; readonly library: string | null } | undefined;
|
||||
string(address: bigint): string;
|
||||
location(address: bigint): ResolvedMetadataLocation;
|
||||
evidence(address: bigint, description: string): BinaryMetadataEvidence;
|
||||
@@ -21,6 +29,36 @@ export interface ObjcDispatchReaders {
|
||||
const hex = (value: bigint) => `0x${value.toString(16)}`;
|
||||
const decoded = { status: "decoded" as const, reason: null };
|
||||
|
||||
/** Name of a class defined in this image, from its class_ro_t. */
|
||||
const localClassName = (read: ObjcDispatchReaders, address: bigint): string =>
|
||||
read.string(read.pointer((read.pointer(address + 32n) & ~7n) + 24n));
|
||||
|
||||
/**
|
||||
* Resolve a class's superclass: a bind to `_OBJC_CLASS_$_Name` names a class
|
||||
* in another image; otherwise the pointer is a class_t in this image.
|
||||
*/
|
||||
const resolveSuperclass = (
|
||||
read: ObjcDispatchReaders,
|
||||
address: bigint,
|
||||
className: string,
|
||||
failures: string[],
|
||||
): { name: string | null; address: string | null } => {
|
||||
const external = boundClassName(read, address + 8n);
|
||||
if (external !== undefined) return { name: external, address: null };
|
||||
const superclass = read.pointer(address + 8n);
|
||||
if (superclass === 0n) return { name: null, address: null };
|
||||
try {
|
||||
return { name: localClassName(read, superclass), address: hex(superclass) };
|
||||
} catch (cause: unknown) {
|
||||
// Superclass resolution failure is recorded; the cause adds no identity.
|
||||
void cause;
|
||||
failures.push(
|
||||
`Superclass pointer ${hex(superclass)} of ${className} requires unsupported binding/fixup resolution`,
|
||||
);
|
||||
return { name: null, address: hex(superclass) };
|
||||
}
|
||||
};
|
||||
|
||||
/** Decode Objective-C protocol lists, classlists, methods, and ivars into `result`. */
|
||||
export const decodeObjcDispatchFacets = (input: {
|
||||
bytes: Buffer;
|
||||
@@ -29,7 +67,7 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
readers: ObjcDispatchReaders;
|
||||
budget: DispatchRecordBudget;
|
||||
result: ObjcSwiftMetadata;
|
||||
}): { failures: string[]; examined: number } => {
|
||||
}): { failures: string[]; examined: number; categoriesExamined: number } => {
|
||||
const { bytes, sections, segments, readers: read, budget, result } = input;
|
||||
const failures: string[] = [];
|
||||
let examined = 0;
|
||||
@@ -37,8 +75,10 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
list: bigint,
|
||||
className: string,
|
||||
methodType: "instance" | "class",
|
||||
) => {
|
||||
if (list === 0n) return;
|
||||
category?: string,
|
||||
): string[] => {
|
||||
const selectors: string[] = [];
|
||||
if (list === 0n) return selectors;
|
||||
const flags = read.u32(list),
|
||||
count = read.u32(list + 4n),
|
||||
relative = (flags & 0x80000000) !== 0;
|
||||
@@ -103,10 +143,13 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
// best-effort cleanup: external/chained pointers remain unresolved.
|
||||
void cause;
|
||||
}
|
||||
const selector = read.string(selectorAddress);
|
||||
selectors.push(selector);
|
||||
result.objc_dispatch_implementations.push({
|
||||
class_name: className,
|
||||
selector: read.string(selectorAddress),
|
||||
selector,
|
||||
method_type: methodType,
|
||||
...(category === undefined ? {} : { category }),
|
||||
implementation_address: implementationLocation?.address ?? null,
|
||||
location: read.location(entry),
|
||||
decode:
|
||||
@@ -124,6 +167,7 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
),
|
||||
});
|
||||
}
|
||||
return selectors;
|
||||
};
|
||||
const protocolReader = createObjcProtocolReader({
|
||||
readers: {
|
||||
@@ -134,6 +178,7 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
evidence: read.evidence,
|
||||
admit: () => budget.admit(),
|
||||
i32: read.i32,
|
||||
u64: read.u64,
|
||||
},
|
||||
result,
|
||||
failures,
|
||||
@@ -157,23 +202,9 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
visited.add(hex(address));
|
||||
const ro = read.pointer(address + 32n) & ~7n;
|
||||
const name = read.string(read.pointer(ro + 24n));
|
||||
const superclass = read.pointer(address + 8n);
|
||||
const root = (read.u32(ro) & 2) !== 0;
|
||||
let superclassName: string | null = null;
|
||||
if (superclass !== 0n) {
|
||||
try {
|
||||
superclassName = read.string(
|
||||
read.pointer((read.pointer(superclass + 32n) & ~7n) + 24n),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
// Superclass resolution failure is recorded; the cause adds no identity.
|
||||
void cause;
|
||||
failures.push(
|
||||
`Superclass pointer ${hex(superclass)} of ${name} requires unsupported binding/fixup resolution`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (superclass === 0n && !root)
|
||||
const superclass = resolveSuperclass(read, address, name, failures);
|
||||
if (superclass.name === null && superclass.address === null && !root)
|
||||
failures.push(
|
||||
`Superclass of ${name} requires external binding resolution`,
|
||||
);
|
||||
@@ -220,7 +251,7 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
methods(read.pointer(ro + 32n), name, meta ? "class" : "instance");
|
||||
result.objc_classes.push({
|
||||
name,
|
||||
super_class: superclassName,
|
||||
super_class: superclass.name,
|
||||
is_meta_class: meta,
|
||||
is_root_class: root,
|
||||
methods: result.objc_dispatch_implementations
|
||||
@@ -241,15 +272,19 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
is_required: false,
|
||||
is_optional: false,
|
||||
})),
|
||||
properties: [],
|
||||
properties: readObjcPropertiesOf(read, read.pointer(ro + 64n), {
|
||||
owner: name,
|
||||
admit: () => budget.admit(),
|
||||
failures,
|
||||
}),
|
||||
protocols: protocolReader.list(read.pointer(ro + 40n)),
|
||||
ivar_count: ivarCount,
|
||||
instance_size: read.u32(ro + 8n),
|
||||
location: read.location(address),
|
||||
superclass_address: superclass === 0n ? null : hex(superclass),
|
||||
superclass_address: superclass.address,
|
||||
metaclass_address: meta ? null : hex(read.pointer(address)),
|
||||
decode:
|
||||
superclassName === null && !root
|
||||
superclass.name === null && !root
|
||||
? { status: "partial", reason: "superclass_binding_unresolved" }
|
||||
: decoded,
|
||||
evidence: read.evidence(
|
||||
@@ -288,5 +323,15 @@ export const decodeObjcDispatchFacets = (input: {
|
||||
}
|
||||
}
|
||||
}
|
||||
return { failures, examined };
|
||||
const categoriesExamined = decodeObjcCategories({
|
||||
sections,
|
||||
read,
|
||||
result,
|
||||
failures,
|
||||
admit: () => budget.admit(),
|
||||
methods,
|
||||
protocols: (list) => protocolReader.list(list),
|
||||
localClassName: (address) => localClassName(read, address),
|
||||
});
|
||||
return { failures, examined, categoriesExamined };
|
||||
};
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
import type { z } from "zod";
|
||||
|
||||
import type { objcPropertySchema } from "../domain/objcSwiftMetadata.js";
|
||||
|
||||
type ObjcProperty = z.infer<typeof objcPropertySchema>;
|
||||
|
||||
/** Byte readers needed to decode an Objective-C `property_list_t`. */
|
||||
export interface ObjcPropertyReaders {
|
||||
u32(address: bigint): number;
|
||||
pointer(address: bigint): bigint;
|
||||
string(address: bigint): string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse an `@property` attribute string such as `T@"NSString",C,N,V_name`.
|
||||
* Each comma-separated token is one attribute; `T` is the type encoding.
|
||||
*/
|
||||
export const parsePropertyAttributes = (
|
||||
name: string,
|
||||
attributes: string,
|
||||
): ObjcProperty => {
|
||||
const tokens = attributes.length === 0 ? [] : splitAttributes(attributes);
|
||||
const value = (code: string): string | null =>
|
||||
tokens.find((token) => token.startsWith(code))?.slice(1) ?? null;
|
||||
return {
|
||||
name,
|
||||
type_encoding: value("T"),
|
||||
attributes: tokens.map((token) => ({
|
||||
name: token.slice(0, 1),
|
||||
value: token.slice(1),
|
||||
is_weak: token === "W",
|
||||
is_atomic: false,
|
||||
is_copy: token === "C",
|
||||
is_strong: token === "&",
|
||||
})),
|
||||
is_readonly: tokens.includes("R"),
|
||||
getter: value("G"),
|
||||
setter: value("S"),
|
||||
};
|
||||
};
|
||||
|
||||
/** Split on commas that are outside a quoted class name in the type encoding. */
|
||||
const splitAttributes = (attributes: string): string[] => {
|
||||
const tokens: string[] = [];
|
||||
let current = "";
|
||||
let quoted = false;
|
||||
for (const character of attributes) {
|
||||
if (character === '"') quoted = !quoted;
|
||||
if (character === "," && !quoted) {
|
||||
tokens.push(current);
|
||||
current = "";
|
||||
} else current += character;
|
||||
}
|
||||
tokens.push(current);
|
||||
return tokens.filter((token) => token.length > 0);
|
||||
};
|
||||
|
||||
/** Decode `property_list_t { entsize_and_flags, count, property_t[] }`. */
|
||||
export const readObjcPropertyList = (
|
||||
read: ObjcPropertyReaders,
|
||||
list: bigint,
|
||||
admit: () => boolean,
|
||||
): ObjcProperty[] => {
|
||||
if (list === 0n) return [];
|
||||
const entrySize = read.u32(list) & ~3;
|
||||
const count = read.u32(list + 4n);
|
||||
if (entrySize !== 16)
|
||||
throw new TypeError(
|
||||
`Unsupported Objective-C property entry size ${entrySize}`,
|
||||
);
|
||||
const properties: ObjcProperty[] = [];
|
||||
for (let index = 0; index < count; index++) {
|
||||
if (!admit()) break;
|
||||
const entry = list + 8n + BigInt(index * entrySize);
|
||||
properties.push(
|
||||
parsePropertyAttributes(
|
||||
read.string(read.pointer(entry)),
|
||||
read.string(read.pointer(entry + 8n)),
|
||||
),
|
||||
);
|
||||
}
|
||||
return properties;
|
||||
};
|
||||
|
||||
/** Decode a property list, recording a failure for `owner` instead of throwing. */
|
||||
export const readObjcPropertiesOf = (
|
||||
read: ObjcPropertyReaders,
|
||||
list: bigint,
|
||||
context: {
|
||||
readonly owner: string;
|
||||
readonly admit: () => boolean;
|
||||
readonly failures: string[];
|
||||
},
|
||||
): ObjcProperty[] => {
|
||||
try {
|
||||
return readObjcPropertyList(read, list, context.admit);
|
||||
} catch (cause: unknown) {
|
||||
context.failures.push(
|
||||
`Properties of ${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
);
|
||||
return [];
|
||||
}
|
||||
};
|
||||
@@ -6,7 +6,12 @@ export const createObjcProtocolReader = (input: {
|
||||
readers: Pick<
|
||||
SwiftMetadataReaders,
|
||||
"u32" | "string" | "location" | "evidence" | "admit"
|
||||
> & { pointer(address: bigint): bigint; i32(address: bigint): number };
|
||||
> & {
|
||||
pointer(address: bigint): bigint;
|
||||
/** Plain 64-bit data, never a fixup. */
|
||||
u64(address: bigint): bigint;
|
||||
i32(address: bigint): number;
|
||||
};
|
||||
result: ObjcSwiftMetadata;
|
||||
failures: string[];
|
||||
}) => {
|
||||
@@ -15,7 +20,8 @@ export const createObjcProtocolReader = (input: {
|
||||
const name = (address: bigint) => read.string(read.pointer(address + 8n));
|
||||
const list = (address: bigint): string[] => {
|
||||
if (address === 0n) return [];
|
||||
const count = read.pointer(address);
|
||||
// `count` is plain uintptr_t data, not a pointer fixup.
|
||||
const count = read.u64(address);
|
||||
if (count > 20000n)
|
||||
throw new RangeError("Protocol list exceeds 20000 entries");
|
||||
const names: string[] = [];
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
@interface ReaDispatchFixture : NSObject <ReaDispatchProtocol> {
|
||||
int state;
|
||||
}
|
||||
@property(nonatomic, copy) NSString *fixtureName;
|
||||
- (void)performAction:(id)sender;
|
||||
+ (int)fixtureVersion;
|
||||
@end
|
||||
@@ -16,4 +17,11 @@
|
||||
- (void)performAction:(id)sender { state += sender == nil ? 1 : 2; }
|
||||
+ (int)fixtureVersion { return 1; }
|
||||
@end
|
||||
|
||||
@interface NSString (ReaDispatchAdditions)
|
||||
- (NSUInteger)reaFixtureLength;
|
||||
@end
|
||||
@implementation NSString (ReaDispatchAdditions)
|
||||
- (NSUInteger)reaFixtureLength { return self.length; }
|
||||
@end
|
||||
int main(void) { return 0; }
|
||||
|
||||
+28
-6
@@ -1,15 +1,16 @@
|
||||
# REA website
|
||||
|
||||
An English static website with explanatory figures, worked guides and a DX-Ball investigation.
|
||||
An English static website with explanatory figures, worked guides and DX-Ball and Notion investigations.
|
||||
The public files are in `website/public/`. The site uses HTML, CSS and a small
|
||||
script for copying code and following the assembly-to-C comparison; it has no
|
||||
build step or npm dependencies.
|
||||
script for copying code and following the assembly-to-C comparison. Python
|
||||
packages the downloadable example; there is no frontend bundler or npm dependency.
|
||||
|
||||
## Local preview
|
||||
|
||||
From the repository root:
|
||||
|
||||
```sh
|
||||
python3 scripts/prepare-website.py
|
||||
python3 -m http.server 4173 --bind 127.0.0.1 --directory website/public
|
||||
```
|
||||
|
||||
@@ -17,8 +18,10 @@ Open <http://127.0.0.1:4173/>. Refresh the browser after editing a file.
|
||||
|
||||
## Pages
|
||||
|
||||
- `public/index.html`: product introduction and DX-Ball overview.
|
||||
- `public/index.html`: product introduction and case-study overviews.
|
||||
- `public/showcase/index.html`: the case-study index.
|
||||
- `public/showcase/dx-ball/index.html`: sound-pan investigation and project status.
|
||||
- `public/showcase/notion/index.html`: Notion's Electron clipboard bridge and rich clipboard format.
|
||||
- `public/get-started/index.html`: agent setup, first CLI result and provider guides.
|
||||
- `public/guides/`: a guide hub and native, JavaScript/Electron and browser examples.
|
||||
- `public/examples/`: downloadable Electron source and an interactive Notes browser app.
|
||||
@@ -40,9 +43,18 @@ Electron fixture is for static analysis; Electron is not a prerequisite for
|
||||
following that example. The separate Notes browser app runs in the local preview
|
||||
and constructs a CSV download after fetching its JSON data.
|
||||
|
||||
The Electron guide offers one ZIP containing the six source files under
|
||||
`notes-example/`. `scripts/prepare-website.py` generates this download from
|
||||
an explicit file list, with fixed timestamps and permissions. The ZIP is ignored
|
||||
by Git; website checks and each manual publication regenerate it before checking
|
||||
and uploading the public directory. The verifier checks that its entries match
|
||||
the current source and contain no extra files.
|
||||
|
||||
Agent terminals show example prompts, not transcripts of previous
|
||||
investigations. A short cursor animation starts when the prompt enters view and
|
||||
respects reduced-motion preferences. All prompt text is present without JavaScript.
|
||||
investigations. All cursors blink continuously with the same CSS animation,
|
||||
respecting reduced-motion preferences. Both the prompt and animation work
|
||||
without JavaScript. The homepage and agent setup section share a copyable
|
||||
installation prompt; setup still presents its plan for approval.
|
||||
|
||||
DX-Ball figures and findings refer to the linked 7 October 2026 checkpoint,
|
||||
commit `a55dca27ec0a07018c1b2c95ae2be027f7d8c3c4`. Update those links and figures
|
||||
@@ -63,6 +75,15 @@ The worked guides use semantic HTML flows that stack vertically on smaller
|
||||
screens. The Electron teaching example uses CommonJS, matching its preload
|
||||
code; the scoped lint override admits `require` only in that example directory.
|
||||
|
||||
The Notion case follows the same HTML figure style. Its short excerpts explain
|
||||
the packaged clipboard bridge; separate web-cache probes illustrate the rich
|
||||
clipboard and Markdown formats. Only selected source details and generic
|
||||
example data belong on the site. Machine paths, account identifiers, local
|
||||
configuration, complete vendor bundles and raw captured results stay outside
|
||||
the website.
|
||||
[evidence/notion-clipboard.md](evidence/notion-clipboard.md) records the REA
|
||||
package version, selected findings, source anchors and module-probe scope.
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
`.github/workflows/website-pages.yml` prepares and deploys only `website/public`.
|
||||
@@ -75,6 +96,7 @@ and the single Pages publisher without installing npm dependencies. The same
|
||||
checks run before each manual deployment. You can also run them locally:
|
||||
|
||||
```sh
|
||||
python3 scripts/prepare-website.py
|
||||
python3 scripts/verify-website.py
|
||||
```
|
||||
|
||||
|
||||
@@ -30,6 +30,12 @@ rea analyze-javascript-application \
|
||||
The source was formatted before this result was recorded. Re-run analysis
|
||||
when the example files change.
|
||||
|
||||
The guide's `examples/notes-example.zip` is generated from exactly these six
|
||||
source files, under the `notes-example/` folder. Packaging changes no file
|
||||
contents. Website verification compares every ZIP entry to its source file and
|
||||
rejects extra entries. Existing source digests and static findings remain valid
|
||||
for the unzipped example.
|
||||
|
||||
## Notes browser example
|
||||
|
||||
The three-file browser app is in `website/public/examples/notes-web/`.
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
# Notion clipboard case: sources and scope
|
||||
|
||||
The case uses Notion Desktop 7.6.1's shipped JavaScript, a fresh REA inspection
|
||||
of its tab preload, and separately recorded probes of cached web-editor modules.
|
||||
The public page contains selected result fields, small code excerpts and generic
|
||||
example data. Original packages, complete analysis results and captured local
|
||||
state are not website assets.
|
||||
|
||||
## Fresh REA result
|
||||
|
||||
The published npm REA 4.1.0 package inspected the saved tab preload on
|
||||
7 October 2026, using Node.js 24.18.0. An independent source build of public
|
||||
checkpoint [`810fe53e`](https://github.com/morluto/rea/tree/810fe53e) returned the
|
||||
same API and invoke findings. The page uses the published-package result.
|
||||
|
||||
The successful `analyze_javascript_application` request inspected the extracted
|
||||
directory `.webpack/renderer/tab_browser_view`. Its only file was `preload.js`:
|
||||
24,579 bytes, one parsed JavaScript file and no parse failures or truncated
|
||||
scopes. The result's relevant observations were:
|
||||
|
||||
| Finding | Selected fields | Source range |
|
||||
| -------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- |
|
||||
| Context bridge | `api_key: "__electronApi"`, `api_status: "dynamic"`, `members: []`, `unknown_members: 1` | `preload.js`, line 1, columns 22764–22828 |
|
||||
| Renderer IPC | `operation: "invoke"`, `channel_expression: "e"`, `channel: null`, `resolution: "dynamic"` | `preload.js`, line 1, columns 6486–6522 |
|
||||
|
||||
These are `ast-static-analysis` observations. Lines are one-based and columns
|
||||
zero-based, in the original decoded source. The page's two result panels are a
|
||||
readable projection of these fields, not a complete or replayable Evidence
|
||||
object.
|
||||
|
||||
The focused result locates the exposed bridge and IPC wrapper. Reading the
|
||||
packaged API object supplies the `clipboard.write` member and its literal
|
||||
`notion:clipboard:write` argument. Reading the main-process wrapper and receiver
|
||||
connects that channel to Electron's clipboard call. The four-step figure
|
||||
summarizes this source reading; it is not an automatically paired IPC graph or
|
||||
a captured desktop execution.
|
||||
|
||||
Additional feature traces reused the focused result:
|
||||
|
||||
- API seed `__electronApi`, exact match: one seed, partial coverage, 17 nodes,
|
||||
16 edges and no terminal paths.
|
||||
- Channel seed `notion:clipboard:write`, exact match: no graph match. Its
|
||||
propagation through the wrappers was unresolved in that graph.
|
||||
|
||||
Neither trace establishes a complete clipboard feature graph. The page therefore
|
||||
uses the directly observed API/invoke source ranges and the separately inspected
|
||||
wrapper code, rather than presenting those trace counts as the clipboard route.
|
||||
|
||||
## Packaged bridge excerpts
|
||||
|
||||
Artifact: Notion Desktop 7.6.1 Windows `app.asar`, 8,903,750 bytes.
|
||||
SHA-256: `97c41bc14fc0ea8c91cd34f502660963dfdf294d5eb35165ccac9d30963069d4`.
|
||||
|
||||
| Relative packaged file | Relevant source anchors |
|
||||
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `.webpack/renderer/tab_browser_view/preload.js` | Clipboard API member around character 8274; invoke helpers around 6105/6460; context bridge exposure around 22764 |
|
||||
| `.webpack/main/index.js` | Handler wrapper around character 313027; clipboard receiver around 726249; sender-check adapter around 750262; underlying `isNotionWebContents` around 1281553 |
|
||||
|
||||
Character anchors refer to decoded JavaScript, counted from the start of each
|
||||
file. They are distinct from REA's line/column ranges above.
|
||||
|
||||
Source digests:
|
||||
|
||||
- Tab preload: `c209b1222cd15721bf1988f88c3e57e187d11306edb5eddb13eca441feb6e337`.
|
||||
- Main bundle: `7d06e97721281403e7cf221389de22c6e40d800030a87511231b5390df1452ea`.
|
||||
|
||||
The HTML excerpts expand minified variable names and omit unrelated members.
|
||||
The API-member excerpt illustrates the relevant member; it does not reproduce
|
||||
the entire assembled API object. The sender-check expression expands the
|
||||
adapter to its underlying `isNotionWebContents` call. The meaningful operations
|
||||
are preserved: bind the literal channel, invoke it, register its receiver,
|
||||
check the sender and call `clipboard.write(data)`.
|
||||
|
||||
## Separately cached web-editor code
|
||||
|
||||
The web examples come from a 13 July 2026 cache, build
|
||||
`swv2-23.13.20260713.0259`. This is a separate artifact identity from the desktop
|
||||
ASAR. Corresponding API names help explain the two sides; no same-version live
|
||||
copy/paste session was captured for this case.
|
||||
|
||||
The clipboard examples use:
|
||||
|
||||
- Module `747001`: copy-payload construction, private MIME storage and virtual
|
||||
clipboard handling.
|
||||
- Module `58169`: marker encoding and decoding.
|
||||
- Module `736810`: desktop clipboard routing, including the
|
||||
`electronApi.clipboard.write` call.
|
||||
|
||||
The routing helper's asset,
|
||||
`clipboard-817bda3acae9bf1e__be64437d1c0e.js`, has SHA-256
|
||||
`be64437d1c0eba9c74b48f4307c5936790c59e85aa2ce845e22016a101c2ff7f`.
|
||||
|
||||
Saved Node/JSDOM probes used extracted modules, faithful lifted helpers and
|
||||
stubbed environment APIs. The marker helper is extracted code; the virtual
|
||||
clipboard reader includes a lifted implementation. A matching-ID specimen
|
||||
recovered private formats; a stale local entry retained ordinary text and HTML.
|
||||
This supports the recovered matching policy, rather than proof of OS clipboard
|
||||
hydration or fidelity of a complex block in the running app.
|
||||
|
||||
The figure's “Project notes” and `<copy-id>` are generic illustrations.
|
||||
`<copy-id>` stands for the generated marker ID; it is not a literal runtime UUID.
|
||||
|
||||
## Markdown specimen
|
||||
|
||||
The table uses the saved extracted-module probe of structured Markdown parser
|
||||
`422457`. Input:
|
||||
|
||||
```markdown
|
||||
| A | B |
|
||||
| --- | --- |
|
||||
| 1 | 2 |
|
||||
```
|
||||
|
||||
In the structured sample record, `/samples/table/raw/blocks/0` is a table with
|
||||
`headerRow: true`, two `table_row` children, and cell text `A`/`B` followed by
|
||||
`1`/`2`. The corresponding page and chat filtered outputs preserve those rows
|
||||
and cells. The public tree is an outline of these fields, not an unmodified
|
||||
JSON object or a persisted Notion page.
|
||||
|
||||
The broader historical harness included stubs and several parser variants.
|
||||
This specimen comes from the intact structured-parser result, rather than a
|
||||
legacy table-creation record affected by a synthetic ID collision. Historical
|
||||
module probes are attributed to that harness; REA's new role in this page is
|
||||
the separately verified preload analysis.
|
||||
|
||||
## SQLite follow-up
|
||||
|
||||
The short expandable follow-up is based on the same desktop package. Its
|
||||
`getSqliteMeta` path transfers `MessageChannelMain` ports between the renderer
|
||||
and a SQLite utility process. Later statement batches and results use that
|
||||
port. Relevant files are the tab preload, main bundle and `SqliteServer.js`.
|
||||
The page explains the source-level handoff without claiming a captured SQL
|
||||
session.
|
||||
@@ -5,8 +5,13 @@ function initializeCopyButtons() {
|
||||
if (target === null) return;
|
||||
|
||||
const status = document.getElementById("copy-status");
|
||||
const content = target.textContent.trim();
|
||||
const text =
|
||||
target.closest(".terminal-prompt") === null
|
||||
? content
|
||||
: content.replace(/\s+/g, " ");
|
||||
try {
|
||||
await navigator.clipboard.writeText(target.textContent.trim());
|
||||
await navigator.clipboard.writeText(text);
|
||||
button.textContent = "Copied";
|
||||
if (status !== null) status.textContent = "Code copied to clipboard.";
|
||||
} catch {
|
||||
@@ -55,22 +60,3 @@ function initializeStepComparisons() {
|
||||
}
|
||||
|
||||
initializeStepComparisons();
|
||||
|
||||
function initializeAgentTerminals() {
|
||||
if (!("IntersectionObserver" in window)) return;
|
||||
const observer = new IntersectionObserver(
|
||||
(entries) => {
|
||||
entries.forEach((entry) => {
|
||||
if (!entry.isIntersecting) return;
|
||||
entry.target.classList.add("is-visible");
|
||||
observer.unobserve(entry.target);
|
||||
});
|
||||
},
|
||||
{ threshold: 0.25 },
|
||||
);
|
||||
document.querySelectorAll(".agent-terminal").forEach((terminal) => {
|
||||
observer.observe(terminal);
|
||||
});
|
||||
}
|
||||
|
||||
initializeAgentTerminals();
|
||||
|
||||
@@ -766,9 +766,7 @@ pre code {
|
||||
margin-left: 0.4em;
|
||||
vertical-align: -0.12em;
|
||||
background: #9bbfe5;
|
||||
}
|
||||
.agent-terminal.is-visible .terminal-cursor {
|
||||
animation: terminal-blink 1s step-end 6;
|
||||
animation: terminal-blink 1s step-end infinite;
|
||||
}
|
||||
@keyframes terminal-blink {
|
||||
50% {
|
||||
@@ -840,6 +838,61 @@ pre code {
|
||||
color: var(--ink);
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
.notion-bridge-flow {
|
||||
grid-template-columns: repeat(4, minmax(0, 1fr));
|
||||
}
|
||||
.notion-channel {
|
||||
color: var(--accent);
|
||||
background: #edf2f8;
|
||||
border-radius: 2px;
|
||||
box-decoration-break: clone;
|
||||
-webkit-box-decoration-break: clone;
|
||||
}
|
||||
.notion-clipboard-grid,
|
||||
.notion-table-example {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||||
gap: 1rem;
|
||||
}
|
||||
.notion-clipboard-grid .code-block,
|
||||
.notion-table-example .code-block {
|
||||
min-width: 0;
|
||||
margin: 0;
|
||||
}
|
||||
.notion-clipboard-grid pre,
|
||||
.notion-table-example pre {
|
||||
padding: 1rem;
|
||||
font-size: 0.75rem;
|
||||
white-space: pre-wrap;
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.notion-mini-flow {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.6rem 1.8rem;
|
||||
margin: 1.3rem 0 0;
|
||||
padding: 0;
|
||||
list-style: none;
|
||||
font-size: 0.8rem;
|
||||
}
|
||||
.notion-mini-flow li {
|
||||
position: relative;
|
||||
margin: 0;
|
||||
}
|
||||
.notion-mini-flow li:not(:last-child)::after {
|
||||
content: "→";
|
||||
position: absolute;
|
||||
right: -1.3rem;
|
||||
color: #8191a2;
|
||||
}
|
||||
.case-preview {
|
||||
margin: 0;
|
||||
}
|
||||
.case-preview pre {
|
||||
white-space: pre-wrap;
|
||||
overflow-wrap: anywhere;
|
||||
font-size: 0.8rem;
|
||||
}
|
||||
.workflow-figure figcaption {
|
||||
margin-top: 1rem;
|
||||
color: var(--muted);
|
||||
@@ -940,7 +993,8 @@ pre code {
|
||||
.rea-query-pair {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
.flow-steps {
|
||||
.flow-steps,
|
||||
.notion-bridge-flow {
|
||||
grid-template-columns: 1fr;
|
||||
gap: 2rem;
|
||||
}
|
||||
@@ -1048,6 +1102,20 @@ pre code {
|
||||
.workflow-figure {
|
||||
padding: 1rem;
|
||||
}
|
||||
.notion-clipboard-grid,
|
||||
.notion-table-example {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
.notion-mini-flow {
|
||||
display: grid;
|
||||
gap: 1.5rem;
|
||||
}
|
||||
.notion-mini-flow li:not(:last-child)::after {
|
||||
content: "↓";
|
||||
right: auto;
|
||||
left: 0.4rem;
|
||||
bottom: -1.4rem;
|
||||
}
|
||||
.step-selector {
|
||||
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||||
}
|
||||
@@ -1061,7 +1129,7 @@ pre code {
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.agent-terminal.is-visible .terminal-cursor {
|
||||
.terminal-cursor {
|
||||
animation: none;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/dx-ball/">DX-Ball</a
|
||||
<a href="../showcase/">Showcases</a
|
||||
><a class="nav-start" href="./" aria-current="page">Get started</a
|
||||
><a href="../guides/">Guides</a
|
||||
><a href="https://github.com/morluto/rea">GitHub</a>
|
||||
@@ -59,20 +59,48 @@
|
||||
include Claude Code, Codex, Cursor, Gemini CLI, Windsurf and other
|
||||
supported MCP clients.
|
||||
</p>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Terminal</span
|
||||
><button
|
||||
<div class="agent-terminal">
|
||||
<div class="terminal-header">
|
||||
<span class="terminal-title"
|
||||
><span class="terminal-dots" aria-hidden="true"
|
||||
><i></i><i></i><i></i></span
|
||||
>Your coding agent</span
|
||||
>
|
||||
<button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="agent-setup"
|
||||
aria-label="Copy agent setup command"
|
||||
data-copy="agent-install-prompt"
|
||||
aria-label="Copy REA installation prompt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="agent-setup">npx rea-agents@latest setup</code></pre>
|
||||
<p class="terminal-prompt">
|
||||
<span class="prompt-symbol" aria-hidden="true">›</span
|
||||
><span id="agent-install-prompt"
|
||||
>Install REA and connect it to this coding agent using npx
|
||||
rea-agents@latest setup. Show me the setup plan for approval,
|
||||
then verify the installation.</span
|
||||
><span class="terminal-cursor" aria-hidden="true"></span>
|
||||
</p>
|
||||
</div>
|
||||
<details class="evidence-details">
|
||||
<summary>Or run setup yourself</summary>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Terminal</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="agent-setup"
|
||||
aria-label="Copy agent setup command"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="agent-setup">npx rea-agents@latest setup</code></pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
Choose your client and review the setup plan. REA adds its MCP
|
||||
connection and the matching investigation skill, keeping a backup
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/dx-ball/">DX-Ball</a
|
||||
<a href="../../showcase/">Showcases</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a
|
||||
><a href="https://github.com/morluto/rea">GitHub</a>
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/dx-ball/">DX-Ball</a
|
||||
<a href="../showcase/">Showcases</a
|
||||
><a class="nav-start" href="../get-started/">Get started</a
|
||||
><a href="./" aria-current="page">Guides</a
|
||||
><a href="https://github.com/morluto/rea">GitHub</a>
|
||||
@@ -71,6 +71,10 @@
|
||||
<span>IPC</span> <b aria-hidden="true">→</b> <span>CSV file</span>
|
||||
</div>
|
||||
<a class="text-link" href="javascript/">Application workflows</a>
|
||||
<p>
|
||||
For a larger packaged app, follow
|
||||
<a href="../showcase/notion/">Notion's clipboard bridge</a>.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
<section class="guide-entry">
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/dx-ball/">DX-Ball</a
|
||||
<a href="../../showcase/">Showcases</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a
|
||||
><a href="https://github.com/morluto/rea">GitHub</a>
|
||||
@@ -203,42 +203,53 @@
|
||||
<section class="article-section" id="try">
|
||||
<h2>Analyze the example yourself</h2>
|
||||
<p>
|
||||
Save these six files together in a folder named
|
||||
<code>notes-example</code>. Static analysis needs Node.js and npm;
|
||||
you can inspect the code without installing or launching Electron.
|
||||
Download the example and unzip it. The archive contains the
|
||||
complete <code>notes-example</code> folder. Analyze it with
|
||||
Node.js and npm; Electron is not needed for this example.
|
||||
</p>
|
||||
<ul class="example-files">
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/package.json" download
|
||||
>package.json</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/main.js" download
|
||||
>main.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/preload.js" download
|
||||
>preload.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/renderer.js" download
|
||||
>renderer.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/csv.js" download
|
||||
>csv.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/index.html" download
|
||||
>index.html</a
|
||||
>
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
<a
|
||||
class="button"
|
||||
href="../../examples/notes-example.zip"
|
||||
download="notes-example.zip"
|
||||
>Download example ZIP</a
|
||||
>
|
||||
</p>
|
||||
<details class="evidence-details">
|
||||
<summary>Browse the six source files</summary>
|
||||
<ul class="example-files">
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/package.json" download
|
||||
>package.json</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/main.js" download
|
||||
>main.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/preload.js" download
|
||||
>preload.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/renderer.js" download
|
||||
>renderer.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/csv.js" download
|
||||
>csv.js</a
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../../examples/notes-electron/index.html" download
|
||||
>index.html</a
|
||||
>
|
||||
</li>
|
||||
</ul>
|
||||
</details>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Static application analysis</span
|
||||
@@ -255,7 +266,7 @@
|
||||
/absolute/path/to/notes-example --json</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
Replace the path with the folder you saved. Look for
|
||||
Replace the path with the folder you unzipped. Look for
|
||||
<code>normalized_result.summary.ipc</code> and the source
|
||||
locations in <code>normalized_result.graph</code>. The example has
|
||||
one channel and one paired invocation.
|
||||
@@ -281,6 +292,12 @@
|
||||
runtime observations give you another way to investigate them.
|
||||
</p>
|
||||
<ul class="reading-list">
|
||||
<li>
|
||||
<a href="../../showcase/notion/"
|
||||
>Follow Notion's clipboard bridge</a
|
||||
>
|
||||
<span>Apply the same approach to a packaged Electron app.</span>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../browser/">Observe a browser export</a
|
||||
><span
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/dx-ball/">DX-Ball</a
|
||||
<a href="../../showcase/">Showcases</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a
|
||||
><a href="https://github.com/morluto/rea">GitHub</a>
|
||||
|
||||
+99
-61
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="showcase/dx-ball/">DX-Ball</a>
|
||||
<a href="showcase/">Showcases</a>
|
||||
<a class="nav-start" href="get-started/">Get started</a>
|
||||
<a href="guides/">Guides</a>
|
||||
<a href="https://github.com/morluto/rea">GitHub</a>
|
||||
@@ -34,17 +34,40 @@
|
||||
<p class="eyebrow">Software analysis · CLI & MCP</p>
|
||||
<h1>Find out how<br />software works.</h1>
|
||||
<p class="lede">
|
||||
REA gives your coding agent tools to inspect apps, binaries and
|
||||
runtime behavior. Ask a question, follow the code, and use what you
|
||||
learn in your own project.
|
||||
Use REA with your coding agent to inspect binaries, trace application
|
||||
code and observe runtime behavior.
|
||||
</p>
|
||||
<div class="actions">
|
||||
<a class="button" href="get-started/">Get started</a>
|
||||
<a class="text-link" href="showcase/dx-ball/"
|
||||
>Read the DX-Ball case study</a
|
||||
>
|
||||
<a class="text-link" href="showcase/">Explore the case studies</a>
|
||||
</div>
|
||||
<div class="hero-command">
|
||||
<div class="agent-terminal">
|
||||
<div class="terminal-header">
|
||||
<span class="terminal-title"
|
||||
><span class="terminal-dots" aria-hidden="true"
|
||||
><i></i><i></i><i></i></span
|
||||
>Your coding agent</span
|
||||
>
|
||||
<button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="home-install-prompt"
|
||||
aria-label="Copy REA installation prompt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<p class="terminal-prompt">
|
||||
<span class="prompt-symbol" aria-hidden="true">›</span
|
||||
><span id="home-install-prompt"
|
||||
>Install REA and connect it to this coding agent using npx
|
||||
rea-agents@latest setup. Show me the setup plan for approval,
|
||||
then verify the installation.</span
|
||||
><span class="terminal-cursor" aria-hidden="true"></span>
|
||||
</p>
|
||||
</div>
|
||||
<p class="caption">Or run this command in your terminal:</p>
|
||||
<div class="code-block code-inline">
|
||||
<code id="setup-command">npx rea-agents@latest setup</code>
|
||||
<button
|
||||
@@ -56,9 +79,43 @@
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<p class="caption">
|
||||
Connects REA to your agent and installs its investigation workflow.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<div class="container">
|
||||
<div class="section-heading">
|
||||
<h2>What REA can analyze</h2>
|
||||
<p>
|
||||
Choose a guide for your binary, JavaScript app or browser session.
|
||||
</p>
|
||||
</div>
|
||||
<div class="workflows">
|
||||
<div>
|
||||
<h3>Native binaries</h3>
|
||||
<p>
|
||||
Inspect functions, strings, references and call relationships in
|
||||
executables and libraries.
|
||||
</p>
|
||||
<a href="guides/native/">Native analysis guide</a>
|
||||
</div>
|
||||
<div>
|
||||
<h3>JavaScript & Electron</h3>
|
||||
<p>
|
||||
Map modules, routes, IPC and native dependencies from an
|
||||
application folder or ASAR archive.
|
||||
</p>
|
||||
<a href="guides/javascript/">Application workflows</a>
|
||||
</div>
|
||||
<div>
|
||||
<h3>Browser & runtime activity</h3>
|
||||
<p>
|
||||
Capture selected browser or process activity, then compare the
|
||||
results across runs.
|
||||
</p>
|
||||
<a href="guides/browser/">Browser observation guide</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -93,7 +150,7 @@
|
||||
<section class="section">
|
||||
<div class="container feature-case">
|
||||
<div>
|
||||
<p class="eyebrow">Case study</p>
|
||||
<p class="eyebrow">Case study · Native</p>
|
||||
<h2>Rebuilding DX-Ball</h2>
|
||||
<p>
|
||||
DX-Ball is a 1996 Windows game. The project is reconstructing it
|
||||
@@ -134,64 +191,44 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<div class="container">
|
||||
<div class="section-heading">
|
||||
<h2>Bring a target. Ask a question.</h2>
|
||||
<p>
|
||||
Start with a local app or file, then narrow the investigation to
|
||||
the feature or behavior you want to understand.
|
||||
</p>
|
||||
</div>
|
||||
<div class="workflows">
|
||||
<div>
|
||||
<h3>Native applications</h3>
|
||||
<p>
|
||||
Inspect functions, strings, references and call relationships in
|
||||
executables and libraries.
|
||||
</p>
|
||||
<a href="guides/native/">Native analysis guide</a>
|
||||
</div>
|
||||
<div>
|
||||
<h3>JavaScript & Electron</h3>
|
||||
<p>
|
||||
Map modules, routes, IPC and native dependencies from an
|
||||
application folder or ASAR archive.
|
||||
</p>
|
||||
<a href="guides/javascript/">Application workflows</a>
|
||||
</div>
|
||||
<div>
|
||||
<h3>Runtime behavior</h3>
|
||||
<p>
|
||||
Capture selected browser or process activity, then compare the
|
||||
results across runs.
|
||||
</p>
|
||||
<a href="guides/browser/">Browser observation guide</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<div class="container feature-case">
|
||||
<div>
|
||||
<h2>Keep the investigation in your workflow.</h2>
|
||||
<p class="eyebrow">Case study · Electron</p>
|
||||
<h2>Notion's Electron clipboard</h2>
|
||||
<p>
|
||||
Use REA from your terminal or through your agent's MCP connection.
|
||||
Analysis runs locally, and results include the source locations,
|
||||
evidence and open questions you need to continue.
|
||||
A copy operation crosses from the page to Electron's main process.
|
||||
Inspect Notion's packaged JavaScript with REA, then follow one
|
||||
channel through the wrappers to the system clipboard.
|
||||
</p>
|
||||
</div>
|
||||
<div>
|
||||
<h3>Use your analysis tools</h3>
|
||||
<p>
|
||||
Connect a local analysis provider for native binaries. Static
|
||||
JavaScript analysis runs with Node.js and npm.
|
||||
Short code excerpts show each handoff. A second figure explains
|
||||
how an HTML marker connects ordinary clipboard text to Notion's
|
||||
structured block data.
|
||||
</p>
|
||||
<a class="text-link" href="get-started/#native"
|
||||
>Choose a native provider</a
|
||||
<a class="text-link" href="showcase/notion/"
|
||||
>Follow the clipboard bridge</a
|
||||
>
|
||||
</div>
|
||||
<figure class="workflow-figure case-preview">
|
||||
<p class="figure-title">Clipboard IPC channel</p>
|
||||
<div class="code-block">
|
||||
<div class="code-header"><span>Preload · send</span></div>
|
||||
<pre><code>invokerInMain(
|
||||
<span class="notion-channel">"notion:clipboard:write"</span>
|
||||
)</code></pre>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-header"><span>Main process · receive</span></div>
|
||||
<pre><code>addListener(
|
||||
<span class="notion-channel">"notion:clipboard:write"</span>,
|
||||
handler
|
||||
)</code></pre>
|
||||
</div>
|
||||
<figcaption>
|
||||
Matching names give the investigation a path to follow.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -200,7 +237,8 @@
|
||||
<div>
|
||||
<h2>What would you like to understand?</h2>
|
||||
<p>
|
||||
Connect your agent, or get your first result from the terminal.
|
||||
Connect REA to your coding agent, or run your first analysis from
|
||||
the terminal.
|
||||
</p>
|
||||
</div>
|
||||
<a class="button" href="get-started/">Get started</a>
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="./" aria-current="page">DX-Ball</a>
|
||||
<a href="../">Showcases</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="https://github.com/morluto/rea">GitHub</a>
|
||||
@@ -31,7 +31,9 @@
|
||||
</header>
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../../">Home</a> / DX-Ball</p>
|
||||
<p class="breadcrumb">
|
||||
<a href="../../">Home</a> / <a href="../">Showcases</a> / DX-Ball
|
||||
</p>
|
||||
<p class="eyebrow">Case study · DX-Ball 1.07</p>
|
||||
<h1>Rebuilding DX-Ball<br />from its executable.</h1>
|
||||
<p class="lede">
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Case studies — REA</title>
|
||||
<meta
|
||||
name="description"
|
||||
content="Follow REA investigations through code and figures: recover a native calculation in DX-Ball and trace Notion's Electron clipboard bridge."
|
||||
/>
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
<script src="../assets/main.js" defer></script>
|
||||
</head>
|
||||
<body>
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
><span class="brand-name">REA</span
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="./" aria-current="page">Showcases</a>
|
||||
<a class="nav-start" href="../get-started/">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="https://github.com/morluto/rea">GitHub</a>
|
||||
</nav>
|
||||
</div>
|
||||
</header>
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / Showcases</p>
|
||||
<h1>Follow the<br />investigation.</h1>
|
||||
<p class="lede">
|
||||
Start with a question about a real application. See what REA finds,
|
||||
follow the code, and understand how the pieces fit together.
|
||||
</p>
|
||||
</div>
|
||||
<div class="guide-index">
|
||||
<section class="guide-entry">
|
||||
<p class="eyebrow">Native · Reconstruction</p>
|
||||
<div>
|
||||
<h2>Rebuilding DX-Ball</h2>
|
||||
<p>
|
||||
Recover a sound-pan calculation from a 1996 Windows game. REA's
|
||||
instructions, caller references and numeric constants lead to a
|
||||
small C function, checked against the original behavior and all 63
|
||||
compiled bytes.
|
||||
</p>
|
||||
<div class="guide-route">
|
||||
<span>Executable</span> <b aria-hidden="true">→</b>
|
||||
<span>REA findings</span> <b aria-hidden="true">→</b>
|
||||
<span>Recovered C</span> <b aria-hidden="true">→</b>
|
||||
<span>Validation</span>
|
||||
</div>
|
||||
<a class="text-link" href="dx-ball/">Read the DX-Ball case study</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="guide-entry">
|
||||
<p class="eyebrow">Electron · Feature tracing</p>
|
||||
<div>
|
||||
<h2>Following a copy through Notion</h2>
|
||||
<p>
|
||||
Trace a page-facing API through Notion's packaged JavaScript.
|
||||
Follow its IPC wrappers to the system clipboard, then see how a
|
||||
small HTML marker keeps rich block data connected to a copy.
|
||||
</p>
|
||||
<div class="guide-route">
|
||||
<span>Packaged app</span> <b aria-hidden="true">→</b>
|
||||
<span>Exposed API</span> <b aria-hidden="true">→</b>
|
||||
<span>IPC wrappers</span> <b aria-hidden="true">→</b>
|
||||
<span>Clipboard</span>
|
||||
</div>
|
||||
<a class="text-link" href="notion/">Read the Notion case study</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<section class="article-section">
|
||||
<h2>Try a smaller example first.</h2>
|
||||
<p>
|
||||
The guides walk through a native calculation, an Electron export and a
|
||||
browser request. Each starts with a prompt and a concrete target.
|
||||
</p>
|
||||
<a class="text-link" href="../guides/">Explore the worked guides</a>
|
||||
</section>
|
||||
</main>
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Community</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,477 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Following Notion's clipboard through Electron — REA</title>
|
||||
<meta
|
||||
name="description"
|
||||
content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format."
|
||||
/>
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
<script src="../../assets/main.js" defer></script>
|
||||
</head>
|
||||
<body>
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
><span class="brand-name">REA</span
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="https://github.com/morluto/rea">GitHub</a>
|
||||
</nav>
|
||||
</div>
|
||||
</header>
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
<a href="../../">Home</a> / <a href="../">Showcases</a> / Notion
|
||||
</p>
|
||||
<p class="eyebrow">Case study · Electron</p>
|
||||
<h1>Following a copy<br />through Notion.</h1>
|
||||
<p class="lede">
|
||||
A familiar action leads through several files. Follow Notion's
|
||||
clipboard API from the page, through Electron, to the system
|
||||
clipboard.
|
||||
</p>
|
||||
<p class="page-meta">Notion Desktop 7.6.1 · JavaScript · REA</p>
|
||||
</div>
|
||||
|
||||
<figure class="workflow-figure">
|
||||
<p class="figure-title">The bridge inside Notion's desktop package</p>
|
||||
<ol class="flow-steps notion-bridge-flow">
|
||||
<li>
|
||||
<span class="flow-label">01 · Page-facing API</span>
|
||||
<span class="flow-node"><code>clipboard.write(data)</code></span>
|
||||
<span class="flow-note"
|
||||
>The preload exposes a callable method.</span
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<span class="flow-label">02 · Preload wrapper</span>
|
||||
<span class="flow-node"><code>ipcRenderer.invoke</code></span>
|
||||
<span class="flow-note"
|
||||
>The wrapper sends the channel and arguments.</span
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<span class="flow-label">03 · Main-process handler</span>
|
||||
<span class="flow-node"><code>ipcMain.handle</code></span>
|
||||
<span class="flow-note"
|
||||
>The receiver checks which page sent it.</span
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<span class="flow-label">04 · System clipboard</span>
|
||||
<span class="flow-node"><code>clipboard.write(data)</code></span>
|
||||
<span class="flow-note"
|
||||
>Electron writes the supplied text and HTML.</span
|
||||
>
|
||||
</li>
|
||||
</ol>
|
||||
<p class="flow-result">
|
||||
One channel joins the two sides:
|
||||
<code class="notion-channel">notion:clipboard:write</code>
|
||||
</p>
|
||||
<figcaption>
|
||||
The packaged code uses the same channel in the preload and main
|
||||
process. Resolving the wrappers reveals the Electron calls behind
|
||||
those names.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<div class="article-layout">
|
||||
<nav class="contents" aria-label="On this page">
|
||||
<p>In this case study</p>
|
||||
<ul>
|
||||
<li><a href="#clipboard">Follow the clipboard bridge</a></li>
|
||||
<li><a href="#rich-clipboard">Keeping a block's structure</a></li>
|
||||
<li><a href="#markdown">Markdown becomes blocks</a></li>
|
||||
<li><a href="#continue">Try another question</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
<article class="article" aria-label="Notion Electron case study">
|
||||
<section class="article-section" id="clipboard">
|
||||
<h2>Where does the copy operation go?</h2>
|
||||
<p>
|
||||
The page sees a method called <code>clipboard.write</code>. Its
|
||||
implementation in the preload is a wrapper. The useful question is
|
||||
what that wrapper sends, and which code receives it.
|
||||
</p>
|
||||
<div class="agent-terminal">
|
||||
<div class="terminal-header">
|
||||
<span class="terminal-title"
|
||||
><span class="terminal-dots" aria-hidden="true"
|
||||
><i></i><i></i><i></i></span
|
||||
>Your coding agent</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="notion-prompt"
|
||||
aria-label="Copy Notion analysis prompt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<p class="terminal-prompt">
|
||||
<span class="prompt-symbol" aria-hidden="true">›</span
|
||||
><span id="notion-prompt"
|
||||
>Use REA to trace how Notion copies text and HTML to the
|
||||
system clipboard. Show the code at each step.</span
|
||||
><span class="terminal-cursor" aria-hidden="true"></span>
|
||||
</p>
|
||||
</div>
|
||||
<p class="caption">
|
||||
An example prompt with Notion's local application package
|
||||
available to your coding agent.
|
||||
</p>
|
||||
|
||||
<h3 class="small-heading">REA finds where to start reading</h3>
|
||||
<p>
|
||||
Analyzing the tab preload with REA locates the API exposed to the
|
||||
page and the call that sends an IPC request. Both findings come
|
||||
with source ranges in the minified bundle:
|
||||
</p>
|
||||
<figure class="workflow-figure">
|
||||
<p class="figure-title">REA findings → two places to open</p>
|
||||
<div class="rea-query-pair">
|
||||
<div class="code-block">
|
||||
<div class="code-header"><span>Exposed page API</span></div>
|
||||
<pre><code>api_key: "__electronApi"
|
||||
api_status: "dynamic"
|
||||
source: preload.js:1:22764–22828</code></pre>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-header"><span>Renderer IPC call</span></div>
|
||||
<pre><code>operation: "invoke"
|
||||
channel_expression: "e"
|
||||
source: preload.js:1:6486–6522</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
<figcaption>
|
||||
Selected fields from a fresh
|
||||
<code>analyze_javascript_application</code> result on Notion's
|
||||
tab preload, recorded with REA 4.1.0. Positions use the original
|
||||
bundle's line and zero-based column.
|
||||
</figcaption>
|
||||
</figure>
|
||||
<p>
|
||||
The agent opens those locations, finds the clipboard member in the
|
||||
assembled API, and reads <code>invokerInMain</code>. Its call site
|
||||
supplies
|
||||
<code class="notion-channel">notion:clipboard:write</code>. That
|
||||
name gives the agent something precise to look for in the main
|
||||
bundle. The four excerpts below show the route it connects.
|
||||
</p>
|
||||
|
||||
<h3 class="small-heading">Four short pieces of code</h3>
|
||||
<p class="caption">
|
||||
Simplified from the packaged JavaScript, with readable variable
|
||||
names. Unrelated members are omitted.
|
||||
</p>
|
||||
<ol class="rea-queries">
|
||||
<li>
|
||||
<h4>Start at the API exposed to the page</h4>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>tab_browser_view/preload.js · API member</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="notion-preload-source"
|
||||
aria-label="Copy Notion preload excerpt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="notion-preload-source">const clipboardApi = {
|
||||
write: invokerInMain(<span class="notion-channel">"notion:clipboard:write"</span>)
|
||||
};
|
||||
|
||||
// Included in the API exposed through contextBridge:
|
||||
// window.__electronApi.clipboard</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
This member supplies the channel name. The implementation of
|
||||
<code>invokerInMain</code> tells us how the request leaves the
|
||||
page's process.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<h4>Resolve the preload's wrapper</h4>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>tab_browser_view/preload.js · IPC helper</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="notion-invoke-source"
|
||||
aria-label="Copy Notion invoke wrapper excerpt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="notion-invoke-source">function invokerInMain(channel) {
|
||||
return (...args) => invokeInMainAndReturnResult(channel, ...args);
|
||||
}
|
||||
|
||||
function invokeInMainAndReturnResult(channel, ...args) {
|
||||
return ipcRenderer.invoke(channel, ...args);
|
||||
}</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
The returned function forwards the arguments through
|
||||
Electron's request-and-response IPC. We can now look for
|
||||
<code class="notion-channel">notion:clipboard:write</code>
|
||||
on the main-process side.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<h4>Check how the receiver is registered</h4>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>main/index.js · handler helper</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="notion-handler-source"
|
||||
aria-label="Copy Notion handler wrapper excerpt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="notion-handler-source">const handleRequestFromRenderer = {
|
||||
addListener(channel, handler) {
|
||||
ipcMain.handle(channel, handler);
|
||||
}
|
||||
};</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
The main process uses another wrapper. Its
|
||||
<code>addListener</code> method registers an
|
||||
<code>ipcMain.handle</code> receiver for that channel.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<h4>Find the write and its sender check</h4>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>main/index.js · clipboard receiver</span
|
||||
><button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="notion-write-source"
|
||||
aria-label="Copy Notion clipboard receiver excerpt"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="notion-write-source">handleRequestFromRenderer.addListener(
|
||||
<span class="notion-channel">"notion:clipboard:write"</span>,
|
||||
(event, data) =>
|
||||
isNotionWebContents(event.sender)
|
||||
? clipboard.write(data)
|
||||
: undefined
|
||||
);</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
This is the destination. After checking the sender, the
|
||||
handler passes the supplied data to Electron's clipboard API.
|
||||
The channel and the two resolved wrappers connect the exposed
|
||||
method to this call.
|
||||
</p>
|
||||
</li>
|
||||
</ol>
|
||||
</section>
|
||||
|
||||
<section class="article-section" id="rich-clipboard">
|
||||
<h2>How does a copied block keep its structure?</h2>
|
||||
<p>
|
||||
The cached web editor adds a small detail to programmatic copies.
|
||||
It sends text and HTML through
|
||||
<code>electronApi.clipboard.write</code>, while keeping Notion's
|
||||
private block data in a local virtual clipboard. An ID in the HTML
|
||||
connects the two.
|
||||
</p>
|
||||
<figure class="workflow-figure">
|
||||
<p class="figure-title">One copy, two representations</p>
|
||||
<div class="notion-clipboard-grid">
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Sent to the system clipboard</span>
|
||||
</div>
|
||||
<pre><code>text: "Project notes"
|
||||
html: "<p>Project notes</p>"
|
||||
+ "<!-- notionvc: <span class="notion-channel"><copy-id></span> -->"</code></pre>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Kept in the local virtual clipboard</span>
|
||||
</div>
|
||||
<pre><code>id: <span class="notion-channel"><copy-id></span>
|
||||
mimeTypes:
|
||||
text/_notion-blocks-v3-production
|
||||
→ structured block data</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
<ol
|
||||
class="notion-mini-flow"
|
||||
aria-label="Restoring rich clipboard data on paste"
|
||||
>
|
||||
<li>Read the HTML ID</li>
|
||||
<li>Find the same local ID</li>
|
||||
<li>Restore private formats</li>
|
||||
</ol>
|
||||
<figcaption>
|
||||
Illustrative text and ID. The saved module probe recovered the
|
||||
private formats when IDs matched; a stale entry left only the
|
||||
ordinary text and HTML.
|
||||
</figcaption>
|
||||
</figure>
|
||||
<p>
|
||||
On paste, the reader looks for the marker and checks it against
|
||||
the saved copy. A matching ID reconnects the text to its richer
|
||||
representation. This explains why the HTML carries more than
|
||||
visible content.
|
||||
</p>
|
||||
<p class="caption">
|
||||
Web assets cached on July 13, 2026. The desktop-package bridge
|
||||
above and this web-side format are separate pieces of the
|
||||
investigation.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section class="article-section" id="markdown">
|
||||
<h2>From Markdown to structured blocks</h2>
|
||||
<p>
|
||||
The same investigation also recovered Notion's Markdown
|
||||
processing. A small table makes the internal format easy to see:
|
||||
its rows and cells become data that the block renderer can use.
|
||||
</p>
|
||||
<figure class="workflow-figure">
|
||||
<p class="figure-title">
|
||||
A table through Notion's Markdown parser
|
||||
</p>
|
||||
<div class="notion-table-example">
|
||||
<div class="code-block">
|
||||
<div class="code-header"><span>Markdown input</span></div>
|
||||
<pre><code>| A | B |
|
||||
| - | - |
|
||||
| 1 | 2 |</code></pre>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Structured parser output · excerpt</span>
|
||||
</div>
|
||||
<pre><code>table · headerRow: true
|
||||
table_row
|
||||
cells: ["A"], ["B"]
|
||||
table_row
|
||||
cells: ["1"], ["2"]</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
<figcaption>
|
||||
A saved extracted-module probe of web parser
|
||||
<code>422457</code>. Both page and chat filters preserve this
|
||||
table. The tree shows the recorded rows and cell text.
|
||||
</figcaption>
|
||||
</figure>
|
||||
<p>
|
||||
Finding that transformation required separating the ordinary
|
||||
paste/import path from the structured Markdown and AI/chat
|
||||
parsers. Each has its own entry point and intermediate format.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section class="article-section" id="continue">
|
||||
<h2>Try another question</h2>
|
||||
<p>
|
||||
Start with one feature and follow the code that crosses a process
|
||||
boundary. A named API, a literal channel and its receiver are
|
||||
useful places to begin.
|
||||
</p>
|
||||
<details class="evidence-details">
|
||||
<summary>Another path: the offline SQLite connection</summary>
|
||||
<p>
|
||||
Notion's renderer requests <code>getSqliteMeta</code> through
|
||||
IPC. The main process creates a message channel and gives one
|
||||
port to the renderer and the other to a SQLite utility process.
|
||||
Subsequent statement batches and results travel over that port.
|
||||
</p>
|
||||
<p>
|
||||
Following this handoff explains where the database work runs,
|
||||
and why tracing only the initial IPC request misses the later
|
||||
conversation.
|
||||
</p>
|
||||
</details>
|
||||
<details class="evidence-details">
|
||||
<summary>Sources and how to read the excerpts</summary>
|
||||
<p>
|
||||
The clipboard bridge comes from Notion Desktop 7.6.1's
|
||||
<code>app.asar</code>: the tab preload and
|
||||
<code>main/index.js</code>. The excerpts expand minified
|
||||
variable names and omit unrelated code; the sender-check helper
|
||||
is shown with its underlying
|
||||
<code>isNotionWebContents</code> call.
|
||||
</p>
|
||||
<p>
|
||||
The virtual clipboard and Markdown examples come from web assets
|
||||
cached on July 13, 2026, including modules <code>747001</code>,
|
||||
<code>58169</code>, <code>736810</code> and <code>422457</code>.
|
||||
Those assets have their own version. Saved probes executed
|
||||
extracted modules and small harnesses; their outputs describe
|
||||
those probes rather than a captured desktop UI session.
|
||||
</p>
|
||||
<p>
|
||||
The REA result shown here is a focused analysis of the saved tab
|
||||
preload, recorded with the published REA 4.1.0 package. It
|
||||
locates the API and invoke operation. The clipboard member and
|
||||
matching receiver are connected by reading their wrapper
|
||||
implementations in the package.
|
||||
</p>
|
||||
</details>
|
||||
<ul class="reading-list">
|
||||
<li>
|
||||
<a href="../../guides/javascript/"
|
||||
>JavaScript application guide</a
|
||||
><span
|
||||
>Follow a small Electron application's export feature.</span
|
||||
>
|
||||
</li>
|
||||
<li>
|
||||
<a href="../dx-ball/">DX-Ball reconstruction</a
|
||||
><span
|
||||
>Follow native instructions to a checked C function.</span
|
||||
>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="actions">
|
||||
<a class="button" href="../../get-started/"
|
||||
>Start with your own target</a
|
||||
>
|
||||
</div>
|
||||
</section>
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Community</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user