Bytes

Author: paulmillr

src/_arx.ts

@@ -37,6 +37,7 @@ xchacha [^2] uses the subkey and remaining 8 byte nonce with ChaCha20 as normal
  * @module
  */
 import {
+  type Bytes,
   type PRG,
   type XorStream,
   abool,
@@ -275,7 +276,7 @@ export class _XorStreamPRG implements PRG {
     this.state.set(this.randomBytes(this.state.length));
     this.reseed(seed);
   }
-  randomBytes(len: number): Uint8Array {
+  randomBytes(len: number): Bytes {
     anumber(len);
     if (len === 0) return new Uint8Array(0);
     const out = new Uint8Array(len);

src/_poly1305.ts

@@ -21,6 +21,7 @@
 import {
   abytes, aexists, aoutput, bytesToHex,
   clean, concatBytes, copyBytes, hexToNumber, numberToBytesBE,
+  type Bytes,
   type IHash2
 } from './utils.ts';
 
@@ -328,7 +329,7 @@ export class Poly1305 implements IHash2 {
     }
     return out;
   }
-  digest(): Uint8Array {
+  digest(): Bytes {
     const { buffer, outputLen } = this;
     this.digestInto(buffer);
     const res = buffer.slice(0, outputLen);

src/_polyval.ts

@@ -20,6 +20,7 @@ import {
   copyBytes,
   createView,
   u32,
+  type Bytes,
   type IHash2,
 } from './utils.ts';
 
@@ -186,7 +187,7 @@ export class GHASH implements IHash2 {
     o32[3] = s3;
     return out;
   }
-  digest(): Uint8Array {
+  digest(): Bytes {
     const res = new Uint8Array(BLOCK_SIZE);
     this.digestInto(res);
     this.destroy();

src/aes.ts

@@ -23,6 +23,7 @@ import {
   abytes, anumber, clean, complexOverlapBytes, concatBytes,
   copyBytes, createView, equalBytes, getOutput, isAligned32, overlapBytes,
   u32, u64Lengths, u8, wrapCipher,
+  type Bytes,
   type Cipher, type CipherWithOutput, type PRG
 } from './utils.ts';
 
@@ -261,8 +262,8 @@ function ctrCounter(
   xk: Uint32Array,
   nonce: Uint8Array,
   src: Uint8Array,
-  dst?: Uint8Array
-): Uint8Array {
+  dst?: Bytes
+): Bytes {
   abytes(nonce, BLOCK_SIZE, 'nonce');
   abytes(src);
   const srcLen = src.length;
@@ -303,8 +304,8 @@ function ctr32(
   isLE: boolean,
   nonce: Uint8Array,
   src: Uint8Array,
-  dst?: Uint8Array
-): Uint8Array {
+  dst?: Bytes
+): Bytes {
   abytes(nonce, BLOCK_SIZE, 'nonce');
   abytes(src);
   dst = getOutput(src.length, dst);
@@ -379,7 +380,7 @@ function validateBlockDecrypt(data: Uint8Array) {
   }
 }
 
-function validateBlockEncrypt(plaintext: Uint8Array, pcks5: boolean, dst?: Uint8Array) {
+function validateBlockEncrypt(plaintext: Uint8Array, pcks5: boolean, dst?: Bytes) {
   abytes(plaintext);
   let outLen = plaintext.length;
   const remaining = outLen % BLOCK_SIZE;

src/chacha.ts

@@ -18,6 +18,7 @@ import { type XorPRG, createCipher, createPRG, rotl } from './_arx.ts';
 import { poly1305 } from './_poly1305.ts';
 import {
   type ARXCipher,
+  type Bytes,
   type CipherWithOutput,
   type XorStream,
   abytes,
@@ -305,7 +306,7 @@ export const _poly1305_aead =
   (key: Uint8Array, nonce: Uint8Array, AAD?: Uint8Array): CipherWithOutput => {
     const tagLength = 16;
     return {
-      encrypt(plaintext: Uint8Array, output?: Uint8Array) {
+      encrypt(plaintext: Uint8Array, output?: Bytes) {
         const plength = plaintext.length;
         output = getOutput(plength + tagLength, output, false);
         output.set(plaintext);
@@ -317,7 +318,7 @@ export const _poly1305_aead =
         clean(tag);
         return output;
       },
-      decrypt(ciphertext: Uint8Array, output?: Uint8Array) {
+      decrypt(ciphertext: Uint8Array, output?: Bytes) {
         output = getOutput(ciphertext.length - tagLength, output, false);
         const data = ciphertext.subarray(0, -tagLength);
         const passedTag = ciphertext.subarray(-tagLength);

src/ff1.ts

@@ -4,7 +4,7 @@
  * @module
  */
 import { unsafe } from './aes.ts';
-import { type Cipher, abytes, anumber, bytesToNumberBE, clean, numberToBytesBE } from './utils.ts';
+import { type Bytes, type Cipher, abytes, anumber, bytesToNumberBE, clean, numberToBytesBE } from './utils.ts';
 
 // NOTE: no point in inlining encrypt instead of encryptBlock, since BigInt stuff will be slow
 const { expandKeyLE, encryptBlock } = unsafe;
@@ -141,7 +141,7 @@ const binLE = {
     }
     return x;
   },
-  decode(b: number[]): Uint8Array {
+  decode(b: number[]): Bytes {
     if (!Array.isArray(b) || b.length % 8) throw new Error('Invalid binary string');
     const res = new Uint8Array(b.length / 8);
     for (let i = 0, j = 0; i < res.length; i++) {

src/salsa.ts

@@ -19,6 +19,7 @@ import { poly1305 } from './_poly1305.ts';
 import {
   abytes,
   type ARXCipher,
+  type Bytes,
   type CipherWithOutput,
   clean,
   equalBytes,
@@ -202,7 +203,7 @@ export const xsalsa20poly1305: ARXCipher = /* @__PURE__ */ wrapCipher(
   { blockSize: 64, nonceLength: 24, tagLength: 16 },
   (key: Uint8Array, nonce: Uint8Array): CipherWithOutput => {
     return {
-      encrypt(plaintext: Uint8Array, output?: Uint8Array) {
+      encrypt(plaintext: Uint8Array, output?: Bytes): Bytes {
         // xsalsa20poly1305 optimizes by calculating auth key during the same call as encryption.
         // Unfortunately, makes it hard to separate tag calculation & encryption itself,
         // because 32 bytes is half-block of 64-byte salsa.
@@ -217,7 +218,7 @@ export const xsalsa20poly1305: ARXCipher = /* @__PURE__ */ wrapCipher(
         clean(output.subarray(0, 16), tag); // clean-up authKey remnants & copy of tag
         return output.subarray(16); // return output[16..]
       },
-      decrypt(ciphertext: Uint8Array, output?: Uint8Array) {
+      decrypt(ciphertext: Uint8Array, output?: Bytes): Bytes {
         // tmp part     passed tag    ciphertext
         // [0..32]      [32..48]      [48..]
         abytes(ciphertext);

src/utils.ts

@@ -49,12 +49,18 @@ export function aoutput(out: any, instance: any): void {
 }
 
 export type IHash = {
-  (data: string | Uint8Array): Uint8Array;
+  (data: Uint8Array): Bytes;
   blockLen: number;
   outputLen: number;
   create: any;
 };
 
+/**
+ * Unified, backwards-compatible ArrayBuffer-based Uint8Array.
+ * In ts5.5: `Uint8Array`; in ts5.9: `Uint8Array<ArrayBuffer>`.
+ */
+export type Bytes = ReturnType<typeof Uint8Array.from>;
+
 /** Generic type encompassing 8/16/32-byte arrays - but not 64-byte. */
 // prettier-ignore
 export type TypedArray = Int8Array | Uint8ClampedArray | Uint8Array |
@@ -248,10 +254,10 @@ export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
 export interface IHash2 {
   blockLen: number; // Bytes per block
   outputLen: number; // Bytes in output
-  update(buf: string | Uint8Array): this;
+  update(buf: Uint8Array): this;
   // Writes digest into buf
   digestInto(buf: Uint8Array): void;
-  digest(): Uint8Array;
+  digest(): Bytes;
   /**
    * Resets internal state. Makes Hash instance unusable.
    * Reset is impossible for keyed hashes if key is consumed into state. If digest is not consumed
@@ -265,20 +271,20 @@ export interface IHash2 {
 
 /** Sync cipher: takes byte array and returns byte array. */
 export type Cipher = {
-  encrypt(plaintext: Uint8Array): Uint8Array;
-  decrypt(ciphertext: Uint8Array): Uint8Array;
+  encrypt(plaintext: Uint8Array): Bytes;
+  decrypt(ciphertext: Uint8Array): Bytes;
 };
 
 /** Async cipher e.g. from built-in WebCrypto. */
 export type AsyncCipher = {
-  encrypt(plaintext: Uint8Array): Promise<Uint8Array>;
-  decrypt(ciphertext: Uint8Array): Promise<Uint8Array>;
+  encrypt(plaintext: Uint8Array): Promise<Bytes>;
+  decrypt(ciphertext: Uint8Array): Promise<Bytes>;
 };
 
 /** Cipher with `output` argument which can optimize by doing 1 less allocation. */
 export type CipherWithOutput = Cipher & {
-  encrypt(plaintext: Uint8Array, output?: Uint8Array): Uint8Array;
-  decrypt(ciphertext: Uint8Array, output?: Uint8Array): Uint8Array;
+  encrypt(plaintext: Uint8Array, output?: Uint8Array): Bytes;
+  decrypt(ciphertext: Uint8Array, output?: Uint8Array): Bytes;
 };
 
 /**
@@ -375,9 +381,9 @@ export type XorStream = (
  */
 export function getOutput(
   expectedLength: number,
-  out?: Uint8Array,
+  out?: Bytes,
   onlyAligned = true
-): Uint8Array {
+): Bytes {
   if (out === undefined) return new Uint8Array(expectedLength);
   if (out.length !== expectedLength)
     throw new Error(
@@ -422,7 +428,7 @@ export function randomBytes(bytesLength = 32): Uint8Array {
  */
 export interface PRG {
   addEntropy(seed: Uint8Array): void;
-  randomBytes(length: number): Uint8Array;
+  randomBytes(length: number): Bytes;
   clean(): void;
 }
 

src/webcrypto.ts

@@ -3,7 +3,7 @@
  * We use WebCrypto aka globalThis.crypto, which exists in browsers and node.js 16+.
  * @module
  */
-import { abytes, anumber, type AsyncCipher } from './utils.ts';
+import { abytes, anumber, type AsyncCipher, type Bytes } from './utils.ts';
 
 function getWebcryptoSubtle(): any {
   const cr = typeof globalThis !== 'undefined' && (globalThis as any).crypto;
@@ -16,15 +16,15 @@ function getWebcryptoSubtle(): any {
  * for example in React Native.
  */
 export const utils: {
-  encrypt: (key: Uint8Array, ...all: any[]) => Promise<Uint8Array>;
-  decrypt: (key: Uint8Array, ...all: any[]) => Promise<Uint8Array>;
+  encrypt: (key: Uint8Array, ...all: any[]) => Promise<Bytes>;
+  decrypt: (key: Uint8Array, ...all: any[]) => Promise<Bytes>;
 } = {
   async encrypt(
     key: Uint8Array,
     keyParams: any,
     cryptParams: any,
     plaintext: Uint8Array
-  ): Promise<Uint8Array> {
+  ): Promise<Bytes> {
     const cr = getWebcryptoSubtle();
     const iKey = await cr.importKey('raw', key, keyParams, true, ['encrypt']);
     const ciphertext = await cr.encrypt(cryptParams, iKey, plaintext);
@@ -35,7 +35,7 @@ export const utils: {
     keyParams: any,
     cryptParams: any,
     ciphertext: Uint8Array
-  ): Promise<Uint8Array> {
+  ): Promise<Bytes> {
     const cr = getWebcryptoSubtle();
     const iKey = await cr.importKey('raw', key, keyParams, true, ['decrypt']);
     const plaintext = await cr.decrypt(cryptParams, iKey, ciphertext);