@cryptforge/key-exchange

Key exchange package for CryptForge SDK. Provides secure key exchange functionality across different environments: browser, Node.js server, and Electron.

Installation

npm install @cryptforge/key-exchange

Usage

This package provides separate entry points for different environments to ensure safe usage without mixing incompatible APIs.

Browser/Web Client

import { KeyTransportClient } from "@cryptforge/key-exchange";

const client = new KeyTransportClient("ws://localhost:3001");
const broadcastId = await client.enableBroadcast();

Node.js Server

import { KeyExchangeServer } from "@cryptforge/key-exchange/server";

const server = new KeyExchangeServer();
await server.start();

Electron

Electron has three separate contexts that must not be mixed:

Main Process (Node.js environment)

// In your main.js or main.ts
import {} from /* your exports */ "@cryptforge/key-exchange/electron-main";

// Main process code with access to Node.js and Electron APIs

Preload Script (Isolated context)

// In your preload.js or preload.ts
import {} from /* your exports */ "@cryptforge/key-exchange/electron-preload";

// Preload script that bridges main and renderer processes
// Use contextBridge to safely expose APIs to renderer

Renderer Process (Browser-like environment)

// In your renderer/app code
import {} from /* your exports */ "@cryptforge/key-exchange/electron-renderer";

// Renderer process code - browser-like environment

Architecture

Why Separate Entry Points?

Each environment has different capabilities and restrictions:

• Browser (/): No Node.js APIs, WebSocket only
• Server (/server): Full Node.js APIs, can use hyperswarm
• Electron Main (/electron-main): Node.js + Electron main process APIs
• Electron Preload (/electron-preload): Limited Node.js APIs in isolated context
• Electron Renderer (/electron-renderer): Browser-like with IPC to main process

Mixing these would cause runtime errors or security issues.

Project Structure

src/
├── index.ts              # Browser/web client entry point
├── server.ts             # Node.js server entry point
├── electron-main.ts      # Electron main process entry point
├── electron-preload.ts   # Electron preload script entry point
├── electron-renderer.ts  # Electron renderer process entry point
├── client/               # Browser client implementation
├── server/               # Server implementation
├── electron/
│   ├── main/            # Electron main process code
│   ├── preload/         # Electron preload script code
│   └── renderer/        # Electron renderer process code
└── types/               # Shared TypeScript types

Features

• Secure key exchange protocol
• Browser and Node.js support
• Full Electron support (main, preload, renderer)
• TypeScript support with full type definitions
• WebSocket-based communication for web/browser
• Hyperswarm support for server-to-server

Vite Plugin (Electron Main Process)

When building Electron apps with Vite, native Node.js modules need to be externalized to prevent bundling errors. The package includes a Vite plugin that automatically handles this for you.

Usage

// vite.main.config.ts (for Electron main process)
import { defineConfig } from "vite";
import { cryptforgeMainPlugin } from "@cryptforge/key-exchange/vite";

export default defineConfig({
  plugins: [cryptforgeMainPlugin()],
  // ... rest of your config
});

What it does

The plugin automatically externalizes these native modules:

• hyperswarm, hyperdht, udx-native, utp-native
• sodium-native, hypercore, hypercore-crypto
• random-access-file, compact-encoding, b4a
• @cryptforge/key-exchange

Without the plugin

If you prefer manual configuration or need to customize, you can add externals manually:

export default defineConfig({
  build: {
    rollupOptions: {
      external: [
        "hyperswarm",
        "hyperdht",
        "udx-native",
        // ... other native modules
      ],
    },
  },
});

Important Notes

• ⚠️ Only use this plugin for Electron main process builds
• ✅ The plugin merges with your existing external configuration
• ✅ Works with both array and function forms of external
• ✅ Supports custom build tools that use Rollup

Additional Documentation

• USAGE_EXAMPLES.md - Additional usage examples for different environments

License

ISC