@yume-chan/adb 0.0.9 → 0.0.12

package/CHANGELOG.json

@@ -0,0 +1,55 @@
+{
+  "name": "@yume-chan/adb",
+  "entries": [
+    {
+      "version": "0.0.12",
+      "tag": "@yume-chan/adb_v0.0.12",
+      "date": "Sun, 03 Apr 2022 11:18:47 GMT",
+      "comments": {}
+    },
+    {
+      "version": "0.0.11",
+      "tag": "@yume-chan/adb_v0.0.11",
+      "date": "Sun, 03 Apr 2022 10:54:15 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Add power related API"
+          },
+          {
+            "comment": "Update compatibility matrix"
+          },
+          {
+            "comment": "Update license year"
+          }
+        ],
+        "patch": [
+          {
+            "comment": "Update to use Web Streams API"
+          },
+          {
+            "comment": "Improve compatibility with Node.js 12 ESM format"
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.0.10",
+      "tag": "@yume-chan/adb_v0.0.10",
+      "date": "Sun, 09 Jan 2022 15:52:20 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Remove `encodeUtf8()` and `decodeUtf8()` from `AdbBackend`"
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.0.9",
+      "tag": "@yume-chan/adb_v0.0.9",
+      "date": "Sun, 09 Jan 2022 15:50:20 GMT",
+      "comments": {}
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Change Log - @yume-chan/adb
+
+This log was last generated on Sun, 03 Apr 2022 11:18:47 GMT and should not be manually modified.
+
+## 0.0.12
+Sun, 03 Apr 2022 11:18:47 GMT
+
+_Version update only_
+
+## 0.0.11
+Sun, 03 Apr 2022 10:54:15 GMT
+
+### Patches
+
+- Update to use Web Streams API
+- Improve compatibility with Node.js 12 ESM format
+
+### Updates
+
+- Add power related API
+- Update compatibility matrix
+- Update license year
+
+## 0.0.10
+Sun, 09 Jan 2022 15:52:20 GMT
+
+### Updates
+
+- Remove `encodeUtf8()` and `decodeUtf8()` from `AdbBackend`
+
+## 0.0.9
+Sun, 09 Jan 2022 15:50:20 GMT
+
+_Initial release_
+

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2020 Simon Chan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2020-2022 Simon Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,257 +1,240 @@
-# @yume-chan/adb
-
-TypeScript implementation of Android Debug Bridge (ADB) protocol.
-
-- [Compatibility](#compatibility)
-- [Connection](#connection)
-  - [Backend](#backend)
-    - [`read`](#read)
-    - [`write`](#write)
-- [Authenticate](#authenticate)
-  - [Public key authentication](#public-key-authentication)
-    - [Backend](#backend-1)
-      - [`generateKey`](#generatekey)
-  - [Token authentication](#token-authentication)
-    - [Backend](#backend-2)
-      - [`iterateKeys`](#iteratekeys)
-- [Stream multiplex](#stream-multiplex)
-  - [Backend](#backend-3)
-    - [`encodeUtf8`](#encodeutf8)
-    - [`decodeUtf8`](#decodeutf8)
-- [Commands](#commands)
-  - [shell](#shell)
-    - [PTY mode](#pty-mode)
-    - [ADB shell protocol](#adb-shell-protocol)
-    - [Raw mode](#raw-mode)
-  - [usb](#usb)
-  - [tcpip](#tcpip)
-  - [sync](#sync)
-    - [LIST](#list)
-    - [LIS2](#lis2)
-    - [STAT](#stat)
-    - [LST2](#lst2)
-    - [STA2](#sta2)
-    - [RECV](#recv)
-    - [RCV2](#rcv2)
-    - [SEND](#send)
-    - [SND2](#snd2)
-- [Useful links](#useful-links)
-
-## Compatibility
-
-The main limiting factor of compatibility is [@yume-chan/struct](https://www.npmjs.com/package/@yume-chan/struct).
-
-This library doesn't use any DOM or Node.js API.
-
-|                 | Chrome | Edge | Firefox | Internet Explorer | Safari         | Node.js |
-| --------------- | ------ | ---- | ------- | ----------------- | -------------- | ------- |
-| **Basic usage** | 68     | 79   | 68      | No                | 14<sup>1</sup> | 10.4    |
-
-<sup>1</sup> Requires a polyfill for [`DataView#getBigUint64`][MDN_DataView_getBigUint64] and [`DataView#setBigUint64`][MDN_DataView_setBigUint64]
-
-[MDN_DataView_getBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64
-[MDN_DataView_setBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64
-
-## Connection
-
-This library doesn't tie with a specific transportation method.
-
-Instead, a `Backend` is responsible for transferring packets in its own way (USB, WebSocket, etc).
-
-### Backend
-
-#### `read`
-
-```ts
-read(length: number): ArrayBuffer | Promise<ArrayBuffer>
-```
-
-Read the specified amount of data from the underlying connection.
-
-The backend should return only the data written by another endpoint in a single operation. That meas, it should never concatenate multiple write operations to fulfill the requested `length`. Here is the reason:
-
-In normal working condition the client always knows how much data it should read and the server will always send exactly such amount of data in a single operation.
-
-One exception is that for stateless connections (including USB and TCP), if one client sent a request and died without reading the response, the data will sit in an operating system's internal buffer. When the next client, reusing the connection, want to read a response to its request, it may get that buffered response instead.
-
-The native ADB implementation tries to detect such a situation by checking length and content of the response data, so do this library. So the backend should not return such a response if possible, or follow this behavior if it can't distinguish.
-
-#### `write`
-
-```ts
-write(buffer: ArrayBuffer): void | Promise<void>
-```
-
-Write data to the underlying connection.
-
-## Authenticate
-
-ADB supports two authentication methods:
-
-### Public key authentication
-
-1. Client (this library) generates a RSA private key and save it.
-2. Client generates an ADB public key (not RSA public key) based on the RSA private key.
-3. Client transfers the ADB public key to server (device).
-4. Server may ask its user to accept the public key, it will save the public key if accepted.
-
-#### Backend
-
-##### `generateKey`
-
-```ts
-generateKey(): ArrayBuffer | Promise<ArrayBuffer>
-```
-
-Generate and store a RSA private key with modulus length 2048 and public exponent 65537.
-
-The returned `ArrayBuffer` is the private key in PKCS #8 format.
-
-### Token authentication
-
-1. Server transfers a 20 bytes token to client.
-2. Client RSA encrypts the token with its RSA private key.
-3. Client transfers the encrypted token to server.
-4. Server tries to decrypt the received data with all saved public keys. If any decryption succeed, the authentication succeed.
-
-#### Backend
-
-##### `iterateKeys`
-
-```ts
-generateKey(): Iterator<ArrayBuffer> | AsyncIterator<ArrayBuffer>
-```
-
-Synchronously or asynchronously iterate through all stored RSA private keys.
-
-Each call to `iterateKeys` must returns a different iterator that iterate through all stored keys.
-
-## Stream multiplex
-
-ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
-
-1. Client sends an `OPEN` packet to create a stream.
-2. Server responds with `OKAY` or `FAIL`.
-3. Client and server read/write on the stream.
-4. Client/server sends a `CLSE` to close the stream.
-
-The `Backend` is responsible for encoding and decoding UTF-8 strings.
-
-### Backend
-
-#### `encodeUtf8`
-
-```ts
-encodeUtf8(input: string): ArrayBuffer
-```
-
-Encode `input` into an `ArrayBuffer` with UTF-8 encoding.
-
-#### `decodeUtf8`
-
-```ts
-decodeUtf8(buffer: ArrayBuffer): string
-```
-
-Decode `buffer` into a string with UTF-8 encoding.
-
-## Commands
-
-### shell
-
-#### PTY mode
-
-Basic mode, supported on all devices.
-
-#### ADB shell protocol
-
-*(Not Implemented)*
-
-Supported on devices with `shell_v2` feature.
-
-Supports window size changing event.
-
-Supports returning process exit code.
-
-#### Raw mode
-
-*(Not Implemented)*
-
-Must be used with ADB shell protocol.
-
-Supports splitting stdout and stderr.
-
-### usb
-
-Disable ADB over WiFi.
-
-### tcpip
-
-Enable ADB over WiFi.
-
-### sync
-
-Client and server will communicate with another protocol on the opened stream.
-
-#### LIST
-
-Request server to list the content of a folder.
-
-#### LIS2
-
-*(Not Implemented)*
-
-Version 2 of the LIST command, contains more information.
-
-Supported on devices with `ls_v2` feature.
-
-#### STAT
-
-Request server to return the information of a file.
-
-If path is a symbolic link, the returned information is about the link itself.
-
-So it's actually the [`lstat`](https://linux.die.net/man/2/lstat) system call.
-
-#### LST2
-
-Version 2 of the STAT command, contains more information.
-
-Supported on devices with `stat_v2` feature.
-
-#### STA2
-
-Basically identical to LST2, but if path is a symbolic link, the information is about the file it refers to.
-
-Supported on devices with `stat_v2` feature.
-
-#### RECV
-
-Request server to send the content of a file.
-
-#### RCV2
-
-*(Not Implemented)*
-
-Version 2 of the RECV command.
-
-Supported on devices with `sendrecv_v2` feature.
-
-#### SEND
-
-*(Not Implemented)*
-
-Send a file onto server's file system.
-
-#### SND2
-
-*(Not Implemented)*
-
-Version 2 of the SEND command.
-
-Supported on devices with `sendrecv_v2` feature.
-
-## Useful links
-
-* [ADB protocol overview](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/OVERVIEW.TXT)
-* [ADB commands](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/SERVICES.TXT#145)
+# @yume-chan/adb
+
+TypeScript implementation of Android Debug Bridge (ADB) protocol.
+
+**WARNING:** The public API is UNSTABLE. If you have any questions, please open an issue.
+
+- [Compatibility](#compatibility)
+  - [Basic usage](#basic-usage)
+  - [Use without bundlers](#use-without-bundlers)
+- [Connection](#connection)
+  - [Backend](#backend)
+    - [`connect`](#connect)
+- [Authentication](#authentication)
+    - [AdbCredentialStore](#adbcredentialstore)
+      - [`generateKey`](#generatekey)
+      - [`iterateKeys`](#iteratekeys)
+      - [Implementations](#implementations)
+    - [AdbAuthenticator](#adbauthenticator)
+    - [`authenticate`](#authenticate)
+- [Stream multiplex](#stream-multiplex)
+  - [Backend](#backend-1)
+- [Commands](#commands)
+  - [childProcess](#childprocess)
+  - [usb](#usb)
+  - [tcpip](#tcpip)
+  - [sync](#sync)
+    - [LIST](#list)
+    - [LIS2](#lis2)
+    - [STAT](#stat)
+    - [LST2](#lst2)
+    - [STA2](#sta2)
+    - [RECV](#recv)
+    - [RCV2](#rcv2)
+    - [SEND](#send)
+    - [SND2](#snd2)
+- [Useful links](#useful-links)
+
+## Compatibility
+
+Here is a list of features, their used APIs, and their compatibilities. If an optional feature is not actually used, its requirements can be ignored.
+
+Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
+
+Each backend may have different requirements.
+
+### Basic usage
+
+|                                 | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js             |
+| ------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------------------- |
+| `@yume-chan/struct`<sup>1</sup> | 67     | 79   | 68      | No                | 14     | 8.3<sup>2</sup>, 11 |
+| [Streams][MDN_Streams]          | 67     | 79   | No      | No                | 14.1   | 16.5                |
+| *Overall*                       | 67     | 79   | No      | No                | 14.1   | 16.5                |
+
+<sup>1</sup> `uint64` and `string` used.
+
+<sup>2</sup> `TextEncoder` and `TextDecoder` are only available in `util` module. Need to be assigned to `globalThis`.
+
+### Use without bundlers
+
+|                 | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
+| --------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
+| Top-level await | 89     | 89   | 89      | No                | 15     | 14.8    |
+
+[MDN_Streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+
+## Connection
+
+This library doesn't tie to a specific transportation method.
+
+Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, TCP, etc).
+
+### Backend
+
+#### `connect`
+
+```ts
+connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
+```
+
+Connect to a device and create a pair of `AdbPacket` streams.
+
+The backend is responsible for serializing and deserializing the packets, because it's extreme slow for WebUSB backend (`@yume-chan/adb-backend-webusb`) to read packets with unknown size.
+
+## Authentication
+
+For how does ADB authentication work, see https://chensi.moe/blog/2020/09/30/webadb-part2-connection/#auth.
+
+In this library, authentication comes in two parts:
+
+#### AdbCredentialStore
+
+An interface to generate, store and iterate ADB private keys on each runtime. (Because Node.js and Browsers have different APIs to do this)
+
+##### `generateKey`
+
+```ts
+generateKey(): ValueOrPromise<Uint8Array>
+```
+
+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.
+
+##### `iterateKeys`
+
+```ts
+iterateKeys(): Iterator<ArrayBuffer> | AsyncIterator<ArrayBuffer>
+```
+
+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.
+
+##### Implementations
+
+The `@yume-chan/adb-credential-web` package contains a `AdbWebCredentialStore` implementation using Web Crypto API for generating keys and Web Storage API for storing keys.
+
+#### AdbAuthenticator
+
+An `AdbAuthenticator` generates `AUTH` responses for each `AUTH` request from server.
+
+This package contains `AdbSignatureAuthenticator` and `AdbPublicKeyAuthenticator`, the two basic modes.
+
+#### `authenticate`
+
+```ts
+static async authenticate(
+    connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
+    credentialStore: AdbCredentialStore,
+    authenticators = AdbDefaultAuthenticators,
+): Promise<Adb>
+```
+
+Call this method to authenticate the connection and create an `Adb` instance.
+
+It's possible to call `authenticate` multiple times on a single connection, every time the device receives a `CNXN` packet, it resets its internal state, and starts a new authentication process.
+
+## Stream multiplex
+
+ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
+
+1. Client sends an `OPEN` packet to create a stream.
+2. Server responds with `OKAY` or `FAIL`.
+3. Client and server read/write on the stream.
+4. Client/server sends a `CLSE` to close the stream.
+
+The `Backend` is responsible for reading and writing data from underlying source.
+
+### Backend
+
+## Commands
+
+### childProcess
+
+Spawns child process on server. ADB has two shell modes:
+
+|                             | Legacy mode                 | Shell Protocol               |
+| --------------------------- | --------------------------- | ---------------------------- |
+| Feature flag                | -                           | `shell_v2`                   |
+| Implementation              | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
+| Splitting stdout and stderr | No                          | Yes                          |
+| Returning exit code         | No                          | Yes                          |
+| Resizing window             | No                          | Yes                          |
+
+The `Adb#childProcess#shell` and `Adb#childProcess#spawn` methods accepts a list of implementations, and will use the first supported one.
+
+For simple command invocation, usually the `AdbNoneSubprocessProtocol` is enough.
+
+### usb
+
+Disable ADB over WiFi.
+
+### tcpip
+
+Enable ADB over WiFi.
+
+### sync
+
+Client and server will communicate with another protocol on the opened stream.
+
+#### LIST
+
+Request server to list the content of a folder.
+
+#### LIS2
+
+Version 2 of the LIST command, contains more information.
+
+Supported on devices with `ls_v2` feature.
+
+#### STAT
+
+Request server to return the information of a file.
+
+If path is a symbolic link, the returned information is about the link itself.
+
+So it's actually the [`lstat`](https://linux.die.net/man/2/lstat) system call.
+
+#### LST2
+
+Version 2 of the STAT command, contains more information.
+
+Supported on devices with `stat_v2` feature.
+
+#### STA2
+
+Basically identical to LST2, but if path is a symbolic link, the information is about the file it refers to.
+
+Supported on devices with `stat_v2` feature.
+
+#### RECV
+
+Request server to send the content of a file.
+
+#### RCV2
+
+*(Not Implemented)*
+
+Version 2 of the RECV command.
+
+Supported on devices with `sendrecv_v2` feature.
+
+#### SEND
+
+*(Not Implemented)*
+
+Send a file onto server's file system.
+
+#### SND2
+
+*(Not Implemented)*
+
+Version 2 of the SEND command.
+
+Supported on devices with `sendrecv_v2` feature.
+
+## Useful links
+
+* [ADB protocol overview](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/OVERVIEW.TXT)
+* [ADB commands](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/SERVICES.TXT#145)