Node.js Installation

The JACS Node.js package (@hai.ai/jacs) provides JavaScript/TypeScript bindings to the JACS Rust library, making it easy to integrate JACS into web applications, servers, and Node.js projects.

Requirements

Node.js: Version 16.0 or higher
npm or yarn: For package management
Operating System: macOS, Linux, or Windows with WSL

Installation

Using npm

npm install @hai.ai/jacs

Using yarn

yarn add @hai.ai/jacs

Using pnpm

pnpm add @hai.ai/jacs

Verify Installation

Create a simple test to verify everything is working:

// test.js
import { JacsAgent } from '@hai.ai/jacs';

console.log('JACS Node.js bindings loaded successfully!');

// Test basic functionality (async API)
try {
  const agent = new JacsAgent();
  await agent.load('./jacs.config.json');
  console.log('Agent loaded successfully!');
} catch (error) {
  console.error('Error loading agent:', error);
}

Run the test:

node test.js

Package Structure

The @hai.ai/jacs package exposes these entry points:

Core and simple API

import { JacsAgent, hashString, createConfig } from '@hai.ai/jacs';
import * as jacs from '@hai.ai/jacs/simple';  // quickstart, load, signMessage, verify, etc.

Instance-based client (recommended for new code)

import { JacsClient } from '@hai.ai/jacs/client';

MCP (`@hai.ai/jacs/mcp`)

import { createJACSTransportProxy, createJACSTransportProxyAsync, registerJacsTools } from '@hai.ai/jacs/mcp';

HTTP / framework adapters

import { jacsMiddleware } from '@hai.ai/jacs/express';
import { jacsKoaMiddleware } from '@hai.ai/jacs/koa';
import { JACSExpressMiddleware, JACSKoaMiddleware } from '@hai.ai/jacs/http';  // legacy

TypeScript Support

The package includes full TypeScript definitions:

import { JacsAgent, createConfig, hashString } from '@hai.ai/jacs';

// Create an agent instance
const agent: JacsAgent = new JacsAgent();

// Load configuration from file (async)
await agent.load('./jacs.config.json');

// Use utility functions
const hash: string = hashString('some data');

// Create a configuration string
const configJson: string = createConfig(
  undefined,           // jacs_use_security
  './jacs_data',       // jacs_data_directory
  './jacs_keys',       // jacs_key_directory
  undefined,           // jacs_agent_private_key_filename
  undefined,           // jacs_agent_public_key_filename
  'ring-Ed25519',      // jacs_agent_key_algorithm
  undefined,           // jacs_private_key_password
  undefined,           // jacs_agent_id_and_version
  'fs'                 // jacs_default_storage
);

Configuration

Basic Configuration

const config = {
  // Required fields
  jacs_data_directory: "./jacs_data",      // Where documents are stored
  jacs_key_directory: "./jacs_keys",       // Where keys are stored
  jacs_default_storage: "fs",              // Storage backend
  jacs_agent_key_algorithm: "ring-Ed25519",     // Signing algorithm
  
  // Optional fields
  jacs_agent_id_and_version: null,         // Existing agent to load
  jacs_agent_private_key_filename: "private.pem",
  jacs_agent_public_key_filename: "public.pem"
};

Configuration File

Create a jacs.config.json file:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  "jacs_default_storage": "fs",
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

Load the configuration:

import { JacsAgent } from '@hai.ai/jacs';

const agent = new JacsAgent();
agent.load('./jacs.config.json');

Environment Variables

JACS reads environment variables that override configuration file settings:

export JACS_DATA_DIRECTORY="./production_data"
export JACS_KEY_DIRECTORY="./production_keys"
export JACS_AGENT_KEY_ALGORITHM="ring-Ed25519"
export JACS_DEFAULT_STORAGE="fs"

Storage Backends

Configure storage in jacs.config.json:

File System (Default)

{
  "jacs_default_storage": "fs",
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys"
}

Local Indexed SQLite

{
  "jacs_default_storage": "rusqlite"
}

Use rusqlite when you want local full-text search and the upgraded DocumentService behavior in bindings and MCP.

AWS Storage

{
  "jacs_default_storage": "aws"
}

AWS credentials are read from standard AWS environment variables.

Memory Storage (Testing)

{
  "jacs_default_storage": "memory"
}

Cryptographic Algorithms

ring-Ed25519 (Recommended)

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

Pros: Fast, secure, small signatures Cons: Requires elliptic curve support

RSA-PSS

{
  "jacs_agent_key_algorithm": "RSA-PSS"
}

Pros: Widely supported, proven security Cons: Larger signatures, slower

pq-dilithium (Post-Quantum)

{
  "jacs_agent_key_algorithm": "pq-dilithium"
}

Pros: Quantum-resistant Cons: Experimental, large signatures

pq2025 (Post-Quantum Hybrid)

{
  "jacs_agent_key_algorithm": "pq2025"
}

Pros: Combines ML-DSA-87 with hybrid approach Cons: Newest algorithm, largest signatures

Development Setup

Project Structure

my-jacs-project/
├── package.json
├── jacs.config.json
├── src/
│   ├── agent.js
│   ├── tasks.js
│   └── agreements.js
├── jacs_data/
│   ├── agents/
│   ├── tasks/
│   └── documents/
└── jacs_keys/
    ├── private.pem
    └── public.pem

Package.json Setup

{
  "name": "my-jacs-app",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@hai.ai/jacs": "^0.6.0",
    "express": "^4.18.0"
  },
  "scripts": {
    "start": "node src/app.js",
    "test": "node test/test.js",
    "dev": "nodemon src/app.js"
  }
}

Basic Application

// src/app.js
import { JacsAgent } from '@hai.ai/jacs';

async function main() {
  const agent = new JacsAgent();
  await agent.load('./jacs.config.json');

  const documentJson = JSON.stringify({
    title: "My First Document",
    content: "Hello from Node.js!"
  });

  const signedDoc = await agent.createDocument(documentJson);
  console.log('Document created:', signedDoc);

  const isValid = await agent.verifyDocument(signedDoc);
  console.log('Document valid:', isValid);
  console.log('JACS agent ready!');
}
main().catch(console.error);

Common Issues

Module Not Found

If you get Module not found errors:

# Check Node.js version
node --version  # Should be 16+

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Permission Errors

If you get permission errors accessing files:

# Check directory permissions
ls -la jacs_data/ jacs_keys/

# Fix permissions
chmod 755 jacs_data/ jacs_keys/
chmod 600 jacs_keys/*.pem

Binary Compatibility

If you get binary compatibility errors:

# Rebuild native modules
npm rebuild

# Or reinstall
npm uninstall @hai.ai/jacs
npm install @hai.ai/jacs

TypeScript Issues

If TypeScript can't find definitions:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Next Steps

Now that you have JACS installed:

Basic Usage - Learn core JACS operations
MCP Integration - Add Model Context Protocol support
HTTP Server - Create JACS HTTP APIs
Express Middleware - Integrate with Express.js
API Reference - Complete API documentation

Examples

Check out the complete examples in the examples directory:

Basic agent creation and task management
Express.js middleware integration
MCP server implementation

JACS Usage Documentation