SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
suaveplan/packages/security-stack/crypto/crypto-browser/README.md
admin 9b28db724f Initial Commit
2026-05-27 23:47:53 +01:00

15 KiB
Raw Permalink Blame History

@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.

Documentation tree

- [aes-kw](./src/aes-kw/aes-kw.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_- [aes-kw](./src/aes-kw/aes-kw.md) — _(no submodules)_- [availability](./src/availability/availability.md) — _(no submodules)_ - [availability](./src/availability/availability.md) — _(no submodules)_- [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_ - [ecdh-p384](./src/ecdh-p384/ecdh-p384.md) — _(no submodules)_- [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_ - [ecdsa-p384](./src/ecdsa-p384/ecdsa-p384.md) — _(no submodules)_- [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_ - [webcrypto-aead-engine](./src/engines/webcrypto-aead-engine/webcrypto-aead-engine.md) — _(no submodules)_- [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_ - [webcrypto-agree-engine](./src/engines/webcrypto-agree-engine/webcrypto-agree-engine.md) — _(no submodules)_- [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_ - [webcrypto-sign-engine](./src/engines/webcrypto-sign-engine/webcrypto-sign-engine.md) — _(no submodules)_- [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_ - [browser-crypto-error](./src/errors/browser-crypto-error/browser-crypto-error.md) — _(no submodules)_- [codes](./src/errors/codes/codes.md) — _(no submodules)_ - [codes](./src/errors/codes/codes.md) — _(no submodules)_- [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_ - [non-extractable-key](./src/non-extractable-key/non-extractable-key.md) — _(no submodules)_- [rsa](./src/rsa/rsa.md) — _(no submodules)_ - [rsa](./src/rsa/rsa.md) — _(no submodules)_

Modules

Module Description
availability isWebCryptoAvailable() + assertWebCryptoAvailable() runtime guard
webcrypto-aead-engine AeadEngine — AES-256-GCM via crypto.subtle
webcrypto-sign-engine SignEngine — Ed25519 and ECDSA-P256 via crypto.subtle
webcrypto-agree-engine AgreeEngine — X25519 and ECDH-P256 via crypto.subtle
rsa RSA-PSS / RSA-OAEP / RSASSA-PKCS1-v1_5
aes-kw AES Key Wrap (RFC 3394)
ecdsa-p384 ECDSA with P-384 / SHA-384
ecdh-p384 ECDH key agreement with P-384
non-extractable-key Non-extractable CryptoKey generation
errors/browser-crypto-error BrowserCryptoError structured error class

Quick Start

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:

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
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);
  }
}
Reference in New Issue View Git Blame Copy Permalink