🔐 Secure Crypto Toolkit

A comprehensive TypeScript cryptography toolkit for learning and understanding modern encryption, authentication, and security techniques. Implements multiple encryption modes, password utilities, OTP generation, and more with security best practices.

⚠️ DISCLAIMER

THIS LIBRARY IS PROVIDED FOR EDUCATIONAL AND PERSONAL USE ONLY.

THE AUTHOR(S) ACCEPT NO RESPONSIBILITY OR LIABILITY WHATSOEVER FOR:

- Any security vulnerabilities or weaknesses in this code
- Data loss, corruption, or unauthorized access resulting from use of this library
- Any damages, direct or indirect, arising from the use of this software
- Compliance with security standards, regulations, or legal requirements
- Production use of this library in any context

This library has NOT undergone professional security audits. While it implements modern cryptographic practices, it may contain bugs, implementation flaws, or design weaknesses.

For production systems handling sensitive data (financial, healthcare, personal information, etc.), you MUST use established, audited libraries:

- libsodium / sodium-native
- tweetnacl
- Native Web Crypto API
- bcrypt / argon2 for password hashing
- otplib for production OTP systems

BY USING THIS SOFTWARE, YOU AGREE THAT:

- You use it entirely at your own risk
- The author(s) have no obligation to provide support, updates, or security patches
- You are solely responsible for evaluating the security implications of using this code
- This library is intended for learning, experimentation, and low-risk personal projects only

🎯 What You'll Learn

$3

- Symmetric encryption (AES-256-GCM with password-based key derivation)
- Asymmetric encryption (RSA-OAEP envelope encryption)
- Elliptic Curve Cryptography (X25519 key exchange with ECDH)
- Digital signatures (Ed25519 for authentication)
- Forward secrecy (ephemeral keys)
- Replay attack prevention (timestamps)
- Key derivation (scrypt, HKDF)

$3

- Secure password generation (cryptographically random)
- Password hashing and verification (scrypt with automatic salt generation)
- UUID generation (v4, cryptographically random)
- OTP generation (HOTP and TOTP for 2FA)
- HMAC-based authentication

$3

- Cryptographic hashing (SHA-256, SHA-512, etc.)
- HMAC operations (keyed-hash message authentication)
- Secure random number generation

$3

- Threat model
- Known limitations
- Security recommendations

📦 Installation

``bash
npm install simple-crypto-utils
`

🚀 Quick Start

$3

`typescript
import { encrypt, decrypt } from "simple-crypto-utils";

// Encrypt
const encrypted = await encrypt(
{ type: "symmetric-password", password: "MyStr0ng!Pass123" },
"Secret message"
);

// Decrypt
const decrypted = await decrypt(
{ type: "symmetric-password", password: "MyStr0ng!Pass123" },
encrypted.data
);

console.log(decrypted.data); // "Secret message"
`

$3

`typescript
import {
generatePassword,
hashPassword,
verifyPassword,
} from "simple-crypto-utils";

// Generate secure password
const password = generatePassword(16); // "aB3$xK9@mPq2#R5z"

// Hash password for storage
const hashed = await hashPassword("user_password_123");
// Returns: "scrypt$16384$8$1$$"

// Verify password
const isValid = await verifyPassword("user_password_123", hashed);
console.log(isValid); // true
`

$3

`typescript
import { generateOTP, generateTOTP } from "simple-crypto-utils";

// Generate one-time password (HOTP)
const otp = generateOTP(); // "123456"

// Generate time-based OTP (TOTP)
const secret = "BASE32ENCODEDSECRET";
const totp = generateTOTP(secret); // "654321" (changes every 30s)

// NOT YET IMPLEMENTED
// Verify TOTP with time window
const isValid = verifyTOTP(secret, "654321", { window: 1 });
console.log(isValid); // true if within time window
`

$3

`typescript
import { generateUUID } from "simple-crypto-utils";

const id = generateUUID();
console.log(id); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
`

$3

`typescript
import { hash, hmac } from "simple-crypto-utils";

// Hash data
const dataHash = hash("sensitive data", "sha256");

// Create HMAC for authentication
const signature = hashHmac("message", "secret-key", "sha256");

// Verify HMAC
const signature = hashHmac(hashedMessage, "secret-key", "sha256");
`

$3

`typescript
// Using the class Key (recommend)
import { Key } from "simple-crypto-utils";

const keys = await Key.generate("sign");
console.log(keys);
// {publicKey:"Mc....", privateKey:"Mc....."}
`

$3

`typescript
import { encrypt, decrypt, generateRSAKeyPair } from "simple-crypto-utils";

// Generate keys
const { publicKey, privateKey } = generateRSAKeyPair();

// Encrypt for recipient
const encrypted = await encrypt(
{ type: "sealEnvelope", recipientPublicKey: publicKey },
"Confidential data"
);

// Decrypt
const decrypted = await decrypt(
{ type: "openEnvelope", recipientPrivateKey: privateKey },
encrypted.data
);
`

$3

`typescript
import { encrypt, decrypt, generateX25519KeyPair } from "simple-crypto-utils";

// Bob generates keys
const bob = generateX25519KeyPair();

// Alice sends to Bob
const encrypted = await encrypt(
{ type: "secure-channel", recipientPublicKey: bob.publicKey },
"Private message"
);

// Bob decrypts
const decrypted = await decrypt(
{ type: "secure-channel", recipientPrivateKey: bob.privateKey },
encrypted.data
);
`

$3

`typescript
import {
encrypt,
decrypt,
generateAuthenticatedKeySet,
} from "simple-crypto-utils";

// Generate keys for both parties
const alice = generateAuthenticatedKeySet();
const bob = generateAuthenticatedKeySet();

// Alice sends authenticated message to Bob
const encrypted = await encrypt(
{
type: "authenticated-channel",
recipientPublicKey: bob.encryption.publicKey,
senderPrivateKey: alice.signing.privateKey,
},
"Authenticated message"
);

// Bob verifies and decrypts
const decrypted = await decrypt(
{
type: "authenticated-channel",
recipientPrivateKey: bob.encryption.privateKey,
senderPublicKey: alice.signing.publicKey,
},
encrypted.data
);

console.log(decrypted.metadata.authenticated); // true
`

📁 File Encryption

All encryption modes support file encryption with streaming for memory efficiency:

`typescript
import { encrypt, decrypt } from "simple-crypto-utils";

// Encrypt file
await encrypt(
{ type: "symmetric-password", password: "SecurePass123!" },
undefined,
"./sensitive.pdf",
"./sensitive.pdf.enc"
);

// Decrypt file
await decrypt(
{ type: "symmetric-password", password: "SecurePass123!" },
undefined,
"./sensitive.pdf.enc",
"./sensitive-decrypted.pdf"
);
`

🔒 Security Features

$3

| Feature | Description |
| ----------------------- | ----------------------------------------------- |
| Confidentiality | AES-256-GCM encryption |
| Integrity | Authenticated encryption with GCM auth tags |
| Forward Secrecy | Ephemeral ECDH keys (secure-channel mode) |
| Authentication | Ed25519 signatures (authenticated-channel mode) |
| Replay Protection | Timestamp validation (optional) |
| Key Validation | Automatic verification of key types and formats |
| Version Control | Format versioning for backward compatibility |
| Password Protection | scrypt KDF with automatic salt generation |
| Secure Random | Cryptographically secure random generation |
| Time-based Security | TOTP with configurable time windows |

$3

#### Encryption Modes

| Mode | Confidentiality | Integrity | Authentication | Forward Secrecy |
| ----------------------- | --------------- | --------- | -------------- | --------------- |
| symmetric-password | ✅ | ✅ | ❌ | N/A |
| sealEnvelope | ✅ | ✅ | ❌ | ❌ |
| secure-channel | ✅ | ✅ | ❌ | ✅ |
| authenticated-channel | ✅ | ✅ | ✅ | ✅ |

#### Authentication Features

| Feature | Algorithm | Use Case |
| ------------------- | --------- | ---------------------------- |
| Password Hashing | scrypt | User authentication |
| HOTP | HMAC-SHA1 | Counter-based 2FA |
| TOTP | HMAC-SHA1 | Time-based 2FA (Google Auth) |
| UUID | Random v4 | Unique identifiers |
| Password Generation | Random | Secure password creation |

🛡️ Strict Mode

Enable strict mode for maximum security enforcement:

`typescript
const encrypted = await encrypt(
{
type: "symmetric-password",
password: "pass",
strictMode: true, // Enforces strong passwords, all validations
},
"data"
);
`

Strict mode enforces:

- Strong password requirements (uppercase, lowercase, numbers, special chars)
- Timestamp validation (prevents replay attacks)
- All security checks enabled

⏱️ Replay Attack Prevention

Secure and authenticated channels include timestamps by default:

`typescript
// Encrypt with timestamp (default)
const encrypted = await encrypt(
{
type: "secure-channel",
recipientPublicKey: pubKey,
includeTimestamp: true, // default
},
"time-sensitive data"
);

// Decrypt with validation (default: 5 minute window)
const decrypted = await decrypt(
{
type: "secure-channel",
recipientPrivateKey: privKey,
validateTimestamp: true, // default
},
encrypted.data
);
`

🔑 API Reference

$3

`typescript
// Generate cryptographically secure password
generatePassword(length: number = 16, options?: {
uppercase?: boolean; // Default: true
lowercase?: boolean; // Default: true
numbers?: boolean; // Default: true
symbols?: boolean; // Default: true
}): string

// Hash password with scrypt
hashPassword(password: string, options?: {
N?: number; // CPU/memory cost (default: 16384)
r?: number; // Block size (default: 8)
p?: number; // Parallelization (default: 1)
keylen?: number; // Output length (default: 32)
}): Promise

// Verify password against hash
verifyPassword(password: string, hash: string): Promise
`

$3

`typescript
// Generate HMAC-based OTP
generateOTP(secret: string, counter: number, digits?: number): string

// Generate time-based OTP
generateTOTP(secret: string, options?: {
time?: number; // Unix timestamp (default: Date.now())
step?: number; // Time step in seconds (default: 30)
digits?: number; // OTP length (default: 6)
}): string

// Verify TOTP with time window
verifyTOTP(secret: string, token: string, options?: {
time?: number;
step?: number;
window?: number; // Allow ±N time steps (default: 1)
}): boolean
`

$3

`typescript
// Hash data
hash(data: string, algorithm?: string): string // Default: sha256

// Generate HMAC
hmac(data: string, key: string, algorithm?: string): string // Default: sha256
`

$3

`typescript
// Generate UUID v4
generateUUID(): string
`

$3

_(See original documentation for encryption options)_

🧪 Testing

`bash
npm test # Run all tests
npm run test:security # Security-specific tests
npm run test:coverage # Coverage report
npm run test:password # Password utility tests
npm run test:otp # OTP/TOTP tests
`

🎓 Educational Notes

$3

`
Encryption
├─ symmetric-password: Personal file encryption, backups
├─ sealEnvelope: Email encryption, legacy compatibility
├─ secure-channel: Secure messaging, forward secrecy
└─ authenticated-channel: Critical communications, signed documents

Authentication
├─ Password hashing: User account security
├─ HOTP: Hardware tokens, API counters
├─ TOTP: Mobile 2FA apps (Google Authenticator)
└─ HMAC: API signatures, webhook verification

Utilities
├─ UUID: Database IDs, session tokens
├─ Password generation: Temporary passwords, API keys
└─ Hashing: Data integrity, checksums
`

$3

- AES-256-GCM: Authenticated encryption
- scrypt: Password-based key derivation (memory-hard)
- RSA-OAEP: Asymmetric encryption
- X25519: Elliptic curve Diffie-Hellman
- Ed25519: Digital signatures
- HMAC-SHA1/SHA256: Message authentication
- HKDF: Key derivation from shared secrets
- CSPRNG: Cryptographically secure random generation

🐛 Common Issues

$3

- Weak password errors: Use strictMode: false for testing or generate with generatePassword()
- Hash verification fails: Ensure you're using the same scrypt parameters

$3

- TOTP mismatch: Check system time synchronization (NTP)
- Time window errors: Increase window parameter for clock drift

$3

- Invalid key errors: Ensure correct key type (RSA vs X25519 vs Ed25519)
- Message expired errors: Message older than 5 minutes or clocks not synchronized

🛠️ Development

$3

`bash


Clone repository

git clone https://github.com/yourusername/simple-crypto-utils.git
cd simple-crypto-utils

Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run tests in watch mode

npm run test:watch

Check coverage

npm run test:coverage
`

$3

`
src/
|-- crypto/
| |-- encrypt.ts # Encryption logic
| |-- decrypt.ts # Decryption logic
| |-- index.ts # Export point and class Crypto
├── hash/
| |-- hash.ts # Simple hashign
| |-- hashHmac.ts # Hashing using hmac
| |-- verifyHmac.ts # Verify hmac hash time safe
| |-- index.ts # Export point no class for the moment
├── keys.ts
| |-- aes.ts # Generation random aes key & iv
| |-- authenticate.ts # Generation X25519 key pair & Ed25519 key pair
| |-- ecdh.ts # Generation X25519 key pair
| |-- ed25519.ts # Generation ED25519 key pair
| |-- rsa.ts # Generation RSA key pair
| |-- x25519.ts # Generation X25519 key pair
| |-- index.ts # Export point and class Key
├── otp
| |-- otp.ts # Generation OTP (no hash or verify for the moment)
| |-- totp.ts # Generation TOTP (no verify for the moment)
| |-- index.ts # Export point no class for the moment
├── password
| |-- generate.ts # Generation safe & random password
| |-- hash.ts # Hashing the password with scrypt
| |-- verify.ts # Verify the hashed password
| |-- index.ts # Export point no class for the moment
├── signature
| |-- sign.ts # Sign logic
| |-- verify.ts # Verify logic
| |-- index.ts # Export point and class Signer
├── index.ts # Public API
└── examples.ts # Examples functions
`

$3

Create a script to generate keys for testing:

`typescript
// generate-keys.js
import { Key } from "simple-crypto-utils";

const fs = require("fs");

// Create keys directory
if (!fs.existsSync("./keys")) {
fs.mkdirSync("./keys", { mode: 0o700 });
}

// Generate keys
const rsa = Key.generate("seal");
const x25519 = Key.generate("secure-channel");
const auth = Key.generate("sign");

// Save keys (restrict permissions)
fs.writeFileSync("./keys/rsa-public.key", rsa.publicKey);
fs.writeFileSync("./keys/rsa-private.key", rsa.privateKey, { mode: 0o600 });
fs.writeFileSync("./keys/x25519-public.key", x25519.publicKey);
fs.writeFileSync("./keys/x25519-private.key", x25519.privateKey, {
mode: 0o600,
});

console.log("✅ Keys generated in ./keys/");
`

Important: Add to .gitignore:

`
keys/
*.key
.env
`

$3

For testing, create .env (don't commit):

`bash


Test credentials (NOT for production)

TEST_PASSWORD=TestPassword123!
TOTP_TEST_SECRET=JBSWY3DPEHPK3PXP

Node environment

NODE_ENV=development
`

$3

`bash


Run example file

node dist/examples.js

Or with ts-node

npx ts-node src/examples.ts
`

$3

`bash


Login to npm

npm login

Dry run

npm publish --dry-run

Publish

npm publish
`

🤝 Contributing

This is an educational project. Contributions welcome:

- Bug fixes
- Additional cryptographic features
- Documentation improvements
- More test cases
- Security analysis reports

Please do NOT:

- Remove security checks
- Weaken cryptographic parameters
- Add backdoors or intentional vulnerabilities

$3

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Write tests for new features
4. Ensure all tests pass (npm test)
5. Update documentation
6. Submit pull request

Don't:

- Remove security checks
- Weaken cryptographic parameters
- Add backdoors or vulnerabilities
- Commit private keys or secrets

📝 License

MIT License

Copyright (c) [2026] [Alessio Galtelli]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.**

🙏 Acknowledgments

Built with:

- Node.js crypto` module (native cryptographic primitives)
- Inspired by libsodium, Signal Protocol, OWASP guidelines, and RFC specifications

Educational resources:

- RFC 4226 (HOTP)
- RFC 6238 (TOTP)
- Signal Protocol Specification
- NIST Guidelines on Cryptography

📚 Further Reading

- Cryptography Engineering (Book)
- OWASP Password Storage Cheat Sheet
- OWASP Authentication Cheat Sheet
- Soatok's Crypto Blog

---

⚠️ FINAL REMINDER: This library is for learning and experimentation. Cryptography is extremely difficult to implement correctly. For anything important, use professionally audited libraries. The authors accept absolutely no responsibility for any consequences of using this code.