General Refresh: rewrite as TypeScript with both CommonJS and ESM + t…

…ree shaking support

.github/workflows/config.yml

@@ -10,14 +10,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
         with:
-          node-version: 14.x
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run test
-      - run: |
-          npm run build
-          git diff --exit-code
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: pnpm run lint
+      - run: pnpm run coverage
+      - run: pnpm run build

.gitignore

@@ -1 +1,5 @@
 node_modules/
+dist
+coverage
+.pnpm-store/
+*.tgz

README.md

@@ -1,32 +1,81 @@
 ### deoxysii.js - JavaScript Deoxys-II-256-128
 ![GitHub CI](https://github.com/oasisprotocol/deoxysii-js/actions/workflows/config.yml/badge.svg)
+[![version][deoxysii-version]][deoxysii-npm]
+[![size][deoxysii-size]][deoxysii-bundlephobia]
+![downloads][deoxysii-downloads]
 
-> When I find my code in tons of trouble,
-> Friends and colleagues come to me,
-> Speaking words of wisdom:
-> "Write in C."
+[deoxysii-npm]: https://www.npmjs.com/package/@oasisprotocol/deoxysii
+[deoxysii-version]: https://img.shields.io/npm/v/@oasisprotocol/deoxysii
+[deoxysii-size]: https://img.shields.io/bundlephobia/minzip/@oasisprotocol/deoxysii
+[deoxysii-bundlephobia]: https://bundlephobia.com/package/@oasisprotocol/deoxysii
+[deoxysii-downloads]: https://img.shields.io/npm/dm/@oasisprotocol/deoxysii.svg
 
 This package provides a pure-JavaScript implementation of the
 [Deoxys-II-256-128 v1.43][1] algorithm from the [final CAESAR portfolio][2].
 
-#### Implementations
+> Deoxys is an authenticated encryption scheme based on a 128-bit lightweight
+> ad-hoc tweakable block cipher. It may be used in two modes to handle
+> nonce-respecting users (Deoxys-I) or nonce-reusing user (Deoxys-II).
+>
+> It has been designed by [Jérémy Jean][3], [Ivica Nikolić][4], [Thomas Peyrin][5] and [Yannick Seurin][6].
 
- * (`ct32`) Bitsliced implementation.
+[1]: https://sites.google.com/view/deoxyscipher
+[2]: https://competitions.cr.yp.to/caesar-submissions.html
+[3]: http://jeremy.jean.free.fr/
+[4]: https://sites.google.com/view/ivica-nikolic-sg/home
+[5]: https://thomaspeyrin.github.io/web/
+[6]: https://yannickseurin.github.io/
 
- * (`vartime`) Variable time implementation with a table driven
-   AES round function.
+## Usage
 
-#### Notes
+Install the package as a dependency of your project:
 
-It is unclear what the various JavaScript implementations will do to the
-`ct32` code or the underlying bitsliced AES round function, and it is
-quite possible that it may be vulnerable to side channels.
+```shell
+npm add '@oasisprotocol/deoxysii'
+```
 
-Performance for both implementation are utterly abysimal, however `vartime`
-is approximately twice the speed of `ct32`.
+The `AEAD` class can then be used to encrypt and decrypt, with an optional
+authenticated data field which can be very useful when constructing protocols.
 
-Users that require a more performant implementation are suggested to
-investigate WebAssembly, or (even better) calling native code.
+```typescript
+import { AEAD, KeySize, NonceSize } from '@oasisprotocol/deoxysii';
 
-[1]: https://sites.google.com/view/deoxyscipher
-[2]: https://competitions.cr.yp.to/caesar-submissions.html
+// Define a key (ensure the size matches requirements)
+const key = crypto.getRandomValues(new Uint8Array(KeySize));
+const aead = new AEAD(key);
+
+// Encryption
+const nonce = crypto.getRandomValues(new Uint8Array(NonceSize));
+const plaintext = new TextEncoder().encode("Hello World");
+const associatedData = new Uint8Array([0x1, 0x2, 0x3]);
+
+const encrypted = aead.encrypt(nonce, plaintext, associatedData);
+console.log('Encrypted:', encrypted);
+
+// Decryption
+try {
+    const decrypted = aead.decrypt(nonce, encrypted, associatedData);
+    console.log('Decrypted:', new TextDecoder().decode(decrypted));
+} catch (error) {
+    console.error('Decryption failed:', error);
+}
+```
+
+## Notes
+
+> [!WARNING]
+> It is unclear what the various JavaScript implementations will do to the
+> `ct32` code or the underlying bitsliced AES round function, and it is
+> quite possible that it may be vulnerable to side channels.
+>
+> Users that require a more performant and secure implementation are suggested
+> to investigate WebAssembly, or (even better) calling native code.
+
+#### Acknowledgements
+
+This MIT licensed project utilizes modified code originally developed by Franz X
+Antesberger. The original code for `uint32.js` is available at [fxa/uint32.js].
+We have adapted this code for TypeScript. We appreciate the contributions of
+Franz X Antesberger to the open-source community.
+
+[fxa/uint32.js]: https://github.com/fxa/uint32.js

biome.json

@@ -0,0 +1,12 @@
+{
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"json": {
+		"parser": {
+			"allowComments": true
+		}
+	}
+}