tessl/npm-jssha

Pure TypeScript/JavaScript streaming implementation of the complete Secure Hash Standard (SHA) family with HMAC support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Variant-Specific Classes

Name: tessl/npm-jssha
Author: tessl

Optimized classes for specific SHA variants, designed for smaller bundle sizes when only particular hash algorithms are needed. These classes provide the same functionality as the universal jsSHA class but are limited to their respective SHA variants.

Capabilities

jsSHA1 - SHA-1 Implementation

Dedicated class for SHA-1 hashing with HMAC support.

/**
 * SHA-1 implementation for TEXT input format
 * @param variant - Must be "SHA-1"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional configuration including encoding and HMAC key
 */
constructor(variant: "SHA-1", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);

/**
 * SHA-1 implementation for binary input formats
 * @param variant - Must be "SHA-1"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional configuration including HMAC key and numRounds
 */
constructor(variant: "SHA-1", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);

/**
 * Stream input data for hashing
 * @param input - Input data matching the constructor inputFormat
 * @returns Reference to this object for method chaining
 */
update(input: string | ArrayBuffer | Uint8Array): this;

/**
 * Get the computed hash in the specified format
 * @param format - Output format: HEX, B64, BYTES, UINT8ARRAY, ARRAYBUFFER
 * @param options - Optional formatting options
 * @returns Hash in the specified format
 */
getHash(format: "HEX", options?: { outputUpper?: boolean }): string;
getHash(format: "B64", options?: { b64Pad?: string }): string;
getHash(format: "BYTES"): string;
getHash(format: "UINT8ARRAY"): Uint8Array;
getHash(format: "ARRAYBUFFER"): ArrayBuffer;

/**
 * Set HMAC key (deprecated - use constructor options instead)
 * @param key - HMAC key
 * @param inputFormat - Key format
 * @param options - Optional encoding for TEXT keys
 */
setHMACKey(key: string, inputFormat: "TEXT", options?: { encoding?: EncodingType }): void;
setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;

/**
 * Get HMAC output (deprecated - use getHash instead)
 * @param format - Output format
 * @param options - Optional formatting options
 * @returns HMAC in the specified format
 */
getHMAC(format: "HEX", options?: { outputUpper?: boolean }): string;
getHMAC(format: "B64", options?: { b64Pad?: string }): string;
getHMAC(format: "BYTES"): string;
getHMAC(format: "UINT8ARRAY"): Uint8Array;
getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;

type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";

interface GenericInputType {
  value: string;
  format: "TEXT";
  encoding?: EncodingType;
} | {
  value: string;
  format: "B64" | "HEX" | "BYTES";
} | {
  value: ArrayBuffer;
  format: "ARRAYBUFFER";
} | {
  value: Uint8Array;
  format: "UINT8ARRAY";
}

interface packedValue {
  value: number[];
  binLen: number;
}

interface FixedLengthOptionsEncodingType {
  hmacKey?: GenericInputType;
  encoding?: EncodingType;
} | {
  numRounds?: number;
  encoding?: EncodingType;
}

interface FixedLengthOptionsNoEncodingType {
  hmacKey?: GenericInputType;
} | {
  numRounds?: number;
}

interface SHAKEOptionsEncodingType {
  numRounds?: number;
  encoding?: EncodingType;
}

interface SHAKEOptionsNoEncodingType {
  numRounds?: number;
}

interface CSHAKEOptionsEncodingType {
  customization?: GenericInputType;
  funcName?: GenericInputType;
  encoding?: EncodingType;
}

interface CSHAKEOptionsNoEncodingType {
  customization?: GenericInputType;
  funcName?: GenericInputType;
}

interface KMACOptionsEncodingType {
  kmacKey: GenericInputType;
  customization?: GenericInputType;
  encoding?: EncodingType;
}

interface KMACOptionsNoEncodingType {
  kmacKey: GenericInputType;
  customization?: GenericInputType;
}

Usage Examples:

import jsSHA1 from "jssha/sha1";

// Basic SHA-1 hashing
const sha1 = new jsSHA1("SHA-1", "TEXT", { encoding: "UTF8" });
sha1.update("Hello, World!");
const hash = sha1.getHash("HEX");

// SHA-1 with HMAC
const hmacSha1 = new jsSHA1("SHA-1", "TEXT", {
  hmacKey: { value: "secret", format: "TEXT" }
});
hmacSha1.update("Message to authenticate");
const hmac = hmacSha1.getHash("B64");

// SHA-1 with hex input
const sha1Hex = new jsSHA1("SHA-1", "HEX");
sha1Hex.update("48656c6c6f"); // "Hello" in hex
const result = sha1Hex.getHash("UINT8ARRAY");

jsSHA256 - SHA-224/256 Implementation

Dedicated class for SHA-224 and SHA-256 hashing with HMAC support.

/**
 * SHA-224/256 implementation for TEXT input format
 * @param variant - SHA variant: "SHA-224" or "SHA-256"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional configuration including encoding and HMAC key
 */
constructor(variant: "SHA-224" | "SHA-256", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);

/**
 * SHA-224/256 implementation for binary input formats
 * @param variant - SHA variant: "SHA-224" or "SHA-256"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional configuration including HMAC key and numRounds
 */
constructor(variant: "SHA-224" | "SHA-256", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);

// Methods are identical to jsSHA1
update(input: string | ArrayBuffer | Uint8Array): this;
getHash(format: "HEX", options?: { outputUpper?: boolean }): string;
getHash(format: "B64", options?: { b64Pad?: string }): string;
getHash(format: "BYTES"): string;
getHash(format: "UINT8ARRAY"): Uint8Array;
getHash(format: "ARRAYBUFFER"): ArrayBuffer;
setHMACKey(key: string, inputFormat: "TEXT", options?: { encoding?: EncodingType }): void;
setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
getHMAC(format: "HEX", options?: { outputUpper?: boolean }): string;
getHMAC(format: "B64", options?: { b64Pad?: string }): string;
getHMAC(format: "BYTES"): string;
getHMAC(format: "UINT8ARRAY"): Uint8Array;
getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;

Usage Examples:

import jsSHA256 from "jssha/sha256";

// SHA-256 hashing
const sha256 = new jsSHA256("SHA-256", "TEXT", { encoding: "UTF8" });
sha256.update("Hello, World!");
const hash256 = sha256.getHash("HEX");

// SHA-224 hashing
const sha224 = new jsSHA256("SHA-224", "TEXT");
sha224.update("Hello, World!");
const hash224 = sha224.getHash("HEX");

// SHA-256 with HMAC
const hmac256 = new jsSHA256("SHA-256", "TEXT", {
  hmacKey: { value: "secret-key", format: "TEXT" }
});
hmac256.update("Authenticated message");
const authHash = hmac256.getHash("B64");

// Multiple rounds
const multiRound = new jsSHA256("SHA-256", "TEXT", { numRounds: 3 });
multiRound.update("Repeated hashing");
const repeatedHash = multiRound.getHash("HEX");

jsSHA512 - SHA-384/512 Implementation

Dedicated class for SHA-384 and SHA-512 hashing with HMAC support.

/**
 * SHA-384/512 implementation for TEXT input format
 * @param variant - SHA variant: "SHA-384" or "SHA-512"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional configuration including encoding and HMAC key
 */
constructor(variant: "SHA-384" | "SHA-512", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);

/**
 * SHA-384/512 implementation for binary input formats
 * @param variant - SHA variant: "SHA-384" or "SHA-512"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional configuration including HMAC key and numRounds
 */
constructor(variant: "SHA-384" | "SHA-512", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);

// Methods are identical to jsSHA1 and jsSHA256
update(input: string | ArrayBuffer | Uint8Array): this;
getHash(format: "HEX", options?: { outputUpper?: boolean }): string;
getHash(format: "B64", options?: { b64Pad?: string }): string;
getHash(format: "BYTES"): string;
getHash(format: "UINT8ARRAY"): Uint8Array;
getHash(format: "ARRAYBUFFER"): ArrayBuffer;
setHMACKey(key: string, inputFormat: "TEXT", options?: { encoding?: EncodingType }): void;
setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
getHMAC(format: "HEX", options?: { outputUpper?: boolean }): string;
getHMAC(format: "B64", options?: { b64Pad?: string }): string;
getHMAC(format: "BYTES"): string;
getHMAC(format: "UINT8ARRAY"): Uint8Array;
getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;

Usage Examples:

import jsSHA512 from "jssha/sha512";

// SHA-512 hashing
const sha512 = new jsSHA512("SHA-512", "TEXT", { encoding: "UTF8" });
sha512.update("Hello, World!");
const hash512 = sha512.getHash("HEX");

// SHA-384 hashing
const sha384 = new jsSHA512("SHA-384", "TEXT");
sha384.update("Hello, World!");
const hash384 = sha384.getHash("HEX");

// SHA-512 with ArrayBuffer input
const sha512Buffer = new jsSHA512("SHA-512", "ARRAYBUFFER");
const buffer = new TextEncoder().encode("Hello").buffer;
sha512Buffer.update(buffer);
const bufferHash = sha512Buffer.getHash("UINT8ARRAY");

// SHA-384 HMAC with Uint8Array key
const keyArray = new TextEncoder().encode("secret-key");
const hmac384 = new jsSHA512("SHA-384", "TEXT", {
  hmacKey: { value: keyArray, format: "UINT8ARRAY" }
});
hmac384.update("Message for HMAC");
const hmacResult = hmac384.getHash("ARRAYBUFFER");

jsSHA3 - SHA3/SHAKE/cSHAKE/KMAC Implementation

Comprehensive class for all SHA-3 family algorithms including fixed-length SHA3 variants, variable-length SHAKE algorithms, customizable cSHAKE, and KMAC authentication.

/**
 * SHA3 fixed-length variants for TEXT input format
 * @param variant - SHA3 variant: "SHA3-224", "SHA3-256", "SHA3-384", "SHA3-512"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional configuration including encoding and HMAC key
 */
constructor(variant: "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);

/**
 * SHA3 fixed-length variants for binary input formats
 * @param variant - SHA3 variant: "SHA3-224", "SHA3-256", "SHA3-384", "SHA3-512"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional configuration including HMAC key and numRounds
 */
constructor(variant: "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);

/**
 * SHAKE variants for TEXT input format
 * @param variant - SHAKE variant: "SHAKE128" or "SHAKE256"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional configuration including encoding and numRounds
 */
constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);

/**
 * SHAKE variants for binary input formats
 * @param variant - SHAKE variant: "SHAKE128" or "SHAKE256"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional configuration including numRounds
 */
constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);

/**
 * cSHAKE variants for TEXT input format
 * @param variant - cSHAKE variant: "CSHAKE128" or "CSHAKE256"
 * @param inputFormat - Must be "TEXT"
 * @param options - Optional customization including funcName and customization
 */
constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);

/**
 * cSHAKE variants for binary input formats
 * @param variant - cSHAKE variant: "CSHAKE128" or "CSHAKE256"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Optional customization including funcName and customization
 */
constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);

/**
 * KMAC variants for TEXT input format
 * @param variant - KMAC variant: "KMAC128" or "KMAC256"
 * @param inputFormat - Must be "TEXT"
 * @param options - Required kmacKey and optional customization
 */
constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);

/**
 * KMAC variants for binary input formats
 * @param variant - KMAC variant: "KMAC128" or "KMAC256"
 * @param inputFormat - Binary format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
 * @param options - Required kmacKey and optional customization
 */
constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);

// Standard methods
update(input: string | ArrayBuffer | Uint8Array): this;
getHash(format: "HEX", options?: { outputUpper?: boolean; outputLen?: number; shakeLen?: number }): string;
getHash(format: "B64", options?: { b64Pad?: string; outputLen?: number; shakeLen?: number }): string;
getHash(format: "BYTES", options?: { outputLen?: number; shakeLen?: number }): string;
getHash(format: "UINT8ARRAY", options?: { outputLen?: number; shakeLen?: number }): Uint8Array;
getHash(format: "ARRAYBUFFER", options?: { outputLen?: number; shakeLen?: number }): ArrayBuffer;
setHMACKey(key: string, inputFormat: "TEXT", options?: { encoding?: EncodingType }): void;
setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
getHMAC(format: "HEX", options?: { outputUpper?: boolean }): string;
getHMAC(format: "B64", options?: { b64Pad?: string }): string;
getHMAC(format: "BYTES"): string;
getHMAC(format: "UINT8ARRAY"): Uint8Array;
getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;

// SHA3-specific protected methods (not typically used directly)
protected _initializeCSHAKE(options?: CSHAKEOptionsNoEncodingType, funcNameOverride?: packedValue): number;
protected _initializeKMAC(options: KMACOptionsNoEncodingType): void;
protected _getKMAC(options: { outputLen: number }): number[];

Usage Examples:

import jsSHA3 from "jssha/sha3";

// SHA3-256 hashing
const sha3_256 = new jsSHA3("SHA3-256", "TEXT", { encoding: "UTF8" });
sha3_256.update("Hello, SHA3!");
const sha3Hash = sha3_256.getHash("HEX");

// SHAKE128 with variable output
const shake128 = new jsSHA3("SHAKE128", "TEXT");
shake128.update("Hello, SHAKE!");
const shake256bit = shake128.getHash("HEX", { outputLen: 256 });
const shake512bit = shake128.getHash("HEX", { outputLen: 512 });

// cSHAKE256 with customization
const cshake = new jsSHA3("CSHAKE256", "TEXT", {
  customization: { value: "MyApp", format: "TEXT" },
  funcName: { value: "KeyGen", format: "TEXT" }
});
cshake.update("Key material");
const customHash = cshake.getHash("B64", { outputLen: 384 });

// KMAC128 for authentication
const kmac = new jsSHA3("KMAC128", "TEXT", {
  kmacKey: { value: "authentication-key", format: "TEXT" },
  customization: { value: "APIAuth", format: "TEXT" }
});
kmac.update("Message to authenticate");
const mac = kmac.getHash("HEX", { outputLen: 256 });

// SHA3-512 with hex input
const sha3Hex = new jsSHA3("SHA3-512", "HEX");
sha3Hex.update("deadbeefcafebabe");
const hexResult = sha3Hex.getHash("UINT8ARRAY");

Bundle Size Optimization

Using variant-specific classes can significantly reduce bundle size when only specific algorithms are needed:

// Large bundle - includes all SHA variants
import jsSHA from "jssha"; // ~23KB (full library)

// Smaller bundles - only specific variants
import jsSHA1 from "jssha/sha1";     // ~10KB (SHA-1 only)
import jsSHA256 from "jssha/sha256"; // ~11KB (SHA-224/256 only)
import jsSHA512 from "jssha/sha512"; // ~14KB (SHA-384/512 only)
import jsSHA3 from "jssha/sha3";     // ~13KB (SHA3/SHAKE/cSHAKE/KMAC only)

// Example: Application only needs SHA-256
import jsSHA256 from "jssha/sha256";

const hash = new jsSHA256("SHA-256", "TEXT");
hash.update("Only need SHA-256");
const result = hash.getHash("HEX");

Module Loading Patterns

ES Modules (Recommended)

// Modern ES module imports
import jsSHA1 from "jssha/sha1";
import jsSHA256 from "jssha/sha256";
import jsSHA512 from "jssha/sha512";
import jsSHA3 from "jssha/sha3";

// Use specific variant
const sha256 = new jsSHA256("SHA-256", "TEXT");

CommonJS (Node.js)

// CommonJS imports (Node.js v13+ with subpath exports)
const jsSHA1 = require("jssha/sha1");
const jsSHA256 = require("jssha/sha256");
const jsSHA512 = require("jssha/sha512");
const jsSHA3 = require("jssha/sha3");

// For older Node.js versions without subpath exports
const jsSHA1 = require("jssha/dist/sha1");
const jsSHA256 = require("jssha/dist/sha256");
const jsSHA512 = require("jssha/dist/sha512");
const jsSHA3 = require("jssha/dist/sha3");

Browser Script Tags

<!-- Individual variant files -->
<script src="path/to/sha1.js"></script>
<script src="path/to/sha256.js"></script>
<script src="path/to/sha512.js"></script>
<script src="path/to/sha3.js"></script>

<script>
  // Classes are available globally
  const sha256 = new jsSHA("SHA-256", "TEXT");
</script>

Compatibility and Interoperability

Type Compatibility

All variant-specific classes implement the same core interface as the universal jsSHA class:

// These are functionally equivalent for SHA-256
import jsSHA from "jssha";
import jsSHA256 from "jssha/sha256";

const universal = new jsSHA("SHA-256", "TEXT");
const specific = new jsSHA256("SHA-256", "TEXT");

// Both produce identical results
universal.update("test");
specific.update("test");

console.log(universal.getHash("HEX") === specific.getHash("HEX")); // true

Performance Characteristics

Bundle Size: Variant-specific classes have smaller bundle sizes
Runtime Performance: Similar performance to universal class for the same algorithms
Memory Usage: Slightly lower memory footprint due to unused code elimination
Tree Shaking: Better tree-shaking support in modern bundlers

Use Case Recommendations

When to Use Universal jsSHA Class

Need multiple SHA variants in the same application
Algorithm choice is determined at runtime
Bundle size is not a primary concern
Want maximum flexibility and feature coverage

When to Use Variant-Specific Classes

Only need specific SHA algorithms
Bundle size optimization is important
Building lightweight applications or libraries
Know exact algorithm requirements at build time

Hybrid Approach

// Use specific classes for known requirements
import jsSHA256 from "jssha/sha256";
import jsSHA3 from "jssha/sha3";

// SHA-256 for file hashing
function hashFile(content: string): string {
  const sha256 = new jsSHA256("SHA-256", "TEXT");
  sha256.update(content);
  return sha256.getHash("HEX");
}

// SHAKE256 for key derivation
function deriveKey(seed: string, length: number): Uint8Array {
  const shake = new jsSHA3("SHAKE256", "TEXT");
  shake.update(seed);
  return shake.getHash("UINT8ARRAY", { outputLen: length * 8 });
}

Error Handling

Variant-specific classes have the same error handling behavior as the universal class:

import jsSHA256 from "jssha/sha256";

// This will throw an error - SHA-1 not supported by jsSHA256
try {
  const invalid = new jsSHA256("SHA-1", "TEXT"); // Error!
} catch (error) {
  console.error("jsSHA256 only supports SHA-224 and SHA-256");
}

// This works correctly
const valid = new jsSHA256("SHA-256", "TEXT");
valid.update("Hello");
const result = valid.getHash("HEX");