@yume-chan/adb 2.6.2 → 3.0.0-beta.1

package/src/daemon/auth/authenticator.ts

@@ -0,0 +1,186 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { PromiseResolver } from "@yume-chan/async";
+import type { WritableStreamDefaultWriter } from "@yume-chan/stream-extra";
+import {
+    AbortController,
+    Consumable,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
+
+import { AdbDeviceFeatures, AdbFeature } from "../../features.js";
+import type { AdbPacketData, AdbPacketInit } from "../packet.js";
+import { AdbCommand, calculateChecksum } from "../packet.js";
+import type { AdbDaemonTransportInit } from "../transport.js";
+import {
+    ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
+    AdbDaemonTransport,
+} from "../transport.js";
+
+import type { AdbDaemonDefaultAuthProcessorInit } from "./packet-processor.js";
+import { AdbDaemonDefaultAuthProcessor } from "./packet-processor.js";
+
+export interface AdbDaemonAuthProcessor {
+    process(packet: AdbPacketData): Promise<AdbPacketData>;
+
+    close?(): MaybePromiseLike<undefined>;
+}
+
+export type AdbDaemonAuthenticateOptions = Pick<
+    AdbDaemonTransportInit,
+    | "serial"
+    | "connection"
+    | "features"
+    | "preserveConnection"
+    | "readTimeLimit"
+> & {
+    /**
+     * The number of bytes the device can send before receiving an ack packet.
+     *
+     * Android 14 added the Delayed Acknowledgement feature to improve performance,
+     * especially for high-latency connections like ADB over Wi-Fi.
+     *
+     * Unlike {@linkcode AdbDaemonTransportInit.initialDelayedAckBytes},
+     * setting this parameter to 0 or a negative number will disable Delayed Ack.
+     */
+    initialDelayedAckBytes?: number | undefined;
+} & (AdbDaemonDefaultAuthProcessorInit | { processor: AdbDaemonAuthProcessor });
+
+/**
+ * Send a packet during authentication stage
+ * @param writer Writer to send packet to
+ * @param packet The packet to send. Note: this object will be modified.
+ */
+function sendPacket(
+    writer: WritableStreamDefaultWriter<Consumable<AdbPacketInit>>,
+    packet: AdbPacketData,
+): Promise<void> {
+    // Always send checksum in auth steps
+    // Because we don't know if the device needs it or not.
+    (packet as AdbPacketInit).checksum = calculateChecksum(packet.payload);
+    (packet as AdbPacketInit).magic = packet.command ^ 0xffffffff;
+    return Consumable.WritableStream.write(writer, packet as AdbPacketInit);
+}
+
+/**
+ * Authenticates an `AdbDaemonConnection` using an `AdbDaemonAuthProcessor`.
+ */
+export async function adbDaemonAuthenticate({
+    serial,
+    connection,
+    features = AdbDeviceFeatures,
+    initialDelayedAckBytes = ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
+    preserveConnection,
+    readTimeLimit,
+    ...processorInit
+}: AdbDaemonAuthenticateOptions) {
+    const processor =
+        "processor" in processorInit
+            ? processorInit.processor
+            : new AdbDaemonDefaultAuthProcessor(processorInit);
+
+    // Initially, set to highest-supported version and payload size.
+    let version = 0x01000001;
+    // Android 4: 4K, Android 7: 256K, Android 9: 1M
+    let maxPayloadSize = 1024 * 1024;
+
+    const resolver = new PromiseResolver<string>();
+
+    const abortController = new AbortController();
+
+    const writer = connection.writable.getWriter();
+
+    const pipe = connection.readable
+        .pipeTo(
+            new WritableStream({
+                write: async (packet) => {
+                    // Here is similar to `AdbPacketDispatcher`,
+                    // But the received packet types and send packet processing are different.
+                    switch (packet.command) {
+                        case AdbCommand.Connect:
+                            version = Math.min(version, packet.arg0);
+                            maxPayloadSize = Math.min(
+                                maxPayloadSize,
+                                packet.arg1,
+                            );
+                            resolver.resolve(decodeUtf8(packet.payload));
+                            break;
+                        case AdbCommand.Auth: {
+                            await sendPacket(
+                                writer,
+                                await processor.process(packet),
+                            );
+                            break;
+                        }
+                        default:
+                            // Maybe the previous ADB client exited without reading all packets,
+                            // so they are still waiting in OS internal buffer.
+                            // Just ignore them.
+                            // Because a `Connect` packet will reset the device,
+                            // Eventually there will be `Connect` and `Auth` response packets.
+                            break;
+                    }
+                },
+            }),
+            {
+                // Don't cancel the source ReadableStream on AbortSignal abort.
+                preventCancel: true,
+                signal: abortController.signal,
+            },
+        )
+        .then(
+            async () => {
+                await processor.close?.();
+
+                // If `resolver` is already settled, call `reject` won't do anything.
+                resolver.reject(new Error("Connection closed unexpectedly"));
+            },
+            async (e) => {
+                await processor.close?.();
+
+                resolver.reject(e);
+            },
+        );
+
+    if (initialDelayedAckBytes <= 0) {
+        // Disable delayed ack by not sending this feature to the device
+        features = features.filter(
+            (feature) => feature !== AdbFeature.DelayedAck,
+        );
+        initialDelayedAckBytes = 0;
+    }
+
+    let banner: string;
+    try {
+        await sendPacket(writer, {
+            command: AdbCommand.Connect,
+            arg0: version,
+            arg1: maxPayloadSize,
+            // The terminating `;` is required in formal definition
+            // But ADB daemon (all versions) can still work without it
+            payload: encodeUtf8(`host::features=${features.join(",")}`),
+        });
+
+        banner = await resolver.promise;
+    } finally {
+        // When failed, release locks on `connection` so the caller can try again.
+        // When success, also release locks so `AdbPacketDispatcher` can use them.
+        abortController.abort();
+        writer.releaseLock();
+
+        // Wait until pipe stops (`ReadableStream` lock released)
+        await pipe;
+    }
+
+    return new AdbDaemonTransport({
+        serial,
+        connection,
+        version,
+        maxPayloadSize,
+        banner,
+        features,
+        initialDelayedAckBytes,
+        preserveConnection,
+        readTimeLimit,
+    });
+}

package/src/daemon/auth/index.ts

@@ -0,0 +1,4 @@
+export * from "./authenticator.js";
+export * from "./packet-processor.js";
+export * from "./public-key.js";
+export * from "./type.js";

package/src/daemon/auth/packet-processor.ts

@@ -0,0 +1,212 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { EmptyUint8Array, encodeUtf8 } from "@yume-chan/struct";
+
+import {
+    calculateBase64EncodedLength,
+    encodeBase64,
+} from "../../utils/base64.js";
+import { rsaSign } from "../crypto.js";
+import type { AdbPacketData } from "../packet.js";
+import { AdbCommand } from "../packet.js";
+
+import type { AdbDaemonAuthProcessor } from "./authenticator.js";
+import {
+    adbGeneratePublicKey,
+    adbGetPublicKeyFingerprint,
+    adbGetPublicKeySize,
+} from "./public-key.js";
+import type { AdbPrivateKey } from "./type.js";
+
+export type MaybeError<T> = T | Error;
+
+export type AdbKeyIterable =
+    | Iterable<MaybeError<AdbPrivateKey>>
+    | AsyncIterable<MaybeError<AdbPrivateKey>>;
+
+export interface AdbCredentialManager {
+    /**
+     * Generates and stores a RSA private key with modulus length `2048` and public exponent `65537`.
+     */
+    generateKey(): MaybePromiseLike<AdbPrivateKey>;
+
+    /**
+     * Synchronously or asynchronously iterates through all stored RSA private keys.
+     *
+     * Each call to `iterateKeys` must return a different iterator that iterate through all stored keys.
+     */
+    iterateKeys(): AdbKeyIterable;
+}
+
+export interface AdbKeyInfo {
+    fingerprint: string;
+    name: string | undefined;
+}
+
+export const AdbDaemonAuthType = {
+    Token: 1,
+    Signature: 2,
+    PublicKey: 3,
+} as const;
+
+export type AdbDaemonAuthType =
+    (typeof AdbDaemonAuthType)[keyof typeof AdbDaemonAuthType];
+
+export interface AdbDaemonDefaultAuthProcessorInit {
+    credentialManager: AdbCredentialManager;
+    onKeyLoadError?: ((error: Error) => void) | undefined;
+    onSignatureAuthentication?: ((key: AdbKeyInfo) => void) | undefined;
+    onSignatureRejected?: ((key: AdbKeyInfo) => void) | undefined;
+    onPublicKeyAuthentication?: ((key: AdbKeyInfo) => void) | undefined;
+}
+
+export class AdbDaemonDefaultAuthProcessor implements AdbDaemonAuthProcessor {
+    #credentialManager: AdbCredentialManager;
+    #onKeyLoadError: ((error: Error) => void) | undefined;
+    #onSignatureAuthentication: ((key: AdbKeyInfo) => void) | undefined;
+    #onSignatureRejected: ((key: AdbKeyInfo) => void) | undefined;
+    #onPublicKeyAuthentication: ((key: AdbKeyInfo) => void) | undefined;
+
+    #iterator:
+        | Iterator<MaybeError<AdbPrivateKey>, void, void>
+        | AsyncIterator<MaybeError<AdbPrivateKey>, void, void>
+        | undefined;
+
+    #prevKeyInfo: AdbKeyInfo | undefined;
+    #firstKey: AdbPrivateKey | undefined;
+
+    constructor(init: AdbDaemonDefaultAuthProcessorInit) {
+        this.#credentialManager = init.credentialManager;
+        this.#onKeyLoadError = init.onKeyLoadError;
+        this.#onSignatureAuthentication = init.onSignatureAuthentication;
+        this.#onSignatureRejected = init.onSignatureRejected;
+        this.#onPublicKeyAuthentication = init.onPublicKeyAuthentication;
+    }
+
+    /**
+     * Gets the next available private key.
+     * @returns The next available private key, or `undefined` if no more key is available
+     */
+    async #getNextKey() {
+        if (!this.#iterator) {
+            const iterable = this.#credentialManager.iterateKeys();
+            if (Symbol.iterator in iterable) {
+                this.#iterator = iterable[Symbol.iterator]();
+            } else if (Symbol.asyncIterator in iterable) {
+                this.#iterator = iterable[Symbol.asyncIterator]();
+            } else {
+                throw new Error("`iterateKeys` doesn't return an iterator");
+            }
+        }
+
+        while (true) {
+            const { done, value } = await this.#iterator.next();
+            if (done) {
+                return undefined;
+            }
+
+            if (value instanceof Error) {
+                // Report the error, then continue calling `next`
+                this.#onKeyLoadError?.(value);
+                continue;
+            }
+
+            return value;
+        }
+    }
+
+    /**
+     * Tries to sign the challenge using the next private key.
+     *
+     * @param challenge The data to sign
+     * @returns An `AdbPacket` containing the response, or `undefined` if no key is available
+     */
+    async #sign(challenge: Uint8Array): Promise<AdbPacketData | undefined> {
+        const key = await this.#getNextKey();
+        if (!key) {
+            return undefined;
+        }
+
+        if (!this.#firstKey) {
+            this.#firstKey = key;
+        }
+
+        // A new challenge implies the previous signature was rejected.
+        if (this.#prevKeyInfo) {
+            this.#onSignatureRejected?.(this.#prevKeyInfo);
+        }
+
+        const fingerprint = adbGetPublicKeyFingerprint(key);
+        this.#prevKeyInfo = { fingerprint, name: key.name };
+        this.#onSignatureAuthentication?.(this.#prevKeyInfo);
+
+        return {
+            command: AdbCommand.Auth,
+            arg0: AdbDaemonAuthType.Signature,
+            arg1: 0,
+            payload: rsaSign(key, challenge),
+        };
+    }
+
+    async process(packet: AdbPacketData): Promise<AdbPacketData> {
+        if (packet.arg0 !== AdbDaemonAuthType.Token) {
+            throw new Error("Unsupported authentication packet");
+        }
+
+        const signature = await this.#sign(packet.payload);
+        if (signature) {
+            return signature;
+        }
+
+        let key = this.#firstKey;
+        if (!key) {
+            key = await this.#credentialManager.generateKey();
+        }
+
+        const publicKeyLength = adbGetPublicKeySize();
+        const [publicKeyBase64Length] =
+            calculateBase64EncodedLength(publicKeyLength);
+
+        const nameBuffer = key.name?.length
+            ? encodeUtf8(key.name)
+            : EmptyUint8Array;
+        const publicKeyBuffer = new Uint8Array(
+            publicKeyBase64Length +
+                (nameBuffer.length ? nameBuffer.length + 1 : 0) + // Space character + name
+                1, // Null character
+        );
+
+        adbGeneratePublicKey(key, publicKeyBuffer);
+        const fingerprint = adbGetPublicKeyFingerprint(
+            publicKeyBuffer.subarray(0, publicKeyLength),
+        );
+
+        encodeBase64(
+            publicKeyBuffer.subarray(0, publicKeyLength),
+            publicKeyBuffer,
+        );
+
+        if (nameBuffer.length) {
+            publicKeyBuffer[publicKeyBase64Length] = 0x20;
+            publicKeyBuffer.set(nameBuffer, publicKeyBase64Length + 1);
+        }
+
+        this.#onPublicKeyAuthentication?.({
+            fingerprint,
+            name: key.name,
+        });
+
+        return {
+            command: AdbCommand.Auth,
+            arg0: AdbDaemonAuthType.PublicKey,
+            arg1: 0,
+            payload: publicKeyBuffer,
+        };
+    }
+
+    async close(): Promise<undefined> {
+        await this.#iterator?.return?.();
+
+        this.#iterator = undefined;
+        this.#firstKey = undefined;
+    }
+}

package/src/daemon/auth/public-key.ts

@@ -0,0 +1,112 @@
+import { md5Digest } from "../../utils/md5.js";
+import type { SimpleRsaPrivateKey } from "../crypto.js";
+import { modInverse, setBigUint } from "../crypto.js";
+
+import type { AdbPrivateKey } from "./type.js";
+
+const ModulusLengthInBytes = 2048 / 8;
+const ModulusLengthInWords = ModulusLengthInBytes / 4;
+
+export function adbGetPublicKeySize() {
+    return 4 + 4 + ModulusLengthInBytes + ModulusLengthInBytes + 4;
+}
+
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+): Uint8Array<ArrayBuffer>;
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+    output: Uint8Array,
+): number;
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+    output?: Uint8Array,
+): Uint8Array | number {
+    // cspell: ignore: mincrypt
+    // Android 6 and earlier has its own encryption library called mincrypt
+    // This is the RSA public key format used by mincrypt:
+    // https://android.googlesource.com/platform/system/core/+/bb0c180e62703c2068a1b2c9f8ba6d634bf1553c/include/mincrypt/rsa.h#46
+    // `n0inv` and `rr` are pre-calculated to speed up RSA operations
+
+    // Android 7 switched its encryption library to BoringSSL, but still keeps the key format:
+    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#38
+    // Except when reading a key, `n0inv` and `rr` are ignored (they are still populated when generating a key):
+    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#55
+
+    // The public key is a struct (in little endian) of:
+    //
+    // [
+    //   modulusLengthInWords, // 32-bit integer, a "word" is 32-bit so it must be 2048 / 8 / 4
+    //                         // (the comment in Android source code is incorrect saying "This must be ANDROID_PUBKEY_MODULUS_SIZE")
+    //   n0inv,                // 32-bit integer, the modular inverse of (lower 32 bits of `n`)
+    //   modulus,              // `n`
+    //   rr,                   // Montgomery parameter R^2
+    //   exponent,             // 32-bit integer, must be 3 or 65537
+    // ]
+
+    let outputType: "Uint8Array" | "number";
+    const outputLength = adbGetPublicKeySize();
+    if (!output) {
+        output = new Uint8Array(outputLength);
+        outputType = "Uint8Array";
+    } else {
+        if (output.length < outputLength) {
+            throw new TypeError("output buffer is too small");
+        }
+
+        outputType = "number";
+    }
+
+    const outputView = new DataView(
+        output.buffer,
+        output.byteOffset,
+        output.length,
+    );
+    let outputOffset = 0;
+
+    // modulusLengthInWords
+    outputView.setUint32(outputOffset, ModulusLengthInWords, true);
+    outputOffset += 4;
+
+    // extract `n` from private key
+    const { n } = privateKey;
+
+    // Calculate `n0inv`
+    const n0inv = -modInverse(Number(n % 2n ** 32n), 2 ** 32);
+    outputView.setInt32(outputOffset, n0inv, true);
+    outputOffset += 4;
+
+    // Write `n` (a.k.a. `modulus`)
+    setBigUint(output, outputOffset, ModulusLengthInBytes, n, true);
+    outputOffset += ModulusLengthInBytes;
+
+    // Calculate rr = (2 ** (rsa_size)) ** 2 % n
+    const rr = 2n ** 4096n % n;
+    setBigUint(output, outputOffset, ModulusLengthInBytes, rr, true);
+    outputOffset += ModulusLengthInBytes;
+
+    // exponent
+    outputView.setUint32(outputOffset, 65537, true);
+
+    if (outputType === "Uint8Array") {
+        return output;
+    } else {
+        return outputLength;
+    }
+}
+
+// https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/services/core/java/com/android/server/adb/AdbDebuggingManager.java;l=1419;drc=61197364367c9e404c7da6900658f1b16c42d0da
+export function adbGetPublicKeyFingerprint(privateKey: AdbPrivateKey): string;
+export function adbGetPublicKeyFingerprint(publicKey: Uint8Array): string;
+export function adbGetPublicKeyFingerprint(
+    key: AdbPrivateKey | Uint8Array,
+): string {
+    if ("d" in key) {
+        key = adbGeneratePublicKey(key);
+    }
+
+    const md5 = md5Digest(key);
+    return Array.from(md5, (byte) => byte.toString(16).padStart(2, "0")).join(
+        ":",
+    );
+}

package/src/daemon/auth/type.ts

@@ -0,0 +1,5 @@
+import type { SimpleRsaPrivateKey } from "../crypto.js";
+
+export interface AdbPrivateKey extends SimpleRsaPrivateKey {
+    name?: string | undefined;
+}