feat: checksum extension

.babelrc

@@ -5,5 +5,6 @@
 			"corejs": false,
 			"forceAllTransforms": true
 		} ]
-	]
+	],
+	"plugins": ["@babel/transform-runtime"]
 }

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "editor.formatOnSaveMode": "modifications"
+}

demos/browser/demo.js

@@ -65,6 +65,7 @@ function startUpload () {
     endpoint,
     chunkSize,
     retryDelays: [0, 1000, 3000, 5000],
+    checksumAlgo: "sha-256",
     parallelUploads,
     metadata   : {
       filename: file.name,

lib/browser/extensions/checksum.js

@@ -0,0 +1,39 @@
+class Checksum {
+  static supportedAlogrithms = ['SHA-1', 'SHA-256', 'SHA-384', 'SHA-512'];
+
+  constructor (algo = 'SHA-256') {
+    this.algo = this._resolveAlgo(algo)
+  }
+
+  /**
+   * Resolves algorithm to one of the inbuilt types
+   * @param {String} algo contains user provided checksumAlgo option
+   */
+  _resolveAlgo = (algo) => {
+    const resolvedAlgo = Checksum.supportedAlgorithms.find(supportedAlgo => supportedAlgo === algo.toUpperCase())
+    if (!resolvedAlgo) {
+      throw new Error(
+        `tus: unsupported checksumAlgo provided. Supported values are : ${Checksum.supportedAlgorithms.join(',')}`,
+      )
+    }
+    return resolvedAlgo
+  }
+  /**
+   * Gets Hexadecimal digest using the algorithm set in this.algo
+   * @param {ArrayBuffer} data contains the chunk of data to be hashed
+   */
+
+  getHexDigest = async (data) => {
+    try {
+      const hashBuffer = await crypto.subtle.digest(this.algo, data)
+      const hashArray = Array.from(new Uint8Array(hashBuffer)) // convert buffer to byte array
+      const hashHex = hashArray
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('') // convert bytes to hex string
+      return hashHex
+    } catch (err) {
+      throw new Error('tus: could not compute checksum for integrity check')
+    }
+  };
+}
+export default Checksum

lib/node/extensions/checksum.js

@@ -0,0 +1,38 @@
+import crypto from 'crypto'
+
+class Checksum {
+  static supportedAlgorithms = ['sha1', 'sha256', 'sha384', 'sha512', 'md5'];
+
+  constructor (algo = 'sha256') {
+    this.algo = this.resolveAlgo(algo)
+  }
+
+  /**
+   * Resolves algorithm to one of the inbuilt types
+   * @param {String} algo contains user provided checksumAlgo option
+   */
+  resolveAlgo = (algo) => {
+    const resolvedAlgo = Checksum.supportedAlgorithms.find(supportedAlgo => supportedAlgo === algo.toLowerCase())
+    if (!resolvedAlgo) throw new Error(`Checksum: unsupported checksumAlgo provided. Supported values are ${Checksum.supportedAlgorithms.join(',')}`)
+    return resolvedAlgo
+  }
+
+  /**
+   * Gets Hexadecimal digest using the algorithm set in this.algo
+   * @param {ArrayBuffer} data contains the chunk of data to be hashed
+   */
+  getHexDigest = async (data) => {
+    try {
+      const hashHex = await crypto
+        .createHash(this.algo)
+        .update(data)
+        .digest('hex')
+
+      return hashHex
+    } catch (err) {
+      throw new Error('tus: could not compute checksum for integrity check')
+    }
+  };
+}
+
+export default Checksum

lib/upload.js

@@ -100,6 +100,9 @@ class BaseUpload {
     // An array of upload URLs which are used for uploading the different
     // parts, if the parallelUploads option is used.
     this._parallelUploadUrls = null
+
+    // A platform dependent checksum generator, this is instantiated if options.enableChecksum is provided
+    this._checksum = null
   }
 
   /**
@@ -531,6 +534,40 @@ class BaseUpload {
       return
     }
 
+    if (this.options.enableChecksum) {
+      const optionsReq = this._openRequest('OPTIONS', this.options.endpoint)
+      this._sendRequest(optionsReq)
+        .then((res) => {
+          const isChecksumSupported = res
+            .getHeader('Tus-Extension')
+            .split(',')
+            .includes('checksum')
+          if (!isChecksumSupported) {
+            log('Checksum is not supported by this tus server')
+            return
+          }
+          const supportedAlgorithms = res.getHeader('Tus-Checksum-Algorithm')
+          if (!supportedAlgorithms) {
+            throw new Error(
+              'tus: checksum is enabled, but Tus-Checksum-Algorithm is not defined by tus server',
+            )
+          }
+          let Checksum
+          if (window) {
+            // eslint-disable-next-line global-require
+            Checksum = require('./browser/extensions/checksum').default
+          } else {
+            // eslint-disable-next-line global-require
+            Checksum = require('./browser/extensions/checksum').default
+          }
+          this._checksum = new Checksum(
+            Checksum.supportedAlogrithms.find((supportedAlgo) => supportedAlgorithms.includes(supportedAlgo)),
+          )
+        })
+        .catch((err) => {
+          log('Failed to fetch options response', err)
+        })
+    }
     const req = this._openRequest('POST', this.options.endpoint)
 
     if (this.options.uploadLengthDeferred) {
@@ -749,11 +786,25 @@ class BaseUpload {
           req.setHeader('Upload-Length', this._size)
         }
 
-        if (value === null) {
+        if (this.options.enableChecksum) {
+          if (this._checksum) {
+            value.arrayBuffer().then((chunkBuffer) => {
+              this._checksum
+                .getHexDigest(chunkBuffer)
+                .then((hash) => {
+                  req.setHeader('Upload-Checksum', `${this._checksum.algo} ${hash}`)
+                  this._emitProgress(this._offset, this._size)
+                  return this._sendRequest(req, value)
+                })
+                .catch((err) => log(err))
+            })
+          }
+        } else if (value === null) {
           return this._sendRequest(req)
+        } else {
+          this._emitProgress(this._offset, this._size)
+          return this._sendRequest(req, value)
         }
-        this._emitProgress(this._offset, this._size)
-        return this._sendRequest(req, value)
       })
   }
 

package.json

@@ -43,7 +43,9 @@
     "@babel/helper-get-function-arity": "^7.16.7",
     "@babel/plugin-syntax-jsx": "^7.12.13",
     "@babel/plugin-transform-modules-commonjs": "^7.9.6",
+    "@babel/plugin-transform-runtime": "^7.17.0",
     "@babel/preset-env": "^7.0.0",
+    "@babel/runtime": "^7.17.9",
     "axios": "^0.27.2",
     "babelify": "^10.0.0",
     "browserify": "^17.0.0",

test/spec/test-browser-specific.js

@@ -3,6 +3,7 @@
 const assertUrlStorage = require('./helpers/assertUrlStorage')
 const { TestHttpStack, waitableFunction, wait } = require('./helpers/utils')
 const tus = require('../..')
+const { default: Checksum } = require('../../lib.es5/browser/extensions/checksum')
 
 describe('tus', () => {
   beforeEach(() => {
@@ -778,4 +779,24 @@ describe('tus', () => {
       await assertUrlStorage(tus.defaultOptions.urlStorage)
     })
   })
+
+  describe('#Checksum', () => {
+    it('should generate hex digest for a given chunk of file', async () => {
+      const checksum = new Checksum()
+      const hexDigest = await checksum.getHexDigest(
+        new TextEncoder().encode('hello'),
+      )
+      expect(hexDigest).toBe(
+        '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+      )
+    })
+
+    it('should throw an error when an unsupported algo is provided', () => {
+      try {
+        const checksum = new Checksum('md5')
+      } catch (err) {
+        expect(err.message).toContain('unsupported checksumAlgo')
+      }
+    })
+  })
 })

test/spec/test-node-specific.js

@@ -8,6 +8,7 @@ const intoStream = require('into-stream')
 const tus = require('../..')
 const assertUrlStorage = require('./helpers/assertUrlStorage')
 const { TestHttpStack, waitableFunction } = require('./helpers/utils')
+const {default: Checksum} = require('../../lib.es5/node/extensions/checksum')
 
 describe('tus', () => {
   describe('#canStoreURLs', () => {
@@ -315,6 +316,22 @@ describe('tus', () => {
     })
   })
 
+  describe('#Checksum', () => {
+    it('should generate hex digest for a given chunk of file', async () => {
+      const checksum = new Checksum();
+      const hexDigest = await checksum.getHexDigest(Buffer.from('hello', 'utf8'))
+      expect(hexDigest).toBe('2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824')
+    })
+
+    it('should throw an error when an unsupported algo is provided', () => {
+      try {
+        const checksum = new Checksum('new-algo')
+      } catch (err) {
+        expect(err).toContain('unsupported checksumAlgo');
+      }
+    })
+  })
+
   describe('#StreamSource', () => {
     it('should slice at different ranges', async () => {
       const input = stream.Readable.from(Buffer.from('ABCDEFGHIJKLMNOPQRSTUVWXYZ'), {