npm package: @openverifiable/ove-node
Description: Core library for creating DIDComm-enabled sovereign nodes
Latest version: 0.0.2

# @openverifiable/ove-node

Core library for creating DIDComm-enabled sovereign nodes in the Open Verifiable Network.

## Features

- **Sovereign Identity**: Auto-provision `did:peer` or `did:cheqd` DIDs
- **DIDComm v2.0**: Secure, encrypted messaging between nodes
- **Relationship Protocol**: Mandatory handshake for trust establishment
- **Payload Transformation**: Pluggable middleware for legacy API/webhook formats
- **HTTP Proxy**: Generic HTTP proxy router for wrapping backend APIs
- **Request Validation**: Zod-based validation middleware
- **Health Checks**: Standardized health check endpoints

## Installation

```bash
pnpm add @openverifiable/ove-node @openverifiable/open-verifiable-id-sdk
```

## Usage

### Basic Node Setup

```typescript
import { OVENode } from '@openverifiable/ove-node';
import { createDIDCommAgent } from '@openverifiable/open-verifiable-id-sdk';

const agentWrapper = createDIDCommAgent({
  dbPath: './node.db',
  kmsSecretKey: 'your-32-byte-hex-key',
});

const node = new OVENode({
  agentWrapper,
  port: 3000
});

await node.initialize();
await node.start();
```

### HTTP Proxy for Backend APIs

```typescript
import { createHttpProxy } from '@openverifiable/ove-node';
import express from 'express';

const app = express();
app.use(express.json());

// Proxy all requests to a backend API
const proxyRouter = createHttpProxy({
  targetUrl: 'https://api.example.com',
  headerTransform: (req) => ({
    'Authorization': `Bearer ${req.headers.authorization}`,
    'X-Custom-Header': 'value',
  }),
  customHandlers: new Map([
    ['/special-endpoint', async (req, res) => {
      // Custom handling for specific paths
      res.json({ custom: 'response' });
    }],
  ]),
});

app.use('/api', proxyRouter);
```

### Request Validation

```typescript
import { validateRequest } from '@openverifiable/ove-node';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  email: z.string().email(),
});

app.post('/users', validateRequest({ body: schema }), (req, res) => {
  // req.body is now validated and typed
  res.json({ success: true });
});
```

### Health Check

```typescript
import { createHealthCheck } from '@openverifiable/ove-node';

const healthHandler = createHealthCheck({
  includeDid: true,
  getDid: () => node.getDid(),
  getStatus: () => ({
    version: '1.0.0',
    uptime: process.uptime(),
  }),
});

app.get('/health', healthHandler);
```

## API

### OVENode

Main class for creating node instances.

#### Methods

- `initialize()`: Initialize the node with DID and agent setup
- `registerHandler(messageType: string, handler: MessageHandler)`: Register a message handler
- `registerMiddleware(path: string, transformer: PayloadTransformer)`: Register payload transformer
- `start(port: number)`: Start the HTTP server
- `getDid()`: Get the node's DID

### Middleware

#### `createHttpProxy(config: HttpProxyConfig)`

Creates an Express router that proxies HTTP requests to a target URL.

**Config Options:**
- `targetUrl`: Base URL of the backend API
- `pathPrefix`: Optional prefix to add/remove from paths
- `headerTransform`: Function to transform request headers
- `excludePaths`: Array of paths to exclude from proxying
- `customHandlers`: Map of path -> handler for custom route handling
- `onResponse`: Hook called after receiving response (for logging/monitoring)

#### `validateRequest(schemas)`

Zod-based validation middleware for request body, query, and params.

#### `createHealthCheck(config)`

Creates a health check endpoint handler.

**Config Options:**
- `includeDid`: Whether to include the node's DID in the response
- `getDid`: Function to get the node's DID
- `getStatus`: Function to return additional status information

## License

Apache-2.0