fix(env): improve env() handling for numeric strings and preserve exact values

Author: 3m1n3nc3

CHANGELOG.md

@@ -10,10 +10,14 @@ The format follows semantic versioning principles.
 
 ### Changed
 
+- `env()` now reads a value as a number only when the number says exactly what was written. `Number()` accepts hexadecimal, binary and octal literals, exponents, surrounding whitespace, and integers wider than a double can hold, and coercing those loses information silently. `'6379'` is still a number; `'0x1f'`, `'007'`, `'1e5'`, `' 12 '`, `'0b1010'`, `'Infinity'` and `'12345678901234567890'` are now the strings they were written as.
+
 ### Docs
 
 ### Fixed
 
+- Fixed `env()` destroying hexadecimal secrets. A `0x`-prefixed 32-byte key parses as a number, so it was silently replaced by a float keeping roughly its first thirteen digits, with nothing downstream able to tell. Private keys, hashes and identifiers read through `env()` now survive verbatim.
+
 ## [0.12.36] - 2026-06-20
 
 ### Added

packages/common/package.json

@@ -64,5 +64,10 @@
         "arkormx": {
             "optional": true
         }
+    },
+    "inlinedDependencies": {
+        "clear-router": "2.9.3",
+        "dayjs": "1.11.20",
+        "kanun": "1.2.0"
     }
 }

packages/common/src/EnvLoader.ts

@@ -44,6 +44,9 @@ export class EnvLoader {
      * Read an environment variable, coercing booleans, numbers and `null`, and
      * falling back to `defaultValue` when it is unset.
      *
+     * A value is only read as a number when the number says exactly what was
+     * written. See {@link isExactNumber}.
+     *
      * @param name          The variable name.
      * @param defaultValue  Returned when the variable is unset.
      */
@@ -60,12 +63,7 @@ export class EnvLoader {
             val = [true, 'true', 'on'].includes(val)
         }
 
-        if (
-            !isNaN(Number(val)) &&
-            typeof val !== 'boolean' &&
-            typeof val !== 'undefined' &&
-            val !== ''
-        ) {
+        if (typeof val === 'string' && this.isExactNumber(val)) {
             val = Number(val)
         }
 
@@ -81,6 +79,27 @@ export class EnvLoader {
 
         return val as EnvReturn<X, K, D>
     }
+
+    /**
+     * Whether a number would say exactly what the variable says.
+     *
+     * `Number()` accepts far more than decimal digits: hexadecimal, binary and
+     * octal literals, exponents, surrounding whitespace, and integers wider
+     * than a double can hold. Coercing those loses information silently, and
+     * the values that look like numbers by accident tend to be the ones where
+     * that matters most - a 32-byte key beginning `0x` becomes a float that
+     * keeps roughly its first thirteen digits, and nothing downstream can tell
+     * that it happened.
+     *
+     * Converting back and comparing is the whole test: `'6379'` survives it,
+     * `'0x1f'`, `'007'`, `'1e5'` and `'12345678901234567890'` do not, and so
+     * they stay the strings they were written as.
+     */
+    private isExactNumber(value: string): boolean {
+        const parsed = Number(value)
+
+        return Number.isFinite(parsed) && String(parsed) === value
+    }
 }
 
 /** 

packages/common/tests/env-loader.test.ts

@@ -49,4 +49,73 @@ describe('EnvLoader', () => {
         process.env[KEY] = 'localhost'
         expect(loader.get(KEY)).toBe('localhost')
     })
+
+    /**
+     * `Number()` accepts far more than decimal digits, and the values that
+     * look like numbers by accident are often the ones where losing them
+     * matters most. A number is only used when it says exactly what was
+     * written.
+     */
+    describe('values that only look like numbers', () => {
+        const keeps = (written: string) => {
+            const loader = new EnvLoader()
+
+            process.env[KEY] = written
+
+            expect(loader.get(KEY)).toBe(written)
+        }
+
+        test('keeps a hexadecimal key, which a number would destroy', () => {
+            // 32 bytes. As a number this keeps about its first thirteen digits.
+            keeps(
+                '0xd6d9ef6d3a5443f0de69a1452d0cb5a62bdd9700225c3c8371db575aa298408c',
+            )
+        })
+
+        test('keeps a short hexadecimal value', () => {
+            keeps('0x1f')
+        })
+
+        test('keeps binary and octal literals', () => {
+            keeps('0b1010')
+            keeps('0o755')
+        })
+
+        test('keeps leading zeros, which carry meaning of their own', () => {
+            keeps('007')
+        })
+
+        test('keeps an integer wider than a double can hold', () => {
+            keeps('12345678901234567890')
+        })
+
+        test('keeps exponent notation as it was written', () => {
+            keeps('1e5')
+        })
+
+        test('keeps surrounding whitespace rather than trimming silently', () => {
+            keeps(' 12 ')
+        })
+
+        test('keeps infinities out of configuration', () => {
+            keeps('Infinity')
+            keeps('-Infinity')
+        })
+
+        test('still reads an ordinary number as a number', () => {
+            const loader = new EnvLoader()
+
+            process.env[KEY] = '6379'
+            expect(loader.get(KEY)).toBe(6379)
+
+            process.env[KEY] = '-3'
+            expect(loader.get(KEY)).toBe(-3)
+
+            process.env[KEY] = '1.5'
+            expect(loader.get(KEY)).toBe(1.5)
+
+            process.env[KEY] = '0'
+            expect(loader.get(KEY)).toBe(0)
+        })
+    })
 })