@oreefy/hash

Zero-dependency, secure plaintext hashing for JavaScript/TypeScript using Web Crypto API (PBKDF2-SHA512) with constant-time comparison, Base64Url encoding, and 100k iterations.

@oreefy/hash is a library built for the Oreefy ecosystem. The package is officially developed, maintained, and fully controlled by Oreefy, ensuring long-term stability, consistency, and compatibility across the ecosystem.

Required Capabilities

• JavaScript / TypeScript
• Web Crypto API (crypto)

API Reference

| Constant | Value | | ------------------- | ------------- | | VERSION | v1 | | ALGORITHM | PBKDF2-SHA512 | | ITERATIONS | 100_000 | | SALT_LENGTH | 16 | | KEY_LENGTH | 64 | | MAX_PLAINTEXT_BYTES | 1024 |

import { hash } from "@oreefy/hash";

await hash.make();
await hash.compare();

hash.make()

Creates a secure, salted hash from plaintext.

Before hashing, the input is normalized using NFC, checked against the maximum byte length, and combined with a cryptographically secure 16-byte salt. The final key is derived using PBKDF2-SHA512 with 100,000 iterations.

Example

import { hash } from "@oreefy/hash";

const hashed = await hash.make("my-super-secret-plaintext");
console.log(hashed);

Parameters

• plaintext: string — The plaintext to hash. It must be non-empty and no larger than 1024 bytes after UTF-8 encoding.

Returns

Promise<string> — A formatted hash string:

<VERSION>$<ALGORITHM>$<i=ITERATIONS>$<BASE64_SALT>$<BASE64_HASH>

Errors

Throws an error when the input is invalid or cannot be processed.

hash.compare()

Verifies plaintext against a previously generated hash.

The comparison is performed in constant time to help mitigate timing attacks.

hash.compare() is designed to be safe to use with untrusted input: it never throws. Invalid input, malformed hashes, and non-matching plaintext simply return false.

Example

import { hash } from "@oreefy/hash";

const isMatch = await hash.compare("plaintext", "hashed-string");
console.log(isMatch);

Parameters

• plaintext: string — The plaintext to verify.
• hash: string — A hash generated by hash.make().

Returns

Promise<boolean> — Returns true when the plaintext matches the hash; otherwise false.

Technical Highlights

• Zero Dependencies — Uses only the native Web Crypto API.
• Cross-Runtime — Works anywhere Web Crypto is available, including Node.js, Bun, Deno, Cloudflare Workers, browsers, and edge runtimes.
• Secure by Default — PBKDF2-SHA512 with 100,000 iterations, a 16-byte salt, and a 64-byte derived key.
• Timing-Safe Comparison — Uses constant-time comparison to reduce timing-attack risk.
• Strict Parsing — Validates the version, algorithm, iteration count, salt, hash length, and Base64Url encoding.

Hash Format

The generated hash follows a modular, future-proof format:

v1$PBKDF2-SHA512$i=100000$<Base64Url-Salt>$<Base64Url-Hash>

| Part | Description | | --------------- | -------------------------------------------------------- | | v1 | Hash format version | | PBKDF2-SHA512 | Key derivation algorithm | | i=100000 | PBKDF2 iteration count | | Salt | 16-byte cryptographically secure salt, Base64Url encoded | | Hash | 64-byte derived key, Base64Url encoded |

Security

@oreefy/hash applies several safeguards by default:

1. Unicode normalization — Plaintext is normalized using NFC for consistent hashing across platforms.
2. Input size limit — Plaintext larger than 1024 bytes is rejected to help reduce denial-of-service risk.
3. Strict Base64Url validation — Encoded values are validated before decoding to reject malformed hash data.
4. Constant-time comparison — Hash verification avoids regular string comparison for the derived key.

About Oreefy

Oreefy is an affordable business ecosystem designed for small to enterprise businesses. Oreefy provides essential software you need for your modern business within a single ecosystem. It will save you significant time, effort, and money.

License

MIT © Oreefy