uncrypto

library0.1.3jsnpmunverified

Uncrypto is a lightweight JavaScript library that provides a unified, cross-runtime API for cryptographic operations, abstracting the differences between the Web Crypto API in browsers and Node.js's native `crypto` module. Currently at version 0.1.3, it offers direct access to `SubtleCrypto` functionalities, `randomUUID`, and `getRandomValues` through a single import. The library leverages Node.js conditional exports to automatically adapt to the target environment (Node.js 15+ or modern browsers in secure contexts) without providing polyfills for older versions, thus maintaining a small footprint. Its primary differentiator is simplifying cryptographic development by eliminating environment-specific branching, allowing developers to write once and deploy across various JavaScript runtimes. The release cadence appears to be driven by feature enhancements and maintenance, reflecting its early-stage development and active development cycle.

http-networking auth-security

npm install uncrypto

github ↗package ↗

INSTALL

IMPORT

SIG · UNCRYPTO

uncrypto

http-networkingjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

subtle

✓ import { subtle } from 'uncrypto';

✗ const { subtle } = require('uncrypto'); // Incorrect in pure ESM projects

For ESM environments, use named imports. CommonJS `require` is supported but primarily for older Node.js projects. Since v0.1.0, both ESM and CJS are explicitly supported via conditional exports.

randomUUID

✓ import { randomUUID } from 'uncrypto';

✗ import randomUUID from 'uncrypto'; // Not a default export

All public APIs are named exports, there is no default export.

getRandomValues

✓ import { getRandomValues } from 'uncrypto';

✗ const getRandomValues = require('uncrypto').getRandomValues;

This function is available in both browser and Node.js environments through the unified API.

Demonstrates importing and using `subtle`, `randomUUID`, and `getRandomValues` to generate a UUID, secure random numbers, and perform a basic AES-GCM encryption operation.

import { subtle, randomUUID, getRandomValues } from 'uncrypto'; async function generateAndEncrypt() { // Generate a random UUID const uuid = randomUUID(); console.log('Generated UUID:', uuid); // Generate cryptographically strong random values const randomBuffer = new Uint8Array(16); getRandomValues(randomBuffer); console.log('Generated random values:', randomBuffer); // Perform a simple AES-GCM encryption using subtle crypto const algorithm = { name: 'AES-GCM', length: 256 }; const key = await subtle.generateKey(algorithm, true, ['encrypt', 'decrypt']); const iv = getRandomValues(new Uint8Array(12)); const encoder = new TextEncoder(); const data = encoder.encode('Hello, Uncrypto!'); const encryptedData = await subtle.encrypt( { name: 'AES-GCM', iv: iv }, key, data ); console.log('Encrypted data:', new Uint8Array(encryptedData)); } generateAndEncrypt().catch(console.error);

Debug

Known issues

breakinguncrypto requires Node.js version 15 or higher. It does not provide polyfills for older Node.js environments, and attempts to use it on unsupported versions will result in runtime errors related to missing crypto APIs.

fix

Upgrade your Node.js environment to version 15 or newer. For projects that must support older Node.js, consider polyfilling `globalThis.crypto` manually or using a different library.

affects: <1.0.0

gotchaWhen used in browser environments, `uncrypto` relies on the Web Crypto API, which mandates a secure context (HTTPS or localhost). Operations will fail in insecure HTTP contexts.

fix

Ensure your web application is served over HTTPS or accessed via `localhost` during development to enable the Web Crypto API.

affects: >=0.1.0

gotchaThis library does not provide its own polyfills for `globalThis.crypto`. If deploying to highly specialized or older JavaScript runtimes without a native `crypto` implementation, you must provide your own polyfill.

fix

For unsupported runtimes, manually polyfill `globalThis.crypto` and `globalThis.crypto.subtle` according to the Web Crypto API specification or use a compatible polyfill library.

affects: >=0.1.0

gotchaAs of version 0.1.3, uncrypto is in an early development stage. While the API aims to be stable, minor versions may introduce breaking changes or significant modifications without a major version bump, as is common with pre-1.0 software.

fix

Pin to exact versions (`"uncrypto": "0.1.3"`) or use caret ranges (`"^0.1.3"`) with caution and regularly review release notes for updates.

affects: <1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax within a JavaScript file that is being treated as an ES module (e.g., `"type": "module"` in `package.json`).

fix

Change your import statements to use ESM syntax: `import { subtle } from 'uncrypto';` instead of `const { subtle } = require('uncrypto');`.

Uncaught ReferenceError: crypto is not defined

The global `crypto` object is missing in the current JavaScript runtime environment. This can occur in unsupported Node.js versions (below 15), older browsers, or custom environments without a `crypto` implementation.

fix

Ensure you are running in Node.js 15+ or a modern browser in a secure context. For other runtimes, you must manually polyfill `globalThis.crypto`.

DOMException: The operation is not supported in this context.

This error typically originates from the Web Crypto API in browsers when cryptographic operations are attempted in an insecure context (e.g., HTTP).

fix

Serve your web application over HTTPS or access it via `localhost` during development to enable the secure context required by the Web Crypto API.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/unjs/uncrypto ↗

packagehttps://www.npmjs.com/package/uncrypto ↗