@altrepo/hash 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# altrepo-hash
+
+AltRepo Hash is a lightweight Node.js utility library for generating hashes and verifying checksums for text, bytes, and files.
+
+## Features
+
+- **Straightforward API:** Easily generate hashes or verify checksums with a clean, intuitive interface.
+- **Zero Dependencies:** Built entirely on top of Node.js's standard `crypto` and `fs` modules, ensuring a lightweight footprint with no external requirements.
+- **Secure Verifications:** Utilizes constant-time comparisons (`crypto.timingSafeEqual`) to securely verify file and text hashes.
+- **Broad Algorithm Support:** Includes built-in support for all major hashing algorithms including `sha256`, `sha512`, `blake2b512`, `blake2s256`, `md5`, `sha1`, and more.
+- **Memory Efficient:** Safely processes large files in chunks via `hashFile` without loading the entire file into memory using standard readable streams.
+
+## Installation
+
+```bash
+npm install altrepo-hash
+```
+
+## Example API
+
+```typescript
+import { hashText, hashFile, verifyFileHash } from "altrepo-hash";
+
+async function run() {
+  console.log(hashText("hello", "sha256"));
+
+  console.log(await hashFile("download.zip", "sha256"));
+
+  console.log(
+    await verifyFileHash("download.zip", "abc123...", "sha256")
+  );
+}
+
+run();
+```
+
+## Browser Version
+
+AltRepo Hash is the JS companion to the browser-based hash tools on AltRepo.
+
+More hash tools:
+https://altrepo.net/hash/

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+export declare function hashBlob(blob: Blob, algorithm: string): Promise<string>;
+export declare function hashFile(file: File, algorithm: string): Promise<string>;
+export declare function verifyBlobHash(blob: Blob, expectedHash: string, algorithm: string): Promise<boolean>;

package/dist/browser.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashBlob = hashBlob;
+exports.hashFile = hashFile;
+exports.verifyBlobHash = verifyBlobHash;
+const shared_1 = require("./shared");
+async function hashBlob(blob, algorithm) {
+    const arrayBuffer = await blob.arrayBuffer();
+    return (0, shared_1.hashBytes)(arrayBuffer, algorithm);
+}
+async function hashFile(file, algorithm) {
+    return hashBlob(file, algorithm);
+}
+// Simple constant-time comparison for browser
+function secureCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let mismatch = 0;
+    for (let i = 0; i < a.length; ++i) {
+        mismatch |= (a.charCodeAt(i) ^ b.charCodeAt(i));
+    }
+    return mismatch === 0;
+}
+async function verifyBlobHash(blob, expectedHash, algorithm) {
+    const actualHash = await hashBlob(blob, algorithm);
+    return secureCompare(actualHash, expectedHash.toLowerCase());
+}

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+export declare function hashFile(filePath: string, algorithm: string): Promise<string>;
+export declare function verifyFileHash(filePath: string, expectedHash: string, algorithm: string): Promise<boolean>;

package/dist/node.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashFile = hashFile;
+exports.verifyFileHash = verifyFileHash;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+async function hashFile(filePath, algorithm) {
+    return new Promise((resolve, reject) => {
+        try {
+            // Allow node formats like 'sha256'
+            const alg = algorithm.toLowerCase().replace("_", "-").replace("sha-", "sha");
+            const hasher = crypto.createHash(alg);
+            const stream = fs.createReadStream(filePath);
+            stream.on("error", (err) => reject(err));
+            stream.on("data", (chunk) => hasher.update(chunk));
+            stream.on("end", () => resolve(hasher.digest("hex")));
+        }
+        catch (err) {
+            reject(err);
+        }
+    });
+}
+function secureCompare(actualHex, expectedHex) {
+    const actualBuffer = Buffer.from(actualHex, "hex");
+    const expectedBuffer = Buffer.from(expectedHex.toLowerCase(), "hex");
+    if (actualBuffer.length !== expectedBuffer.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+async function verifyFileHash(filePath, expectedHash, algorithm) {
+    const actualHash = await hashFile(filePath, algorithm);
+    return secureCompare(actualHash, expectedHash);
+}

package/dist/shared.d.ts

@@ -0,0 +1,10 @@
+export declare const SUPPORTED_ALGORITHMS: string[];
+export declare function supportedAlgorithms(): string[];
+/**
+ * Generate a hash string from a Uint8Array or ArrayBuffer.
+ */
+export declare function hashBytes(data: BufferSource, algorithm: string): Promise<string>;
+/**
+ * Generate a hash string from text.
+ */
+export declare function hashText(text: string, algorithm: string): Promise<string>;

package/dist/shared.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_ALGORITHMS = void 0;
+exports.supportedAlgorithms = supportedAlgorithms;
+exports.hashBytes = hashBytes;
+exports.hashText = hashText;
+exports.SUPPORTED_ALGORITHMS = [
+    "sha-1",
+    "sha-256",
+    "sha-384",
+    "sha-512",
+];
+function supportedAlgorithms() {
+    return [...exports.SUPPORTED_ALGORITHMS];
+}
+function normalizeAlgorithm(algorithm) {
+    const alg = algorithm.toLowerCase().replace(/_/g, "-");
+    if (!alg.startsWith("sha-")) {
+        const algWithDash = alg.replace("sha", "sha-");
+        if (exports.SUPPORTED_ALGORITHMS.includes(algWithDash)) {
+            return algWithDash;
+        }
+    }
+    return alg;
+}
+/**
+ * Generate a hash string from a Uint8Array or ArrayBuffer.
+ */
+async function hashBytes(data, algorithm) {
+    const normalizedAlg = normalizeAlgorithm(algorithm);
+    if (!exports.SUPPORTED_ALGORITHMS.includes(normalizedAlg)) {
+        throw new Error(`Unsupported algorithm in browser/shared context: ${algorithm}. Supported: ${exports.SUPPORTED_ALGORITHMS.join(", ")}`);
+    }
+    const hashBuffer = await globalThis.crypto.subtle.digest(normalizedAlg, data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Generate a hash string from text.
+ */
+async function hashText(text, algorithm) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(text);
+    return hashBytes(data, algorithm);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@altrepo/hash",
+  "version": "0.1.0",
+  "description": "A lightweight multi-environment utility library for generating hashes and verifying checksums for text, bytes, and files.",
+  "exports": {
+    ".": "./dist/shared.js",
+    "./node": "./dist/node.js",
+    "./browser": "./dist/browser.js"
+  },
+  "typesVersions": {
+    "*": {
+      "node": [
+        "dist/node.d.ts"
+      ],
+      "browser": [
+        "dist/browser.d.ts"
+      ],
+      "*": [
+        "dist/shared.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hash",
+    "checksum",
+    "sha256",
+    "sha512",
+    "sha3",
+    "blake2",
+    "browser",
+    "node",
+    "webcrypto",
+    "altrepo"
+  ],
+  "homepage": "https://altrepo.net/hash/text-hash-generator.html",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alterpoYT/altrepo-hash.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alterpoYT/altrepo-hash/issues"
+  },
+  "author": "AltRepo <void@altrepo.net>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,27 @@
+import { hashBytes } from "./shared";
+
+export async function hashBlob(blob: Blob, algorithm: string): Promise<string> {
+  const arrayBuffer = await blob.arrayBuffer();
+  return hashBytes(arrayBuffer, algorithm);
+}
+
+export async function hashFile(file: File, algorithm: string): Promise<string> {
+  return hashBlob(file, algorithm);
+}
+
+// Simple constant-time comparison for browser
+function secureCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < a.length; ++i) {
+    mismatch |= (a.charCodeAt(i) ^ b.charCodeAt(i));
+  }
+  return mismatch === 0;
+}
+
+export async function verifyBlobHash(blob: Blob, expectedHash: string, algorithm: string): Promise<boolean> {
+  const actualHash = await hashBlob(blob, algorithm);
+  return secureCompare(actualHash, expectedHash.toLowerCase());
+}

package/src/node.ts

@@ -0,0 +1,33 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+
+export async function hashFile(filePath: string, algorithm: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    try {
+      // Allow node formats like 'sha256'
+      const alg = algorithm.toLowerCase().replace("_", "-").replace("sha-", "sha");
+      const hasher = crypto.createHash(alg);
+      const stream = fs.createReadStream(filePath);
+      
+      stream.on("error", (err) => reject(err));
+      stream.on("data", (chunk) => hasher.update(chunk));
+      stream.on("end", () => resolve(hasher.digest("hex")));
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+function secureCompare(actualHex: string, expectedHex: string): boolean {
+  const actualBuffer = Buffer.from(actualHex, "hex");
+  const expectedBuffer = Buffer.from(expectedHex.toLowerCase(), "hex");
+  if (actualBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+export async function verifyFileHash(filePath: string, expectedHash: string, algorithm: string): Promise<boolean> {
+  const actualHash = await hashFile(filePath, algorithm);
+  return secureCompare(actualHash, expectedHash);
+}

package/src/shared.ts

@@ -0,0 +1,44 @@
+export const SUPPORTED_ALGORITHMS = [
+  "sha-1",
+  "sha-256",
+  "sha-384",
+  "sha-512",
+];
+
+export function supportedAlgorithms(): string[] {
+  return [...SUPPORTED_ALGORITHMS];
+}
+
+function normalizeAlgorithm(algorithm: string): string {
+  const alg = algorithm.toLowerCase().replace(/_/g, "-");
+  if (!alg.startsWith("sha-")) {
+    const algWithDash = alg.replace("sha", "sha-");
+    if (SUPPORTED_ALGORITHMS.includes(algWithDash)) {
+      return algWithDash;
+    }
+  }
+  return alg;
+}
+
+/**
+ * Generate a hash string from a Uint8Array or ArrayBuffer.
+ */
+export async function hashBytes(data: BufferSource, algorithm: string): Promise<string> {
+  const normalizedAlg = normalizeAlgorithm(algorithm);
+  if (!SUPPORTED_ALGORITHMS.includes(normalizedAlg)) {
+    throw new Error(`Unsupported algorithm in browser/shared context: ${algorithm}. Supported: ${SUPPORTED_ALGORITHMS.join(", ")}`);
+  }
+
+  const hashBuffer = await globalThis.crypto.subtle.digest(normalizedAlg, data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Generate a hash string from text.
+ */
+export async function hashText(text: string, algorithm: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(text);
+  return hashBytes(data, algorithm);
+}

package/tests/browser.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeAll } from "vitest";
+import { hashBlob, hashFile, verifyBlobHash } from "../src/browser";
+
+describe("browser", () => {
+  beforeAll(() => {
+    // In jsdom WebCrypto isn't perfectly mapped to globalThis.crypto.subtle out of the box in some Node versions,
+    // but in modern Node environments globalThis.crypto works directly. We'll map Node's crypto to the global.
+    if (typeof globalThis.crypto === "undefined" || !globalThis.crypto.subtle) {
+      const crypto = require("crypto");
+      Object.defineProperty(globalThis, "crypto", {
+        value: crypto.webcrypto
+      });
+    }
+  });
+
+  it("should hash blob and verify securely", async () => {
+    const blob = new Blob(["hello browser"]);
+    const expected = "ec687a304db07950a92649222c77ef61efae6e968e62dfb6065a4f242246a760";
+    expect(await hashBlob(blob, "sha256")).toBe(expected);
+    expect(await verifyBlobHash(blob, expected, "sha256")).toBe(true);
+  });
+  
+  it("should hash File object", async () => {
+    const file = new File(["hello browser"], "test.txt");
+    const expected = "ec687a304db07950a92649222c77ef61efae6e968e62dfb6065a4f242246a760";
+    expect(await hashFile(file, "sha256")).toBe(expected);
+  });
+});

package/tests/node.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import { hashFile, verifyFileHash } from "../src/node";
+
+describe("node", () => {
+  it("should hash file and verify securely", async () => {
+    const tmpPath = path.join(__dirname, "temp-test-file.txt");
+    fs.writeFileSync(tmpPath, "hello file");
+    
+    try {
+      const expected = "f3877e8a3d98f809d9f844060fbea2864a4b66980a22ff22297014d0c168db2e";
+      expect(await hashFile(tmpPath, "sha256")).toBe(expected);
+      expect(await verifyFileHash(tmpPath, expected, "sha256")).toBe(true);
+      expect(await verifyFileHash(tmpPath, "badhash000000000000000000000000000000000000000000000000000000000", "sha256")).toBe(false);
+    } finally {
+      fs.unlinkSync(tmpPath);
+    }
+  });
+});

package/tests/shared.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { hashText, hashBytes, supportedAlgorithms } from "../src/shared";
+
+describe("shared (WebCrypto)", () => {
+  it("should have expected algorithms", () => {
+    const algs = supportedAlgorithms();
+    expect(algs).toContain("sha-256");
+  });
+
+  it("should hash text via WebCrypto", async () => {
+    const expected = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
+    expect(await hashText("hello", "sha256")).toBe(expected);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["es2022", "dom"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "tests", "dist"]
+}