@yume-chan/adb 0.0.23 → 1.0.0

package/src/commands/tcpip.ts

@@ -20,14 +20,14 @@ export interface AdbTcpIpListenAddresses {
     persistPort: number | undefined;
 }
 
-export class AdbTcpIpCommand extends AdbCommandBase {
-    #parsePort(value: string): number | undefined {
-        if (!value || value === "0") {
-            return undefined;
-        }
-        return Number.parseInt(value, 10);
+function parsePort(value: string): number | undefined {
+    if (!value || value === "0") {
+        return undefined;
     }
+    return Number.parseInt(value, 10);
+}
 
+export class AdbTcpIpCommand extends AdbCommandBase {
     async getListenAddresses(): Promise<AdbTcpIpListenAddresses> {
         const serviceListenAddresses = await this.adb.getProp(
             "service.adb.listen_addrs",
@@ -40,14 +40,14 @@ export class AdbTcpIpCommand extends AdbCommandBase {
                 serviceListenAddresses != ""
                     ? serviceListenAddresses.split(",")
                     : [],
-            servicePort: this.#parsePort(servicePort),
-            persistPort: this.#parsePort(persistPort),
+            servicePort: parsePort(servicePort),
+            persistPort: parsePort(persistPort),
         };
     }
 
     async setPort(port: number): Promise<string> {
         if (port <= 0) {
-            throw new Error(`Invalid port ${port}`);
+            throw new TypeError(`Invalid port ${port}`);
         }
 
         const output = await this.adb.createSocketAndWait(`tcpip:${port}`);

package/src/daemon/auth.ts

@@ -1,7 +1,7 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
 import type { Disposable } from "@yume-chan/event";
-import type { ValueOrPromise } from "@yume-chan/struct";
-import { EMPTY_UINT8_ARRAY } from "@yume-chan/struct";
+import { EmptyUint8Array } from "@yume-chan/struct";
 
 import {
     calculateBase64EncodedLength,
@@ -33,7 +33,7 @@ export interface AdbCredentialStore {
     /**
      * Generates and stores a RSA private key with modulus length `2048` and public exponent `65537`.
      */
-    generateKey(): ValueOrPromise<AdbPrivateKey>;
+    generateKey(): MaybePromiseLike<AdbPrivateKey>;
 
     /**
      * Synchronously or asynchronously iterates through all stored RSA private keys.
@@ -43,11 +43,13 @@ export interface AdbCredentialStore {
     iterateKeys(): AdbKeyIterable;
 }
 
-export enum AdbAuthType {
-    Token = 1,
-    Signature = 2,
-    PublicKey = 3,
-}
+export const AdbAuthType = {
+    Token: 1,
+    Signature: 2,
+    PublicKey: 3,
+} as const;
+
+export type AdbAuthType = (typeof AdbAuthType)[keyof typeof AdbAuthType];
 
 export interface AdbAuthenticator {
     /**
@@ -83,7 +85,7 @@ export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
             command: AdbCommand.Auth,
             arg0: AdbAuthType.Signature,
             arg1: 0,
-            payload: new Uint8Array(signature),
+            payload: signature,
         };
     }
 };
@@ -114,7 +116,7 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
 
     const nameBuffer = privateKey.name?.length
         ? encodeUtf8(privateKey.name)
-        : EMPTY_UINT8_ARRAY;
+        : EmptyUint8Array;
     const publicKeyBuffer = new Uint8Array(
         publicKeyBase64Length +
             (nameBuffer.length ? nameBuffer.length + 1 : 0) + // Space character + name

package/src/daemon/crypto.ts

@@ -1,7 +1,8 @@
 import {
-    getBigUint64,
-    setBigUint64,
-} from "@yume-chan/dataview-bigint-polyfill/esm/fallback.js";
+    getUint64BigEndian,
+    setInt64BigEndian,
+    setInt64LittleEndian,
+} from "@yume-chan/no-data-view";
 
 /**
  * Gets the `BigInt` value at the specified byte offset and length from the start of the view. There is
@@ -11,7 +12,7 @@ import {
  * @param byteOffset The place in the buffer at which the value should be retrieved.
  */
 export function getBigUint(
-    dataView: DataView,
+    array: Uint8Array,
     byteOffset: number,
     length: number,
 ): bigint {
@@ -22,8 +23,8 @@ export function getBigUint(
 
     for (let i = byteOffset; i < byteOffset + length; i += 8) {
         result <<= 64n;
-        const value = getBigUint64(dataView, i, false);
-        result += value;
+        const value = getUint64BigEndian(array, i);
+        result |= value;
     }
 
     return result;
@@ -32,40 +33,34 @@ export function getBigUint(
 /**
  * Stores an arbitrary-precision positive `BigInt` value at the specified byte offset from the start of the view.
  * @param byteOffset The place in the buffer at which the value should be set.
+ * @param length The number of bytes to set.
  * @param value The value to set.
  * @param littleEndian If `false` or `undefined`, a big-endian value should be written,
  * otherwise a little-endian value should be written.
  */
+
+// eslint-disable-next-line @typescript-eslint/max-params
 export function setBigUint(
-    dataView: DataView,
+    array: Uint8Array,
     byteOffset: number,
+    length: number,
     value: bigint,
     littleEndian?: boolean,
 ) {
-    const start = byteOffset;
-
     if (littleEndian) {
         while (value > 0n) {
-            setBigUint64(dataView, byteOffset, value, true);
+            setInt64LittleEndian(array, byteOffset, value);
             byteOffset += 8;
             value >>= 64n;
         }
     } else {
-        // Because we don't know how long (in bits) the `value` is,
-        // Convert it to an array of `uint64` first.
-        const uint64Array: bigint[] = [];
+        let position = byteOffset + length - 8;
         while (value > 0n) {
-            uint64Array.push(BigInt.asUintN(64, value));
+            setInt64BigEndian(array, position, value);
+            position -= 8;
             value >>= 64n;
         }
-
-        for (let i = uint64Array.length - 1; i >= 0; i -= 1) {
-            setBigUint64(dataView, byteOffset, uint64Array[i]!, false);
-            byteOffset += 8;
-        }
     }
-
-    return byteOffset - start;
 }
 
 // These values are correct only if
@@ -95,17 +90,26 @@ const RsaPrivateKeyDOffset = 303;
 const RsaPrivateKeyDLength = 2048 / 8;
 
 export function rsaParsePrivateKey(key: Uint8Array): [n: bigint, d: bigint] {
-    const view = new DataView(key.buffer, key.byteOffset, key.byteLength);
-    const n = getBigUint(view, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
-    const d = getBigUint(view, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
+    const n = getBigUint(key, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
+    const d = getBigUint(key, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
     return [n, d];
 }
 
+function nonNegativeMod(m: number, d: number) {
+    const r = m % d;
+    if (r > 0) {
+        return r;
+    }
+    return r + (d > 0 ? d : -d);
+}
+
+// https://en.wikipedia.org/wiki/Modular_multiplicative_inverse
+// Solve for the smallest positive `x` in the equation `a * x ≡ 1 (mod m)`,
+// or in other words, `a * x % m = 1`
 // Taken from https://stackoverflow.com/a/51562038
-// I can't understand, but it does work
 // Only used with numbers smaller than 2^32 so doesn't need BigInt
 export function modInverse(a: number, m: number) {
-    a = ((a % m) + m) % m;
+    a = nonNegativeMod(a, m);
     if (!a || m < 2) {
         return NaN; // invalid input
     }
@@ -116,6 +120,7 @@ export function modInverse(a: number, m: number) {
         [a, b] = [b, a % b];
         s.push({ a, b });
     }
+    /* istanbul ignore next */
     if (a !== 1) {
         return NaN; // inverse does not exists
     }
@@ -125,11 +130,14 @@ export function modInverse(a: number, m: number) {
     for (let i = s.length - 2; i >= 0; i -= 1) {
         [x, y] = [y, x - y * Math.floor(s[i]!.a / s[i]!.b)];
     }
-    return ((y % m) + m) % m;
+    return nonNegativeMod(y, m);
 }
 
+const ModulusLengthInBytes = 2048 / 8;
+const ModulusLengthInWords = ModulusLengthInBytes / 4;
+
 export function adbGetPublicKeySize() {
-    return 4 + 4 + 2048 / 8 + 2048 / 8 + 4;
+    return 4 + 4 + ModulusLengthInBytes + ModulusLengthInBytes + 4;
 }
 
 export function adbGeneratePublicKey(privateKey: Uint8Array): Uint8Array;
@@ -141,22 +149,27 @@ export function adbGeneratePublicKey(
     privateKey: Uint8Array,
     output?: Uint8Array,
 ): Uint8Array | number {
-    // Android has its own public key generation algorithm
-    // See https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#111
-
-    // The public key is an array of
+    // 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
-    //                         // Actually the comment in Android source code was wrong
-    //   n0inv,                // 32-bit integer, the modular inverse of (low 32 bits of n)
-    //   modulus,              // n
+    //                         // (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 65537
+    //   exponent,             // 32-bit integer, must be 3 or 65537
     // ]
-    //
-    // (All in little endian)
-    // See https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#38
 
     let outputType: "Uint8Array" | "number";
     const outputLength = adbGetPublicKeySize();
@@ -164,8 +177,8 @@ export function adbGeneratePublicKey(
         output = new Uint8Array(outputLength);
         outputType = "Uint8Array";
     } else {
-        if (output.byteLength < outputLength) {
-            throw new Error("output buffer is too small");
+        if (output.length < outputLength) {
+            throw new TypeError("output buffer is too small");
         }
 
         outputType = "number";
@@ -174,31 +187,30 @@ export function adbGeneratePublicKey(
     const outputView = new DataView(
         output.buffer,
         output.byteOffset,
-        output.byteLength,
+        output.length,
     );
     let outputOffset = 0;
 
     // modulusLengthInWords
-    outputView.setUint32(outputOffset, 2048 / 8 / 4, true);
+    outputView.setUint32(outputOffset, ModulusLengthInWords, true);
     outputOffset += 4;
 
     // extract `n` from private key
     const [n] = rsaParsePrivateKey(privateKey);
 
     // Calculate `n0inv`
-    // Don't know why need to multiply by -1
-    // Didn't exist in Android codebase
-    const n0inv = modInverse(-Number(BigInt.asUintN(32, n)), 2 ** 32);
-    outputView.setUint32(outputOffset, n0inv, true);
+    const n0inv = -modInverse(Number(n % 2n ** 32n), 2 ** 32);
+    outputView.setInt32(outputOffset, n0inv, true);
     outputOffset += 4;
 
-    // Write n
-    setBigUint(outputView, outputOffset, n, true);
-    outputOffset += 256;
+    // Write `n` (a.k.a. `modulus`)
+    setBigUint(output, outputOffset, ModulusLengthInBytes, n, true);
+    outputOffset += ModulusLengthInBytes;
 
-    // Calculate rr = (2^(rsa_size)) ^ 2 mod n
+    // Calculate rr = (2 ** (rsa_size)) ** 2 % n
     const rr = 2n ** 4096n % n;
-    outputOffset += setBigUint(outputView, outputOffset, rr, true);
+    setBigUint(output, outputOffset, ModulusLengthInBytes, rr, true);
+    outputOffset += ModulusLengthInBytes;
 
     // exponent
     outputView.setUint32(outputOffset, 65537, true);
@@ -305,12 +317,11 @@ export function rsaSign(privateKey: Uint8Array, data: Uint8Array): Uint8Array {
 
     // Encryption
     // signature = padded ** d % n
-    const view = new DataView(padded.buffer);
-    const signature = powMod(getBigUint(view, 0, view.byteLength), d, n);
+    const signature = powMod(getBigUint(padded, 0, padded.length), d, n);
 
     // `padded` is not used anymore,
     // re-use the buffer to store the result
-    setBigUint(view, 0, signature, false);
+    setBigUint(padded, 0, padded.length, signature, false);
 
     return padded;
 }

package/src/daemon/device.ts

@@ -1,5 +1,5 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import type { Consumable, ReadableWritablePair } from "@yume-chan/stream-extra";
-import type { ValueOrPromise } from "@yume-chan/struct";
 
 import type { AdbPacketData, AdbPacketInit } from "./packet.js";
 
@@ -8,7 +8,7 @@ export interface AdbDaemonDevice {
 
     readonly name: string | undefined;
 
-    connect(): ValueOrPromise<
+    connect(): MaybePromiseLike<
         ReadableWritablePair<AdbPacketData, Consumable<AdbPacketInit>>
     >;
 }

package/src/daemon/dispatcher.ts

@@ -3,47 +3,78 @@ import {
     PromiseResolver,
     delay,
 } from "@yume-chan/async";
+import {
+    getUint32LittleEndian,
+    setUint32LittleEndian,
+} from "@yume-chan/no-data-view";
 import type {
-    Consumable,
     ReadableWritablePair,
     WritableStreamDefaultWriter,
 } from "@yume-chan/stream-extra";
 import {
     AbortController,
-    ConsumableWritableStream,
+    Consumable,
     WritableStream,
 } from "@yume-chan/stream-extra";
-import { EMPTY_UINT8_ARRAY, NumberFieldType } from "@yume-chan/struct";
+import { EmptyUint8Array, decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
 
 import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
-import { decodeUtf8, encodeUtf8 } from "../utils/index.js";
 
 import type { AdbPacketData, AdbPacketInit } from "./packet.js";
 import { AdbCommand, calculateChecksum } from "./packet.js";
 import { AdbDaemonSocketController } from "./socket.js";
 
 export interface AdbPacketDispatcherOptions {
+    /**
+     * From Android 9.0, ADB stopped checking the checksum in packet header to improve performance.
+     *
+     * The value should be inferred from the device's ADB protocol version.
+     */
     calculateChecksum: boolean;
+
     /**
-     * Before Android 9.0, ADB uses `char*` to parse service string,
+     * Before Android 9.0, ADB uses `char*` to parse service strings,
      * thus requires a null character to terminate.
      *
-     * Usually it should have the same value as `calculateChecksum`.
+     * The value should be inferred from the device's ADB protocol version.
+     * Usually it should have the same value as `calculateChecksum`, since they both changed
+     * in Android 9.0.
      */
     appendNullToServiceString: boolean;
+
     maxPayloadSize: number;
+
     /**
-     * The number of bytes the device can send before receiving an ack packet.
+     * Whether to keep the `connection` open (don't call `writable.close` and `readable.cancel`)
+     * when `AdbPacketDispatcher.close` is called.
+     *
+     * @default false
+     */
+    preserveConnection?: boolean | undefined;
 
-     * Set to 0 or any negative value to disable delayed ack.
-     * Otherwise the value must be in the range of unsigned 32-bit integer.
+    /**
+     * The number of bytes the device can send before receiving an ack packet.
+     * Using delayed ack can improve the throughput,
+     * especially when the device is connected over Wi-Fi (so the latency is higher).
+     *
+     * This must be the negotiated value between the client and device. If the device enabled
+     * delayed ack but the client didn't, the device will throw an error when the client sends
+     * the first `WRTE` packet. And vice versa.
      */
     initialDelayedAckBytes: number;
+
     /**
-     * Whether to preserve the connection open after the `AdbPacketDispatcher` is closed.
+     * When set, the dispatcher will throw an error when
+     * one of the socket readable stalls for this amount of milliseconds.
+     *
+     * Because ADB is a multiplexed protocol, blocking one socket will also block all other sockets.
+     * It's important to always read from all sockets to prevent stalling.
+     *
+     * This option is helpful to detect bugs in the client code.
+     *
+     * @default false
      */
-    preserveConnection?: boolean | undefined;
-    debugSlowRead?: boolean | undefined;
+    readTimeLimit?: number | undefined;
 }
 
 interface SocketOpenResult {
@@ -187,14 +218,14 @@ export class AdbPacketDispatcher implements Closeable {
     #handleOkay(packet: AdbPacketData) {
         let ackBytes: number;
         if (this.options.initialDelayedAckBytes !== 0) {
-            if (packet.payload.byteLength !== 4) {
+            if (packet.payload.length !== 4) {
                 throw new Error(
                     "Invalid OKAY packet. Payload size should be 4",
                 );
             }
-            ackBytes = NumberFieldType.Uint32.deserialize(packet.payload, true);
+            ackBytes = getUint32LittleEndian(packet.payload, 0);
         } else {
-            if (packet.payload.byteLength !== 0) {
+            if (packet.payload.length !== 0) {
                 throw new Error(
                     "Invalid OKAY packet. Payload size should be 0",
                 );
@@ -224,38 +255,51 @@ export class AdbPacketDispatcher implements Closeable {
 
         // Maybe the device is responding to a packet of last connection
         // Tell the device to close the socket
-        void this.sendPacket(AdbCommand.Close, packet.arg1, packet.arg0);
+        void this.sendPacket(
+            AdbCommand.Close,
+            packet.arg1,
+            packet.arg0,
+            EmptyUint8Array,
+        );
     }
 
     #sendOkay(localId: number, remoteId: number, ackBytes: number) {
         let payload: Uint8Array;
         if (this.options.initialDelayedAckBytes !== 0) {
+            // TODO: try reusing this buffer to reduce memory allocation
+            // However, that requires blocking reentrance of `sendOkay`, which might be more expensive
             payload = new Uint8Array(4);
-            new DataView(payload.buffer).setUint32(0, ackBytes, true);
+            setUint32LittleEndian(payload, 0, ackBytes);
         } else {
-            payload = EMPTY_UINT8_ARRAY;
+            payload = EmptyUint8Array;
         }
 
         return this.sendPacket(AdbCommand.Okay, localId, remoteId, payload);
     }
 
     async #handleOpen(packet: AdbPacketData) {
-        // `AsyncOperationManager` doesn't support skipping IDs
-        // Use `add` + `resolve` to simulate this behavior
+        // Allocate a local ID for the socket from `#initializers`.
+        // `AsyncOperationManager` doesn't directly support returning the next ID,
+        // so use `add` + `resolve` to simulate this
         const [localId] = this.#initializers.add<number>();
         this.#initializers.resolve(localId, undefined);
 
         const remoteId = packet.arg0;
-        let initialDelayedAckBytes = packet.arg1;
-        const service = decodeUtf8(packet.payload);
+        let availableWriteBytes = packet.arg1;
+        let service = decodeUtf8(packet.payload);
+        // ADB Daemon still adds a null character to the service string
+        if (service.endsWith("\0")) {
+            service = service.substring(0, service.length - 1);
+        }
 
+        // Check remote delayed ack enablement is consistent with local
         if (this.options.initialDelayedAckBytes === 0) {
-            if (initialDelayedAckBytes !== 0) {
+            if (availableWriteBytes !== 0) {
                 throw new Error("Invalid OPEN packet. arg1 should be 0");
             }
-            initialDelayedAckBytes = Infinity;
+            availableWriteBytes = Infinity;
         } else {
-            if (initialDelayedAckBytes === 0) {
+            if (availableWriteBytes === 0) {
                 throw new Error(
                     "Invalid OPEN packet. arg1 should be greater than 0",
                 );
@@ -264,7 +308,12 @@ export class AdbPacketDispatcher implements Closeable {
 
         const handler = this.#incomingSocketHandlers.get(service);
         if (!handler) {
-            await this.sendPacket(AdbCommand.Close, 0, remoteId);
+            await this.sendPacket(
+                AdbCommand.Close,
+                0,
+                remoteId,
+                EmptyUint8Array,
+            );
             return;
         }
 
@@ -274,8 +323,8 @@ export class AdbPacketDispatcher implements Closeable {
             remoteId,
             localCreated: false,
             service,
+            availableWriteBytes,
         });
-        controller.ack(initialDelayedAckBytes);
 
         try {
             await handler(controller.socket);
@@ -285,8 +334,13 @@ export class AdbPacketDispatcher implements Closeable {
                 remoteId,
                 this.options.initialDelayedAckBytes,
             );
-        } catch (e) {
-            await this.sendPacket(AdbCommand.Close, 0, remoteId);
+        } catch {
+            await this.sendPacket(
+                AdbCommand.Close,
+                0,
+                remoteId,
+                EmptyUint8Array,
+            );
         }
     }
 
@@ -297,14 +351,8 @@ export class AdbPacketDispatcher implements Closeable {
         }
 
         let handled = false;
-        await Promise.race([
-            delay(5000).then(() => {
-                if (this.options.debugSlowRead && !handled) {
-                    throw new Error(
-                        `packet for \`${socket.service}\` not handled in 5 seconds`,
-                    );
-                }
-            }),
+
+        const promises: Promise<void>[] = [
             (async () => {
                 await socket.enqueue(packet.payload);
                 await this.#sendOkay(
@@ -314,9 +362,22 @@ export class AdbPacketDispatcher implements Closeable {
                 );
                 handled = true;
             })(),
-        ]);
+        ];
+
+        if (this.options.readTimeLimit) {
+            promises.push(
+                (async () => {
+                    await delay(this.options.readTimeLimit!);
+                    if (!handled) {
+                        throw new Error(
+                            `readable of \`${socket.service}\` has stalled for ${this.options.readTimeLimit} milliseconds`,
+                        );
+                    }
+                })(),
+            );
+        }
 
-        return;
+        await Promise.race(promises);
     }
 
     async createSocket(service: string): Promise<AdbSocket> {
@@ -341,8 +402,8 @@ export class AdbPacketDispatcher implements Closeable {
             remoteId,
             localCreated: true,
             service,
+            availableWriteBytes,
         });
-        controller.ack(availableWriteBytes);
         this.#sockets.set(localId, controller);
 
         return controller.socket;
@@ -364,17 +425,18 @@ export class AdbPacketDispatcher implements Closeable {
         command: AdbCommand,
         arg0: number,
         arg1: number,
-        payload: string | Uint8Array = EMPTY_UINT8_ARRAY,
+        // PERF: It's slightly faster to not use default parameter values
+        payload: string | Uint8Array,
     ): Promise<void> {
         if (typeof payload === "string") {
             payload = encodeUtf8(payload);
         }
 
-        if (payload.byteLength > this.options.maxPayloadSize) {
-            throw new Error("payload too large");
+        if (payload.length > this.options.maxPayloadSize) {
+            throw new TypeError("payload too large");
         }
 
-        await ConsumableWritableStream.write(this.#writer, {
+        await Consumable.WritableStream.write(this.#writer, {
             command,
             arg0,
             arg1,