unsecure

unsecure is a collection of runtime-agnostic cryptographically-secure utilities. (ba dum tss 🥁)

Usage

Install the package:

# ✨ Auto-detect (supports npm, yarn, pnpm, deno and bun)
npx nypm install unsecure

Import:

ESM (Node.js, Bun, Deno)

// Main functions
import { hash, secureGenerate, secureCompare } from "unsecure";
// Utility functions
import {
  hexEncode,
  hexDecode,
  secureShuffle,
  // ...
} from "unsecure/utils";

CDN (Deno, Bun and Browsers)

// Main functions
import { hash, secureGenerate, secureCompare } from "https://esm.sh/unsecure";
// Utility functions
import {
  hexEncode,
  hexDecode,
  secureShuffle,
  // ...
} from "https://esm.sh/unsecure/utils";

hash

Hashes input data using a specified cryptographic algorithm. It uses the Web Crypto API, so it works in any modern JavaScript runtime.

options:

• algorithm: SHA-256, SHA-384, SHA-512 (default SHA-256)
• returnAs: hex, base64, base64url, bytes (default hex)

import { hash } from "unsecure";

// Hash an input using the default SHA-256 and return as a hex string
const hashHex = await hash("hello world");
// 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'

// Hash an input using the default SHA-256 and return as a base64 string
const hashBase64 = await hash("hello world", { returnAs: "base64" });
// 'UhywQV8aBkKEVtnvTpSMAnCoBkQjJSU8t6imt+Q9qcc='

// Hash an input using the default SHA-256 and return as a base64 URL string
const hashBase64URL = await hash("hello world", { returnAs: "base64url" });
// 'UhywQV8aBkKEVtnvTpSMAnCoBkQjJSU8t6imt-Q9qcc'

// Hash and get raw bytes (Uint8Array)
const hashBytes = await hash("hello world", { returnAs: "bytes" });
// Uint8Array(32) [ 185, 77, 39, 185, 147, 77, ... ]

// Hash using SHA-512
const hash512 = await hash("hello world", { algorithm: "SHA-512" });
// '309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f...'

secureGenerate (or generateSecureToken)

Generates a cryptographically secure string. You can customize its length and character set (all enabled by default). If a string is passed it will be used as a set of allowed characters.

Internally it uses a buffer, which is constantly updated, to minimize Web Crypto API calls and greatly improve performance. This becomes useful when generating 128-512 characters long tokens.

import { secureGenerate } from "unsecure";

// Generate a default 16-character password
const password = secureGenerate();
// e.g. 'Zk(p4@L!v9{g~8sB'

// Generate 28-character password
const password = secureGenerate(28);
// e.g. '4~j&zgf-tO+PoMBVl}tK/}5$FgzF'

// Generate a 24-character token with no special characters
const token = secureGenerate({
  length: 24,
  specials: false,
});

// Generate a pin using only custom numbers
const pin = secureGenerate({
  length: 6,
  uppercase: false,
  lowercase: false,
  specials: false,
  numbers: "13579",
});

secureCompare

Compares two values (string or Uint8Array) in a timing-attack-safe manner. The first argument is always the reference value, which determines the time it takes for verification.

import { secureCompare } from "unsecure";

const secret = "my-super-secret-token";
const userInput = "my-super-secret-token";
// from user input

if (secureCompare(secret, userInput)) {
  console.log("Tokens match!");
} else {
  console.log("Tokens do not match!");
}

// Also works with Uint8Array and mixed types
const mac1 = new Uint8Array([1, 2, 3]);
const mac2 = new Uint8Array([1, 2, 3]);
secureCompare(mac1, mac2); // true
secureCompare(secret, mac2); // false

Utilities (unsecure/utils)

A collection of supplementary utilities for encoding, decoding, and random number generation.

Encoding

Includes hexEncode, hexDecode, base64Encode, base64Decode, base64UrlEncode, and base64UrlDecode.

import { hexEncode, hexDecode } from "unsecure/utils";

const hex = hexEncode("hello"); // "68656c6c6f"
const text = hexDecode(hex); // "hello"

Randomness

Includes createSecureRandomGenerator, secureRandomNumber and secureShuffle.

import {
  createSecureRandomGenerator,
  secureRandomNumber,
  secureShuffle,
} from "unsecure/utils";

// Creates a secure random number generator (more performant for subsequent calls)
const generator = createSecureRandomGenerator();
const n = generator.next(1000); // Get a secure random number between 0 and 999

// Get a secure random number between 0 and 99 (more memory-efficient for single use)
const n = secureRandomNumber(100);

// Securely shuffle an array in-place
const list = [1, 2, 3, 4, 5];
secureShuffle(list); // e.g. [ 3, 1, 5, 2, 4 ]

// Or spread the original to not mutate it
const shuffled = secureShuffle([...list]);

Development

local development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

Credits

Inspired by DeepSource Corp work.

License

Published under the MIT license. Made by community 💛

---

🤖 auto updated with automd