@agnostack/verifyd

Cryptographic verification and encryption library for agnoStack platform integrations. Provides ECDH key exchange, HMAC verification, AES-GCM encryption/decryption, and related utilities.

Installation

yarn add @agnostack/verifyd
# or
npm install @agnostack/verifyd

Export Paths

| Path | Format | Use Case | |------|--------|----------| | @agnostack/verifyd | CJS | Default — works everywhere (Node.js, bundlers) | | @agnostack/verifyd/esm | ESM | Tree-shakeable — for modern bundlers (Vite, esbuild, Webpack 5+) | | @agnostack/verifyd/react | CJS | React hooks (useVerification) | | @agnostack/verifyd/react/esm | ESM | Tree-shakeable React hooks | | @agnostack/verifyd/external | UMD | Script tag / CDN usage |

Tree-Shaking (ESM)

The /esm subpaths enable bundlers to eliminate unused code. For example, importing only { WebCrypto } from @agnostack/verifyd/esm produces a ~62% smaller bundle compared to the CJS export (unused utilities like display.js are fully eliminated).

// CJS (no tree-shaking)
import { WebCrypto } from '@agnostack/verifyd'

// ESM (tree-shakeable)
import { WebCrypto } from '@agnostack/verifyd/esm'

Web Crypto Resolution

WebCrypto uses a layered resolution strategy to find a Web Crypto API implementation:

1. Constructor-injected — if you pass { crypto } to new WebCrypto({ crypto }), that's used directly
2. globalThis.crypto.subtle — native Web Crypto, available in all modern browsers and Node.js 18+
3. isomorphic-webcrypto polyfill — fallback for older Node.js environments (see below)
4. Node.js crypto module — last resort fallback

Each stage exits early on success — later fallbacks are only reached if all earlier checks fail.

isomorphic-webcrypto (Optional Peer Dependency)

isomorphic-webcrypto is an optional peer dependency. Most consumers do not need to install it:

• Browser: globalThis.crypto.subtle is always available natively — the polyfill is never reached

• Node.js 18+: globalThis.crypto.subtle is available natively — the polyfill is never reached

• Node.js <15: globalThis.crypto is not available — install the polyfill if you are not passing crypto to the WebCrypto constructor:

  yarn add isomorphic-webcrypto
  # or
  npm install isomorphic-webcrypto

Note: isomorphic-webcrypto transitively pulls in expo and react-native as optional dependencies, which is why it is not included as a direct dependency of this package.

Usage

WebCrypto — Encryption / Decryption

import { WebCrypto } from '@agnostack/verifyd'

// Option 1: Let WebCrypto resolve crypto automatically
const webCrypto = new WebCrypto()

// Option 2: Pass native crypto explicitly (recommended for known environments)
const webCrypto = new WebCrypto({ crypto: globalThis.crypto })

// Encrypt
const encrypted = await webCrypto.encryptMessage('secret data', cryptoKey)

// Decrypt
const decrypted = await webCrypto.decryptMessage(encrypted, cryptoKey)

Verification Helpers (Server-Side)

import { getVerificationHelpers } from '@agnostack/verifyd'

const {
  generateStorableKeyPairs,
  prepareVerificationRequest,
  processVerificationResponse,
} = getVerificationHelpers()

React Hook

import { useVerification } from '@agnostack/verifyd/react'

const { verify, isVerified, error } = useVerification(options)

Contact Adam Grohs @ agnoStack for any questions.