Coding Test

.github/workflows/ci.yml

@@ -4,25 +4,17 @@ name: ci
   - pull_request
 jobs:
   test:
-    name: Node ${{ matrix.node }} / ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    environment: ci
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-        node:
-          - '14'
+    name: Test
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v2.4.0
       - uses: actions/setup-node@v2
         with:
-          node-version: ${{ matrix.node }}
+          node-version: 16
       - run: npm install
       - run: npm run build --if-present
       - run: echo "127.0.0.1 airtap.local" | sudo tee -a /etc/hosts
-      - run: npm test
+      - run: npm run lint
         env:
           SAUCE_USERNAME: ${{ secrets.SAUCE_USERNAME }}
           SAUCE_ACCESS_KEY: ${{ secrets.SAUCE_ACCESS_KEY }}

README.md

@@ -1,4 +1,7 @@
-# wormhole-crypto [![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
+# wormhole-crypto 
+
+[![Socket Badge](https://socket.dev/api/badge/npm/package/wormhole-crypto)](https://socket.dev/npm/package/wormhole-crypto)
+[![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
 
 [ci-image]: https://img.shields.io/github/workflow/status/SocketDev/wormhole-crypto/ci/master
 [ci-url]: https://github.com/SocketDev/wormhole-crypto/actions
@@ -187,6 +190,21 @@ Returns: `Promise[ReadableStream]`
 Returns a `Promise` that resolves to a `ReadableStream` decryption stream that
 consumes the data in `encryptedStream` and returns a plaintext version.
 
+### `keychain.decryptStreamRange(offset, length, totalEncryptedLength)`
+
+Type: `Function`
+
+Returns: `Promise[{ ranges, decrypt }]`
+
+Returns a `Promise` that resolves to a object containing `ranges`, which is an array of
+objects containing `offset` and `length` integers specifying the encrypted byte ranges
+that are needed to decrypt the client's specified range, and a `decrypt` function.
+
+Once the client has gathered a stream for each byte range in `ranges`, the client
+should call `decrypt(streams)`, where `streams` is an array of `ReadableStream` objects,
+one for each of the requested ranges. `decrypt` will then return a `ReadableStream`
+containing the plaintext data for the client's desired byte range.
+
 #### `encryptedStream`
 
 Type: `ReadableStream`

lib/concat-streams.js

@@ -0,0 +1,49 @@
+/* eslint-env browser */
+
+/**
+ * Concatenates the array of ReadableStreams passed in `inputStreams` into a single
+ * ReadableStream.
+ *
+ * @param {ReadableStream[]} inputStreams
+ * @returns ReadableStream
+ */
+export function concatStreams (inputStreams) {
+  let currentReader = null
+
+  // Move to the next stream
+  const nextStream = (controller) => {
+    const stream = inputStreams.shift()
+    if (stream !== undefined) {
+      currentReader = stream.getReader()
+    } else {
+      currentReader = null
+      controller.close()
+    }
+  }
+
+  return new ReadableStream({
+    start (controller) {
+      nextStream(controller)
+    },
+
+    async pull (controller) {
+      // eslint-disable-next-line no-unmodified-loop-condition
+      while (currentReader !== null) {
+        const { value, done } = await currentReader.read()
+        if (done) {
+          nextStream(controller)
+        } else {
+          controller.enqueue(value)
+          break
+        }
+      }
+    },
+
+    async cancel (reason) {
+      await Promise.all([
+        currentReader && currentReader.cancel(reason),
+        ...inputStreams.map(stream => stream.cancel(reason))
+      ])
+    }
+  })
+}

lib/ece.js

@@ -5,7 +5,9 @@
  * specification. See: https://tools.ietf.org/html/rfc8188
  */
 
+import { concatStreams } from './concat-streams.js'
 import { transformStream } from './transform-stream.js'
+import { ExtractTransformer } from './extract-transformer.js'
 import { SliceTransformer } from './slice-transformer.js'
 
 const MODE_ENCRYPT = 'encrypt'
@@ -79,11 +81,12 @@ export function encryptStream (
   const stream = transformStream(
     input,
     new SliceTransformer(rs - TAG_LENGTH - 1)
-  )
+  ).readable
+
   return transformStream(
     stream,
     new ECETransformer(MODE_ENCRYPT, secretKey, rs, salt)
-  )
+  ).readable
 }
 
 /**
@@ -94,11 +97,92 @@ export function encryptStream (
  * rs:        int containing record size, optional
  */
 export function decryptStream (input, secretKey, rs = RECORD_SIZE) {
-  const stream = transformStream(input, new SliceTransformer(HEADER_LENGTH, rs))
+  const stream = transformStream(input, new SliceTransformer(HEADER_LENGTH, rs)).readable
+
   return transformStream(
     stream,
-    new ECETransformer(MODE_DECRYPT, secretKey, rs)
-  )
+    new ECETransformer(MODE_DECRYPT, secretKey, rs, null)
+  ).readable
+}
+
+/**
+ * Given a desired plaintext byte range specified by `offset` and `length`, and the
+ * total size of the encrypted stream in `totalEncryptedLength`, provides a mechanism to
+ * decrypt that range.
+ *
+ * To decrypt an arbitrary plaintext range, the client will need to supply multiple
+ * (currently always two) ranges of encrypted data. `decryptStreamRange` returns a promise
+ * that resolves to an object containing `ranges`, which is an array of { offset, length }
+ * entries specifying the needed encrypted byte ranges, and `encrypt`, a callback function.
+ *
+ * Once the client has gathered an array `streams` of encrypted ReadableStreams, one for
+ * each of these ranges, it should call `encrypt(streams)`. This will then return the final
+ * plaintext ReadableStream.
+ *
+ * secretKey:             CryptoKey containing secret key of size KEY_LENGTH
+ * offset:                int containing plaintext byte offset at which to start decryption
+ * length:                int containing the number of plaintext bytes to decrypt
+ * totalEncryptedLength:  The total number of bytes in the encrypted stream
+ * rs:                    int containing record size, optional
+ */
+export function decryptStreamRange (secretKey, offset, length, totalEncryptedLength, rs = RECORD_SIZE) {
+  if (!Number.isInteger(rs)) {
+    throw new TypeError('rs')
+  }
+
+  // Chunk metadata, tag and delimiter
+  const chunkMetaLength = TAG_LENGTH + 1
+
+  // First record needed to decrypt the range
+  const startRecord = Math.floor(offset / (rs - chunkMetaLength))
+  const offsetInStartRecord = offset % (rs - chunkMetaLength)
+
+  // Record after the last record needed to decrypt the range
+  const endRecord = Math.ceil((offset + length) / (rs - chunkMetaLength))
+
+  // Range needed for data (not header) stream
+  const dataOffset = HEADER_LENGTH + startRecord * rs
+  let dataEnd = HEADER_LENGTH + endRecord * rs // exclusive
+
+  // Determine if the stream ends at the end of the encrypted file.
+  // This is necessary to correctly validate the padding of the final record.
+  const endsPrematurely = dataEnd < totalEncryptedLength
+  if (!endsPrematurely) {
+    dataEnd = totalEncryptedLength
+  }
+
+  return {
+    ranges: [
+      {
+        offset: 0,
+        length: HEADER_LENGTH
+      }, {
+        offset: dataOffset,
+        length: dataEnd - dataOffset
+      }
+    ],
+    decrypt: (streams) => {
+      if (!(streams.every(stream => stream instanceof ReadableStream))) {
+        throw new TypeError('stream')
+      }
+
+      // Combine the header and data streams, and then slice how ECETransformer expects
+      const encryptedStream = transformStream(concatStreams(streams), new SliceTransformer(HEADER_LENGTH, rs)).readable
+
+      // Plaintext stream of needed records
+      const plaintextStream = transformStream(
+        encryptedStream,
+        new ECETransformer(MODE_DECRYPT, secretKey, rs, null, {
+          startSeq: startRecord,
+          endSeq: endRecord,
+          endsPrematurely
+        })
+      ).readable
+
+      // Extract the exact needed bytes from the plaintext stream
+      return transformStream(plaintextStream, new ExtractTransformer(offsetInStartRecord, length)).readable
+    }
+  }
 }
 
 function checkSecretKey (secretKey) {
@@ -123,7 +207,7 @@ function generateSalt (len) {
 }
 
 class ECETransformer {
-  constructor (mode, secretKey, rs, salt) {
+  constructor (mode, secretKey, rs, salt, seekOpts = {}) {
     if (mode !== MODE_ENCRYPT && mode !== MODE_DECRYPT) {
       throw new Error('mode must be either encrypt or decrypt')
     }
@@ -136,6 +220,12 @@ class ECETransformer {
     this.rs = rs
     this.salt = salt
 
+    // seekOpts can contain (for decryption only):
+    // startSeq: first record sequence number
+    // endSeq: last record sequence number + 1 (exclusive)
+    // endsPrematurely: true if the last record should have non-final padding
+    this.seekOpts = seekOpts
+
     // sequence number. -1 is the header, 0 is the first data chunk
     this.seq = -1
     this.prevChunk = null
@@ -307,9 +397,28 @@ class ECETransformer {
 
         this.key = await this.generateKey()
         this.nonceBase = await this.generateNonceBase()
+
+        const startSeq = this.seekOpts.startSeq
+        if (startSeq != null && startSeq > 0) {
+          // update the sequence number if decryption doesn't start
+          // at seq = 0
+          this.seq += startSeq
+        }
       } else {
+        let expectEndPadding = false
+        if (isLast) {
+          // verify encrypted stream length even when seeking
+          const endSeq = this.seekOpts.endSeq
+          if (endSeq != null && endSeq !== this.seq + 1) {
+            throw new Error('Incorrect encrypted stream length')
+          }
+
+          // if the stream ends prematurely, expect a non-end padding byte
+          expectEndPadding = !this.seekOpts.endsPrematurely
+        }
+
         controller.enqueue(
-          await this.decryptRecord(this.prevChunk, this.seq, isLast)
+          await this.decryptRecord(this.prevChunk, this.seq, expectEndPadding)
         )
       }
     }

lib/extract-transformer.js

@@ -0,0 +1,45 @@
+/* eslint-env browser */
+
+/**
+ * Tranform stream that extracts `length` bytes starting at `offset` and turns
+ * that result into a new stream. If the input stream ends before `length` bytes,
+ * the output stream will error.
+ *
+ * offset: The number of bytes to skip before starting the output stream
+ * length: The number of bytes to include in the output stream. All further
+ *         input data will be discarded.
+ */
+
+export class ExtractTransformer {
+  constructor (offset, length) {
+    // desired range to extract
+    this.extractStart = offset
+    this.extractEnd = offset + length // exclusive end
+
+    this.offset = 0 // current offset into input stream
+  }
+
+  transform (chunk, controller) {
+    // The start and end of `chunk` relative to the entire input stream
+    const chunkStart = this.offset
+    const chunkEnd = this.offset + chunk.byteLength // exclusive end
+    this.offset = chunkEnd
+
+    // What part of `chunk` belongs in the output stream?
+    const sliceStart = Math.max(this.extractStart - chunkStart, 0)
+    const sliceEnd = Math.min(this.extractEnd - chunkStart, chunk.byteLength)
+
+    // This chunk is entirely outside the range to extract
+    if (sliceStart >= chunk.byteLength || sliceEnd <= 0) {
+      return
+    }
+
+    controller.enqueue(chunk.subarray(sliceStart, sliceEnd))
+  }
+
+  flush (controller) {
+    if (this.offset < this.extractEnd) {
+      controller.error(new Error('Stream passed through ExtractTransformer ended early'))
+    }
+  }
+}

lib/keychain.js

@@ -2,6 +2,7 @@
 
 import {
   decryptStream,
+  decryptStreamRange,
   encryptStream
 } from './ece.js'
 
@@ -140,6 +141,21 @@ export class Keychain {
     return decryptStream(encryptedStream, mainKey)
   }
 
+  async decryptStreamRange (offset, length, totalEncryptedLength) {
+    if (!Number.isInteger(offset)) {
+      throw new TypeError('offset')
+    }
+    if (!Number.isInteger(length)) {
+      throw new TypeError('length')
+    }
+    if (!Number.isInteger(totalEncryptedLength)) {
+      throw new TypeError('totalEncryptedLength')
+    }
+
+    const mainKey = await this.mainKeyPromise
+    return decryptStreamRange(mainKey, offset, length, totalEncryptedLength)
+  }
+
   async encryptMeta (meta) {
     if (!(meta instanceof Uint8Array)) {
       throw new TypeError('meta')