Mistic Auth - TypeScript Authentication Library

A robust and secure TypeScript authentication library providing cryptographic utilities for token generation, encryption, verification, and digital signatures.

Features

• 🔒 AES-256-GCM Encryption - Secure token encryption with authenticated encryption
• 🎫 Token Generation - Generate secure, verifiable authentication tokens
• ✅ Token Verification - Verify token integrity and authenticity
• 📦 Bundled - Pre-bundled with Webpack for easy distribution

Installation

npm install @magestica/crypto_auth

Quick Start

CryptoAuth - Token-Based Authentication

import CryptoAuth from '@magestica/crypto_auth';

// Initialize with a secret key
const auth = new CryptoAuth('your-secret-key');

// Generate a token
const result = auth.request('username', 'password');
console.log(result);
// {
//   token: 'encrypted-token-string',
//   check: 'md5-checksum'
// }

// Verify the token
const verified = auth.verify({
  token: result.token,
  check: result.check
});
console.log(verified);
// { username: 'username', password: 'hashed-password' }

// Generate password hash
const hashedPassword = auth.generatePassword('password');
console.log(hashedPassword);
// 'sha512-hash-of-password'

Hash Functions

import CryptoAuth from '@magestica/crypto_auth';

const auth = new CryptoAuth();

// SHA512 hashing
const hash = auth.generatePassword('password');

// MD5 for checksums (not recommended for security-critical operations)
// Used internally for token verification checksums

API Reference

CryptoAuth

Constructor

constructor(secret?: string): CryptoAuth

Creates a new CryptoAuth instance with an optional secret key. Defaults to "default_secret".

Methods

• request(username: string, password: string): TokenResult

  • Generates an encrypted token and checksum for the given credentials
  • Returns { token: string; check: string }

• verify(options: { token: string; check: string }): VerifiedToken

  • Verifies and decrypts a token
  • Returns { username: string; password: string }
  • Throws error if verification fails

• generatePassword(password: string): string

  • Generates SHA512 hash of password
  • Returns hex-encoded hash string

RSA

Constructor

constructor(publicKey: string, privateKey: string): RSA

Creates a new RSA instance with public and private keys in PEM format.

Methods

• encrypt(message: string): string

  • Encrypts message with public key
  • Returns base64-encoded ciphertext

• decrypt(ciphertext: string): string

  • Decrypts ciphertext with private key
  • Returns original message

• sign(message: string): string

  • Signs message with private key using SHA256
  • Returns base64-encoded signature

• verify(message: string, signature: string): boolean

  • Verifies signature with public key
  • Returns true if valid, false otherwise

Helper Functions

• createRSAKeyPair(modulusLength?: number): RSAKeyPair
  • Generates RSA key pair (default 2048-bit)
  • Returns { publicKey: string; privateKey: string }

Security Notes

⚠️ Important Security Considerations:

1. Secret Management - Store secrets securely, never hardcode them
2. Token Expiration - Implement token expiration in your application
3. HTTPS Only - Always transmit tokens over HTTPS
4. MD5 Caveat - MD5 is used for checksums only, not for security
5. RSA Key Size - Use at least 2048-bit keys in production

Build Instructions

Development

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Build type definitions
npm run build:types

Output Files

• dist/index.js - Main bundled library
• dist/index.d.ts - TypeScript type definitions
• dist/index.js.map - Source map (if enabled)

Project Structure

auther/
├── src/
│   ├── index.ts        # Main CryptoAuth class
│   └── rsa.ts          # RSA encryption/signing
├── dist/               # Compiled output
├── test/
│   └── test.js         # Jest tests
├── webpack.config.js   # Webpack configuration
├── tsconfig.json       # TypeScript configuration
└── package.json        # Package configuration

Testing

Run the test suite with:

npm test

Tests verify:

• Token generation and verification flow
• Password hashing
• Token integrity checks

Dependencies

Development Only

• typescript (^5.6.3) - TypeScript compiler
• webpack (^5.96.1) - Module bundler
• webpack-cli (^5.1.4) - Webpack CLI
• ts-loader (^9.5.2) - TypeScript loader for Webpack
• jest (^30.4.2) - Testing framework
• @types/node (^22.10.7) - Node.js type definitions

Runtime

• Built-in Node.js crypto module (no external dependencies!)

License

ISC

Contributing

See CONTRIBUTING.md for contribution guidelines.

Author

Mistic Auth Contributors

Troubleshooting

Token Verification Fails

• Verify you're using the same secret key for encryption and decryption
• Ensure token format hasn't been corrupted
• Check that the check value is exact match

RSA Key Format Error

• Ensure keys are in PEM format
• Verify public key in SPKI format
• Verify private key in PKCS8 format

Build Failures

• Clear node_modules and reinstall: rm -r node_modules && npm install
• Ensure Node.js version is compatible (14+)
• Run npm run build:types separately for type generation

Performance Notes

• Token generation: ~1-2ms average

• Token verification: ~1-2ms average

• RSA operations scale with key size (2048-bit: ~5-10ms)