Advanced Token Manager

---

Links

• English Version
• Portuguese Version

Overview

AdvancedTokenManager is a TypeScript library to generate and validate secure tokens with advanced obfuscation. Ideal for applications requiring data security, such as authentication, information signing, or secure storage.

---

Features

Performance

Performance tests show that token generation and validation are extremely fast (average result of 1,000 iterations performed 10 times). These tests were conducted on an Apple M1 processor.

• Average memory usage during token generation: 0.9766 MB.
• Average memory usage during token validation: 0.9842 MB.
• Average time for generateToken is 0.002953 ms.
• Average time for validateToken is 0.002344 ms.

Security

• Uses HMAC with a private secret to ensure token integrity.
• Adds a random salt to each token, making decryption difficult.

Flexibility

• Supports various hash algorithms (sha256 by default, sha512).
• Customizable secret and salts configuration.

Easy Integration

• Automatic generation of secret and salts if needed.
• Supports extracting original data from valid tokens.

---

Installation

npm i hash-token

---

Examples

Manual Configuration

import AdvancedTokenManager from 'hash-token';

const secretKey = process.env.SECRET_KEY || "secure-key";
const salts = process.env.SALTS?.split(',') || ["salt1", "salt2", "salt3"];

const tokenManager = new AdvancedTokenManager(secretKey, salts);

const token = tokenManager.generateToken("sensitive-data");
console.log("Generated Token:", token);

const validatedData = tokenManager.validateToken(token);
console.log(validatedData ? "Valid Token:" : "Invalid Token");

Automatic Generation (Use with Caution)

import AdvancedTokenManager from 'hash-token';

const tokenManager = new AdvancedTokenManager();

const config = tokenManager.getConfig();
console.warn("⚠️ Save these values securely:");
console.log("SECRET:", config.secret);
console.log("SALTS:", config.salts.join(','));

const token = tokenManager.generateToken("auto-generated-data");
console.log("Generated Token:", token);

const validatedData = tokenManager.validateToken(token);
console.log(validatedData ? "Valid Token:" : "Invalid Token");

Important: Save the secret and salts generated automatically to ensure consistent behavior.

Forced Salt Index Usage

You can force the use of a specific salt index when generating tokens for added control and predictability.

import AdvancedTokenManager from 'hash-token';

const tokenManager = new AdvancedTokenManager('secure-key', ['salt1', 'salt2', 'salt3']);

const token = tokenManager.generateToken('sensitive-data', 1);
console.log('Generated Token:', token);

const validatedData = tokenManager.validateToken(token);
console.log(validatedData ? 'Valid Token:' : 'Invalid Token');

Note: Ensure that the forced salt index exists, or an error will be thrown.

---

AdvancedTokenManager options

Pass an optional configuration object as the last constructor argument to fine-tune behaviour:

import AdvancedTokenManager from 'hash-token';

const manager = new AdvancedTokenManager('secure-key', ['salt1', 'salt2'], 'sha256', true, false, {
    logger: { warn: message => myLogger.warn(message) },
    jwtDefaultAlgorithms: ['HS256'],
    defaultSecretLength: 48,
    defaultSaltCount: 12,
    defaultSaltLength: 24
});

Option	Type	Requirement	Description
logger.warn	(message: string) => void	optional	Redirects warning messages (defaults to console).
logger.error	(message: string) => void	optional	Handles validation errors (defaults to console.error).
jwtDefaultAlgorithms	JwtAlgorithm[]	optional	Algorithms enforced automatically when validateJwt is called without algorithms.
defaultSecretLength	number	≥ 16	Length used when auto-generating secrets.
defaultSaltCount	number	≥ 2	Amount of salts generated when none are provided.
defaultSaltLength	number	≥ 1	Length of each generated salt string.
throwOnValidationFailure	boolean	optional	Throws instead of returning null when validateToken fails.
jwtMaxPayloadSize	number	> 0	Maximum payload size (bytes) enforced during validateJwt.
jwtAllowedClaims	string[]	optional	Whitelist of additional claims allowed beyond the standard ones.

Need stricter token handling for debugging? Pass throwOnFailure per call:

try {
    tokenManager.validateToken(token, { throwOnFailure: true });
} catch (error) {
    auditLogger.error('Suspicious token rejected', error);
}

---

JWT (native, dependency-free)

hash-token ships with a zero-dependency JSON Web Token implementation that relies on Node.js crypto only. It protects against common JWT pitfalls, enforces strict validation and integrates with the existing AdvancedTokenManager class.

Security tips for JWT usage:

• Pin algorithms in production with algorithms: ['HS256'] or ['HS512'] when verifying.
• Consider a small clockTolerance (e.g., 5–30s) in distributed systems.
• notBefore in signJwt is a relative offset (seconds) from the current time.

Core helpers

Helper	Description
signJwt(payload, options)	Builds a signed JWT string using HMAC (HS256 or HS512).
verifyJwt(token, options)	Validates structure, signature and claims before returning the payload.

Signing options

Option	Type	Default	Notes
secret	string	—	Required. HMAC secret used to sign the token.
algorithm	'HS256' | 'HS512'	HS256	Chooses the HMAC digest.
expiresIn	number (seconds)	—	Adds an exp claim relative to the current time.
notBefore	number (seconds)	—	Adds an nbf claim relative to the current time.
issuedAt	number (epoch seconds)	now	Overrides the automatic iat.
issuer	string	—	Ensures a consistent iss claim.
audience	string | string[]	—	Accepts a single or multiple audiences.
subject	string	—	Sets the sub claim.

Verification options

Option	Type	Default	Notes
secret	string	—	Required. Must match the signing secret.
algorithms	JwtAlgorithm[]	any supported	Restricts which algorithms are allowed.
clockTolerance	number (seconds)	0	Accepts small clock skews for exp, nbf, iat.
maxAge	number (seconds)	—	Caps the lifetime counted from iat.
issuer	string | string[]	—	Expected issuers. Missing or mismatched claims reject the token.
audience	string | string[]	—	Expected audiences.
subject	string	—	Expected subject.
maxPayloadSize	number (bytes)	—	Rejects tokens whose payload exceeds the configured byte length.
allowedClaims	string[]	—	Restricts additional claims to the provided whitelist (standard claims remain accepted).

Usage examples

import { signJwt, verifyJwt } from 'hash-token';

const secret = 'rotate-me';

const token = signJwt(
    { userId: 'u-123', role: 'admin' },
    { secret, algorithm: 'HS512', expiresIn: 300 }
);

const payload = verifyJwt(token, {
    secret,
    algorithms: ['HS512'],
    audience: 'dashboard'
});

console.log(payload);

For end-to-end samples, check the new scripts under examples/:

• sign-verify.ts
• with-claims.ts
• manager-integration.ts

---

Tests

Use Jest to test functionality under various scenarios, such as altered tokens or invalid salts.

npm install --save-dev jest @types/jest ts-jest
npm test

---

License

This project is licensed under the MIT License.

---

Contact

For questions or suggestions, please open an issue on GitHub.