@peculiar/webcrypto

A comprehensive WebCrypto polyfill for Node.js that implements the standard Web Cryptography API using native Node.js crypto capabilities. This library provides full compatibility with browser WebCrypto while offering extensive algorithm support including advanced cryptographic operations not typically available in browsers.

Package Information

• Package Name: @peculiar/webcrypto
• Package Type: npm
• Language: TypeScript
• Installation: npm install @peculiar/webcrypto

Core Imports

import { Crypto } from "@peculiar/webcrypto";

For CommonJS:

const { Crypto } = require("@peculiar/webcrypto");

Basic Usage

import { Crypto } from "@peculiar/webcrypto";

const crypto = new Crypto();

// Generate a key pair
const keyPair = await crypto.subtle.generateKey(
  {
    name: "RSA-PSS",
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["sign", "verify"]
);

// Sign data
const data = new TextEncoder().encode("Hello, World!");
const signature = await crypto.subtle.sign(
  {
    name: "RSA-PSS",
    saltLength: 32,
  },
  keyPair.privateKey,
  data
);

// Generate random values
const randomBytes = new Uint8Array(32);
crypto.getRandomValues(randomBytes);

// Generate additional random values
const moreRandomBytes = new Uint8Array(16);
crypto.getRandomValues(moreRandomBytes);

Architecture

@peculiar/webcrypto is built on several key components:

• Crypto Class: Main entry point implementing the global Crypto interface with subtle property and utility methods
• SubtleCrypto Implementation: Comprehensive cryptographic operations using algorithm-specific providers
• Algorithm Providers: Specialized classes for each cryptographic algorithm (AES, RSA, ECDSA, etc.)
• Key Classes: Type-safe representations of cryptographic keys with proper serialization support
• Platform Integration: Conditional algorithm availability based on Node.js version and crypto capabilities

Capabilities

Core Cryptographic Interface

Main Crypto class providing WebCrypto API compatibility with random value generation and UUID creation.

class Crypto implements globalThis.Crypto {
  public subtle: SubtleCrypto;
  getRandomValues<T extends ArrayBufferView | null>(array: T): T;
  randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
}

Core Interface

Symmetric Encryption

AES encryption in multiple modes (CBC, CTR, GCM, ECB) with key wrapping capabilities, plus legacy DES support.

// AES key generation
interface AesKeyGenParams extends Algorithm {
  name: "AES-CBC" | "AES-CTR" | "AES-GCM" | "AES-ECB" | "AES-KW" | "AES-CMAC";
  length: 128 | 192 | 256;
}

// AES encryption parameters
interface AesGcmParams extends Algorithm {
  name: "AES-GCM";
  iv: BufferSource;
  additionalData?: BufferSource;
  tagLength?: 8 | 32 | 64 | 96 | 104 | 112 | 120 | 128;
}

Symmetric Encryption

Asymmetric Cryptography

RSA operations (signatures, encryption, key wrapping) and Elliptic Curve cryptography (ECDSA, ECDH) with extensive curve support.

// RSA key generation
interface RsaHashedKeyGenParams extends RsaKeyGenParams {
  name: "RSA-PSS" | "RSASSA-PKCS1-v1_5" | "RSA-OAEP";
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
}

// ECDSA key generation  
interface EcKeyGenParams extends Algorithm {
  name: "ECDSA" | "ECDH";
  namedCurve: "P-256" | "P-384" | "P-521" | "K-256" | string;
}

Asymmetric Cryptography

Modern Cryptography

EdDSA signatures and Curve25519 key agreement for next-generation cryptographic applications (Node.js ≥14).

// EdDSA key generation
interface EdDsaKeyGenParams extends Algorithm {
  name: "EdDSA";
  namedCurve: "Ed25519" | "Ed448";
}

// ECDH-ES key generation
interface EcdhEsKeyGenParams extends Algorithm {
  name: "ECDH-ES";
  namedCurve: "X25519" | "X448";
}

Modern Cryptography

Hash Functions

SHA family hash functions including SHA-3 variants and SHAKE extendable-output functions.

// Hash algorithms
type HashAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512" | 
                    "SHA3-256" | "SHA3-384" | "SHA3-512" | 
                    "shake128" | "shake256";

// SHAKE parameters
interface ShakeParams extends Algorithm {
  name: "shake128" | "shake256";
  length: number;
}

Hash Functions

Key Derivation

PBKDF2 and HKDF key derivation functions with HMAC support for secure key management.

// PBKDF2 parameters
interface Pbkdf2Params extends Algorithm {
  name: "PBKDF2";
  salt: BufferSource;
  iterations: number;
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
}

// HKDF parameters
interface HkdfParams extends Algorithm {
  name: "HKDF";
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
  salt: BufferSource;
  info: BufferSource;
}

Key Derivation

Supported Algorithms

Symmetric Algorithms

• AES: CBC, CTR, GCM, ECB, KW (Key Wrap), CMAC
• DES: CBC (conditional), 3DES-EDE-CBC

Asymmetric Algorithms

• RSA: RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, RSAES-PKCS1-v1_5
• ECDSA: P-256, P-384, P-521, K-256, Brainpool curves
• ECDH: P-256, P-384, P-521, K-256, Brainpool curves
• EdDSA: Ed25519, Ed448 (Node.js ≥14)
• ECDH-ES: X25519, X448 (Node.js ≥14)

Hash Functions

• SHA: SHA-1, SHA-256, SHA-384, SHA-512
• SHA-3: SHA3-256, SHA3-384, SHA3-512 (conditional)
• SHAKE: SHAKE128, SHAKE256 (Node.js ≥12)

Key Derivation

• PBKDF2: With SHA-1, SHA-256, SHA-384, SHA-512
• HKDF: With SHA-1, SHA-256, SHA-384, SHA-512
• HMAC: With SHA-1, SHA-256, SHA-384, SHA-512

Supported Elliptic Curves

• Standard: P-256, P-384, P-521, K-256
• Brainpool: brainpoolP160r1, brainpoolP160t1, brainpoolP192r1, brainpoolP192t1, brainpoolP224r1, brainpoolP224t1, brainpoolP256r1, brainpoolP256t1, brainpoolP320r1, brainpoolP320t1, brainpoolP384r1, brainpoolP384t1, brainpoolP512r1, brainpoolP512t1
• EdDSA: Ed25519, Ed448
• ECDH-ES: X25519, X448

Platform Requirements

• Node.js: ≥10.12.0
• SHAKE functions: Node.js ≥12
• EdDSA/Curve25519: Node.js ≥14
• SHA-3 functions: Platform-dependent crypto support