@jscrypto/core

Core registry, component contracts, transform helpers, byte helpers, and shared errors for @jscrypto packages.

Install

npm install @jscrypto/core

Usage

@jscrypto/core provides the framework contracts and registry. It does not ship concrete ciphers or modes by itself. Install component packages for actual algorithms:

npm install @jscrypto/core @jscrypto/ciphers @jscrypto/modes @jscrypto/paddings

import { createRegistry, randomBytes } from '@jscrypto/core';
import { aes } from '@jscrypto/ciphers/aes';
import { cbc } from '@jscrypto/modes/cbc';
import { pkcs7 } from '@jscrypto/paddings/pkcs7';

const registry = createRegistry()
  .use(aes)
  .use(cbc)
  .use(pkcs7);

const key = randomBytes(32);
const iv = randomBytes(16);
const cipher = registry.createCipher({
  cipher: 'AES',
  mode: 'CBC',
  padding: 'Pkcs7',
  key,
});

const ciphertext = cipher.encrypt(plaintext, { iv });

Use createCipher for traditional cipher pipelines (cipher + optional mode + padding). Use createAead for authenticated encryption algorithms selected by full algorithm name:

import { aesPreset } from '@jscrypto/ciphers/aes';
import { gcmPreset } from '@jscrypto/modes/gcm';

const registry = createRegistry()
  .use(aesPreset)
  .use(gcmPreset);
const aead = registry.createAead({
  algorithm: 'AES-GCM',
  key,
});

const sealed = aead.seal(plaintext, { nonce, aad });
const opened = aead.open(sealed, { nonce, aad });

const sealer = aead.createSealer({ nonce, aad });
const chunk = sealer.process(plaintextChunk);
const finalChunkWithTag = sealer.finalize();

AEAD has no padding. nonce must be unique for a given key. aad is authenticated but not encrypted. seal() appends the authentication tag; open() accepts that sealed byte string or a detached tag. createSealer() and createOpener() expose primitive transforms; safe openers may withhold plaintext until finalize() verifies the authentication tag.

Per-operation options are passed to facade methods rather than being fixed only at facade creation time. Core forwards mode-specific options without naming them; modes such as GCM may define options like nonce, aad, tag, or tagLength.

What It Provides

• createRegistry: component registry with cipher facade, AEAD facade, and derived-key facade creation.
• randomBytes(length): caller-owned random byte helper.
• Component contracts: cipher, mode, padding, KDF, format, hash, AEAD, and preset types.
• Transform contract: process(input) plus finalize(input?) for streaming ciphers, modes, and AEAD primitives.
• AEAD contract: one-shot seal / open plus createSealer / createOpener.
• Byte helpers: concatBytes, equalBytes, xorBytes, and byte assertions.
• Block helpers: block-size, IV, and padding assertions.
• Errors: CryptoError, DuplicateComponentError, and MissingComponentError.

@jscrypto/core does not include concrete cryptographic algorithms. Use @jscrypto/suite, component packages, or custom components for actual ciphers, modes, paddings, KDFs, hashes, and formats.