kron-otp 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,7 +5,7 @@ A small CommonJS TOTP engine for Node.js, maintained in the [KronOTP monorepo](h
5
5
  ## Install
6
6
 
7
7
  ```sh
8
- npm install kron-otp
8
+ npm install kron-otp@2.0.0
9
9
  ```
10
10
 
11
11
  ## Usage
@@ -22,8 +22,8 @@ console.log('Verification:', valid);
22
22
  ```
23
23
 
24
24
  - `generate(secret)` returns a six-digit string, or throws `TypeError` for a malformed Base32 secret.
25
- - `verify(secret, token)` returns `true` or `false` for a six-digit string, with ±one 30-second step tolerated. Invalid secrets throw `TypeError`.
26
- - Configuration: SHA-1, 6 digits, 30-second period. Secrets are normalized by removing whitespace and uppercasing.
25
+ - **v2.0.0 breaking change:** `verify(secret, token)` returns `true`/`false`, including `false` for expected invalid secrets. Previous v1.0.0 threw `TypeError` on invalid secrets. Update any consumer error-handling logic before upgrading.
26
+ - Configuration remains SHA-1, 6 digits and 30 seconds. **v2.0.0:** canonical ASCII Base32, >=14 decoded bytes (112 bits), <=4096 raw chars and <=1024 cleaned chars, only ASCII space/tab/CR/LF/FF/VT removed; `generate` rejects invalid keys with sanitized `TypeError`. Recommend cryptographically random >=20-byte secrets for provisioning.
27
27
  - Supported Node.js: 20.19+ (dependency requirement).
28
28
 
29
29
  ## Local tests
@@ -38,3 +38,5 @@ Only use provisioning secrets for accounts you own or are authorized to automate
38
38
  See the [integration and publishing guide](../docs/AUTOMATION_AND_PUBLISHING.md).
39
39
 
40
40
  Licensed under the [MIT License](./LICENSE).
41
+
42
+ **Migration from v1.0.0:** Short legacy keys with fewer than 14 decoded bytes now fail validation; re-provision weak credentials securely. The legacy v1.0.0 version is not overwritten. v2.0.0 includes the P01 input/contract updates. This library has no built-in rate limits or replay protection.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kron-otp",
3
- "version": "1.0.0",
3
+ "version": "2.0.0",
4
4
  "description": "Lightweight TOTP generation and verification for Node.js.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",
package/src/kron-otp.js CHANGED
@@ -2,14 +2,30 @@
2
2
 
3
3
  const OTPAuth = require('otpauth');
4
4
 
5
+ // Bound attacker-controlled input before normalization/decoding.
6
+ // 14 bytes matches PyOTP >=2.12; use random 20+ byte keys when provisioning.
7
+ const MIN_SECRET_BYTES = 14;
8
+ const MAX_RAW_SECRET_LENGTH = 4096;
9
+ const MAX_BASE32_LENGTH = 1024;
10
+ const INVALID_SECRET = 'Invalid TOTP secret: expected valid Base32 of an accepted size.';
11
+
5
12
  class KronOTP {
6
13
  static #createTOTP(secret) {
7
14
  if (typeof secret !== 'string') {
8
15
  throw new TypeError('TOTP secret must be a Base32 string.');
9
16
  }
17
+ if (secret.length > MAX_RAW_SECRET_LENGTH) {
18
+ throw new TypeError(INVALID_SECRET);
19
+ }
20
+
21
+ // Only ASCII whitespace is ignored, identically in Python and Node.
22
+ // Check ASCII characters BEFORE uppercasing to avoid Unicode case folding.
23
+ const compact = secret.replace(/[ \t\n\r\f\v]+/g, '');
24
+ if (compact.length > MAX_BASE32_LENGTH || !/^[A-Za-z2-7=]+$/.test(compact)) {
25
+ throw new TypeError(INVALID_SECRET);
26
+ }
10
27
 
11
- // Authenticator setup keys may contain spaces, mixed case, or Base32 padding.
12
- const cleaned = secret.replace(/\s+/g, '').toUpperCase();
28
+ const cleaned = compact.toUpperCase();
13
29
  const unpadded = cleaned.replace(/=+$/, '');
14
30
  const padding = cleaned.length - unpadded.length;
15
31
  const remainder = unpadded.length % 8;
@@ -20,15 +36,15 @@ class KronOTP {
20
36
  (padding === 0 || (remainder !== 0 && padding === 8 - remainder));
21
37
 
22
38
  if (!validBase32) {
23
- throw new TypeError('Invalid TOTP secret: expected a valid Base32 string.');
39
+ throw new TypeError(INVALID_SECRET);
24
40
  }
25
41
 
26
42
  try {
27
43
  const decoded = OTPAuth.Secret.fromBase32(unpadded);
28
44
 
29
- // Reject malformed encodings instead of silently accepting altered keys.
30
- if (decoded.bytes.length === 0 || decoded.base32 !== unpadded) {
31
- throw new Error('Non-canonical Base32 input.');
45
+ // Enforce PyOTP's minimum and reject non-canonical unused padding bits.
46
+ if (decoded.bytes.length < MIN_SECRET_BYTES || decoded.base32 !== unpadded) {
47
+ throw new TypeError(INVALID_SECRET);
32
48
  }
33
49
 
34
50
  return new OTPAuth.TOTP({
@@ -38,8 +54,8 @@ class KronOTP {
38
54
  secret: decoded,
39
55
  });
40
56
  } catch {
41
- // Never include the secret or dependency error details in an exception.
42
- throw new TypeError('Invalid TOTP secret: expected a valid Base32 string.');
57
+ // Never include secret values or dependency internals in public errors.
58
+ throw new TypeError(INVALID_SECRET);
43
59
  }
44
60
  }
45
61
 
@@ -48,14 +64,20 @@ class KronOTP {
48
64
  }
49
65
 
50
66
  static verify(secret, token) {
51
- const totp = KronOTP.#createTOTP(secret);
52
-
53
- // Preserve leading zeros: OTP tokens must be six-character strings.
54
- if (typeof token !== 'string' || !/^\d{6}$/.test(token)) {
67
+ // Invalid OTPs or expected invalid secrets are nonmatches in both runtimes.
68
+ if (typeof token !== 'string' || !/^[0-9]{6}$/.test(token)) {
55
69
  return false;
56
70
  }
57
71
 
58
- // Allow one 30-second time step of clock drift on either side.
72
+ let totp;
73
+ try {
74
+ totp = KronOTP.#createTOTP(secret);
75
+ } catch (error) {
76
+ if (error instanceof TypeError) return false;
77
+ throw error;
78
+ }
79
+
80
+ // Preserve existing SHA-1, 6 digits, 30-second window and stateless design.
59
81
  return totp.validate({ token, window: 1 }) !== null;
60
82
  }
61
83
  }