@digitaldefiance/enclave-bridge-client

TypeScript client for Enclave Bridge - a macOS app that bridges Node.js to Apple's Secure Enclave via Unix domain socket.

Features

• 🔐 Secure Enclave Integration - Sign data with P-256 keys stored in Apple's Secure Enclave
• 🔑 ECIES Encryption - Encrypt/decrypt data with secp256k1 ECIES (compatible with @digitaldefiance/node-ecies-lib)
• 🔌 Unix Socket IPC - Fast local communication with the native macOS bridge app
• 📦 TypeScript First - Full type definitions included
• ⚡ Async/Await - Modern Promise-based API
• 🔄 Auto-Reconnection - Configurable reconnection with exponential backoff
• 📊 Request Queuing - Concurrent request handling with configurable limits
• 💾 Key Caching - Optional caching for frequently-used public keys
• 🌊 Streaming Support - Process large files with chunked encryption/decryption
• 🏊 Connection Pooling - Manage multiple connections for high-throughput scenarios

Prerequisites

• macOS with Apple Silicon (M1/M2/M3) or T2 chip
• Enclave Bridge macOS app running
• Node.js 18+

Installation

npm install @digitaldefiance/enclave-bridge-client

Optional Dependencies

For client-side encryption support, install:

npm install @digitaldefiance/node-ecies-lib

Quick Start

import { EnclaveBridgeClient } from '@digitaldefiance/enclave-bridge-client';

async function main() {
  // Create and connect client
  const client = new EnclaveBridgeClient();
  await client.connect();

  try {
    // Get the secp256k1 public key for ECIES encryption
    const publicKey = await client.getPublicKey();
    console.log('ECIES Public Key:', publicKey.hex);

    // Get the Secure Enclave P-256 public key
    const enclaveKey = await client.getEnclavePublicKey();
    console.log('Enclave Public Key:', enclaveKey.hex);

    // Sign data with Secure Enclave
    const signature = await client.enclaveSign(Buffer.from('Hello, Secure Enclave!'));
    console.log('Signature:', signature.hex);

    // Decrypt ECIES-encrypted data
    // (encrypted with the public key from getPublicKey())
    const decrypted = await client.decrypt(encryptedBuffer);
    console.log('Decrypted:', decrypted.text);
  } finally {
    await client.disconnect();
  }
}

main().catch(console.error);

API Reference

Constructor

new EnclaveBridgeClient(options?: EnclaveBridgeClientOptions)

Options:

Option	Type	Default	Description
socketPath	string	/tmp/enclave-bridge.sock	Path to Unix socket
timeout	number	30000	Operation timeout in ms
autoReconnect	boolean	true	Auto-reconnect on disconnect
maxReconnectAttempts	number	5	Max reconnection attempts
reconnectDelay	number	1000	Initial reconnect delay in ms
maxReconnectDelay	number	30000	Max reconnect delay (backoff cap)
debug	boolean	false	Enable verbose debug logging
logger	function	console.log	Custom logging function
cacheKeys	boolean	true	Cache public keys
maxConcurrentRequests	number	1	Max concurrent requests to server
enableHeartbeat	boolean	false	Enable automatic heartbeat
heartbeatInterval	number	30000	Heartbeat interval in ms

Static Methods

EnclaveBridgeClient.isSupported(socketPath?): Promise<PlatformSupport>

Check if the current platform supports Enclave Bridge.

const support = await EnclaveBridgeClient.isSupported();
if (!support.supported) {
  console.log('Not supported:', support.reason);
}

Connection Methods

connect(): Promise<void>

Connect to the EnclaveBridge socket server.

await client.connect();

disconnect(): Promise<void>

Disconnect from the server.

await client.disconnect();

isConnected: boolean

Check if currently connected.

connectionState: ConnectionState

Get current state: 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error'

Key Operations

getPublicKey(): Promise<PublicKeyInfo>

Get the secp256k1 public key used for ECIES operations. This key is persisted in the macOS Keychain.

const key = await client.getPublicKey();
console.log(key.base64);  // Base64 encoded
console.log(key.hex);     // Hex encoded
console.log(key.buffer);  // Raw Buffer

getEnclavePublicKey(): Promise<PublicKeyInfo>

Get the Secure Enclave P-256 public key. The private key never leaves the Secure Enclave.

const enclaveKey = await client.getEnclavePublicKey();

setPeerPublicKey(publicKey: string | Buffer): Promise<void>

Set a peer's public key for ECDH operations.

await client.setPeerPublicKey(peerPublicKeyHex);

listKeys(): Promise<KeyList>

List all available keys (requires server support).

const keys = await client.listKeys();
keys.keys.forEach(key => {
  console.log(key.keyId, key.keyType, key.createdAt);
});

rotateKey(): Promise<KeyRotationResult>

Rotate the current key (requires server support).

const result = await client.rotateKey();
console.log('New key ID:', result.newKeyId);

Cryptographic Operations

enclaveSign(data: Buffer | string): Promise<SignatureResult>

Sign data using the Secure Enclave P-256 key. The data is hashed with SHA-256 before signing.

const signature = await client.enclaveSign('message to sign');
console.log(signature.hex);

decrypt(encryptedData: Buffer): Promise<DecryptionResult>

Decrypt ECIES-encrypted data. Compatible with @digitaldefiance/node-ecies-lib format.

const result = await client.decrypt(encryptedBuffer);
console.log(result.text);    // As UTF-8 string
console.log(result.buffer);  // As Buffer

encrypt(data: Buffer, publicKey: Buffer): Promise<Buffer>

Encrypt data using ECIES (requires @digitaldefiance/node-ecies-lib).

const publicKey = await client.getPublicKey();
const encrypted = await client.encrypt(
  Buffer.from('secret'),
  publicKey.buffer
);

verifySignature(signature: Buffer, data: Buffer, publicKey: Buffer): Promise<boolean>

Verify a P-256 signature.

const isValid = await client.verifySignature(
  signatureBuffer,
  dataBuffer,
  publicKeyBuffer
);

enclaveGenerateKey(): Promise<KeyGenerationResult>

Generate a new ephemeral key.

const newKey = await client.enclaveGenerateKey();
console.log(newKey.publicKey.hex);

Server Commands

heartbeat(): Promise<HeartbeatResponse>

Send a heartbeat to the server.

const response = await client.heartbeat();
console.log('Server time:', response.timestamp);

getVersion(): Promise<ServerVersion>

Get the server version information.

const version = await client.getVersion();
console.log(version.version, version.protocol);

getStatus(): Promise<ServerStatus>

Get detailed server status.

const status = await client.getStatus();
console.log(status.status, status.connections, status.uptime);

getMetrics(): Promise<ServerMetrics>

Get server performance metrics.

const metrics = await client.getMetrics();
console.log('Total requests:', metrics.totalRequests);

getHealthStatus(): Promise<HealthStatus>

Get comprehensive health status.

const health = await client.getHealthStatus();
console.log(health.isHealthy, health.uptime);

Events

The client extends EventEmitter and emits:

Event	Description	Payload
connect	Connected to bridge	None
disconnect	Disconnected from bridge	None
error	Error occurred	Error
stateChange	Connection state changed	ConnectionState
reconnecting	Attempting reconnection	{ attempt, maxAttempts, delay }
reconnected	Successfully reconnected	None
reconnectFailed	All reconnection attempts failed	None
beforeDisconnect	About to disconnect	None
debug	Debug log message	{ message, meta }
requestSent	Request sent to server	{ command, payload }
responseReceived	Response received	response

client.on('connect', () => console.log('Connected!'));
client.on('reconnecting', ({ attempt, maxAttempts }) => {
  console.log(`Reconnecting: attempt ${attempt}/${maxAttempts}`);
});
client.on('error', (err) => console.error('Error:', err));

Advanced Usage

Connection Pooling

For high-throughput scenarios, use the connection pool:

import { ConnectionPool } from '@digitaldefiance/enclave-bridge-client';

const pool = new ConnectionPool({ poolSize: 3 });
await pool.initialize();

// Execute with automatic connection management
const signature = await pool.execute(async (client) => {
  return await client.enclaveSign('data');
});

// Or manually manage connections
const client = await pool.acquire();
try {
  await client.enclaveSign('data');
} finally {
  pool.release(client);
}

await pool.close();

Streaming Support

For large files, use streaming to process data in chunks:

import {
  encryptStream,
  decryptStream,
  encryptFile,
  decryptToFile
} from '@digitaldefiance/enclave-bridge-client/streaming';

// Encrypt a file with progress callback
await encryptFile(
  client,
  publicKey,
  '/path/to/input.txt',
  '/path/to/output.enc',
  { chunkSize: 1024 * 1024 }, // 1MB chunks
  (progress) => console.log(`${progress.percentage}% complete`)
);

// Decrypt a file
await decryptToFile(
  client,
  '/path/to/input.enc',
  '/path/to/output.txt'
);

Auto-Reconnection

Configure automatic reconnection with exponential backoff:

const client = new EnclaveBridgeClient({
  autoReconnect: true,
  maxReconnectAttempts: 10,
  reconnectDelay: 500,       // Start at 500ms
  maxReconnectDelay: 60000,  // Cap at 60 seconds
});

client.on('reconnecting', ({ attempt, delay }) => {
  console.log(`Reconnecting in ${delay}ms (attempt ${attempt})`);
});

client.on('reconnected', () => {
  console.log('Successfully reconnected!');
});

client.on('reconnectFailed', () => {
  console.error('All reconnection attempts failed');
});

Request Queuing

Multiple concurrent requests are automatically queued:

const client = new EnclaveBridgeClient({
  maxConcurrentRequests: 1, // Serialize requests
});

// These will be queued and processed sequentially
const [key1, key2, sig] = await Promise.all([
  client.getPublicKey(),
  client.getEnclavePublicKey(),
  client.enclaveSign('data'),
]);

Debug Logging

Enable verbose logging for troubleshooting:

const client = new EnclaveBridgeClient({
  debug: true,
  logger: (level, message, meta) => {
    console.log(`[${level}] ${message}`, meta);
  },
});

client.on('debug', (message, meta) => {
  // Handle debug events
});

Custom Error Types

The library provides specific error types for better error handling:

import {
  EnclaveBridgeError,
  ConnectionError,
  TimeoutError,
  DecryptionError,
  EncryptionError,
  SignatureError,
  InvalidOperationError,
  ProtocolError,
  PlatformError,
} from '@digitaldefiance/enclave-bridge-client';

try {
  await client.connect();
} catch (err) {
  if (err instanceof ConnectionError) {
    console.error('Connection failed:', err.code);
  } else if (err instanceof TimeoutError) {
    console.error('Timed out:', err.operation, err.timeoutMs);
  } else if (err instanceof PlatformError) {
    console.error('Platform not supported:', err.message);
  }
}

ECIES Format

The client uses the @digitaldefiance/node-ecies-lib ECIES format:

Field	Size	Description
Version	1 byte	Protocol version
Cipher Suite	1 byte	Cipher suite identifier
Encryption Type	1 byte	33=Basic, 66=WithLength, 99=Multiple
Ephemeral Public Key	33 bytes	Compressed secp256k1 key
IV	12 bytes	Initialization vector
Auth Tag	16 bytes	GCM authentication tag
Ciphertext	Variable	Encrypted data

Protocol

Communication uses a JSON-based protocol over Unix domain socket:

Request Format:

{ "cmd": "COMMAND_NAME", "data": "optional_payload" }

Response Format:

{ "publicKey": "base64_data" }  // Success
{ "error": "error_message" }     // Error

Commands

Command	Payload	Description
GET_PUBLIC_KEY	None	Get secp256k1 public key
GET_ENCLAVE_PUBLIC_KEY	None	Get Secure Enclave P-256 key
SET_PEER_PUBLIC_KEY	{ publicKey }	Store peer's public key
ENCLAVE_SIGN	{ data }	Sign with Secure Enclave
ENCLAVE_DECRYPT	{ data }	Decrypt ECIES data
ENCLAVE_GENERATE_KEY	None	Generate new key
HEARTBEAT	None	Server heartbeat
VERSION	None	Get server version
STATUS	None	Get server status
METRICS	None	Get server metrics
LIST_KEYS	None	List available keys
ENCLAVE_ROTATE_KEY	None	Rotate current key

Example: Encrypt in Node.js, Decrypt in Secure Enclave

import { eciesEncrypt } from '@digitaldefiance/node-ecies-lib';
import { EnclaveBridgeClient } from '@digitaldefiance/enclave-bridge-client';

async function encryptAndDecrypt() {
  const client = new EnclaveBridgeClient();
  await client.connect();

  // Get the bridge's public key
  const { buffer: publicKey } = await client.getPublicKey();

  // Encrypt a message using node-ecies-lib
  const message = Buffer.from('Secret message');
  const encrypted = eciesEncrypt(publicKey, message);

  // Decrypt using the Secure Enclave bridge
  const decrypted = await client.decrypt(encrypted);
  console.log('Decrypted:', decrypted.text); // "Secret message"

  await client.disconnect();
}

Security Considerations

• Secure Enclave Keys: Private keys for P-256 operations never leave the Secure Enclave hardware
• secp256k1 Keys: Stored in macOS Keychain with access control
• Local Only: Communication is via Unix domain socket (local only)
• No Network: The bridge does not expose any network interfaces
• Key Caching: Public keys can be cached in memory to reduce socket calls

Migration Guide

From v1.x to v2.x

The v2.x release adds new features while maintaining backward compatibility:

1. Connection State: Now includes 'reconnecting' state
2. Error Types: Use specific error classes for better handling
3. Event Names: New events added (reconnecting, reconnected, debug, etc.)

No breaking changes - existing code continues to work.

License

MIT