90 lines
15 KiB
Markdown
90 lines
15 KiB
Markdown
# @suaveplan/crypto-browser - WebCrypto-backed engine implementations for @suaveplan/crypto — AES-256-GCM, Ed25519, ECDSA-P256/P384, X25519, ECDH, RSA, AES-KW, and non-extractable key support via crypto.subtle.
|
|
|
|
## Summary
|
|
|
|
WebCrypto-backed engine implementations for `@suaveplan/crypto` — AES-256-GCM, Ed25519, ECDSA-P256/P384, X25519, ECDH-P256/P384, RSA, AES-KW, and non-extractable key support via `crypto.subtle`. Zero third-party cryptography dependencies.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — <!-- begin:auto-docs --> _(no submodules)_- [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_ - [availability](./src/availability/availability.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ - [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_ - [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ - [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ - [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ - [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_ - [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_ - [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — <!-- begin:auto-docs --> _(no submodules)_- [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rsa](./src/rsa/rsa.md) — <!-- begin:auto-docs --> _(no submodules)_
|
|
## Modules
|
|
|
|
| Module | Description |
|
|
|--------|-------------|
|
|
| [availability](src/availability/availability.md) | `isWebCryptoAvailable()` + `assertWebCryptoAvailable()` runtime guard |
|
|
| [webcrypto-aead-engine](src/engines/webcrypto-aead-engine.md) | `AeadEngine` — AES-256-GCM via `crypto.subtle` |
|
|
| [webcrypto-sign-engine](src/engines/webcrypto-sign-engine.md) | `SignEngine` — Ed25519 and ECDSA-P256 via `crypto.subtle` |
|
|
| [webcrypto-agree-engine](src/engines/webcrypto-agree-engine.md) | `AgreeEngine` — X25519 and ECDH-P256 via `crypto.subtle` |
|
|
| [rsa](src/rsa/rsa.md) | RSA-PSS / RSA-OAEP / RSASSA-PKCS1-v1_5 |
|
|
| [aes-kw](src/aes-kw/aes-kw.md) | AES Key Wrap (RFC 3394) |
|
|
| [ecdsa-p384](src/ecdsa-p384/ecdsa-p384.md) | ECDSA with P-384 / SHA-384 |
|
|
| [ecdh-p384](src/ecdh-p384/ecdh-p384.md) | ECDH key agreement with P-384 |
|
|
| [non-extractable-key](src/non-extractable-key/non-extractable-key.md) | Non-extractable `CryptoKey` generation |
|
|
| [errors/browser-crypto-error](src/errors/browser-crypto-error.md) | `BrowserCryptoError` structured error class |
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
import { webCryptoAeadEngine, isWebCryptoAvailable } from "@suaveplan/crypto-browser";
|
|
|
|
if (!isWebCryptoAvailable()) throw new Error("WebCrypto not available");
|
|
|
|
const key = crypto.getRandomValues(new Uint8Array(32));
|
|
const nonce = crypto.getRandomValues(new Uint8Array(12));
|
|
const ct = await (webCryptoAeadEngine.encrypt(key, new TextEncoder().encode("hello"), nonce) as unknown as Promise<Uint8Array>);
|
|
```
|
|
|
|
## Engine Plug-in
|
|
|
|
These engines implement interfaces from `@suaveplan/crypto/engines` and can be passed directly to `@suaveplan/crypto` facade functions:
|
|
|
|
```ts
|
|
import { encrypt, decrypt } from "@suaveplan/crypto/aead";
|
|
import { webCryptoAeadEngine } from "@suaveplan/crypto-browser/engines/webcrypto-aead-engine";
|
|
|
|
const ciphertext = await encrypt(key, plaintext, nonce, { engine: webCryptoAeadEngine });
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All operations throw `BrowserCryptoError` with stable codes:
|
|
|
|
- `BROWSER_CRYPTO.NOT_AVAILABLE` — `crypto.subtle` is absent
|
|
- `BROWSER_CRYPTO.KEY.GENERATION_FAILED` — key generation failed
|
|
- `BROWSER_CRYPTO.OPERATION.FAILED` — encrypt/decrypt/sign/verify/agree failed
|
|
|
|
```ts
|
|
import { BrowserCryptoError } from "@suaveplan/crypto-browser/errors";
|
|
|
|
try {
|
|
await rsa.decrypt(privateKey, ciphertext);
|
|
} catch (err) {
|
|
if (err instanceof BrowserCryptoError) {
|
|
console.error(err.code, err.cause);
|
|
}
|
|
}
|
|
```
|