@aepyornis/fastboot.ts 0.0.1

package/.prettierignore

@@ -0,0 +1 @@
+dist

package/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "semi": false
+}

package/README.md

@@ -0,0 +1,56 @@
+# fastboot.ts
+
+```sh
+pnpm install
+pnpm run build
+```
+
+    src/device.ts handles interfacing with WebUSB and implements fastboot protocol
+    src/client.ts implements higher level API, similar to fastboot cli tool
+    src/flasher.ts flashes zip image from a list of instructions
+    src/sparse.ts sparse image utilities Copyright (c) 2021 Danny Lin <danny@kdrag0n.dev>
+
+TODO
+
+    --apply-vbmeta
+    repack_ramdisk ?
+
+```js
+import { FastbootClient, FashbootFlasher } from "@aepyornis/fastboot.ts"
+
+const client = await FastbootClient.create()
+
+// run commands
+await client.unlock()
+await client.getVar("product")
+
+// flash CalyxOS
+import OpfsBlobStore from "@aepyornis/opfs_blob_store"
+const bs = await OpfsBlobStore.create()
+const hash = "a4434edb21e5e12a00ab9949f48f06c48169adcaeb4dce644857e1528b275274"
+const url = "https://release.calyxinstitute.org/lynx-factory-25605200.zip"
+await bs.fetch(hash, url)
+const file = await bs.get(hash)
+
+const instructions = `
+fastboot --set-active=other reboot-bootloader
+sleep 5
+fastboot flash --slot=other bootloader bootloader-lynx-lynx-15.2-12878710.img
+fastboot --set-active=other reboot-bootloader
+sleep 5
+fastboot flash --slot=other radio radio-lynx-g5300q-241205-250127-B-12973597.img
+fastboot --set-active=other reboot-bootloader
+sleep 5
+fastboot flash --slot=other radio radio-lynx-g5300q-241205-250127-B-12973597.img
+fastboot --set-active=other reboot-bootloader
+sleep 5
+fastboot erase avb_custom_key
+fastboot flash avb_custom_key avb_custom_key.img
+fastboot --skip-reboot -w update image-lynx-bp1a.250305.019.zip
+fastboot reboot-bootloader
+`
+
+const client = await FastbootClient.create()
+const deviceFlasher = new FastbootFlasher()
+await deviceFlasher.run(instructions)
+```

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+import eslint from "@eslint/js"
+import tseslint from "typescript-eslint"
+
+export default tseslint.config(
+  { ignores: ["dist/"] },
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+)

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aepyornis/fastboot.ts",
+  "version": "0.0.1",
+  "description": "fastboot again",
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "esbuild src/index.ts --bundle --sourcemap --format=esm --platform=browser --target=chrome121 --outfile=dist/fastboot.js"
+  },
+  "keywords": [],
+  "author": "Ziggy, Calyx Institute",
+  "license": "MIT",
+  "packageManager": "pnpm@10.8.0",
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/w3c-web-usb": "^1.0.10",
+    "esbuild": "^0.25.2",
+    "eslint": "^9.24.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1"
+  },
+  "dependencies": {
+    "@zip.js/zip.js": "^2.7.60"
+  }
+}

package/src/client.ts

@@ -0,0 +1,344 @@
+import { BlobWriter, Entry } from "@zip.js/zip.js"
+import { IMAGES } from "./images"
+import { parseFileHeader, splitBlob, fromRaw } from "./sparse"
+import { FastbootDevice } from "./device"
+
+export class FastbootError extends Error {}
+
+const FastbootUSBDeviceFilter = {
+  classCode: 0xff,
+  subclassCode: 0x42,
+  protocolCode: 0x03,
+}
+
+interface Logger {
+  log(message: string): void
+}
+
+// higher level API to interact with fastboot device
+// translates CLI commands to
+export class FastbootClient {
+  fd: FastbootDevice
+  logger: Logger
+
+  constructor(usb_device: USBDevice, logger: Logger = window.console) {
+    this.fd = new FastbootDevice(usb_device, logger)
+    this.logger = logger
+  }
+
+  async getVar(variable: string) {
+    return this.fd.getVar(variable)
+  }
+
+  async lock() {
+    await this.flashing("lock")
+    await this.fd.waitForReconnect()
+    if (await this.unlocked()) {
+      throw new FastbootError("failed to lock device")
+    }
+  }
+
+  async unlock() {
+    await this.flashing("unlock")
+    await this.fd.waitForReconnect()
+    if (await this.locked()) {
+      throw new FastbootError("failed to unlock device")
+    }
+  }
+
+  async reboot() {
+    this.logger.log("rebooting")
+    await this.fd.exec("reboot")
+  }
+
+  async rebootBootloader() {
+    this.logger.log("rebooting into bootloader")
+    this.fd.exec("reboot-bootloader")
+    await this.fd.waitForReconnect()
+  }
+
+  async rebootFastboot() {
+    this.logger.log("rebooting into fastboot")
+    this.fd.exec("reboot-fastboot")
+    await this.fd.waitForReconnect()
+  }
+
+  async doFlash(
+    partition: string,
+    blob: Blob,
+    slot: "current" | "other" | "a" | "b" = "current",
+    applyVbmeta: boolean = false,
+  ) {
+    // add _a or _b
+    //    !(await this.isUserspace()) ?
+    if (
+      partition !== "avb_custom_key" &&
+      (await this.getVar(`has-slot:${partition}`)) === "yes"
+    ) {
+      if (slot === "current") {
+        partition += "_" + (await this.currentSlot())
+      } else if (slot === "other") {
+        partition += "_" + (await this.otherSlot())
+      } else if (slot === "a" || slot === "b") {
+        partition += "_" + slot
+      } else {
+        throw new FastbootError(`Unknown Slot: ${slot}`)
+      }
+    }
+
+    const { blobSize, totalBytes, isSparse } = await parseBlobHeader(blob)
+
+    // should_flash_in_userspace() ?
+    // Logical partitions need to be resized before flashing because
+    // they're sized perfectly to the payload.
+    if (
+      (await this.isUserspace()) &&
+      (await this.getVar(`is-logical:${partition}`)) === "yes"
+    ) {
+      await this.resizePartition(partition, totalBytes)
+    }
+
+    const max = await this.maxDownloadSize()
+
+    if (blobSize > max && !isSparse) {
+      this.logger.log(`${partition} image is raw, converting to sparse`)
+      blob = await fromRaw(blob)
+    }
+
+    this.logger.log(
+      `Flashing ${totalBytes} bytes to ${partition} w/ max ${max} bytes per split`,
+    )
+
+    let splits = 0
+    let sentBytes = 0
+    for await (const split of splitBlob(blob, max)) {
+      await this.fd.transferData(split.data)
+      this.logger.log(`run command flash:${partition}`)
+      await this.fd.sendCommand(`flash:${partition}`)
+      sentBytes += split.bytes
+      splits += 1
+      this.logger.log(
+        `${partition} #${splits}) sent ${split.bytes} bytes. ${sentBytes}/${blobSize}`,
+      )
+    }
+    this.logger.log(
+      `Flashed ${partition} with ${splits} split(s). Bytes sent: ${sentBytes}`,
+    )
+  }
+
+  // fb->ResizePartition ?
+  async resizePartition(name: string, totalBytes: number) {
+    // As per AOSP fastboot, we reset the partition to 0 bytes first
+    // to optimize extent allocation before setting the actual size.
+    await this.fd.sendCommand(`resize-logical-partition:${name}:0`)
+    await this.fd.sendCommand(`resize-logical-partition:${name}:${totalBytes}`)
+  }
+
+  async flashing(command: "unlock" | "lock") {
+    if (
+      (command === "unlock" && (await this.unlocked())) ||
+      (command === "lock" && (await this.locked()))
+    ) {
+      return true
+    }
+
+    this.logger.log(`ACTION NEEDED: flashing ${command}`)
+    await this.fd.exec(`flashing ${command}`)
+    await this.fd.waitForReconnect()
+  }
+
+  // run directions, typically the contents of fastboot-info.txt
+  // retriving the flashing data from files in entries
+  async fastbootInfo(
+    entries: Entry[],
+    directions: string,
+    wipe: boolean = false,
+  ) {
+    const lines = directions
+      .split("\n")
+      .map((x) => x.trim())
+      .filter((l) => !(l == "" || l[0] == "#" || l.slice(0, 7) == "version"))
+
+    for (const line of lines) {
+      this.logger.log(`fastboot-info: ${line}`)
+      const parts = line.split(" ").map((x) => x.trim())
+      const command = parts.shift()
+
+      switch (command) {
+        case "flash": {
+          let slot = "current"
+          let applyVbmeta = false
+          let partition = null
+          let filename = null
+
+          for (const arg of parts) {
+            if (arg === "--slot-other") {
+              slot = "other"
+            } else if (arg === "--apply-vbmeta") {
+              applyVbmeta = true
+            } else if (partition == null) {
+              partition = arg
+            } else {
+              filename = arg
+            }
+          }
+
+          if (filename === null) {
+            filename = IMAGES.find(
+              (img) => img["nickname"] === partition,
+            )?.img_name
+            if (!filename) {
+              throw new Error(`Unknown partition: ${partition}`)
+            }
+          }
+
+          const entry = entries.find((e) => e.filename === filename)
+          if (!entry) {
+            throw new Error(
+              `partition ${partition} with filename ${filename} not found in zipfile.`,
+            )
+          }
+          this.logger.log(`Extracting ${filename}`)
+          const blob = await entry.getData(
+            new BlobWriter("application/octet-stream"),
+          )
+          this.logger.log(
+            `flashing partition ${partition} with ${filename} from nested zip`,
+          )
+          await this.doFlash(partition, blob, slot, applyVbmeta)
+          break
+        }
+        case "reboot":
+          if (parts[0] === "fastboot") {
+            await this.rebootFastboot()
+          } else {
+            await this.rebootBootloader()
+          }
+          break
+        case "update-super": {
+          await this.updateSuper(entries, wipe)
+          break
+        }
+        case "if-wipe":
+          if (wipe && parts[0] === "erase" && parts[1]) {
+            await this.erase(parts[1])
+          }
+          break
+        case "erase":
+          await this.erase(parts[0])
+          break
+        default:
+          throw new Error(`unknown command ${command}`)
+      }
+    }
+  }
+
+  async updateSuper(entries: Entry[], wipe: boolean) {
+    const superEmptyImage = entries.find(
+      (e) => e.filename === "super_empty.img",
+    )
+    if (!superEmptyImage) {
+      throw new FastbootError(`super_empty.img not found`)
+    }
+
+    let superName = "super"
+    try {
+      superName = await this.getVar("super-partition-name")
+    } catch (err) {}
+
+    // fastboot-info does this
+    // await this.rebootFastboot()
+
+    const blob = await superEmptyImage.getData(
+      new BlobWriter("application/octet-stream"),
+    )
+    const buffer = await blob.arrayBuffer()
+
+    await this.fd.transferData(buffer)
+    await this.fd.sendCommand(`update-super:${superName}${wipe ? ":wipe" : ""}`)
+  }
+
+  async erase(partition: string) {
+    return this.fd.exec(`erase:${partition}`)
+  }
+
+  async setActiveOtherSlot() {
+    const otherSlot = await this.otherSlot()
+    return await this.fd.exec(`set_active:${otherSlot}`)
+  }
+
+  async maxDownloadSize() {
+    try {
+      const deviceMax = parseInt(await this.getVar("max-download-size"), 16)
+      const upperLimit = 1024 * 1024 * 1024 * 1 // 1 GiB
+      return Math.min(deviceMax, upperLimit)
+    } catch (err) {
+      console.debug(err)
+    }
+    // FAIL or empty variable means no max, set a reasonable limit to conserve memory
+    return 512 * 1024 * 1024 // 512 MiB
+  }
+
+  async unlocked() {
+    return (await this.getVar("unlocked")) === "yes"
+  }
+
+  async locked() {
+    return (await this.getVar("unlocked")) === "no"
+  }
+
+  async currentSlot() {
+    return this.getVar("current-slot")
+  }
+
+  async otherSlot() {
+    const currentSlot = await this.getVar("current-slot")
+    if (currentSlot === "a") {
+      return "b"
+    } else if (currentSlot === "b") {
+      return "a"
+    } else {
+      throw new Error(
+        `Unable to determine other slot, current slot: ${currentSlot}`,
+      )
+    }
+  }
+
+  async isUserspace() {
+    return (await this.getVar("is-userspace")) === "yes"
+  }
+
+  static async create() {
+    return new FastbootClient(await this.requestUsbDevice(), window.console)
+  }
+
+  static requestUsbDevice(): Promise<USBDevice> {
+    return window.navigator.usb.requestDevice({
+      filters: [FastbootUSBDeviceFilter],
+    })
+  }
+}
+
+async function parseBlobHeader(blob: Blob): {
+  blobSize: number
+  totalBytes: number
+  isSparse: boolean
+} {
+  const FILE_HEADER_SIZE = 28
+  const blobSize = blob.size
+  let totalBytes = blobSize
+  let isSparse = false
+
+  try {
+    const fileHeader = await blob.slice(0, FILE_HEADER_SIZE).arrayBuffer()
+    const sparseHeader = parseFileHeader(fileHeader)
+    if (sparseHeader !== null) {
+      totalBytes = sparseHeader.blocks * sparseHeader.blockSize
+      isSparse = true
+    }
+  } catch (error) {
+    console.debug(error)
+    // ImageError = invalid, so keep blob.size
+  }
+  return { blobSize, totalBytes, isSparse }
+}

package/src/device.ts

@@ -0,0 +1,258 @@
+type CommandPacket = {
+  command: string
+}
+
+type ResponsePacket = {
+  status: "OKAY" | "FAIL" | "DATA" | "INFO" | "TEXT"
+  message?: string
+  dataLength?: number
+}
+
+type FastbootSession = {
+  phase: 1 | 2 | 3 | 4 | 5
+  status: null | "OKAY" | "FAIL"
+  packets: (CommandPacket | ResponsePacket)[]
+}
+
+interface Logger {
+  log(message: string): void
+}
+
+export class FastbootDeviceError extends Error {
+  status: string
+
+  constructor(status: string, message: string) {
+    super(`Bootloader replied with ${status}: ${message}`)
+    this.status = status
+    this.name = "FastbootDeviceError"
+  }
+}
+
+// implements the fastboot protocol over WebUSB
+export class FastbootDevice {
+  device: USBDevice
+  serialNumber: string;
+  in: USBEndpoint
+  out: USBEndpoint
+  session: FastbootSession
+  sessions: FastbootSession[]
+  logger: Logger
+
+  constructor(device, logger = window.console) {
+    this.device = device
+    this.serialNumber = this.device.serialNumber
+    this.session = null
+    this.sessions = []
+    this.logger = logger
+    this.setup()
+  }
+
+  // validate device and assign endpoints attributes
+  setup() {
+    if (this.device.configurations.length > 1) {
+      console.warn(
+        `device has ${device.configurations.length} configurations. Using the first one.`,
+      )
+    }
+
+    // this.in = this.device.configurations[0].interfaces[0].alternate.endpoints[0]
+    const endpoints =
+      this.device.configurations[0].interfaces[0].alternate.endpoints
+
+    if (endpoints.length !== 2) {
+      throw new Error("USB Interface must have only 2 endpoints")
+    }
+
+    for (const endpoint of endpoints) {
+      if (endpoint.direction === "in") {
+        this.in = endpoint
+      } else if (endpoint.direction === "out") {
+        this.out = endpoint
+      } else {
+        throw new Error(`Endpoint error: ${endpoint}`)
+      }
+    }
+  }
+
+  async connect() {
+    if (!this.device.opened) {
+      await this.device.open()
+    }
+    await this.device.selectConfiguration(1)
+    await this.device.claimInterface(0)
+  }
+
+  // some commands (like "flashing lock") will disconnect the device
+  // we have to re-assign this.device after it reconnects
+  async reconnect() {
+    const devices = await navigator.usb.getDevices()
+    for (const device of devices) {
+      if (device.serialNumber === this.serialNumber) {
+        this.device = device
+        this.setup()
+        await this.connect()
+        return true
+      }
+    }
+    throw new Error("Could not find device in navigator.usb.getDevices()")
+  }
+
+  waitForReconnect(): Promise<boolean> {
+    return new Promise((resolve, reject) => {
+      navigator.usb.addEventListener(
+        "connect",
+        async () => {
+          try {
+            await this.reconnect()
+            resolve(true)
+          } catch (e) {
+            reject(e)
+          }
+        },
+        { once: true },
+      )
+    })
+  }
+
+  async getPacket(): ResponsePacket {
+    this.logger.log(`receiving packet from endpoint ${this.in.endpointNumber}`)
+    const inPacket = await this.device.transferIn(this.in.endpointNumber, 256)
+    const inPacketText = new TextDecoder().decode(inPacket.data)
+    const status = inPacketText.substring(0, 4)
+    const message = inPacketText.slice(4).trim()
+    switch (status) {
+      case "INFO":
+        return { status, message: `(bootloader)  ${message}` }
+      case "TEXT":
+        return { status, message }
+      case "FAIL":
+        return { status, message }
+      case "OKAY":
+        return { status, message }
+      case "DATA": {
+        const dataLength = parseInt(inPacketText.slice(4, 12), 16)
+        return {
+          status,
+          dataLength,
+          message: `ready to transfer ${dataLength} bytes`,
+        }
+      }
+      default:
+        throw new Error(`invalid packet: ${inPacketText}`)
+    }
+  }
+
+  async getPackets() {
+    let response
+    do {
+      response = await this.getPacket()
+      this.session.packets.push(response)
+      this.logger.log(`[${response.status}] ${response.message}`)
+    } while (["INFO", "TEXT"].includes(response.status))
+  }
+
+  async sendCommand(text): ResponsePacket {
+    this.session.packets.push({ command: text } as CommandPacket)
+    const outPacket = new TextEncoder().encode(text)
+    this.logger.log(
+      `transfering "${text}" to endpoint ${this.out.endpointNumber}`,
+    )
+    const result: USBOutTransferResult = await this.device.transferOut(
+      this.out.endpointNumber,
+      outPacket,
+    )
+    await this.getPackets()
+
+    if (this.lastPacket.status === "FAIL") {
+      this.session.status = "FAIL"
+      throw new FastbootDeviceError(
+        this.lastPacket.status,
+        this.lastPacket.message,
+      )
+    } else {
+      return this.lastPacket
+    }
+  }
+
+  async exec(command): ResponsePacket {
+    if (this.isActive) {
+      throw new Error("fastboot device is busy")
+    } else if (!this.device.opened) {
+      await this.connect()
+    }
+
+    if (this.session) {
+      this.sessions.push(this.session)
+    }
+
+    this.session = { status: null, packets: [] }
+
+    return this.sendCommand(command)
+  }
+
+  async getVar(variable: FastbootClientVariables): Promise<string> {
+    await this.exec(`getvar:${variable}`)
+    return this.lastPacket.message
+  }
+
+  get lastPacket() {
+    return this.session.packets[this.session.packets.length - 1]
+  }
+
+  get isActive() {
+    if (!this.session || this.session.packets.length === 0) {
+      return false
+    }
+
+    return !["FAIL", "OKAY"].includes(this.lastPacket.status)
+  }
+
+  // send buffer to phone
+  // download:00001234 -> "DATA" -> transferOut -> "OKAY"
+  async transferData(buffer: ArrayBuffer) {
+    // Bootloader requires an 8-digit hex number
+    const xferHex = buffer.byteLength.toString(16).padStart(8, "0")
+    if (xferHex.length !== 8) {
+      throw new FastbootDeviceError(
+        "FAIL",
+        `Transfer size overflow: ${xferHex} is more than 8 digits`,
+      )
+    }
+
+    this.logger.log(`Sending command download:${xferHex}.`)
+    const response = await this.sendCommand(`download:${xferHex}`)
+
+    if (response.status !== "DATA") {
+      throw new FastbootDeviceError(
+        "FAIL",
+        `response to download:${xferHex} is ${response.status}. Expected DATA.`,
+      )
+    } else if (response.dataLength !== buffer.byteLength) {
+      throw new FastbootDeviceError(
+        "FAIL",
+        `Bootloader wants ${response.dataLength} bytes, requested to send ${buffer.byteLength} bytes`,
+      )
+    }
+
+    const BULK_TRANSFER_SIZE = 16384
+    this.logger.log(`Sending payload: ${buffer.byteLength} bytes`)
+    let i = 0
+    let remainingBytes = buffer.byteLength
+    while (remainingBytes > 0) {
+      const chunk = buffer.slice(
+        i * BULK_TRANSFER_SIZE,
+        (i + 1) * BULK_TRANSFER_SIZE,
+      )
+      if (i % 1000 === 0) {
+        this.logger.log(
+          `Sending ${chunk.byteLength} bytes to endpoint, ${remainingBytes} remaining, i=${i}`,
+        )
+      }
+      await this.device.transferOut(this.out.endpointNumber, chunk)
+      remainingBytes -= chunk.byteLength
+      i += 1
+    }
+    this.logger.log("Payload sent, waiting for response...")
+    await this.getPackets()
+  }
+}