rea-agents 6.4.0 → 6.7.0

package/bridge/pwntools/recorded_crash_impl.py

@@ -11,6 +11,12 @@ import sys
 
 PROFILE = "pwntools@4.15.0;pyelftools@0.33;unicorn@2.1.2"
 
+# Linux ET_CORE machine identifiers whose PRSTATUS layout is interpreted with
+# unchanged pwntools 4.15.0 ctypes. Both share pr_cursig@12, pr_pid@32 and
+# pr_reg@112; only the register window differs: amd64 is 27 x 8 bytes for a
+# 336-byte descriptor, AArch64 is 34 x 8 bytes for a 392-byte descriptor.
+CORE_MACHINES = (62, 183)
+
 
 class CoreFailure(Exception):
     def __init__(self, reason, message):
@@ -51,12 +57,27 @@ def inspect_core(path, cache):
     # Other declared OSABIs must never select Linux note ctypes.
     if content[7] not in (0, 3) or content[8] != 0:
         raise CoreFailure("unsupported-target", "Initial recorded-core profile requires System V or GNU/Linux OSABI with ABI version zero; selected OSABI=" + str(content[7]) + ", ABI version=" + str(content[8]) + ".")
-    if int.from_bytes(content[16:18], "little") != 4 or int.from_bytes(content[18:20], "little") != 62:
-        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires x86-64 ET_CORE.")
+    machine = int.from_bytes(content[18:20], "little")
+    if int.from_bytes(content[16:18], "little") != 4 or machine not in CORE_MACHINES:
+        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires ET_CORE for x86-64 or AArch64; selected ET_TYPE=" + str(int.from_bytes(content[16:18], "little")) + ", e_machine=" + str(machine) + ".")
     from elftools.common.exceptions import ELFError
     from elftools.common.utils import struct_parse
     from elftools.elf.elffile import ELFFile
-    from pwnlib.elf.datatypes import elf_prstatus_amd64, elf_siginfo_64, user_regs_struct_amd64
+    from pwnlib.elf.datatypes import (
+        elf_prstatus_aarch64,
+        elf_prstatus_amd64,
+        elf_siginfo_64,
+        user_regs_struct_aarch64,
+        user_regs_struct_amd64,
+    )
+    if machine == 62:
+        profile_label = "x86-64"
+        architecture = "x86_64-little-endian"
+        prstatus_type, registers_type = elf_prstatus_amd64, user_regs_struct_amd64
+    else:
+        profile_label = "AArch64"
+        architecture = "aarch64-little-endian"
+        prstatus_type, registers_type = elf_prstatus_aarch64, user_regs_struct_aarch64
     try:
         image = ELFFile(io.BytesIO(content))
         header = image.header
@@ -107,17 +128,17 @@ def inspect_core(path, cache):
                 if owner != b"CORE\0":
                     continue
                 if note.n_type == "NT_PRSTATUS":
-                    if len(descriptor) < ctypes.sizeof(elf_prstatus_amd64):
-                        raise CoreFailure("format", "Linux amd64 NT_PRSTATUS descriptor is truncated.")
-                    status = elf_prstatus_amd64.from_buffer_copy(descriptor)
+                    if len(descriptor) < ctypes.sizeof(prstatus_type):
+                        raise CoreFailure("format", "Linux " + profile_label + " NT_PRSTATUS descriptor is truncated.")
+                    status = prstatus_type.from_buffer_copy(descriptor)
                     registers = []
-                    for name, kind in user_regs_struct_amd64._fields_:
-                        relative = elf_prstatus_amd64.pr_reg.offset + getattr(user_regs_struct_amd64, name).offset
+                    for name, kind in registers_type._fields_:
+                        relative = prstatus_type.pr_reg.offset + getattr(registers_type, name).offset
                         registers.append({"name": name, "value": hex(getattr(status.pr_reg, name)), "location": location(descriptor_start + relative, ctypes.sizeof(kind), end)})
                     threads.append({"note_index": note_index, "historical_pid": ctypes.c_int32(status.pr_pid).value, "recorded_current_signal": status.pr_cursig, "registers": registers})
                 elif note.n_type == "NT_SIGINFO":
                     if len(descriptor) < ctypes.sizeof(elf_siginfo_64):
-                        raise CoreFailure("format", "Linux amd64 NT_SIGINFO descriptor is truncated.")
+                        raise CoreFailure("format", "Linux " + profile_label + " NT_SIGINFO descriptor is truncated.")
                     signal = elf_siginfo_64.from_buffer_copy(descriptor)
                     number = ctypes.c_int32(signal.si_signo).value
                     code = ctypes.c_int32(signal.si_code).value
@@ -125,7 +146,7 @@ def inspect_core(path, cache):
                     signals.append({"note_index": note_index, "number": number, "code": code, "errno": ctypes.c_int32(signal.si_errno).value,
                                     "fault_address": hex(signal.sigfault_addr) if known else None,
                                     "fault_address_meaning": "recorded-sigsegv-address" if known else "unknown", "thread_association": "unknown"})
-        return {"format": "elf-core", "architecture": "x86_64-little-endian", "target_execution": "not-performed", "live_process_identity": "unknown",
+        return {"format": "elf-core", "architecture": architecture, "target_execution": "not-performed", "live_process_identity": "unknown",
                 "segments": segments, "notes": notes, "note_padding": padding, "threads": threads, "signals": signals,
                 "note_interpretation_completeness": "unknown",
                 "limitations": ["The initial Linux note profile accepts System V/unspecified or GNU/Linux OSABI with ABI version zero; an unspecified OSABI alone does not prove operating-system origin.",

package/dist/adb/AdbCommand.js

@@ -0,0 +1,148 @@
+import { AnalysisCancelledError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+import { execFileBytes, ExecFileOutputCancelledError, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { packageChangeFailureReason } from "./AdbShellOutput.js";
+const STDERR_EXCERPT_BYTES = 512;
+/** Project parsed command-owner facts without reinterpreting the rejection. */
+export const adbCommandCapturedOutput = (failure) => ({
+    stdout: failure.stdout,
+    stderr: failure.stderr,
+    ...(failure.stdoutBytes === undefined
+        ? {}
+        : { stdout_bytes: failure.stdoutBytes }),
+    ...(failure.stderrBytes === undefined
+        ? {}
+        : { stderr_bytes: failure.stderrBytes }),
+    exit_code: typeof failure.code === "number" ? failure.code : null,
+    signal: failure.signal,
+    truncated: failure.outputTruncated,
+});
+/** Parsed command failure owned by this adapter, separate from its public tag. */
+class AdbProtocolError extends AnalysisProtocolError {
+    commandFailure;
+    constructor(message, commandFailure, cause) {
+        super(message, { cause });
+        this.commandFailure = commandFailure;
+    }
+}
+/** adb joins shell operands into a remote POSIX command; quote at that boundary. */
+const quoteShellOperand = (value) => /^[A-Za-z0-9_./:=@+,-]+$/u.test(value)
+    ? value
+    : "'" + value.replaceAll("'", "'\\''") + "'";
+export const adbArguments = (serial, arguments_) => {
+    const operands = arguments_[0] === "shell"
+        ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]
+        : [...arguments_];
+    return serial === undefined ? operands : ["-s", serial, ...operands];
+};
+/** Run one bounded adb invocation and keep its exact failure shape. */
+export const runAdbCapture = async (operation, targetPath, binary, arguments_, limits, signal) => {
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+    try {
+        return ok(await execFileBytes(binary, arguments_, {
+            timeout: limits.timeoutMs,
+            maxBuffer: limits.maxOutputBytes,
+            stopSignal: "SIGTERM",
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    catch (cause) {
+        const failure = execFileOutputFailure(cause);
+        if (cause instanceof ExecFileOutputCancelledError)
+            return err(new AnalysisCancelledError(operation, {
+                cause: cause.cause,
+                ...(failure === undefined
+                    ? {}
+                    : { capturedOutput: adbCommandCapturedOutput(failure) }),
+            }));
+        if (failure === undefined)
+            return err(new AnalysisProtocolError(`adb failed for ${operation}`, { cause }));
+        if (failure.outputTruncated)
+            return err(new AnalysisResourceConstraintError(operation, "memory", `adb output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`, { max_output_bytes: limits.maxOutputBytes }, { cause }));
+        const excerpt = failure.stderr.trim().slice(0, STDERR_EXCERPT_BYTES);
+        if (/unauthorized/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (/device[^\n]*not found|device offline|still authorizing|more than one device/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (/No such file or directory|Permission denied|read: Permission denied/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (failure.killed)
+            return err(new AnalysisTimeoutError(operation, limits.timeoutMs, { cause }));
+        return err(new AdbProtocolError(excerpt === ""
+            ? `adb exited with code ${String(failure.code)} for ${operation}`
+            : excerpt, failure, cause));
+    }
+};
+/** Decode textual adb protocols after the shared byte capture and error boundary. */
+export const runAdb = async (...arguments_) => {
+    const captured = await runAdbCapture(...arguments_);
+    if (!captured.ok)
+        return captured;
+    return ok({
+        stdout: captured.value.stdout.toString("utf8"),
+        stderr: captured.value.stderr.toString("utf8"),
+        // Byte count of the captured output before UTF-8 decoding, so malformed
+        // sequences replaced by U+FFFD still report their true captured size.
+        stdoutBytes: captured.value.stdout.byteLength,
+    });
+};
+/**
+ * adb exits nonzero when the device refuses a package change, printing the
+ * `Failure [...]` verdict to stderr (install) or stdout (uninstall). Read the
+ * refusal from that failed run so it is not reported as unreadable output.
+ */
+export const packageChangeRefusal = (operation, serial, error) => {
+    if (!(error instanceof AdbProtocolError))
+        return undefined;
+    const failure = error.commandFailure;
+    const reason = packageChangeFailureReason(`${failure.stdout}\n${failure.stderr}`);
+    return reason === null
+        ? undefined
+        : err(new AnalysisUnsupportedTargetError(operation, serial, reason, {
+            cause: error,
+        }));
+};
+/** Only the clean false result of test -e establishes absence. */
+export const probeAdbPathExistence = async (operation, serial, path, binary, limits, signal) => {
+    const probed = await runAdbCapture(operation, path, binary, adbArguments(serial, ["shell", "test", "-e", path]), limits, signal);
+    if (probed.ok) {
+        if (probed.value.stdout.length === 0 && probed.value.stderr.length === 0)
+            return ok(true);
+        return err(new AnalysisProtocolError("The ADB path existence probe returned unexpected output; destination existence is unknown", {
+            diagnostics: { destination_existence: "unknown" },
+            capturedOutput: {
+                stdout: probed.value.stdout.toString("utf8"),
+                stderr: probed.value.stderr.toString("utf8"),
+                stdout_bytes: probed.value.stdout.length,
+                stderr_bytes: probed.value.stderr.length,
+                exit_code: 0,
+                signal: null,
+                truncated: false,
+            },
+        }));
+    }
+    const error = probed.error;
+    if (!(error instanceof AdbProtocolError))
+        return probed;
+    const failure = error.commandFailure;
+    if (failure.code === 1 &&
+        failure.signal === null &&
+        !failure.killed &&
+        !failure.outputTruncated &&
+        failure.collectionFailure !== true &&
+        failure.stdout === "" &&
+        failure.stderr === "")
+        return ok(false);
+    return err(new AnalysisProtocolError(error.message, {
+        cause: error.cause,
+        diagnostics: { destination_existence: "unknown" },
+        capturedOutput: adbCommandCapturedOutput(failure),
+    }));
+};

package/dist/adb/AdbConfiguration.js

@@ -1,6 +1,7 @@
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { isAbsolute } from "node:path";
-import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { execFileOutput, ExecFileOutputCancelledError, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { adbCommandCapturedOutput } from "./AdbCommand.js";
 /** Environment key selecting the caller's adb binary. */
 export const ADB_BINARY_ENV = "REA_ADB_PATH";
 const VERSION_TIMEOUT_MS = 10_000;
@@ -32,7 +33,7 @@ export class AdbConfigurationFailure extends Error {
  * `Version ` the build version (no colon), and `Installed as` the binary path.
  */
 export const parseAdbVersionOutput = (stdout) => {
-    const build = /^Version\s+(\S.*)$/mu.exec(stdout);
+    const build = /^Version\s+(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\s*$/mu.exec(stdout);
     const installed = /^Installed as\s+(.+)$/mu.exec(stdout);
     return {
         version: build === null ? null : build[1].trim(),
@@ -45,18 +46,51 @@ export const parseAdbVersionOutput = (stdout) => {
  */
 export const inspectAdbClient = async (selection, signal) => {
     try {
-        const { stdout } = await execFileOutput(selection.binary, ["version"], {
+        const { stdout, stderr } = await execFileOutput(selection.binary, ["version"], {
             timeout: VERSION_TIMEOUT_MS,
             stopSignal: "SIGTERM",
             maxBuffer: VERSION_MAX_OUTPUT_BYTES,
             ...(signal === undefined ? {} : { signal }),
         });
-        return parseAdbVersionOutput(stdout);
+        const identity = parseAdbVersionOutput(stdout);
+        const hasRecognizedProtocolVersion = /^Android Debug Bridge version\s+\d+\.\d+\.\d+\s*$/mu.test(stdout);
+        if (identity.version === null && !hasRecognizedProtocolVersion)
+            throw new AdbConfigurationFailure("version_unresolved", "The selected adb binary exited successfully but did not report a recognizable protocol or build version", {
+                selected_binary: selection.binary,
+                path_source: selection.pathSource,
+                version_probe: "unrecognized_output",
+                stdout,
+                stderr,
+            });
+        return identity;
     }
     catch (cause) {
+        if (cause instanceof AdbConfigurationFailure)
+            throw cause;
         const failure = execFileOutputFailure(cause);
-        if (signal?.aborted || failure?.code === "ABORT_ERR")
-            throw new AnalysisCancelledError("inspect_adb_client", { cause });
+        if (cause instanceof ExecFileOutputCancelledError)
+            throw new AnalysisCancelledError("inspect_adb_client", {
+                cause: cause.cause,
+                ...(failure === undefined
+                    ? {}
+                    : { capturedOutput: adbCommandCapturedOutput(failure) }),
+            });
+        const diagnostics = {
+            selected_binary: selection.binary,
+            path_source: selection.pathSource,
+            ...(failure === undefined ? {} : { exit_code: failure.code }),
+        };
+        const options = {
+            cause,
+            diagnostics,
+            ...(failure === undefined
+                ? {}
+                : { capturedOutput: adbCommandCapturedOutput(failure) }),
+        };
+        if (failure?.outputTruncated === true)
+            throw new AnalysisResourceConstraintError("inspect_adb_client", "memory", `adb version output exceeded the ${String(VERSION_MAX_OUTPUT_BYTES)}-byte capture budget`, { max_output_bytes: VERSION_MAX_OUTPUT_BYTES }, options);
+        if (failure?.code === "ETIMEDOUT")
+            throw new AnalysisTimeoutError("inspect_adb_client", VERSION_TIMEOUT_MS, options);
         if (failure?.code === "ENOENT")
             throw new AdbConfigurationFailure("binary_missing", `The selected adb binary was not found: ${selection.binary}`, {
                 selected_binary: selection.binary,

package/dist/adb/AdbDeviceOutput.js

@@ -5,25 +5,12 @@
  * retained rather than silently dropped, and derived classifications carry
  * their evidence basis.
  */
-/**
- * Device states adb prints after the serial, longest first so two-word
- * states match before their single-word prefixes. A line whose remainder
- * starts with none of them is not a device line.
- */
-const DEVICE_STATES = [
-    "no permissions",
-    "unauthorized",
-    "authorizing",
-    "offline",
-    "recovery",
-    "sideload",
-    "connecting",
-    "bootloader",
-    "device",
-    "unknown",
-    "host",
-];
+import { adbHostFileName, } from "./AdbHostFileName.js";
+import { ADB_DEVICE_STATES, } from "../domain/adb/adbDeviceAnalysis.js";
 const DEVICE_LINE = /^(\S+)\s+(.*)$/u;
+const normalizeAdbOutputLine = (rawLine) => rawLine.trimEnd();
+const isSuccessfulDaemonStartNotice = (line) => line === "* daemon started successfully" ||
+    line === "* daemon started successfully *";
 const metadataValue = (remainder, key) => {
     const match = new RegExp(`(?:^|\\s)${key}:(\\S+)`, "u").exec(remainder);
     return match === null ? null : match[1];
@@ -33,24 +20,31 @@ const metadataValue = (remainder, key) => {
  * daemon startup notices adb prints on first use are recognized separately;
  * every other unrecognized line is returned for honest reporting.
  */
-export const parseAdbDevicesOutput = (stdout) => {
+export const parseAdbDevicesOutput = (stdout, stderr = "") => {
     const devices = [];
     const unparsedLines = [];
     let daemonStarted = false;
     for (const rawLine of stdout.split(/\r?\n/u)) {
-        const line = rawLine.trimEnd();
+        const line = normalizeAdbOutputLine(rawLine);
+        if (isSuccessfulDaemonStartNotice(line)) {
+            daemonStarted = true;
+            continue;
+        }
         if (line === "" || line.startsWith("List of devices attached"))
             continue;
-        if (line.startsWith("* daemon")) {
-            if (line.includes("started successfully"))
-                daemonStarted = true;
+        if (line.startsWith("* daemon"))
             continue;
-        }
         const match = DEVICE_LINE.exec(line);
-        const state = DEVICE_STATES.find((candidate) => match?.[2]?.startsWith(candidate));
+        const state = ADB_DEVICE_STATES.find((candidate) => {
+            const remainder = match?.[2];
+            if (remainder === undefined || !remainder.startsWith(candidate))
+                return false;
+            const next = remainder[candidate.length];
+            return next === undefined || /\s/u.test(next);
+        });
         if (match === null || state === undefined) {
-            if (line.trim() !== "")
-                unparsedLines.push(line);
+            if (rawLine.trim() !== "")
+                unparsedLines.push(rawLine);
             continue;
         }
         const serial = match[1];
@@ -86,6 +80,15 @@ export const parseAdbDevicesOutput = (stdout) => {
                     : "none",
         });
     }
+    if (!daemonStarted && stderr !== "") {
+        for (const rawLine of stderr.split(/\r?\n/u)) {
+            const line = normalizeAdbOutputLine(rawLine);
+            if (isSuccessfulDaemonStartNotice(line)) {
+                daemonStarted = true;
+                break;
+            }
+        }
+    }
     return { devices, unparsedLines, daemonStarted };
 };
 /**
@@ -139,7 +142,7 @@ export const parsePackageListOutput = (stdout) => {
             continue;
         const match = PACKAGE_LINE.exec(line);
         if (match === null) {
-            unparsedLines.push(line);
+            unparsedLines.push(rawLine);
             continue;
         }
         packages.push({
@@ -149,9 +152,20 @@ export const parsePackageListOutput = (stdout) => {
     }
     return { packages, unparsedLines };
 };
-const fileNameOf = (devicePath) => {
-    const parts = devicePath.split(/\//u);
-    return parts[parts.length - 1] ?? devicePath;
+/** Quote raw device paths for prose without allowing bidi or invisible text. */
+export const displayDevicePath = (devicePath) => {
+    let excerpt = "";
+    let count = 0;
+    for (const character of devicePath) {
+        if (count === 160)
+            break;
+        excerpt += character;
+        count += 1;
+    }
+    const quoted = JSON.stringify(excerpt).replace(/[\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\u2800]/gu, (character) => character === " "
+        ? character
+        : `\\u{${character.codePointAt(0).toString(16).toUpperCase()}}`);
+    return excerpt.length === devicePath.length ? quoted : `${quoted} (excerpt)`;
 };
 /**
  * Parse `pm path PACKAGE` lines. The base/split role is derived from the file
@@ -160,18 +174,26 @@ const fileNameOf = (devicePath) => {
  */
 export const parsePmPathOutput = (stdout) => {
     const paths = [];
+    const rejectedPaths = [];
     const unparsedLines = [];
     for (const rawLine of stdout.split(/\r?\n/u)) {
-        const line = rawLine.trim();
-        if (line === "")
+        if (rawLine === "")
             continue;
-        const match = /^package:(\S+)$/u.exec(line);
+        const match = /^package:(.*)$/u.exec(rawLine);
         if (match === null) {
-            unparsedLines.push(line);
+            unparsedLines.push(rawLine);
             continue;
         }
         const devicePath = match[1];
-        const fileName = fileNameOf(devicePath);
+        const validated = adbHostFileName(devicePath);
+        if (!validated.ok) {
+            rejectedPaths.push({
+                device_path: devicePath,
+                reason: validated.reason,
+            });
+            continue;
+        }
+        const fileName = validated.fileName;
         paths.push({
             device_path: devicePath,
             file_name: fileName,
@@ -182,5 +204,5 @@ export const parsePmPathOutput = (stdout) => {
                     : "unknown",
         });
     }
-    return { paths, unparsedLines };
+    return { paths, rejectedPaths, unparsedLines };
 };

package/dist/adb/AdbDirectoryListing.js

@@ -0,0 +1,80 @@
+import { isUtf8 } from "node:buffer";
+/**
+ * List direct children with Android 8 Toybox's batched `find -exec` and
+ * `stat -c` support. Names and link targets are NUL-framed; neither is ever
+ * inserted into a line-oriented metadata record or command substitution.
+ */
+export const ADB_DIRECTORY_BATCH_SCRIPT = String.raw `metadata=$(stat -c '%A|%U|%G|%s|%y' "$@") || exit
+printf '%s\n' "$metadata" | {
+  while IFS= read -r metadata; do
+    [ "$#" -gt 0 ] || exit 1
+    path=$1
+    shift
+    printf '%s\000%s\000' "$metadata" "${"${path##*/}"}"
+    case "$metadata" in
+      l*) readlink -n "$path" || exit 1 ;;
+    esac
+    printf '\000'
+  done
+  [ "$#" -eq 0 ]
+}`;
+const METADATA = /^([bcdlps-][rwxstST-]{9})\|([^|\n]+)\|([^|\n]+)\|(\d+)\|([^|\n]+)$/u;
+const parseEntry = (metadata, name, linkTarget) => {
+    const match = METADATA.exec(metadata);
+    if (match === null || name === "" || name.includes("/"))
+        return null;
+    const permissions = match[1];
+    const bytes = Number(match[4]);
+    if (!Number.isSafeInteger(bytes))
+        return null;
+    const isSymlink = permissions.startsWith("l");
+    if (isSymlink ? linkTarget === "" : linkTarget !== "")
+        return null;
+    return {
+        name,
+        kind: permissions.startsWith("d")
+            ? "directory"
+            : isSymlink
+                ? "symlink"
+                : permissions.startsWith("-")
+                    ? "file"
+                    : "other",
+        permissions,
+        owner: match[2],
+        group: match[3],
+        bytes,
+        date: match[5],
+        link_target: isSymlink ? linkTarget : null,
+    };
+};
+/** Parse metadata/name/target NUL triples from `ADB_DIRECTORY_BATCH_SCRIPT`. */
+export const parseAdbDirectoryListing = (stdout) => {
+    const entries = [];
+    const unparsedLines = [];
+    let offset = 0;
+    while (offset < stdout.length) {
+        const metadataEnd = stdout.indexOf(0, offset);
+        const nameEnd = metadataEnd < 0 ? -1 : stdout.indexOf(0, metadataEnd + 1);
+        const targetEnd = nameEnd < 0 ? -1 : stdout.indexOf(0, nameEnd + 1);
+        if (targetEnd < 0) {
+            unparsedLines.push(describeUnparsedRecord(stdout.subarray(offset)));
+            break;
+        }
+        const rawRecord = stdout.subarray(offset, targetEnd + 1);
+        if (!isUtf8(rawRecord)) {
+            unparsedLines.push(describeUnparsedRecord(rawRecord));
+        }
+        else {
+            const entry = parseEntry(stdout.toString("utf8", offset, metadataEnd), stdout.toString("utf8", metadataEnd + 1, nameEnd), stdout.toString("utf8", nameEnd + 1, targetEnd));
+            if (entry === null)
+                unparsedLines.push(rawRecord.toString("utf8"));
+            else
+                entries.push(entry);
+        }
+        offset = targetEnd + 1;
+    }
+    return { entries, unparsedLines };
+};
+const describeUnparsedRecord = (record) => isUtf8(record)
+    ? record.toString("utf8")
+    : `Invalid UTF-8 directory record (hex): ${record.toString("hex")}`;

package/dist/adb/AdbHostFileName.js

@@ -0,0 +1,34 @@
+const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu;
+/**
+ * Derive the final component of a device POSIX path without normalizing the
+ * source. A trailing slash has no filename and must not silently become the
+ * preceding component as `basename` would make it.
+ */
+export const adbHostFileName = (devicePath, platform = process.platform) => {
+    if (devicePath === "" || devicePath.endsWith("/"))
+        return { ok: false, reason: "empty_file_name" };
+    if (devicePath.includes("\0"))
+        return { ok: false, reason: "unsupported_character" };
+    if (!devicePath.startsWith("/"))
+        return { ok: false, reason: "not_absolute_path" };
+    const fileName = devicePath.slice(devicePath.lastIndexOf("/") + 1);
+    if (fileName === "." || fileName === "..")
+        return { ok: false, reason: "dot_segment" };
+    if (platform === "win32") {
+        if (/[\\:*?"<>|]/u.test(fileName) || hasWindowsControl(fileName))
+            return { ok: false, reason: "unsupported_character" };
+        if (WINDOWS_RESERVED_BASENAME.test(fileName))
+            return { ok: false, reason: "reserved_name" };
+        if (/[. ]$/u.test(fileName))
+            return { ok: false, reason: "trailing_dot_or_space" };
+    }
+    return { ok: true, fileName };
+};
+const hasWindowsControl = (fileName) => {
+    for (const character of fileName) {
+        const code = character.codePointAt(0);
+        if (code > 0 && code < 0x20)
+            return true;
+    }
+    return false;
+};