nhb-toolbox 4.27.10 → 4.28.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.28.0] - 2025-12-01
+
+- **Added** *new* class `Cipher` to *encrypt/decrypt* string with *secret key*.
+- **Added** *new* class `Signet` to *sign*, *decode* and *verify* **token** like `JWT`.
+- **Added** *new* `sha256` hash function. **Updated** `sha1` *encoding algorithm*. Now it avoids depending on `TextEncoder`.
+- **Added** *new* utility `parseMSec` to convert time value to *milliseconds* or *seconds* along with new *type guard* `isTimeWithUnit`.
+- **Added** *new* `JSON` utilities: `stableStringify` for *stable, deterministic stringifying* and `stripJsonEdgeGarbage` for stripping `JSON` string.
+
+## [4.27.11] - 2025-11-29
+
+- **Updated** *core algorithms* of `md5` and `sha1` utilities to fix *incorrect hash digest generation*.
+
 ## [4.27.10] - 2025-11-28
 
 - **Updated** type augmentation for `String` methods: `toLowerCase` and `toUpperCase` (type level only, implementation remains intact).

package/dist/cjs/date/constants.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INTERNALS = exports.ZODIAC_PRESETS = exports.VEDIC_ZODIAC_SIGNS = exports.WESTERN_ZODIAC_SIGNS = exports.DATE_PART_RANGES = exports.SORTED_TIME_FORMATS = exports.TIME_FORMATS = exports.MILLISECOND_FORMATS = exports.ZONE_FORMATS = exports.SECOND_FORMATS = exports.MINUTE_FORMATS = exports.HOUR_FORMATS = exports.DAY_FORMATS = exports.DATE_FORMATS = exports.MONTH_FORMATS = exports.YEAR_FORMATS = exports.MONTHS = exports.DAYS = void 0;
+exports.MS_MAP = exports.TIME_UNIT_REGEX = exports.TIME_UNIT_VARIANTS = exports.ZODIAC_PRESETS = exports.VEDIC_ZODIAC_SIGNS = exports.WESTERN_ZODIAC_SIGNS = exports.DATE_PART_RANGES = exports.SORTED_TIME_FORMATS = exports.TIME_FORMATS = exports.MILLISECOND_FORMATS = exports.ZONE_FORMATS = exports.SECOND_FORMATS = exports.MINUTE_FORMATS = exports.HOUR_FORMATS = exports.DAY_FORMATS = exports.DATE_FORMATS = exports.MONTH_FORMATS = exports.YEAR_FORMATS = exports.MONTHS = exports.DAYS = exports.INTERNALS = void 0;
+exports.INTERNALS = Symbol('Internals');
 exports.DAYS = /* @__PURE__ */ Object.freeze([
     'Sunday',
     'Monday',
@@ -95,4 +96,63 @@ exports.ZODIAC_PRESETS = /* @__PURE__ */ Object.freeze({
     tropical: exports.WESTERN_ZODIAC_SIGNS,
     sidereal: exports.VEDIC_ZODIAC_SIGNS,
 });
-exports.INTERNALS = Symbol('Internals');
+exports.TIME_UNIT_VARIANTS = /* @__PURE__ */ Object.freeze({
+    year: ['y', 'yr', 'yrs', 'year', 'years'],
+    month: ['mo', 'month', 'months'],
+    week: ['w', 'week', 'weeks'],
+    day: ['d', 'day', 'days'],
+    hour: ['h', 'hr', 'hrs', 'hour', 'hours'],
+    minute: ['m', 'min', 'mins', 'minute', 'minutes'],
+    second: ['s', 'sec', 'secs', 'second', 'seconds'],
+    millisecond: ['ms', 'msec', 'msecs', 'millisecond', 'milliseconds'],
+});
+const TIME_UNIT_REGEX_STR = /* @__PURE__ */ Object.freeze(Object.values(exports.TIME_UNIT_VARIANTS)
+    .flat()
+    .sort((a, b) => b.length - a.length)
+    .join('|'));
+exports.TIME_UNIT_REGEX = /* @__PURE__ */ Object.freeze(new RegExp(`^(?<value>-?\\d*\\.?\\d+) *(?<unit>${TIME_UNIT_REGEX_STR})?$`, 'i'));
+exports.MS_MAP = /* @__PURE__ */ Object.freeze((() => {
+    const s = 1000;
+    const m = s * 60;
+    const h = m * 60;
+    const d = h * 24;
+    const w = d * 7;
+    const y = d * 365.25;
+    const mo = y / 12;
+    return {
+        y,
+        yr: y,
+        yrs: y,
+        year: y,
+        years: y,
+        mo,
+        month: mo,
+        months: mo,
+        w,
+        week: w,
+        weeks: w,
+        d,
+        day: d,
+        days: d,
+        h,
+        hr: h,
+        hrs: h,
+        hour: h,
+        hours: h,
+        m,
+        min: m,
+        mins: m,
+        minute: m,
+        minutes: m,
+        s,
+        sec: s,
+        secs: s,
+        second: s,
+        seconds: s,
+        ms: 1,
+        msec: 1,
+        msecs: 1,
+        millisecond: 1,
+        milliseconds: 1,
+    };
+})());

package/dist/cjs/date/guards.js

@@ -6,12 +6,14 @@ exports.isValidTimeZoneId = isValidTimeZoneId;
 exports.isNativeTimeZoneId = isNativeTimeZoneId;
 exports.isLeapYear = isLeapYear;
 exports.isDateLike = isDateLike;
+exports.isTimeWithUnit = isTimeWithUnit;
 const primitives_1 = require("../guards/primitives");
 const specials_1 = require("../guards/specials");
 const utilities_1 = require("../number/utilities");
+const constants_1 = require("./constants");
 const timezone_1 = require("./timezone");
 function isValidTime(value) {
-    if (!(0, primitives_1.isString)(value))
+    if (!(0, primitives_1.isNonEmptyString)(value))
         return false;
     const [hourStr, minuteStr] = value.split(':');
     if (!(0, specials_1.isNumericString)(hourStr) || !(0, specials_1.isNumericString)(minuteStr))
@@ -24,10 +26,12 @@ function isValidUTCOffset(value) {
     return (0, primitives_1.isString)(value) ? /^UTC[+-]?\d{1,2}:\d{2}$/.test(value) : false;
 }
 function isValidTimeZoneId(value) {
-    return (0, primitives_1.isString)(value) ? [...timezone_1.IANA_TZ_IDS].includes(value) : false;
+    return (0, primitives_1.isNonEmptyString)(value) ? new Set([...timezone_1.IANA_TZ_IDS]).has(value) : false;
 }
 function isNativeTimeZoneId(value) {
-    return (0, primitives_1.isString)(value) ? Intl.supportedValuesOf('timeZone').includes(value) : false;
+    return (0, primitives_1.isNonEmptyString)(value) ?
+        new Set(Intl.supportedValuesOf('timeZone')).has(value)
+        : false;
 }
 function isLeapYear(year) {
     const $year = (0, utilities_1.normalizeNumber)(year);
@@ -62,3 +66,6 @@ function isDateLike(value) {
     }
     return false;
 }
+function isTimeWithUnit(value) {
+    return (0, primitives_1.isNonEmptyString)(value) && constants_1.TIME_UNIT_REGEX.test(value);
+}

package/dist/cjs/date/parse.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMSec = parseMSec;
+const primitives_1 = require("../guards/primitives");
+const specials_1 = require("../guards/specials");
+const constants_1 = require("./constants");
+const guards_1 = require("./guards");
+function parseMSec(value, sec = false) {
+    if ((0, specials_1.isNumericString)(value)) {
+        return _parse(`${value}s`, sec);
+    }
+    else if ((0, guards_1.isTimeWithUnit)(value)) {
+        return _parse(value, sec);
+    }
+    else if ((0, primitives_1.isNumber)(value)) {
+        return _parse(`${value}s`, sec);
+    }
+    return NaN;
+}
+function _parse(str, sec = false) {
+    if (!(0, primitives_1.isNonEmptyString)(str) || str.length > 100) {
+        throw new RangeError(`Value must be a string with length between 1 and 99!`);
+    }
+    const match = constants_1.TIME_UNIT_REGEX.exec(str);
+    if (!match?.groups)
+        return NaN;
+    const unit = (match.groups.unit ?? 'ms').toLowerCase();
+    const multiplier = constants_1.MS_MAP[unit];
+    if (!multiplier)
+        throw new RangeError(`Unknown unit "${unit}"!`);
+    const ms = parseFloat(match.groups.value) * multiplier;
+    return sec ? ms / 1000 : ms;
+}

package/dist/cjs/hash/Cipher.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cipher = void 0;
+const primitives_1 = require("../guards/primitives");
+const specials_1 = require("../guards/specials");
+const helpers_1 = require("./helpers");
+const utils_1 = require("./utils");
+class Cipher {
+    #secretBytes;
+    #encKey;
+    #macKey;
+    constructor(secret) {
+        if (!(0, primitives_1.isNonEmptyString)(secret)) {
+            throw new Error('Secret must be non-empty string!');
+        }
+        this.#secretBytes = (0, utils_1.utf8ToBytes)(secret);
+        this.#encKey = (0, utils_1.hmacSha256)(this.#secretBytes, (0, utils_1.utf8ToBytes)('enc'));
+        this.#macKey = (0, utils_1.hmacSha256)(this.#secretBytes, (0, utils_1.utf8ToBytes)('mac'));
+    }
+    #genKeystream(target, iv) {
+        const blocks = Math.ceil(target.length / 32);
+        const keystreamParts = [];
+        for (let counter = 0; counter < blocks; counter++) {
+            keystreamParts.push((0, utils_1.hmacSha256)(this.#encKey, (0, utils_1.concatBytes)(iv, (0, utils_1.intTo4BytesBE)(counter))));
+        }
+        return (0, utils_1.concatBytes)(...keystreamParts).subarray(0, target.length);
+    }
+    encrypt(text) {
+        const plain = (0, utils_1.utf8ToBytes)(text);
+        const seed = (0, utils_1.utf8ToBytes)(String(Date.now()) + '-' + String(Math.random()));
+        const ivFull = (0, utils_1.sha256Bytes)(seed);
+        const iv = ivFull.subarray(0, 16);
+        const keystream = this.#genKeystream(plain, iv);
+        const ct = new Uint8Array(plain.length);
+        for (let i = 0; i < plain.length; i++)
+            ct[i] = plain[i] ^ keystream[i];
+        const tag = (0, utils_1.hmacSha256)(this.#macKey, (0, utils_1.concatBytes)(iv, ct));
+        const blob = (0, utils_1.concatBytes)(iv, ct, tag);
+        return (0, utils_1.bytesToBase64)(blob);
+    }
+    isValid(token) {
+        if (!(0, specials_1.isBase64)(token))
+            return false;
+        const blob = (0, utils_1.base64ToBytes)(token);
+        if (blob.length < 48)
+            return false;
+        const iv = blob.subarray(0, 16);
+        const tag = blob.subarray(blob.length - 32);
+        const ct = blob.subarray(16, blob.length - 32);
+        const expectedTag = (0, utils_1.hmacSha256)(this.#macKey, (0, utils_1.concatBytes)(iv, ct));
+        return (0, helpers_1._constantTimeEquals)(expectedTag, tag);
+    }
+    decrypt(token) {
+        if (!(0, specials_1.isBase64)(token))
+            throw new Error('Token must be a base64 string!');
+        const blob = (0, utils_1.base64ToBytes)(token);
+        if (blob.length < 48)
+            throw new Error('Malformed or tampered token!');
+        const iv = blob.subarray(0, 16);
+        const tag = blob.subarray(blob.length - 32);
+        const ct = blob.subarray(16, blob.length - 32);
+        const expectedTag = (0, utils_1.hmacSha256)(this.#macKey, (0, utils_1.concatBytes)(iv, ct));
+        if (!(0, helpers_1._constantTimeEquals)(expectedTag, tag)) {
+            throw new Error('Key in the token is tampered or invalid!)');
+        }
+        const keystream = this.#genKeystream(ct, iv);
+        const pt = new Uint8Array(ct.length);
+        for (let i = 0; i < ct.length; i++)
+            pt[i] = ct[i] ^ keystream[i];
+        return (0, utils_1.bytesToUtf8)(pt);
+    }
+}
+exports.Cipher = Cipher;

package/dist/cjs/hash/Signet.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Signet = void 0;
+const parse_1 = require("../date/parse");
+const non_primitives_1 = require("../guards/non-primitives");
+const primitives_1 = require("../guards/primitives");
+const index_1 = require("../utils/index");
+const helpers_1 = require("./helpers");
+const utils_1 = require("./utils");
+class Signet {
+    #secretBytes;
+    constructor(secret) {
+        if (!(0, primitives_1.isNonEmptyString)(secret)) {
+            throw new Error('Secret must be a non-empty string!');
+        }
+        this.#secretBytes = (0, utils_1.utf8ToBytes)(secret);
+    }
+    #decode(token) {
+        if (!(0, primitives_1.isNonEmptyString)(token)) {
+            throw new Error('Token must be a non-empty string!');
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            throw new Error('Token is tampered or malformed!');
+        }
+        const [hdr, pld, signature] = parts;
+        const headerBytes = (0, utils_1.base64ToBytes)(hdr);
+        const payloadBytes = (0, utils_1.base64ToBytes)(pld);
+        const headerStr = (0, index_1.stripJsonEdgeGarbage)((0, utils_1.bytesToUtf8)(headerBytes));
+        const payloadStr = (0, index_1.stripJsonEdgeGarbage)((0, utils_1.bytesToUtf8)(payloadBytes));
+        let header;
+        try {
+            header = JSON.parse(headerStr);
+        }
+        catch {
+            throw new Error('Cannot parse header!');
+        }
+        let payload;
+        try {
+            const { iat, iatDate, exp, expDate, nbf, nbfDate, aud, sub, iss, ...rest } = JSON.parse(payloadStr);
+            payload = {
+                iat,
+                iatDate: iatDate ? new Date(iatDate) : (0, helpers_1._secToDate)(iat),
+                ...(exp && { exp }),
+                ...(exp && { expDate: expDate ? new Date(expDate) : (0, helpers_1._secToDate)(exp) }),
+                ...(nbf && { nbf }),
+                ...(nbf && { nbfDate: nbfDate ? new Date(nbfDate) : (0, helpers_1._secToDate)(nbf) }),
+                ...(aud && { aud }),
+                ...(sub && { sub }),
+                ...(iss && { iss }),
+                ...rest,
+            };
+        }
+        catch {
+            throw new Error('Cannot parse payload!');
+        }
+        return {
+            header,
+            payload,
+            signature,
+            signingInput: `${hdr}.${pld}`,
+        };
+    }
+    sign(payload, options) {
+        if (!(0, non_primitives_1.isNotEmptyObject)(payload))
+            throw new Error('Payload must be a valid object!');
+        const { expiresIn, notBefore, audience, issuer, subject } = options || {};
+        const iat = (0, helpers_1._toSeconds)(Date.now());
+        const $payload = {
+            iat,
+            iatDate: (0, helpers_1._secToDate)(iat),
+            ...(expiresIn && { exp: iat + (0, helpers_1._toSeconds)((0, parse_1.parseMSec)(expiresIn)) }),
+            ...(expiresIn && { expDate: (0, helpers_1._secToDate)(iat + (0, helpers_1._toSeconds)((0, parse_1.parseMSec)(expiresIn))) }),
+            ...(notBefore && { nbf: iat + (0, helpers_1._toSeconds)((0, parse_1.parseMSec)(notBefore)) }),
+            ...(notBefore && { nbfDate: (0, helpers_1._secToDate)(iat + (0, helpers_1._toSeconds)((0, parse_1.parseMSec)(notBefore))) }),
+            ...(audience && { aud: audience }),
+            ...(subject && { sub: subject }),
+            ...(issuer && { iss: issuer }),
+            ...payload,
+        };
+        const header = { alg: 'HS256', typ: 'SIGNET+JWT' };
+        const headerJson = (0, index_1.stableStringify)(header);
+        const payloadJson = (0, index_1.stableStringify)($payload);
+        const headerB = (0, utils_1.utf8ToBytes)(headerJson);
+        const payloadB = (0, utils_1.utf8ToBytes)(payloadJson);
+        const signingInput = `${(0, utils_1.bytesToBase64)(headerB)}.${(0, utils_1.bytesToBase64)(payloadB)}`;
+        const mac = (0, utils_1.hmacSha256)(this.#secretBytes, (0, utils_1.utf8ToBytes)(signingInput));
+        const signature = (0, utils_1.bytesToBase64)(mac);
+        return `${signingInput}.${signature}`;
+    }
+    decode(token) {
+        return this.#decode(token);
+    }
+    hasExpired(token) {
+        const { exp } = this.#decode(token).payload;
+        return exp ? (0, helpers_1._toSeconds)(Date.now()) > exp : false;
+    }
+    isTooEarly(token) {
+        const { nbf } = this.#decode(token).payload;
+        return nbf ? (0, helpers_1._toSeconds)(Date.now()) < nbf : false;
+    }
+    isInvalidIssuer(token, expected) {
+        if (!expected)
+            return false;
+        const { iss } = this.#decode(token).payload;
+        return iss ? iss !== expected : false;
+    }
+    isInvalidAudience(token, expected) {
+        if (!expected)
+            return false;
+        const { aud } = this.#decode(token).payload;
+        if (!aud)
+            return false;
+        const payloadAud = Array.isArray(aud) ? aud : [aud];
+        const expectedAud = Array.isArray(expected) ? expected : [expected];
+        return payloadAud.some((tokenAud) => expectedAud.includes(tokenAud));
+    }
+    isInvalidSubject(token, expected) {
+        if (!expected)
+            return false;
+        const { sub } = this.#decode(token).payload;
+        return sub ? sub !== expected : false;
+    }
+    verify(token, options) {
+        try {
+            const { signature, signingInput, payload } = this.#decode(token);
+            const { audience, issuer, subject } = options || {};
+            const expectedMac = (0, utils_1.hmacSha256)(this.#secretBytes, (0, utils_1.utf8ToBytes)(signingInput));
+            const expectedSig = (0, utils_1.bytesToBase64)(expectedMac);
+            if (!(0, helpers_1._constantTimeEquals)(signature, expectedSig)) {
+                throw new Error('Invalid or tampered signature!');
+            }
+            if (this.hasExpired(token)) {
+                throw new Error('Token has expired!');
+            }
+            if (this.isTooEarly(token)) {
+                throw new Error('Token is not active yet!');
+            }
+            if (this.isInvalidIssuer(token, issuer)) {
+                throw new Error('Invalid token issuer!');
+            }
+            if (this.isInvalidAudience(token, audience)) {
+                throw new Error('Invalid token audience(s!');
+            }
+            if (this.isInvalidSubject(token, subject)) {
+                throw new Error('Invalid token subject!');
+            }
+            return { isValid: true, payload };
+        }
+        catch (e) {
+            return {
+                isValid: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    verifyOrThrow(token, options) {
+        const res = this.verify(token, options);
+        if (!res.isValid) {
+            throw new Error(res.error || 'Invalid, malformed or expired token!');
+        }
+        return res;
+    }
+    decodePayload(token) {
+        return this.#decode(token).payload;
+    }
+}
+exports.Signet = Signet;

package/dist/cjs/hash/core.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.md5 = md5;
+exports.sha1 = sha1;
+exports.sha256 = sha256;
+const helpers_1 = require("./helpers");
+const utils_1 = require("./utils");
+function md5(str) {
+    const state = [1732584193, -271733879, -1732584194, 271733878];
+    const len = str.length;
+    let i;
+    for (i = 64; i <= len; i += 64) {
+        (0, helpers_1._md5cycle)(state, (0, helpers_1._stringToNumbers)(str.substring(i - 64, i)));
+    }
+    const $str = str.substring(i - 64);
+    const tail = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+    for (i = 0; i < $str.length; i++) {
+        tail[i >> 2] |= $str.charCodeAt(i) << (i % 4 << 3);
+    }
+    tail[i >> 2] |= 0x80 << (i % 4 << 3);
+    if (i > 55) {
+        (0, helpers_1._md5cycle)(state, tail);
+        for (let j = 0; j < 16; j++) {
+            tail[j] = 0;
+        }
+    }
+    tail[14] = len * 8;
+    (0, helpers_1._md5cycle)(state, tail);
+    return state.map(helpers_1._numToHex).join('');
+}
+function sha1(msg) {
+    const K = [0x5a827999, 0x6ed9eba1, 0x8f1bbcdc, 0xca62c1d6];
+    const utf8 = (0, utils_1.utf8ToBytes)(msg);
+    const rotl = (n, bits) => (n << bits) | (n >>> (32 - bits));
+    const toHex = (n) => (n >>> 0).toString(16).padStart(8, '0');
+    const len = utf8.length;
+    const padBytes = (len + 9) % 64 ? 64 - ((len + 9) % 64) : 0;
+    const total = len + 1 + padBytes + 8;
+    const words = new Uint32Array(total >>> 2);
+    for (let i = 0; i < utf8.length; i++) {
+        words[i >> 2] |= utf8[i] << (24 - (i % 4) * 8);
+    }
+    words[utf8.length >> 2] |= 0x80 << (24 - (utf8.length % 4) * 8);
+    words[words.length - 1] = utf8.length * 8;
+    const h = [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476, 0xc3d2e1f0];
+    const W = new Uint32Array(80);
+    for (let i = 0; i < words.length; i += 16) {
+        for (let j = 0; j < 16; j++)
+            W[j] = words[i + j] | 0;
+        for (let j = 16; j < 80; j++) {
+            W[j] = rotl(W[j - 3] ^ W[j - 8] ^ W[j - 14] ^ W[j - 16], 1);
+        }
+        let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4];
+        for (let j = 0; j < 80; j++) {
+            let f, k;
+            if (j < 20) {
+                f = (b & c) | (~b & d);
+                k = K[0];
+            }
+            else if (j < 40) {
+                f = b ^ c ^ d;
+                k = K[1];
+            }
+            else if (j < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = K[2];
+            }
+            else {
+                f = b ^ c ^ d;
+                k = K[3];
+            }
+            const temp = (rotl(a, 5) + f + e + k + W[j]) | 0;
+            e = d;
+            d = c;
+            c = rotl(b, 30);
+            b = a;
+            a = temp;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d) | 0;
+        h[4] = (h[4] + e) | 0;
+    }
+    return h.map(toHex).join('');
+}
+function sha256(msg) {
+    return (0, utils_1.bytesToHex)((0, utils_1.sha256Bytes)((0, utils_1.utf8ToBytes)(msg)));
+}