Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

6.5 KB
Raw Blame
// SPDX-License-Identifier: MPL-2.0
//! Elevated over USB (`docs/protocol/elevated-usb.md`).
//!
//! Elevated runs a small helper on the phone as Android's shell user. The
//! phone normally starts it through its own wireless debugging; a phone
//! plugged into a PC with USB debugging allowed can instead ask the PC to
//! start it, the way scrcpy starts its server. The PC only runs the app's own
//! helper and the app's own grants (checked in [`ElevatedUsbStart::is_valid`]),
//! and only on the phone that asked, over that phone's own USB connection.
//! The helper runs as long as the PC holds its adb shell: until the phone
//! asks again, the cable comes out, or the node stops.

use std::{net::SocketAddr, sync::Arc, time::Duration};

use nectarlink_protocol::{
    DeviceId, Envelope, ErrorCode,
    messages::{ElevatedUsbReady, ElevatedUsbStart, elevated, types},
};
use tokio::io::{AsyncBufReadExt, AsyncReadExt, BufReader};

use crate::{
    error::{Error, Result},
    node::Shared,
    session::Session,
};

/// How long one grant may take.
const GRANT_TIMEOUT: Duration = Duration::from_secs(10);
/// How long the helper may take to say it's listening.
const READY_TIMEOUT: Duration = Duration::from_secs(15);

/// The phone's side: asks `session`'s PC to start this phone's helper and
/// returns the port it listens on.
pub(crate) async fn start(session: &Session, request: ElevatedUsbStart) -> Result<u16> {
    if !request.is_valid() {
        return Err(Error::Protocol("invalid Elevated over USB request".into()));
    }
    let env = Envelope::new(types::ELEVATED_USB_START, &request)?;
    let reply = session.request(env, READY_TIMEOUT + GRANT_TIMEOUT * elevated::MAX_GRANTS as u32).await?;
    let ready: ElevatedUsbReady = reply.expect_body(types::ELEVATED_USB_READY)?;
    Ok(ready.port)
}

/// The PC's side of `elevated.usb.start`.
pub(crate) async fn handle(shared: &Arc<Shared>, session: &Arc<Session>, env: &Envelope) -> Result<bool> {
    if env.t != types::ELEVATED_USB_START {
        return Ok(false);
    }
    let peer = session.peer;
    let request: ElevatedUsbStart = env.body()?;
    let usb = shared.usb_serials.lock().unwrap_or_else(|e| e.into_inner()).get(&peer).cloned();
    let refusal = if !request.is_valid() {
        Some(Envelope::error(ErrorCode::BadMessage, "invalid Elevated over USB request"))
    } else if !shared.we_offer(elevated::USB) {
        Some(Envelope::error(ErrorCode::Unsupported, "this PC doesn't start Elevated over USB"))
    } else if usb.is_none() {
        Some(Envelope::error(ErrorCode::Unsupported, "this phone isn't connected to this PC over USB"))
    } else {
        None
    };
    if let Some(refusal) = refusal {
        session.send(refusal.reply_to(env.id)).await?;
        return Ok(true);
    }
    let Some((serial, adb_addr)) = usb else { return Ok(true) };
    // Grants and the helper take seconds: answer from a task of its own.
    let (shared, session, id) = (shared.clone(), session.clone(), env.id);
    tokio::spawn(async move {
        let reply = match launch(&shared, peer, adb_addr, &serial, &request).await {
            Ok(port) => Envelope::new(types::ELEVATED_USB_READY, &ElevatedUsbReady { port })
                .unwrap_or_else(|_| Envelope::error(ErrorCode::Internal, "can't answer")),
            Err(reason) => {
                tracing::info!(peer = %peer.short(), reason, "couldn't start Elevated over USB");
                Envelope::error(ErrorCode::Internal, reason)
            }
        };
        let _ = session.send(reply.reply_to(id)).await;
    });
    Ok(true)
}

/// Runs the grants, then starts the helper and keeps its shell open in a task
/// stored for `peer`. Returns the helper's port.
async fn launch(
    shared: &Arc<Shared>,
    peer: DeviceId,
    adb_addr: SocketAddr,
    serial: &str,
    request: &ElevatedUsbStart,
) -> std::result::Result<u16, String> {
    for grant in &request.grants {
        run_to_end(adb_addr, serial, grant).await?;
    }
    let command = helper_command(&request.apk, &request.token);
    let stream = nectarlink_adb::shell(adb_addr, serial, &command).await.map_err(|e| e.to_string())?;
    let mut output = BufReader::new(stream);
    let mut first = String::new();
    tokio::time::timeout(READY_TIMEOUT, output.read_line(&mut first))
        .await
        .map_err(|_| "the helper didn't start in time".to_owned())?
        .map_err(|e| e.to_string())?;
    let port = parse_ready(&first).ok_or_else(|| format!("the helper said {:?}", first.trim()))?;
    // Holding the shell keeps the helper running; its output is only drained.
    let keep = tokio::spawn(async move {
        let mut sink = [0u8; 1024];
        while matches!(output.read(&mut sink).await, Ok(n) if n > 0) {}
    });
    if let Some(old) = shared.usb_helpers.lock().unwrap_or_else(|e| e.into_inner()).insert(peer, keep) {
        old.abort();
    }
    Ok(port)
}

/// Runs a short command and waits for it to finish.
async fn run_to_end(adb_addr: SocketAddr, serial: &str, command: &str) -> std::result::Result<(), String> {
    let mut stream = nectarlink_adb::shell(adb_addr, serial, command).await.map_err(|e| e.to_string())?;
    let mut ignored = Vec::new();
    tokio::time::timeout(GRANT_TIMEOUT, stream.read_to_end(&mut ignored))
        .await
        .map_err(|_| format!("{command:?} didn't finish"))?
        .map_err(|e| e.to_string())?;
    Ok(())
}

/// The shell command that starts the helper (both parts already checked).
fn helper_command(apk: &str, token: &str) -> String {
    format!("CLASSPATH={apk} app_process /system/bin {} {token}", elevated::HELPER_CLASS)
}

/// The port from the helper's first line, `ready <port>`.
fn parse_ready(line: &str) -> Option<u16> {
    line.trim().strip_prefix("ready ")?.parse().ok().filter(|p| *p > 0)
}

/// Stops every helper started over USB (the node is stopping).
pub(crate) fn stop_all(shared: &Shared) {
    for (_, helper) in shared.usb_helpers.lock().unwrap_or_else(|e| e.into_inner()).drain() {
        helper.abort();
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_helper_command_and_its_answer() {
        assert_eq!(
            helper_command("/data/app/~~a==/app.nectarlink-b==/base.apk", "00ff"),
            "CLASSPATH=/data/app/~~a==/app.nectarlink-b==/base.apk app_process /system/bin \
             app.nectarlink.android.elevated.InputServer 00ff"
        );
        assert_eq!(parse_ready("ready 41234\n"), Some(41234));
        assert_eq!(parse_ready("ready 0"), None);
        assert_eq!(parse_ready("can't listen: denied"), None);
        assert_eq!(parse_ready(""), None);
    }
}