@punikonta/node-otp 0.0.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License
+
+Copyright (c) Marcel Jovic <punikonta@protonmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# Dependency free OTP implementation
+
+Simple and dependency free OTP implementation (HOTP, TOTP) for Node.js written in TypeScript. Passes RFC test vectors and works with common authenticator apps.
+
+## Features
+
+- HOTP
+- TOTP (builds on top of HOTP)
+- `otpauth://` URL generation
+
+Generating QR codes for `otpauth://` URLs is **not** within the scope of this library. There are [plenty of good QR code libraries](https://www.npmjs.com/search?q=qr) out there. Just run your URL through one of them and you're good to go. There's an example QR code that works in conjunction with the example code below if you want to test it with your own authenticator app, though.
+
+## Installation
+
+```bash
+npm install @punikonta/node-otp
+```
+
+## Example
+
+Example usage for TOTP in plain JavaScript:
+
+```javascript
+import Otp from '@punikonta/node-otp'
+
+// example 128 bit secret for demonstration only! don't use this in your application.
+// this must be random, stored securely and be unique for each user.
+const secret = Buffer.from('8eddb53e05fa936c2530c8045a58f81b', 'hex')
+
+// options are optional. these are the defaults and common practice.
+// just omit the options parameter if you're fine with the defaults.
+const options = {
+    algorithm: Otp.HashAlgorithm.SHA1,
+    digits: 6,
+    period: 30,
+}
+
+const now = Date.now()
+
+const token = Otp.Totp.generate(secret, now, options)
+const remaining = Otp.Totp.remaining(options.period, now)
+const url = Otp.Url.getTotpUrl('example.com', 'foobar', secret, options)
+
+// default value. omit if you're fine with the default.
+const window = 1
+const valid = Otp.Totp.validate('123456', secret, now, window, options)
+
+console.log(`token: ${token}`)
+console.log(`valid for ${remaining.toFixed(2)} seconds`)
+console.log(url)
+console.log(`is 123456 valid? ${valid ? 'yes' : 'no'}`)
+```
+
+If you want to verify the example right away with an authenticator app, you can use the following QR code without having to generate one yourself:
+
+![example QR code](assets/example.png)
+
+`otpauth://totp/example.com:foobar?secret=R3O3KPQF7KJWYJJQZACFUWHYDM&algorithm=SHA1&digits=6&period=30&issuer=example.com`
+
+## Motivation
+
+I wanted a project with a small scope to get my hands dirty with TypeScript and NPM packaging. Also I've been looking for a TOTP library at the same time. I couldn't find one that I liked, so I decided to create my own. TOTP builds on top of HOTP, so I implemented that as well.
+
+## Remarks
+
+I've successfully tested the TOTP functionality with the following authenticator apps:
+
+- Authy
+- Google Authenticator
+- Microsoft Authenticator
+- Proton Authenticator
+- Bitwarden Authenticator
+
+Double check if you want to use anything but `SHA1` as your hash algorithm. Some popular authenticator apps don't support anything else and even go as far as completely ignoring that parameter, silently giving the user wrong tokens. To catch this and other issues early, your onboarding flow should implement a successful token readback while setting up 2FA anyway.
+
+Also don't use a `window` value other than `0` for HOTP unless you know what you're doing. Managing the HOTP counter is up to you.
+
+The default `window` value of `1` for TOTP generally is fine and common practice to mitigate small clock drifts between the server and the user.
+
+## API
+
+The API uses the following types and enums:
+
+```typescript
+enum HashAlgorithm {
+    SHA1 = 'sha1',
+    SHA256 = 'sha256',
+    SHA384 = 'sha384',
+    SHA512 = 'sha512',
+}
+
+type HotpOptions = {
+    algorithm: HashAlgorithm
+    digits: number
+}
+
+type TotpOptions = {
+    algorithm: HashAlgorithm
+    digits: number
+    period: number
+}
+```
+
+### HOTP
+
+```typescript
+Hotp.generate(
+    secret: Buffer,
+    counter: number,
+    options?: Partial<HotpOptions>
+): string
+
+Hotp.validate(
+    token: string,
+    secret: Buffer,
+    counter: number,
+    window: number = 0,
+    options?: Partial<HotpOptions>
+): boolean
+
+// default values for option parameters that are omitted
+static readonly DEFAULTS: HotpOptions = {
+    algorithm: HashAlgorithm.SHA1,
+    digits: 6,
+}
+```
+
+### TOTP
+
+```typescript
+Totp.generate(
+    secret: Buffer,
+    time: number = Date.now(),
+    options?: Partial<TotpOptions>
+): string
+
+Totp.validate(
+    token: string,
+    secret: Buffer,
+    time: number = Date.now(),
+    window: number = 1,
+    options?: Partial<TotpOptions>
+): boolean
+
+// remaining time until next token (seconds, fractional)
+Totp.remaining(
+    period: number = 30,
+    time: number = Date.now()
+): number
+
+// default values for option parameters that are omitted
+static readonly DEFAULTS: TotpOptions = {
+    algorithm: HashAlgorithm.SHA1,
+    digits: 6,
+    period: 30,
+}
+```
+
+### URL
+
+```typescript
+// HOTP
+Url.getHotpUrl(
+    issuer: string, // usually a domain or application name
+    label: string, // usually the username or email of the user
+    secret: Buffer,
+    counter: number,
+    options?: Partial<HotpOptions>
+): string
+
+// TOTP
+Url.getTotpUrl(
+    issuer: string, // usually a domain or application name
+    label: string, // usually the username or email of the user
+    secret: Buffer,
+    options?: Partial<TotpOptions>
+): string
+```
+
+## TODO
+
+Probably a good idea to add some sanity checks in the future, e.g. for nonsensical stuff like negative periods, windows or missing mandatory parameters.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { Buffer } from 'node:buffer';
+declare namespace Otp {
+    const enum HashAlgorithm {
+        SHA1 = "sha1",
+        SHA256 = "sha256",
+        SHA384 = "sha384",
+        SHA512 = "sha512"
+    }
+    type HotpOptions = {
+        algorithm: HashAlgorithm;
+        digits: number;
+    };
+    type TotpOptions = {
+        algorithm: HashAlgorithm;
+        digits: number;
+        period: number;
+    };
+    class Hotp {
+        static readonly DEFAULTS: HotpOptions;
+        static generate(secret: Buffer, counter: number, options?: Partial<HotpOptions>): string;
+        static validate(token: string, secret: Buffer, counter: number, window?: number, options?: Partial<HotpOptions>): boolean;
+    }
+    class Totp {
+        static readonly DEFAULTS: TotpOptions;
+        static generate(secret: Buffer, time: number, options?: Partial<TotpOptions>): string;
+        static validate(token: string, secret: Buffer, time?: number, window?: number, options?: Partial<TotpOptions>): boolean;
+        static remaining(period?: number, time?: number): number;
+        static timeToCounter(time: number, period: number): number;
+    }
+    class Url {
+        static getHotpUrl(issuer: string, label: string, secret: Buffer, counter: number, options?: Partial<HotpOptions>): string;
+        static getTotpUrl(issuer: string, label: string, secret: Buffer, options?: Partial<TotpOptions>): string;
+    }
+}
+export default Otp;

package/dist/index.js

@@ -0,0 +1,143 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+var Otp;
+(function (Otp) {
+    let HashAlgorithm;
+    (function (HashAlgorithm) {
+        HashAlgorithm["SHA1"] = "sha1";
+        HashAlgorithm["SHA256"] = "sha256";
+        HashAlgorithm["SHA384"] = "sha384";
+        HashAlgorithm["SHA512"] = "sha512";
+    })(HashAlgorithm = Otp.HashAlgorithm || (Otp.HashAlgorithm = {}));
+    class Hotp {
+        static generate(secret, counter, options) {
+            const opts = Object.assign(Object.assign({}, this.DEFAULTS), options);
+            const bytes = Buffer.alloc(8);
+            bytes.writeBigUInt64BE(BigInt(counter));
+            const hmac = createHmac(opts.algorithm, secret);
+            hmac.update(bytes);
+            const hash = hmac.digest();
+            const offset = hash[hash.length - 1] & 0xf;
+            const token = ((hash[offset] & 0x7f) << 24 >>> 0)
+                | hash[offset + 1] << 16
+                | hash[offset + 2] << 8
+                | hash[offset + 3];
+            return (token % (Math.pow(10, opts.digits))).toString().padStart(opts.digits, '0');
+        }
+        static validate(token, secret, counter, window = 0, options) {
+            const opts = Object.assign(Object.assign({}, this.DEFAULTS), options);
+            if (token.length != opts.digits)
+                return false;
+            const compare = (counter) => {
+                const generated = Hotp.generate(secret, counter, opts);
+                const token_buffer = Buffer.from(token);
+                const generated_buffer = Buffer.from(generated);
+                if (token_buffer.length != generated_buffer.length)
+                    return false;
+                return timingSafeEqual(token_buffer, generated_buffer);
+            };
+            if (compare(counter))
+                return true;
+            for (let i = 1; i <= window; i++) {
+                if (compare(counter + i))
+                    return true;
+                if (compare(counter - i))
+                    return true;
+            }
+            return false;
+        }
+    }
+    Hotp.DEFAULTS = {
+        algorithm: HashAlgorithm.SHA1,
+        digits: 6,
+    };
+    Otp.Hotp = Hotp;
+    class Totp {
+        static generate(secret, time, options) {
+            const opts = Object.assign(Object.assign({}, this.DEFAULTS), options);
+            const counter = Totp.timeToCounter(time, opts.period);
+            return Hotp.generate(secret, counter, opts);
+        }
+        static validate(token, secret, time = Date.now(), window = 1, options) {
+            const opts = Object.assign(Object.assign({}, this.DEFAULTS), options);
+            const counter = Totp.timeToCounter(time, opts.period);
+            return Hotp.validate(token, secret, counter, window, opts);
+        }
+        static remaining(period = 30, time = Date.now()) {
+            return period - (time / 1000) % period;
+        }
+        static timeToCounter(time, period) {
+            return Math.floor((time / 1000) / period);
+        }
+    }
+    Totp.DEFAULTS = {
+        algorithm: HashAlgorithm.SHA1,
+        digits: 6,
+        period: 30,
+    };
+    Otp.Totp = Totp;
+    class Base32 {
+        static encode(buffer) {
+            let bits = 0;
+            let value = 0;
+            let output = '';
+            for (let i = 0; i < buffer.length; i++) {
+                value = (value << 8) | buffer[i];
+                bits += 8;
+                while (bits >= 5) {
+                    output += this.ALPHABET[(value >>> (bits - 5)) & 31];
+                    bits -= 5;
+                }
+            }
+            if (bits > 0) {
+                output += this.ALPHABET[(value << (5 - bits)) & 31];
+            }
+            return output;
+        }
+        static decode(str) {
+            const cleaned = str.toUpperCase().trim().replace(/[^A-Z2-7]/g, '');
+            const buffer = Buffer.alloc(Math.floor((cleaned.length * 5) / 8));
+            let bits = 0;
+            let value = 0;
+            let index = 0;
+            for (let i = 0; i < cleaned.length; i++) {
+                const val = this.ALPHABET.indexOf(cleaned[i]);
+                if (val === -1)
+                    throw new Error('Invalid character in Base32 string');
+                value = (value << 5) | val;
+                bits += 5;
+                if (bits >= 8) {
+                    buffer[index++] = (value >>> (bits - 8)) & 255;
+                    bits -= 8;
+                }
+            }
+            return buffer;
+        }
+    }
+    Base32.ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+    class Url {
+        static getHotpUrl(issuer, label, secret, counter, options) {
+            const opts = Object.assign(Object.assign({}, Hotp.DEFAULTS), options);
+            const url = new URL(`otpauth://hotp/${issuer}:${label}`);
+            url.searchParams.set('secret', Base32.encode(secret));
+            url.searchParams.set('algorithm', opts.algorithm.toUpperCase());
+            url.searchParams.set('digits', opts.digits.toString());
+            url.searchParams.set('counter', counter.toString());
+            url.searchParams.set('issuer', issuer);
+            return url.toString();
+        }
+        static getTotpUrl(issuer, label, secret, options) {
+            const opts = Object.assign(Object.assign({}, Totp.DEFAULTS), options);
+            const url = new URL(`otpauth://totp/${issuer}:${label}`);
+            url.searchParams.set('secret', Base32.encode(secret));
+            url.searchParams.set('algorithm', opts.algorithm.toUpperCase());
+            url.searchParams.set('digits', opts.digits.toString());
+            url.searchParams.set('period', opts.period.toString());
+            url.searchParams.set('issuer', issuer);
+            return url.toString();
+        }
+    }
+    Otp.Url = Url;
+})(Otp || (Otp = {}));
+export default Otp;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/index.ts

@@ -0,0 +1,169 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+
+namespace Otp {
+    export const enum HashAlgorithm {
+        SHA1 = 'sha1',
+        SHA256 = 'sha256',
+        SHA384 = 'sha384',
+        SHA512 = 'sha512',
+    }
+
+    export type HotpOptions = {
+        algorithm: HashAlgorithm
+        digits: number
+    }
+
+    export type TotpOptions = {
+        algorithm: HashAlgorithm
+        digits: number
+        period: number
+    }
+
+    export class Hotp {
+        static readonly DEFAULTS: HotpOptions = {
+            algorithm: HashAlgorithm.SHA1,
+            digits: 6,
+        }
+
+        static generate(secret: Buffer, counter: number, options?: Partial<HotpOptions>): string {
+            const opts = { ...this.DEFAULTS, ...options }
+            const bytes = Buffer.alloc(8)
+            bytes.writeBigUInt64BE(BigInt(counter))
+
+            const hmac = createHmac(opts.algorithm, secret)
+            hmac.update(bytes)
+            const hash = hmac.digest()
+
+            const offset = hash[hash.length - 1] & 0xf
+            const token = ((hash[offset] & 0x7f) << 24 >>> 0)
+                | hash[offset + 1] << 16
+                | hash[offset + 2] << 8
+                | hash[offset + 3]
+
+            return (token % (10 ** opts.digits)).toString().padStart(opts.digits, '0')
+        }
+
+        static validate(token: string, secret: Buffer, counter: number, window: number = 0, options?: Partial<HotpOptions>): boolean {
+            const opts = { ...this.DEFAULTS, ...options }
+            if (token.length != opts.digits) return false
+            const compare = (counter: number) => {
+                const generated = Hotp.generate(secret, counter, opts)
+                const token_buffer = Buffer.from(token)
+                const generated_buffer = Buffer.from(generated)
+                if (token_buffer.length != generated_buffer.length) return false
+                return timingSafeEqual(token_buffer, generated_buffer)
+            }
+            if (compare(counter)) return true
+            for (let i = 1; i <= window; i++) {
+                if (compare(counter + i)) return true
+                if (compare(counter - i)) return true
+            }
+            return false
+        }
+    }
+
+    export class Totp {
+        static readonly DEFAULTS: TotpOptions = {
+            algorithm: HashAlgorithm.SHA1,
+            digits: 6,
+            period: 30,
+        }
+
+        static generate(secret: Buffer, time: number, options?: Partial<TotpOptions>): string {
+            const opts = { ...this.DEFAULTS, ...options }
+            const counter = Totp.timeToCounter(time, opts.period)
+            return Hotp.generate(secret, counter, opts)
+        }
+
+        static validate(token: string, secret: Buffer, time: number = Date.now(), window: number = 1, options?: Partial<TotpOptions>): boolean {
+            const opts = { ...this.DEFAULTS, ...options }
+            const counter = Totp.timeToCounter(time, opts.period)
+            return Hotp.validate(token, secret, counter, window, opts)
+        }
+
+        static remaining(period: number = 30, time: number = Date.now()) {
+            return period - (time / 1000) % period
+        }
+
+        static timeToCounter(time: number, period: number): number {
+            return Math.floor((time / 1000) / period)
+        }
+    }
+
+    class Base32 {
+        private static readonly ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+        public static encode(buffer: Buffer): string {
+            let bits = 0
+            let value = 0
+            let output = ''
+
+            for (let i = 0; i < buffer.length; i++) {
+                value = (value << 8) | buffer[i]
+                bits += 8
+
+                while (bits >= 5) {
+                    output += this.ALPHABET[(value >>> (bits - 5)) & 31]
+                    bits -= 5
+                }
+            }
+
+            if (bits > 0) {
+                output += this.ALPHABET[(value << (5 - bits)) & 31]
+            }
+
+            return output
+        }
+
+        public static decode(str: string): Buffer {
+            const cleaned = str.toUpperCase().trim().replace(/[^A-Z2-7]/g, '');
+            const buffer = Buffer.alloc(Math.floor((cleaned.length * 5) / 8))
+
+            let bits = 0
+            let value = 0
+            let index = 0
+
+            for (let i = 0; i < cleaned.length; i++) {
+                const val = this.ALPHABET.indexOf(cleaned[i])
+                if (val === -1) throw new Error('Invalid character in Base32 string')
+
+                value = (value << 5) | val
+                bits += 5
+
+                if (bits >= 8) {
+                    buffer[index++] = (value >>> (bits - 8)) & 255
+                    bits -= 8
+                }
+            }
+
+            return buffer
+        }
+    }
+
+    export class Url {
+        public static getHotpUrl(issuer: string, label: string, secret: Buffer, counter: number, options?: Partial<HotpOptions>): string {
+            const opts = { ...Hotp.DEFAULTS, ...options }
+            const url = new URL(`otpauth://hotp/${issuer}:${label}`)
+            url.searchParams.set('secret', Base32.encode(secret))
+            url.searchParams.set('algorithm', opts.algorithm.toUpperCase())
+            url.searchParams.set('digits', opts.digits.toString())
+            url.searchParams.set('counter', counter.toString())
+            url.searchParams.set('issuer', issuer)
+            return url.toString()
+        }
+
+        public static getTotpUrl(issuer: string, label: string, secret: Buffer, options?: Partial<TotpOptions>): string {
+            const opts = { ...Totp.DEFAULTS, ...options }
+            const url = new URL(`otpauth://totp/${issuer}:${label}`)
+            url.searchParams.set('secret', Base32.encode(secret))
+            url.searchParams.set('algorithm', opts.algorithm.toUpperCase())
+            url.searchParams.set('digits', opts.digits.toString())
+            url.searchParams.set('period', opts.period.toString())
+            url.searchParams.set('issuer', issuer)
+            return url.toString()
+        }
+    }
+}
+
+export default Otp

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@punikonta/node-otp",
+    "version": "0.0.1",
+    "description": "Simple and dependency free OTP implementation (HOTP, TOTP) for Node.js written in TypeScript. Passes RFC test vectors and works with most common authenticator apps.",
+    "keywords": [
+        "otp",
+        "hotp",
+        "totp",
+        "2fa",
+        "mfa",
+        "security",
+        "typescript",
+        "node",
+        "rfc4226",
+        "rfc6238",
+        "authenticator",
+        "authy",
+        "google-authenticator",
+        "microsoft-authenticator",
+        "proton-authenticator",
+        "bitwarden-authenticator"
+    ],
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "license": "MIT",
+    "scripts": {
+        "build": "npx tsc",
+        "test": "node --test test.mjs"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/punikonta/node-otp"
+    },
+    "bugs": {
+        "url": "https://github.com/punikonta/node-otp/issues",
+        "email": "punikonta@protonmail.com"
+    },
+    "author": {
+        "name": "Marcel Jovic",
+        "email": "punikonta@protonmail.com",
+        "url": "https://punikonta.de"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.2",
+        "typescript": "^6.0.2"
+    }
+}

package/test.mjs

@@ -0,0 +1,66 @@
+import test from 'node:test'
+import assert from 'node:assert'
+
+import Otp from './dist/index.js'
+
+const rfc = {
+    hotp: [
+        // "RFC 4226 - Appendix D - HOTP Algorithm: Test Values"
+        // https://datatracker.ietf.org/doc/html/rfc4226
+        { secret: '12345678901234567890', count: 0, expected: '755224', },
+        { secret: '12345678901234567890', count: 1, expected: '287082', },
+        { secret: '12345678901234567890', count: 2, expected: '359152', },
+        { secret: '12345678901234567890', count: 3, expected: '969429', },
+        { secret: '12345678901234567890', count: 4, expected: '338314', },
+        { secret: '12345678901234567890', count: 5, expected: '254676', },
+        { secret: '12345678901234567890', count: 6, expected: '287922', },
+        { secret: '12345678901234567890', count: 7, expected: '162583', },
+        { secret: '12345678901234567890', count: 8, expected: '399871', },
+        { secret: '12345678901234567890', count: 9, expected: '520489', },
+    ],
+    totp: [
+        // "RFC 6238 - Appendix B - Test Vectors"
+        // https://datatracker.ietf.org/doc/html/rfc6238
+        { time: 59, expected: '94287082', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 59, expected: '46119246', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 59, expected: '90693936', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+        { time: 1111111109, expected: '07081804', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 1111111109, expected: '68084774', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 1111111109, expected: '25091201', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+        { time: 1111111111, expected: '14050471', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 1111111111, expected: '67062674', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 1111111111, expected: '99943326', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+        { time: 1234567890, expected: '89005924', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 1234567890, expected: '91819424', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 1234567890, expected: '93441116', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+        { time: 2000000000, expected: '69279037', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 2000000000, expected: '90698825', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 2000000000, expected: '38618901', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+        { time: 20000000000, expected: '65353130', algorithm: Otp.HashAlgorithm.SHA1, secret: '12345678901234567890', },
+        { time: 20000000000, expected: '77737706', algorithm: Otp.HashAlgorithm.SHA256, secret: '12345678901234567890123456789012', },
+        { time: 20000000000, expected: '47863826', algorithm: Otp.HashAlgorithm.SHA512, secret: '1234567890123456789012345678901234567890123456789012345678901234', },
+    ],
+}
+
+test('hotp rfc4226 test values', () => {
+    for (const value of rfc.hotp) {
+        test(`test value count ${value.count}`, () => {
+            const key = Buffer.from(value.secret, 'utf8')
+            const actual = Otp.Hotp.generate(key, value.count)
+
+            assert.strictEqual(value.expected, actual)
+        })
+    }
+})
+
+test('totp rfc6238 test values', () => {
+    for (const value of rfc.totp) {
+        test(`test value, time: ${value.time}, algorithm: ${value.algorithm}`, () => {
+            const key = Buffer.from(value.secret, 'utf8')
+            const time = value.time * 1000 // test values are given in seconds, but we expect milliseconds
+            const actual = Otp.Totp.generate(key, time, { algorithm: value.algorithm, digits: value.expected.length })
+
+            assert.strictEqual(value.expected, actual)
+        })
+    }
+})

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+        "target": "es6",
+        "module": "preserve",
+        "declaration": true,
+        "noImplicitAny": true,
+        "removeComments": true,
+        "preserveConstEnums": true,
+        "isolatedModules": true,
+        "sourceMap": true,
+        "outDir": "dist",
+        "types": [
+            "node"
+        ]
+    },
+    "files": [
+        "./index.ts"
+    ]
+}