@yume-chan/adb 0.0.23 → 0.0.24

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,32 @@ 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.
  */
 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 +88,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 +118,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 +128,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 +147,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 +175,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 +185,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 +315,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/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 { EMPTY_UINT8_ARRAY, 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,14 +255,21 @@ 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,
+            EMPTY_UINT8_ARRAY,
+        );
     }
 
     #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;
         }
@@ -240,22 +278,28 @@ export class AdbPacketDispatcher implements Closeable {
     }
 
     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,
+                EMPTY_UINT8_ARRAY,
+            );
             return;
         }
 
@@ -274,8 +323,8 @@ export class AdbPacketDispatcher implements Closeable {
             remoteId,
             localCreated: false,
             service,
+            availableWriteBytes,
         });
-        controller.ack(initialDelayedAckBytes);
 
         try {
             await handler(controller.socket);
@@ -286,7 +335,12 @@ export class AdbPacketDispatcher implements Closeable {
                 this.options.initialDelayedAckBytes,
             );
         } catch (e) {
-            await this.sendPacket(AdbCommand.Close, 0, remoteId);
+            await this.sendPacket(
+                AdbCommand.Close,
+                0,
+                remoteId,
+                EMPTY_UINT8_ARRAY,
+            );
         }
     }
 
@@ -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,

package/src/daemon/packet.ts

@@ -1,4 +1,4 @@
-import { ConsumableTransformStream } from "@yume-chan/stream-extra";
+import { Consumable, TransformStream } from "@yume-chan/stream-extra";
 import Struct from "@yume-chan/struct";
 
 export enum AdbCommand {
@@ -49,26 +49,33 @@ export function calculateChecksum(payload: Uint8Array): number {
     return payload.reduce((result, item) => result + item, 0);
 }
 
-export class AdbPacketSerializeStream extends ConsumableTransformStream<
-    AdbPacketInit,
-    Uint8Array
+export class AdbPacketSerializeStream extends TransformStream<
+    Consumable<AdbPacketInit>,
+    Consumable<Uint8Array>
 > {
     constructor() {
         const headerBuffer = new Uint8Array(AdbPacketHeader.size);
         super({
             transform: async (chunk, controller) => {
-                const init = chunk as AdbPacketInit & AdbPacketHeaderInit;
-                init.payloadLength = init.payload.byteLength;
+                await chunk.tryConsume(async (chunk) => {
+                    const init = chunk as AdbPacketInit & AdbPacketHeaderInit;
+                    init.payloadLength = init.payload.length;
 
-                AdbPacketHeader.serialize(init, headerBuffer);
-                await controller.enqueue(headerBuffer);
+                    await Consumable.ReadableStream.enqueue(
+                        controller,
+                        AdbPacketHeader.serialize(init, headerBuffer),
+                    );
 
-                if (init.payload.byteLength) {
-                    // USB protocol preserves packet boundaries,
-                    // so we must write payload separately as native ADB does,
-                    // otherwise the read operation on device will fail.
-                    await controller.enqueue(init.payload);
-                }
+                    if (init.payloadLength) {
+                        // USB protocol preserves packet boundaries,
+                        // so we must write payload separately as native ADB does,
+                        // otherwise the read operation on device will fail.
+                        await Consumable.ReadableStream.enqueue(
+                            controller,
+                            init.payload,
+                        );
+                    }
+                });
             },
         });
     }