@antmind/otp 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@antmind/otp",
+  "version": "0.1.0",
+  "description": "OTP (One-Time Password) library for Node.js and browsers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --coverage"
+  },
+  "keywords": [
+    "otp",
+    "hotp",
+    "totp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghosind/node-otp.git"
+  },
+  "homepage": "https://github.com/ghosind/node-otp#readme",
+  "bugs": {
+    "url": "https://github.com/ghosind/node-otp/issues"
+  },
+  "author": "Chen Su",
+  "license": "MIT",
+  "directories": {
+    "test": "tests"
+  },
+  "dependencies": {
+    "@antmind/encoding": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,25 @@
+import { createHmac } from 'crypto';
+
+/**
+ * The supported HMAC algorithms.
+ */
+export type Algorithm = 'SHA1' | 'SHA256' | 'SHA512';
+
+/**
+ * Generates an HMAC digest for the given message using the specified algorithm and key.
+ *
+ * @param algorithm The HMAC algorithm to use. Default is 'SHA1'.
+ * @param key The secret key used for HMAC generation.
+ * @param message The message to be hashed.
+ * @returns The generated HMAC digest as a Uint8Array.
+ */
+export const hmac = async (
+  algorithm: Algorithm = 'SHA1',
+  key: Uint8Array,
+  message: Uint8Array,
+) => {
+  const hmac = createHmac(algorithm, key);
+  hmac.update(message);
+
+  return new Uint8Array(hmac.digest());
+}

package/src/hotp.ts

@@ -0,0 +1,47 @@
+import { OTP } from './otp';
+
+/**
+ * HMAC-based One-Time Password (HOTP) generator and verifier.
+ */
+export class HOTP extends OTP {
+  /**
+   * Generates an HOTP code based on the provided secret and counter.
+   *
+   * @param secret The shared secret key used for generating the HOTP code.
+   * @param counter The counter value used for generating the HOTP code.
+   * @returns The generated HOTP code as a string.
+   */
+  async generate(secret: string, counter?: number): Promise<string> {
+    return this.generateCode(secret, counter || 0);
+  }
+
+  /**
+   * Verifies the provided HOTP code against the generated code for the given secret and counter.
+   *
+   * @param secret The shared secret key used for generating the HOTP code.
+   * @param token The HOTP code to verify.
+   * @param counter The counter value used for generating the HOTP code.
+   * @returns A boolean indicating whether the HOTP code is valid.
+   */
+  async verify(secret: string, token: string, counter?: number): Promise<boolean> {
+    return this.verifyCode(secret, token, counter || 0);
+  }
+
+  /**
+   * Generates the OTP URI for the given parameters.
+   *
+   * @param secret The shared secret key used for generating the HOTP code.
+   * @param accountName The account name associated with the OTP.
+   * @param counter The counter value used for generating the HOTP code.
+   * @returns The generated OTP URI as a string.
+   */
+  getURI(secret: string, accountName: string, counter?: number): string {
+    const params: Record<string, string> = {};
+
+    if (counter !== undefined) {
+      params['counter'] = counter.toString();
+    }
+
+    return this.buildURI('hotp', secret, accountName, params);
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Algorithm } from './crypto';
+export { TOTP, TOTPOptions } from './totp';
+export { HOTP } from './hotp';

package/src/otp.ts

@@ -0,0 +1,145 @@
+import { Base32Encoding } from '@antmind/encoding';
+import { Algorithm, hmac } from './crypto';
+
+const DefaultAlgorithm: Algorithm = 'SHA1';
+const DefaultDigits = 6;
+
+export interface OTPOptions {
+  /**
+   * The algorithm used for the OTP generation, typically 'SHA1', 'SHA256', or 'SHA512'.
+   * Default is 'SHA1'.
+   */
+  algorithm?: Algorithm;
+
+  /**
+   * The number of digits in the generated OTP, typically 6 or 8. Default is 6.
+   */
+  digits?: number;
+
+  /**
+   * The issuer name to be included in the OTP URI.
+   */
+  issuer?: string;
+}
+
+export abstract class OTP {
+  /**
+   * The algorithm used for the OTP generation, typically 'SHA1', 'SHA256', or 'SHA512'.
+   * Default is 'SHA1'.
+   */
+  algorithm?: Algorithm;
+
+  /**
+   * The number of digits in the generated OTP, typically 6 or 8. Default is 6.
+   */
+  digits?: number;
+
+  /**
+   * The issuer name to be included in the OTP URI.
+   */
+  issuer?: string | undefined;
+
+  private base32?: Base32Encoding;
+
+  constructor(options?: OTPOptions) {
+    this.algorithm = options?.algorithm || DefaultAlgorithm;
+    this.digits = options?.digits || DefaultDigits;
+    this.issuer = options?.issuer;
+  }
+
+  abstract generate(secret: string, counterOrTime?: number): Promise<string>;
+
+  abstract verify(secret: string, token: string, counterOrTime?: number): Promise<boolean>;
+
+  /**
+   * Verifies the provided OTP code against the generated code for the given secret and counter or
+   * time.
+   *
+   * @param secret The shared secret key used for generating the OTP code.
+   * @param token The OTP code to verify.
+   * @param counter The counter or time value used for generating the OTP code.
+   * @returns A boolean indicating whether the OTP code is valid.
+   */
+  protected async verifyCode(secret: string, token: string, counter: number): Promise<boolean> {
+    const generatedCode = await this.generateCode(secret, counter);
+
+    return generatedCode === token;
+  }
+
+  /**
+   * Generates an OTP code based on the provided secret and counter or time.
+   *
+   * @param secret The shared secret key used for generating the OTP code.
+   * @param counter The counter or time value used for generating the OTP code.
+   * @returns The generated OTP code as a string.
+   */
+  protected async generateCode(secret: string, counter: number): Promise<string> {
+    const message = new Uint8Array(8);
+    const view = new DataView(message.buffer);
+    view.setUint32(4, counter, false);
+    const secretBytes = new TextEncoder().encode(secret);
+
+    const hash = await hmac(this.algorithm, secretBytes, message);
+    const offset = (hash[hash.length - 1] || 0) & 0x0f;
+    const code = (((hash[offset] || 0) & 0x7F) << 24)
+      | (((hash[offset+1] || 0) & 0xFF) << 16)
+      | (((hash[offset+2] || 0) & 0xFF) << 8)
+      | ((hash[offset+3] || 0) & 0xFF);
+    const mod = 10 ** (this.digits || DefaultDigits);
+    const otp = (code % mod).toString().padStart(this.digits || DefaultDigits, '0');
+
+    return otp;
+  }
+
+  /**
+   * Builds the OTP URI for the given OTP type, secret, account name, and other parameters.
+   *
+   * @param type The type of OTP, either 'totp' or 'hotp'.
+   * @param secret The shared secret key used for generating the OTP code.
+   * @param accountName The account name associated with the OTP.
+   * @param otherParams Additional parameters to include in the OTP URI.
+   * @returns The generated OTP URI as a string.
+   */
+  protected buildURI(type: 'totp' | 'hotp', secret: string, accountName: string, otherParams: {
+    [key: string]: string | number;
+  }): string {
+    const params = new URLSearchParams();
+
+    const base32 = this.getBase32();
+    const secretBase32 = base32.encode(secret);
+    params.append('secret', secretBase32);
+
+    if (this.issuer) {
+      params.append('issuer', this.issuer);
+    }
+    if (this.algorithm && this.algorithm !== DefaultAlgorithm) {
+      params.append('algorithm', this.algorithm);
+    }
+    if (this.digits && this.digits !== DefaultDigits) {
+      params.append('digits', (this.digits).toString());
+    }
+
+    for (const [key, value] of Object.entries(otherParams)) {
+      params.append(key, value.toString());
+    }
+
+    const path = this.issuer
+      ? `${encodeURIComponent(this.issuer)}:${encodeURIComponent(accountName)}`
+      : encodeURIComponent(accountName);
+
+    return `otpauth://${type}/${path}?${params.toString()}`;
+  }
+
+  /**
+   * Gets the Base32 encoding instance.
+   *
+   * @returns The base32 encoding instance.
+   */
+  private getBase32(): Base32Encoding {
+    if (!this.base32) {
+      this.base32 = new Base32Encoding({ padChar: '' });
+    }
+
+    return this.base32;
+  }
+}

package/src/totp.ts

@@ -0,0 +1,77 @@
+import { OTP, OTPOptions } from './otp';
+
+const DefaultPeriod = 30;
+
+export interface TOTPOptions extends OTPOptions {
+  /**
+   * The time period in seconds for which a TOTP code is valid. Default is 30 seconds.
+   */
+  period?: number;
+}
+
+/**
+ * Time-based One-Time Password (TOTP) generator and verifier.
+ */
+export class TOTP extends OTP {
+  /**
+   * The time period in seconds for which a TOTP code is valid. Default is 30 seconds.
+   */
+  period?: number;
+
+  constructor(options?: TOTPOptions) {
+    super(options);
+    this.period = options?.period || DefaultPeriod;
+  }
+
+  /**
+   * Generates a TOTP code for the given secret and time.
+   *
+   * @param secret The shared secret key used for generating the TOTP code.
+   * @param time The specific time (in seconds since epoch) for which to generate the TOTP code.
+   * If not provided, the current time will be used.
+   * @returns The generated TOTP code as a string.
+   */
+  async generate(secret: string, time?: number): Promise<string> {
+    if (!time) {
+      time = Math.floor(Date.now() / 1000);
+    }
+    const counter = Math.floor(time / (this.period || DefaultPeriod));
+
+    return this.generateCode(secret, counter);
+  }
+
+  /**
+   * Verifies a TOTP code for the given secret and time.
+   *
+   * @param secret The shared secret key used for generating the TOTP code.
+   * @param token The TOTP code to verify.
+   * @param time The specific time (in seconds since epoch) for which to verify the TOTP code.
+   * If not provided, the current time will be used.
+   * @returns A boolean indicating whether the TOTP code is valid.
+   */
+  async verify(secret: string, token: string, time?: number): Promise<boolean> {
+    if (!time) {
+      time = Math.floor(Date.now() / 1000);
+    }
+    const counter = Math.floor(time / (this.period || DefaultPeriod));
+
+    return this.verifyCode(secret, token, counter);
+  }
+
+  /**
+   * Generates the OTP URI for provisioning.
+   *
+   * @param secret The shared secret key used for generating the TOTP code.
+   * @param accountName The account name (e.g., user email) to be included in the URI.
+   * @returns The generated OTP URI as a string.
+   */
+  getURI(secret: string, accountName: string): string {
+    const params: Record<string, string | number> = {};
+
+    if (this.period && this.period !== DefaultPeriod) {
+      params['period'] = this.period;
+    }
+
+    return this.buildURI('totp', secret, accountName, params);
+  }
+}

package/src/utils.ts

@@ -0,0 +1,9 @@
+/**
+ * Encodes a string into a Uint8Array using UTF-8 encoding.
+ *
+ * @param str The string to encode.
+ * @returns The encoded Uint8Array.
+ */
+export const encodeString = (str: string): Uint8Array => {
+  return new TextEncoder().encode(str);
+};

package/tests/hotp.test.ts

@@ -0,0 +1,88 @@
+import { HOTP } from '../src/index';
+
+describe('test HOTP generate', () => {
+  test('test HOTP SHA1', async () => {
+    const secret = '12345678901234567890';
+    const hotp = new HOTP({ digits: 6, algorithm: 'SHA1' });
+
+    let code = await hotp.generate(secret, 0);
+    expect(code).toBe('755224');
+
+    code = await hotp.generate(secret, 1);
+    expect(code).toBe('287082');
+
+    code = await hotp.generate(secret, 2);
+    expect(code).toBe('359152');
+
+    code = await hotp.generate(secret, 3);
+    expect(code).toBe('969429');
+
+    code = await hotp.generate(secret, 4);
+    expect(code).toBe('338314');
+
+    code = await hotp.generate(secret, 5);
+    expect(code).toBe('254676');
+
+    code = await hotp.generate(secret, 6);
+    expect(code).toBe('287922');
+
+    code = await hotp.generate(secret, 7);
+    expect(code).toBe('162583');
+
+    code = await hotp.generate(secret, 8);
+    expect(code).toBe('399871');
+
+    code = await hotp.generate(secret, 9);
+    expect(code).toBe('520489');
+  });
+});
+
+describe('test HOTP verify', () => {
+  test('test HOTP SHA1 verify', async () => {
+    const secret = '12345678901234567890';
+    const hotp = new HOTP({ digits: 6, algorithm: 'SHA1' });
+
+    const isValid0 = await hotp.verify(secret, '755224', 0);
+    expect(isValid0).toBe(true);
+
+    const isValid1 = await hotp.verify(secret, '287082', 1);
+    expect(isValid1).toBe(true);
+
+    const isValid2 = await hotp.verify(secret, '359152', 2);
+    expect(isValid2).toBe(true);
+
+    const isValid3 = await hotp.verify(secret, '969429', 3);
+    expect(isValid3).toBe(true);
+
+    const isValid4 = await hotp.verify(secret, '338314', 4);
+    expect(isValid4).toBe(true);
+
+    const isValid5 = await hotp.verify(secret, '254676', 5);
+    expect(isValid5).toBe(true);
+
+    const isValid6 = await hotp.verify(secret, '287922', 6);
+    expect(isValid6).toBe(true);
+
+    const isValid7 = await hotp.verify(secret, '162583', 7);
+    expect(isValid7).toBe(true);
+
+    const isValid8 = await hotp.verify(secret, '399871', 8);
+    expect(isValid8).toBe(true);
+
+    const isValid9 = await hotp.verify(secret, '520489', 9);
+    expect(isValid9).toBe(true);
+  });
+});
+
+describe('test HOTP URI generation', () => {
+  test('test HOTP URI', () => {
+    const hotp = new HOTP({ issuer: 'ExampleIssuer' });
+    const secret = '12345678901234567890';
+
+    let uri = hotp.getURI(secret, 'user@example.com');
+    expect(uri).toBe('otpauth://hotp/ExampleIssuer:user%40example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=ExampleIssuer');
+
+    uri = hotp.getURI(secret, 'user@example.com', 0);
+    expect(uri).toBe('otpauth://hotp/ExampleIssuer:user%40example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=ExampleIssuer&counter=0');
+  });
+});

package/tests/totp.test.ts

@@ -0,0 +1,174 @@
+import { TOTP } from '../src/index';
+
+describe('test TOTP generate', () => {
+  test('test TOTP SHA1', async () => {
+    const secret = '12345678901234567890';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA1' });
+
+    let code = await totp.generate(secret, 59);
+    expect(code).toBe('94287082');
+
+    code = await totp.generate(secret, 1111111109);
+    expect(code).toBe('07081804');
+
+    code = await totp.generate(secret, 1111111111);
+    expect(code).toBe('14050471');
+
+    code = await totp.generate(secret, 1234567890);
+    expect(code).toBe('89005924');
+
+    code = await totp.generate(secret, 2000000000);
+    expect(code).toBe('69279037');
+
+    code = await totp.generate(secret, 20000000000);
+    expect(code).toBe('65353130');
+  });
+
+  test('test TOTP SHA256', async () => {
+    const secret = '12345678901234567890123456789012';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA256' });
+
+    let code = await totp.generate(secret, 59);
+    expect(code).toBe('46119246');
+
+    code = await totp.generate(secret, 1111111109);
+    expect(code).toBe('68084774');
+
+    code = await totp.generate(secret, 1111111111);
+    expect(code).toBe('67062674');
+
+    code = await totp.generate(secret, 1234567890);
+    expect(code).toBe('91819424');
+
+    code = await totp.generate(secret, 2000000000);
+    expect(code).toBe('90698825');
+
+    code = await totp.generate(secret, 20000000000);
+    expect(code).toBe('77737706');
+  });
+
+  test('test TOTP SHA512', async () => {
+    const secret = '1234567890123456789012345678901234567890123456789012345678901234';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA512' });
+
+    let code = await totp.generate(secret, 59);
+    expect(code).toBe('90693936');
+
+    code = await totp.generate(secret, 1111111109);
+    expect(code).toBe('25091201');
+
+    code = await totp.generate(secret, 1111111111);
+    expect(code).toBe('99943326');
+
+    code = await totp.generate(secret, 1234567890);
+    expect(code).toBe('93441116');
+
+    code = await totp.generate(secret, 2000000000);
+    expect(code).toBe('38618901');
+
+    code = await totp.generate(secret, 20000000000);
+    expect(code).toBe('47863826');
+  });
+
+  test('test TOTP with current time', async () => {
+    // This test case may fail if the code generation crosses a time step boundary.
+    const totp = new TOTP();
+
+    const secret = '12345678901234567890';
+
+    const code = await totp.generate(secret);
+    expect(code).toHaveLength(6);
+
+    const isValid = await totp.verify(secret, code);
+    expect(isValid).toBe(true);
+  });
+});
+
+describe('test TOTP verify', () => {
+  test('test TOTP verify SHA1', async () => {
+    const secret = '12345678901234567890';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA1' });
+
+    let isValid = await totp.verify(secret, '94287082', 59);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '07081804', 1111111109);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '14050471', 1111111111);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '89005924', 1234567890);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '69279037', 2000000000);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '65353130', 20000000000);
+    expect(isValid).toBe(true);
+  });
+
+  test('test TOTP verify SHA256', async () => {
+    const secret = '12345678901234567890123456789012';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA256' });
+
+    let isValid = await totp.verify(secret, '46119246', 59);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '68084774', 1111111109);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '67062674', 1111111111);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '91819424', 1234567890);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '90698825', 2000000000);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '77737706', 20000000000);
+    expect(isValid).toBe(true);
+  });
+
+  test('test TOTP verify SHA512', async () => {
+    const secret = '1234567890123456789012345678901234567890123456789012345678901234';
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA512' });
+
+    let isValid = await totp.verify(secret, '90693936', 59);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '25091201', 1111111109);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '99943326', 1111111111);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '93441116', 1234567890);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '38618901', 2000000000);
+    expect(isValid).toBe(true);
+
+    isValid = await totp.verify(secret, '47863826', 20000000000);
+    expect(isValid).toBe(true);
+  });
+});
+
+describe('test TOTP URI generation', () => {
+  test('test TOTP URI with default options', () => {
+    const totp = new TOTP({ digits: 6, algorithm: 'SHA1', period: 30, issuer: 'ExampleIssuer' });
+    const secret = '12345678901234567890';
+
+    const uri = totp.getURI(secret, 'user@example.com');
+    expect(uri).toBe('otpauth://totp/ExampleIssuer:user%40example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=ExampleIssuer');
+  });
+
+  test('test TOTP URI with custom period', () => {
+    const totp = new TOTP({ digits: 8, algorithm: 'SHA256', period: 60, issuer: 'ExampleIssuer' });
+    const secret = '12345678901234567890123456789012';
+
+    const uri = totp.getURI(secret, 'user@example.com');
+    expect(uri).toBe('otpauth://totp/ExampleIssuer:user%40example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZA&issuer=ExampleIssuer&algorithm=SHA256&digits=8&period=60');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "commonjs",
+    "target": "es2024",
+    "types": ["node", "jest"],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  },
+  "include": ["src"]
+}