@yume-chan/adb 0.0.12 → 0.0.15

package/src/commands/sync/sync.ts

@@ -4,11 +4,28 @@ import { AdbFeatures } from '../../features.js';
 import type { AdbSocket } from '../../socket/index.js';
 import { AdbBufferedStream, ReadableStream, WrapReadableStream, WrapWritableStream, WritableStream, WritableStreamDefaultWriter } from '../../stream/index.js';
 import { AutoResetEvent } from '../../utils/index.js';
-import { AdbSyncEntryResponse, adbSyncOpenDir } from './list.js';
+import { escapeArg } from "../index.js";
+import { adbSyncOpenDir, type AdbSyncEntry } from './list.js';
 import { adbSyncPull } from './pull.js';
 import { adbSyncPush } from './push.js';
 import { adbSyncLstat, adbSyncStat } from './stat.js';
 
+/**
+ * A simplified `dirname` function that only handles absolute unix paths.
+ * @param path an absolute unix path
+ * @returns the directory name of the input path
+ */
+export function dirname(path: string): string {
+    const end = path.lastIndexOf('/');
+    if (end === -1) {
+        throw new Error(`Invalid path`);
+    }
+    if (end === 0) {
+        return '/';
+    }
+    return path.substring(0, end);
+}
+
 export class AdbSync extends AutoDisposable {
     protected adb: Adb;
 
@@ -22,6 +39,19 @@ export class AdbSync extends AutoDisposable {
         return this.adb.features!.includes(AdbFeatures.StatV2);
     }
 
+    public get supportsList2(): boolean {
+        return this.adb.features!.includes(AdbFeatures.ListV2);
+    }
+
+    public get fixedPushMkdir(): boolean {
+        return this.adb.features!.includes(AdbFeatures.FixedPushMkdir);
+    }
+
+    public get needPushMkdirWorkaround(): boolean {
+        // https://android.googlesource.com/platform/packages/modules/adb/+/91768a57b7138166e0a3d11f79cd55909dda7014/client/file_sync_client.cpp#1361
+        return this.adb.features!.includes(AdbFeatures.ShellV2) && !this.fixedPushMkdir;
+    }
+
     public constructor(adb: Adb, socket: AdbSocket) {
         super();
 
@@ -65,18 +95,18 @@ export class AdbSync extends AutoDisposable {
 
     public async *opendir(
         path: string
-    ): AsyncGenerator<AdbSyncEntryResponse, void, void> {
+    ): AsyncGenerator<AdbSyncEntry, void, void> {
         await this.sendLock.wait();
 
         try {
-            yield* adbSyncOpenDir(this.stream, this.writer, path);
+            yield* adbSyncOpenDir(this.stream, this.writer, path, this.supportsList2);
         } finally {
             this.sendLock.notify();
         }
     }
 
     public async readdir(path: string) {
-        const results: AdbSyncEntryResponse[] = [];
+        const results: AdbSyncEntry[] = [];
         for await (const entry of this.opendir(path)) {
             results.push(entry);
         }
@@ -90,13 +120,10 @@ export class AdbSync extends AutoDisposable {
      * @returns A `ReadableStream` that reads from the file.
      */
     public read(filename: string): ReadableStream<Uint8Array> {
-        return new WrapReadableStream<Uint8Array, ReadableStream<Uint8Array>, undefined>({
+        return new WrapReadableStream({
             start: async () => {
                 await this.sendLock.wait();
-                return {
-                    readable: adbSyncPull(this.stream, this.writer, filename),
-                    state: undefined,
-                };
+                return adbSyncPull(this.stream, this.writer, filename);
             },
             close: async () => {
                 this.sendLock.notify();
@@ -120,16 +147,25 @@ export class AdbSync extends AutoDisposable {
         return new WrapWritableStream({
             start: async () => {
                 await this.sendLock.wait();
-                return {
-                    writable: adbSyncPush(
-                        this.stream,
-                        this.writer,
-                        filename,
-                        mode,
-                        mtime,
-                    ),
-                    state: undefined,
-                };
+
+                if (this.needPushMkdirWorkaround) {
+                    // It may fail if the path is already existed.
+                    // Ignore the result.
+                    // TODO: sync: test this
+                    await this.adb.subprocess.spawnAndWait([
+                        'mkdir',
+                        '-p',
+                        escapeArg(dirname(filename)),
+                    ]);
+                }
+
+                return adbSyncPush(
+                    this.stream,
+                    this.writer,
+                    filename,
+                    mode,
+                    mtime,
+                );
             },
             close: async () => {
                 this.sendLock.notify();
@@ -139,7 +175,7 @@ export class AdbSync extends AutoDisposable {
 
     public override async dispose() {
         super.dispose();
-        this.stream.close();
+        await this.stream.close();
         await this.writer.close();
     }
 }

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;