Registry / auth-security / iron-webcrypto

iron-webcrypto

library2.0.0jsnpmunverified

iron-webcrypto is a JavaScript/TypeScript library providing a WebCrypto API-based implementation of `@hapi/iron`. It enables sealing (encrypting and signing) and unsealing JSON-like data using symmetric key encryption with built-in message integrity verification, producing compact, URL-safe string tokens. The current stable version is 2.0.0, which notably dropped support for Node.js versions older than 20 and transitioned to an ESM-only module. It differentiates itself by relying solely on standard WebCrypto APIs, making it highly portable across modern JavaScript runtimes like Node.js v20+, Deno, Bun, and Cloudflare Workers, without depending on Node.js-specific `node:crypto` or `node:buffer` modules. The library's API is designed to be compatible with `@hapi/iron`, facilitating migrations or consistent usage patterns across projects. It ships with full TypeScript type definitions and is primarily intended for server-side or worker environments due to security implications of client-side secret exposure, which could expose encryption secrets.

auth-security serialization

npm install iron-webcrypto

github ↗package ↗

INSTALL

IMPORT

SIG · IRON-WEBCRYPTO

iron-webcrypto

auth-securityjavascriptv2.0.0

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.

Iron

✓ import * as Iron from 'iron-webcrypto'

✗ const Iron = require('iron-webcrypto')

iron-webcrypto is an ESM-only package since v2; CommonJS `require` is not supported. For Deno/JSR, use `import * as Iron from '@brc-dd/iron'`.

seal, unseal

✓ import { seal, unseal } from 'iron-webcrypto'

✗ import { seal } from 'iron-webcrypto/lib/seal'

All primary functions are named exports from the top-level package. Avoid importing from internal paths.

defaults

✓ import { defaults } from 'iron-webcrypto'

Commonly used default options for sealing and unsealing.

Demonstrates sealing a JSON object into a tamper-evident, encrypted token and then unsealing it, highlighting the use of a secure password and default options.

import * as Iron from 'iron-webcrypto' async function runCryptoExample() { // It's crucial to use a strong, randomly generated secret stored securely // in environment variables or a secrets manager. NEVER hardcode in production. const password = process.env.IRON_SECRET_KEY ?? 'a_long_random_secret_please_change_me_32_chars_min' if (password.length < 32) { console.error('Warning: Password must be at least 32 characters long for security.') return } const payload = { userId: 123, scope: ['user'], issuedAt: Date.now() } try { const sealed = await Iron.seal(payload, password, Iron.defaults) console.log('Sealed token:', sealed) // Simulate receiving the token later or in another service const unsealed = await Iron.unseal(sealed, password, Iron.defaults) console.log('Unsealed payload:', unsealed) // Example with TTL (Time To Live) const optionsWithTTL = { ...Iron.defaults, ttl: 5000 } // 5 seconds expiry const sealedWithTTL = await Iron.seal(payload, password, optionsWithTTL) console.log('Sealed token with TTL:', sealedWithTTL) // Wait for expiry (optional, for demonstration) // await new Promise(resolve => setTimeout(resolve, 6000)) // try { // await Iron.unseal(sealedWithTTL, password, optionsWithTTL) // } catch (e) { // console.log('Expected expiry error:', e.message) // } } catch (error) { console.error('Cryptography operation failed:', error) } } runCryptoExample()

Debug

Known issues

breakingVersion 2.0.0 of `iron-webcrypto` drops support for Node.js versions older than v20. Running on unsupported versions may lead to runtime errors or unexpected behavior due to missing WebCrypto APIs.

fix

Upgrade your Node.js environment to version 20 or higher to ensure compatibility.

affects: >=2.0.0

breakingInternal utility functions for base64/buffer operations, which were not part of the public API, have been removed in v2.0.0. If you were using these, migrate to dedicated libraries like `uint8array-extras`.

fix

Replace usage of internal utility functions with purpose-built libraries like `uint8array-extras` for base64/buffer operations.

affects: >=2.0.0

gotchaWhile `iron-webcrypto` technically functions in a browser environment due to its WebCrypto reliance, it is not recommended for client-side use. Exposing encryption secrets (passwords) to the client poses significant security risks.

fix

Use `iron-webcrypto` primarily in server-side, worker, or other secure backend environments where encryption secrets can be properly managed and protected.

affects: >=1.0.0

gotchaEncryption secrets (passwords) should never be hardcoded in application code. They must be stored securely, ideally in environment variables, a secrets manager, or a secure configuration system.

fix

Refactor your application to load encryption secrets from environment variables (e.g., `process.env.IRON_SECRET_KEY`) or a secure secrets management service.

affects: >=1.0.0

gotchaThe default `minPasswordLength` is 32 characters. Using passwords shorter than this may be insecure and could result in runtime errors or weakened cryptography.

fix

Ensure that the password provided for sealing and unsealing is at least 32 characters long. Adjust `minPasswordLength` in `SealOptions` if absolutely necessary for specific use cases (though not recommended).

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax with an ESM-only package.

fix

Change `const Iron = require('iron-webcrypto')` to `import * as Iron from 'iron-webcrypto'` and ensure your project is configured for ESM.

TypeError: crypto.subtle is undefined

Running `iron-webcrypto` in an environment that lacks the WebCrypto API, most commonly an older Node.js version (<v20).

fix

Upgrade your Node.js version to v20 or higher. Alternatively, ensure your environment provides a `crypto.subtle` implementation.

RangeError: Password must be at least 32 characters long.

The provided password for `seal` or `unseal` is shorter than the minimum required length (default 32 characters).

fix

Provide a password that meets or exceeds the minimum length configured in `SealOptions.encryption.minPasswordlength` (default: 32 characters). Always use strong, securely generated passwords.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/brc-dd/iron-webcrypto ↗

packagehttps://www.npmjs.com/package/iron-webcrypto ↗