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:

1npm add iron-webcrypto
2yarn add iron-webcrypto
3pnpm add iron-webcrypto
4bun add iron-webcrypto

You can then import it using:

1import * as Iron from 'iron-webcrypto'

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

1npx jsr add @brc-dd/iron
2yarn dlx jsr add @brc-dd/iron
3pnpm dlx jsr add @brc-dd/iron
4bunx jsr add @brc-dd/iron
5deno add @brc-dd/iron

You can then import it using:

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

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

1import * as Iron from 'https://deno.land/x/iron@v1.2.1/mod.ts'
2import * as Iron from 'https://esm.sh/iron-webcrypto@1.2.1'
3import * as Iron from 'npm:iron-webcrypto@1.2.1'

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:

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

becomes:

1Iron.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

1@hapi/iron
2    Copyright (c) 2012-2022, Project contributors
3    Copyright (c) 2012-2020, Sideway Inc
4    All rights reserved.
5    https://cdn.jsdelivr.net/npm/@hapi/iron@7.0.1/LICENSE.md
6
7@smithy/util-base64
8    Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
9    https://cdn.jsdelivr.net/npm/@smithy/util-base64@3.0.0/LICENSE
10
11@smithy/util-utf8
12    Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
13    https://cdn.jsdelivr.net/npm/@smithy/util-utf8@3.0.0/LICENSE

Sponsors