iron-webcrypto

This module is a replacement for @hapi/iron, written using standard APIs like Web Crypto and Uint8Array, which make this compatible with a variety of runtimes like Node.js, Deno, Bun, browsers, workers, and edge environments. Refer @hapi/iron's docs on what it does and how it works.

Check out unjs/h3 and vvo/iron-session to see this module in use!

Installation

For Node.js and Bun, run any of the following commands depending on your package manager / runtime:

npm add iron-webcrypto
yarn add iron-webcrypto
pnpm add iron-webcrypto
bun add iron-webcrypto

You can then import it using:

import * as Iron from 'iron-webcrypto'

If using JSR, run any of the following commands depending on your package manager / runtime:

npx jsr add @brc-dd/iron
yarn dlx jsr add @brc-dd/iron
pnpm dlx jsr add @brc-dd/iron
bunx jsr add @brc-dd/iron
deno add @brc-dd/iron

You can then import it using:

import * as Iron from '@brc-dd/iron'

On Deno, you can also any of the following imports:

import * as Iron from 'https://deno.land/x/iron@v1.1.0/mod.ts'
import * as Iron from 'https://esm.sh/iron-webcrypto@1.1.0'
import * as Iron from 'npm:iron-webcrypto@1.1.0'

Don't use this module directly in the browser. While it will work, it's not recommended to use it in client-side code because of the security implications.

Usage

Refer @hapi/iron's docs. There are certain differences.

You need to pass a Web Crypto implementation as the first parameter to each function. For example:

Iron.seal(obj, password, Iron.defaults)

becomes:

Iron.seal(_crypto, obj, password, Iron.defaults)

where _crypto is your Web Crypto implementation. Generally, this will be available in your context. For example, globalThis.crypto in browsers, workers, edge runtimes, Deno, Bun, and Node.js v19+; require('crypto').webcrypto in Node.js v15+. You can directly use uncrypto for this too. Also, you might need to polyfill this for older Node.js versions. I recommend using @peculiar/webcrypto for that.

There are certain other differences because of the underlying implementation using standard APIs instead of Node.js-specific ones like node:crypto and node:buffer. There might also be differences in certain error messages because of this.

Security Considerations

Users are responsible for implementing iron-webcrypto in a secure manner and ensuring the security of their cryptographic keys. I DO NOT guarantee the security of this module. So far, no security vulnerabilities have been reported, but I am no cryptography expert. Quoting MDN:

The Web Crypto API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.

Even assuming you use the basic cryptographic functions correctly, secure key management and overall security system design are extremely hard to get right, and are generally the domain of specialist security experts.

Errors in security system design and implementation can make the security of the system completely ineffective.

As a request, it would be great if someone with expertise in this field could thoroughly review the code.

Credits

@hapi/iron
    Copyright (c) 2012-2022, Project contributors
    Copyright (c) 2012-2020, Sideway Inc
    All rights reserved.
    https://cdn.jsdelivr.net/npm/@hapi/iron@7.0.1/LICENSE.md

@smithy/util-base64
    Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
    https://cdn.jsdelivr.net/npm/@smithy/util-base64@2.2.0/LICENSE

@smithy/util-utf8
    Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
    https://cdn.jsdelivr.net/npm/@smithy/util-utf8@2.2.0/LICENSE

Sponsors