143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# iron-webcrypto
|
|
|
|
[](https://www.jsdocs.io/package/iron-webcrypto)
|
|
[](https://www.npmjs.com/package/iron-webcrypto)
|
|
[](https://www.npmjs.com/package/iron-webcrypto)
|
|
[](https://deno.land/x/iron@v1.2.1/mod.ts)
|
|
[](https://jsr.io/@brc-dd/iron)
|
|
|
|
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**](https://github.com/unjs/h3) and
|
|
> [**vvo/iron-session**](https://github.com/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:
|
|
|
|
```sh
|
|
npm add iron-webcrypto
|
|
yarn add iron-webcrypto
|
|
pnpm add iron-webcrypto
|
|
bun add iron-webcrypto
|
|
```
|
|
|
|
You can then import it using:
|
|
|
|
```ts
|
|
import * as Iron from 'iron-webcrypto'
|
|
```
|
|
|
|
If using JSR, run any of the following commands depending on your package
|
|
manager / runtime:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```ts
|
|
import * as Iron from '@brc-dd/iron'
|
|
```
|
|
|
|
On Deno, you can also use any of the following imports:
|
|
|
|
```ts
|
|
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](https://hapi.dev/module/iron/). There are certain
|
|
differences.
|
|
|
|
You need to pass a Web Crypto implementation as the first parameter to each
|
|
function. For example:
|
|
|
|
```ts
|
|
Iron.seal(obj, password, Iron.defaults)
|
|
```
|
|
|
|
becomes:
|
|
|
|
```ts
|
|
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`](https://github.com/unjs/uncrypto) for this too. Also, you might
|
|
need to polyfill this for older Node.js versions. I recommend using
|
|
[`@peculiar/webcrypto`](https://github.com/PeculiarVentures/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](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API):
|
|
|
|
> 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
|
|
|
|
```txt
|
|
@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
|
|
|
|
<p align="center">
|
|
<a href="https://cdn.jsdelivr.net/gh/brc-dd/static/sponsors.svg">
|
|
<img alt="brc-dd's sponsors" src='https://cdn.jsdelivr.net/gh/brc-dd/static/sponsors.svg'/>
|
|
</a>
|
|
</p>
|