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 use any of the following imports:

import * as Iron from 'https://deno.land/x/iron@v1.2.1/mod.ts'
import * as Iron from 'https://esm.sh/iron-webcrypto@1.2.1'
import * 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:

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.3.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.3.0/LICENSE

Sponsors