JACS: JSON Agent Communication Standard

Welcome to the JSON Agent Communication Standard (JACS) documentation! JACS is a comprehensive framework for creating, signing, and verifying JSON documents with cryptographic integrity, designed specifically for AI agent communication and task management.

What is JACS?

JACS provides a standard way for AI agents to:

• Create and sign JSON documents with cryptographic signatures
• Verify authenticity and integrity of documents
• Manage tasks and agreements between multiple agents
• Maintain audit trails of modifications and versioning
• Ensure trust in multi-agent systems

As a developer, JACS gives you the tools to build trustworthy AI systems where agents can securely exchange tasks, agreements, and data with verifiable integrity.

Key Features

• 🔐 Cryptographic Security: RSA, Ed25519, and post-quantum cryptographic algorithms
• 📋 JSON Schema Validation: Enforced document structure and validation
• 🤝 Multi-Agent Agreements: Built-in support for agent collaboration and task agreements
• 🔍 Full Audit Trail: Complete versioning and modification history
• 🌐 Multiple Language Support: Rust, Node.js, and Python implementations
• 🔌 MCP Integration: Native Model Context Protocol support
• 📊 Observability: Built-in logging and metrics for production systems

Available Implementations

JACS is available in three languages, each with its own strengths:

🦀 Rust (Core Library + CLI)

• Performance: Fastest implementation with native performance
• CLI Tool: Complete command-line interface for agent and document management
• Library: Full-featured Rust library for embedded applications
• Observability: Advanced logging and metrics with OpenTelemetry support

🟢 Node.js (jacsnpm)

• Web Integration: Perfect for web servers and Express.js applications
• MCP Support: Native Model Context Protocol integration
• HTTP Server: Built-in HTTP server capabilities
• NPM Package: Easy installation and integration

🐍 Python (jacspy)

• AI/ML Integration: Ideal for AI and machine learning workflows
• FastMCP: Advanced MCP server implementations
• PyPI Package: Simple pip install integration
• Data Science: Perfect for Jupyter notebooks and data pipelines

Quick Start

Choose your implementation and get started in minutes:

Rust CLI

cargo install jacs
jacs init  # Create config, keys, and agent

Or step by step:

jacs config create
jacs agent create --create-keys true

Node.js

npm install jacsnpm

import { JacsAgent } from 'jacsnpm';

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

Python

pip install jacs

import jacs

agent = jacs.JacsAgent()
agent.load("./config.json")

When to Use JACS

JACS is ideal for scenarios where you need:

• Multi-agent systems where agents need to trust each other
• Task delegation with verifiable completion and approval
• Audit trails for AI decision-making processes
• Secure data exchange between AI systems
• Compliance requirements for AI system interactions
• Version control for AI-generated content and decisions

Why JACS?

🎯 Agent-Focused Design

Unlike general-purpose signing frameworks, JACS is specifically designed for AI agent communication patterns - tasks, agreements, and collaborative workflows.

🚀 Production Ready

With built-in observability, multiple storage backends, and comprehensive error handling, JACS is ready for production AI systems.

🔒 Future-Proof Security

Support for both current (RSA, Ed25519) and post-quantum cryptographic algorithms ensures your system remains secure.

🌐 Universal Compatibility

JSON-based documents work everywhere - store them in any database, transmit over any protocol, integrate with any system.

🧩 Flexible Integration

Whether you're building a simple CLI tool or a complex multi-agent system, JACS adapts to your architecture.

Getting Started

1. Core Concepts - Understand agents, documents, and agreements
2. Quick Start Guide - Get up and running in minutes
3. Choose Your Implementation:
   • Rust CLI & Library
   • Node.js Package
   • Python Package

Community and Support

• GitHub: HumanAssisted/JACS
• Issues: Report bugs and feature requests
• Examples: Complete examples for all implementations
• Documentation: This comprehensive guide

Ready to build trustworthy AI systems? Let's get started!

What is JACS?

JACS (JSON Agent Communication Standard) is a comprehensive framework designed to solve a critical problem in AI systems: How do agents communicate and collaborate securely with verifiable trust?

The Problem JACS Solves

As AI systems become more sophisticated, we're moving toward multi-agent architectures where different AI agents need to:

• Exchange tasks and delegate work to each other
• Create agreements and verify their completion
• Share data with guaranteed authenticity
• Maintain audit trails of decisions and actions
• Establish trust without centralized authorities

Traditional approaches fall short because they lack:

• Cryptographic integrity for agent communications
• Standardized formats for agent interactions
• Built-in versioning and audit trails
• Support for multi-agent agreements and workflows

JACS Core Philosophy

🎯 Agent-First Design

JACS is built specifically for AI agent communication patterns, not as a general-purpose document signing system. It understands concepts like:

• Agents with identities and capabilities
• Tasks that can be delegated and tracked
• Agreements between multiple parties
• Versioning for iterative improvements

🔐 Trust Through Cryptography

Every JACS document includes:

• Digital signatures proving authenticity
• Hash verification ensuring integrity
• Public key cryptography for identity verification
• Timestamps for chronological ordering

📋 Standards-Based

JACS builds on proven standards:

• JSON for universal compatibility
• JSON Schema for structure validation
• RFC 3339 timestamps for consistency
• Standard cryptographic algorithms (RSA, Ed25519, post-quantum)

Key Concepts

Agents

An Agent is an autonomous entity with:

• A unique identity (UUID)
• Cryptographic keys for signing
• Capabilities defined in services
• The ability to create and verify documents

Documents

A Document is any JSON object that includes:

• JACS header fields (ID, version, creator, etc.)
• A cryptographic signature
• A hash for integrity verification
• Business logic specific to the document type

Tasks

A Task is a special document type representing:

• Work to be performed
• Success/failure criteria
• Input/output specifications
• Delegation and completion tracking

Agreements

An Agreement is a mechanism for:

• Multiple agents to consent to terms
• Tracking signatures from all required parties
• Ensuring all participants have signed before proceeding
• Creating binding commitments between agents

How JACS Works

graph TD
    A[Agent A] -->|Creates Task| T[JACS Task Document]
    T -->|Contains| S[Digital Signature]
    T -->|Contains| H[SHA256 Hash]
    T -->|Contains| M[Metadata]
    
    A -->|Sends to| B[Agent B]
    B -->|Verifies| T
    B -->|Signs Agreement| AG[Agreement Document]
    AG -->|Returns to| A

1. Agent A creates a task document with their requirements
2. The document is signed with Agent A's private key
3. A hash is calculated for integrity verification
4. Agent B receives and verifies the signature and hash
5. Agent B can create an agreement to accept the task
6. Both agents have a verifiable record of the interaction

Real-World Examples

🤖 AI Content Pipeline

Content Agent → Research Agent → Review Agent → Publishing Agent

Each handoff includes signed task documents with clear requirements and deliverables.

📊 Data Processing Workflow

Data Ingestion Agent → Processing Agent → Validation Agent → Storage Agent

Each step is tracked with verifiable completion certificates and quality metrics.

🔍 Multi-Agent Analysis

Query Agent → Research Agent → Analysis Agent → Reporting Agent

Complex analysis tasks are broken down with clear accountability for each step.

Benefits Over Alternatives

When to Use JACS

✅ Perfect for:

• Multi-agent AI systems
• Task delegation and tracking
• Audit trail requirements
• Cross-organization AI collaboration
• Compliance-critical AI applications
• Research environments with multiple AI models

⚠️ Consider alternatives for:

• Simple single-agent systems
• Real-time streaming data
• High-frequency micro-transactions
• Systems where trust is not a concern

Next Steps

Ready to dive deeper? Continue with:

• Core Concepts - Learn about agents, documents, and agreements
• Quick Start - Get hands-on experience
• Implementation guides for Rust, Node.js, or Python

Core Concepts

Understanding JACS requires familiarity with several key concepts that work together to create a secure, verifiable communication framework for AI agents.

Agents

An Agent is the fundamental entity in JACS - an autonomous participant that can create, sign, and verify documents.

Agent Identity

{
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "123e4567-e89b-12d3-a456-426614174000",
  "jacsType": "agent",
  "name": "Content Creation Agent",
  "description": "Specialized in creating marketing content"
}

Key Properties:

• jacsId: Permanent UUID identifying the agent
• jacsVersion: UUID that changes with each update
• Cryptographic Keys: Ed25519, RSA, or post-quantum key pairs
• Services: Capabilities the agent offers
• Contacts: How to reach the agent

Agent Lifecycle

1. Creation: Generate keys and initial agent document
2. Registration: Store public keys for verification
3. Operation: Create and sign documents
4. Updates: Version changes while maintaining identity
5. Verification: Other agents validate signatures

Documents

A Document is any JSON object that follows JACS conventions for identity, versioning, and cryptographic integrity.

Document Structure

{
  "jacsId": "doc-uuid-here",
  "jacsVersion": "version-uuid-here",
  "jacsType": "task",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsPreviousVersion": "previous-version-uuid",
  
  "title": "Analyze Q4 Sales Data",
  "description": "Generate insights from sales data",
  
  "jacsSha256": "hash-of-document-content",
  "jacsSignature": {
    "agentID": "agent-uuid",
    "agentVersion": "agent-version-uuid",
    "signature": "base64-signature",
    "signingAlgorithm": "ring-Ed25519",
    "publicKeyHash": "hash-of-public-key",
    "date": "2024-01-15T10:30:00Z",
    "fields": ["jacsId", "title", "description"]
  }
}

Required JACS Fields

Document Types

Agent Documents

• Define agent identity and capabilities
• Contain service definitions and contact information
• Self-signed by the agent

Task Documents

• Describe work to be performed
• Include success/failure criteria
• Can be delegated between agents

Message Documents

• General communication between agents
• Can include attachments and metadata
• Support threaded conversations

Agreement Documents

• Multi-party consent mechanisms
• Track required and actual signatures
• Enforce completion before proceeding

Tasks

Tasks represent work that can be delegated, tracked, and verified between agents.

Task Structure

{
  "jacsType": "task",
  "title": "Generate Marketing Copy",
  "description": "Create compelling copy for product launch",
  
  "actions": [
    {
      "id": "research",
      "name": "Research competitors",
      "description": "Analyze competitor messaging",
      "success": "Complete competitive analysis report",
      "failure": "Unable to access competitor data"
    }
  ],
  
  "jacsTaskCustomer": {
    "agentID": "customer-agent-uuid",
    "signature": "customer-signature"
  }
}

Task Lifecycle

1. Creation: Customer agent creates task with requirements
2. Delegation: Task sent to service provider agent
3. Agreement: Provider signs agreement to accept task
4. Execution: Provider performs the work
5. Completion: Provider creates completion document
6. Verification: Customer verifies and accepts results

Task Components

Actions: Individual steps within a task

• id: Unique identifier within the task
• name: Human-readable action name
• description: Detailed requirements
• success: Definition of successful completion
• failure: What constitutes failure

Services: Required capabilities

• type: Service category
• requirements: Specific needs
• constraints: Limitations or restrictions

Agreements

Agreements enable multi-party consent and coordination between agents.

Agreement Structure

{
  "jacsType": "agreement",
  "title": "Task Acceptance Agreement",
  "question": "Do you agree to complete the marketing copy task?",
  "context": "Task ID: abc123, Deadline: 2024-01-20",
  
  "agents": [
    "agent-1-uuid",
    "agent-2-uuid",
    "agent-3-uuid"
  ],
  
  "jacsAgreement": {
    "agent-1-uuid": {
      "agentID": "agent-1-uuid",
      "signature": "base64-signature",
      "date": "2024-01-15T10:30:00Z"
    },
    "agent-2-uuid": {
      "agentID": "agent-2-uuid", 
      "signature": "base64-signature",
      "date": "2024-01-15T11:15:00Z"
    }
    // agent-3-uuid has not signed yet
  },
  
  "jacsAgreementHash": "hash-of-agreement-content"
}

Agreement Process

1. Creation: Initial agent creates agreement with required participants
2. Distribution: Agreement sent to all required agents
3. Review: Each agent reviews terms and conditions
4. Signing: Agents add their signatures if they consent
5. Completion: Agreement becomes binding when all parties have signed
6. Verification: Any party can verify all signatures

Agreement Types

Task Agreements: Consent to perform specific work Service Agreements: Long-term service provision contracts
Data Sharing Agreements: Permission to access or use data Update Agreements: Consent to system or process changes

Cryptographic Security

JACS uses industry-standard cryptographic primitives for security.

Supported Algorithms

Current Standards

• ring-Ed25519: Fast elliptic curve signatures using the ring library (recommended)
• RSA-PSS: Traditional RSA with probabilistic signature scheme

Post-Quantum

• pq-dilithium: NIST-standardized post-quantum signatures

Signature Process

1. Content Extraction: Specific fields are extracted for signing
2. Canonicalization: Fields are sorted and formatted consistently
3. Hashing: SHA-256 hash of the canonical content
4. Signing: Private key signs the hash
5. Verification: Public key verifies the signature

Key Management

• Agent Keys: Each agent has a unique key pair
• Public Key Distribution: Public keys shared through secure channels
• Key Rotation: Agents can update keys while maintaining identity
• Key Verification: Public key hashes ensure integrity

Versioning and Audit Trails

JACS provides comprehensive versioning for tracking document evolution.

Version Management

• Immutable IDs: jacsId never changes for a document
• Version IDs: jacsVersion changes with each update
• Previous Versions: jacsPreviousVersion creates a chain
• Timestamps: jacsVersionDate provides chronological order

Audit Trail Benefits

• Complete History: Track all changes to any document
• Attribution: Know exactly who made each change
• Verification: Cryptographic proof of authenticity
• Compliance: Meet regulatory audit requirements

Storage and Transport

JACS documents are designed to be storage and transport agnostic.

Storage Options

• File System: Simple JSON files
• Databases: Store as JSON/JSONB fields
• Object Storage: S3, Azure Blob, Google Cloud Storage
• Version Control: Git repositories for change tracking

Transport Mechanisms

• HTTP APIs: RESTful or GraphQL endpoints
• Message Queues: RabbitMQ, Kafka, SQS
• Email: Documents as attachments
• Direct Transfer: USB drives, file sharing

Format Compatibility

• JSON: Universal compatibility across all systems
• Schema Validation: Ensures consistent structure
• Self-Contained: All necessary information in the document
• Human Readable: Can be inspected and debugged easily

Next Steps

Now that you understand the core concepts:

1. Quick Start - Try JACS hands-on
2. Choose Implementation:
   • Rust CLI for command-line usage
   • Node.js for web applications
   • Python for AI/ML workflows
3. Examples - See real-world usage patterns

Quick Start Guide

This guide will get you up and running with JACS in under 10 minutes. We'll create an agent, generate a task, and demonstrate the core workflow across all three implementations.

Choose Your Implementation

Select the implementation that best fits your needs:

# Install from crates.io
cargo install jacs

# Or build from source
git clone https://github.com/HumanAssisted/JACS
cd JACS/jacs
cargo install --path . --features="cli"

# Create configuration and agent in one step
jacs init

# This creates:
# - ~/.jacs/config.json
# - Agent keys and documents
# - Basic directory structure

# Create an agent (if not done via jacs init)
# Agent type is defined in the input JSON file or default template
jacs agent create --create-keys true

# Or provide a custom agent definition file
jacs agent create --create-keys true -f my-agent.json

# Verify your agent was created correctly
jacs agent verify

# Create a task document with name and description
jacs task create \
  -n "Write Product Description" \
  -d "Create compelling copy for new product launch"

# The task is automatically signed by your agent

npm install jacsnpm

import { JacsAgent, createConfig } from 'jacsnpm';
import fs from 'fs';

// Create configuration
const config = {
  jacs_agent_id_and_version: null,
  jacs_data_directory: "./jacs_data",
  jacs_key_directory: "./jacs_keys",
  jacs_default_storage: "fs",
  jacs_agent_key_algorithm: "ring-Ed25519"
};

// Save config
fs.writeFileSync('./jacs.config.json', JSON.stringify(config, null, 2));

// Create agent instance and load configuration
const agent = new JacsAgent();
agent.load('./jacs.config.json');

// Create agent with services
const agentData = {
  name: "Content Creator Bot",
  description: "AI agent specialized in content creation",
  services: [
    {
      type: "content_generation",
      name: "Product Description Writer",
      description: "Creates compelling product descriptions",
      success: "Engaging copy that converts visitors",
      failure: "Generic or low-quality content"
    }
  ]
};

// Generate keys and create agent
await agent.generateKeys();
const agentDoc = await agent.createAgent(agentData);
console.log('Agent created:', agentDoc.jacsId);

// Create task document
const task = {
  title: "Write Product Description",
  description: "Create compelling copy for new product launch",
  actions: [
    {
      id: "research",
      name: "Product Research", 
      description: "Analyze product features and benefits",
      success: "Complete understanding of product value",
      failure: "Insufficient product knowledge"
    },
    {
      id: "write",
      name: "Write Copy",
      description: "Create engaging product description",
      success: "200-word compelling description",
      failure: "Generic or unconvincing copy"
    }
  ]
};

// Sign and create task
const signedTask = await agent.createTask(task);
console.log('Task created:', signedTask.jacsId);

pip install jacs

import jacs
import json
import os

# Create configuration
config = {
    "jacs_agent_id_and_version": None,
    "jacs_data_directory": "./jacs_data",
    "jacs_key_directory": "./jacs_keys",
    "jacs_default_storage": "fs",
    "jacs_agent_key_algorithm": "ring-Ed25519"
}

# Ensure directories exist
os.makedirs("./jacs_data", exist_ok=True)
os.makedirs("./jacs_keys", exist_ok=True)

# Save config
with open('jacs.config.json', 'w') as f:
    json.dump(config, f, indent=2)

# Create agent instance and load configuration
agent = jacs.JacsAgent()
agent.load("./jacs.config.json")

# Define agent capabilities
agent_data = {
    "name": "Content Creator Bot",
    "description": "AI agent specialized in content creation",
    "services": [
        {
            "type": "content_generation",
            "name": "Product Description Writer", 
            "description": "Creates compelling product descriptions",
            "success": "Engaging copy that converts visitors",
            "failure": "Generic or low-quality content"
        }
    ]
}

# Generate keys and create agent
agent.generate_keys()
agent_doc = agent.create_agent(agent_data)
print(f'Agent created: {agent_doc["jacsId"]}')

# Define task
task = {
    "title": "Write Product Description",
    "description": "Create compelling copy for new product launch",
    "actions": [
        {
            "id": "research",
            "name": "Product Research",
            "description": "Analyze product features and benefits", 
            "success": "Complete understanding of product value",
            "failure": "Insufficient product knowledge"
        },
        {
            "id": "write", 
            "name": "Write Copy",
            "description": "Create engaging product description",
            "success": "200-word compelling description",
            "failure": "Generic or unconvincing copy"
        }
    ]
}

# Sign and create task
signed_task = agent.create_task(task)
print(f'Task created: {signed_task["jacsId"]}')

Understanding What Happened

When you completed the quick start, several important things occurred:

1. Agent Creation

• A unique identity (UUID) was generated for your agent
• Cryptographic key pair was created for signing
• Agent document was created and self-signed
• Public key was stored for verification

2. Configuration Setup

• Storage directories were configured
• Cryptographic algorithm was selected
• Agent identity was linked to configuration

3. Task Creation

• Task document was structured according to JACS schema
• Document was signed with your agent's private key
• SHA-256 hash was calculated for integrity
• Signature metadata was embedded in the document

Verify Everything Works

Let's verify that the documents are properly signed and can be validated:

# Verify agent signature
jacs agent verify

# Verify a specific document
jacs document verify -f ./jacs_data/[document-id].json

# Sign a document
jacs document sign -f ./jacs_data/[document-id].json

// Verify agent signature
const isValid = await agent.verifyAgent();
console.log('Agent signature valid:', isValid);

// List all documents
const documents = await agent.listDocuments();
console.log('Documents:', documents.length);

// Verify task signature
const taskValid = await agent.verifyDocument(signedTask);
console.log('Task signature valid:', taskValid);

// Get document details
const taskDetails = await agent.getDocument(signedTask.jacsId);
console.log('Task details:', taskDetails);

# Verify agent signature
is_valid = agent.verify_agent()
print(f'Agent signature valid: {is_valid}')

# List all documents
documents = agent.list_documents()
print(f'Documents: {len(documents)}')

# Verify task signature  
task_valid = agent.verify_document(signed_task)
print(f'Task signature valid: {task_valid}')

# Get document details
task_details = agent.get_document(signed_task["jacsId"])
print(f'Task details: {task_details}')

Next Steps: Multi-Agent Workflow

Now let's create a second agent and demonstrate inter-agent communication:

# Create a second agent configuration
cp jacs.config.json reviewer.config.json
# Edit reviewer.config.json to set jacs_agent_id_and_version to null

# Create reviewer agent (uses JACS_CONFIG_PATH environment variable)
JACS_CONFIG_PATH=./reviewer.config.json jacs agent create --create-keys true

# Create an agreement on a document
jacs agreement create -f ./document.json \
  --agents [agent-1-id],[agent-2-id] \
  --question "Do you agree to collaborate on this content task?"

# Sign the agreement as first agent
jacs agreement sign -f ./document.json

# Sign as second agent (using reviewer config)
JACS_CONFIG_PATH=./reviewer.config.json jacs agreement sign -f ./document.json

# Verify agreement is complete
jacs agreement check -f ./document.json

// Create second agent with separate config file
const reviewerConfig = { ...config };
reviewerConfig.jacs_agent_id_and_version = null;

fs.writeFileSync('./reviewer.config.json', JSON.stringify(reviewerConfig, null, 2));

const reviewer = new JacsAgent();
reviewer.load('./reviewer.config.json');
await reviewer.generateKeys();

const reviewerDoc = await reviewer.createAgent({
  name: "Content Reviewer Bot",
  description: "AI agent specialized in content review"
});

// Create agreement between agents
const agreement = {
  title: "Content Collaboration Agreement",
  question: "Do you agree to collaborate on this content task?",
  context: `Task: ${signedTask.jacsId}`,
  agents: [agentDoc.jacsId, reviewerDoc.jacsId]
};

const signedAgreement = await agent.createAgreement(agreement);

// Both agents sign the agreement
await agent.signAgreement(signedAgreement.jacsId);
await reviewer.signAgreement(signedAgreement.jacsId);

// Verify all signatures
const agreementValid = await agent.verifyAgreement(signedAgreement.jacsId);
console.log('Agreement complete:', agreementValid);

# Create second agent with separate config file
reviewer_config = config.copy()
reviewer_config["jacs_agent_id_and_version"] = None

with open('reviewer.config.json', 'w') as f:
    json.dump(reviewer_config, f, indent=2)

reviewer = jacs.JacsAgent()
reviewer.load("./reviewer.config.json")
reviewer.generate_keys()

reviewer_doc = reviewer.create_agent({
    "name": "Content Reviewer Bot", 
    "description": "AI agent specialized in content review"
})

# Create agreement between agents
agreement = {
    "title": "Content Collaboration Agreement",
    "question": "Do you agree to collaborate on this content task?",
    "context": f"Task: {signed_task['jacsId']}",
    "agents": [agent_doc["jacsId"], reviewer_doc["jacsId"]]
}

signed_agreement = agent.create_agreement(agreement)

# Both agents sign the agreement
agent.sign_agreement(signed_agreement["jacsId"])
reviewer.sign_agreement(signed_agreement["jacsId"])

# Verify all signatures
agreement_valid = agent.verify_agreement(signed_agreement["jacsId"])
print(f'Agreement complete: {agreement_valid}')

What You've Accomplished

Congratulations! You've successfully:

✅ Created JACS agents with cryptographic identities ✅ Generated and signed documents with verifiable integrity
✅ Established multi-agent agreements with cryptographic consent ✅ Verified signatures and document authenticity ✅ Created an audit trail of all interactions

Key Takeaways

• Everything is verifiable: All documents have cryptographic signatures
• Agents are autonomous: Each has its own identity and keys
• Agreements enable trust: Multi-party consent before proceeding
• Audit trails are automatic: Complete history of all interactions
• JSON is universal: Documents work everywhere

Where to Go Next

Now that you have the basics working:

1. Rust Deep Dive - Learn the full Rust API
2. Node.js Integration - Add MCP support
3. Python FastMCP - Build MCP servers
4. Production Setup - Add monitoring and logging
5. Real Examples - See production patterns

Troubleshooting

Agent creation fails: Check that the data and key directories exist and are writable Signature verification fails: Ensure public keys are properly stored and accessible Agreement signing fails: Verify all agent IDs are correct and agents exist Documents not found: Check the data directory configuration

Need help? Check the GitHub issues or review the detailed implementation guides.

Installation

This guide covers installing the JACS Rust CLI and library.

Requirements

• Rust: Version 1.93 or later (Edition 2024)
• Cargo: Included with Rust installation

Verify Rust Version

rustc --version
# Should show rustc 1.93.0 or later

If you need to update Rust:

rustup update stable

Installing the CLI

From crates.io (Recommended)

cargo install jacs --features cli

From Source

git clone https://github.com/HumanAssisted/JACS
cd JACS/jacs
cargo install --path . --features cli

Verify Installation

jacs --help

Using as a Library

Add JACS to your Cargo.toml:

[dependencies]
jacs = "0.3"

With Optional Features

JACS supports several optional features for observability and integrations:

[dependencies]
# Basic library usage
jacs = "0.3"

# With OpenTelemetry logging
jacs = { version = "0.3", features = ["otlp-logs"] }

# With OpenTelemetry metrics
jacs = { version = "0.3", features = ["otlp-metrics"] }

# With OpenTelemetry tracing
jacs = { version = "0.3", features = ["otlp-tracing"] }

# With all observability features
jacs = { version = "0.3", features = ["otlp-logs", "otlp-metrics", "otlp-tracing"] }

Available Features

Platform Support

JACS supports the following platforms:

WebAssembly Notes

When targeting WebAssembly, some features are unavailable:

• Post-quantum cryptographic algorithms (pq-dilithium)
• File system storage backend
• HTTP-based remote operations

Configuration

After installation, initialize JACS:

# Create configuration and agent in one step
jacs init

This creates:

• ~/.jacs/jacs.config.json - Configuration file
• Cryptographic keys for your agent
• Initial agent document

Manual Configuration

Alternatively, create configuration and agent separately:

# Create configuration only
jacs config create

# Create agent with keys
jacs agent create --create-keys true

Environment Variables

JACS respects the following environment variables:

Troubleshooting

Build Errors

"edition 2024 is required" Update Rust to version 1.93 or later:

rustup update stable

Missing dependencies on Linux Install build essentials:

# Debian/Ubuntu
sudo apt-get install build-essential pkg-config libssl-dev

# Fedora
sudo dnf install gcc openssl-devel

Runtime Errors

"Configuration file not found" Run jacs init or set JACS_CONFIG_PATH environment variable.

"Key directory does not exist" Create the key directory or run jacs init:

mkdir -p ./jacs_keys

"Permission denied" Ensure you have write permissions to the data and key directories.

Next Steps

• CLI Usage - Learn CLI commands
• Creating an Agent - Create your first agent
• Rust Library API - Use JACS as a library

CLI Usage

The JACS CLI provides a command-line interface for managing agents, documents, tasks, and agreements.

Getting Help

# General help
jacs --help

# Command-specific help
jacs agent --help
jacs document --help
jacs task --help

Commands Overview

Initialization

Quick Start

# Initialize everything in one step
jacs init

This command:

1. Creates a configuration file (jacs.config.json)
2. Generates cryptographic keys
3. Creates an initial agent document

Configuration Commands

Create Configuration

jacs config create

Creates a new jacs.config.json file in the current directory with default settings.

Read Configuration

jacs config read

Displays the current configuration, including values from both the config file and environment variables.

Agent Commands

Create Agent

jacs agent create --create-keys true

# With a custom agent definition file
jacs agent create --create-keys true -f my-agent.json

# Without creating new keys (use existing)
jacs agent create --create-keys false -f my-agent.json

Options:

Verify Agent

# Verify agent from config
jacs agent verify

# Verify specific agent file
jacs agent verify -a ./path/to/agent.json

# With DNS validation options
jacs agent verify --require-dns
jacs agent verify --require-strict-dns
jacs agent verify --no-dns
jacs agent verify --ignore-dns

Options:

DNS Commands

# Generate DNS TXT record commands for agent publishing
jacs agent dns --domain example.com --agent-id [uuid]

# With different output formats
jacs agent dns --domain example.com --encoding hex
jacs agent dns --domain example.com --provider aws

# With custom TTL
jacs agent dns --domain example.com --ttl 7200

Options:

Lookup Agent

# Look up another agent's public key from their domain
jacs agent lookup agent.example.com

# With strict DNSSEC validation
jacs agent lookup agent.example.com --strict

# Skip DNS lookup
jacs agent lookup agent.example.com --no-dns

Task Commands

Create Task

jacs task create -n "Task Name" -d "Task description"

# With optional agent file
jacs task create -n "Task Name" -d "Description" -a ./agent.json

# With input file
jacs task create -n "Task Name" -d "Description" -f ./task-details.json

Options:

Document Commands

Create Document

# Create from a JSON file
jacs document create -f ./document.json

# Create from a directory of files
jacs document create -d ./documents/

# With custom schema
jacs document create -f ./document.json -s ./custom-schema.json

# With file attachments
jacs document create -f ./document.json --attach ./attachment.pdf

# Embed attachments in document
jacs document create -f ./document.json --attach ./files/ --embed true

# Output to specific file
jacs document create -f ./document.json -o ./output.json

# Print to stdout instead of saving
jacs document create -f ./document.json --no-save

Options:

Update Document

# Update an existing document with new content
jacs document update -f ./original.json -n ./updated.json

# With output file
jacs document update -f ./original.json -n ./updated.json -o ./result.json

# With file attachments
jacs document update -f ./original.json -n ./updated.json --attach ./new-file.pdf

Options:

Verify Document

# Verify a document
jacs document verify -f ./document.json

# Verify all documents in a directory
jacs document verify -d ./documents/

# With custom schema
jacs document verify -f ./document.json -s ./schema.json

# Verbose output
jacs document verify -f ./document.json -v

Options:

Extract Embedded Content

# Extract embedded content from a document
jacs document extract -f ./document.json

# Extract from all documents in directory
jacs document extract -d ./documents/

Agreement Commands

# Create an agreement requiring signatures from specified agents
jacs document create-agreement -f ./document.json -i agent1-uuid,agent2-uuid

# Check agreement status
jacs document check-agreement -f ./document.json

# Sign an agreement
jacs document sign-agreement -f ./document.json

Create Agreement Options:

Environment Variables

The CLI respects the following environment variables:

# Use a specific configuration file
JACS_CONFIG_PATH=./custom-config.json jacs agent verify

# Override settings
JACS_DATA_DIRECTORY=./data jacs document create -f ./doc.json
JACS_KEY_DIRECTORY=./keys jacs agent create --create-keys true

Common Workflows

Create and Sign a Document

# 1. Initialize (if not done)
jacs init

# 2. Create document
jacs document create -f ./my-document.json

# 3. Verify the signed document
jacs document verify -f ./jacs_data/[document-id].json

Multi-Agent Agreement

# 1. Create agreement on a document
jacs document create-agreement -f ./document.json -i agent1-id,agent2-id

# 2. First agent signs
jacs document sign-agreement -f ./document.json

# 3. Second agent signs (using their config)
JACS_CONFIG_PATH=./agent2.config.json jacs document sign-agreement -f ./document.json

# 4. Check agreement is complete
jacs document check-agreement -f ./document.json

Verify Another Agent

# Look up agent by domain
jacs agent lookup other-agent.example.com

# Verify with strict DNS
jacs agent verify -a ./other-agent.json --require-strict-dns

Exit Codes

Next Steps

• Creating an Agent - Detailed agent creation guide
• Working with Documents - Document operations in depth
• Agreements - Multi-agent agreements

Creating an Agent

An agent is the fundamental identity in JACS - an autonomous entity that can create, sign, and verify documents. This guide covers creating and managing agents.

What is an Agent?

A JACS agent is:

• A unique identity with a UUID that never changes
• A holder of cryptographic keys for signing
• A provider of services defined in the agent document
• Self-signed to prove authenticity

Creating Your First Agent

Quick Method (Recommended)

# Initialize JACS (creates config and agent)
jacs init

This creates:

• Configuration file
• Cryptographic key pair
• Initial agent document

Manual Method

# 1. Create configuration
jacs config create

# 2. Create agent with new keys
jacs agent create --create-keys true

With Custom Agent Definition

Create an agent definition file (my-agent.json):

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsAgentType": "ai",
  "jacsAgentDomain": "myagent.example.com",
  "name": "Content Creation Agent",
  "description": "AI agent specialized in content creation",
  "jacsServices": [
    {
      "jacsServiceName": "content-generation",
      "jacsServiceDescription": "Generate high-quality content",
      "jacsServiceSuccess": "Engaging, accurate content delivered",
      "jacsServiceFailure": "Unable to generate requested content"
    }
  ]
}

Then create the agent:

jacs agent create --create-keys true -f my-agent.json

Agent Types

JACS supports four agent types:

AI Agent Example

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsAgentType": "ai",
  "name": "DataBot",
  "description": "Data processing agent",
  "jacsServices": [
    {
      "jacsServiceName": "data-processing",
      "jacsServiceDescription": "Process and transform data"
    }
  ]
}

Human Agent Example

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsAgentType": "human",
  "name": "John Smith",
  "description": "Software engineer",
  "jacsContacts": [
    {
      "jacsContactType": "email",
      "jacsContactValue": "john@example.com"
    }
  ],
  "jacsServices": [
    {
      "jacsServiceName": "code-review",
      "jacsServiceDescription": "Review code for quality and security"
    }
  ]
}

Agent Services

Services define what an agent can do. Each service has:

{
  "jacsServiceName": "service-identifier",
  "jacsServiceDescription": "What the service does",
  "jacsServiceSuccess": "Definition of successful completion",
  "jacsServiceFailure": "What constitutes failure",
  "jacsServiceActions": [
    {
      "jacsActionName": "action-1",
      "jacsActionDescription": "First action in this service"
    }
  ]
}

Service with Actions

{
  "jacsServiceName": "document-processing",
  "jacsServiceDescription": "Process and analyze documents",
  "jacsServiceActions": [
    {
      "jacsActionName": "extract-text",
      "jacsActionDescription": "Extract text from PDF documents"
    },
    {
      "jacsActionName": "summarize",
      "jacsActionDescription": "Generate document summaries"
    },
    {
      "jacsActionName": "translate",
      "jacsActionDescription": "Translate documents between languages"
    }
  ]
}

Agent Contacts

For human and hybrid agents, contacts are required:

{
  "jacsContacts": [
    {
      "jacsContactType": "email",
      "jacsContactValue": "agent@example.com"
    },
    {
      "jacsContactType": "website",
      "jacsContactValue": "https://example.com"
    },
    {
      "jacsContactType": "phone",
      "jacsContactValue": "+1-555-0123"
    }
  ]
}

Cryptographic Keys

Key Algorithms

JACS supports multiple cryptographic algorithms:

Configure Key Algorithm

In jacs.config.json:

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

Or via environment variable:

JACS_AGENT_KEY_ALGORITHM=ring-Ed25519 jacs agent create --create-keys true

Key Storage

Keys are stored in the key directory (default: ./jacs_keys):

jacs_keys/
├── private_key.pem    # Private key (keep secure!)
└── public_key.pem     # Public key (can be shared)

Verifying Agents

Verify Your Own Agent

jacs agent verify

Verify a Specific Agent File

jacs agent verify -a ./path/to/agent.json

With DNS Verification

# Require DNS validation
jacs agent verify --require-dns

# Require strict DNSSEC
jacs agent verify --require-strict-dns

Updating Agents

Agent updates create a new version while maintaining the same jacsId:

1. Modify the agent document
2. Re-sign with the agent's keys

The jacsVersion changes but jacsId remains constant.

Agent Document Structure

A complete agent document looks like:

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "123e4567-e89b-12d3-a456-426614174000",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "123e4567-e89b-12d3-a456-426614174000",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsType": "agent",
  "jacsLevel": "config",

  "jacsAgentType": "ai",
  "jacsAgentDomain": "myagent.example.com",
  "name": "Content Creation Agent",
  "description": "AI agent for content generation",

  "jacsServices": [
    {
      "jacsServiceName": "content-generation",
      "jacsServiceDescription": "Generate high-quality content"
    }
  ],

  "jacsSha256": "hash-of-document",
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "123e4567-e89b-12d3-a456-426614174000",
    "signature": "base64-encoded-signature",
    "signingAlgorithm": "ring-Ed25519",
    "publicKeyHash": "hash-of-public-key",
    "date": "2024-01-15T10:30:00Z",
    "fields": ["jacsId", "jacsVersion", "jacsAgentType", "name", "jacsServices"]
  }
}

Best Practices

Security

1. Protect private keys: Never share or commit private keys
2. Use strong algorithms: Prefer Ed25519 or post-quantum
3. Enable DNS verification: For production agents
4. Regular key rotation: Update keys periodically

Agent Design

1. Clear service definitions: Be specific about capabilities
2. Meaningful names: Use descriptive agent names
3. Contact information: Include for human agents
4. Version control: Track agent document changes

Operations

1. Backup keys: Keep secure backups of private keys
2. Monitor signatures: Watch for unauthorized signing
3. Document services: Keep service definitions current

Next Steps

• Working with Documents - Create signed documents
• Agreements - Multi-agent coordination
• DNS Verification - Publish agent identity

Working with Documents

Documents are the core data structure in JACS. Any JSON object can become a JACS document by adding the required header fields and a cryptographic signature.

What is a JACS Document?

A JACS document is a JSON object that includes:

• Identity: Unique ID and version tracking
• Metadata: Type, timestamps, and origin information
• Signature: Cryptographic proof of authenticity
• Hash: Integrity verification

Creating Documents

From a JSON File

Create a simple JSON document (my-document.json):

{
  "title": "Project Proposal",
  "description": "Q1 development plan",
  "budget": 50000,
  "deadline": "2024-03-31"
}

Sign it with JACS:

jacs document create -f my-document.json

This adds JACS headers and signature, producing a signed document.

From a Directory

Process multiple documents at once:

jacs document create -d ./documents/

With Custom Schema

Validate against a custom JSON schema:

jacs document create -f my-document.json -s ./schemas/proposal.schema.json

Output Options

# Save to specific file
jacs document create -f my-document.json -o ./output/signed-doc.json

# Print to stdout instead of saving
jacs document create -f my-document.json --no-save

# Verbose output
jacs document create -f my-document.json -v

Document Structure

After signing, a document looks like:

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "doc-uuid-here",
  "jacsVersion": "version-uuid-here",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "version-uuid-here",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsType": "document",
  "jacsLevel": "artifact",

  "title": "Project Proposal",
  "description": "Q1 development plan",
  "budget": 50000,
  "deadline": "2024-03-31",

  "jacsSha256": "a1b2c3d4...",
  "jacsSignature": {
    "agentID": "agent-uuid",
    "agentVersion": "agent-version-uuid",
    "signature": "base64-signature",
    "signingAlgorithm": "ring-Ed25519",
    "publicKeyHash": "hash-of-public-key",
    "date": "2024-01-15T10:30:00Z",
    "fields": ["jacsId", "title", "description", "budget", "deadline"]
  }
}

Required Header Fields

Document Levels

The jacsLevel field indicates the document's purpose:

File Attachments

Attach Files

# Attach a single file
jacs document create -f my-document.json --attach ./report.pdf

# Attach a directory of files
jacs document create -f my-document.json --attach ./attachments/

Embed vs. Reference

# Embed files directly in the document (larger document, self-contained)
jacs document create -f my-document.json --attach ./files/ --embed true

# Reference files (smaller document, files stored separately)
jacs document create -f my-document.json --attach ./files/ --embed false

Attachment Structure

Embedded attachments appear in the jacsFiles field:

{
  "jacsFiles": [
    {
      "jacsFileName": "report.pdf",
      "jacsFileMimeType": "application/pdf",
      "jacsFileSha256": "file-hash",
      "jacsFileContent": "base64-encoded-content"
    }
  ]
}

Verifying Documents

Basic Verification

jacs document verify -f ./signed-document.json

Verification checks:

1. Hash integrity (document hasn't been modified)
2. Signature validity (signature matches content)
3. Schema compliance (if schema specified)

Verify with Schema

jacs document verify -f ./document.json -s ./schema.json

Verify Directory

jacs document verify -d ./documents/

Verbose Output

jacs document verify -f ./document.json -v

Updating Documents

Updates create a new version while maintaining the same jacsId:

jacs document update -f ./original.json -n ./modified.json

The update process:

1. Reads the original document
2. Applies changes from the modified file
3. Increments jacsVersion
4. Links to previous version via jacsPreviousVersion
5. Re-signs with agent's key

Update with Attachments

jacs document update -f ./original.json -n ./modified.json --attach ./new-file.pdf

Extracting Embedded Content

Extract attachments from a document:

jacs document extract -f ./document-with-attachments.json

Extract from multiple documents:

jacs document extract -d ./documents/

Document Types

Task Documents

Tasks are specialized documents for work tracking:

jacs task create -n "Code Review" -d "Review PR #123"

See Task Schema for details.

Message Documents

Messages for agent communication:

{
  "$schema": "https://hai.ai/schemas/message/v1/message.schema.json",
  "jacsType": "message",
  "jacsMessageContent": "Hello, I've completed the task.",
  "jacsMessageReplyTo": "previous-message-uuid"
}

Custom Documents

Any JSON can be a JACS document. Create custom schemas:

{
  "$schema": "https://example.com/schemas/invoice.schema.json",
  "jacsType": "invoice",
  "invoiceNumber": "INV-001",
  "amount": 1000,
  "currency": "USD"
}

Version History

JACS tracks document history through version chains:

Version 1 (jacsOriginalVersion)
    ↓
Version 2 (jacsPreviousVersion → Version 1)
    ↓
Version 3 (jacsPreviousVersion → Version 2)
    ↓
Current Version

Each version is a complete document that can be independently verified.

Working with Multiple Agents

Different Agent Signs Document

# Use a specific agent's keys
jacs document create -f ./document.json -a ./other-agent.json

Verify Document from Unknown Agent

# Verify with strict DNS requirement
jacs document verify -f ./document.json --require-strict-dns

Best Practices

Document Design

1. Use appropriate levels: Match jacsLevel to document purpose
2. Include context: Add descriptive fields for human readability
3. Version control: Keep source files in git alongside JACS documents

Security

1. Verify before trusting: Always verify signatures
2. Check agent identity: Verify the signing agent
3. Validate schemas: Use custom schemas for strict validation

Performance

1. External attachments: Use --embed false for large files
2. Batch processing: Use directory mode for multiple documents
3. Selective verification: Verify only when needed

Common Workflows

Create and Share Document

# 1. Create document
jacs document create -f ./proposal.json -o ./signed-proposal.json

# 2. Share the signed document
# The recipient can verify it:
jacs document verify -f ./signed-proposal.json

Track Document Changes

# 1. Create initial version
jacs document create -f ./contract-v1.json

# 2. Make changes and update
jacs document update -f ./contract-v1.json -n ./contract-v2.json

# 3. Continue updating
jacs document update -f ./contract-v2.json -n ./contract-v3.json

Process Multiple Documents

# Create all documents in a directory
jacs document create -d ./input-docs/

# Verify all documents
jacs document verify -d ./signed-docs/

Next Steps

• Agreements - Multi-agent consent
• Task Schema - Task document structure
• Custom Schemas - Create your own schemas

Creating and Using Agreements

Agreements enable multi-party consent in JACS. They allow multiple agents to cryptographically sign a document, creating binding commitments between parties.

What is an Agreement?

An agreement is a mechanism for:

• Collecting signatures from multiple agents
• Tracking consent from required parties
• Enforcing completion before proceeding
• Creating audit trails of who agreed and when

Agreement Lifecycle

1. Create Agreement → 2. Distribute → 3. Agents Sign → 4. Verify Complete

1. Create: Initial agent creates agreement with required participants
2. Distribute: Agreement document shared with all parties
3. Sign: Each agent reviews and adds their signature
4. Verify: Check that all required parties have signed

Creating Agreements

Basic Agreement

# Create agreement requiring signatures from two agents
jacs document create-agreement \
  -f ./document.json \
  -i agent1-uuid,agent2-uuid

With Context

Include a question and context for clarity:

{
  "jacsAgreement": {
    "jacsAgreementQuestion": "Do you agree to the terms of this contract?",
    "jacsAgreementContext": "Service agreement for Q1 2024",
    "jacsAgreementAgents": ["agent1-uuid", "agent2-uuid"]
  }
}

Signing Agreements

Sign as Current Agent

jacs document sign-agreement -f ./document-with-agreement.json

Sign as Different Agent

# Use a different configuration/agent
JACS_CONFIG_PATH=./agent2.config.json jacs document sign-agreement -f ./document.json

Sign with Response

When signing, agents can include a response:

{
  "jacsAgreement": {
    "signatures": {
      "agent1-uuid": {
        "agentID": "agent1-uuid",
        "signature": "base64-signature",
        "date": "2024-01-15T10:30:00Z",
        "response": "Agreed with minor reservation about timeline",
        "responseType": "agree"
      }
    }
  }
}

Response types:

• agree - Agent consents
• disagree - Agent does not consent
• reject - Agent considers the question invalid or irrelevant

Checking Agreement Status

Check if Complete

jacs document check-agreement -f ./document.json

This shows:

• Which agents have signed
• Which agents still need to sign
• Whether the agreement is complete

Agreement Structure

A document with an agreement includes:

{
  "jacsId": "doc-uuid",
  "jacsType": "contract",

  "jacsAgreement": {
    "jacsAgreementQuestion": "Do you agree to these terms?",
    "jacsAgreementContext": "Annual service contract",
    "jacsAgreementAgents": [
      "550e8400-e29b-41d4-a716-446655440000",
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "signatures": {
      "550e8400-e29b-41d4-a716-446655440000": {
        "agentID": "550e8400-e29b-41d4-a716-446655440000",
        "agentVersion": "version-uuid",
        "signature": "base64-signature",
        "signingAlgorithm": "ring-Ed25519",
        "publicKeyHash": "hash",
        "date": "2024-01-15T10:30:00Z",
        "responseType": "agree",
        "fields": ["jacsId", "jacsAgreement"]
      }
    }
  },

  "jacsAgreementHash": "hash-of-agreement-content"
}

Task Agreements

Tasks have built-in support for start and end agreements:

{
  "jacsType": "task",
  "jacsTaskName": "Code Review",

  "jacsStartAgreement": {
    "jacsAgreementQuestion": "Do you agree to start this task?",
    "jacsAgreementAgents": ["customer-uuid", "provider-uuid"]
  },

  "jacsEndAgreement": {
    "jacsAgreementQuestion": "Do you agree the task is complete?",
    "jacsAgreementAgents": ["customer-uuid", "provider-uuid"]
  }
}

Multi-Agent Workflow Example

# 1. Agent A creates a task
jacs task create -n "Write Report" -d "Quarterly sales report"

# 2. Agent A adds agreement requiring both agents
jacs document create-agreement \
  -f ./task.json \
  -i agent-a-uuid,agent-b-uuid

# 3. Agent A signs the agreement
jacs document sign-agreement -f ./task.json

# 4. Agent B signs the agreement
JACS_CONFIG_PATH=./agent-b.config.json \
  jacs document sign-agreement -f ./task.json

# 5. Check agreement is complete
jacs document check-agreement -f ./task.json

Agreement Hash

The jacsAgreementHash ensures all agents agree to the same content:

1. Hash is computed from the agreement content
2. Each signature includes the hash
3. If content changes, hash changes, invalidating existing signatures

This prevents modifications after some parties have signed.

Best Practices

1. Verify before signing: Always review documents before signing
2. Check agent identities: Verify who you're agreeing with (use DNS)
3. Include context: Make the agreement purpose clear
4. Handle disagreement: Have a process for when agents disagree

Next Steps

• DNS Verification - Verify agent identities
• Task Schema - Task-specific agreements
• Security Model - Agreement security

DNS-Based Agent Verification

JACS supports DNS-based agent verification using DNS TXT records and DNSSEC. This allows agents to publish their identity in a decentralized, verifiable way that doesn't require a central authority.

Overview

DNS verification in JACS works by:

1. Publishing an agent's public key fingerprint as a DNS TXT record
2. Using DNSSEC to cryptographically verify the DNS response
3. Comparing the fingerprint from DNS with the agent's actual public key

This provides a secure, decentralized way to verify agent identity across the internet.

Why DNS Verification?

• Decentralized: No central authority required
• Existing Infrastructure: Uses established DNS infrastructure
• DNSSEC Security: Cryptographic verification of DNS responses
• Human-Readable: Agents can be identified by domain names
• Widely Supported: Works with any DNS provider

Publishing Agent Identity

Generate DNS Commands

# Generate DNS TXT record commands for your agent
jacs agent dns --domain myagent.example.com

# Specify agent ID explicitly
jacs agent dns --domain myagent.example.com --agent-id 550e8400-e29b-41d4-a716-446655440000

# Use hex encoding instead of base64
jacs agent dns --domain myagent.example.com --encoding hex

# Set custom TTL (time-to-live)
jacs agent dns --domain myagent.example.com --ttl 7200

Provider-Specific Formats

JACS can generate DNS commands for various providers:

# Plain text format (default)
jacs agent dns --domain myagent.example.com --provider plain

# AWS Route 53 format
jacs agent dns --domain myagent.example.com --provider aws

# Azure DNS format
jacs agent dns --domain myagent.example.com --provider azure

# Cloudflare DNS format
jacs agent dns --domain myagent.example.com --provider cloudflare

DNS Record Structure

The DNS TXT record follows this format:

_v1.agent.jacs.myagent.example.com. 3600 IN TXT "jacs-agent-fingerprint=<fingerprint>"

Where:

• _v1.agent.jacs. is the JACS-specific subdomain prefix
• <fingerprint> is the base64-encoded hash of the agent's public key

Setting Up with Route 53 (AWS)

1. Generate the AWS-formatted command:

jacs agent dns --domain myagent.example.com --provider aws

2. The output will include an AWS CLI command like:

aws route53 change-resource-record-sets \
  --hosted-zone-id YOUR_ZONE_ID \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "_v1.agent.jacs.myagent.example.com",
        "Type": "TXT",
        "TTL": 3600,
        "ResourceRecords": [{"Value": "\"jacs-agent-fingerprint=...\""}]
      }
    }]
  }'

3. Replace YOUR_ZONE_ID with your actual Route 53 hosted zone ID.

Setting Up with Cloudflare

1. Generate the Cloudflare-formatted command:

jacs agent dns --domain myagent.example.com --provider cloudflare

2. Or add manually in the Cloudflare dashboard:
   • Type: TXT
   • Name: _v1.agent.jacs
   • Content: jacs-agent-fingerprint=<your-fingerprint>
   • TTL: 3600

Setting Up with Azure DNS

1. Generate the Azure-formatted command:

jacs agent dns --domain myagent.example.com --provider azure

2. The output will include an Azure CLI command that you can run directly.

Verifying Agents with DNS

Look Up Another Agent

# Look up an agent by their domain
jacs agent lookup other-agent.example.com

# With strict DNSSEC validation
jacs agent lookup other-agent.example.com --strict

# Skip DNS verification (not recommended)
jacs agent lookup other-agent.example.com --no-dns

Verify Agent with DNS

When verifying an agent, you can specify DNS requirements:

# Default: Use DNS if available, but don't require it
jacs agent verify -a ./agent.json

# Require DNS validation (non-strict)
jacs agent verify -a ./agent.json --require-dns

# Require strict DNSSEC validation
jacs agent verify -a ./agent.json --require-strict-dns

# Disable DNS validation entirely
jacs agent verify -a ./agent.json --no-dns

# Ignore DNS (won't fail if DNS unavailable)
jacs agent verify -a ./agent.json --ignore-dns

DNS Validation Modes

Agent Domain Configuration

Agents can specify their domain in their agent document:

{
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsAgentType": "ai",
  "jacsAgentDomain": "myagent.example.com",
  "jacsServices": [...]
}

The jacsAgentDomain field is optional but enables DNS-based verification.

DNSSEC Requirements

For maximum security, enable DNSSEC on your domain:

1. Enable DNSSEC at your registrar: Most registrars support DNSSEC
2. Configure your DNS provider: Ensure your DNS provider signs zones
3. Use --require-strict-dns: Enforce DNSSEC validation

Checking DNSSEC Status

You can verify DNSSEC is working using standard tools:

# Check if DNSSEC is enabled
dig +dnssec _v1.agent.jacs.myagent.example.com TXT

# Verify DNSSEC validation
delv @8.8.8.8 _v1.agent.jacs.myagent.example.com TXT

Security Considerations

Trust Model

• With DNSSEC: Full cryptographic chain of trust from root DNS servers
• Without DNSSEC: Trust depends on DNS infrastructure security
• Local Only: Trust is limited to having the correct public key

Best Practices

1. Always enable DNSSEC for production agents
2. Use strict validation when verifying unknown agents
3. Rotate keys carefully - update DNS records before key changes
4. Monitor DNS records for unauthorized changes
5. Use short TTLs during transitions then increase for stability

Caching

DNS responses are cached based on TTL. Consider:

• Short TTL (300-600s): Better for development or key rotation
• Long TTL (3600-86400s): Better for production stability

Troubleshooting

"DNS record not found"

1. Verify the record exists:

dig _v1.agent.jacs.myagent.example.com TXT

2. Check DNS propagation (may take up to 48 hours for new records)

3. Verify the domain in the agent document matches

"DNSSEC validation failed"

1. Check DNSSEC is enabled:

dig +dnssec myagent.example.com

2. Verify DS records at registrar

3. Use --require-dns instead of --require-strict-dns if DNSSEC isn't available

"Fingerprint mismatch"

1. The public key may have changed - regenerate DNS record:

jacs agent dns --domain myagent.example.com

2. Update the DNS TXT record with the new fingerprint

3. Wait for DNS propagation

Integration with CI/CD

Automate DNS updates in your deployment pipeline:

#!/bin/bash
# deploy-agent.sh

# 1. Create new agent keys
jacs agent create --create-keys true

# 2. Generate DNS update command
DNS_CMD=$(jacs agent dns --domain $AGENT_DOMAIN --provider aws)

# 3. Execute DNS update
eval $DNS_CMD

# 4. Wait for propagation
sleep 60

# 5. Verify DNS is working
jacs agent verify --require-dns

Next Steps

• Creating an Agent - Set up agents with DNS domains
• Security Model - Deep dive into JACS security
• Agreements - Use DNS-verified agents in agreements

Rust Library API

JACS provides a Rust library for programmatic agent and document management. This chapter covers how to use the JACS library in your Rust applications.

Adding JACS as a Dependency

Add JACS to your Cargo.toml:

[dependencies]
jacs = "0.3"

Feature Flags

[dependencies]
jacs = { version = "0.3", features = ["cli", "observability"] }

Core Types

Agent

The Agent struct is the central type in JACS. It holds:

• Schema validators
• Agent identity and keys
• Document storage
• Configuration

use jacs::{get_empty_agent, load_agent};
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // Create a new empty agent
    let agent = get_empty_agent();

    // Or load an existing agent
    let agent = load_agent(Some("path/to/agent.json".to_string()))?;

    Ok(())
}

JACSDocument

Documents in JACS are represented by the JACSDocument struct:

#![allow(unused)]
fn main() {
pub struct JACSDocument {
    pub id: String,
    pub version: String,
    pub value: serde_json::Value,
    pub jacs_type: String,
}
}

Key methods:

• getkey() - Returns "id:version" identifier
• getvalue() - Returns reference to the JSON value
• getschema() - Returns the document's schema URL
• signing_agent() - Returns the ID of the signing agent

Creating an Agent

Minimal Agent

use jacs::{get_empty_agent, create_minimal_blank_agent};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create agent JSON
    let agent_json = create_minimal_blank_agent(
        "ai".to_string(),                    // agent type
        Some("My service".to_string()),      // service description
        Some("Task completed".to_string()),  // success description
        Some("Task failed".to_string()),     // failure description
    )?;

    // Initialize and load the agent
    let mut agent = get_empty_agent();
    agent.create_agent_and_load(&agent_json, true, None)?;

    // Save the agent
    agent.save()?;

    Ok(())
}

Loading by Configuration

use jacs::get_empty_agent;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut agent = get_empty_agent();

    // Load from config file
    agent.load_by_config("./jacs.config.json".to_string())?;

    // Or load by agent ID
    agent.load_by_id("agent-id:version-id".to_string())?;

    Ok(())
}

DNS Strict Mode

use jacs::load_agent_with_dns_strict;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load agent with strict DNS verification
    let agent = load_agent_with_dns_strict(
        "path/to/agent.json".to_string(),
        true  // strict mode
    )?;

    Ok(())
}

Working with Documents

Creating Documents

The DocumentTraits trait provides document operations:

use jacs::agent::document::DocumentTraits;
use jacs::get_empty_agent;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut agent = get_empty_agent();
    agent.load_by_config("./jacs.config.json".to_string())?;

    // Create a document from JSON
    let json = r#"{"title": "My Document", "content": "Hello, World!"}"#;
    let doc = agent.create_document_and_load(json, None, None)?;

    println!("Document created: {}", doc.getkey());

    Ok(())
}

Creating Documents with Attachments

#![allow(unused)]
fn main() {
use jacs::agent::document::DocumentTraits;

// With file attachments
let attachments = Some(vec!["./report.pdf".to_string()]);
let embed = Some(true);  // Embed files in document

let doc = agent.create_document_and_load(
    json,
    attachments,
    embed
)?;
}

Loading Documents

#![allow(unused)]
fn main() {
use jacs::agent::document::DocumentTraits;

// Load a document from JSON string
let doc = agent.load_document(&document_json_string)?;

// Get a stored document by key
let doc = agent.get_document("doc-id:version-id")?;

// List all document keys
let keys = agent.get_document_keys();
}

Updating Documents

#![allow(unused)]
fn main() {
use jacs::agent::document::DocumentTraits;

// Update creates a new version
let updated_doc = agent.update_document(
    "doc-id:version-id",    // original document key
    &modified_json_string,  // new content
    None,                   // optional attachments
    None,                   // embed flag
)?;
}

Verifying Documents

#![allow(unused)]
fn main() {
use jacs::agent::document::DocumentTraits;

// Verify document signature with agent's public key
agent.verify_document_signature(
    "doc-id:version-id",
    None,  // signature key (uses default)
    None,  // fields to verify
    None,  // public key (uses agent's)
    None,  // key encoding type
)?;

// Verify using external public key
agent.verify_external_document_signature("doc-id:version-id")?;
}

Saving Documents

#![allow(unused)]
fn main() {
use jacs::agent::document::DocumentTraits;

// Save document to filesystem
agent.save_document(
    "doc-id:version-id",
    Some("output.json".to_string()),  // output filename
    Some(true),                       // export embedded files
    None,                             // extract only
)?;
}

Creating Tasks

use jacs::{get_empty_agent, create_task};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut agent = get_empty_agent();
    agent.load_by_config("./jacs.config.json".to_string())?;

    // Create a task
    let task_json = create_task(
        &mut agent,
        "Review Code".to_string(),
        "Review pull request #123".to_string(),
    )?;

    println!("Task created: {}", task_json);

    Ok(())
}

Signing and Verification

Signing Documents

The agent's signing_procedure method creates cryptographic signatures:

#![allow(unused)]
fn main() {
use serde_json::json;

let document = json!({
    "title": "Contract",
    "terms": "..."
});

// Sign the document
let signature = agent.signing_procedure(
    &document,
    None,           // fields to sign (None = all)
    "jacsSignature" // placement key
)?;
}

Verification

#![allow(unused)]
fn main() {
// Verify self-signature (agent document)
agent.verify_self_signature()?;

// Verify hash integrity
agent.verify_hash(&document)?;

// Full signature verification
agent.signature_verification_procedure(
    &document,
    None,                    // fields
    "jacsSignature",         // signature key
    public_key,              // public key bytes
    Some("ring-Ed25519".to_string()),  // algorithm
    None,                    // original public key hash
    None,                    // signature override
)?;
}

Custom Schema Validation

#![allow(unused)]
fn main() {
// Load custom schemas
agent.load_custom_schemas(&[
    "./schemas/invoice.schema.json".to_string(),
    "https://example.com/schemas/contract.schema.json".to_string(),
])?;

// Validate document against custom schema
agent.validate_document_with_custom_schema(
    "./schemas/invoice.schema.json",
    &document_value,
)?;
}

Configuration

Loading Configuration

#![allow(unused)]
fn main() {
use jacs::config::{load_config, find_config, Config};

// Load from specific path
let config = load_config("./jacs.config.json")?;

// Find config in directory
let config = find_config("./".to_string())?;

// Create programmatically
let config = Config::new(
    Some("false".to_string()),           // use_security
    Some("./jacs_data".to_string()),     // data_directory
    Some("./jacs_keys".to_string()),     // key_directory
    Some("private_key.pem".to_string()), // private key filename
    Some("public_key.pem".to_string()),  // public key filename
    Some("ring-Ed25519".to_string()),    // key algorithm
    Some("password".to_string()),        // private key password
    None,                                // agent ID and version
    Some("fs".to_string()),              // storage type
);
}

Accessing Configuration

#![allow(unused)]
fn main() {
// Get key algorithm
let algorithm = config.get_key_algorithm()?;

// Access config fields
let data_dir = config.jacs_data_directory();
let key_dir = config.jacs_key_directory();
let storage_type = config.jacs_default_storage();
}

Observability

Initialize Default Observability

use jacs::init_default_observability;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Set up file-based logging
    init_default_observability()?;

    // Your application code...

    Ok(())
}

Custom Observability Configuration

use jacs::{
    init_custom_observability,
    ObservabilityConfig,
    LogConfig,
    LogDestination,
    MetricsConfig,
    MetricsDestination,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ObservabilityConfig {
        logs: LogConfig {
            enabled: true,
            level: "debug".to_string(),
            destination: LogDestination::Otlp {
                endpoint: "http://localhost:4317".to_string(),
                headers: None,
            },
            headers: None,
        },
        metrics: MetricsConfig {
            enabled: true,
            destination: MetricsDestination::Prometheus {
                endpoint: "http://localhost:9090".to_string(),
                headers: None,
            },
            export_interval_seconds: Some(30),
            headers: None,
        },
        tracing: None,
    };

    init_custom_observability(config)?;

    Ok(())
}

Storage Backends

JACS supports multiple storage backends:

#![allow(unused)]
fn main() {
use jacs::storage::MultiStorage;

// Filesystem storage (default)
let storage = MultiStorage::new("fs".to_string())?;

// In-memory storage
let storage = MultiStorage::new("memory".to_string())?;

// S3 storage
let storage = MultiStorage::new("s3".to_string())?;
}

Error Handling

JACS functions return Result<T, Box<dyn Error>>:

use jacs::get_empty_agent;

fn main() {
    match get_empty_agent().load_by_config("./jacs.config.json".to_string()) {
        Ok(()) => println!("Agent loaded successfully"),
        Err(e) => eprintln!("Failed to load agent: {}", e),
    }
}

Thread Safety

The Agent struct uses internal mutexes for thread-safe access to:

• Document schemas (Arc<Mutex<HashMap<String, Validator>>>)
• Storage operations

For concurrent usage:

#![allow(unused)]
fn main() {
use std::sync::{Arc, Mutex};
use jacs::get_empty_agent;

let agent = Arc::new(Mutex::new(get_empty_agent()));

// Clone Arc for threads
let agent_clone = Arc::clone(&agent);
std::thread::spawn(move || {
    let mut agent = agent_clone.lock().unwrap();
    // Use agent...
});
}

Complete Example

use jacs::{get_empty_agent, create_task};
use jacs::agent::document::DocumentTraits;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize agent
    let mut agent = get_empty_agent();
    agent.load_by_config("./jacs.config.json".to_string())?;

    // Create a document
    let doc_json = json!({
        "title": "Project Proposal",
        "description": "Q1 development plan",
        "budget": 50000
    });

    let doc = agent.create_document_and_load(
        &doc_json.to_string(),
        None,
        None
    )?;

    println!("Created document: {}", doc.getkey());

    // Verify the document
    agent.verify_document_signature(&doc.getkey(), None, None, None, None)?;
    println!("Document verified successfully");

    // Save to file
    agent.save_document(&doc.getkey(), Some("proposal.json".to_string()), None, None)?;

    // Create a task
    let task = create_task(
        &mut agent,
        "Review Proposal".to_string(),
        "Review and approve the project proposal".to_string(),
    )?;

    println!("Task created");

    Ok(())
}

Next Steps

• Observability - Logging and metrics setup
• Storage Backends - Configure different storage
• Custom Schemas - Define custom document types

Observability

JACS provides comprehensive observability features including logging, metrics, and distributed tracing. This chapter covers configuring and using these features in your applications.

Overview

JACS observability is built on the OpenTelemetry standard, providing:

• Logging: Structured logging with multiple destinations
• Metrics: Counters, gauges, and histograms for monitoring
• Tracing: Distributed tracing for request flows

Feature Flags

Enable observability features in your Cargo.toml:

[dependencies]
jacs = { version = "0.3", features = ["observability"] }

Quick Start

Default Configuration

The simplest way to enable observability:

use jacs::init_default_observability;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_default_observability()?;

    // Your application code...

    Ok(())
}

This sets up:

• File-based logging to ./logs/ with daily rotation
• Metrics disabled by default
• Tracing disabled by default

Custom Configuration

For more control, use init_custom_observability:

use jacs::{
    init_custom_observability,
    ObservabilityConfig,
    LogConfig,
    LogDestination,
    MetricsConfig,
    MetricsDestination,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ObservabilityConfig {
        logs: LogConfig {
            enabled: true,
            level: "info".to_string(),
            destination: LogDestination::Stderr,
            headers: None,
        },
        metrics: MetricsConfig {
            enabled: false,
            destination: MetricsDestination::Stdout,
            export_interval_seconds: None,
            headers: None,
        },
        tracing: None,
    };

    init_custom_observability(config)?;
    Ok(())
}

Logging

Log Levels

Supported log levels (from most to least verbose):

• trace
• debug
• info
• warn
• error

Log Destinations

Stderr (Default)

#![allow(unused)]
fn main() {
LogDestination::Stderr
}

Logs to standard error. Useful for development and containerized environments.

File

#![allow(unused)]
fn main() {
LogDestination::File {
    path: "./logs".to_string(),
}
}

Logs to rotating files with daily rotation. Creates files like app.log.2024-01-15.

OTLP

#![allow(unused)]
fn main() {
LogDestination::Otlp {
    endpoint: "http://localhost:4318".to_string(),
    headers: None,
}
}

Exports logs via OpenTelemetry Protocol. Requires otlp-logs feature.

Null

#![allow(unused)]
fn main() {
LogDestination::Null
}

Disables logging completely.

Using Logs

JACS uses the tracing crate for logging:

#![allow(unused)]
fn main() {
use tracing::{info, debug, warn, error};

fn process_document() {
    info!("Processing document");
    debug!("Document details: {:?}", doc);

    if let Err(e) = verify() {
        error!("Verification failed: {}", e);
    }
}
}

Metrics

Enabling Metrics

#![allow(unused)]
fn main() {
MetricsConfig {
    enabled: true,
    destination: MetricsDestination::Otlp {
        endpoint: "http://localhost:4318".to_string(),
        headers: None,
    },
    export_interval_seconds: Some(30),
    headers: None,
}
}

Metrics Destinations

OTLP

#![allow(unused)]
fn main() {
MetricsDestination::Otlp {
    endpoint: "http://localhost:4318".to_string(),
    headers: None,
}
}

Exports to an OpenTelemetry collector. Requires otlp-metrics feature.

Prometheus (via Collector)

#![allow(unused)]
fn main() {
MetricsDestination::Prometheus {
    endpoint: "http://localhost:9090".to_string(),
    headers: None,
}
}

Note: Direct Prometheus export requires routing through an OTLP collector.

File

#![allow(unused)]
fn main() {
MetricsDestination::File {
    path: "./metrics.txt".to_string(),
}
}

Writes metrics to a file.

Stdout

#![allow(unused)]
fn main() {
MetricsDestination::Stdout
}

Prints metrics to standard output. Useful for testing.

Recording Metrics

JACS provides convenience functions for common metrics:

#![allow(unused)]
fn main() {
use jacs::observability::metrics::{increment_counter, set_gauge, record_histogram};
use std::collections::HashMap;

// Increment a counter
let mut tags = HashMap::new();
tags.insert("operation".to_string(), "sign".to_string());
increment_counter("jacs_operations_total", 1, Some(tags));

// Set a gauge value
set_gauge("jacs_documents_active", 42.0, None);

// Record a histogram value (e.g., latency)
let mut tags = HashMap::new();
tags.insert("method".to_string(), "verify".to_string());
record_histogram("jacs_operation_duration_ms", 150.0, Some(tags));
}

Built-in Metrics

When observability-convenience feature is enabled, JACS automatically records:

• jacs_agent_operations - Count of agent operations
• jacs_signature_verifications - Signature verification results
• jacs_document_operations - Document create/update/verify counts

Distributed Tracing

Enabling Tracing

#![allow(unused)]
fn main() {
use jacs::{TracingConfig, TracingDestination, SamplingConfig, ResourceConfig};
use std::collections::HashMap;

let config = ObservabilityConfig {
    // ... logs and metrics config ...
    tracing: Some(TracingConfig {
        enabled: true,
        sampling: SamplingConfig {
            ratio: 1.0,           // Sample all traces
            parent_based: true,
            rate_limit: None,
        },
        resource: Some(ResourceConfig {
            service_name: "my-jacs-app".to_string(),
            service_version: Some("1.0.0".to_string()),
            environment: Some("production".to_string()),
            attributes: HashMap::new(),
        }),
        destination: Some(TracingDestination::Otlp {
            endpoint: "http://localhost:4318".to_string(),
            headers: None,
        }),
    }),
};
}

Tracing Destinations

OTLP

#![allow(unused)]
fn main() {
TracingDestination::Otlp {
    endpoint: "http://localhost:4318".to_string(),
    headers: None,
}
}

Jaeger

#![allow(unused)]
fn main() {
TracingDestination::Jaeger {
    endpoint: "http://localhost:14268/api/traces".to_string(),
    headers: None,
}
}

Sampling Configuration

Control how many traces are captured:

#![allow(unused)]
fn main() {
SamplingConfig {
    ratio: 0.1,          // Sample 10% of traces
    parent_based: true,  // Inherit parent sampling decision
    rate_limit: Some(100), // Max 100 samples per second
}
}

Using Tracing Spans

#![allow(unused)]
fn main() {
use tracing::{instrument, info_span};

#[instrument]
fn sign_document(doc: &Document) -> Result<(), Error> {
    // Automatically creates a span named "sign_document"
    // with doc as a field
}

fn manual_span() {
    let span = info_span!("verify_chain", doc_count = 5);
    let _guard = span.enter();

    // Operations within this span
}
}

Configuration File

You can configure observability via jacs.config.json:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  "jacs_agent_key_algorithm": "ring-Ed25519",
  "observability": {
    "logs": {
      "enabled": true,
      "level": "info",
      "destination": {
        "file": {
          "path": "./logs"
        }
      }
    },
    "metrics": {
      "enabled": true,
      "destination": {
        "otlp": {
          "endpoint": "http://localhost:4318"
        }
      },
      "export_interval_seconds": 30
    },
    "tracing": {
      "enabled": true,
      "sampling": {
        "ratio": 1.0,
        "parent_based": true
      },
      "resource": {
        "service_name": "jacs-service",
        "service_version": "1.0.0",
        "environment": "production"
      },
      "destination": {
        "otlp": {
          "endpoint": "http://localhost:4318"
        }
      }
    }
  }
}

OpenTelemetry Collector Setup

For production use, route telemetry through an OpenTelemetry Collector:

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  logging:
    loglevel: debug
  prometheus:
    endpoint: "0.0.0.0:9090"
  jaeger:
    endpoint: jaeger:14250

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]

Reset and Cleanup

For testing or reinitialization:

#![allow(unused)]
fn main() {
use jacs::observability::{reset_observability, flush_observability, force_reset_for_tests};

// Flush pending data
flush_observability();

// Reset configuration
reset_observability();

// Force reset for tests (clears all state)
force_reset_for_tests();
}

Best Practices

Development

#![allow(unused)]
fn main() {
let config = ObservabilityConfig {
    logs: LogConfig {
        enabled: true,
        level: "debug".to_string(),
        destination: LogDestination::Stderr,
        headers: None,
    },
    metrics: MetricsConfig {
        enabled: false,
        destination: MetricsDestination::Stdout,
        export_interval_seconds: None,
        headers: None,
    },
    tracing: None,
};
}

Production

#![allow(unused)]
fn main() {
let config = ObservabilityConfig {
    logs: LogConfig {
        enabled: true,
        level: "info".to_string(),
        destination: LogDestination::Otlp {
            endpoint: "http://collector:4318".to_string(),
            headers: Some(auth_headers()),
        },
        headers: None,
    },
    metrics: MetricsConfig {
        enabled: true,
        destination: MetricsDestination::Otlp {
            endpoint: "http://collector:4318".to_string(),
            headers: Some(auth_headers()),
        },
        export_interval_seconds: Some(30),
        headers: None,
    },
    tracing: Some(TracingConfig {
        enabled: true,
        sampling: SamplingConfig {
            ratio: 0.1,  // Sample 10% in production
            parent_based: true,
            rate_limit: Some(1000),
        },
        resource: Some(ResourceConfig {
            service_name: "jacs-production".to_string(),
            service_version: Some(env!("CARGO_PKG_VERSION").to_string()),
            environment: Some("production".to_string()),
            attributes: HashMap::new(),
        }),
        destination: Some(TracingDestination::Otlp {
            endpoint: "http://collector:4318".to_string(),
            headers: Some(auth_headers()),
        }),
    }),
};
}

Troubleshooting

Logs Not Appearing

1. Check that logging is enabled: logs.enabled: true
2. Verify log level includes your log statements
3. For file logging, ensure the directory is writable

Metrics Not Exporting

1. Verify otlp-metrics feature is enabled
2. Check endpoint connectivity
3. Confirm metrics are enabled: metrics.enabled: true

Traces Missing

1. Verify otlp-tracing feature is enabled
2. Check sampling ratio isn't filtering all traces
3. Ensure spans are properly instrumented

Next Steps

• Rust Library API - Use observability in your code
• Configuration Reference - Full config options
• Advanced Topics - Security considerations

Node.js Installation

The JACS Node.js package (jacsnpm) 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 jacsnpm

Using yarn

yarn add jacsnpm

Using pnpm

pnpm add jacsnpm

Verify Installation

Create a simple test to verify everything is working:

// test.js
import { JacsAgent } from 'jacsnpm';

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

// Test basic functionality
try {
  const agent = new JacsAgent();
  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 jacsnpm package includes several modules:

Core Module (jacsnpm)

import { 
  JacsAgent,
  JacsConfig,
  JacsDocument,
  JacsError
} from 'jacsnpm';

MCP Integration (jacsnpm/mcp)

import { 
  JacsMcpServer,
  createJacsMiddleware 
} from 'jacsnpm/mcp';

HTTP Server (jacsnpm/http)

import { 
  JacsHttpServer,
  createJacsRouter 
} from 'jacsnpm/http';

TypeScript Support

The package includes full TypeScript definitions:

import { JacsAgent, createConfig, hashString } from 'jacsnpm';

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

// Load configuration from file
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 'jacsnpm';

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"
}

S3 Storage

{
  "jacs_default_storage": "s3"
}

S3 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": {
    "jacsnpm": "^0.1.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 'jacsnpm';

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

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

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

// Verify the document
const isValid = agent.verifyDocument(signedDoc);
console.log('Document valid:', isValid);

console.log('JACS agent ready!');

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 jacsnpm
npm install jacsnpm

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:

1. Basic Usage - Learn core JACS operations
2. MCP Integration - Add Model Context Protocol support
3. HTTP Server - Create JACS HTTP APIs
4. Express Middleware - Integrate with Express.js
5. 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

Basic Usage

This chapter covers fundamental JACS operations in Node.js, including agent initialization, document creation, signing, and verification.

Initializing an Agent

Create and Load Agent

import { JacsAgent } from 'jacsnpm';

// Create a new agent instance
const agent = new JacsAgent();

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

Configuration File

Create jacs.config.json:

{
  "$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",
  "jacs_agent_id_and_version": "agent-uuid:version-uuid"
}

Creating Documents

Basic Document Creation

import { JacsAgent } from 'jacsnpm';

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

// Create a document from JSON
const documentData = {
  title: "Project Proposal",
  content: "Quarterly development plan",
  budget: 50000
};

const signedDocument = agent.createDocument(JSON.stringify(documentData));
console.log('Signed document:', signedDocument);

With Custom Schema

Validate against a custom JSON Schema:

const signedDocument = agent.createDocument(
  JSON.stringify(documentData),
  './schemas/proposal.schema.json'  // custom schema path
);

With Output File

const signedDocument = agent.createDocument(
  JSON.stringify(documentData),
  null,                    // no custom schema
  './output/proposal.json' // output filename
);

Without Saving

const signedDocument = agent.createDocument(
  JSON.stringify(documentData),
  null,   // no custom schema
  null,   // no output filename
  true    // noSave = true
);

With Attachments

const signedDocument = agent.createDocument(
  JSON.stringify(documentData),
  null,                      // no custom schema
  null,                      // no output filename
  false,                     // save the document
  './attachments/report.pdf', // attachment path
  true                       // embed files
);

Verifying Documents

Verify Document Signature

// Verify a document's signature and hash
const isValid = agent.verifyDocument(signedDocumentJson);
console.log('Document valid:', isValid);

Verify Specific Signature Field

// Verify with a custom signature field
const isValid = agent.verifySignature(
  signedDocumentJson,
  'jacsSignature'  // signature field name
);

Updating Documents

Update Existing Document

// Original document key format: "id:version"
const documentKey = 'doc-uuid:version-uuid';

// Modified document content
const updatedData = {
  jacsId: 'doc-uuid',
  jacsVersion: 'version-uuid',
  title: "Updated Proposal",
  content: "Revised quarterly plan",
  budget: 75000
};

const updatedDocument = agent.updateDocument(
  documentKey,
  JSON.stringify(updatedData)
);

console.log('Updated document:', updatedDocument);

Update with New Attachments

const updatedDocument = agent.updateDocument(
  documentKey,
  JSON.stringify(updatedData),
  ['./new-report.pdf'],  // new attachments
  true                   // embed files
);

Signing and Verification

Sign Arbitrary Data

// Sign any string data
const signature = agent.signString('Important message to sign');
console.log('Signature:', signature);

Verify Arbitrary Data

// Verify a signature on string data
const isValid = agent.verifyString(
  'Important message to sign',  // original data
  signatureBase64,              // base64 signature
  publicKeyBuffer,              // public key as Buffer
  'ring-Ed25519'                // algorithm
);

Working with Agreements

Create an Agreement

// Add agreement requiring multiple agent signatures
const documentWithAgreement = agent.createAgreement(
  signedDocumentJson,
  ['agent1-uuid', 'agent2-uuid'],           // required signers
  'Do you agree to these terms?',            // question
  'Q1 2024 service contract',                // context
  'jacsAgreement'                            // field name
);

Sign an Agreement

// Sign the agreement as the current agent
const signedAgreement = agent.signAgreement(
  documentWithAgreementJson,
  'jacsAgreement'  // agreement field name
);

Check Agreement Status

// Check which agents have signed
const status = agent.checkAgreement(
  documentWithAgreementJson,
  'jacsAgreement'
);

console.log('Agreement status:', JSON.parse(status));

Agent Operations

Verify Agent

// Verify the loaded agent's signature
const isValid = agent.verifyAgent();
console.log('Agent valid:', isValid);

// Verify a specific agent file
const isValidOther = agent.verifyAgent('./other-agent.json');

Update Agent

// Update agent document
const updatedAgentJson = agent.updateAgent(JSON.stringify({
  jacsId: 'agent-uuid',
  jacsVersion: 'version-uuid',
  name: 'Updated Agent Name',
  description: 'Updated description'
}));

Sign External Agent

// Sign another agent's document with registration signature
const signedAgentJson = agent.signAgent(
  externalAgentJson,
  publicKeyBuffer,
  'ring-Ed25519'
);

Request/Response Signing

Sign a Request

// Sign request parameters as a JACS document
const signedRequest = agent.signRequest({
  method: 'GET',
  path: '/api/resource',
  timestamp: new Date().toISOString(),
  body: { query: 'data' }
});

Verify a Response

// Verify a signed response
const result = agent.verifyResponse(signedResponseJson);
console.log('Response valid:', result);

// Verify and get signer's agent ID
const resultWithId = agent.verifyResponseWithAgentId(signedResponseJson);
console.log('Signer ID:', resultWithId);

Utility Functions

Hash String

import { hashString } from 'jacsnpm';

// SHA-256 hash of a string
const hash = hashString('data to hash');
console.log('Hash:', hash);

Create Configuration

import { createConfig } from 'jacsnpm';

// Programmatically create a config JSON string
const configJson = createConfig(
  undefined,            // jacs_use_security
  './jacs_data',        // jacs_data_directory
  './jacs_keys',        // jacs_key_directory
  undefined,            // private key filename
  undefined,            // public key filename
  'ring-Ed25519',       // key algorithm
  undefined,            // private key password
  undefined,            // agent id and version
  'fs'                  // default storage
);

console.log('Config:', configJson);

Error Handling

import { JacsAgent } from 'jacsnpm';

const agent = new JacsAgent();

try {
  agent.load('./jacs.config.json');
} catch (error) {
  console.error('Failed to load agent:', error.message);
}

try {
  const doc = agent.createDocument(JSON.stringify({ data: 'test' }));
  console.log('Document created');
} catch (error) {
  console.error('Failed to create document:', error.message);
}

try {
  const isValid = agent.verifyDocument(invalidJson);
} catch (error) {
  console.error('Verification failed:', error.message);
}

Complete Example

import { JacsAgent, hashString } from 'jacsnpm';

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

  // Create a task document
  const task = {
    title: 'Code Review',
    description: 'Review pull request #123',
    assignee: 'developer-uuid',
    deadline: '2024-02-01'
  };

  const signedTask = agent.createDocument(JSON.stringify(task));
  console.log('Task created');

  // Verify the task
  if (agent.verifyDocument(signedTask)) {
    console.log('Task signature valid');
  }

  // Create agreement for task acceptance
  const taskWithAgreement = agent.createAgreement(
    signedTask,
    ['manager-uuid', 'developer-uuid'],
    'Do you accept this task assignment?'
  );

  // Sign the agreement
  const signedAgreement = agent.signAgreement(taskWithAgreement);
  console.log('Agreement signed');

  // Check agreement status
  const status = agent.checkAgreement(signedAgreement);
  console.log('Status:', status);

  // Hash some data for reference
  const taskHash = hashString(signedTask);
  console.log('Task hash:', taskHash);
}

main().catch(console.error);

Next Steps

• MCP Integration - Model Context Protocol support
• HTTP Server - Create HTTP APIs
• Express Middleware - Express.js integration
• API Reference - Complete API documentation

Model Context Protocol (MCP) Integration

JACS provides native integration with the Model Context Protocol (MCP), enabling secure agent communication within AI systems. JACS uses a transport proxy pattern that wraps any MCP transport with cryptographic signing and verification.

What is MCP?

Model Context Protocol is a standard for AI models to securely access external tools, data, and services. JACS enhances MCP by adding:

• Cryptographic verification of all messages
• Agent identity for all operations
• Transparent encryption of MCP JSON-RPC traffic
• Audit trails of all MCP interactions

How JACS MCP Works

JACS provides a transport proxy that sits between your MCP server/client and the underlying transport (STDIO, SSE, WebSocket). The proxy:

1. Outgoing messages: Signs JSON-RPC messages with the JACS agent's key using signRequest()
2. Incoming messages: Verifies signatures using verifyResponse() and extracts the payload
3. Fallback: If verification fails, passes messages through as plain JSON (graceful degradation)

Quick Start

Basic MCP Server with JACS

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';
import { z } from 'zod';

const JACS_CONFIG_PATH = "./jacs.config.json";

async function main() {
  // Create the base STDIO transport
  const baseTransport = new StdioServerTransport();

  // Wrap with JACS encryption
  const secureTransport = createJACSTransportProxy(
    baseTransport,
    JACS_CONFIG_PATH,
    "server"
  );

  // Create MCP server
  const server = new McpServer({
    name: "my-jacs-server",
    version: "1.0.0"
  });

  // Register tools
  server.tool("add", {
    a: z.number().describe("First number"),
    b: z.number().describe("Second number")
  }, async ({ a, b }) => {
    return { content: [{ type: "text", text: `${a} + ${b} = ${a + b}` }] };
  });

  // Connect with JACS encryption
  await server.connect(secureTransport);
  console.error("JACS MCP Server running with encryption enabled");
}

main();

MCP Client with JACS

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';

const JACS_CONFIG_PATH = "./jacs.config.json";

async function main() {
  // Create base transport to connect to MCP server
  const baseTransport = new StdioClientTransport({
    command: 'node',
    args: ['my-jacs-server.js']
  });

  // Wrap with JACS encryption
  const secureTransport = createJACSTransportProxy(
    baseTransport,
    JACS_CONFIG_PATH,
    "client"
  );

  // Create MCP client
  const client = new Client({
    name: "my-jacs-client",
    version: "1.0.0"
  }, {
    capabilities: {
      tools: {}
    }
  });

  // Connect with JACS encryption
  await client.connect(secureTransport);

  // List available tools
  const tools = await client.listTools();
  console.log('Available tools:', tools.tools.map(t => t.name));

  // Call a tool (message will be JACS-signed)
  const result = await client.callTool({
    name: "add",
    arguments: { a: 5, b: 3 }
  });

  console.log('Result:', result.content);
}

main();

API Reference

JACSTransportProxy

The main class that wraps MCP transports with JACS encryption.

import { JACSTransportProxy } from 'jacsnpm/mcp';

const proxy = new JACSTransportProxy(
  transport,      // Any MCP transport (Stdio, SSE, WebSocket)
  role,           // "server" or "client"
  jacsConfigPath  // Path to jacs.config.json
);

createJACSTransportProxy

Factory function for creating a transport proxy.

import { createJACSTransportProxy } from 'jacsnpm/mcp';

const secureTransport = createJACSTransportProxy(
  baseTransport,    // The underlying MCP transport
  configPath,       // Path to jacs.config.json
  role              // "server" or "client"
);

createJACSTransportProxyAsync

Async factory that waits for JACS to be fully loaded before returning.

import { createJACSTransportProxyAsync } from 'jacsnpm/mcp';

const secureTransport = await createJACSTransportProxyAsync(
  baseTransport,
  configPath,
  role
);

Transport Options

STDIO Transport

Best for CLI tools and subprocess communication:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';

const baseTransport = new StdioServerTransport();
const secureTransport = createJACSTransportProxy(
  baseTransport,
  "./jacs.config.json",
  "server"
);

Important: When using STDIO transport, all debug logging goes to stderr to keep stdout clean for JSON-RPC messages.

SSE Transport (HTTP)

For web-based MCP servers:

import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';
import express from 'express';

const app = express();

app.get('/sse', (req, res) => {
  const baseTransport = new SSEServerTransport('/messages', res);
  const secureTransport = createJACSTransportProxy(
    baseTransport,
    "./jacs.config.json",
    "server"
  );

  // Connect your MCP server to secureTransport
  server.connect(secureTransport);
});

// Handle POST messages with JACS decryption
app.post('/messages', express.text(), async (req, res) => {
  await secureTransport.handlePostMessage(req, res, req.body);
});

app.listen(3000);

Configuration

JACS Config File

Create a jacs.config.json for your MCP server/client:

{
  "$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",
  "jacs_agent_id_and_version": "agent-uuid:version-uuid"
}

Environment Variables

Enable debug logging (not recommended for STDIO):

export JACS_MCP_DEBUG=true

How Messages Are Signed

Outgoing Messages

When the MCP SDK sends a message, the proxy intercepts it and:

1. Serializes the JSON-RPC message
2. Calls jacs.signRequest(message) to create a JACS artifact
3. Sends the signed artifact to the transport

// Original MCP message
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "add", "arguments": { "a": 5, "b": 3 } }
}

// Becomes a JACS-signed artifact with jacsId, jacsSignature, etc.

Incoming Messages

When the transport receives a message, the proxy:

1. Attempts to verify it as a JACS artifact using jacs.verifyResponse()
2. If valid, extracts the original JSON-RPC payload
3. If not valid JACS, parses as plain JSON (fallback mode)
4. Passes the clean message to the MCP SDK

Complete Example

Server (mcp.server.js)

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';
import { z } from 'zod';

async function main() {
  console.error("JACS MCP Server starting...");

  // Create transport with JACS encryption
  const baseTransport = new StdioServerTransport();
  const secureTransport = createJACSTransportProxy(
    baseTransport,
    "./jacs.server.config.json",
    "server"
  );

  // Create MCP server
  const server = new McpServer({
    name: "jacs-demo-server",
    version: "1.0.0"
  });

  // Register tools
  server.tool("echo", {
    message: z.string().describe("Message to echo")
  }, async ({ message }) => {
    console.error(`Echo called with: ${message}`);
    return { content: [{ type: "text", text: `Echo: ${message}` }] };
  });

  server.tool("add", {
    a: z.number().describe("First number"),
    b: z.number().describe("Second number")
  }, async ({ a, b }) => {
    console.error(`Add called with: ${a}, ${b}`);
    return { content: [{ type: "text", text: `Result: ${a + b}` }] };
  });

  // Register resources
  server.resource(
    "server-info",
    "info://server",
    async (uri) => ({
      contents: [{
        uri: uri.href,
        text: "JACS-secured MCP Server",
        mimeType: "text/plain"
      }]
    })
  );

  // Connect
  await server.connect(secureTransport);
  console.error("Server running with JACS encryption");
}

main().catch(err => {
  console.error("Fatal error:", err);
  process.exit(1);
});

Client (mcp.client.js)

#!/usr/bin/env node
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { createJACSTransportProxy } from 'jacsnpm/mcp';

async function main() {
  console.log("JACS MCP Client starting...");

  // Connect to the server
  const baseTransport = new StdioClientTransport({
    command: 'node',
    args: ['mcp.server.js']
  });

  const secureTransport = createJACSTransportProxy(
    baseTransport,
    "./jacs.client.config.json",
    "client"
  );

  const client = new Client({
    name: "jacs-demo-client",
    version: "1.0.0"
  }, {
    capabilities: { tools: {} }
  });

  await client.connect(secureTransport);
  console.log("Connected to JACS MCP Server");

  // List tools
  const tools = await client.listTools();
  console.log("Available tools:", tools.tools.map(t => t.name));

  // Call echo tool
  const echoResult = await client.callTool({
    name: "echo",
    arguments: { message: "Hello, JACS!" }
  });
  console.log("Echo result:", echoResult.content[0].text);

  // Call add tool
  const addResult = await client.callTool({
    name: "add",
    arguments: { a: 10, b: 20 }
  });
  console.log("Add result:", addResult.content[0].text);

  await client.close();
}

main().catch(console.error);

Security Considerations

Message Verification

All JACS-signed messages include:

• jacsId - Unique document identifier
• jacsVersion - Version tracking
• jacsSignature - Cryptographic signature
• jacsHash - Content hash for integrity

Passthrough Mode

If JACS cannot verify an incoming message, it falls back to plain JSON parsing. This allows:

• Gradual migration to JACS-secured communication
• Interoperability with non-JACS MCP clients/servers

To require JACS verification (no fallback), implement custom validation in your tools.

Key Management

Each MCP server and client needs its own JACS agent with:

• Unique agent ID
• Private/public key pair
• Configuration file

Debugging

Enable Debug Logging

export JACS_MCP_DEBUG=true

This outputs detailed logs about message signing and verification.

STDIO Debug Note

For STDIO transports, debug logs go to stderr to prevent contaminating the JSON-RPC stream on stdout.

Common Issues

"JACS not operational": Check that your config file path is correct and the agent is properly initialized.

Verification failures: Ensure both server and client are using compatible JACS versions and valid keys.

Empty responses: The proxy removes null values from messages to prevent MCP schema validation issues.

Next Steps

• HTTP Server - Create HTTP APIs with JACS
• Express Middleware - Integrate with Express.js
• API Reference - Complete API documentation

HTTP Server

JACS provides middleware and utilities for building HTTP servers with cryptographic request/response signing. This enables secure communication between JACS agents over HTTP.

Overview

JACS HTTP integration provides:

• Request signing: Sign outgoing HTTP requests with your agent's key
• Request verification: Verify incoming requests were signed by a valid agent
• Response signing: Automatically sign responses before sending
• Response verification: Verify server responses on the client side
• Framework middleware: Ready-to-use middleware for Express and Koa

Core Concepts

Request/Response Flow

Client                          Server
  |                               |
  |-- signRequest(payload) -----> |
  |                               |-- verifyResponse() --> payload
  |                               |-- process payload
  |                               |-- signResponse(result)
  |<-- verifyResponse(result) ---|
  |

All messages are cryptographically signed, ensuring:

• Message integrity (no tampering)
• Agent identity (verified sender)
• Non-repudiation (proof of origin)

HTTP Client

Basic Client Usage

import jacs from 'jacsnpm';
import http from 'http';

async function main() {
  // Load JACS agent
  await jacs.load('./jacs.config.json');

  // Prepare payload
  const payload = {
    message: "Hello, secure server!",
    data: { id: 123, value: "some data" },
    timestamp: new Date().toISOString()
  };

  // Sign the request
  const signedRequest = await jacs.signRequest(payload);

  // Send HTTP request
  const response = await sendRequest(signedRequest, 'localhost', 3000, '/api/echo');

  // Verify the response
  const verifiedResponse = await jacs.verifyResponse(response);
  console.log('Verified payload:', verifiedResponse.payload);
}

function sendRequest(body, host, port, path) {
  return new Promise((resolve, reject) => {
    const options = {
      hostname: host,
      port: port,
      path: path,
      method: 'POST',
      headers: {
        'Content-Type': 'text/plain',
        'Content-Length': Buffer.byteLength(body),
      },
    };

    const req = http.request(options, (res) => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(data);
        } else {
          reject(new Error(`HTTP ${res.statusCode}: ${data}`));
        }
      });
    });

    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

main();

Using Fetch

import jacs from 'jacsnpm';

async function sendJacsRequest(url, payload) {
  await jacs.load('./jacs.config.json');

  // Sign the payload
  const signedRequest = await jacs.signRequest(payload);

  // Send request
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'text/plain' },
    body: signedRequest
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  // Verify response
  const responseText = await response.text();
  const verified = await jacs.verifyResponse(responseText);

  return verified.payload;
}

// Usage
const result = await sendJacsRequest('http://localhost:3000/api/data', {
  action: 'fetch',
  query: { id: 42 }
});

Express Server

Using Express Middleware

JACS provides JACSExpressMiddleware that automatically:

• Verifies incoming JACS requests
• Attaches the verified payload to req.jacsPayload
• Signs outgoing responses when you call res.send() with an object

import express from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const app = express();
const PORT = 3000;

// IMPORTANT: Use express.text() BEFORE JACS middleware
// This ensures req.body is a string for JACS verification
app.use('/api', express.text({ type: '*/*' }));

// Apply JACS middleware to API routes
app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.server.config.json'
}));

// Route handler
app.post('/api/echo', (req, res) => {
  // Access verified payload from req.jacsPayload
  const payload = req.jacsPayload;

  if (!payload) {
    return res.status(400).send('JACS payload missing');
  }

  console.log('Received verified payload:', payload);

  // Send response object - middleware will sign it automatically
  res.send({
    echo: "Server says hello!",
    received: payload,
    timestamp: new Date().toISOString()
  });
});

app.listen(PORT, () => {
  console.log(`JACS Express server listening on port ${PORT}`);
});

Middleware Configuration

JACSExpressMiddleware({
  configPath: './jacs.config.json'  // Required: path to JACS config
})

Manual Request/Response Handling

For more control, you can handle signing manually:

import express from 'express';
import jacs from 'jacsnpm';

const app = express();

// Initialize JACS once at startup
await jacs.load('./jacs.config.json');

app.use(express.text({ type: '*/*' }));

app.post('/api/process', async (req, res) => {
  try {
    // Manually verify incoming request
    const verified = await jacs.verifyResponse(req.body);
    const payload = verified.payload;

    // Process the request
    const result = {
      success: true,
      data: processData(payload),
      timestamp: new Date().toISOString()
    };

    // Manually sign the response
    const signedResponse = await jacs.signResponse(result);
    res.type('text/plain').send(signedResponse);

  } catch (error) {
    console.error('JACS verification failed:', error);
    res.status(400).send('Invalid JACS request');
  }
});

Koa Server

Using Koa Middleware

import Koa from 'koa';
import { JACSKoaMiddleware } from 'jacsnpm/http';

const app = new Koa();
const PORT = 3000;

// Apply JACS Koa middleware
// Handles raw body reading, verification, and response signing
app.use(JACSKoaMiddleware({
  configPath: './jacs.server.config.json'
}));

// Route handler
app.use(async (ctx) => {
  if (ctx.path === '/api/echo' && ctx.method === 'POST') {
    // Access verified payload from ctx.state.jacsPayload or ctx.jacsPayload
    const payload = ctx.state.jacsPayload || ctx.jacsPayload;

    if (!payload) {
      ctx.status = 400;
      ctx.body = 'JACS payload missing';
      return;
    }

    console.log('Received verified payload:', payload);

    // Set response object - middleware will sign it automatically
    ctx.body = {
      echo: "Koa server says hello!",
      received: payload,
      timestamp: new Date().toISOString()
    };
  } else {
    ctx.status = 404;
    ctx.body = 'Not Found. Try POST to /api/echo';
  }
});

app.listen(PORT, () => {
  console.log(`JACS Koa server listening on port ${PORT}`);
});

API Reference

jacs.signRequest(payload)

Sign an object as a JACS request.

const signedRequest = await jacs.signRequest({
  method: 'getData',
  params: { id: 123 }
});
// Returns: JACS-signed JSON string

jacs.verifyResponse(responseString)

Verify a JACS-signed response and extract the payload.

const result = await jacs.verifyResponse(jacsResponseString);
// Returns: { payload: {...}, jacsId: '...', ... }

const payload = result.payload;

jacs.signResponse(payload)

Sign an object as a JACS response.

const signedResponse = await jacs.signResponse({
  success: true,
  data: { result: 42 }
});
// Returns: JACS-signed JSON string

JACSExpressMiddleware(options)

Express middleware for JACS request/response handling.

import { JACSExpressMiddleware } from 'jacsnpm/http';

app.use(JACSExpressMiddleware({
  configPath: './jacs.config.json'  // Required
}));

Request Processing:

• Reads req.body as a JACS string
• Verifies the signature
• Attaches payload to req.jacsPayload
• On failure, sends 400 response

Response Processing:

• Intercepts res.send() calls
• If body is an object, signs it as JACS
• Sends signed string to client

JACSKoaMiddleware(options)

Koa middleware for JACS request/response handling.

import { JACSKoaMiddleware } from 'jacsnpm/http';

app.use(JACSKoaMiddleware({
  configPath: './jacs.config.json'  // Required
}));

Request Processing:

• Reads raw request body
• Verifies JACS signature
• Attaches payload to ctx.state.jacsPayload and ctx.jacsPayload

Response Processing:

• Signs ctx.body if it's an object
• Converts to JACS string before sending

Complete Example

Server (server.js)

import express from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const app = express();

// JACS middleware for /api routes
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.server.config.json'
}));

// Echo endpoint
app.post('/api/echo', (req, res) => {
  const payload = req.jacsPayload;
  res.send({
    echo: payload,
    serverTime: new Date().toISOString()
  });
});

// Calculate endpoint
app.post('/api/calculate', (req, res) => {
  const { operation, a, b } = req.jacsPayload;

  let result;
  switch (operation) {
    case 'add': result = a + b; break;
    case 'subtract': result = a - b; break;
    case 'multiply': result = a * b; break;
    case 'divide': result = a / b; break;
    default: return res.status(400).send({ error: 'Unknown operation' });
  }

  res.send({ operation, a, b, result });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Client (client.js)

import jacs from 'jacsnpm';

async function main() {
  await jacs.load('./jacs.client.config.json');

  // Call echo endpoint
  const echoResult = await callApi('/api/echo', {
    message: 'Hello, server!'
  });
  console.log('Echo result:', echoResult);

  // Call calculate endpoint
  const calcResult = await callApi('/api/calculate', {
    operation: 'multiply',
    a: 7,
    b: 6
  });
  console.log('Calculate result:', calcResult);
}

async function callApi(path, payload) {
  const signedRequest = await jacs.signRequest(payload);

  const response = await fetch(`http://localhost:3000${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'text/plain' },
    body: signedRequest
  });

  const responseText = await response.text();
  const verified = await jacs.verifyResponse(responseText);
  return verified.payload;
}

main().catch(console.error);

Security Considerations

Content-Type

JACS requests should use text/plain content type since they are signed JSON strings, not raw JSON.

Error Handling

Always handle verification failures gracefully:

try {
  const verified = await jacs.verifyResponse(responseText);
  return verified.payload;
} catch (error) {
  console.error('JACS verification failed:', error.message);
  // Handle invalid/tampered response
}

Agent Keys

Each server and client needs its own JACS agent with:

• Unique agent ID
• Private/public key pair
• Configuration file pointing to the keys

Middleware Order

For Express, ensure express.text() comes before JACSExpressMiddleware:

// Correct order
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: '...' }));

// Wrong - JACS middleware won't receive string body
app.use('/api', JACSExpressMiddleware({ configPath: '...' }));
app.use('/api', express.text({ type: '*/*' }));

Next Steps

• Express Middleware - More Express integration patterns
• MCP Integration - Model Context Protocol support
• API Reference - Complete API documentation

Express Middleware

This chapter covers advanced Express.js integration patterns with JACS, building on the basics covered in HTTP Server.

Overview

JACS provides JACSExpressMiddleware for seamless integration with Express.js applications:

• Automatic request verification
• Automatic response signing
• Access to verified payloads via req.jacsPayload
• Error handling for invalid requests

Quick Start

import express from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const app = express();

// Required: Parse body as text before JACS middleware
app.use('/api', express.text({ type: '*/*' }));

// Apply JACS middleware
app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.config.json'
}));

// Routes automatically get verified payloads and signed responses
app.post('/api/data', (req, res) => {
  const payload = req.jacsPayload;
  res.send({ received: payload, status: 'ok' });
});

app.listen(3000);

Middleware Configuration

Basic Configuration

JACSExpressMiddleware({
  configPath: './jacs.config.json'  // Required: path to JACS config
})

Per-Route Configuration

Apply JACS to specific routes:

const app = express();

// Non-JACS routes (public endpoints)
app.get('/health', (req, res) => res.send({ status: 'ok' }));
app.get('/public/info', (req, res) => res.send({ name: 'My API' }));

// JACS-protected routes
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: './jacs.config.json' }));

app.post('/api/secure', (req, res) => {
  // Only JACS-signed requests reach here
  res.send({ data: 'secure response' });
});

Multiple JACS Agents

Use different JACS agents for different routes:

// Admin routes with admin agent
app.use('/admin', express.text({ type: '*/*' }));
app.use('/admin', JACSExpressMiddleware({
  configPath: './jacs.admin.config.json'
}));

// User routes with user agent
app.use('/user', express.text({ type: '*/*' }));
app.use('/user', JACSExpressMiddleware({
  configPath: './jacs.user.config.json'
}));

Request Handling

Accessing Verified Payload

The middleware attaches the verified payload to req.jacsPayload:

app.post('/api/process', (req, res) => {
  // req.jacsPayload contains the verified, decrypted payload
  const { action, data, timestamp } = req.jacsPayload;

  console.log('Action:', action);
  console.log('Data:', data);
  console.log('Request timestamp:', timestamp);

  res.send({ processed: true });
});

Handling Missing Payload

If JACS verification fails, req.jacsPayload will be undefined:

app.post('/api/secure', (req, res) => {
  if (!req.jacsPayload) {
    return res.status(400).json({ error: 'Invalid JACS request' });
  }

  // Process verified payload
  res.send({ success: true });
});

Validation Helper

Create a reusable validation middleware:

function requireJacsPayload(req, res, next) {
  if (!req.jacsPayload) {
    return res.status(400).json({
      error: 'JACS verification failed',
      message: 'Request must be signed with valid JACS credentials'
    });
  }
  next();
}

// Apply to routes
app.post('/api/secure', requireJacsPayload, (req, res) => {
  // Guaranteed to have valid req.jacsPayload
  res.send({ data: req.jacsPayload });
});

Response Handling

Automatic Signing

When you call res.send() with an object, the middleware automatically signs it:

app.post('/api/data', (req, res) => {
  // This object will be automatically JACS-signed
  res.send({
    result: 'success',
    data: { value: 42 },
    timestamp: new Date().toISOString()
  });
});

Sending Unsigned Responses

To bypass automatic signing, send a string directly:

app.post('/api/raw', (req, res) => {
  // String responses are not signed
  res.type('text/plain').send('Raw text response');
});

Custom Response Format

app.post('/api/custom', (req, res) => {
  const response = {
    success: true,
    payload: {
      action: 'completed',
      result: processRequest(req.jacsPayload)
    },
    metadata: {
      serverTime: new Date().toISOString(),
      requestId: generateRequestId()
    }
  };

  // Automatically signed before sending
  res.send(response);
});

Error Handling

Global Error Handler

import express from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const app = express();

app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: './jacs.config.json' }));

app.post('/api/process', (req, res, next) => {
  try {
    if (!req.jacsPayload) {
      throw new Error('Missing JACS payload');
    }

    const result = processData(req.jacsPayload);
    res.send({ result });
  } catch (error) {
    next(error);
  }
});

// Global error handler
app.use((error, req, res, next) => {
  console.error('Error:', error.message);

  res.status(500).send({
    error: 'Internal server error',
    message: error.message
  });
});

Typed Errors

class JacsValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'JacsValidationError';
    this.statusCode = 400;
  }
}

app.post('/api/validate', (req, res, next) => {
  try {
    if (!req.jacsPayload) {
      throw new JacsValidationError('Invalid JACS request');
    }

    const { requiredField } = req.jacsPayload;
    if (!requiredField) {
      throw new JacsValidationError('Missing required field');
    }

    res.send({ valid: true });
  } catch (error) {
    next(error);
  }
});

// Error handler
app.use((error, req, res, next) => {
  const statusCode = error.statusCode || 500;
  res.status(statusCode).send({
    error: error.name,
    message: error.message
  });
});

Advanced Patterns

Router-Level Middleware

import { Router } from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

// Create a JACS-enabled router
function createJacsRouter(configPath) {
  const router = Router();

  router.use(express.text({ type: '*/*' }));
  router.use(JACSExpressMiddleware({ configPath }));

  return router;
}

// Usage
const apiRouter = createJacsRouter('./jacs.config.json');

apiRouter.post('/users', (req, res) => {
  res.send({ users: getUserList() });
});

apiRouter.post('/orders', (req, res) => {
  res.send({ orders: getOrders(req.jacsPayload.userId) });
});

app.use('/api', apiRouter);

Middleware Composition

Combine JACS with other middleware:

import rateLimit from 'express-rate-limit';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

// Apply multiple middleware in order
app.use('/api',
  limiter,                              // Rate limiting first
  express.text({ type: '*/*' }),        // Parse body as text
  JACSExpressMiddleware({ configPath: './jacs.config.json' })  // JACS verification
);

Logging Middleware

Log JACS requests for auditing:

function jacsLogger(req, res, next) {
  if (req.jacsPayload) {
    console.log(JSON.stringify({
      timestamp: new Date().toISOString(),
      method: req.method,
      path: req.path,
      jacsPayload: req.jacsPayload,
      ip: req.ip
    }));
  }
  next();
}

app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: './jacs.config.json' }));
app.use('/api', jacsLogger);  // After JACS middleware

Authentication Integration

Combine JACS with user authentication:

// JACS middleware first
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: './jacs.config.json' }));

// Then authentication check
function requireAuth(req, res, next) {
  const payload = req.jacsPayload;

  if (!payload || !payload.userId) {
    return res.status(401).send({ error: 'Authentication required' });
  }

  // Attach user to request
  req.user = { id: payload.userId };
  next();
}

app.post('/api/protected', requireAuth, (req, res) => {
  res.send({
    message: `Hello, user ${req.user.id}`,
    data: req.jacsPayload.data
  });
});

Testing

Unit Testing Routes

import request from 'supertest';
import jacs from 'jacsnpm';

describe('JACS API', () => {
  beforeAll(async () => {
    await jacs.load('./jacs.test.config.json');
  });

  it('should accept valid JACS requests', async () => {
    const payload = { action: 'test', data: 'hello' };
    const signedRequest = await jacs.signRequest(payload);

    const response = await request(app)
      .post('/api/echo')
      .set('Content-Type', 'text/plain')
      .send(signedRequest);

    expect(response.status).toBe(200);

    // Verify response is JACS-signed
    const verified = await jacs.verifyResponse(response.text);
    expect(verified.payload.echo).toEqual(payload);
  });

  it('should reject unsigned requests', async () => {
    const response = await request(app)
      .post('/api/echo')
      .set('Content-Type', 'text/plain')
      .send('{"invalid": "request"}');

    expect(response.status).toBe(400);
  });
});

Mock JACS for Testing

// test/mocks/jacs.js
export const mockJacs = {
  payload: null,

  setPayload(p) {
    this.payload = p;
  },

  reset() {
    this.payload = null;
  }
};

// Mock middleware for testing
export function mockJacsMiddleware(req, res, next) {
  req.jacsPayload = mockJacs.payload;
  next();
}

// In tests
describe('API without real JACS', () => {
  beforeEach(() => {
    mockJacs.setPayload({ userId: 'test-user', action: 'test' });
  });

  afterEach(() => {
    mockJacs.reset();
  });

  it('processes payload correctly', async () => {
    const response = await request(testApp)
      .post('/api/process')
      .send('test');

    expect(response.status).toBe(200);
  });
});

Complete Application Example

import express from 'express';
import { JACSExpressMiddleware } from 'jacsnpm/http';

const app = express();

// Health check (no JACS)
app.get('/health', (req, res) => res.send({ status: 'healthy' }));

// JACS-protected API routes
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.config.json'
}));

// Validation middleware
function requirePayload(req, res, next) {
  if (!req.jacsPayload) {
    return res.status(400).send({ error: 'Invalid JACS request' });
  }
  next();
}

// Routes
app.post('/api/echo', requirePayload, (req, res) => {
  res.send({ echo: req.jacsPayload });
});

app.post('/api/users', requirePayload, (req, res) => {
  const { name, email } = req.jacsPayload;

  if (!name || !email) {
    return res.status(400).send({ error: 'Name and email required' });
  }

  const user = createUser({ name, email });
  res.send({ user, created: true });
});

app.post('/api/documents', requirePayload, async (req, res) => {
  const { title, content } = req.jacsPayload;

  const document = await createDocument({ title, content });
  res.send({ document });
});

// Error handler
app.use((err, req, res, next) => {
  console.error('Error:', err);
  res.status(500).send({ error: 'Internal server error' });
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`JACS Express server listening on port ${PORT}`);
});

Troubleshooting

Body Parsing Issues

Problem: req.jacsPayload is always undefined

Solution: Ensure express.text() comes before JACS middleware:

// Correct
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: '...' }));

// Wrong
app.use('/api', JACSExpressMiddleware({ configPath: '...' }));
app.use('/api', express.text({ type: '*/*' }));

JSON Body Parser Conflict

Problem: Using express.json() interferes with JACS

Solution: Use route-specific middleware:

// JSON for non-JACS routes
app.use('/public', express.json());

// Text for JACS routes
app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({ configPath: '...' }));

Response Not Signed

Problem: Responses are plain JSON, not JACS-signed

Solution: Ensure you're sending an object, not a string:

// Will be signed
res.send({ data: 'value' });

// Will NOT be signed
res.send(JSON.stringify({ data: 'value' }));

Next Steps

• HTTP Server - Core HTTP integration concepts
• MCP Integration - Model Context Protocol support
• API Reference - Complete API documentation

API Reference

Complete API documentation for the jacsnpm Node.js package.

Installation

npm install jacsnpm

Core Module

import { JacsAgent, hashString, createConfig } from 'jacsnpm';

JacsAgent Class

The JacsAgent class is the primary interface for JACS operations. Each instance maintains its own state and can be used independently, allowing multiple agents in the same process.

Constructor

new JacsAgent()

Creates a new empty JacsAgent instance. Call load() to initialize with a configuration.

Example:

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

agent.load(configPath)

Load and initialize the agent from a configuration file.

Parameters:

• configPath (string): Path to the JACS configuration file

Returns: string - The loaded agent's JSON

Example:

const agent = new JacsAgent();
const agentJson = agent.load('./jacs.config.json');
console.log('Agent loaded:', JSON.parse(agentJson).jacsId);

agent.createDocument(documentString, customSchema?, outputFilename?, noSave?, attachments?, embed?)

Create and sign a new JACS document.

Parameters:

• documentString (string): JSON string of the document content
• customSchema (string, optional): Path to a custom JSON Schema for validation
• outputFilename (string, optional): Filename to save the document
• noSave (boolean, optional): If true, don't save to storage (default: false)
• attachments (string, optional): Path to file attachments
• embed (boolean, optional): If true, embed attachments in the document

Returns: string - The signed document as a JSON string

Example:

// Basic document creation
const doc = agent.createDocument(JSON.stringify({
  title: 'My Document',
  content: 'Hello, World!'
}));

// With custom schema
const validatedDoc = agent.createDocument(
  JSON.stringify({ title: 'Validated', amount: 100 }),
  './schemas/invoice.schema.json'
);

// Without saving
const tempDoc = agent.createDocument(
  JSON.stringify({ data: 'temporary' }),
  null,
  null,
  true  // noSave = true
);

// With attachments
const docWithFile = agent.createDocument(
  JSON.stringify({ report: 'Monthly Report' }),
  null,
  null,
  false,
  './report.pdf',
  true  // embed = true
);

agent.verifyDocument(documentString)

Verify a document's signature and hash integrity.

Parameters:

• documentString (string): The signed document JSON string

Returns: boolean - True if the document is valid

Example:

const isValid = agent.verifyDocument(signedDocumentJson);
if (isValid) {
  console.log('Document signature verified');
} else {
  console.log('Document verification failed');
}

agent.verifySignature(documentString, signatureField?)

Verify a document's signature with an optional custom signature field.

Parameters:

• documentString (string): The signed document JSON string
• signatureField (string, optional): Name of the signature field (default: 'jacsSignature')

Returns: boolean - True if the signature is valid

Example:

// Verify default signature field
const isValid = agent.verifySignature(docJson);

// Verify custom signature field
const isValidCustom = agent.verifySignature(docJson, 'customSignature');

agent.updateDocument(documentKey, newDocumentString, attachments?, embed?)

Update an existing document, creating a new version.

Parameters:

• documentKey (string): The document key in format "id:version"
• newDocumentString (string): The modified document as JSON string
• attachments (Array, optional): Array of attachment file paths
• embed (boolean, optional): If true, embed attachments

Returns: string - The updated document as a JSON string

Example:

// Parse existing document to get key
const doc = JSON.parse(signedDoc);
const documentKey = `${doc.jacsId}:${doc.jacsVersion}`;

// Update the document
const updatedDoc = agent.updateDocument(
  documentKey,
  JSON.stringify({
    ...doc,
    title: 'Updated Title',
    content: 'Modified content'
  })
);

agent.createAgreement(documentString, agentIds, question?, context?, agreementFieldName?)

Add an agreement requiring multiple agent signatures to a document.

Parameters:

• documentString (string): The document JSON string
• agentIds (Array): Array of agent IDs required to sign
• question (string, optional): The agreement question
• context (string, optional): Additional context for the agreement
• agreementFieldName (string, optional): Field name for the agreement (default: 'jacsAgreement')

Returns: string - The document with agreement as a JSON string

Example:

const docWithAgreement = agent.createAgreement(
  signedDocumentJson,
  ['agent-1-uuid', 'agent-2-uuid', 'agent-3-uuid'],
  'Do you agree to these terms?',
  'Q1 2024 Service Agreement',
  'jacsAgreement'
);

agent.signAgreement(documentString, agreementFieldName?)

Sign an agreement as the current agent.

Parameters:

• documentString (string): The document with agreement JSON string
• agreementFieldName (string, optional): Field name of the agreement (default: 'jacsAgreement')

Returns: string - The document with this agent's signature added

Example:

const signedAgreement = agent.signAgreement(
  docWithAgreementJson,
  'jacsAgreement'
);

agent.checkAgreement(documentString, agreementFieldName?)

Check the status of an agreement (which agents have signed).

Parameters:

• documentString (string): The document with agreement JSON string
• agreementFieldName (string, optional): Field name of the agreement (default: 'jacsAgreement')

Returns: string - JSON string with agreement status

Example:

const statusJson = agent.checkAgreement(signedAgreementJson);
const status = JSON.parse(statusJson);

console.log('Required signers:', status.required);
console.log('Signatures received:', status.signed);
console.log('Complete:', status.complete);

agent.signString(data)

Sign arbitrary string data with the agent's private key.

Parameters:

• data (string): The data to sign

Returns: string - Base64-encoded signature

Example:

const signature = agent.signString('Important message');
console.log('Signature:', signature);

agent.verifyString(data, signatureBase64, publicKey, publicKeyEncType)

Verify a signature on arbitrary string data.

Parameters:

• data (string): The original data
• signatureBase64 (string): The base64-encoded signature
• publicKey (Buffer): The public key as a Buffer
• publicKeyEncType (string): The key algorithm (e.g., 'ring-Ed25519')

Returns: boolean - True if the signature is valid

Example:

const isValid = agent.verifyString(
  'Important message',
  signatureBase64,
  publicKeyBuffer,
  'ring-Ed25519'
);

agent.signRequest(params)

Sign a request payload, wrapping it in a JACS document.

Parameters:

• params (any): The request payload object

Returns: string - JACS-signed request as a JSON string

Example:

const signedRequest = agent.signRequest({
  method: 'GET',
  path: '/api/data',
  timestamp: new Date().toISOString(),
  body: { query: 'value' }
});

agent.verifyResponse(documentString)

Verify a JACS-signed response and extract the payload.

Parameters:

• documentString (string): The JACS-signed response

Returns: object - Object containing the verified payload

Example:

const result = agent.verifyResponse(jacsResponseString);
const payload = result.payload;
console.log('Verified payload:', payload);

agent.verifyResponseWithAgentId(documentString)

Verify a response and return both the payload and signer's agent ID.

Parameters:

• documentString (string): The JACS-signed response

Returns: object - Object with payload and agent ID

Example:

const result = agent.verifyResponseWithAgentId(jacsResponseString);
console.log('Payload:', result.payload);
console.log('Signed by agent:', result.agentId);

agent.verifyAgent(agentFile?)

Verify the agent's own signature and hash, or verify another agent file.

Parameters:

• agentFile (string, optional): Path to an agent file to verify

Returns: boolean - True if the agent is valid

Example:

// Verify the loaded agent
const isValid = agent.verifyAgent();

// Verify another agent file
const isOtherValid = agent.verifyAgent('./other-agent.json');

agent.updateAgent(newAgentString)

Update the agent document with new data.

Parameters:

• newAgentString (string): The modified agent document as JSON string

Returns: string - The updated agent document

Example:

const currentAgent = JSON.parse(agent.load('./jacs.config.json'));
const updatedAgent = agent.updateAgent(JSON.stringify({
  ...currentAgent,
  description: 'Updated description'
}));

agent.signAgent(agentString, publicKey, publicKeyEncType)

Sign another agent's document with a registration signature.

Parameters:

• agentString (string): The agent document to sign
• publicKey (Buffer): The public key as a Buffer
• publicKeyEncType (string): The key algorithm

Returns: string - The signed agent document

Example:

const signedAgent = agent.signAgent(
  externalAgentJson,
  publicKeyBuffer,
  'ring-Ed25519'
);

Utility Functions

hashString(data)

Hash a string using SHA-256.

Parameters:

• data (string): The string to hash

Returns: string - Hexadecimal hash string

Example:

import { hashString } from 'jacsnpm';

const hash = hashString('data to hash');
console.log('SHA-256:', hash);

createConfig(options)

Create a JACS configuration JSON string programmatically.

Parameters:

• jacsUseSecurity (string, optional): Enable security features
• jacsDataDirectory (string, optional): Directory for data storage
• jacsKeyDirectory (string, optional): Directory for key storage
• jacsAgentPrivateKeyFilename (string, optional): Private key filename
• jacsAgentPublicKeyFilename (string, optional): Public key filename
• jacsAgentKeyAlgorithm (string, optional): Signing algorithm
• jacsPrivateKeyPassword (string, optional): Password for private key
• jacsAgentIdAndVersion (string, optional): Agent ID and version to load
• jacsDefaultStorage (string, optional): Storage backend ('fs', 's3', 'memory')

Returns: string - Configuration as JSON string

Example:

import { createConfig } from 'jacsnpm';

const configJson = createConfig(
  undefined,           // jacsUseSecurity
  './jacs_data',       // jacsDataDirectory
  './jacs_keys',       // jacsKeyDirectory
  undefined,           // private key filename
  undefined,           // public key filename
  'ring-Ed25519',      // algorithm
  undefined,           // password
  undefined,           // agent id
  'fs'                 // storage
);

// Write to file
fs.writeFileSync('jacs.config.json', configJson);

HTTP Module

import { JACSExpressMiddleware, JACSKoaMiddleware } from 'jacsnpm/http';

JACSExpressMiddleware(options)

Express middleware for JACS request/response handling.

Parameters:

• options.configPath (string): Path to JACS configuration file

Returns: Express middleware function

Example:

import { JACSExpressMiddleware } from 'jacsnpm/http';

app.use('/api', express.text({ type: '*/*' }));
app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.config.json'
}));

app.post('/api/data', (req, res) => {
  // req.jacsPayload contains verified payload
  res.send({ received: req.jacsPayload });
});

JACSKoaMiddleware(options)

Koa middleware for JACS request/response handling.

Parameters:

• options.configPath (string): Path to JACS configuration file

Returns: Koa middleware function

Example:

import { JACSKoaMiddleware } from 'jacsnpm/http';

app.use(JACSKoaMiddleware({
  configPath: './jacs.config.json'
}));

app.use(async (ctx) => {
  // ctx.state.jacsPayload contains verified payload
  ctx.body = { received: ctx.state.jacsPayload };
});

MCP Module

import {
  JACSTransportProxy,
  createJACSTransportProxy,
  createJACSTransportProxyAsync
} from 'jacsnpm/mcp';

JACSTransportProxy

Class that wraps MCP transports with JACS encryption.

Constructor:

new JACSTransportProxy(transport, role, jacsConfigPath)

Parameters:

• transport: Any MCP transport (Stdio, SSE, WebSocket)
• role (string): 'server' or 'client'
• jacsConfigPath (string): Path to JACS configuration file

createJACSTransportProxy(transport, configPath, role)

Factory function for creating a transport proxy.

Parameters:

• transport: The underlying MCP transport
• configPath (string): Path to JACS configuration file
• role (string): 'server' or 'client'

Returns: JACSTransportProxy instance

Example:

import { createJACSTransportProxy } from 'jacsnpm/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const baseTransport = new StdioServerTransport();
const secureTransport = createJACSTransportProxy(
  baseTransport,
  './jacs.config.json',
  'server'
);

createJACSTransportProxyAsync(transport, configPath, role)

Async factory that waits for JACS to be fully loaded.

Parameters: Same as createJACSTransportProxy

Returns: Promise

Example:

const secureTransport = await createJACSTransportProxyAsync(
  baseTransport,
  './jacs.config.json',
  'server'
);

TypeScript Support

The package includes full TypeScript definitions. Import types as needed:

import { JacsAgent, hashString, createConfig } from 'jacsnpm';

const agent: JacsAgent = new JacsAgent();
const hash: string = hashString('data');
const config: string = createConfig(
  undefined,
  './data',
  './keys'
);

Deprecated Functions

The following module-level functions are deprecated. Use new JacsAgent() and instance methods instead:

• load() - Use agent.load()
• signAgent() - Use agent.signAgent()
• verifyString() - Use agent.verifyString()
• signString() - Use agent.signString()
• verifyAgent() - Use agent.verifyAgent()
• updateAgent() - Use agent.updateAgent()
• verifyDocument() - Use agent.verifyDocument()
• updateDocument() - Use agent.updateDocument()
• verifySignature() - Use agent.verifySignature()
• createAgreement() - Use agent.createAgreement()
• signAgreement() - Use agent.signAgreement()
• createDocument() - Use agent.createDocument()
• checkAgreement() - Use agent.checkAgreement()
• signRequest() - Use agent.signRequest()
• verifyResponse() - Use agent.verifyResponse()
• verifyResponseWithAgentId() - Use agent.verifyResponseWithAgentId()

Migration Example:

// Old (deprecated)
import jacs from 'jacsnpm';
await jacs.load('./jacs.config.json');
const doc = jacs.createDocument(JSON.stringify({ data: 'test' }));

// New (recommended)
import { JacsAgent } from 'jacsnpm';
const agent = new JacsAgent();
agent.load('./jacs.config.json');
const doc = agent.createDocument(JSON.stringify({ data: 'test' }));

Error Handling

All methods may throw errors. Use try/catch for error handling:

try {
  const agent = new JacsAgent();
  agent.load('./jacs.config.json');
  const doc = agent.createDocument(JSON.stringify({ data: 'test' }));
} catch (error) {
  console.error('JACS error:', error.message);
}

See Also

• Installation - Getting started
• Basic Usage - Common usage patterns
• MCP Integration - Model Context Protocol
• HTTP Server - HTTP integration
• Express Middleware - Express.js patterns

Python Installation

The JACS Python package (jacs) provides Python bindings to the JACS Rust library, making it easy to integrate JACS into AI/ML workflows, data science projects, and Python applications.

Requirements

• Python: Version 3.10 or higher
• pip: For package management
• Operating System: Linux, macOS, or Windows with WSL
• Architecture: x86_64 or ARM64

Installation

Using pip

pip install jacs

Using conda

conda install -c conda-forge jacs

Using poetry

poetry add jacs

Development Installation

# Clone the repository
git clone https://github.com/HumanAssisted/JACS
cd JACS/jacspy

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

Verify Installation

Create a simple test to verify everything is working:

# test.py
import jacs

print('JACS Python bindings loaded successfully!')

# Test basic functionality
try:
    agent = jacs.JacsAgent()
    agent.load('./jacs.config.json')
    print('Agent loaded successfully!')
except Exception as error:
    print(f'Error loading agent: {error}')

Run the test:

python test.py

Package Structure

The jacs package provides Python bindings to the JACS Rust library:

Core Module

import jacs

# Create and load agent
agent = jacs.JacsAgent()
agent.load('./jacs.config.json')

# Utility functions
hash_value = jacs.hash_string("data to hash")
config_json = jacs.create_config(
    jacs_data_directory="./data",
    jacs_key_directory="./keys",
    jacs_agent_key_algorithm="ring-Ed25519"
)

JacsAgent Methods

# Create a new agent instance
agent = jacs.JacsAgent()

# Load configuration
agent.load('./jacs.config.json')

# Document operations
signed_doc = agent.create_document(json_string)
is_valid = agent.verify_document(document_string)

# Signing operations
signature = agent.sign_string("data to sign")

Configuration

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",
  "jacs_agent_id_and_version": "agent-uuid:version-uuid"
}

Load Configuration in Python

import jacs

# Create agent and load configuration
agent = jacs.JacsAgent()
agent.load('./jacs.config.json')

Programmatic Configuration

import jacs

# Create a configuration JSON string programmatically
config_json = jacs.create_config(
    jacs_data_directory="./jacs_data",
    jacs_key_directory="./jacs_keys",
    jacs_agent_key_algorithm="ring-Ed25519",
    jacs_default_storage="fs"
)

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"
}

S3 Storage

{
  "jacs_default_storage": "s3"
}

S3 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/
├── requirements.txt
├── jacs.config.json
├── src/
│   ├── agent.py
│   ├── tasks.py
│   └── agreements.py
├── jacs_data/
│   ├── agents/
│   ├── tasks/
│   └── documents/
├── jacs_keys/
│   ├── private.pem
│   └── public.pem
└── tests/
    └── test_jacs.py

Requirements.txt Setup

jacs>=0.1.0
fastapi>=0.100.0  # For FastMCP integration
uvicorn>=0.23.0   # For ASGI server
pydantic>=2.0.0   # For data validation

Basic Application

# src/app.py
import jacs
import json

def main():
    # Create and load agent
    agent = jacs.JacsAgent()
    agent.load('./jacs.config.json')

    # Create a document
    document_data = {
        "title": "My First Document",
        "content": "Hello from Python!"
    }

    signed_doc = agent.create_document(json.dumps(document_data))
    print('Document created')

    # Verify the document
    is_valid = agent.verify_document(signed_doc)
    print(f'Document valid: {is_valid}')

    print('JACS agent ready!')
    return agent

if __name__ == "__main__":
    agent = main()

Virtual Environment Setup

Using venv

# Create virtual environment
python -m venv jacs-env

# Activate (Linux/macOS)
source jacs-env/bin/activate

# Activate (Windows)
jacs-env\Scripts\activate

# Install JACS
pip install jacs

Using conda

# Create conda environment
conda create -n jacs-env python=3.11

# Activate environment
conda activate jacs-env

# Install JACS
pip install jacs

Using poetry

# Initialize poetry project
poetry init

# Add JACS dependency
poetry add jacs

# Install dependencies
poetry install

# Activate shell
poetry shell

Jupyter Notebook Setup

# Install Jupyter in your JACS environment
pip install jupyter

# Start Jupyter
jupyter notebook

# In your notebook
import jacs
import json

# Create and load agent
agent = jacs.JacsAgent()
agent.load('./jacs.config.json')

# Create a simple document
doc = agent.create_document(json.dumps({
    "title": "Notebook Analysis",
    "data": [1, 2, 3, 4, 5]
}))

print("Document created!")
print("JACS ready for notebook use!")

Common Issues

Module Not Found

If you get ModuleNotFoundError: No module named 'jacs':

# Check Python version
python --version  # Should be 3.10+

# Check if jacs is installed
pip list | grep jacs

# Reinstall if needed
pip uninstall jacs
pip install jacs

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:

# Update pip and reinstall
pip install --upgrade pip
pip uninstall jacs
pip install jacs --no-cache-dir

Windows Issues

On Windows, you may need Visual C++ Build Tools:

# Install Visual C++ Build Tools
# Or use conda-forge
conda install -c conda-forge jacs

Type Hints and IDE Support

JACS is built with Rust and PyO3, providing Python bindings:

import jacs
import json

# Create agent instance
agent: jacs.JacsAgent = jacs.JacsAgent()
agent.load('./jacs.config.json')

# Create and verify documents
signed_doc: str = agent.create_document(json.dumps({"title": "Test"}))
is_valid: bool = agent.verify_document(signed_doc)

Testing Setup

# tests/test_jacs.py
import unittest
import jacs
import json

class TestJACS(unittest.TestCase):
    def setUp(self):
        # Requires a valid jacs.config.json file
        self.agent = jacs.JacsAgent()
        self.agent.load('./jacs.config.json')

    def test_document_creation(self):
        doc_data = {"title": "Test Document", "content": "Test content"}
        signed_doc = self.agent.create_document(json.dumps(doc_data))

        # Document should be a valid JSON string
        parsed = json.loads(signed_doc)
        self.assertIn("jacsId", parsed)
        self.assertIn("jacsSignature", parsed)

    def test_document_verification(self):
        doc_data = {"title": "Verify Test"}
        signed_doc = self.agent.create_document(json.dumps(doc_data))

        is_valid = self.agent.verify_document(signed_doc)
        self.assertTrue(is_valid)

    def test_sign_string(self):
        signature = self.agent.sign_string("test data")
        self.assertIsInstance(signature, str)
        self.assertTrue(len(signature) > 0)

if __name__ == "__main__":
    unittest.main()

Next Steps

Now that you have JACS installed:

1. Basic Usage - Learn core JACS operations
2. MCP Integration - Add Model Context Protocol support
3. FastMCP Integration - Build advanced MCP servers
4. API Reference - Complete API documentation

Examples

Check out the complete examples in the examples directory:

• Basic agent creation and task management
• Jupyter notebook workflows
• FastMCP server implementation
• AI/ML pipeline integration

Basic Usage

This chapter covers fundamental JACS operations in Python, including agent initialization, document creation, signing, and verification.

Initializing an Agent

Create and Load Agent

import jacs

# Create a new agent instance
agent = jacs.JacsAgent()

# Load configuration from file
agent.load('./jacs.config.json')

Configuration File

Create jacs.config.json:

{
  "$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",
  "jacs_agent_id_and_version": "agent-uuid:version-uuid"
}

Creating Documents

Basic Document Creation

import jacs
import json

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

# Create a document from JSON
document_data = {
    "title": "Project Proposal",
    "content": "Quarterly development plan",
    "budget": 50000
}

signed_document = agent.create_document(json.dumps(document_data))
print('Signed document:', signed_document)

With Custom Schema

Validate against a custom JSON Schema:

signed_document = agent.create_document(
    json.dumps(document_data),
    './schemas/proposal.schema.json'  # custom schema path
)

With Output File

signed_document = agent.create_document(
    json.dumps(document_data),
    None,                     # no custom schema
    './output/proposal.json'  # output filename
)

Without Saving

signed_document = agent.create_document(
    json.dumps(document_data),
    None,   # no custom schema
    None,   # no output filename
    True    # no_save = True
)

With Attachments

signed_document = agent.create_document(
    json.dumps(document_data),
    None,                        # no custom schema
    None,                        # no output filename
    False,                       # save the document
    './attachments/report.pdf',  # attachment path
    True                         # embed files
)

Verifying Documents

Verify Document Signature

# Verify a document's signature and hash
is_valid = agent.verify_document(signed_document_json)
print('Document valid:', is_valid)

Verify Specific Signature Field

# Verify with a custom signature field
is_valid = agent.verify_signature(
    signed_document_json,
    'jacsSignature'  # signature field name
)

Updating Documents

Update Existing Document

# Original document key format: "id:version"
document_key = 'doc-uuid:version-uuid'

# Modified document content (must include jacsId and jacsVersion)
updated_data = {
    "jacsId": "doc-uuid",
    "jacsVersion": "version-uuid",
    "title": "Updated Proposal",
    "content": "Revised quarterly plan",
    "budget": 75000
}

updated_document = agent.update_document(
    document_key,
    json.dumps(updated_data)
)

print('Updated document:', updated_document)

Update with New Attachments

updated_document = agent.update_document(
    document_key,
    json.dumps(updated_data),
    ['./new-report.pdf'],  # new attachments
    True                   # embed files
)

Signing and Verification

Sign Arbitrary Data

# Sign any string data
signature = agent.sign_string('Important message to sign')
print('Signature:', signature)

Verify Arbitrary Data

# Verify a signature on string data
is_valid = agent.verify_string(
    'Important message to sign',  # original data
    signature_base64,             # base64 signature
    public_key_bytes,             # public key as bytes
    'ring-Ed25519'                # algorithm
)

Working with Agreements

Create an Agreement

# Add agreement requiring multiple agent signatures
document_with_agreement = agent.create_agreement(
    signed_document_json,
    ['agent1-uuid', 'agent2-uuid'],           # required signers
    'Do you agree to these terms?',            # question
    'Q1 2024 service contract',                # context
    'jacsAgreement'                            # field name
)

Sign an Agreement

# Sign the agreement as the current agent
signed_agreement = agent.sign_agreement(
    document_with_agreement_json,
    'jacsAgreement'  # agreement field name
)

Check Agreement Status

# Check which agents have signed
status = agent.check_agreement(
    document_with_agreement_json,
    'jacsAgreement'
)

print('Agreement status:', json.loads(status))

Agent Operations

Verify Agent

# Verify the loaded agent's signature
is_valid = agent.verify_agent()
print('Agent valid:', is_valid)

# Verify a specific agent file
is_valid_other = agent.verify_agent('./other-agent.json')

Update Agent

# Update agent document
updated_agent_json = agent.update_agent(json.dumps({
    "jacsId": "agent-uuid",
    "jacsVersion": "version-uuid",
    "name": "Updated Agent Name",
    "description": "Updated description"
}))

Sign External Agent

# Sign another agent's document with registration signature
signed_agent_json = agent.sign_agent(
    external_agent_json,
    public_key_bytes,
    'ring-Ed25519'
)

Request/Response Signing

Sign a Request

# Sign request parameters as a JACS document
signed_request = agent.sign_request({
    "method": "GET",
    "path": "/api/resource",
    "timestamp": datetime.now().isoformat(),
    "body": {"query": "data"}
})

Verify a Response

# Verify a signed response
result = agent.verify_response(signed_response_json)
print('Response valid:', result)

# Verify and get signer's agent ID
result_with_id = agent.verify_response_with_agent_id(signed_response_json)
print('Signer ID:', result_with_id)

Utility Functions

Hash String

import jacs

# SHA-256 hash of a string
hash_value = jacs.hash_string('data to hash')
print('Hash:', hash_value)

Create Configuration

import jacs

# Programmatically create a config JSON string
config_json = jacs.create_config(
    jacs_data_directory='./jacs_data',
    jacs_key_directory='./jacs_keys',
    jacs_agent_key_algorithm='ring-Ed25519',
    jacs_default_storage='fs'
)

print('Config:', config_json)

Error Handling

import jacs

agent = jacs.JacsAgent()

try:
    agent.load('./jacs.config.json')
except Exception as error:
    print(f'Failed to load agent: {error}')

try:
    doc = agent.create_document(json.dumps({'data': 'test'}))
    print('Document created')
except Exception as error:
    print(f'Failed to create document: {error}')

try:
    is_valid = agent.verify_document(invalid_json)
except Exception as error:
    print(f'Verification failed: {error}')

Complete Example

import jacs
import json

def main():
    # Initialize agent
    agent = jacs.JacsAgent()
    agent.load('./jacs.config.json')

    # Create a task document
    task = {
        "title": "Code Review",
        "description": "Review pull request #123",
        "assignee": "developer-uuid",
        "deadline": "2024-02-01"
    }

    signed_task = agent.create_document(json.dumps(task))
    print('Task created')

    # Verify the task
    if agent.verify_document(signed_task):
        print('Task signature valid')

    # Create agreement for task acceptance
    task_with_agreement = agent.create_agreement(
        signed_task,
        ['manager-uuid', 'developer-uuid'],
        'Do you accept this task assignment?'
    )

    # Sign the agreement
    signed_agreement = agent.sign_agreement(task_with_agreement)
    print('Agreement signed')

    # Check agreement status
    status = agent.check_agreement(signed_agreement)
    print('Status:', status)

    # Hash some data for reference
    task_hash = jacs.hash_string(signed_task)
    print('Task hash:', task_hash)

if __name__ == "__main__":
    main()

Working with Document Data

Parse Signed Documents

import json

# Create and sign a document
doc_data = {"title": "My Document", "content": "Hello, World!"}
signed_doc = agent.create_document(json.dumps(doc_data))

# Parse the signed document to access JACS fields
parsed = json.loads(signed_doc)
print('Document ID:', parsed.get('jacsId'))
print('Document Version:', parsed.get('jacsVersion'))
print('Signature:', parsed.get('jacsSignature'))

Document Key Format

# Document keys combine ID and version
doc_id = parsed['jacsId']
doc_version = parsed['jacsVersion']
document_key = f"{doc_id}:{doc_version}"

# Use the key for updates
updated_doc = agent.update_document(document_key, json.dumps({
    **parsed,
    "content": "Updated content"
}))

Configuration Management

Load from File

import jacs

agent = jacs.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"

Programmatic Configuration

import jacs
import json
import os

# Create config programmatically
config_json = jacs.create_config(
    jacs_data_directory='./jacs_data',
    jacs_key_directory='./jacs_keys',
    jacs_agent_key_algorithm='ring-Ed25519',
    jacs_default_storage='fs'
)

# Write to file
with open('jacs.config.json', 'w') as f:
    f.write(config_json)

# Then load it
agent = jacs.JacsAgent()
agent.load('./jacs.config.json')

Next Steps

• MCP Integration - Model Context Protocol support
• FastMCP Integration - Build advanced MCP servers
• API Reference - Complete API documentation

MCP Integration

JACS provides seamless integration with the Model Context Protocol (MCP), enabling cryptographically signed and verified communication between AI agents and MCP servers. This integration ensures that all tool calls, resource requests, and prompt interactions are authenticated and tamper-proof.

Overview

JACS MCP integration provides:

• Cryptographic Authentication: All MCP messages are signed and verified
• FastMCP Support: Native integration with FastMCP servers
• HTTP & SSE Transports: Support for Server-Sent Events transport
• Transparent Security: Existing MCP code works with minimal changes

Quick Start

Basic MCP Server with JACS

import jacs
import os
from pathlib import Path
from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP
import uvicorn

# Setup JACS configuration
current_dir = Path(__file__).parent.absolute()
jacs_config_path = current_dir / "jacs.config.json"

# Initialize JACS agent
agent = jacs.JacsAgent()
agent.load(str(jacs_config_path))

# Create FastMCP server with JACS authentication
mcp = JACSMCPServer(FastMCP("Authenticated Echo Server"))

@mcp.tool()
def echo_tool(text: str) -> str:
    """Echo the input text with server prefix"""
    return f"SERVER SAYS: {text}"

@mcp.resource("echo://static")
def echo_resource() -> str:
    return "Echo!"

@mcp.prompt("echo")
def echo_prompt(text: str) -> str:
    return f"Echo prompt: {text}"

# Get the ASGI app with JACS middleware
sse_app_with_middleware = mcp.sse_app()

if __name__ == "__main__":
    print("Starting JACS-enabled MCP server...")
    uvicorn.run(sse_app_with_middleware, host="localhost", port=8000)

Basic MCP Client with JACS

import asyncio
import os
from pathlib import Path
import jacs
from jacs.mcp import JACSMCPClient

# Setup JACS configuration
current_dir = Path(__file__).parent.absolute()
jacs_config_path = current_dir / "jacs.client.config.json"

# Initialize JACS agent
agent = jacs.JacsAgent()
agent.load(str(jacs_config_path))

async def main():
    server_url = "http://localhost:8000/sse"

    try:
        client = JACSMCPClient(server_url)

        async with client:
            # Call authenticated tool
            result = await client.call_tool("echo_tool", {
                "text": "Hello from authenticated client!"
            })
            print(f"Tool result: {result}")

            # Read authenticated resource
            resource = await client.read_resource("echo://static")
            print(f"Resource: {resource}")

    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())

How It Works

JACSMCPServer

The JACSMCPServer wrapper adds JACS middleware to a FastMCP server:

1. Incoming Requests: Intercepts JSON-RPC requests and verifies them using jacs.verify_request()
2. Outgoing Responses: Signs JSON-RPC responses using jacs.sign_response()

from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP

# Create FastMCP server
base_server = FastMCP("My Server")

# Wrap with JACS authentication
authenticated_server = JACSMCPServer(base_server)

# All decorators work normally
@authenticated_server.tool()
def my_tool(data: str) -> str:
    return f"Processed: {data}"

# Get ASGI app with JACS middleware
app = authenticated_server.sse_app()

JACSMCPClient

The JACSMCPClient wrapper adds interceptors to a FastMCP client:

1. Outgoing Messages: Signs messages using jacs.sign_request()
2. Incoming Messages: Verifies messages using jacs.verify_response()

from jacs.mcp import JACSMCPClient

client = JACSMCPClient("http://localhost:8000/sse")

async with client:
    result = await client.call_tool("my_tool", {"data": "test"})

Configuration

JACS Configuration File

Create a jacs.config.json file for your server and client:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_agent_id_and_version": "your-agent-id:version",
  "jacs_agent_key_algorithm": "ring-Ed25519",
  "jacs_agent_private_key_filename": "private.pem",
  "jacs_agent_public_key_filename": "public.pem",
  "jacs_data_directory": "./jacs_data",
  "jacs_default_storage": "fs",
  "jacs_key_directory": "./jacs_keys"
}

Initializing the Agent

Before using MCP integration, initialize your JACS agent:

import jacs

# Create and load agent
agent = jacs.JacsAgent()
agent.load("./jacs.config.json")

# Agent is now ready for MCP operations

Integration Patterns

FastMCP with JACS Middleware

from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP
import jacs

# Initialize JACS
agent = jacs.JacsAgent()
agent.load("./jacs.config.json")

# Create and wrap server
server = FastMCP("My Server")
authenticated_server = JACSMCPServer(server)

@authenticated_server.tool()
def secure_tool(input_data: str) -> str:
    """A tool that processes signed input"""
    return f"Securely processed: {input_data}"

# Run server
if __name__ == "__main__":
    import uvicorn
    app = authenticated_server.sse_app()
    uvicorn.run(app, host="localhost", port=8000)

Manual Request/Response Signing

For custom integrations, you can use the module-level functions directly:

import jacs

# Initialize agent first
agent = jacs.JacsAgent()
agent.load("./jacs.config.json")

# Sign a request
signed_request = jacs.sign_request({
    "method": "tools/call",
    "params": {"name": "my_tool", "arguments": {"data": "test"}}
})

# Verify a response
verified_response = jacs.verify_response(signed_response_string)
payload = verified_response.get("payload")

Error Handling

Common Errors

import jacs
from jacs.mcp import JACSMCPClient

async def robust_mcp_client():
    try:
        agent = jacs.JacsAgent()
        agent.load("./jacs.config.json")

        client = JACSMCPClient("http://localhost:8000/sse")
        async with client:
            result = await client.call_tool("my_tool", {"data": "test"})
            return result

    except FileNotFoundError as e:
        print(f"Configuration file not found: {e}")

    except ConnectionError as e:
        print(f"MCP connection failed: {e}")

    except Exception as e:
        print(f"Unexpected error: {e}")

Debugging

Enable logging to debug authentication issues:

import logging

# Enable detailed logging
logging.basicConfig(level=logging.DEBUG)

# Your MCP code here...

Production Deployment

Security Best Practices

1. Key Management: Store private keys securely
2. Environment Variables: Use environment variables for sensitive paths
3. Network Security: Use TLS for network transport
4. Key Rotation: Implement key rotation policies

import os
import jacs

# Production initialization
config_path = os.getenv("JACS_CONFIG_PATH", "/etc/jacs/config.json")

agent = jacs.JacsAgent()
agent.load(config_path)

Docker Deployment

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application
COPY . .

# Create secure key directory
RUN mkdir -p /secure/keys && chmod 700 /secure/keys

# Set environment variables
ENV JACS_CONFIG_PATH=/app/jacs.config.json

# Run MCP server
CMD ["python", "mcp_server.py"]

Testing

Unit Testing MCP Tools

import pytest
import jacs
from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP
from fastmcp.client import Client
from fastmcp.client.transports import FastMCPTransport

@pytest.fixture
def jacs_agent():
    agent = jacs.JacsAgent()
    agent.load("./test.config.json")
    return agent

@pytest.fixture
def jacs_mcp_server(jacs_agent):
    server = FastMCP("Test Server")
    return JACSMCPServer(server)

async def test_authenticated_tool(jacs_mcp_server):
    @jacs_mcp_server.tool()
    def echo(text: str) -> str:
        return f"Echo: {text}"

    # Test the tool directly
    result = echo("test")
    assert "test" in result

API Reference

JACSMCPServer(mcp_server)

Wraps a FastMCP server with JACS authentication middleware.

Parameters:

• mcp_server: A FastMCP server instance

Returns: The wrapped server with JACS middleware

Example:

from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP

server = FastMCP("My Server")
authenticated = JACSMCPServer(server)
app = authenticated.sse_app()

JACSMCPClient(url, **kwargs)

Creates a FastMCP client with JACS authentication interceptors.

Parameters:

• url: The MCP server SSE endpoint URL
• **kwargs: Additional arguments passed to the FastMCP Client

Returns: A FastMCP Client with JACS interceptors

Example:

from jacs.mcp import JACSMCPClient

client = JACSMCPClient("http://localhost:8000/sse")
async with client:
    result = await client.call_tool("my_tool", {"arg": "value"})

Module Functions

These functions are used internally by the MCP integration:

• jacs.sign_request(data) - Sign a request payload
• jacs.verify_request(data) - Verify an incoming request
• jacs.sign_response(data) - Sign a response payload
• jacs.verify_response(data) - Verify an incoming response

Next Steps

• FastMCP Integration - Advanced FastMCP patterns
• API Reference - Complete API documentation
• Examples - More complex examples

API Reference

Complete API documentation for the jacs Python package.

Installation

pip install jacs

Core Module

import jacs
from jacs import JacsAgent

JacsAgent Class

The JacsAgent class is the primary interface for JACS operations. Each instance maintains its own state and can be used independently, allowing multiple agents in the same process.

Constructor

JacsAgent()

Creates a new empty JacsAgent instance. Call load() to initialize with a configuration.

Example:

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

agent.load(config_path)

Load and initialize the agent from a configuration file.

Parameters:

• config_path (str): Path to the JACS configuration file

Returns: str - The loaded agent's JSON

Example:

agent = jacs.JacsAgent()
agent_json = agent.load('./jacs.config.json')
print('Agent loaded:', json.loads(agent_json)['jacsId'])

agent.create_document(document_string, custom_schema=None, output_filename=None, no_save=False, attachments=None, embed=False)

Create and sign a new JACS document.

Parameters:

• document_string (str): JSON string of the document content
• custom_schema (str, optional): Path to a custom JSON Schema for validation
• output_filename (str, optional): Filename to save the document
• no_save (bool, optional): If True, don't save to storage (default: False)
• attachments (str, optional): Path to file attachments
• embed (bool, optional): If True, embed attachments in the document

Returns: str - The signed document as a JSON string

Example:

# Basic document creation
doc = agent.create_document(json.dumps({
    'title': 'My Document',
    'content': 'Hello, World!'
}))

# With custom schema
validated_doc = agent.create_document(
    json.dumps({'title': 'Validated', 'amount': 100}),
    custom_schema='./schemas/invoice.schema.json'
)

# Without saving
temp_doc = agent.create_document(
    json.dumps({'data': 'temporary'}),
    no_save=True
)

# With attachments
doc_with_file = agent.create_document(
    json.dumps({'report': 'Monthly Report'}),
    attachments='./report.pdf',
    embed=True
)

agent.verify_document(document_string)

Verify a document's signature and hash integrity.

Parameters:

• document_string (str): The signed document JSON string

Returns: bool - True if the document is valid

Example:

is_valid = agent.verify_document(signed_document_json)
if is_valid:
    print('Document signature verified')
else:
    print('Document verification failed')

agent.verify_signature(document_string, signature_field=None)

Verify a document's signature with an optional custom signature field.

Parameters:

• document_string (str): The signed document JSON string
• signature_field (str, optional): Name of the signature field (default: 'jacsSignature')

Returns: bool - True if the signature is valid

Example:

# Verify default signature field
is_valid = agent.verify_signature(doc_json)

# Verify custom signature field
is_valid_custom = agent.verify_signature(doc_json, 'customSignature')

agent.update_document(document_key, new_document_string, attachments=None, embed=False)

Update an existing document, creating a new version.

Parameters:

• document_key (str): The document key in format "id:version"
• new_document_string (str): The modified document as JSON string
• attachments (list, optional): List of attachment file paths
• embed (bool, optional): If True, embed attachments

Returns: str - The updated document as a JSON string

Example:

# Parse existing document to get key
doc = json.loads(signed_doc)
document_key = f"{doc['jacsId']}:{doc['jacsVersion']}"

# Update the document
updated_doc = agent.update_document(
    document_key,
    json.dumps({
        **doc,
        'title': 'Updated Title',
        'content': 'Modified content'
    })
)

agent.create_agreement(document_string, agent_ids, question=None, context=None, agreement_field_name=None)

Add an agreement requiring multiple agent signatures to a document.

Parameters:

• document_string (str): The document JSON string
• agent_ids (list): List of agent IDs required to sign
• question (str, optional): The agreement question
• context (str, optional): Additional context for the agreement
• agreement_field_name (str, optional): Field name for the agreement (default: 'jacsAgreement')

Returns: str - The document with agreement as a JSON string

Example:

doc_with_agreement = agent.create_agreement(
    signed_document_json,
    ['agent-1-uuid', 'agent-2-uuid', 'agent-3-uuid'],
    question='Do you agree to these terms?',
    context='Q1 2024 Service Agreement',
    agreement_field_name='jacsAgreement'
)

agent.sign_agreement(document_string, agreement_field_name=None)

Sign an agreement as the current agent.

Parameters:

• document_string (str): The document with agreement JSON string
• agreement_field_name (str, optional): Field name of the agreement (default: 'jacsAgreement')

Returns: str - The document with this agent's signature added

Example:

signed_agreement = agent.sign_agreement(
    doc_with_agreement_json,
    'jacsAgreement'
)

agent.check_agreement(document_string, agreement_field_name=None)

Check the status of an agreement (which agents have signed).

Parameters:

• document_string (str): The document with agreement JSON string
• agreement_field_name (str, optional): Field name of the agreement (default: 'jacsAgreement')

Returns: str - JSON string with agreement status

Example:

status_json = agent.check_agreement(signed_agreement_json)
status = json.loads(status_json)

print('Required signers:', status['required'])
print('Signatures received:', status['signed'])
print('Complete:', status['complete'])

agent.sign_string(data)

Sign arbitrary string data with the agent's private key.

Parameters:

• data (str): The data to sign

Returns: str - Base64-encoded signature

Example:

signature = agent.sign_string('Important message')
print('Signature:', signature)

agent.verify_string(data, signature_base64, public_key, public_key_enc_type)

Verify a signature on arbitrary string data.

Parameters:

• data (str): The original data
• signature_base64 (str): The base64-encoded signature
• public_key (bytes): The public key as bytes
• public_key_enc_type (str): The key algorithm (e.g., 'ring-Ed25519')

Returns: bool - True if the signature is valid

Example:

is_valid = agent.verify_string(
    'Important message',
    signature_base64,
    public_key_bytes,
    'ring-Ed25519'
)

agent.sign_request(params)

Sign a request payload, wrapping it in a JACS document.

Parameters:

• params (any): The request payload (will be JSON serialized)

Returns: str - JACS-signed request as a JSON string

Example:

signed_request = agent.sign_request({
    'method': 'GET',
    'path': '/api/data',
    'timestamp': datetime.now().isoformat(),
    'body': {'query': 'value'}
})

agent.verify_response(document_string)

Verify a JACS-signed response and extract the payload.

Parameters:

• document_string (str): The JACS-signed response

Returns: dict - Dictionary containing the verified payload

Example:

result = agent.verify_response(jacs_response_string)
payload = result.get('payload')
print('Verified payload:', payload)

agent.verify_response_with_agent_id(document_string)

Verify a response and return both the payload and signer's agent ID.

Parameters:

• document_string (str): The JACS-signed response

Returns: dict - Dictionary with payload and agent ID

Example:

result = agent.verify_response_with_agent_id(jacs_response_string)
print('Payload:', result['payload'])
print('Signed by agent:', result['agentId'])

agent.verify_agent(agent_file=None)

Verify the agent's own signature and hash, or verify another agent file.

Parameters:

• agent_file (str, optional): Path to an agent file to verify

Returns: bool - True if the agent is valid

Example:

# Verify the loaded agent
is_valid = agent.verify_agent()

# Verify another agent file
is_other_valid = agent.verify_agent('./other-agent.json')

agent.update_agent(new_agent_string)

Update the agent document with new data.

Parameters:

• new_agent_string (str): The modified agent document as JSON string

Returns: str - The updated agent document

Example:

current_agent = json.loads(agent.load('./jacs.config.json'))
updated_agent = agent.update_agent(json.dumps({
    **current_agent,
    'description': 'Updated description'
}))

agent.sign_agent(agent_string, public_key, public_key_enc_type)

Sign another agent's document with a registration signature.

Parameters:

• agent_string (str): The agent document to sign
• public_key (bytes): The public key as bytes
• public_key_enc_type (str): The key algorithm

Returns: str - The signed agent document

Example:

signed_agent = agent.sign_agent(
    external_agent_json,
    public_key_bytes,
    'ring-Ed25519'
)

Module-Level Functions

These functions operate on a global agent singleton and are maintained for backwards compatibility. New code should use the JacsAgent class instead.

jacs.load(config_path)

Load the global agent from a configuration file.

import jacs
jacs.load('./jacs.config.json')

jacs.sign_request(data)

Sign a request using the global agent.

signed = jacs.sign_request({'method': 'tools/call', 'params': {...}})

jacs.verify_request(data)

Verify an incoming request using the global agent.

payload = jacs.verify_request(incoming_request_string)

jacs.sign_response(data)

Sign a response using the global agent.

signed = jacs.sign_response({'result': 'success'})

jacs.verify_response(data)

Verify an incoming response using the global agent.

result = jacs.verify_response(response_string)
payload = result.get('payload')

MCP Module

from jacs.mcp import JACSMCPServer, JACSMCPClient

JACSMCPServer(mcp_server)

Wraps a FastMCP server with JACS authentication middleware.

Parameters:

• mcp_server: A FastMCP server instance

Returns: The wrapped server with JACS middleware

Example:

from jacs.mcp import JACSMCPServer
from fastmcp import FastMCP

server = FastMCP("My Server")
authenticated = JACSMCPServer(server)
app = authenticated.sse_app()

JACSMCPClient(url, **kwargs)

Creates a FastMCP client with JACS authentication interceptors.

Parameters:

• url: The MCP server SSE endpoint URL
• **kwargs: Additional arguments passed to the FastMCP Client

Returns: A FastMCP Client with JACS interceptors

Example:

from jacs.mcp import JACSMCPClient

client = JACSMCPClient("http://localhost:8000/sse")
async with client:
    result = await client.call_tool("my_tool", {"arg": "value"})

Configuration

Configuration File Format

Create a jacs.config.json file:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_agent_id_and_version": "your-agent-id:version",
  "jacs_agent_key_algorithm": "ring-Ed25519",
  "jacs_agent_private_key_filename": "private.pem",
  "jacs_agent_public_key_filename": "public.pem",
  "jacs_data_directory": "./jacs_data",
  "jacs_default_storage": "fs",
  "jacs_key_directory": "./jacs_keys"
}

Configuration Options

Error Handling

All methods may raise exceptions. Use try/except for error handling:

try:
    agent = jacs.JacsAgent()
    agent.load('./jacs.config.json')
    doc = agent.create_document(json.dumps({'data': 'test'}))
except FileNotFoundError as e:
    print(f'Configuration file not found: {e}')
except ValueError as e:
    print(f'Invalid configuration: {e}')
except Exception as e:
    print(f'JACS error: {e}')

Common Exceptions

Type Hints

The package supports type hints for better IDE integration:

from jacs import JacsAgent
import json

def process_document(agent: JacsAgent, data: dict) -> str:
    """Create and return a signed document."""
    doc_string = json.dumps(data)
    return agent.create_document(doc_string)

def verify_and_extract(agent: JacsAgent, doc: str) -> dict:
    """Verify document and extract content."""
    if agent.verify_document(doc):
        return json.loads(doc)
    raise ValueError("Document verification failed")

Thread Safety

JacsAgent instances use internal locking and are thread-safe. You can safely use the same agent instance across multiple threads:

import threading
from jacs import JacsAgent

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

def worker(data):
    # Safe to call from multiple threads
    doc = agent.create_document(json.dumps(data))
    return doc

threads = [
    threading.Thread(target=worker, args=({'id': i},))
    for i in range(10)
]
for t in threads:
    t.start()
for t in threads:
    t.join()

See Also

• Installation - Getting started
• Basic Usage - Common usage patterns
• MCP Integration - Model Context Protocol
• Examples - More complex examples

JSON Schemas

JACS uses JSON Schema (Draft-07) to define the structure and validation rules for all documents in the system. These schemas ensure consistency, enable validation, and provide a contract for interoperability between agents.

Schema Architecture

JACS schemas follow a hierarchical composition pattern:

┌─────────────────────────────────────────────────────────┐
│                    Document Schemas                      │
│  (agent.schema.json, task.schema.json, message.schema.json)  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Header Schema                          │
│              (header.schema.json)                        │
│  Base fields: jacsId, jacsVersion, jacsSignature, etc.  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                 Component Schemas                        │
│   signature.schema.json, agreement.schema.json,         │
│   files.schema.json, embedding.schema.json, etc.        │
└─────────────────────────────────────────────────────────┘

Schema Categories

Configuration Schema

Document Schemas

Component Schemas

Schema Locations

Schemas are available at:

• HTTPS URLs: https://hai.ai/schemas/...
• Local files: jacs/schemas/...

Example schema URLs:

https://hai.ai/schemas/jacs.config.schema.json
https://hai.ai/schemas/header/v1/header.schema.json
https://hai.ai/schemas/agent/v1/agent.schema.json
https://hai.ai/schemas/components/signature/v1/signature.schema.json

Using Schemas

In Documents

Every JACS document must include a $schema field:

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsType": "agent",
  ...
}

In Configuration Files

Reference the config schema for IDE support:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  ...
}

Custom Schema Validation

Validate documents against custom schemas:

import jacs
import json

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

# Create document with custom schema
doc = agent.create_document(
    json.dumps({'invoice_id': 'INV-001', 'amount': 100.00}),
    custom_schema='./schemas/invoice.schema.json'
)

import { JacsAgent } from 'jacsnpm';

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

// Create document with custom schema
const doc = agent.createDocument(
  JSON.stringify({ invoice_id: 'INV-001', amount: 100.00 }),
  './schemas/invoice.schema.json'
);

HAI Extensions

JACS schemas include a custom hai property that categorizes fields:

This categorization helps determine which fields should be included in hash calculations and signature operations.

Versioning

Schemas are versioned using directory paths:

schemas/
├── header/
│   └── v1/
│       └── header.schema.json
├── agent/
│   └── v1/
│       └── agent.schema.json
└── components/
    └── signature/
        └── v1/
            └── signature.schema.json

Configuration options allow specifying schema versions:

{
  "jacs_agent_schema_version": "v1",
  "jacs_header_schema_version": "v1",
  "jacs_signature_schema_version": "v1"
}

Schema Composition

Document schemas use JSON Schema's allOf to compose the header with type-specific fields:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    {
      "type": "object",
      "properties": {
        "jacsAgentType": { ... },
        "jacsServices": { ... }
      }
    }
  ]
}

This ensures all documents share common header fields while allowing type-specific extensions.

Creating Custom Schemas

Create custom schemas that extend JACS schemas:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/schemas/invoice.schema.json",
  "title": "Invoice",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    {
      "type": "object",
      "properties": {
        "invoiceNumber": {
          "type": "string",
          "description": "Unique invoice identifier"
        },
        "amount": {
          "type": "number",
          "minimum": 0,
          "description": "Invoice amount"
        },
        "currency": {
          "type": "string",
          "enum": ["USD", "EUR", "GBP"],
          "default": "USD"
        },
        "lineItems": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "description": { "type": "string" },
              "quantity": { "type": "integer", "minimum": 1 },
              "unitPrice": { "type": "number", "minimum": 0 }
            },
            "required": ["description", "quantity", "unitPrice"]
          }
        }
      },
      "required": ["invoiceNumber", "amount"]
    }
  ]
}

Validation Rules

Required Fields

All JACS documents require these header fields:

• jacsId - Unique document identifier (UUID v4)
• jacsType - Document type identifier
• jacsVersion - Version identifier (UUID v4)
• jacsVersionDate - Version timestamp (ISO 8601)
• jacsOriginalVersion - First version identifier
• jacsOriginalDate - Creation timestamp
• jacsLevel - Document level (raw, config, artifact, derived)
• $schema - Schema reference URL

Format Validation

Fields use JSON Schema format keywords:

• uuid - UUID v4 format
• date-time - ISO 8601 date-time format
• uri - Valid URI format

Enum Constraints

Many fields have enumerated valid values:

{
  "jacsLevel": {
    "enum": ["raw", "config", "artifact", "derived"]
  },
  "jacsAgentType": {
    "enum": ["human", "human-org", "hybrid", "ai"]
  },
  "jacs_agent_key_algorithm": {
    "enum": ["RSA-PSS", "ring-Ed25519", "pq-dilithium", "pq2025"]
  }
}

Schema Reference

For detailed documentation on specific schemas:

• Agent Schema - Agent identity and capabilities
• Document Schema - Document header and structure
• Task Schema - Task workflow management
• Configuration - Configuration file format

See Also

• Custom Schemas - Creating custom document types
• Security Model - How schemas relate to security
• API Reference - Using schemas in code

Agent Schema

The Agent Schema defines the structure for agent identity documents in JACS. Agents represent entities that can sign documents, participate in agreements, and provide services.

Schema Location

https://hai.ai/schemas/agent/v1/agent.schema.json

Overview

Agent documents describe:

• Identity: Unique identifiers and versioning
• Type: Human, organizational, hybrid, or AI classification
• Services: Capabilities the agent offers
• Contacts: How to reach human or hybrid agents
• Domain: Optional DNS-based verification

Schema Structure

The agent schema extends the Header Schema using JSON Schema composition:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "title": "Agent",
  "description": "General schema for human, hybrid, and AI agents",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    { "type": "object", "properties": { ... } }
  ]
}

Agent Types

The jacsAgentType field classifies the agent:

{
  "jacsAgentType": {
    "type": "string",
    "enum": ["human", "human-org", "hybrid", "ai"]
  }
}

Contact Requirements

Human and hybrid agents must provide contact information:

{
  "if": {
    "properties": {
      "jacsAgentType": { "enum": ["human", "human-org", "hybrid"] }
    }
  },
  "then": {
    "required": ["jacsContacts"]
  }
}

Agent Properties

Core Fields (from Header)

All agents inherit these header fields:

Agent-Specific Fields

Services

Services describe capabilities the agent offers:

{
  "jacsServices": [{
    "name": "Document Signing Service",
    "serviceDescription": "Sign and verify JACS documents",
    "successDescription": "Documents are signed with valid signatures",
    "failureDescription": "Invalid documents or signing errors",
    "costDescription": "Free for basic usage, paid tiers available",
    "idealCustomerDescription": "Developers building secure agent systems",
    "termsOfService": "https://example.com/tos",
    "privacyPolicy": "https://example.com/privacy",
    "isDev": false,
    "tools": [...]
  }]
}

Service Schema Fields

PII Types

Services can declare what personally identifiable information they need:

{
  "piiDesired": ["email", "phone", "address"]
}

Valid PII types:

• signature - Digital signatures
• cryptoaddress - Cryptocurrency addresses
• creditcard - Payment card numbers
• govid - Government identification
• social - Social security numbers
• email - Email addresses
• phone - Phone numbers
• address - Physical addresses
• zip - Postal codes
• PHI - Protected health information
• MHI - Mental health information
• identity - Identity documents
• political - Political affiliation
• bankaddress - Banking information
• income - Income data

Contacts

Contact information for human and hybrid agents:

{
  "jacsContacts": [{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+1-555-0123",
    "isPrimary": true,
    "mailAddress": "123 Main St",
    "mailState": "CA",
    "mailZip": "94102",
    "mailCountry": "USA"
  }]
}

Contact Schema Fields

DNS Verification

Agents can link to a domain for DNSSEC-validated verification:

{
  "jacsAgentDomain": "example.com"
}

The domain should have a DNS TXT record at _v1.agent.jacs.example.com. containing the agent's public key fingerprint.

See the DNS chapter for complete setup instructions.

Complete Example

AI Agent

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsType": "agent",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",
  "jacsAgentType": "ai",
  "jacsServices": [{
    "name": "Code Review Service",
    "serviceDescription": "Automated code review and analysis",
    "successDescription": "Review completed with actionable feedback",
    "failureDescription": "Unable to process or analyze code",
    "isDev": false
  }],
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "base64-encoded-signature...",
    "publicKeyHash": "sha256-hash-of-public-key",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsVersion", "jacsAgentType", "jacsServices"]
  },
  "jacsSha256": "document-hash..."
}

Human Agent

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "660e8400-e29b-41d4-a716-446655440001",
  "jacsVersion": "a47ac10b-58cc-4372-a567-0e02b2c3d480",
  "jacsVersionDate": "2024-01-15T11:00:00Z",
  "jacsType": "agent",
  "jacsOriginalVersion": "a47ac10b-58cc-4372-a567-0e02b2c3d480",
  "jacsOriginalDate": "2024-01-15T11:00:00Z",
  "jacsLevel": "artifact",
  "jacsAgentType": "human",
  "jacsAgentDomain": "smith.example.com",
  "jacsServices": [{
    "name": "Consulting",
    "serviceDescription": "Technical consulting services",
    "successDescription": "Project goals achieved",
    "failureDescription": "Unable to meet requirements",
    "termsOfService": "https://smith.example.com/tos"
  }],
  "jacsContacts": [{
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@smith.example.com",
    "isPrimary": true
  }]
}

Organization Agent

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "770e8400-e29b-41d4-a716-446655440002",
  "jacsVersion": "b47ac10b-58cc-4372-a567-0e02b2c3d481",
  "jacsVersionDate": "2024-01-15T12:00:00Z",
  "jacsType": "agent",
  "jacsOriginalVersion": "b47ac10b-58cc-4372-a567-0e02b2c3d481",
  "jacsOriginalDate": "2024-01-15T12:00:00Z",
  "jacsLevel": "artifact",
  "jacsAgentType": "human-org",
  "jacsAgentDomain": "acme.com",
  "jacsServices": [{
    "name": "Enterprise Software",
    "serviceDescription": "Enterprise software solutions",
    "successDescription": "Software deployed and operational",
    "failureDescription": "Deployment or integration failure",
    "privacyPolicy": "https://acme.com/privacy",
    "piiDesired": ["email", "phone"]
  }],
  "jacsContacts": [{
    "addressName": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1-800-555-ACME",
    "mailAddress": "1 Corporate Plaza",
    "mailState": "NY",
    "mailZip": "10001",
    "mailCountry": "USA",
    "isPrimary": true
  }]
}

Creating Agents

Python

import jacs
import json

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

# The agent is created during configuration setup
# Agent document is available after loading
agent_json = agent.load('./jacs.config.json')
agent_doc = json.loads(agent_json)

print(f"Agent ID: {agent_doc['jacsId']}")
print(f"Agent Type: {agent_doc['jacsAgentType']}")

Node.js

import { JacsAgent } from 'jacsnpm';

const agent = new JacsAgent();
const agentJson = agent.load('./jacs.config.json');
const agentDoc = JSON.parse(agentJson);

console.log(`Agent ID: ${agentDoc.jacsId}`);
console.log(`Agent Type: ${agentDoc.jacsAgentType}`);

CLI

# Create a new agent
jacs agent create

# View agent details
jacs agent show

Verifying Agents

# Verify the loaded agent
is_valid = agent.verify_agent()

# Verify another agent file
is_valid = agent.verify_agent('./other-agent.json')

// Verify the loaded agent
const isValid = agent.verifyAgent();

// Verify another agent file
const isOtherValid = agent.verifyAgent('./other-agent.json');

See Also

• Document Schema - Header fields documentation
• Task Schema - Task workflow schema
• DNS Verification - Setting up domain verification
• Creating an Agent - Agent creation guide

Document Schema

The Document Schema (Header Schema) defines the base structure for all JACS documents. Every JACS document type (agents, tasks, messages, etc.) extends this schema.

Schema Location

https://hai.ai/schemas/header/v1/header.schema.json

Overview

The header schema provides:

• Unique Identification: Every document has a unique ID and version
• Version Tracking: Full history with previous version references
• Cryptographic Integrity: Signatures and hashes for verification
• File Attachments: Support for embedded or linked files
• Vector Embeddings: Pre-computed embeddings for semantic search
• Agreements: Multi-party signature support

Core Fields

Identification

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsType": "document"
}

Versioning

{
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsPreviousVersion": "e36ac10b-58cc-4372-a567-0e02b2c3d478",
  "jacsOriginalVersion": "a47ac10b-58cc-4372-a567-0e02b2c3d476",
  "jacsOriginalDate": "2024-01-01T09:00:00Z"
}

Document Level

The jacsLevel field indicates the intended use:

{
  "jacsLevel": "artifact"
}

Cryptographic Fields

Signature

The jacsSignature field contains the creator's cryptographic signature:

{
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "base64-encoded-signature-string",
    "publicKeyHash": "sha256-hash-of-public-key",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsVersion", "jacsType", "content"]
  }
}

Signature Schema Fields

Registration

The jacsRegistration field contains a signature from a registration authority:

{
  "jacsRegistration": {
    "agentID": "registrar-agent-id",
    "agentVersion": "registrar-version",
    "date": "2024-01-15T10:35:00Z",
    "signature": "registrar-signature",
    "publicKeyHash": "registrar-key-hash",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsSignature"]
  }
}

Hash

The jacsSha256 field contains a SHA-256 hash of all document content (excluding this field):

{
  "jacsSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Agreements

Documents can include multi-party agreements using jacsAgreement:

{
  "jacsAgreement": {
    "agentIDs": [
      "agent-1-uuid",
      "agent-2-uuid",
      "agent-3-uuid"
    ],
    "question": "Do you agree to these terms?",
    "context": "Q1 2024 Service Agreement",
    "signatures": [
      {
        "agentID": "agent-1-uuid",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-15T11:00:00Z"
      }
    ]
  },
  "jacsAgreementHash": "hash-of-content-at-agreement-time"
}

Agreement Schema Fields

File Attachments

Documents can include file attachments using jacsFiles:

{
  "jacsFiles": [
    {
      "mimetype": "application/pdf",
      "path": "./documents/contract.pdf",
      "embed": true,
      "contents": "base64-encoded-file-contents",
      "sha256": "file-content-hash"
    },
    {
      "mimetype": "image/png",
      "path": "./images/diagram.png",
      "embed": false,
      "sha256": "file-content-hash"
    }
  ]
}

File Schema Fields

Vector Embeddings

Documents can include pre-computed embeddings for semantic search:

{
  "jacsEmbedding": [
    {
      "llm": "text-embedding-ada-002",
      "vector": [0.0023, -0.0089, 0.0156, ...]
    }
  ]
}

Embedding Schema Fields

Complete Example

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsType": "document",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",

  "title": "Sample Document",
  "content": "This is the document content.",

  "jacsFiles": [
    {
      "mimetype": "application/pdf",
      "path": "./attachment.pdf",
      "embed": false,
      "sha256": "abc123..."
    }
  ],

  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "signature-base64...",
    "publicKeyHash": "key-hash...",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsVersion", "title", "content"]
  },

  "jacsSha256": "document-hash..."
}

HAI Field Categories

Fields include a hai property indicating their category:

This categorization determines which fields are included in hash and signature calculations.

Working with Documents

Creating Documents

import jacs
import json

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

# Create a basic document
doc = agent.create_document(json.dumps({
    'title': 'My Document',
    'content': 'Document content here'
}))

import { JacsAgent } from 'jacsnpm';

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

const doc = agent.createDocument(JSON.stringify({
  title: 'My Document',
  content: 'Document content here'
}));

Verifying Documents

is_valid = agent.verify_document(doc_json)

const isValid = agent.verifyDocument(docJson);

Updating Documents

doc = json.loads(signed_doc)
document_key = f"{doc['jacsId']}:{doc['jacsVersion']}"

updated = agent.update_document(
    document_key,
    json.dumps({**doc, 'content': 'Updated content'})
)

const doc = JSON.parse(signedDoc);
const documentKey = `${doc.jacsId}:${doc.jacsVersion}`;

const updated = agent.updateDocument(
  documentKey,
  JSON.stringify({...doc, content: 'Updated content'})
);

Adding Attachments

doc = agent.create_document(
    json.dumps({'title': 'Report'}),
    attachments='./report.pdf',
    embed=True
)

const doc = agent.createDocument(
  JSON.stringify({ title: 'Report' }),
  null,    // custom_schema
  null,    // output_filename
  false,   // no_save
  './report.pdf',  // attachments
  true     // embed
);

Version History

Documents maintain a version chain:

Original (v1) ← Previous (v2) ← Current (v3)
     │
     └── jacsOriginalVersion points here for all versions

Each version:

• Has its own jacsVersion UUID
• References jacsPreviousVersion (except the first)
• All share the same jacsId and jacsOriginalVersion

See Also

• Agent Schema - Agent document structure
• Task Schema - Task document structure
• Working with Documents - Document operations guide
• Agreements - Multi-party agreements

Task Schema

The Task Schema defines the structure for task documents in JACS. Tasks represent work items with defined states, assigned agents, and completion criteria.

Schema Location

https://hai.ai/schemas/task/v1/task.schema.json

Overview

Task documents manage:

• Workflow States: From creation through completion
• Agent Assignment: Customer and assigned agent tracking
• Actions: Desired outcomes and completion criteria
• Agreements: Start and end agreements between parties
• Relationships: Sub-tasks, copies, and merges

Schema Structure

The task schema extends the Header Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://hai.ai/schemas/task/v1/task-schema.json",
  "title": "Task",
  "description": "General schema for stateful resources.",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    { "type": "object", "properties": { ... } }
  ]
}

Task States

Tasks progress through defined workflow states:

{
  "jacsTaskState": "started"
}

State Transitions

creating → rfp → proposal → negotiation → started → review → completed
                    ↑_______________|
                (may cycle back for renegotiation)

Task Properties

Core Fields (from Header)

Tasks inherit all document header fields plus task-specific fields.

Task-Specific Fields

Relationship Fields

Actions

Actions define what needs to be accomplished:

{
  "jacsTaskActionsDesired": [
    {
      "name": "Create API Endpoint",
      "description": "Build REST endpoint for user registration",
      "cost": {
        "value": 500,
        "unit": "USD"
      },
      "duration": {
        "value": 8,
        "unit": "hours"
      },
      "completionAgreementRequired": true,
      "tools": [...]
    }
  ]
}

Action Schema Fields

Unit Schema

Costs and durations use the unit schema:

{
  "cost": {
    "value": 100,
    "unit": "USD"
  },
  "duration": {
    "value": 2,
    "unit": "days"
  }
}

Agreements

Tasks can include start and end agreements:

Start Agreement

Signed when parties agree to begin work:

{
  "jacsStartAgreement": {
    "agentIDs": ["customer-uuid", "agent-uuid"],
    "question": "Do you agree to begin this work?",
    "context": "Project XYZ - Phase 1",
    "signatures": [...]
  }
}

End Agreement

Signed when parties agree work is complete:

{
  "jacsEndAgreement": {
    "agentIDs": ["customer-uuid", "agent-uuid"],
    "question": "Do you agree this work is complete?",
    "context": "Final deliverables reviewed",
    "signatures": [...]
  }
}

Complete Example

{
  "$schema": "https://hai.ai/schemas/task/v1/task.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsType": "task",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",

  "jacsTaskName": "Build Authentication System",
  "jacsTaskSuccess": "Users can register, login, and manage sessions",
  "jacsTaskState": "started",

  "jacsTaskCustomer": {
    "agentID": "customer-agent-uuid",
    "agentVersion": "customer-version-uuid",
    "date": "2024-01-15T10:30:00Z",
    "signature": "customer-signature...",
    "publicKeyHash": "customer-key-hash",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsTaskName", "jacsTaskActionsDesired"]
  },

  "jacsTaskAgent": {
    "agentID": "assigned-agent-uuid",
    "agentVersion": "agent-version-uuid",
    "date": "2024-01-16T09:00:00Z",
    "signature": "agent-signature...",
    "publicKeyHash": "agent-key-hash",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsTaskName", "jacsTaskActionsDesired"]
  },

  "jacsTaskStartDate": "2024-01-16T09:00:00Z",

  "jacsStartAgreement": {
    "agentIDs": ["customer-agent-uuid", "assigned-agent-uuid"],
    "question": "Do you agree to begin work on this task?",
    "signatures": [
      {
        "agentID": "customer-agent-uuid",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-16T09:00:00Z"
      },
      {
        "agentID": "assigned-agent-uuid",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-16T09:05:00Z"
      }
    ]
  },

  "jacsTaskActionsDesired": [
    {
      "name": "User Registration",
      "description": "Implement user registration with email verification",
      "duration": { "value": 4, "unit": "hours" },
      "completionAgreementRequired": true
    },
    {
      "name": "User Login",
      "description": "Implement secure login with password hashing",
      "duration": { "value": 3, "unit": "hours" },
      "completionAgreementRequired": true
    },
    {
      "name": "Session Management",
      "description": "Implement JWT-based session tokens",
      "duration": { "value": 2, "unit": "hours" },
      "completionAgreementRequired": false
    }
  ],

  "jacsSignature": {
    "agentID": "customer-agent-uuid",
    "agentVersion": "customer-version-uuid",
    "date": "2024-01-15T10:30:00Z",
    "signature": "document-signature...",
    "publicKeyHash": "key-hash...",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsTaskName", "jacsTaskActionsDesired"]
  }
}

Task Relationships

Sub-Tasks

Break large tasks into smaller units:

{
  "jacsTaskSubTaskOf": ["parent-task-uuid"]
}

Task Copies (Branching)

Create variations or branches:

{
  "jacsTaskCopyOf": ["original-task-uuid"]
}

Merged Tasks

Combine completed tasks:

{
  "jacsTaskMergedTasks": [
    "subtask-1-uuid",
    "subtask-2-uuid"
  ]
}

Task Workflow

1. Creating a Task

import jacs
import json

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

task = agent.create_document(json.dumps({
    'jacsTaskName': 'Build Feature X',
    'jacsTaskSuccess': 'Feature is deployed and tested',
    'jacsTaskState': 'creating',
    'jacsTaskActionsDesired': [
        {
            'name': 'Implementation',
            'description': 'Write the code',
            'completionAgreementRequired': True
        }
    ]
}), custom_schema='https://hai.ai/schemas/task/v1/task.schema.json')

2. Assigning an Agent

When an agent accepts the task, add their signature to jacsTaskAgent and update state to started.

3. Signing Start Agreement

Both parties sign the start agreement to confirm work begins.

4. Completing Work

Update state to review, then both parties sign the end agreement.

5. Final Completion

After end agreement is signed by all parties, update state to completed.

State Machine Rules

See Also

• Document Schema - Base document fields
• Agent Schema - Agent structure
• Agreements - Working with agreements
• JSON Schemas Overview - Schema architecture

Configuration

The JACS configuration file (jacs.config.json) defines agent settings, key locations, storage backends, and observability options.

Schema Location

https://hai.ai/schemas/jacs.config.schema.json

Quick Start

Create a minimal configuration file:

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

Required Fields

Configuration Options

Key Configuration

jacs_agent_key_algorithm

Specifies the cryptographic algorithm for signing:

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

jacs_agent_private_key_filename

Name of the private key file in the key directory:

{
  "jacs_agent_private_key_filename": "private.pem"
}

If the key is encrypted, it will have .enc appended automatically when loading.

jacs_agent_public_key_filename

Name of the public key file:

{
  "jacs_agent_public_key_filename": "public.pem"
}

jacs_private_key_password

Password for encrypted private keys:

{
  "jacs_private_key_password": "your-password"
}

Warning: Do not store passwords in config files for production. Use the JACS_AGENT_PRIVATE_KEY_PASSWORD environment variable instead.

Storage Configuration

jacs_default_storage

Specifies where documents are stored:

{
  "jacs_default_storage": "fs"
}

jacs_data_directory

Path for storing documents and agents:

{
  "jacs_data_directory": "./jacs_data"
}

Agent Identity

jacs_agent_id_and_version

Load an existing agent by ID and version:

{
  "jacs_agent_id_and_version": "550e8400-e29b-41d4-a716-446655440000:f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Schema Versions

Specify which schema versions to use:

{
  "jacs_agent_schema_version": "v1",
  "jacs_header_schema_version": "v1",
  "jacs_signature_schema_version": "v1"
}

DNS Configuration

For DNSSEC-based agent verification:

jacs_agent_domain

Domain for DNS-based public key verification:

{
  "jacs_agent_domain": "example.com"
}

jacs_dns_validate

Enable DNS TXT fingerprint validation:

{
  "jacs_dns_validate": true
}

jacs_dns_strict

Require DNSSEC validation (no fallback):

{
  "jacs_dns_strict": true
}

jacs_dns_required

Require domain and DNS validation:

{
  "jacs_dns_required": true
}

Security

jacs_use_security

Enable strict security features:

{
  "jacs_use_security": "1"
}

Values: "0", "1", or "false", "true"

Observability Configuration

JACS supports comprehensive observability through logs, metrics, and tracing.

Logs Configuration

{
  "observability": {
    "logs": {
      "enabled": true,
      "level": "info",
      "destination": {
        "type": "stderr"
      }
    }
  }
}

Log Levels

Log Destinations

stderr (default):

{
  "destination": { "type": "stderr" }
}

File:

{
  "destination": {
    "type": "file",
    "path": "/var/log/jacs/app.log"
  }
}

OTLP (OpenTelemetry):

{
  "destination": {
    "type": "otlp",
    "endpoint": "http://localhost:4317",
    "headers": {
      "Authorization": "Bearer token"
    }
  }
}

Null (disabled):

{
  "destination": { "type": "null" }
}

Metrics Configuration

{
  "observability": {
    "metrics": {
      "enabled": true,
      "destination": {
        "type": "prometheus",
        "endpoint": "http://localhost:9090/api/v1/write"
      },
      "export_interval_seconds": 60
    }
  }
}

Metrics Destinations

Prometheus:

{
  "destination": {
    "type": "prometheus",
    "endpoint": "http://localhost:9090/api/v1/write"
  }
}

OTLP:

{
  "destination": {
    "type": "otlp",
    "endpoint": "http://localhost:4317"
  }
}

File:

{
  "destination": {
    "type": "file",
    "path": "/var/log/jacs/metrics.json"
  }
}

stdout:

{
  "destination": { "type": "stdout" }
}

Tracing Configuration

{
  "observability": {
    "tracing": {
      "enabled": true,
      "sampling": {
        "ratio": 0.1,
        "parent_based": true,
        "rate_limit": 100
      },
      "resource": {
        "service_name": "my-jacs-agent",
        "service_version": "1.0.0",
        "environment": "production",
        "attributes": {
          "team": "backend"
        }
      }
    }
  }
}

Sampling Options

Complete Configuration Example

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",

  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  "jacs_agent_private_key_filename": "private.pem",
  "jacs_agent_public_key_filename": "public.pem",
  "jacs_agent_key_algorithm": "ring-Ed25519",
  "jacs_default_storage": "fs",

  "jacs_agent_schema_version": "v1",
  "jacs_header_schema_version": "v1",
  "jacs_signature_schema_version": "v1",

  "jacs_agent_domain": "myagent.example.com",
  "jacs_dns_validate": true,
  "jacs_dns_strict": false,

  "observability": {
    "logs": {
      "enabled": true,
      "level": "info",
      "destination": {
        "type": "file",
        "path": "/var/log/jacs/agent.log"
      }
    },
    "metrics": {
      "enabled": true,
      "destination": {
        "type": "prometheus",
        "endpoint": "http://prometheus:9090/api/v1/write"
      },
      "export_interval_seconds": 30
    },
    "tracing": {
      "enabled": true,
      "sampling": {
        "ratio": 0.1,
        "parent_based": true
      },
      "resource": {
        "service_name": "jacs-agent",
        "service_version": "1.0.0",
        "environment": "production"
      }
    }
  }
}

Environment Variables

Configuration can be overridden with environment variables:

export JACS_AGENT_PRIVATE_KEY_PASSWORD="secure-password"

Loading Configuration

Python

import jacs

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

Node.js

import { JacsAgent } from 'jacsnpm';

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

CLI

jacs --config ./jacs.config.json agent show

Production Best Practices

1. Never commit private keys - Keep keys out of version control
2. Use environment variables for secrets - Don't store passwords in config files
3. Enable observability - Configure logs and metrics for monitoring
4. Use DNS validation - Enable jacs_dns_validate for additional security
5. Secure key directories - Restrict file permissions on key directories

chmod 700 ./jacs_keys
chmod 600 ./jacs_keys/private.pem

See Also

• JSON Schemas Overview - Schema architecture
• Observability - Monitoring guide
• DNS Verification - Domain-based verification
• Quick Start - Getting started guide

Security Model

JACS implements a comprehensive security model designed to ensure authenticity, integrity, and non-repudiation for all agent communications and documents.

Core Security Principles

1. Cryptographic Identity

Every JACS agent has a unique cryptographic identity:

• Key Pair: Each agent possesses a private/public key pair
• Agent ID: Unique UUID identifying the agent
• Public Key Hash: SHA-256 hash of the public key for verification

{
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "publicKeyHash": "sha256-of-public-key",
    "signingAlgorithm": "ring-Ed25519"
  }
}

2. Document Integrity

All documents include cryptographic guarantees:

• Signature: Cryptographic signature over specified fields
• Hash: SHA-256 hash of document contents
• Version Tracking: Immutable version history

3. Non-Repudiation

Signatures provide proof of origin:

• Agents cannot deny signing a document
• Timestamps record when signatures were made
• Public keys enable independent verification

Threat Model

Protected Against

Trust Assumptions

1. Private keys are kept secure
2. Cryptographic algorithms are sound
3. DNS infrastructure (when used) is trustworthy

Signature Process

Signing a Document

1. Field Selection: Determine which fields to sign
2. Canonicalization: Serialize fields deterministically
3. Signature Generation: Sign with private key
4. Hash Computation: Compute SHA-256 of signed document

import jacs
import json

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

# Create signed document
doc = agent.create_document(json.dumps({
    'title': 'Confidential Report',
    'content': 'Sensitive data here'
}))

# Document now includes jacsSignature and jacsSha256

Verifying a Document

1. Hash Verification: Recompute hash and compare
2. Signature Verification: Verify signature with public key
3. Agent Verification: Optionally verify agent identity via DNS

is_valid = agent.verify_document(doc_json)
is_signature_valid = agent.verify_signature(doc_json)

Key Management

Key Generation

JACS generates cryptographic key pairs during agent creation:

# Keys are created in the configured key directory
jacs_keys/
├── private.pem    # Private key (keep secure!)
└── public.pem     # Public key (can be shared)

Key Protection

Encryption at Rest:

{
  "jacs_private_key_password": "NEVER_STORE_IN_CONFIG"
}

Use environment variables instead:

export JACS_AGENT_PRIVATE_KEY_PASSWORD="secure-password"

File Permissions:

chmod 700 ./jacs_keys
chmod 600 ./jacs_keys/private.pem

Key Rotation

Update agent version to rotate keys:

1. Generate new key pair
2. Create new agent version
3. Sign new version with old key
4. Update configuration to use new keys

DNS-Based Verification

JACS supports DNSSEC-validated identity verification:

How It Works

1. Agent publishes public key fingerprint in DNS TXT record
2. Verifier queries DNS for _v1.agent.jacs.<domain>.
3. DNSSEC validates the response authenticity
4. Fingerprint is compared against agent's public key

Configuration

{
  "jacs_agent_domain": "myagent.example.com",
  "jacs_dns_validate": true,
  "jacs_dns_strict": true
}

Security Levels

Agreement Security

Multi-party agreements provide additional security:

Agreement Structure

{
  "jacsAgreement": {
    "agentIDs": ["agent-1", "agent-2", "agent-3"],
    "signatures": [
      {
        "agentID": "agent-1",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-15T10:00:00Z"
      }
    ]
  },
  "jacsAgreementHash": "hash-at-agreement-time"
}

Agreement Guarantees

1. Content Lock: jacsAgreementHash ensures all parties agreed to same content
2. Individual Consent: Each signature records explicit agreement
3. Response Types: Support for agree, disagree, or reject
4. Timestamp: Records when each party signed

Request/Response Security

For MCP and HTTP communication:

Request Signing

signed_request = agent.sign_request({
    'method': 'tools/call',
    'params': {'name': 'echo', 'arguments': {'text': 'hello'}}
})

The signed request includes:

• Full JACS document structure
• Agent signature
• Timestamp
• Content hash

Response Verification

result = agent.verify_response(response_string)
payload = result.get('payload')
agent_id = result.get('agentId')  # Who signed the response

Algorithm Security

Supported Algorithms

Algorithm Selection

Choose based on requirements:

• General Use: ring-Ed25519 - fast, secure, small signatures
• Legacy Systems: RSA-PSS - widely supported
• Future-Proofing: pq-dilithium - quantum-resistant
• Transition: pq2025 - hybrid classical/post-quantum

Security Best Practices

1. Key Storage

# Never commit keys to version control
echo "jacs_keys/" >> .gitignore

# Secure file permissions
chmod 700 ./jacs_keys
chmod 600 ./jacs_keys/private.pem

2. Password Handling

# Use environment variables
export JACS_AGENT_PRIVATE_KEY_PASSWORD="$(pass show jacs/key-password)"

3. Transport Security

Always use TLS for network communication:

# HTTPS for web transport
client = JACSMCPClient("https://localhost:8000/sse")  # Good
# client = JACSMCPClient("http://localhost:8000/sse")  # Avoid in production

4. Verification Policies

{
  "jacs_dns_strict": true,
  "jacs_dns_required": true,
  "jacs_use_security": "1"
}

5. Audit Logging

Enable observability for security auditing:

{
  "observability": {
    "logs": {
      "enabled": true,
      "level": "info"
    }
  }
}

Security Checklist

Development

• Generate unique keys for each environment
• Never commit private keys
• Use test keys separate from production

Production

• Encrypt private keys at rest
• Use environment variables for secrets
• Enable DNS verification
• Configure strict security mode
• Enable audit logging
• Use TLS for all network transport
• Restrict key file permissions
• Implement key rotation policy

Verification

• Always verify documents before trusting
• Verify agent signatures
• Check agreement completeness
• Validate DNS records when required

Security Considerations

Supply Chain

• Verify JACS packages are from official sources
• Use package checksums
• Keep dependencies updated

Side Channels

• Use constant-time comparison for signatures
• Protect against timing attacks
• Secure memory handling for keys

Recovery

• Backup key material securely
• Document key recovery procedures
• Plan for key compromise scenarios

See Also

• Cryptographic Algorithms - Algorithm details
• DNS Verification - DNS-based identity
• Configuration - Security configuration
• Agreements - Multi-party agreements

Cryptographic Algorithms

JACS supports multiple cryptographic algorithms for digital signatures, providing flexibility for different security requirements and future-proofing against quantum computing threats.

Supported Algorithms

Ed25519 (ring-Ed25519)

The recommended algorithm for most use cases.

Overview

Ed25519 is an elliptic curve signature scheme using Curve25519. JACS uses the ring cryptographic library implementation.

Characteristics

• Speed: Extremely fast signing and verification
• Key Size: 32-byte private key, 32-byte public key
• Signature Size: 64 bytes
• Security Level: ~128 bits (classical)

Configuration

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

Use Cases

• General agent communication
• MCP message signing
• HTTP request/response signing
• Document signing

Example

import jacs
import json

agent = jacs.JacsAgent()
agent.load('./jacs.config.json')  # Using ring-Ed25519

# Sign a message
signature = agent.sign_string("Hello, World!")
print(f"Signature (64 bytes): {len(signature)} characters base64")

RSA-PSS

Industry-standard RSA with Probabilistic Signature Scheme padding.

Overview

RSA-PSS provides compatibility with systems that require RSA signatures. JACS uses 2048-bit or larger keys.

Characteristics

• Speed: Slower than Ed25519
• Key Size: 2048-4096 bits
• Signature Size: Same as key size (256-512 bytes)
• Security Level: ~112-128 bits (2048-bit key)

Configuration

{
  "jacs_agent_key_algorithm": "RSA-PSS"
}

Use Cases

• Integration with legacy systems
• Compliance requirements mandating RSA
• Interoperability with enterprise PKI

Considerations

• Larger signatures increase document size
• Slower than Ed25519
• Larger keys needed for equivalent security

Dilithium (pq-dilithium)

NIST-standardized post-quantum digital signature algorithm.

Overview

Dilithium is a lattice-based signature scheme selected by NIST for post-quantum cryptography standardization. It provides security against both classical and quantum computers.

Characteristics

• Speed: Moderate (faster than RSA, slower than Ed25519)
• Key Size: ~1.3 KB public key, ~2.5 KB private key
• Signature Size: ~2.4 KB
• Security Level: NIST Level 3 (quantum-resistant)

Configuration

{
  "jacs_agent_key_algorithm": "pq-dilithium"
}

Use Cases

• Long-term document security
• Protection against future quantum attacks
• High-security applications
• Government/defense requirements

Considerations

• Larger signatures and keys than classical algorithms
• Newer algorithm (less battle-tested)
• May be required for future compliance

PQ2025 (Hybrid)

Transitional hybrid scheme combining classical and post-quantum algorithms.

Overview

PQ2025 combines Ed25519 with Dilithium, providing security even if one algorithm is broken. This approach is recommended by security researchers during the quantum transition period.

Characteristics

• Speed: Slower (two signatures computed)
• Key Size: Combined Ed25519 + Dilithium
• Signature Size: ~2.5 KB (combined)
• Security Level: Max of both algorithms

Configuration

{
  "jacs_agent_key_algorithm": "pq2025"
}

Use Cases

• Transitioning to post-quantum
• Maximum security requirements
• Uncertainty about algorithm security
• Long-lived documents

Considerations

• Largest signatures
• Slowest signing/verification
• Best for paranoid security requirements

Algorithm Selection Guide

Decision Matrix

By Use Case

Web APIs and MCP:

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

Fast signing is critical for real-time communication.

Legal/Financial Documents:

{
  "jacs_agent_key_algorithm": "pq-dilithium"
}

Long-term validity requires quantum resistance.

Enterprise Integration:

{
  "jacs_agent_key_algorithm": "RSA-PSS"
}

Compatibility with existing PKI infrastructure.

High-Security:

{
  "jacs_agent_key_algorithm": "pq2025"
}

Belt-and-suspenders approach for maximum protection.

Key Generation

Keys are generated automatically when creating an agent:

# Directory structure after agent creation
jacs_keys/
├── private.pem    # Algorithm-specific private key
└── public.pem     # Algorithm-specific public key

Key Formats

Signature Structure

Signatures in JACS documents include algorithm metadata:

{
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "base64-encoded-signature",
    "publicKeyHash": "sha256-of-public-key",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsVersion", "content"]
  }
}

The signingAlgorithm field enables verifiers to use the correct verification method.

Hashing

JACS uses SHA-256 for all hash operations:

• Document content hashing (jacsSha256)
• Public key fingerprints (publicKeyHash)
• Agreement content locking (jacsAgreementHash)

{
  "jacsSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Algorithm Migration

To migrate to a new algorithm:

1. Generate New Keys

   {
     "jacs_agent_key_algorithm": "pq-dilithium"
   }
   

2. Create New Agent Version

   # Load with old algorithm
   agent.load('./old-config.json')
   
   # Update to new algorithm and generate new version
   new_agent = agent.update_agent(json.dumps({
       # ... agent data with new keys
   }))
   

3. Update Configuration

   {
     "jacs_agent_id_and_version": "agent-id:new-version",
     "jacs_agent_key_algorithm": "pq-dilithium"
   }
   

4. Maintain Backward Compatibility

   • Keep old agent versions for verifying old documents
   • Old signatures remain valid with old public keys

Performance Comparison

Approximate performance (varies by hardware):

Security Considerations

Algorithm Agility

JACS documents include the signing algorithm, enabling:

• Verification with correct algorithm
• Graceful algorithm transitions
• Multi-algorithm environments

Forward Secrecy

Signatures don't provide forward secrecy. For confidentiality:

• Use TLS for transport
• Consider additional encryption layers

Key Compromise

If a private key is compromised:

1. Generate new key pair
2. Create new agent version
3. Revoke trust in compromised version
4. Re-sign critical documents

See Also

• Security Model - Overall security architecture
• Configuration - Algorithm configuration
• DNS Verification - Public key fingerprint verification

Storage Backends

JACS supports multiple storage backends for persisting documents and agents. This flexibility allows deployment in various environments from local development to cloud infrastructure.

Available Backends

Configuration

Set the storage backend in your configuration:

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

Filesystem Storage (fs)

The default storage backend, storing documents as JSON files on the local filesystem.

Configuration

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

Directory Structure

jacs_data/
├── agents/
│   └── {agent-id}/
│       └── {version-id}.json
├── documents/
│   └── {document-id}/
│       └── {version-id}.json
└── files/
    └── {attachment-hash}

Use Cases

• Local development
• Single-server deployments
• Testing and prototyping
• Air-gapped environments

Advantages

• Simple setup
• No network dependencies
• Fast local access
• Easy backup and migration

Considerations

• Not suitable for distributed systems
• Limited by local disk space
• Single point of failure

Example

import jacs
import json

agent = jacs.JacsAgent()
agent.load('./jacs.config.json')  # Using filesystem storage

# Documents are saved to jacs_data/documents/
doc = agent.create_document(json.dumps({
    'title': 'My Document'
}))
# Saved to: jacs_data/documents/{doc-id}/{version-id}.json

AWS S3 Storage (aws)