@yume-chan/adb 0.0.9 → 0.0.12

package/src/auth.ts

@@ -1,156 +1,170 @@
-import { PromiseResolver } from '@yume-chan/async';
-import { Disposable } from '@yume-chan/event';
-import { ValueOrPromise } from '@yume-chan/struct';
-import { calculatePublicKey, calculatePublicKeyLength, sign } from './crypto';
-import { AdbCommand, AdbPacket, AdbPacketInit } from './packet';
-import { calculateBase64EncodedLength, encodeBase64 } from './utils';
-
-export type AdbKeyIterable = Iterable<ArrayBuffer> | AsyncIterable<ArrayBuffer>;
-
-export interface AdbCredentialStore {
-    iterateKeys(): AdbKeyIterable;
-
-    generateKey(): ValueOrPromise<ArrayBuffer>;
-}
-
-export enum AdbAuthType {
-    Token = 1,
-    Signature = 2,
-    PublicKey = 3,
-}
-
-export interface AdbAuthenticator {
-    /**
-     * @param getNextRequest
-     *
-     * Call this function to get the next authentication request packet from device.
-     *
-     * After calling `getNextRequest`, authenticator can `yield` a packet as response, or `return` to indicate its incapability of handling the request.
-     *
-     * After `return`, the `AdbAuthenticatorHandler` will move on to next authenticator and never go back.
-     *
-     * Calling `getNextRequest` multiple times without `yield` or `return` will always return the same request.
-     */
-    (
-        credentialStore: AdbCredentialStore,
-        getNextRequest: () => Promise<AdbPacket>
-    ): AsyncIterable<AdbPacketInit>;
-}
-
-export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
-    credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
-    for await (const key of credentialStore.iterateKeys()) {
-        const packet = await getNextRequest();
-
-        if (packet.arg0 !== AdbAuthType.Token) {
-            return;
-        }
-
-        const signature = sign(key, packet.payload!);
-        yield {
-            command: AdbCommand.Auth,
-            arg0: AdbAuthType.Signature,
-            arg1: 0,
-            payload: signature,
-        };
-    }
-};
-
-export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
-    credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
-    const packet = await getNextRequest();
-
-    if (packet.arg0 !== AdbAuthType.Token) {
-        return;
-    }
-
-    let privateKey: ArrayBuffer | undefined;
-    for await (const key of credentialStore.iterateKeys()) {
-        privateKey = key;
-        break;
-    }
-
-    if (!privateKey) {
-        privateKey = await credentialStore.generateKey();
-    }
-
-    const publicKeyLength = calculatePublicKeyLength();
-    const [publicKeyBase64Length] = calculateBase64EncodedLength(publicKeyLength);
-
-    // The public key is null terminated,
-    // So we allocate the buffer with one extra byte.
-    const publicKeyBuffer = new ArrayBuffer(publicKeyBase64Length + 1);
-
-    calculatePublicKey(privateKey, publicKeyBuffer);
-    encodeBase64(publicKeyBuffer, 0, publicKeyLength, publicKeyBuffer);
-
-    yield {
-        command: AdbCommand.Auth,
-        arg0: AdbAuthType.PublicKey,
-        arg1: 0,
-        payload: publicKeyBuffer
-    };
-};
-
-export const AdbDefaultAuthenticators: AdbAuthenticator[] = [
-    AdbSignatureAuthenticator,
-    AdbPublicKeyAuthenticator
-];
-
-export class AdbAuthenticationHandler implements Disposable {
-    public readonly authenticators: readonly AdbAuthenticator[];
-
-    private readonly credentialStore: AdbCredentialStore;
-
-    private pendingRequest = new PromiseResolver<AdbPacket>();
-
-    private iterator: AsyncIterator<AdbPacketInit> | undefined;
-
-    public constructor(
-        authenticators: readonly AdbAuthenticator[],
-        credentialStore: AdbCredentialStore
-    ) {
-        this.authenticators = authenticators;
-        this.credentialStore = credentialStore;
-    }
-
-    private getNextRequest = (): Promise<AdbPacket> => {
-        return this.pendingRequest.promise;
-    };
-
-    private async* runAuthenticator(): AsyncGenerator<AdbPacketInit> {
-        for (const authenticator of this.authenticators) {
-            for await (const packet of authenticator(this.credentialStore, this.getNextRequest)) {
-                // If the authenticator yielded a response
-                // Prepare `nextRequest` for next authentication request
-                this.pendingRequest = new PromiseResolver<AdbPacket>();
-
-                // Yield the response to outer layer
-                yield packet;
-            }
-
-            // If the authenticator returned,
-            // Next authenticator will be given the same `pendingRequest`
-        }
-
-        throw new Error('Cannot authenticate with device');
-    }
-
-    public async handle(packet: AdbPacket): Promise<AdbPacketInit> {
-        if (!this.iterator) {
-            this.iterator = this.runAuthenticator();
-        }
-
-        this.pendingRequest.resolve(packet);
-        const result = await this.iterator.next();
-        return result.value;
-    }
-
-    public dispose() {
-        this.iterator?.return?.();
-    }
-}
+import { PromiseResolver } from '@yume-chan/async';
+import type { Disposable } from '@yume-chan/event';
+import type { ValueOrPromise } from '@yume-chan/struct';
+import { calculatePublicKey, calculatePublicKeyLength, sign } from './crypto.js';
+import { AdbCommand, AdbPacket, type AdbPacketCore } from './packet.js';
+import { calculateBase64EncodedLength, encodeBase64 } from './utils/index.js';
+
+export type AdbKeyIterable = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
+
+export interface AdbCredentialStore {
+    /**
+     * Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
+     *
+     * The returned `Uint8Array` is the private key in PKCS #8 format.
+     */
+    generateKey(): ValueOrPromise<Uint8Array>;
+
+    /**
+     * Synchronously or asynchronously iterate through all stored RSA private keys.
+     *
+     * Each call to `iterateKeys` must return a different iterator that iterate through all stored keys.
+     */
+    iterateKeys(): AdbKeyIterable;
+}
+
+export enum AdbAuthType {
+    Token = 1,
+    Signature = 2,
+    PublicKey = 3,
+}
+
+export interface AdbAuthenticator {
+    /**
+     * @param getNextRequest
+     *
+     * Call this function to get the next authentication request packet from device.
+     *
+     * After calling `getNextRequest`, authenticator can `yield` a packet as response, or `return` to indicate its incapability of handling the request.
+     *
+     * After `return`, the `AdbAuthenticatorHandler` will move on to next authenticator and never go back.
+     *
+     * Calling `getNextRequest` multiple times without `yield` or `return` will always return the same request.
+     */
+    (
+        credentialStore: AdbCredentialStore,
+        getNextRequest: () => Promise<AdbPacket>
+    ): AsyncIterable<AdbPacketCore>;
+}
+
+export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
+    credentialStore: AdbCredentialStore,
+    getNextRequest: () => Promise<AdbPacket>,
+): AsyncIterable<AdbPacketCore> {
+    for await (const key of credentialStore.iterateKeys()) {
+        const packet = await getNextRequest();
+
+        if (packet.arg0 !== AdbAuthType.Token) {
+            return;
+        }
+
+        const signature = sign(key, packet.payload);
+        yield {
+            command: AdbCommand.Auth,
+            arg0: AdbAuthType.Signature,
+            arg1: 0,
+            payload: new Uint8Array(signature),
+        };
+    }
+};
+
+export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
+    credentialStore: AdbCredentialStore,
+    getNextRequest: () => Promise<AdbPacket>,
+): AsyncIterable<AdbPacketCore> {
+    const packet = await getNextRequest();
+
+    if (packet.arg0 !== AdbAuthType.Token) {
+        return;
+    }
+
+    let privateKey: Uint8Array | undefined;
+    for await (const key of credentialStore.iterateKeys()) {
+        privateKey = key;
+        break;
+    }
+
+
+    if (!privateKey) {
+        privateKey = await credentialStore.generateKey();
+    }
+
+    const publicKeyLength = calculatePublicKeyLength();
+    const [publicKeyBase64Length] = calculateBase64EncodedLength(publicKeyLength);
+
+    // The public key is null terminated,
+    // So we allocate the buffer with one extra byte.
+    const publicKeyBuffer = new Uint8Array(publicKeyBase64Length + 1);
+
+    calculatePublicKey(privateKey, publicKeyBuffer);
+    encodeBase64(
+        publicKeyBuffer.subarray(0, publicKeyLength),
+        publicKeyBuffer
+    );
+
+    yield {
+        command: AdbCommand.Auth,
+        arg0: AdbAuthType.PublicKey,
+        arg1: 0,
+        payload: publicKeyBuffer,
+    };
+};
+
+export const AdbDefaultAuthenticators: AdbAuthenticator[] = [
+    AdbSignatureAuthenticator,
+    AdbPublicKeyAuthenticator,
+];
+
+export class AdbAuthenticationHandler implements Disposable {
+    public readonly authenticators: readonly AdbAuthenticator[];
+
+    private readonly credentialStore: AdbCredentialStore;
+
+    private pendingRequest = new PromiseResolver<AdbPacket>();
+
+    private iterator: AsyncIterator<AdbPacketCore> | undefined;
+
+    public constructor(
+        authenticators: readonly AdbAuthenticator[],
+        credentialStore: AdbCredentialStore
+    ) {
+        this.authenticators = authenticators;
+        this.credentialStore = credentialStore;
+    }
+
+    private getNextRequest = (): Promise<AdbPacket> => {
+        return this.pendingRequest.promise;
+    };
+
+    private async* runAuthenticator(): AsyncGenerator<AdbPacketCore> {
+        for (const authenticator of this.authenticators) {
+            for await (const packet of authenticator(this.credentialStore, this.getNextRequest)) {
+                // If the authenticator yielded a response
+                // Prepare `nextRequest` for next authentication request
+                this.pendingRequest = new PromiseResolver<AdbPacket>();
+
+                // Yield the response to outer layer
+                yield packet;
+            }
+
+            // If the authenticator returned,
+            // Next authenticator will be given the same `pendingRequest`
+        }
+
+        throw new Error('Cannot authenticate with device');
+    }
+
+    public async handle(packet: AdbPacket): Promise<AdbPacketCore> {
+        if (!this.iterator) {
+            this.iterator = this.runAuthenticator();
+        }
+
+        this.pendingRequest.resolve(packet);
+        const result = await this.iterator.next();
+        return result.value;
+    }
+
+    public dispose() {
+        this.iterator?.return?.();
+    }
+}

package/src/backend.ts

@@ -1,24 +1,11 @@
-import { Event } from '@yume-chan/event';
-import { ValueOrPromise } from '@yume-chan/struct';
-
-export interface AdbBackend {
-    readonly serial: string;
-
-    readonly name: string | undefined;
-
-    readonly connected: boolean;
-
-    readonly onDisconnected: Event<void>;
-
-    connect?(): ValueOrPromise<void>;
-
-    encodeUtf8(input: string): ArrayBuffer;
-
-    decodeUtf8(buffer: ArrayBuffer): string;
-
-    write(buffer: ArrayBuffer): ValueOrPromise<void>;
-
-    read(length: number): ValueOrPromise<ArrayBuffer>;
-
-    dispose(): ValueOrPromise<void>;
-}
+import type { ValueOrPromise } from '@yume-chan/struct';
+import type { AdbPacketCore, AdbPacketInit } from "./packet.js";
+import type { ReadableWritablePair } from "./stream/index.js";
+
+export interface AdbBackend {
+    readonly serial: string;
+
+    readonly name: string | undefined;
+
+    connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>;
+}

package/src/commands/base.ts

@@ -1,11 +1,11 @@
-import { AutoDisposable } from '@yume-chan/event';
-import { Adb } from '../adb';
-
-export class AdbCommandBase extends AutoDisposable {
-    protected adb: Adb;
-
-    public constructor(adb: Adb) {
-        super();
-        this.adb = adb;
-    }
-}
+import { AutoDisposable } from '@yume-chan/event';
+import type { Adb } from '../adb.js';
+
+export class AdbCommandBase extends AutoDisposable {
+    protected adb: Adb;
+
+    public constructor(adb: Adb) {
+        super();
+        this.adb = adb;
+    }
+}

package/src/commands/framebuffer.ts

@@ -1,73 +1,73 @@
-import Struct from "@yume-chan/struct";
-import { Adb } from '../adb';
-import { AdbBufferedStream } from '../stream';
-
-const Version =
-    new Struct({ littleEndian: true })
-        .uint32('version');
-
-/*
- * ADB uses 8 int32 fields to describe bit depths
- * The only combination I have seen is RGBA8888, which is
- *   red_offset:   0
- *   red_length:   8
- *   blue_offset:  16
- *   blue_length:  8
- *   green_offset: 8
- *   green_length: 8
- *   alpha_offset: 24
- *   alpha_length: 8
- */
-
-export const AdbFrameBufferV1 =
-    new Struct({ littleEndian: true })
-        .uint32('bpp')
-        .uint32('size')
-        .uint32('width')
-        .uint32('height')
-        .uint32('red_offset')
-        .uint32('red_length')
-        .uint32('blue_offset')
-        .uint32('blue_length')
-        .uint32('green_offset')
-        .uint32('green_length')
-        .uint32('alpha_offset')
-        .uint32('alpha_length')
-        .uint8ClampedArray('data', { lengthField: 'size' });
-
-export type AdbFrameBufferV1 = typeof AdbFrameBufferV1['TDeserializeResult'];
-
-export const AdbFrameBufferV2 =
-    new Struct({ littleEndian: true })
-        .uint32('bpp')
-        .uint32('colorSpace')
-        .uint32('size')
-        .uint32('width')
-        .uint32('height')
-        .uint32('red_offset')
-        .uint32('red_length')
-        .uint32('blue_offset')
-        .uint32('blue_length')
-        .uint32('green_offset')
-        .uint32('green_length')
-        .uint32('alpha_offset')
-        .uint32('alpha_length')
-        .uint8ClampedArray('data', { lengthField: 'size' });
-
-export type AdbFrameBufferV2 = typeof AdbFrameBufferV2['TDeserializeResult'];
-
-export type AdbFrameBuffer = AdbFrameBufferV1 | AdbFrameBufferV2;
-
-export async function framebuffer(adb: Adb): Promise<AdbFrameBuffer> {
-    const socket = await adb.createSocket('framebuffer:');
-    const stream = new AdbBufferedStream(socket);
-    const { version } = await Version.deserialize(stream);
-    switch (version) {
-        case 1:
-            return AdbFrameBufferV1.deserialize(stream);
-        case 2:
-            return AdbFrameBufferV2.deserialize(stream);
-        default:
-            throw new Error('Unknown FrameBuffer version');
-    }
-}
+import Struct from "@yume-chan/struct";
+import type { Adb } from '../adb.js';
+import { AdbBufferedStream } from '../stream/index.js';
+
+const Version =
+    new Struct({ littleEndian: true })
+        .uint32('version');
+
+/*
+ * ADB uses 8 int32 fields to describe bit depths
+ * The only combination I have seen is RGBA8888, which is
+ *   red_offset:   0
+ *   red_length:   8
+ *   blue_offset:  16
+ *   blue_length:  8
+ *   green_offset: 8
+ *   green_length: 8
+ *   alpha_offset: 24
+ *   alpha_length: 8
+ */
+
+export const AdbFrameBufferV1 =
+    new Struct({ littleEndian: true })
+        .uint32('bpp')
+        .uint32('size')
+        .uint32('width')
+        .uint32('height')
+        .uint32('red_offset')
+        .uint32('red_length')
+        .uint32('blue_offset')
+        .uint32('blue_length')
+        .uint32('green_offset')
+        .uint32('green_length')
+        .uint32('alpha_offset')
+        .uint32('alpha_length')
+        .uint8Array('data', { lengthField: 'size' });
+
+export type AdbFrameBufferV1 = typeof AdbFrameBufferV1['TDeserializeResult'];
+
+export const AdbFrameBufferV2 =
+    new Struct({ littleEndian: true })
+        .uint32('bpp')
+        .uint32('colorSpace')
+        .uint32('size')
+        .uint32('width')
+        .uint32('height')
+        .uint32('red_offset')
+        .uint32('red_length')
+        .uint32('blue_offset')
+        .uint32('blue_length')
+        .uint32('green_offset')
+        .uint32('green_length')
+        .uint32('alpha_offset')
+        .uint32('alpha_length')
+        .uint8Array('data', { lengthField: 'size' });
+
+export type AdbFrameBufferV2 = typeof AdbFrameBufferV2['TDeserializeResult'];
+
+export type AdbFrameBuffer = AdbFrameBufferV1 | AdbFrameBufferV2;
+
+export async function framebuffer(adb: Adb): Promise<AdbFrameBuffer> {
+    const socket = await adb.createSocket('framebuffer:');
+    const stream = new AdbBufferedStream(socket);
+    const { version } = await Version.deserialize(stream);
+    switch (version) {
+        case 1:
+            return AdbFrameBufferV1.deserialize(stream);
+        case 2:
+            return AdbFrameBufferV2.deserialize(stream);
+        default:
+            throw new Error('Unknown FrameBuffer version');
+    }
+}

package/src/commands/index.ts

@@ -1,8 +1,8 @@
-export * from './base';
-export * from './demo-mode';
-export * from './framebuffer';
-export * from './install';
-export * from './reverse';
-export * from './shell';
-export * from './sync';
-export * from './tcpip';
+export * from './base.js';
+export * from './framebuffer.js';
+export * from './install.js';
+export * from './power.js';
+export * from './reverse.js';
+export * from './subprocess/index.js';
+export * from './sync/index.js';
+export * from './tcpip.js';

package/src/commands/install.ts

@@ -1,21 +1,32 @@
-import { Adb } from "../adb";
-import { escapeArg } from "./shell";
-
-export async function install(
-    adb: Adb,
-    apk: ArrayLike<number> | ArrayBufferLike | AsyncIterable<ArrayBuffer>,
-    onProgress?: (uploaded: number) => void,
-): Promise<void> {
-    const filename = `/data/local/tmp/${Math.random().toString().substr(2)}.apk`;
-
-    // Upload apk file to tmp folder
-    const sync = await adb.sync();
-    await sync.write(filename, apk, undefined, undefined, onProgress);
-    sync.dispose();
-
-    // Invoke `pm install` to install it
-    await adb.childProcess.exec('pm', 'install', escapeArg(filename));
-
-    // Remove the temp file
-    await adb.rm(filename);
-}
+import type { Adb } from "../adb.js";
+import { WrapWritableStream, WritableStream } from "../stream/index.js";
+import { escapeArg } from "./subprocess/index.js";
+import type { AdbSync } from "./sync/index.js";
+
+export function install(
+    adb: Adb,
+): WritableStream<Uint8Array> {
+    const filename = `/data/local/tmp/${Math.random().toString().substring(2)}.apk`;
+
+    return new WrapWritableStream<Uint8Array, WritableStream<Uint8Array>, AdbSync>({
+        async start() {
+            // Upload apk file to tmp folder
+            const sync = await adb.sync();
+            const writable = sync.write(filename, undefined, undefined);
+
+            return {
+                writable,
+                state: sync,
+            };
+        },
+        async close(sync) {
+            sync.dispose();
+
+            // Invoke `pm install` to install it
+            await adb.subprocess.spawnAndWaitLegacy(['pm', 'install', escapeArg(filename)]);
+
+            // Remove the temp file
+            await adb.rm(filename);
+        }
+    });
+}

package/src/commands/power.ts

@@ -0,0 +1,54 @@
+// cspell: ignore bootloader
+// cspell: ignore fastboot
+// cspell: ignore keyevent
+// cspell: ignore longpress
+
+import { AdbCommandBase } from "./base.js";
+
+export class AdbPower extends AdbCommandBase {
+    public reboot(name: string = '') {
+        return this.adb.createSocketAndWait(`reboot:${name}`);
+    }
+
+    public bootloader() {
+        return this.reboot('bootloader');
+    }
+
+    public fastboot() {
+        return this.reboot('fastboot');
+    }
+
+    public recovery() {
+        return this.reboot('recovery');
+    }
+
+    public sideload() {
+        return this.reboot('sideload');
+    }
+
+    /**
+     * Reboot to Qualcomm Emergency Download (EDL) Mode.
+     *
+     * Only works on some Qualcomm devices.
+     */
+    public qualcommEdlMode() {
+        return this.reboot('edl');
+    }
+
+    public powerOff() {
+        return this.adb.subprocess.spawnAndWaitLegacy(['reboot', '-p']);
+    }
+
+    public powerButton(longPress: boolean = false) {
+        return this.adb.subprocess.spawnAndWaitLegacy(['input', 'keyevent', longPress ? '--longpress POWER' : 'POWER']);
+    }
+
+    /**
+     * Reboot to Samsung Odin download mode.
+     *
+     * Only works on Samsung devices.
+     */
+    public samsungOdin() {
+        return this.reboot('download');
+    }
+}