@slack/radar-mcp 1.3.0 → 1.5.0

package/dist/shared/db.js

@@ -0,0 +1,403 @@
+/**
+ * On-device SQLite browser (host-side, read-only).
+ *
+ * Slack's on-device databases are plaintext SQLite (not SQLCipher) on a debug build,
+ * which is what makes host-side reading possible at all: `adb exec-out "run-as <pkg>
+ * cat databases/<db>"` streams the file to the host, where the platform-tools `sqlite3`
+ * binary runs read-only SELECT/PRAGMA against a local copy. Nothing is written on the
+ * device; no app rebuild is needed. If a future build encrypts these DBs, the magic-header
+ * check in `pullDatabase` fails fast with a clear message rather than producing garbage.
+ *
+ * SECURITY: a pulled DB is the full message store in plaintext (request bodies, message
+ * text, user/channel IDs). Pulled copies are written 0600 under a dedicated tmp dir and
+ * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
+ * live from the device (`listDatabases`); none are baked into this file.
+ */
+import { execFile, execFileSync } from "child_process";
+import { promisify } from "util";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { resolveAdbPath } from "./android.js";
+/** The debug build whose sandbox we can `run-as` into. */
+const DB_PKG = "com.Slack.internal.debug";
+/** Dedicated tmp dir for pulled DB copies. Cleaned on start/stop; files written 0600. Port-scoped so concurrent dashboards do not collide. */
+let DB_TMP = path.join(os.tmpdir(), "slack-radar-db");
+/** Initialize DB_TMP with a port-scoped path. Call from the web server on startup. */
+export function initializeDatabasePath(port) {
+    DB_TMP = path.join(os.tmpdir(), `slack-radar-db-${port}`);
+}
+/** Every valid SQLite file begins with these 16 bytes. */
+const SQLITE_MAGIC = Buffer.from("SQLite format 3\0", "binary");
+const ADB_MAX_BUFFER = 256 * 1024 * 1024; // an org message DB can be several MB
+const SQLITE_MAX_BUFFER = 64 * 1024 * 1024;
+// No cached user preference: the target user is passed explicitly to every call (sourced
+// from the dashboard's bound profile / the operator's profile switcher), never guessed.
+// Caching the sqlite binary path is safe because the binary does not change during a session.
+let cachedSqlite = null;
+function adbBin() {
+    const p = resolveAdbPath();
+    if (!p)
+        throw new Error("adb not found. Ensure platform-tools is installed and on PATH.");
+    return p;
+}
+function runAdb(args, opts = {}) {
+    return execFileSync(adbBin(), args, {
+        timeout: 15000,
+        maxBuffer: ADB_MAX_BUFFER,
+        ...opts,
+    });
+}
+const execFileP = promisify(execFile);
+// Async adb/exec — used for the HEAVY operations (the multi-MB device pull and the sqlite
+// query over it). These must NOT use execFileSync: Node is single-threaded, so a blocking
+// 62MB exec-out or a sqlite read freezes the whole event loop (every tab, the stream, and
+// /health hang until it returns). The light, cached probes (ls, pm list users) stay sync.
+function runAdbAsync(args) {
+    // buffer encoding: the pull streams raw SQLite bytes, not text.
+    return execFileP(adbBin(), args, {
+        timeout: 30000,
+        maxBuffer: ADB_MAX_BUFFER,
+        encoding: "buffer",
+    }).then((r) => r.stdout);
+}
+/**
+ * Locate a host `sqlite3`. The Slack on-device DBs use FTS5 virtual tables (search index),
+ * so a binary WITHOUT the fts5 module fails with "no such module: fts5" on those tables —
+ * including the per-table COUNT the browser runs. Android platform-tools' bundled sqlite3 is
+ * built without fts5; the macOS system /usr/bin/sqlite3 has it. So prefer an fts5-capable
+ * binary, and only fall back to a working-but-fts5-less one if none has it (non-FTS DBs still
+ * work there). Cached after first success.
+ */
+function hasSqlite(bin) {
+    try {
+        execFileSync(bin, ["--version"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasFts5(bin) {
+    try {
+        // throws "no such module: fts5" on a binary built without it
+        execFileSync(bin, [":memory:", "CREATE VIRTUAL TABLE t USING fts5(x);"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sqliteBin() {
+    if (cachedSqlite)
+        return cachedSqlite;
+    const candidates = [
+        "/usr/bin/sqlite3", // macOS system build: has fts5
+        "/opt/homebrew/bin/sqlite3",
+        "/usr/local/bin/sqlite3",
+        path.join(process.env.HOME ?? "", "Library/Android/sdk/platform-tools/sqlite3"),
+        "sqlite3",
+    ];
+    const working = candidates.filter(hasSqlite);
+    // Prefer one with fts5; else any working sqlite3 (non-FTS DBs still query fine).
+    cachedSqlite = working.find(hasFts5) ?? working[0] ?? "sqlite3";
+    return cachedSqlite;
+}
+/**
+ * Enumerate the Android user IDs present on the device from `pm list users`, whose lines
+ * read `UserInfo{<id>:<name>:<flags>} ...`. Returns the numeric ids as strings, in device
+ * order (personal 0 first, then profiles 10/11/12/... — NOT a hardcoded guess, so a second
+ * work profile or a cloned profile is covered). Empty on parse/adb failure.
+ */
+function deviceUserIds() {
+    try {
+        const out = runAdb(["shell", "pm list users"]).toString();
+        const ids = [];
+        for (const m of out.matchAll(/UserInfo\{(\d+):/g))
+            ids.push(m[1]);
+        return ids;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Probe whether the debug build is runnable for an Android user. Used to filter the
+ * device's users down to the profiles that actually have the build (a multi-profile device
+ * may have it on personal=0 and a work profile=10/11/..., each holding a DIFFERENT org's store).
+ */
+function userHasBuild(user) {
+    try {
+        runAdb([
+            "shell",
+            `run-as ${DB_PKG} ${user ? "--user " + user : ""} ls databases >/dev/null 2>&1 && echo ok`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Android users that actually have the debug build, enumerated from the device (not a
+ * fixed list). "" means a single-user device (no --user flag). Empty array => build not
+ * installed/debuggable anywhere.
+ *
+ * CACHED: this runs `pm list users` + a `run-as` probe per user — several blocking adb
+ * round-trips. The set of profiles does not change during a session, so probing it on every
+ * /dbs request froze the (single-threaded) event loop and hung the whole dashboard. Resolve
+ * it once and reuse; resetDbState() clears it for a device/profile change.
+ */
+let cachedUsers = null;
+export function availableUsers() {
+    if (cachedUsers)
+        return cachedUsers;
+    const ids = deviceUserIds();
+    const found = ids.filter(userHasBuild);
+    // Fallback for an older adb / odd `pm` output: try the no-flag form.
+    const resolved = found.length ? found : userHasBuild("") ? [""] : [];
+    if (resolved.length)
+        cachedUsers = resolved; // only cache a successful probe
+    return resolved;
+}
+/** `--user N` flag for a resolved user, or "" for the single-user case. */
+function userFlag(user) {
+    return user ? `--user ${user}` : "";
+}
+/**
+ * Reset cached device state. Clears the sqlite-binary path so a device swap
+ * re-detects it. The targeted Android user is passed explicitly to every call
+ * (sourced from the dashboard's bound profile) rather than guessed, so list / pull /
+ * query can never silently disagree on which profile's store they touch.
+ */
+export function resetDbState() {
+    cachedSqlite = null;
+    cachedUsers = null;
+}
+/** A DB name from the device. Reject anything that is not a bare filename. */
+function assertSafeName(name) {
+    if (!name || !/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new Error("invalid database name");
+    }
+}
+/**
+ * Local copy path, scoped by Android user. A work + personal profile can each hold a
+ * databases/<same-name> with DIFFERENT contents; without the user in the path, pulling
+ * one would overwrite the other's copy and queries would read the wrong profile's store.
+ */
+function localPath(name, user) {
+    const safeName = name.replace(/[^A-Za-z0-9._-]/g, "_");
+    const safeUser = (user || "single").replace(/[^A-Za-z0-9._-]/g, "_");
+    return path.join(DB_TMP, `u${safeUser}-${safeName}.sqlite`);
+}
+/**
+ * Resolve the Android user to target. The dashboard passes the profile it is bound to
+ * (transport.getActiveUserId()); if that user does not have the build (or none was
+ * passed), fall back to the first available profile. Throws if none is available.
+ */
+function resolveUser(user) {
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    if (user != null && available.includes(user))
+        return user;
+    return available[0];
+}
+/**
+ * List the on-device databases for the given Android user (the dashboard's bound
+ * profile). Filters out WAL/SHM/journal sidecar files. Returns the resolved user and
+ * the full set of profiles that have the build, so the UI can show which profile this
+ * store belongs to and offer a switch when more than one exists.
+ */
+export function listDatabases(user) {
+    // NOTE: do not resetDbState() here — that would re-run the multi-call user probe on every
+    // /dbs and freeze the event loop. The profile set is cached for the session; a device or
+    // profile change clears it via resetDbState() (wired to /enable / reconnect).
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    const u = user != null && available.includes(user) ? user : available[0];
+    const out = runAdb([
+        "shell",
+        `run-as ${DB_PKG} ${userFlag(u)} ls -1 databases`,
+    ]).toString();
+    const names = out
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .filter((n) => !/-(wal|shm|journal)$/.test(n));
+    return { user: u, availableUsers: available, names };
+}
+/**
+ * Stream a database off the device to a local 0600 copy (scoped to the target user) and
+ * return its path. `run-as ... cp` into shared storage fails silently (sandbox), so the
+ * working path is `exec-out cat` piped to a host file. Validates the SQLite magic header
+ * so a missing DB (whose `cat` emits an error string, not file bytes) fails with a clear
+ * message instead of being written as a junk file that later trips an opaque parse error.
+ *
+ * WAL: Slack's on-device DBs are WAL-mode and the live app holds write connections open,
+ * so recently-committed rows live in the `-wal` sidecar, NOT yet in the main file. Pulling
+ * the main file alone (and reading it `immutable`) silently drops those recent rows — the
+ * exact data a debugger wants. So we also pull the `-wal` and `-shm` sidecars next to the
+ * main copy (best-effort; absent if the DB was checkpointed), and queryDatabase opens the
+ * copy NORMALLY (not immutable) so SQLite replays the WAL into the view.
+ */
+export async function pullDatabase(name, user, force = false) {
+    assertSafeName(name);
+    const u = resolveUser(user);
+    // DB_TMP lives under os.tmpdir(), which the OS (or a manual cleanup) can wipe
+    // mid-session; recreate it every pull so writeFileSync cannot ENOENT on a gone dir.
+    // mode 0700: the pulled copies are the plaintext message store; even though each file is
+    // 0600, a world-traversable dir would leak the DB filenames to other local users.
+    fs.mkdirSync(DB_TMP, { recursive: true, mode: 0o700 });
+    const local = localPath(name, u);
+    // Pull-once: an on-device DB can be several MB and writes a plaintext copy to disk, so
+    // reuse the existing local copy across db-switches. The UI's Refresh control passes
+    // force=true to re-stream when the user wants the current device state.
+    if (!force && fs.existsSync(local))
+        return local;
+    let bytes;
+    try {
+        // Async exec-out so a multi-MB pull does not block the event loop (which would hang
+        // every other tab, the stream, and /health for the duration of the pull).
+        bytes = await runAdbAsync([
+            "exec-out",
+            `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}`,
+        ]);
+    }
+    catch {
+        throw new Error(`"${name}" is not readable on the device (not present for this profile, or run-as failed). List databases to see what is there.`);
+    }
+    if (!bytes ||
+        bytes.length < SQLITE_MAGIC.length ||
+        !bytes.subarray(0, SQLITE_MAGIC.length).equals(SQLITE_MAGIC)) {
+        throw new Error(`"${name}" did not come back as a valid SQLite file (${bytes ? bytes.length : 0} bytes). It may not exist on the device, the org may not be loaded on this profile, or the database may be encrypted.`);
+    }
+    fs.writeFileSync(local, bytes, { mode: 0o600 });
+    // Pull the WAL sidecars alongside the main file so the normal (non-immutable) open below
+    // replays recently-committed rows. Best-effort: a checkpointed DB has none; a `cat` of a
+    // missing sidecar returns empty, which we simply skip. Stale local sidecars from a prior
+    // pull are removed first so they cannot be mis-applied to a freshly-pulled main file.
+    // The main file and the sidecars are separate `cat` round-trips against a DB the app may
+    // be writing, so the snapshot is best-effort, not atomic: if the app checkpoints between
+    // the cats, SQLite finds a mismatched -wal salt and ignores it (a partial, not corrupt,
+    // view). Unavoidable without a device-side read lock; the normal-open choice still stands.
+    for (const ext of ["-wal", "-shm"]) {
+        const sidecar = local + ext;
+        try {
+            fs.rmSync(sidecar, { force: true });
+            const sb = await runAdbAsync([
+                "exec-out",
+                `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}${ext}`,
+            ]);
+            if (sb && sb.length > 0)
+                fs.writeFileSync(sidecar, sb, { mode: 0o600 });
+        }
+        catch {
+            // sidecar absent or unreadable — fine, the main file stands alone
+        }
+    }
+    return local;
+}
+/**
+ * Run a read-only query against a (lazily pulled) local copy.
+ *
+ * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
+ * opened DB, but a single SELECT can still READ any host file the process can open, via
+ * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
+ * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
+ * or a pushed db-spec's `sql`. Three layers close this:
+ *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ *      control; a keyword denylist alone is whack-a-mole.
+ *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
+ *      explicit reject of attach/readfile/writefile names as defense in depth.
+ *   3. `-readonly` still blocks writes to the opened DB.
+ * Surfaces sqlite's own error message on failure.
+ */
+export async function queryDatabase(name, sql, user) {
+    assertSafeName(name);
+    // Leading-keyword gate over the common read-query entry forms: SELECT, WITH
+    // (CTEs, common against the message store), EXPLAIN, VALUES, PRAGMA. This shapes
+    // UX; it is NOT the security boundary. A `WITH ... DELETE` would slip the gate,
+    // but the device-safety property does not rest here — it rests on the copy-based
+    // design (the device file is `cat`'d to a throwaway and never written back), plus
+    // `-safe` (blocks file access), the single-statement gate, the write-PRAGMA
+    // reject, and the file-primitive denylist below. Worst case a smuggled write
+    // mutates the disposable copy; the device store is untouched.
+    if (!/^\s*(select|pragma|with|explain|values)\b/i.test(sql)) {
+        throw new Error("only read-only statements are allowed (SELECT, WITH, EXPLAIN, VALUES, PRAGMA)");
+    }
+    // Single statement only: a trailing `;` is fine, but no statement chaining (which is how
+    // `select 1; ATTACH ...; select * from s.t` smuggles a read past the leading-keyword check).
+    if (/;\s*\S/.test(sql)) {
+        throw new Error("only a single statement is allowed (no ';'-separated statements)");
+    }
+    // Reject the common write PRAGMAs: an assigning form (`PRAGMA user_version=5`,
+    // `PRAGMA journal_mode=DELETE`) or a checkpoint (`PRAGMA wal_checkpoint(...)`).
+    // This is not exhaustive — a few argless mutating PRAGMAs (`incremental_vacuum`,
+    // `optimize`, `shrink_memory`) still pass. That is acceptable: the device-safety
+    // guarantee comes from the copy-based design (we only ever read the device file
+    // and write a throwaway local copy), not from this gate. Worst case such a PRAGMA
+    // mutates the disposable copy; the device store is never written back.
+    if (/^\s*pragma\b/i.test(sql) && (/=/.test(sql) || /\bwal_checkpoint\b/i.test(sql))) {
+        throw new Error("that PRAGMA writes; only read-only PRAGMAs are allowed");
+    }
+    // Belt-and-suspenders over -safe: reject the file-access primitives by name too.
+    if (/\b(attach|readfile|writefile|edit|load_extension|fts3_tokenizer)\b/i.test(sql)) {
+        throw new Error("that function/statement is not allowed (read-only, no file access)");
+    }
+    const u = resolveUser(user);
+    const local = localPath(name, u);
+    if (!fs.existsSync(local))
+        await pullDatabase(name, u);
+    let out;
+    try {
+        // Open the pulled copy NORMALLY (not `immutable`, not `-readonly`): pullDatabase brought
+        // the -wal/-shm sidecars along, and only a normal open replays the WAL so recently-
+        // committed rows (which live in -wal until the app checkpoints) are visible. immutable=1
+        // / -readonly would read the main file alone and silently drop those rows. The copy is in
+        // our own writable temp dir, so SQLite can do its WAL replay there; nothing on the device
+        // is touched. `-safe` is the load-bearing read-only/exfil control (blocks ATTACH/readfile/
+        // writefile/load_extension at the engine level) and holds in normal mode too. The path is
+        // URI-encoded so spaces/specials are safe. Async exec so a large query does not block the
+        // event loop.
+        const uri = `file:${encodeURI(local)}`;
+        const r = await execFileP(sqliteBin(), ["-safe", "-json", uri, sql], {
+            timeout: 15000,
+            maxBuffer: SQLITE_MAX_BUFFER,
+            encoding: "utf8",
+        });
+        out = String(r.stdout) || "[]";
+    }
+    catch (e) {
+        const err = e;
+        const stderr = (err.stderr && err.stderr.toString().trim()) || "";
+        const m = stderr.match(/(no such table:.*|no such column:.*|near ".*|syntax error.*|.*error.*)/i);
+        throw new Error(m ? m[0].trim() : stderr.split("\n")[0] || "query failed");
+    }
+    return JSON.parse(out);
+}
+/** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */
+export function pulledSize(name, user) {
+    try {
+        return fs.statSync(localPath(name, resolveUser(user))).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Remove all pulled database copies. Pulled DBs are plaintext message stores, so they
+ * must not linger; call on server start and stop. Best-effort.
+ */
+export function cleanupPulledDatabases() {
+    try {
+        fs.rmSync(DB_TMP, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort
+    }
+}

package/dist/shared/screen.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Live device-screen mirror + record, for the dashboard's Screen overlay.
+ *
+ * Pipeline (scrcpy-lite, no custom decoder): `adb exec-out screenrecord
+ * --output-format=h264` on the active display -> `ffmpeg` transcodes h264 to
+ * MJPEG -> the server pushes JPEG frames to a browser <img> over
+ * multipart/x-mixed-replace. Record tees the same JPEG frames to a second
+ * ffmpeg (mjpeg in -> libx264 mp4), so the live view and the recording share one
+ * screenrecord (the way scrcpy shares one capture).
+ *
+ * SENSITIVE: this mirrors the real device screen, which shows live DMs, message
+ * content, and anything else on screen. It is OFF by default and gated behind an
+ * explicit per-process consent (see consent state below); the server refuses the
+ * stream and record routes until consent is granted.
+ *
+ * DEPENDENCY POLICY: ffmpeg is NOT bundled and NOT a hard dependency (it is large
+ * and license-encumbered; the published package keeps a single runtime dep). The
+ * stream/record paths detect-and-degrade: present -> embedded MJPEG; absent ->
+ * a clear message plus the platform install command, and a scrcpy fallback hint.
+ * The screenshot path uses pure `screencap` (PNG, no transcode) so it MUST keep
+ * working with no ffmpeg.
+ *
+ * Hard-won device facts baked in (Pixel 10 Pro Fold and similar):
+ *  - Active-display detect must be deterministic: pick the powered-ON physical
+ *    panel from `cmd display get-displays`. Byte-probing cannot tell a dozing
+ *    black panel from a live one (a DOZE panel still emits ~1 keyframe).
+ *  - `screencap -p` prepends a "[Warning] Multiple displays were found" text line
+ *    on multi-display devices, corrupting the PNG. Strip everything before the
+ *    PNG magic bytes.
+ *  - screenrecord emits full-range YUV that the mjpeg encoder rejects; `-vf
+ *    format=yuvj420p` fixes it.
+ *  - H.264 emits nothing on a static screen (correct, not a hang). A
+ *    multipart/x-mixed-replace viewer only paints part N when part N+1 arrives,
+ *    so a keepalive re-pushes the last frame while idle to flush it.
+ *  - adb does not reliably SIGKILL the device-side screenrecord on host pipe
+ *    close; orphaned screenrecord procs congest the single adb transport. Kill
+ *    explicitly on cleanup.
+ */
+import { type ChildProcess } from "child_process";
+/**
+ * Remove all recorded mp4s from the screen tmp dir. Recordings capture sensitive
+ * live screen content and must not linger across sessions on disk. Called on
+ * resetScreenState() (device re-enable) and on process exit — the same posture the
+ * DB-browser uses for its pulled copies. Scoped to the radar_screen_*.mp4 names this
+ * module writes so it never deletes an unrelated file that landed in the dir.
+ */
+export declare function cleanupRecordings(): void;
+/** Resolve an ffmpeg binary, or null if none is installed. Cached. */
+export declare function resolveFfmpeg(): string | null;
+/** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
+export declare function hasScrcpy(): boolean;
+/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+export declare function ffmpegInstallHint(): string;
+/** Capability summary for /health: what the screen overlay can do on this machine. */
+export declare function screenCapabilities(): {
+    screenshot: boolean;
+    liveCast: boolean;
+    ffmpeg: boolean;
+    scrcpy: boolean;
+    installHint: string | null;
+};
+/** Grant consent to mirror the live screen. Per server process. */
+export declare function grantScreenConsent(): void;
+export declare function hasScreenConsent(): boolean;
+export interface DisplayInfo {
+    on: boolean;
+    phys: string;
+}
+/**
+ * Parse `adb shell cmd display get-displays` output into per-display
+ * {on, phys}, dropping any block without a physical id. The active panel is the
+ * one whose block reports state ON.
+ */
+export declare function parseDisplays(out: string): DisplayInfo[];
+/** Choose the physical display id to record: the powered-ON panel, else a lone panel, else null. */
+export declare function pickDisplay(displays: DisplayInfo[]): {
+    phys: string | null;
+    note: string;
+};
+/** Strip any text prefix (e.g. a multi-display warning) before the PNG magic header. */
+export declare function stripPngPrefix(raw: Buffer): Buffer;
+/** Detect (and cache) the active display id. resetScreenState() forces a re-detect. */
+export declare function detectDisplay(): Promise<string | null>;
+export declare function displayNote(): string;
+/** Capture a full-resolution PNG of the active display. Works without ffmpeg. */
+export declare function captureScreenshot(): Promise<Buffer | null>;
+interface Recording {
+    proc: ChildProcess;
+    path: string;
+}
+interface LiveCast {
+    sr: ChildProcess;
+    ff: ChildProcess;
+    viewers: Set<NodeJS.WritableStream>;
+    lastFrame: Buffer | null;
+    lastFrameTs: number;
+    recording: Recording | null;
+    fps: number;
+    keepalive: NodeJS.Timeout | null;
+}
+/**
+ * Start (or return the existing) live cast. Returns null if ffmpeg is unavailable
+ * — callers must degrade rather than assume a stream. The boundary string is
+ * SC_BOUNDARY; the route serves multipart/x-mixed-replace with it.
+ */
+export declare function startLive(fps: number): LiveCast | null;
+/** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
+export declare function addViewer(L: LiveCast, res: NodeJS.WritableStream): void;
+export declare function removeViewer(res: NodeJS.WritableStream): void;
+export declare function getLive(): LiveCast | null;
+export declare function lastFrame(): Buffer | null;
+export declare function primeIfNeeded(): Promise<void>;
+export declare const SCREEN_BOUNDARY = "radarframe";
+export declare function startRecording(): string | null;
+export declare function stopRecording(L?: LiveCast): Promise<string | null>;
+/**
+ * Resolve a recording for download. Restricted to the screen tmp dir AND to the
+ * radar_screen_*.mp4 name this module writes: path.basename strips any directory
+ * (no traversal), and the prefix/extension check means a download request can only
+ * ever name a radar recording, never an arbitrary file that happened to land in the dir.
+ */
+export declare function recordingPath(file: string): string | null;
+/** Reset detection + tear down any live cast. Called on device re-enable and shutdown. */
+export declare function resetScreenState(): void;
+/**
+ * Kill any live cast (and orphaned device-side screenrecord) on process exit. Mirrors
+ * logcat-capture.registerCleanup(); without it, Ctrl-C on an open mirror orphans the
+ * screenrecord + ffmpeg children and leaves the device transport congested for the
+ * next session. Called from createServer().
+ */
+export declare function registerScreenCleanup(): void;
+export {};