@yume-chan/adb 0.0.11 → 0.0.14

package/src/crypto.ts

@@ -5,48 +5,60 @@ const BigInt1 = BigInt(1);
 const BigInt2 = BigInt(2);
 const BigInt64 = BigInt(64);
 
-export function getBig(
-    array: Uint8Array,
-    offset = 0,
-    length = array.byteLength - offset
-): bigint {
-    const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
-
+/**
+ * Gets the `BigInt` value at the specified byte offset and length from the start of the view. There is
+ * no alignment constraint; multi-byte values may be fetched from any offset.
+ *
+ * Only supports Big-Endian, because that's what ADB uses.
+ * @param byteOffset The place in the buffer at which the value should be retrieved.
+ */
+export function getBigUint(dataView: DataView, byteOffset: number, length: number): bigint {
     let result = BigInt0;
 
     // Currently `length` must be a multiplication of 8
     // Support for arbitrary length can be easily added
 
-    for (let i = offset; i < offset + length; i += 8) {
+    for (let i = byteOffset; i < byteOffset + length; i += 8) {
         result <<= BigInt64;
-        const value = getBigUint64(view, i, false);
+        const value = getBigUint64(dataView, i, false);
         result += value;
     }
 
     return result;
 }
 
-export function setBig(buffer: ArrayBuffer, value: bigint, offset: number = 0) {
-    const uint64Array: bigint[] = [];
-    while (value > BigInt0) {
-        uint64Array.push(BigInt.asUintN(64, value));
-        value >>= BigInt64;
-    }
+/**
+ * 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 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, byteOffset: number, value: bigint, littleEndian?: boolean) {
+    const start = byteOffset;
+
+    if (littleEndian) {
+        while (value > BigInt0) {
+            setBigUint64(dataView, byteOffset, value, true);
+            byteOffset += 8;
+            value >>= BigInt64;
+        }
+    } else {
+        // Because we don't know how long (in bits) the `value` is,
+        // Convert it to an array of `uint64` first.
+        const uint64Array: bigint[] = [];
+        while (value > BigInt0) {
+            uint64Array.push(BigInt.asUintN(64, value));
+            value >>= BigInt64;
+        }
 
-    const view = new DataView(buffer);
-    for (let i = uint64Array.length - 1; i >= 0; i -= 1) {
-        setBigUint64(view, offset, uint64Array[i]!, false);
-        offset += 8;
+        for (let i = uint64Array.length - 1; i >= 0; i -= 1) {
+            setBigUint64(dataView, byteOffset, uint64Array[i]!, false);
+            byteOffset += 8;
+        }
     }
-}
 
-export function setBigLE(array: Uint8Array, value: bigint, offset = 0) {
-    const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
-    while (value > BigInt0) {
-        setBigUint64(view, offset, value, true);
-        offset += 8;
-        value >>= BigInt64;
-    }
+    return byteOffset - start;
 }
 
 // These values are correct only if
@@ -76,9 +88,9 @@ const RsaPrivateKeyDOffset = 303;
 const RsaPrivateKeyDLength = 2048 / 8;
 
 export function parsePrivateKey(key: Uint8Array): [n: bigint, d: bigint] {
-    let n = getBig(key, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
-    let d = getBig(key, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
-
+    const view = new DataView(key.buffer, key.byteOffset, key.byteLength);
+    const n = getBigUint(view, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
+    const d = getBigUint(view, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
     return [n, d];
 }
 
@@ -132,7 +144,7 @@ export function calculatePublicKey(
     // [
     //   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 (lower 32 bits of) n
+    //   n0inv,                // 32-bit integer, the modular inverse of (low 32 bits of n)
     //   modulus,              // n
     //   rr,                   // Montgomery parameter R^2
     //   exponent,             // 32-bit integer, must be 65537
@@ -172,13 +184,12 @@ export function calculatePublicKey(
     outputOffset += 4;
 
     // Write n
-    setBigLE(output, n, outputOffset);
+    setBigUint(outputView, outputOffset, n, true);
     outputOffset += 256;
 
     // Calculate rr = (2^(rsa_size)) ^ 2 mod n
     let rr = BigInt(2) ** BigInt(4096) % n;
-    setBigLE(output, rr, outputOffset);
-    outputOffset += 256;
+    outputOffset += setBigUint(outputView, outputOffset, rr, true);
 
     // exponent
     outputView.setUint32(outputOffset, 65537, true);
@@ -218,21 +229,21 @@ export function powMod(base: bigint, exponent: bigint, modulus: bigint): bigint
     return r;
 }
 
-export const Sha1DigestLength = 20;
+export const SHA1_DIGEST_LENGTH = 20;
 
-export const Asn1Sequence = 0x30;
-export const Asn1OctetString = 0x04;
-export const Asn1Null = 0x05;
-export const Asn1Oid = 0x06;
+export const ASN1_SEQUENCE = 0x30;
+export const ASN1_OCTET_STRING = 0x04;
+export const ASN1_NULL = 0x05;
+export const ASN1_OID = 0x06;
 
 // PKCS#1 SHA-1 hash digest info
-export const Sha1DigestInfo = new Uint8Array([
-    Asn1Sequence, 0x0d + Sha1DigestLength,
-    Asn1Sequence, 0x09,
+export const SHA1_DIGEST_INFO = new Uint8Array([
+    ASN1_SEQUENCE, 0x0d + SHA1_DIGEST_LENGTH,
+    ASN1_SEQUENCE, 0x09,
     // SHA-1 (1 3 14 3 2 26)
-    Asn1Oid, 0x05, 1 * 40 + 3, 14, 3, 2, 26,
-    Asn1Null, 0x00,
-    Asn1OctetString, Sha1DigestLength
+    ASN1_OID, 0x05, 1 * 40 + 3, 14, 3, 2, 26,
+    ASN1_NULL, 0x00,
+    ASN1_OCTET_STRING, SHA1_DIGEST_LENGTH
 ]);
 
 // SubtleCrypto.sign() will hash the given data and sign the hash
@@ -241,7 +252,7 @@ export const Sha1DigestInfo = new Uint8Array([
 // encrypt the given data with its private key)
 // However SubtileCrypto.encrypt() doesn't accept 'RSASSA-PKCS1-v1_5' algorithm
 // So we need to implement the encryption by ourself
-export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
+export function sign(privateKey: Uint8Array, data: Uint8Array): Uint8Array {
     const [n, d] = parsePrivateKey(privateKey);
 
     // PKCS#1 padding
@@ -254,7 +265,7 @@ export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
     padded[index] = 1;
     index += 1;
 
-    const fillLength = padded.length - Sha1DigestInfo.length - data.length - 1;
+    const fillLength = padded.length - SHA1_DIGEST_INFO.length - data.length - 1;
     while (index < fillLength) {
         padded[index] = 0xff;
         index += 1;
@@ -263,18 +274,23 @@ export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
     padded[index] = 0;
     index += 1;
 
-    padded.set(Sha1DigestInfo, index);
-    index += Sha1DigestInfo.length;
+    padded.set(SHA1_DIGEST_INFO, index);
+    index += SHA1_DIGEST_INFO.length;
 
     padded.set(data, index);
 
     // Encryption
     // signature = padded ** d % n
-    let signature = powMod(getBig(padded), d, n);
-
-    // Put into an ArrayBuffer
-    const result = new ArrayBuffer(256);
-    setBig(result, signature);
-
-    return result;
+    const view = new DataView(padded.buffer);
+    const signature = powMod(
+        getBigUint(view, 0, view.byteLength),
+        d,
+        n
+    );
+
+    // `padded` is not used anymore,
+    // re-use the buffer to store the result
+    setBigUint(view, 0, signature, false);
+
+    return padded;
 }

package/src/features.ts

@@ -1,5 +1,9 @@
+// The order follows
+// https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
 export enum AdbFeatures {
-    StatV2 = 'stat_v2',
+    ShellV2 = "shell_v2",
     Cmd = 'cmd',
-    ShellV2 = "shell_v2"
+    StatV2 = 'stat_v2',
+    ListV2 = 'ls_v2',
+    FixedPushMkdir = 'fixed_push_mkdir',
 }

package/src/packet.ts

@@ -10,7 +10,7 @@ export enum AdbCommand {
     Write = 0x45545257,   // 'WRTE'
 }
 
-const AdbPacketHeader =
+export const AdbPacketHeader =
     new Struct({ littleEndian: true })
         .uint32('command')
         .uint32('arg0')
@@ -19,6 +19,8 @@ const AdbPacketHeader =
         .uint32('checksum')
         .int32('magic');
 
+export type AdbPacketHeader = typeof AdbPacketHeader['TDeserializeResult'];
+
 type AdbPacketHeaderInit = typeof AdbPacketHeader['TInit'];
 
 export const AdbPacket =
@@ -28,15 +30,24 @@ export const AdbPacket =
 
 export type AdbPacket = typeof AdbPacket['TDeserializeResult'];
 
-// All the useful fields
-export type AdbPacketCore = Omit<typeof AdbPacket['TInit'], 'checksum' | 'magic'>;
+/**
+ * `AdbPacketData` contains all the useful fields of `AdbPacket`.
+ *
+ * `AdbBackend#connect` will return a `ReadableStream<AdbPacketData>`,
+ * so each backend can encode `AdbPacket` in different ways.
+ *
+ * `AdbBackend#connect` will return a `WritableStream<AdbPacketInit>`,
+ * however, `AdbPacketDispatcher` will transform `AdbPacketData` to `AdbPacketInit` for you,
+ * so `AdbSocket#writable#write` only needs `AdbPacketData`.
+ */
+export type AdbPacketData = Omit<typeof AdbPacket['TInit'], 'checksum' | 'magic'>;
 
 // All fields except `magic`, which can be calculated in `AdbPacketSerializeStream`
 export type AdbPacketInit = Omit<typeof AdbPacket['TInit'], 'magic'>;
 
 export function calculateChecksum(payload: Uint8Array): number;
-export function calculateChecksum(init: AdbPacketCore): AdbPacketInit;
-export function calculateChecksum(payload: Uint8Array | AdbPacketCore): number | AdbPacketInit {
+export function calculateChecksum(init: AdbPacketData): AdbPacketInit;
+export function calculateChecksum(payload: Uint8Array | AdbPacketData): number | AdbPacketInit {
     if (payload instanceof Uint8Array) {
         return payload.reduce((result, item) => result + item, 0);
     } else {
@@ -49,7 +60,7 @@ export class AdbPacketSerializeStream extends TransformStream<AdbPacketInit, Uin
     public constructor() {
         super({
             transform: async (init, controller) => {
-                // This syntax is ugly, but I don't want to create an new object.
+                // This syntax is ugly, but I don't want to create a new object.
                 (init as unknown as AdbPacketHeaderInit).magic = init.command ^ 0xFFFFFFFF;
                 (init as unknown as AdbPacketHeaderInit).payloadLength = init.payload.byteLength;
 

package/src/socket/dispatcher.ts

@@ -1,97 +1,113 @@
 import { AsyncOperationManager, PromiseResolver } from '@yume-chan/async';
-import { AutoDisposable, EventEmitter } from '@yume-chan/event';
-import { AdbCommand, calculateChecksum, type AdbPacketCore, type AdbPacketInit } from '../packet.js';
+import type { RemoveEventListener } from '@yume-chan/event';
+import type { ValueOrPromise } from "@yume-chan/struct";
+
+import { AdbCommand, calculateChecksum, type AdbPacketData, type AdbPacketInit } from '../packet.js';
 import { AbortController, WritableStream, WritableStreamDefaultWriter, type ReadableWritablePair } from '../stream/index.js';
 import { decodeUtf8, encodeUtf8 } from '../utils/index.js';
-import { AdbSocket } from './socket.js';
+import { AdbSocket, AdbSocketController } from './socket.js';
 
-export interface AdbIncomingSocketEventArgs {
-    handled: boolean;
+const EmptyUint8Array = new Uint8Array(0);
 
-    packet: AdbPacketCore;
+export interface AdbPacketDispatcherOptions {
+    calculateChecksum: boolean;
+    /**
+     * Before Android 9.0, ADB uses `char*` to parse service string,
+     * thus requires a null character to terminate.
+     *
+     * Usually it should have the same value as `calculateChecksum`.
+     */
+    appendNullToServiceString: boolean;
+    maxPayloadSize: number;
+}
 
-    serviceString: string;
+export type AdbIncomingSocketHandler = (socket: AdbSocket) => ValueOrPromise<boolean>;
 
-    socket: AdbSocket;
+export interface Closeable {
+    close(): ValueOrPromise<void>;
 }
 
-const EmptyUint8Array = new Uint8Array(0);
-
-export class AdbPacketDispatcher extends AutoDisposable {
+/**
+ * The dispatcher is the "dumb" part of the connection handling logic.
+ *
+ * Except some options to change some minor behaviors,
+ * its only job is forwarding packets between authenticated underlying streams
+ * and abstracted socket objects.
+ *
+ * The `Adb` class is responsible for doing the authentication,
+ * negotiating the options, and has shortcuts to high-level services.
+ */
+export class AdbPacketDispatcher implements Closeable {
     // ADB socket id starts from 1
     // (0 means open failed)
     private readonly initializers = new AsyncOperationManager(1);
-    private readonly sockets = new Map<number, AdbSocket>();
+    private readonly sockets = new Map<number, AdbSocketController>();
 
     private _writer!: WritableStreamDefaultWriter<AdbPacketInit>;
 
-    public maxPayloadSize = 0;
-    public calculateChecksum = true;
-    public appendNullToServiceString = true;
+    public readonly options: AdbPacketDispatcherOptions;
 
     private _disconnected = new PromiseResolver<void>();
     public get disconnected() { return this._disconnected.promise; }
 
-    private readonly incomingSocketEvent = this.addDisposable(new EventEmitter<AdbIncomingSocketEventArgs>());
-    public get onIncomingSocket() { return this.incomingSocketEvent.event; }
-
-    private readonly errorEvent = this.addDisposable(new EventEmitter<Error>());
-    public get onError() { return this.errorEvent.event; }
+    private _incomingSocketHandlers: Set<AdbIncomingSocketHandler> = new Set();
 
     private _abortController = new AbortController();
 
     public constructor(
-        connection: ReadableWritablePair<AdbPacketCore, AdbPacketInit>,
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
+        options: AdbPacketDispatcherOptions
     ) {
-        super();
+        this.options = options;
 
         connection.readable
             .pipeTo(new WritableStream({
                 write: async (packet) => {
-                    try {
-                        switch (packet.command) {
-                            case AdbCommand.OK:
-                                this.handleOk(packet);
-                                return;
-                            case AdbCommand.Close:
-                                await this.handleClose(packet);
-                                return;
-                            case AdbCommand.Write:
-                                if (this.sockets.has(packet.arg1)) {
-                                    await this.sockets.get(packet.arg1)!.enqueue(packet.payload);
-                                    await this.sendPacket(AdbCommand.OK, packet.arg1, packet.arg0);
-                                }
-
-                                // Maybe the device is responding to a packet of last connection
-                                // Just ignore it
-                                return;
-                            case AdbCommand.Open:
-                                await this.handleOpen(packet);
-                                return;
-                        }
-                    } catch (e) {
-                        this.errorEvent.fire(e as Error);
-
-                        // Throw error here will stop the pipe
-                        // But won't close `readable` because of `preventCancel: true`
-                        throw e;
+                    switch (packet.command) {
+                        case AdbCommand.OK:
+                            this.handleOk(packet);
+                            break;
+                        case AdbCommand.Close:
+                            await this.handleClose(packet);
+                            break;
+                        case AdbCommand.Write:
+                            if (this.sockets.has(packet.arg1)) {
+                                await this.sockets.get(packet.arg1)!.enqueue(packet.payload);
+                                await this.sendPacket(AdbCommand.OK, packet.arg1, packet.arg0);
+                                break;
+                            }
+                            throw new Error(`Unknown local socket id: ${packet.arg1}`);
+                        case AdbCommand.Open:
+                            await this.handleOpen(packet);
+                            break;
+                        default:
+                            // Junk data may only appear in the authentication phase,
+                            // since the dispatcher only works after authentication,
+                            // all packets should have a valid command.
+                            // (although it's possible that Adb added new commands in the future)
+                            throw new Error(`Unknown command: ${packet.command.toString(16)}`);
                     }
                 },
             }), {
+                // There are multiple reasons for the pipe to stop,
+                // including device disconnection, protocol error, or user abort,
+                // if the underlying streams are still open,
+                // it's still possible to create another ADB connection.
+                // So don't close `readable` here.
                 preventCancel: false,
                 signal: this._abortController.signal,
             })
             .then(() => {
                 this.dispose();
-            }, () => {
-                // TODO: AdbPacketDispatcher: reject `_disconnected` when pipe errored?
+            }, (e) => {
+                this._disconnected.reject(e);
                 this.dispose();
             });
 
         this._writer = connection.writable.getWriter();
     }
 
-    private handleOk(packet: AdbPacketCore) {
+    private handleOk(packet: AdbPacketData) {
         if (this.initializers.resolve(packet.arg1, packet.arg0)) {
             // Device successfully created the socket
             return;
@@ -109,7 +125,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         this.sendPacket(AdbCommand.Close, packet.arg1, packet.arg0);
     }
 
-    private async handleClose(packet: AdbPacketCore) {
+    private async handleClose(packet: AdbPacketData) {
         // From https://android.googlesource.com/platform/packages/modules/adb/+/65d18e2c1cc48b585811954892311b28a4c3d188/adb.cpp#459
         /* According to protocol.txt, p->msg.arg0 might be 0 to indicate
          * a failed OPEN only. However, due to a bug in previous ADB
@@ -117,13 +133,18 @@ export class AdbPacketDispatcher extends AutoDisposable {
          * CLOSE() operations.
          */
 
-        // So don't return if `reject` didn't find a pending socket
+        // If the socket is still pending
         if (packet.arg0 === 0 &&
             this.initializers.reject(packet.arg1, new Error('Socket open failed'))) {
             // Device failed to create the socket
+            // (unknown service string, failed to execute command, etc.)
+            // it doesn't break the connection,
+            // so only reject the socket creation promise,
+            // don't throw an error here.
             return;
         }
 
+        // Ignore `arg0` and search for the socket
         const socket = this.sockets.get(packet.arg1);
         if (socket) {
             // The device want to close the socket
@@ -135,11 +156,21 @@ export class AdbPacketDispatcher extends AutoDisposable {
             return;
         }
 
-        // Maybe the device is responding to a packet of last connection
-        // Just ignore it
+        // TODO: adb: is double closing an socket a catastrophic error?
+        // If the client sends two `CLSE` packets for one socket,
+        // the device may also respond with two `CLSE` packets.
     }
 
-    private async handleOpen(packet: AdbPacketCore) {
+    public addIncomingSocketHandler(handler: AdbIncomingSocketHandler): RemoveEventListener {
+        this._incomingSocketHandlers.add(handler);
+        const remove = () => {
+            this._incomingSocketHandlers.delete(handler);
+        };
+        remove.dispose = remove;
+        return remove;
+    }
+
+    private async handleOpen(packet: AdbPacketData) {
         // AsyncOperationManager doesn't support get and skip an ID
         // Use `add` + `resolve` to simulate this behavior
         const [localId] = this.initializers.add<number>();
@@ -148,7 +179,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         const remoteId = packet.arg0;
         const serviceString = decodeUtf8(packet.payload);
 
-        const socket = new AdbSocket({
+        const controller = new AdbSocketController({
             dispatcher: this,
             localId,
             remoteId,
@@ -156,41 +187,42 @@ export class AdbPacketDispatcher extends AutoDisposable {
             serviceString,
         });
 
-        const args: AdbIncomingSocketEventArgs = {
-            handled: false,
-            packet,
-            serviceString,
-            socket,
-        };
-        this.incomingSocketEvent.fire(args);
-
-        if (args.handled) {
-            this.sockets.set(localId, socket);
-            await this.sendPacket(AdbCommand.OK, localId, remoteId);
-        } else {
-            await this.sendPacket(AdbCommand.Close, 0, remoteId);
+        for (const handler of this._incomingSocketHandlers) {
+            if (await handler(controller.socket)) {
+                this.sockets.set(localId, controller);
+                await this.sendPacket(AdbCommand.OK, localId, remoteId);
+                return;
+            }
         }
+
+        await this.sendPacket(AdbCommand.Close, 0, remoteId);
     }
 
     public async createSocket(serviceString: string): Promise<AdbSocket> {
-        if (this.appendNullToServiceString) {
+        if (this.options.appendNullToServiceString) {
             serviceString += '\0';
         }
 
         const [localId, initializer] = this.initializers.add<number>();
-        await this.sendPacket(AdbCommand.Open, localId, 0, serviceString);
+        await this.sendPacket(
+            AdbCommand.Open,
+            localId,
+            0,
+            serviceString
+        );
 
+        // Fulfilled by `handleOk`
         const remoteId = await initializer;
-        const socket = new AdbSocket({
+        const controller = new AdbSocketController({
             dispatcher: this,
             localId,
             remoteId,
             localCreated: true,
             serviceString,
         });
-        this.sockets.set(localId, socket);
+        this.sockets.set(localId, controller);
 
-        return socket;
+        return controller.socket;
     }
 
     public sendPacket(packet: AdbPacketInit): Promise<void>;
@@ -206,7 +238,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         arg1?: number,
         payload: string | Uint8Array = EmptyUint8Array,
     ): Promise<void> {
-        let init: AdbPacketCore;
+        let init: AdbPacketData;
         if (arg0 === undefined) {
             init = packetOrCommand as AdbPacketInit;
         } else {
@@ -223,11 +255,11 @@ export class AdbPacketDispatcher extends AutoDisposable {
         }
 
         if (init.payload &&
-            init.payload.byteLength > this.maxPayloadSize) {
+            init.payload.byteLength > this.options.maxPayloadSize) {
             throw new Error('payload too large');
         }
 
-        if (this.calculateChecksum) {
+        if (this.options.calculateChecksum) {
             calculateChecksum(init);
         } else {
             (init as AdbPacketInit).checksum = 0;
@@ -236,21 +268,34 @@ export class AdbPacketDispatcher extends AutoDisposable {
         await this._writer.write(init as AdbPacketInit);
     }
 
-    public override dispose() {
-        for (const socket of this.sockets.values()) {
-            socket.dispose();
-        }
-        this.sockets.clear();
-
+    public async close() {
+        // Send `CLSE` packets for all sockets
+        await Promise.all(
+            Array.from(
+                this.sockets.values(),
+                socket => socket.close(),
+            )
+        );
+
+        // Stop receiving
+        // It's possible that we haven't received all `CLSE` confirm packets,
+        // but it doesn't matter, the next connection can cope with them.
         try {
-            // Stop pipes
             this._abortController.abort();
         } catch { }
 
+        // Adb connection doesn't have a method to confirm closing,
+        // so call `dispose` immediately
+        this.dispose();
+    }
+
+    private dispose() {
+        for (const socket of this.sockets.values()) {
+            socket.dispose();
+        }
+
         this._writer.releaseLock();
 
         this._disconnected.resolve();
-
-        super.dispose();
     }
 }