chore: update readme

chore: readme and added warnings

chore: update readm

configs/builds.js

@@ -50,8 +50,8 @@ module.exports = {
   },
 
   'otplib-preset-default': standard('preset-default'),
-  'otplib-preset-legacy': {
-    ...standard('preset-legacy'),
+  'otplib-preset-v11': {
+    ...standard('preset-v11'),
     files: ['index.js']
   }
 };

package.json

@@ -74,7 +74,7 @@
       "packages/**/*.{js,ts}",
       "!**/node_modules/**",
       "!packages/tests-*/*",
-      "!packages/otplib-browser/*"
+      "!packages/otplib-preset-browser/*"
     ],
     "coverageDirectory": "./coverage/",
     "modulePaths": [

packages/otplib-hotp/hotp.ts

@@ -45,7 +45,7 @@ export interface HOTPOptions {
   algorithm: HashAlgorithms;
   /** Creates the digest which token is derived from. */
   createDigest: CreateDigest;
-  /** The method used to create a HMAC key (when calculating HMAC). */
+  /** Formats the secret into a HMAC key, applying transformations (like padding) where needed  */
   createHmacKey: CreateHmacKey;
   /** The number of digits a token will have. Usually 6 or 8. */
   digits: number;

packages/otplib-preset-browser/index.ts

@@ -1,12 +1,22 @@
-/* globals buffer */
+/**
+ * otplib-preset-browser
+ *
+ * Provides fully initialised classes that are targeted
+ * for a browser build.
+ *
+ * Uses:
+ *
+ * - Base32: 'plugin-base32-enc-dec'
+ * - Crypto: 'plugin-crypto-js'
+ */
 import { createDigest, createRandomBytes } from 'otplib-plugin-crypto-js';
 import { keyDecoder, keyEncoder } from 'otplib-plugin-base32-enc-dec';
 import { HOTP, TOTP, Authenticator } from 'otplib-core';
 
 // @ts-ignore
 if (typeof window === 'object' && typeof window.Buffer === 'undefined') {
   // @ts-ignore
-  window.Buffer = buffer.Buffer;
+  window.Buffer = buffer.Buffer; /* globals buffer */
 }
 
 export const hotp = new HOTP({

packages/otplib-preset-default/index.ts

@@ -1,3 +1,19 @@
+/**
+ * otplib-preset-default
+ *
+ * Provides fully initialised classes that is targeted
+ * at the node environment. This is meant for getting started
+ * quickly.
+ *
+ * If you want to use your own Base32 and/or crypto plugin, it
+ * would be better to create a new file in your project and initialise
+ * the core classes manually.
+ *
+ * Uses:
+ *
+ * - Base32: 'plugin-thirty-two'
+ * - Crypto: 'plugin-crypto'
+ */
 import { createDigest, createRandomBytes } from 'otplib-plugin-crypto';
 import { keyDecoder, keyEncoder } from 'otplib-plugin-thirty-two';
 import { HOTP, TOTP, Authenticator } from 'otplib-core';

packages/otplib-preset-legacy/index.js → packages/otplib-preset-v11/index.js

@@ -1,3 +1,16 @@
+/**
+ * otplib-preset-legacy
+ *
+ * Target: [email protected]
+ *
+ * Provides legacy class bindings for the target version of otplib.
+ * Backported class and methods will log a warning on use.
+ *
+ * Uses:
+ *
+ * - Base32: 'plugin-thirty-two'
+ * - Crypto: 'plugin-crypto'
+ */
 import { createDigest, createRandomBytes } from 'otplib-plugin-crypto';
 import { keyEncoder, keyDecoder } from 'otplib-plugin-thirty-two';
 import { HOTP, TOTP, Authenticator } from './v11';

packages/otplib-preset-legacy/v11.js → packages/otplib-preset-v11/v11.js

@@ -47,6 +47,7 @@ export function createV11(Base, legacyOptions) {
   class Legacy extends Base {
     constructor(defaultOptions = {}) {
       super(epochUnixToJS({ ...legacyOptions, ...defaultOptions }));
+      console.warn(Base.name, 'initialised with v11.x adapter');
     }
 
     static get name() {
@@ -55,22 +56,28 @@ export function createV11(Base, legacyOptions) {
     }
 
     set options(opt = {}) {
+      console.warn(
+        Base.name,
+        '.options setter will remove UNIX epoch if it is set to null.' +
+          '\n Do note that library versions above v11.x uses JavaScript epoch.'
+      );
       super.options = epochUnixToJS(opt);
     }
 
     get options() {
       console.warn(
         Base.name,
-        'The [OTP].options getter will remove epoch if it is set to null'
+        '.options getter will remove epoch if it is set to null' +
+          '\n Do note that library versions above v11.x uses JavaScript epoch.'
       );
       return epochJSToUnix(super.options);
     }
 
     get defaultOptions() {
       console.warn(
         Base.name,
-        'The [OTP].defaultOptions getter has been deprecated in favour of the [OTP].options getter' +
-          '\n\n The [OTP].options getter now returns the combined defaultOptions and options values' +
+        '.defaultOptions getter has been deprecated in favour of the .options getter' +
+          '\n\n The .options getter now returns the combined defaultOptions and options values' +
           'instead of setting options when adding defaultOptions.'
       );
 
@@ -80,7 +87,7 @@ export function createV11(Base, legacyOptions) {
     set defaultOptions(opt) {
       console.warn(
         Base.name,
-        'The [OTP].defaultOptions setter has been deprecated in favour of the [OTP].clone(defaultOptions) function'
+        '.defaultOptions setter has been deprecated in favour of the .clone(defaultOptions) method'
       );
       this._defaultOptions = Object.freeze({
         ...this._defaultOptions,
@@ -91,9 +98,10 @@ export function createV11(Base, legacyOptions) {
     get optionsAll() {
       console.warn(
         Base.name,
-        'The [OTP].optionsAll getter has been deprecated in favour of the [OTP].allOptions() function.' +
-          '\n That epoch returned here will be in Unix Epoch, while [OTP].allOptions()' +
-          ' will return JavaScript epoch.'
+        '.optionsAll getter has been deprecated in favour of the .allOptions() method.' +
+          '\n That epoch returned here will be in Unix Epoch, while .allOptions()' +
+          ' will return JavaScript epoch.' +
+          '\n Do note that library versions above v11.x uses JavaScript epoch.'
       );
       return epochJSToUnix(super.allOptions());
     }

packages/tests-suites/plugin-base32.ts

@@ -15,6 +15,11 @@ const testKeys: TestKeys[] = [
     encoded: 'NBCC6NZLM5DU4L2HMF3HS4DPNYYHK32R',
     decoded: '68442f372b67474e2f47617679706f6e30756f51'
   },
+  {
+    // ensure lowercase strings do not fail
+    encoded: 'nbcc6nzlm5du4l2hmf3hs4dpnyyhk32r',
+    decoded: '68442f372b67474e2f47617679706f6e30756f51'
+  },
   {
     encoded: 'MNWGYTSQMR4UG3ZRJ5VUQUTCGFTVMT3W',
     decoded: '636c6c4e506479436f314f6b4852623167564f76'

packages/tests-suites/plugin-crypto.ts

@@ -32,11 +32,22 @@ export function cryptoPluginTestSuite(
       });
     });
 
-    test('should create random bytes of expected length', (): void => {
-      // 10 bytes * 8 = 80 bits
-      // 80 / 4 = 20 for hex encoded;
-      const result = plugin.createRandomBytes(10, KeyEncodings.HEX);
-      expect(result.length).toBe(20);
-    });
+    test('given an invalid algorithm, createDigest should throw', (): void => {
+      const result = (): string =>
+        plugin.createDigest(
+          // @ts-ignore
+          'oops',
+          hotpCreateHmacKey(HashAlgorithms.SHA1, secret, KeyEncodings.ASCII),
+          hotpCounter(1000)
+        );
+
+      expect(result).toThrow();
+    }),
+      test('should create random bytes of expected length', (): void => {
+        // 10 bytes * 8 = 80 bits
+        // 80 / 4 = 20 for hex encoded;
+        const result = plugin.createRandomBytes(10, KeyEncodings.HEX);
+        expect(result.length).toBe(20);
+      });
   });
 }