Skip to content

A full-featured download manager.

16.6 KB
Raw Blame
import { Buffer } from 'node:buffer'
import { createHash } from 'node:crypto'
import { existsSync } from 'node:fs'
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import {
  extractLoadedMoext,
  extractMoext,
  loadMoext,
  readMoextEntry,
} from './moext-reader'

// Minimal zip writer for fixtures. yauzl reads what we write here, so we keep
// it on the central directory + local file header format with no compression.
// That keeps the fixture builder small and deterministic.

interface FakeEntry {
  name: string
  data: Buffer
  externalAttrUpper16?: number // for symlink mode bits
}

function crc32(buf: Buffer): number {
  let c = 0
  for (let i = 0; i < buf.length; i++) {
    c = c ^ buf[i]
    for (let k = 0; k < 8; k++) {
      c = (c >>> 1) ^ (0xedb88320 & -(c & 1))
    }
  }
  return (c ^ 0xffffffff) >>> 0
}

function makeZip(entries: FakeEntry[]): Buffer {
  const localParts: Buffer[] = []
  const centralParts: Buffer[] = []
  let offset = 0
  for (const e of entries) {
    const nameBuf = Buffer.from(e.name, 'utf8')
    const crc = crc32(e.data)
    const size = e.data.length

    // Local file header
    const lfh = Buffer.alloc(30)
    lfh.writeUInt32LE(0x04034b50, 0)
    lfh.writeUInt16LE(20, 4) // version needed
    lfh.writeUInt16LE(0x800, 6) // UTF-8 names
    lfh.writeUInt16LE(0, 8) // compression: stored
    lfh.writeUInt16LE(0, 10) // mod time
    lfh.writeUInt16LE(0, 12) // mod date
    lfh.writeUInt32LE(crc, 14)
    lfh.writeUInt32LE(size, 18) // compressed
    lfh.writeUInt32LE(size, 22) // uncompressed
    lfh.writeUInt16LE(nameBuf.length, 26)
    lfh.writeUInt16LE(0, 28) // extra len
    localParts.push(lfh, nameBuf, e.data)
    const localStart = offset
    offset += lfh.length + nameBuf.length + e.data.length

    // Central directory header
    const cdh = Buffer.alloc(46)
    cdh.writeUInt32LE(0x02014b50, 0)
    cdh.writeUInt16LE(20, 4) // version made by
    cdh.writeUInt16LE(20, 6) // version needed
    cdh.writeUInt16LE(0x800, 8) // UTF-8 names
    cdh.writeUInt16LE(0, 10)
    cdh.writeUInt16LE(0, 12)
    cdh.writeUInt16LE(0, 14)
    cdh.writeUInt32LE(crc, 16)
    cdh.writeUInt32LE(size, 20)
    cdh.writeUInt32LE(size, 24)
    cdh.writeUInt16LE(nameBuf.length, 28)
    cdh.writeUInt16LE(0, 30) // extra
    cdh.writeUInt16LE(0, 32) // comment
    cdh.writeUInt16LE(0, 34) // disk
    cdh.writeUInt16LE(0, 36) // internal attrs
    cdh.writeUInt32LE(((e.externalAttrUpper16 ?? 0) << 16) >>> 0, 38)
    cdh.writeUInt32LE(localStart, 42)
    centralParts.push(cdh, nameBuf)
  }

  const local = Buffer.concat(localParts)
  const central = Buffer.concat(centralParts)
  const eocd = Buffer.alloc(22)
  eocd.writeUInt32LE(0x06054b50, 0)
  eocd.writeUInt16LE(0, 4)
  eocd.writeUInt16LE(0, 6)
  eocd.writeUInt16LE(entries.length, 8)
  eocd.writeUInt16LE(entries.length, 10)
  eocd.writeUInt32LE(central.length, 12)
  eocd.writeUInt32LE(local.length, 16)
  eocd.writeUInt16LE(0, 20)
  return Buffer.concat([local, central, eocd])
}

const SYMLINK_MODE = 0o120755
const VALID_MANIFEST = JSON.stringify({
  manifestVersion: 1,
  id: 'com.example.test',
  name: 'Test Plugin',
  version: '1.0.0',
  description: 'a fixture',
  categories: ['utilities'],
  engines: { motrix: '^2.0.0' },
  main: 'dist/plugin.js',
  permissions: [],
  activationEvents: ['onStartup'],
  contributes: {},
})
const TINY_BUNDLE = Buffer.from('export default function(){};', 'utf8')
let tmp: string

beforeEach(async () => {
  tmp = await mkdtemp(path.join(tmpdir(), 'motrix-moext-'))
})

afterEach(async () => {
  await rm(tmp, { recursive: true, force: true })
})

async function writeFixture(name: string, buf: Buffer): Promise<string> {
  const p = path.join(tmp, name)
  await writeFile(p, buf)
  return p
}

async function expectPathCollision(
  fixtureName: string,
  entries: FakeEntry[]
): Promise<void> {
  const dest = path.join(tmp, `${fixtureName}-dest`)
  const moext = await writeFixture(`${fixtureName}.moext`, makeZip(entries))
  await expect(extractMoext(moext, dest)).rejects.toMatchObject({
    message: 'plugin.install.path_collision',
  })
  expect(existsSync(dest)).toBe(false)
}

describe('moext-reader', () => {
  it('valid bundle extracts and preserves bundle digest semantics', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ])
    const moext = await writeFixture('valid.moext', moextBuf)
    const dest = path.join(tmp, 'unpacked')
    const result = await extractMoext(moext, dest)
    expect(result.bundleSha256).toBe(
      createHash('sha256').update(TINY_BUNDLE).digest('hex')
    )
    expect(JSON.parse(result.manifestRaw).id).toBe('com.example.test')
    const onDisk = await readFile(path.join(dest, 'dist/plugin.js'))
    expect(onDisk.equals(TINY_BUNDLE)).toBe(true)
  })

  it('retains a complete-archive digest independently of the bundle digest', async () => {
    const baseEntries = [
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ]
    const first = makeZip([
      ...baseEntries,
      { name: 'dist/alternate.js', data: Buffer.from('first') },
    ])
    const second = makeZip([
      ...baseEntries,
      { name: 'dist/alternate.js', data: Buffer.from('second') },
    ])

    const firstLoaded = await loadMoext(
      await writeFixture('first.moext', first)
    )
    const secondLoaded = await loadMoext(
      await writeFixture('second.moext', second)
    )
    const firstResult = await extractLoadedMoext(
      firstLoaded,
      path.join(tmp, 'first')
    )
    const secondResult = await extractLoadedMoext(
      secondLoaded,
      path.join(tmp, 'second')
    )

    expect(firstLoaded.archiveSha256).not.toBe(secondLoaded.archiveSha256)
    expect(firstResult.bundleSha256).toBe(secondResult.bundleSha256)
  })

  it('rejects retained package bytes that no longer match their digest', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ])
    const loaded = await loadMoext(
      await writeFixture('mutated.moext', moextBuf)
    )
    loaded.bytes[0] ^= 0xff

    await expect(
      extractLoadedMoext(loaded, path.join(tmp, 'mutated'))
    ).rejects.toMatchObject({ message: 'plugin.install.sha256_mismatch' })
  })

  it('keeps Linux-valid case, Unicode, colon, trailing-dot, and reserved names usable', async () => {
    if (process.platform !== 'linux') return
    const entries: FakeEntry[] = [
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
      { name: 'assets/Name.txt', data: Buffer.from('upper', 'utf8') },
      { name: 'assets/name.txt', data: Buffer.from('lower', 'utf8') },
      { name: 'assets/café.json', data: Buffer.from('nfc', 'utf8') },
      { name: 'assets/cafe\u0301.json', data: Buffer.from('nfd', 'utf8') },
      { name: 'assets/name:part', data: Buffer.from('colon', 'utf8') },
      { name: 'assets/trailing.', data: Buffer.from('dot', 'utf8') },
      { name: 'assets/CON', data: Buffer.from('reserved', 'utf8') },
    ]
    const dest = path.join(tmp, 'linux-valid-dest')
    const moext = await writeFixture('linux-valid.moext', makeZip(entries))

    await extractMoext(moext, dest)

    expect(await readFile(path.join(dest, 'assets/Name.txt'), 'utf8')).toBe(
      'upper'
    )
    expect(await readFile(path.join(dest, 'assets/name.txt'), 'utf8')).toBe(
      'lower'
    )
    expect(await readFile(path.join(dest, 'assets/name:part'), 'utf8')).toBe(
      'colon'
    )
  })

  it('allows ordinary path components containing two dots', async () => {
    const dest = path.join(tmp, 'two-dots-dest')
    const moext = await writeFixture(
      'two-dots.moext',
      makeZip([
        {
          name: 'motrix-plugin.json',
          data: Buffer.from(VALID_MANIFEST, 'utf8'),
        },
        { name: 'dist/plugin.js', data: TINY_BUNDLE },
        { name: 'assets/name..part', data: Buffer.from('dots', 'utf8') },
      ])
    )

    await extractMoext(moext, dest)

    expect(await readFile(path.join(dest, 'assets/name..part'), 'utf8')).toBe(
      'dots'
    )
  })

  it('rejects exact duplicate paths', async () => {
    await expectPathCollision('exact-collision', [
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
      { name: 'assets/data.json', data: Buffer.from('{}', 'utf8') },
      { name: 'assets/data.json', data: Buffer.from('{"x":1}', 'utf8') },
    ])
  })

  it('maps an exclusive-create EEXIST to path_collision', async () => {
    const dest = path.join(tmp, 'preexisting-dest')
    await mkdir(dest, { recursive: true })
    await writeFile(path.join(dest, 'motrix-plugin.json'), 'keep')
    const moext = await writeFixture(
      'preexisting.moext',
      makeZip([
        {
          name: 'motrix-plugin.json',
          data: Buffer.from(VALID_MANIFEST, 'utf8'),
        },
        { name: 'dist/plugin.js', data: TINY_BUNDLE },
      ])
    )

    await expect(extractMoext(moext, dest)).rejects.toMatchObject({
      message: 'plugin.install.path_collision',
    })
    expect(await readFile(path.join(dest, 'motrix-plugin.json'), 'utf8')).toBe(
      'keep'
    )
  })

  it('rejects file-directory prefix conflicts in either entry order', async () => {
    const requiredEntries: FakeEntry[] = [
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ]
    await expectPathCollision('file-before-child', [
      ...requiredEntries,
      { name: 'assets', data: Buffer.from('file', 'utf8') },
      { name: 'assets/payload.js', data: Buffer.from('child', 'utf8') },
    ])
    await expectPathCollision('child-before-file', [
      ...requiredEntries,
      { name: 'assets/payload.js', data: Buffer.from('child', 'utf8') },
      { name: 'assets', data: Buffer.from('file', 'utf8') },
    ])
  })

  it('zip-slip "../escape.txt" rejected', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: '../escape.txt', data: Buffer.from('pwn', 'utf8') },
    ])
    const moext = await writeFixture('slip.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.install.zip_slip' })
  })

  it('absolute-path entry "/etc/passwd" rejected', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: '/etc/passwd', data: Buffer.from('x', 'utf8') },
    ])
    const moext = await writeFixture('abs.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.install.zip_slip' })
  })

  it('backslash entry is normalized by yauzl but missing bundle writes nothing', async () => {
    // yauzl 3.x rewrites '\' to '/' before handing the entry to us. The
    // resulting name 'a/b/c' is a valid nested path inside destDir, so the
    // path validation accepts that contained name, but the full preflight sees
    // the required bundle is missing before creating the destination tree.
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'a\\b\\c', data: Buffer.from('x', 'utf8') },
    ])
    const moext = await writeFixture('back.moext', moextBuf)
    const dest = path.join(tmp, 'unpacked')
    await expect(extractMoext(moext, dest)).rejects.toMatchObject({
      message: 'plugin.install.bundle_missing',
    })
    expect(existsSync(dest)).toBe(false)
  })

  it('symlink entry rejected via external-attr mode', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      {
        name: 'dist/plugin.js',
        data: Buffer.from('../../../etc/passwd', 'utf8'),
        externalAttrUpper16: SYMLINK_MODE,
      },
    ])
    const moext = await writeFixture('symlink.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.install.zip_symlink' })
  })

  it('bundle > 1 MB rejected via uncompressedSize', async () => {
    const big = Buffer.alloc((1 << 20) + 1, 0x61) // 1 MB + 1
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: big },
    ])
    const moext = await writeFixture('big.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.manifest.bundle_too_large' })
  })

  it('missing manifest at root rejected', async () => {
    const moextBuf = makeZip([{ name: 'dist/plugin.js', data: TINY_BUNDLE }])
    const moext = await writeFixture('no-manifest.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({
      message: 'plugin.install.manifest_not_at_root',
    })
  })

  it('missing bundle (no dist/plugin.js) rejected', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
    ])
    const moext = await writeFixture('no-bundle.moext', moextBuf)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.install.bundle_missing' })
  })

  it('total .moext file > 5 MB rejected at stat boundary', async () => {
    const big = Buffer.alloc((5 << 20) + 1, 0x62)
    const moext = await writeFixture('over.moext', big)
    await expect(
      extractMoext(moext, path.join(tmp, 'unpacked'))
    ).rejects.toMatchObject({ message: 'plugin.manifest.bundle_too_large' })
  })
})

// -----------------------------------------------------------------------
// readMoextEntry — in-memory single-entry lookup (Firefox packed-XPI read
// path, 2026-07-18 design §4). Used by PluginRegistry.applyOverlay (manifest)
// and PluginHost (executed code) once bundle.moext's signature has been
// verified, so neither ever has to trust the separately-tamperable extracted
// tree again.
// -----------------------------------------------------------------------
describe('readMoextEntry', () => {
  it('returns the exact uncompressed bytes of a matching entry', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ])
    const bytes = await readMoextEntry(moextBuf, 'dist/plugin.js')
    expect(bytes).not.toBeNull()
    expect(bytes?.equals(TINY_BUNDLE)).toBe(true)
  })

  it('returns null when the entry is absent', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
    ])
    const bytes = await readMoextEntry(moextBuf, 'dist/plugin.js')
    expect(bytes).toBeNull()
  })

  it('rejects a traversal entry name encountered while scanning, even when it is not the requested entry', async () => {
    // '../escape.txt' sorts before the requested entry in this fixture, so
    // this exercises the per-entry validation inside the scan loop (mirrors
    // extractMoext validating every entry, not just the one being written) —
    // not just a check on the caller-supplied `entryName` parameter.
    const moextBuf = makeZip([
      { name: '../escape.txt', data: Buffer.from('pwn', 'utf8') },
      { name: 'dist/plugin.js', data: TINY_BUNDLE },
    ])
    await expect(
      readMoextEntry(moextBuf, 'dist/plugin.js')
    ).rejects.toMatchObject({ message: 'plugin.install.zip_slip' })
  })

  it('rejects a traversal requested entryName upfront', async () => {
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
    ])
    await expect(
      readMoextEntry(moextBuf, '../escape.txt')
    ).rejects.toMatchObject({ message: 'plugin.install.zip_slip' })
  })

  it('enforces the per-entry uncompressed size cap', async () => {
    const big = Buffer.alloc((1 << 20) + 1, 0x61) // 1 MB + 1
    const moextBuf = makeZip([
      { name: 'motrix-plugin.json', data: Buffer.from(VALID_MANIFEST, 'utf8') },
      { name: 'dist/plugin.js', data: big },
    ])
    await expect(
      readMoextEntry(moextBuf, 'dist/plugin.js')
    ).rejects.toMatchObject({ message: 'plugin.manifest.bundle_too_large' })
  })
})