For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

✨ Why SmartHash?

🌐 Universal SHA-256: Works in Node.js and browsers without polyfills
⚡ Smart Fallbacks: Uses the local implementation when Web Crypto is unavailable
🔧 TypeScript First: Full type safety and IntelliSense support
📦 Dual Entry Points: Optimized builds for both environments
🎯 Simple API: Consistent interface across all platforms

🚀 Quick Start

pnpm install @push.rocks/smarthash

📖 API Reference

🔤 String Hashing

import { sha256FromString, sha256FromStringSync } from '@push.rocks/smarthash';

// Async (works everywhere)
const hash = await sha256FromString('Hello, world!');
console.log(hash); // 📄 64-character hex string

// Sync (Node.js and browsers)
const hashSync = sha256FromStringSync('Hello, world!');
console.log(hashSync); // ⚡ Instant result

Browser code imports the same functions from @push.rocks/smarthash/web.

🗂️ File & Stream Hashing

import { sha256FromFile, sha256FromStream } from '@push.rocks/smarthash';
import fs from 'fs';

// Hash files directly
const fileHash = await sha256FromFile('./myfile.txt');
console.log(fileHash); // 📁 File's SHA256 hash

// Hash streams (perfect for large files)
const stream = fs.createReadStream('./largefile.zip');
const streamHash = await sha256FromStream(stream);
console.log(streamHash); // 🌊 Stream's SHA256 hash

sha256FromFile() is Node-only. sha256FromStream() accepts Node readable streams in the main entrypoint and WHATWG ReadableStream<Uint8Array> objects in both entrypoints.

🧱 Buffer Hashing

import { sha256FromBuffer } from '@push.rocks/smarthash';

// Works with both Buffer (Node.js) and Uint8Array (Browser)
const encoder = new TextEncoder();
const buffer = encoder.encode('Hello, world!');
const bufferHash = await sha256FromBuffer(buffer);
console.log(bufferHash); // 🔢 Buffer's SHA256 hash

Incremental Hashing

createSha256Hasher() is available from both entrypoints and accepts incremental updates without buffering the complete payload.

import { createSha256Hasher } from '@push.rocks/smarthash';

const hasher = createSha256Hasher();
hasher.update(new Uint8Array([0xca, 0xfe]));
hasher.update(new Uint8Array([0xba, 0xbe]));
const digest = hasher.digest();

update() accepts ArrayBuffer and Uint8Array values and returns the hasher for chaining. digest() returns lowercase hexadecimal and finalizes the instance. Further update() or digest() calls throw.

Browser byte streams can be hashed directly:

import { sha256FromStream } from '@push.rocks/smarthash/web';

const response = await fetch('/artifact');
const digest = await sha256FromStream(response.body!);

🎯 Object Hashing

import { sha265FromObject } from '@push.rocks/smarthash';

// Consistent hashing for JavaScript objects
const myObject = { 
  userId: 12345, 
  role: 'admin',
  timestamp: Date.now()
};

const objectHash = await sha265FromObject(myObject);
console.log(objectHash); // 🎯 Deterministic object hash

🔥 Pro Tip: Object property order doesn't matter! {a: 1, b: 2} and {b: 2, a: 1} produce the same hash.

🛡️ MD5 Hashing (Node.js Only)

import { md5FromString } from '@push.rocks/smarthash';

// Legacy MD5 support (use SHA256 for new projects!)
const md5Hash = await md5FromString('Hello, world!');
console.log(md5Hash); // 🔐 32-character MD5 hash

🌍 Environment Compatibility

The Browser column refers to the @push.rocks/smarthash/web entrypoint.

Function	Node.js	Browser	Notes
`sha256FromString`	✅	✅	Universal support
`sha256FromStringSync`	✅	✅	Local incremental implementation in browsers
`sha256FromBuffer`	✅	✅	Handles Buffer/Uint8Array
`sha256FromFile`	✅	❌	File system access required
`sha256FromStream`	✅	✅	Node streams and WHATWG byte streams
`createSha256Hasher`	✅	✅	Incremental, bounded-memory SHA-256
`sha265FromObject`	✅	✅	Existing typo-preserving API; uses JSON serialization
`md5FromString`	✅	❌	Not supported by Web Crypto API

🔧 Advanced Usage

Error Handling

import { sha256FromString } from '@push.rocks/smarthash';

try {
  const hash = await sha256FromString('sensitive data');
  console.log(`✅ Hash computed: ${hash}`);
} catch (error) {
  console.error('❌ Hashing failed:', error);
}

Browser-Specific Features

In browsers, SmartHash automatically:

🔒 Uses Web Crypto API when crypto.subtle is available
🔄 Falls back to the local implementation when crypto.subtle is unavailable
🌊 Hashes WHATWG byte streams incrementally

Import Strategies

// Main entry point (Node.js optimized)
import { sha256FromString } from '@push.rocks/smarthash';

// Browser-compatible entry point
import { sha256FromString } from '@push.rocks/smarthash/web';

🛠️ Development

# Run tests (both Node.js and browser)
pnpm test

# Build the project
pnpm build

# Generate documentation
pnpm buildDocs

🔐 Security Notes

✅ SHA256: Suitable for cryptographic digests and data-integrity checks
⚠️ MD5: Legacy support only, not recommended for security-critical applications
🌍 Cross-Environment: Produces identical hashes across Node.js and browsers
🔒 Web Crypto: Uses native browser APIs when available

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

🔐 @push.rocks/smarthash

Issue Reporting and Security