Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/brc-dd/iron-webcrypto
A cryptographic utility for sealing a JSON object using symmetric key encryption with message integrity verification.
https://github.com/brc-dd/iron-webcrypto
Last synced: 12 days ago
JSON representation
A cryptographic utility for sealing a JSON object using symmetric key encryption with message integrity verification.
- Host: GitHub
- URL: https://github.com/brc-dd/iron-webcrypto
- Owner: brc-dd
- License: mit
- Created: 2022-05-19T15:41:44.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-31T09:24:26.000Z (2 months ago)
- Last Synced: 2024-10-29T16:14:51.662Z (13 days ago)
- Language: TypeScript
- Homepage: https://jsdocs.io/package/iron-webcrypto
- Size: 538 KB
- Stars: 63
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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/[email protected]/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/[email protected]/mod.ts'
import * as Iron from 'https://esm.sh/[email protected]'
import * as Iron from 'npm:[email protected]'
```
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/[email protected]/LICENSE.md
@smithy/util-base64
Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
https://cdn.jsdelivr.net/npm/@smithy/[email protected]/LICENSE
@smithy/util-utf8
Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
https://cdn.jsdelivr.net/npm/@smithy/[email protected]/LICENSE
```
## Sponsors
