JACS: JSON Agent Communication Standard

JACS is a cryptographic provenance layer for agent systems. Use it when an output, tool call, or agent handoff crosses a trust boundary and logs alone are not enough.

Start With The Deployment

Most teams adopt JACS in one of four ways:

• LangChain / LangGraph / CrewAI / FastAPI: add signing at tool or API boundaries without changing the rest of the app
• MCP: secure a local tool server or expose JACS itself as an MCP tool suite
• A2A: publish an Agent Card, exchange signed artifacts, and apply trust policy across organizations
• Core signing: sign JSON, files, or agreements directly from Rust, Python, Node.js, or Go

The book now focuses on those supported workflows first. Older roadmap-style integration chapters have been reduced or removed from navigation.

What JACS Gives You

• Signed JSON and file envelopes with tamper detection
• Persistent agent identity with encrypted private keys
• Trust bootstrap primitives such as share_public_key, share_agent, and trust_agent_with_key
• A2A artifact signing and trust policies (open, verified, strict)
• MCP integration paths for ready-made servers, transport security, or tool registration
• Framework adapters for Python and Node.js ecosystems
• Multi-party agreements with quorum, timeout, and algorithm constraints
• Cross-language compatibility across Rust, Python, Node.js, and Go

Best Entry Points

If you are choosing where to start:

1. Which Integration?
2. Use Cases
3. MCP Overview
4. A2A Interoperability
5. Python Framework Adapters
6. Node.js LangChain.js

Implementations

Rust

• Deepest feature surface
• CLI plus library APIs
• Best fit when you want a ready-made MCP server via jacs mcp

Python (jacs)

• Best fit for LangChain, LangGraph, CrewAI, FastAPI, and local MCP/A2A helpers
• Strong adapter story for adding provenance inside an existing app

Node.js (@hai.ai/jacs)

• Best fit for Express, Koa, Vercel AI SDK, LangChain.js, and MCP transport/tool integration
• Also exposes A2A helpers and Express discovery middleware

Go (jacsgo)

• Good fit for services that need signing and verification without framework adapters

Quick Start

Rust CLI

cargo install jacs-cli
jacs quickstart --name my-agent --domain my-agent.example.com

Python

pip install jacs

Node.js

npm install @hai.ai/jacs

Go

go get github.com/HumanAssisted/JACS/jacsgo

Rust, Python, and Node quickstart flows create or load a persistent agent and return agent metadata including config and key paths.

What This Book Does Not Claim

• It does not treat MCP and A2A as the same thing. MCP is for model-to-tool calls inside an application boundary; A2A is for agent discovery and exchange across boundaries.
• It does not assume every aspirational integration is first-class. If a chapter describes a feature that is not fully supported today, it has been moved out of the main path and tracked separately.
• It does not require a registry or blockchain to work. JACS identity is key-based and can be used entirely locally.

Community

• GitHub Repository
• Issue Tracker

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 with flexible key resolution (local trust stores, DNS, optional key services)

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, while still being usable as a general-purpose signed JSON provenance layer. 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

JACS provides signed artifacts, schemas, trust primitives, and auditability. Real-time transport and task orchestration are handled by integrations (e.g., A2A, MCP, HTTP server layers).

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

Which JACS Path Should I Use?

Choose the smallest supported integration that matches your deployment.

Start Here

When You Probably Do Not Need JACS

• Everything stays inside one service you control and your own logs are enough
• You only need integrity, not signer identity or third-party verification
• A plain checksum or database audit log already satisfies the requirement

Recommended Adoption Order

1. Prototype with quickstart and simple sign/verify calls.
2. Attach provenance at the boundary that already exists in your system: LangChain tool, FastAPI response, MCP call, or A2A artifact.
3. Add trust policy only when other agents or organizations enter the picture.
4. Add agreements, DNS, or attestations only if your deployment actually needs them.

The mistake to avoid is starting with the broadest story. Start with the boundary you need to secure now.

Use Cases

This chapter stays close to current product use, not roadmap integrations.

1. Secure A Local MCP Tool Server

Use this when: Claude Desktop, Codex, or another MCP client is calling tools that should not run on blind trust.

Recommended JACS path:

• Use jacs-mcp if you want a full server immediately
• Use Python MCP Integration or Node.js MCP Integration if you already have server code

What JACS adds:

• Signed JSON-RPC messages
• Fail-closed verification by default
• Agent identity and auditability for tool calls

2. Add Provenance To LangChain Or LangGraph

Use this when: your model already runs inside LangChain or LangGraph and you want signed tool outputs without introducing MCP.

Recommended JACS path:

• Python Framework Adapters
• Node.js LangChain.js

What JACS adds:

• Signed tool results
• Optional strict mode at the adapter boundary
• Minimal changes to existing framework code

3. Exchange Signed Artifacts Across Organizations

Use this when: one agent produces work that another organization, service, or team must verify before acting on it.

Recommended JACS path:

• A2A Interoperability
• A2A Quickstart

What JACS adds:

• Agent Cards with JACS provenance metadata
• Signed A2A artifacts
• Trust policies for admission control

4. Sign HTTP Or API Boundaries Without MCP

Use this when: the boundary is an API route, not an MCP transport.

Recommended JACS path:

• Python Framework Adapters for FastAPI
• Express Middleware
• Koa Middleware

What JACS adds:

• Signed JSON responses
• Verified inbound requests
• A clean upgrade path to A2A discovery on the same app boundary

5. Run Multi-Agent Approval Workflows

Use this when: multiple agents must sign off on the same document, deployment, or decision.

Recommended JACS path:

• Multi-Agent Agreements
• Rust Agreements

What JACS adds:

• M-of-N quorum
• Timeout and algorithm constraints
• Verifiable signature chain across signers

6. Keep Signed Files Or JSON As Durable Artifacts

Use this when: you need an artifact to stay verifiable after it leaves the process that created it.

Recommended JACS path:

• Verifying Signed Documents
• Working with Documents
• Python Basic Usage
• Node.js Basic Usage

What JACS adds:

• Self-contained signed envelopes
• Re-verification at read time
• Cross-language interoperability

7. Publish Public Identity Without A Central Auth Service

Use this when: external systems need to verify your agent identity but you do not want a shared auth server in the middle.

Recommended JACS path:

• DNS-Based Verification
• DNS Trust Anchoring

What JACS adds:

• Public key fingerprint anchoring
• DNS-based verification flows
• Local private-key custody

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

Verification: load() vs verify_standalone()

When consuming signed documents, you can verify in two ways:

• With a loaded agent (load(config) first): Call verify(signedDocument). The loaded agent uses its config (trust store, key resolution) to resolve the signer’s public key and verify the signature. Use this when your process already has a JACS config (e.g. it also signs) or when you want to use a specific key directory and resolution order.

• Without loading an agent (one-off verification): Call verify_standalone(signedDocument, options) (or the language equivalent: verifyStandalone, VerifyStandalone). This verifies the document using only the options you pass (e.g. keyResolution, keyDirectory). No config file or persistent agent state is required. Use this in lightweight services that only need to verify incoming documents.

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

Get signing and verifying in under a minute. No manual setup needed.

Zero-Config Quick Start

quickstart(name, domain, ...) creates a persistent agent with keys on disk (default algorithm: pq2025). If ./jacs.config.json already exists, it loads it; otherwise it creates a new agent. Returned AgentInfo includes config/key paths (config_path/public_key_path/private_key_path in Python, configPath/publicKeyPath/privateKeyPath in Node) plus key directory metadata so you can locate key material immediately. Rust/CLI quickstart requires an explicit password source (JACS_PRIVATE_KEY_PASSWORD, or JACS_PASSWORD_FILE in CLI). Python/Node can auto-generate a password if needed; set JACS_SAVE_PASSWORD_FILE=true if you want that generated password persisted to ./jacs_keys/.jacs_password.

Password bootstrap

Rust CLI quickstart requires exactly one explicit password source:

# Recommended
export JACS_PRIVATE_KEY_PASSWORD='use-a-strong-password'

# CLI convenience (file contains only the password)
export JACS_PASSWORD_FILE=/secure/path/jacs-password.txt

If both JACS_PRIVATE_KEY_PASSWORD and JACS_PASSWORD_FILE are set, CLI fails fast to avoid ambiguity. Python/Node quickstart can auto-generate a secure password if JACS_PRIVATE_KEY_PASSWORD is unset. Set JACS_SAVE_PASSWORD_FILE=true if you want the generated password persisted to ./jacs_keys/.jacs_password. In production, set JACS_PRIVATE_KEY_PASSWORD explicitly. One call and you're signing.

pip install jacs

import jacs.simple as jacs

info = jacs.quickstart(name="my-agent", domain="my-agent.example.com")
print(info.config_path, info.public_key_path, info.private_key_path)
signed = jacs.sign_message({"action": "approve", "amount": 100})
result = jacs.verify(signed.raw)
print(f"Valid: {result.valid}, Signer: {result.signer_id}")

npm install @hai.ai/jacs

const jacs = require('@hai.ai/jacs/simple');

const info = await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
console.log(info.configPath, info.publicKeyPath, info.privateKeyPath);
const signed = await jacs.signMessage({ action: 'approve', amount: 100 });
const result = await jacs.verify(signed.raw);
console.log(`Valid: ${result.valid}, Signer: ${result.signerId}`);

cargo install jacs-cli

# Info mode -- prints agent ID and algorithm
jacs quickstart --name my-agent --domain my-agent.example.com

# Sign JSON from stdin
echo '{"action":"approve"}' | jacs quickstart --name my-agent --domain my-agent.example.com --sign

# Sign a file
jacs quickstart --name my-agent --domain my-agent.example.com --sign --file mydata.json

Pass algorithm="ring-Ed25519" (or { algorithm: 'ring-Ed25519' } in JS, --algorithm ring-Ed25519 in CLI) to override the default (pq2025).

That's it -- you're signing. For most use cases, the quick start above is all you need. Jump to Which integration should I use? to find the right framework adapter, or read on for manual agent setup.

macOS Homebrew install (Rust CLI)

brew tap HumanAssisted/homebrew-jacs
brew install jacs

MCP server (Rust CLI)

The MCP server is built into the jacs binary. No separate install step needed.

# Start the MCP server (stdio transport)
jacs mcp

Advanced: Explicit Agent Setup

For full control over agent creation, you can set up an agent manually with a config file and JACS_PRIVATE_KEY_PASSWORD environment variable. This is optional since quickstart(...) already creates a persistent agent.

cargo install jacs-cli

# Create configuration and agent in one step
jacs init

# Or step by step:
# 1. Create config
jacs config create
# 2. Create agent with keys
jacs agent create --create-keys true
# 3. Verify
jacs agent verify

jacs document create -f mydata.json

npm install @hai.ai/jacs

const jacs = require('@hai.ai/jacs/simple');

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

const signed = await jacs.signMessage({ action: 'approve', amount: 100 });
const result = await jacs.verify(signed.raw);
console.log(`Valid: ${result.valid}`);

pip install jacs

import jacs.simple as jacs

# Load from config file
jacs.load("./jacs.config.json")

signed = jacs.sign_message({"action": "approve", "amount": 100})
result = jacs.verify(signed.raw)
print(f"Valid: {result.valid}")

Programmatic Agent Creation (v0.6.0+)

For scripts, CI/CD, and server environments where you need agents created programmatically with explicit parameters (without interactive prompts), use create(). For most cases, quickstart(...) above is simpler and also creates a persistent agent.

import jacs.simple as jacs

agent = jacs.create(
    name="my-agent",
    password="Str0ng-P@ssw0rd!",  # or set JACS_PRIVATE_KEY_PASSWORD
    algorithm="pq2025",
)
print(f"Agent: {agent.agent_id}")

const jacs = require('@hai.ai/jacs/simple');

const agent = await jacs.create({
  name: 'my-agent',
  password: process.env.JACS_PRIVATE_KEY_PASSWORD,
  algorithm: 'pq2025',
});
console.log(`Agent: ${agent.agentId}`);

info, err := jacs.Create("my-agent", &jacs.CreateAgentOptions{
    Password:  os.Getenv("JACS_PRIVATE_KEY_PASSWORD"),
    Algorithm: "pq2025",
})

#![allow(unused)]
fn main() {
use jacs::simple::{CreateAgentParams, SimpleAgent};

let params = CreateAgentParams {
    name: "my-agent".into(),
    password: std::env::var("JACS_PRIVATE_KEY_PASSWORD").unwrap(),
    algorithm: "pq2025".into(),
    ..Default::default()
};
let (agent, info) = SimpleAgent::create_with_params(params)?;
}

Password requirements: At least 8 characters, with uppercase, lowercase, a digit, and a special character.

Algorithm note: pq-dilithium is deprecated in v0.6.0. Use pq2025 (ML-DSA-87, FIPS-204) instead.

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 (async)
const isValid = await agent.verifyAgent();
console.log('Agent signature valid:', isValid);

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

# 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();
await reviewer.load('./reviewer.config.json');

// Create agreement between agents
const signedAgreement = await agent.createAgreement(
  signedTask,
  [agentDoc.jacsId, reviewerDoc.jacsId],
  'Do you agree to collaborate on this content task?'
);

// Both agents sign the agreement
const signed1 = await agent.signAgreement(signedAgreement);
const signed2 = await reviewer.signAgreement(signed1);

// Check agreement status
const status = await agent.checkAgreement(signed2);
console.log('Agreement status:', JSON.parse(status));

# 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. Verify Signed Documents - Verify any document from CLI, Python, or Node.js -- no agent required
2. A2A Quickstart - Make your agent discoverable by other A2A agents in minutes
3. Framework Adapters - Add auto-signing to LangChain, FastAPI, CrewAI, or Anthropic SDK in 1-3 lines
4. Multi-Agent Agreements - Cross-trust-boundary verification with quorum and timeout
5. Rust Deep Dive - Learn the full Rust API
6. Node.js Integration - Add MCP support
7. Python MCP - Build authenticated MCP servers
8. Production Security - Harden runtime settings and key management
9. 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.

Multi-Agent Agreements

Three agents from different organizations sign an agreement with 2-of-3 quorum.

Imagine three departments -- Finance, Compliance, and Legal -- must approve a production deployment. Requiring all three creates bottlenecks. With JACS quorum agreements, any two of three is sufficient: cryptographically signed, independently verifiable, with a full audit trail.

No central authority. No shared database. Every signature is independently verifiable.

The Lifecycle

Create Agreement --> Agent A Signs --> Agent B Signs --> Quorum Met (2/3) --> Verified

Python

from jacs.client import JacsClient

# Step 1: Create three agents (one per organization)
finance = JacsClient.quickstart(
    name="finance",
    domain="finance.example.com",
    algorithm="ring-Ed25519",
    config_path="./finance.config.json",
)
compliance = JacsClient.quickstart(
    name="compliance",
    domain="compliance.example.com",
    algorithm="ring-Ed25519",
    config_path="./compliance.config.json",
)
legal = JacsClient.quickstart(
    name="legal",
    domain="legal.example.com",
    algorithm="ring-Ed25519",
    config_path="./legal.config.json",
)

# Step 2: Finance proposes an agreement with quorum
from datetime import datetime, timedelta, timezone

proposal = {
    "action": "Deploy model v2 to production",
    "conditions": ["passes safety audit", "approved by 2 of 3 signers"],
}
deadline = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat()

agreement = finance.create_agreement(
    document=proposal,
    agent_ids=[finance.agent_id, compliance.agent_id, legal.agent_id],
    question="Do you approve deployment of model v2?",
    context="Production rollout pending safety audit sign-off.",
    quorum=2,           # only 2 of 3 need to sign
    timeout=deadline,
)

# Step 3: Finance signs
agreement = finance.sign_agreement(agreement)

# Step 4: Compliance co-signs -- quorum is now met
agreement = compliance.sign_agreement(agreement)

# Step 5: Verify -- any party can confirm independently
status = finance.check_agreement(agreement)
print(f"Complete: {status.complete}")  # True -- 2 of 3 signed

for s in status.signers:
    label = "signed" if s.signed else "pending"
    print(f"  {s.agent_id[:12]}... {label}")

Node.js / TypeScript

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

async function main() {
  // Step 1: Create three agents
  const finance    = await JacsClient.ephemeral("ring-Ed25519");
  const compliance = await JacsClient.ephemeral("ring-Ed25519");
  const legal      = await JacsClient.ephemeral("ring-Ed25519");

  // Step 2: Finance proposes an agreement with quorum
  const proposal = {
    action: "Deploy model v2 to production",
    conditions: ["passes safety audit", "approved by 2 of 3 signers"],
  };
  const deadline = new Date(Date.now() + 60 * 60 * 1000).toISOString();
  const agentIds = [finance.agentId, compliance.agentId, legal.agentId];

  let agreement = await finance.createAgreement(proposal, agentIds, {
    question: "Do you approve deployment of model v2?",
    context: "Production rollout pending safety audit sign-off.",
    quorum: 2,
    timeout: deadline,
  });

  // Step 3: Finance signs
  agreement = await finance.signAgreement(agreement);

  // Step 4: Compliance co-signs -- quorum is now met
  agreement = await compliance.signAgreement(agreement);

  // Step 5: Verify
  const doc = JSON.parse(agreement.raw);
  const ag = doc.jacsAgreement;
  const sigCount = ag.signatures?.length ?? 0;
  console.log(`Signatures: ${sigCount} of ${agentIds.length}`);
  console.log(`Quorum met: ${sigCount >= (ag.quorum ?? agentIds.length)}`);
}

main().catch(console.error);

What Just Happened?

1. Three independent agents were created, each with their own keys -- no shared secrets.
2. Finance proposed an agreement requiring 2-of-3 quorum with a one-hour deadline.
3. Finance and Compliance signed. Legal never needed to act -- quorum was met.
4. Any party can verify the agreement independently. The cryptographic proof chain is self-contained.

Every signature includes: the signer's agent ID, the signing algorithm, a timestamp, and a hash of the agreement content. If anyone tampers with the document after signing, verification fails.

Next Steps

• Agreements API Reference -- timeout, algorithm constraints, and more
• Python Framework Adapters -- use agreements inside LangChain, FastAPI, CrewAI
• Security Model -- how the cryptographic proof chain works

Verifying Signed Documents

Verify a JACS-signed document in under 2 minutes. Verification confirms two things: the document was signed by the claimed agent, and the content has not been modified since signing.

Verification does NOT require creating an agent. You only need the signed document (and optionally access to the signer's public key).

CLI: jacs verify

The fastest way to verify a document from the command line. No config file, no agent setup.

# Verify a local file
jacs verify signed-document.json

# Verify with JSON output (for scripting)
jacs verify signed-document.json --json

# Verify a remote document by URL
jacs verify --remote https://example.com/signed-doc.json

# Specify a directory containing public keys
jacs verify signed-document.json --key-dir ./trusted-keys/

Output on success:

Status:    VALID
Signer:    550e8400-e29b-41d4-a716-446655440000
Signed at: 2026-02-10T12:00:00Z

JSON output (--json):

{
  "valid": true,
  "signerId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-10T12:00:00Z"
}

The exit code is 0 for valid, 1 for invalid or error. Use this in CI/CD pipelines:

if jacs verify artifact.json --json; then
  echo "Artifact is authentic"
else
  echo "Verification failed" >&2
  exit 1
fi

If a jacs.config.json and agent keys exist in the current directory, the CLI uses them automatically. Otherwise, it creates a temporary ephemeral verifier internally.

Python

With an agent loaded

import jacs.simple as jacs

jacs.load("./jacs.config.json")

result = jacs.verify(signed_json)
if result.valid:
    print(f"Signed by: {result.signer_id}")
else:
    print(f"Errors: {result.errors}")

Without an agent (standalone)

import jacs.simple as jacs

result = jacs.verify_standalone(
    signed_json,
    key_resolution="local",
    key_directory="./trusted-keys/"
)
print(f"Valid: {result.valid}, Signer: {result.signer_id}")

verify_standalone does not use a global agent. Pass the key resolution strategy and directories explicitly.

Verify by document ID

If the document is in local storage and you know its ID:

result = jacs.verify_by_id("550e8400-e29b-41d4:1")

Node.js

With an agent loaded

import * as jacs from '@hai.ai/jacs/simple';

await jacs.load('./jacs.config.json');

const result = await jacs.verify(signedJson);
console.log(`Valid: ${result.valid}, Signer: ${result.signerId}`);

Without an agent (standalone)

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

const result = verifyStandalone(signedJson, {
  keyResolution: 'local',
  keyDirectory: './trusted-keys/',
});
console.log(`Valid: ${result.valid}, Signer: ${result.signerId}`);

Verify by document ID

const result = await jacs.verifyById('550e8400-e29b-41d4:1');

Verification Links

Generate a URL that lets anyone verify a signed document through a web verifier (e.g., hai.ai):

Python:

url = jacs.generate_verify_link(signed_doc.raw_json)
# https://hai.ai/jacs/verify?s=<base64url-encoded-document>

Node.js:

const url = jacs.generateVerifyLink(signed.raw);

The document is base64url-encoded into the URL query parameter. Documents must be under ~1.5 KB to fit within the 2048-character URL limit. For larger documents, share the file directly and verify with the CLI or SDK.

DNS Verification

DNS verification checks that an agent's public key hash matches a DNS TXT record published at _v1.agent.jacs.<domain>. This provides a decentralized trust anchor: anyone can look up the agent's expected key fingerprint via DNS without contacting a central server.

Publishing a DNS record

jacs agent dns --domain example.com --provider plain

This outputs the TXT record to add to your DNS zone. Provider options: plain, aws, azure, cloudflare.

Looking up an agent by domain

jacs agent lookup example.com

This fetches the agent's public key from https://example.com/.well-known/jacs-pubkey.json and checks the DNS TXT record at _v1.agent.jacs.example.com.

CLI verification with DNS

# Require DNS validation (fail if no DNS record)
jacs agent verify --require-dns

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

For full DNS setup instructions, see DNS-Based Verification and DNS Trust Anchoring.

Cross-Language Verification

JACS signatures are language-agnostic. A document signed by a Rust agent verifies identically in Python and Node.js, and vice versa. This holds for both Ed25519 and post-quantum (ML-DSA-87/pq2025) algorithms.

This is tested on every commit: Rust generates signed fixtures, then Python calls verify_standalone() and Node.js calls verifyStandalone() to verify them. Each binding also countersigns the fixture with a different algorithm, proving round-trip interoperability.

Test sources:

• Rust fixture generator: jacs/tests/cross_language/mod.rs
• Python consumer: jacspy/tests/test_cross_language.py
• Node.js consumer: jacsnpm/test/cross-language.test.js

Key Resolution Order

When verifying a document, JACS resolves the signer's public key in a configurable order. Set JACS_KEY_RESOLUTION to control this:

Default: local,hai. Example: JACS_KEY_RESOLUTION=local,dns,hai.

What Is an Attestation?

Signing says WHO. Attestation says WHO plus WHY.

A JACS attestation is a cryptographically signed document that goes beyond proving who signed something. It records why a piece of data should be trusted -- the evidence, the claims, and the reasoning behind that trust.

Signing vs. Attestation

Key Concepts

Subject

What is being attested. Every attestation targets a specific subject -- an artifact, agent, workflow, or identity. The subject is identified by type, ID, and cryptographic digests.

Claims

What you assert about the subject. Claims are structured statements with a name, value, optional confidence score (0.0-1.0), and assurance level (self-asserted, verified, or independently-attested).

Evidence

What supports the claims. Evidence references link to external proofs (A2A messages, email headers, JWT tokens, TLS notary sessions) with their own digests and timestamps.

Derivation Chain

How the attestation was produced. When one attestation builds on another -- for example, a review attestation that references an earlier scan attestation -- the derivation chain captures the full transformation history.

Architecture Layers

Layer 2: Adapters (A2A, email, JWT, TLSNotary)
           |
Layer 1: Attestation Engine (create, verify, lift, DSSE export)
           |
Layer 0: JACS Core (sign, verify, agreements, storage)

Attestations build on top of existing JACS signing. Every attestation is also a valid signed JACS document. You can verify an attestation with verify() for signature checks, or use verify_attestation() for the full trust evaluation.

Quick Example

from jacs.client import JacsClient

client = JacsClient.ephemeral(algorithm="ed25519")

# Sign a document (Layer 0)
signed = client.sign_message({"action": "approve", "amount": 100})

# Attest WHY it's trustworthy (Layer 1)
att = client.create_attestation(
    subject={"type": "artifact", "id": signed.document_id,
             "digests": {"sha256": "..."}},
    claims=[{"name": "reviewed", "value": True, "confidence": 0.95}],
)

# Verify the full trust chain
result = client.verify_attestation(att.raw_json, full=True)
print(f"Valid: {result['valid']}")

Attestation vs. A2A Trust Policy

Attestation (Layer C) provides trust context: claims, evidence, and derivation chains. It answers "why should this data be trusted?" A2A trust policy (Layer B) handles agent admission: "is this agent allowed to communicate?"

For transport trust decisions, see A2A Interoperability. For how attestation and A2A compose, see A2A + Attestation Composition. For the full three-layer model, see Trust Layers.

When to Use Attestations

Use attestations when you need to answer questions like:

• Why should I trust this data? (claims + evidence)
• Who reviewed it and when? (issuer, timestamps, assurance level)
• How was it produced? (derivation chain)
• Can I independently verify the trust chain? (DSSE export, evidence verification)

If you only need to prove who signed something and that it hasn't been tampered with, sign_message() is sufficient. See Sign vs. Attest for a detailed decision guide.

JACS Trust Layers

JACS organizes trust into three distinct layers. Each layer has a clear scope and its own vocabulary. Understanding which layer you need prevents confusion between identity, transport policy, and evidentiary trust.

The Three Layers

Layer A: Identity + Integrity (JACS Core)

Scope: Who signed what, and has it been tampered with?

APIs: sign_message(), verify(), verify_standalone()

This is the foundation. Every JACS document carries a cryptographic signature that proves which agent created it and that the content hasn't changed. Layer A answers: "Is this signature valid?"

Crypto status values: Verified · SelfSigned · Unverified · Invalid

• Verified: Signature is valid and signer's key was resolved from a trusted source.
• SelfSigned: Signature is valid but signer is the same as verifier (no third-party trust).
• Unverified: Signature could not be checked because the signer's key was not available.
• Invalid: Signature check failed — the content was tampered with or the wrong key was used.

Layer B: Exchange + Discovery (A2A Integration)

Scope: Is this agent allowed to communicate with me?

APIs: sign_artifact(), verify_wrapped_artifact(), assess_remote_agent(), discover_agent()

Layer B handles cross-boundary exchange between agents using the A2A protocol. It adds trust policy on top of Layer A's cryptographic status. Layer B answers: "Should I accept artifacts from this agent?"

Policy status values: allowed · blocked · not_assessed

Trust policies (open, verified, strict) control admission:

See A2A Interoperability for full details.

Layer C: Trust Context (Attestation)

Scope: Why should this data be trusted?

APIs: create_attestation(), verify_attestation(), lift_to_attestation(), export_attestation_dsse()

Layer C records the reasoning behind trust: claims, evidence, derivation chains, and assurance levels. Layer C answers: "What evidence supports this data?"

Attestation status values: local_valid · full_valid

• local_valid: Signature and hash are correct; claims are structurally valid.
• full_valid: All of the above, plus evidence digests verified and derivation chain intact.

See What Is an Attestation? for full details.

Terminology Glossary

Quick Decision Flow

"Which layer do I need?"

1. I just need to prove data hasn't been tampered with → Layer A. Use sign_message() and verify().
2. I need to exchange signed data with other agents → Layer B. Use sign_artifact() and A2A discovery. See the A2A Quickstart.
3. I need to record WHY data should be trusted → Layer C. Use create_attestation(). See the Attestation Tutorial.
4. I need both exchange AND trust evidence → Layer B + C. See A2A + Attestation Composition.

Common Misconceptions

• "Unverified" does not mean "Invalid." Unverified means the signer's key wasn't available. Invalid means the signature check actively failed. These have very different security implications.
• A2A trust policy is not attestation verification. A2A policy (Layer B) answers "should I talk to this agent?" Attestation (Layer C) answers "why should I trust this data?" They compose but are not interchangeable.
• "Trusted" is not the same as "Verified." In JACS, "trusted" refers to trust store membership (Layer B). "Verified" refers to cryptographic signature validation (Layer A).

Deployment Compatibility

JACS includes native bindings (Rust compiled to platform-specific libraries), so deployment depends on pre-built binary availability for your target platform.

Supported Platforms

Not Yet Supported

Version Requirements

Docker Example

FROM python:3.12-slim
RUN pip install jacs
COPY . /app
WORKDIR /app
RUN python -c "import jacs.simple as j; j.quickstart(name='docker-agent', domain='docker.local')"
CMD ["python", "main.py"]

Lambda Deployment

For AWS Lambda, include the JACS native library in a Lambda layer or bundle it in your deployment package. Set JACS_PRIVATE_KEY_PASSWORD as a Lambda environment variable (use AWS Secrets Manager for production).

Building from Source

If no pre-built binary exists for your platform:

# Python
pip install maturin
cd jacspy && maturin develop --release

# Node.js
cd jacsnpm && npm run build

Requires Rust 1.93+ toolchain installed via rustup.

Troubleshooting

Common issues and solutions when installing or using JACS.

Installation Issues

pip install fails

Check your Python version (3.10+ required). If no pre-built wheel exists for your platform, install the Rust toolchain and build from source:

pip install maturin
cd jacspy && maturin develop --release

npm install fails

Pre-built binaries are available for Linux/macOS/Windows x64 and ARM64 macOS. If no pre-built binary matches your platform, you need the Rust toolchain installed so the native addon can compile during npm install.

Alpine Linux / musl libc

The default wheels and binaries target glibc. On Alpine or other musl-based systems, build from source with the Rust toolchain, or use a Debian-based container image instead.

Configuration Issues

Config not found

Run jacs quickstart --name my-agent --domain my-agent.example.com to auto-create a config, or copy the example:

cp jacs.config.example.json jacs.config.json

Private key decryption failed

Wrong or missing password. Check JACS_PRIVATE_KEY_PASSWORD. For CLI, you may also set JACS_PASSWORD_FILE to a file that contains only the password. Set exactly one explicit source; if both are set, CLI fails by design.

Algorithm detection failed

Set the signingAlgorithm field in your config, or pass it explicitly to quickstart(...) / create(...). Valid values: pq2025, ring-Ed25519, RSA-PSS.

Runtime Issues

Agent creation fails

Ensure the data and key directories exist and are writable. By default these are ./jacs_data and ./jacs_keys.

Signature verification fails

Ensure the signer's public key is accessible. If verifying a document from another agent, you may need to import their public key or use the trust store.

Documents not found

Check the jacs_data_directory path in your config. Documents are stored as JSON files in that directory.

Building from Source

git clone https://github.com/HumanAssisted/JACS.git
cd JACS

# Rust core + CLI
cargo build --release
cargo install --path jacs --features cli

# Python binding
cd jacspy && maturin develop --release

# Node.js binding
cd jacsnpm && npm run build

Requires Rust 1.93+ (install via rustup).

Getting Help

• GitHub Issues -- report bugs and feature requests
• Quick Start Guide -- step-by-step setup

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-cli

From Homebrew (macOS)

brew tap HumanAssisted/homebrew-jacs
brew install jacs

From Source

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

Verify Installation

jacs --help

MCP Server

The MCP server is built into the jacs binary. No separate install step needed.

# Start the MCP server (stdio transport)
jacs mcp

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 (pq2025, legacy 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.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 Tutorial

This page walks through common CLI workflows. For a complete command reference, see the CLI Command Reference. For practical scripting examples, see CLI Examples.

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

MCP Server

The MCP server is built into the jacs binary. No separate install step needed.

# Start the MCP server (stdio transport)
jacs mcp

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": [
    {
      "name": "content-generation",
      "serviceDescription": "Generate high-quality content",
      "successDescription": "Engaging, accurate content delivered",
      "failureDescription": "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": [
    {
      "name": "data-processing",
      "serviceDescription": "Process and transform data",
      "successDescription": "Data transformed successfully",
      "failureDescription": "Input data could not be processed"
    }
  ]
}

Human Agent Example

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsAgentType": "human",
  "name": "John Smith",
  "description": "Software engineer",
  "jacsContacts": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john@example.com",
      "isPrimary": true
    }
  ],
  "jacsServices": [
    {
      "name": "code-review",
      "serviceDescription": "Review code for quality and security",
      "successDescription": "Actionable review delivered",
      "failureDescription": "Could not complete review"
    }
  ]
}

Agent Services

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

{
  "name": "service-identifier",
  "serviceDescription": "What the service does",
  "successDescription": "Definition of successful completion",
  "failureDescription": "What constitutes failure"
}

Detailed Service Example

{
  "name": "document-processing",
  "serviceDescription": "Process and analyze documents",
  "successDescription": "Documents processed accurately",
  "failureDescription": "Unable to process one or more documents",
  "costDescription": "Usage-based pricing",
  "privacyPolicy": "https://example.com/privacy",
  "termsOfService": "https://example.com/terms"
}

Agent Contacts

For human and hybrid agents, contacts are required:

{
  "jacsContacts": [
    {
      "firstName": "Example",
      "lastName": "Agent",
      "email": "agent@example.com",
      "phone": "+1-555-0123",
      "isPrimary": true
    }
  ]
}

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": [
    {
      "name": "content-generation",
      "serviceDescription": "Generate high-quality content",
      "successDescription": "High-quality content generated",
      "failureDescription": "Unable to generate requested 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.

Agreement Options (v0.6.2+)

Timeout

Set a deadline after which the agreement expires:

# Python
agreement = client.create_agreement(
    document=proposal,
    agent_ids=[alice.agent_id, bob.agent_id],
    timeout="2025-12-31T23:59:59Z"
)

If the deadline passes before all required signatures are collected, check_agreement() returns an error.

Quorum (M-of-N Signing)

Require only a subset of agents to sign:

# Only 2 of 3 agents need to sign
agreement = client.create_agreement(
    document=proposal,
    agent_ids=[alice.agent_id, bob.agent_id, carol.agent_id],
    quorum=2
)

When quorum is met, check_agreement() succeeds even if some agents haven't signed.

Algorithm Constraints

Enforce that only specific cryptographic algorithms can be used:

# Only post-quantum algorithms allowed
agreement = client.create_agreement(
    document=proposal,
    agent_ids=agent_ids,
    required_algorithms=["pq2025", "pq-dilithium"],
    minimum_strength="post-quantum"
)

An agent using RSA-PSS or Ed25519 will be rejected when trying to sign this agreement.

Combined Options

agreement = client.create_agreement(
    document={"proposal": "Deploy model v2"},
    agent_ids=[alice.agent_id, bob.agent_id, mediator.agent_id],
    question="Do you approve deployment?",
    timeout="2025-06-30T00:00:00Z",
    quorum=2,
    minimum_strength="post-quantum"
)

Using JacsClient (Instance-Based API)

For running multiple agents in one process, use JacsClient instead of the module-level API:

Python

from jacs.client import JacsClient

alice = JacsClient.ephemeral("ring-Ed25519")  # for testing
bob = JacsClient.ephemeral("ring-Ed25519")

signed = alice.sign_message({"action": "approve"})
# alice.agent_id, bob.agent_id are unique

See the full example: examples/multi_agent_agreement.py

Node.js

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

const alice = JacsClient.ephemeral('ring-Ed25519');
const bob = JacsClient.ephemeral('ring-Ed25519');

const signed = alice.signMessage({ action: 'approve' });

See the full example: examples/multi_agent_agreement.ts

MCP Tools for Agreements

The JACS MCP server exposes agreement tools that LLMs can use directly:

See MCP Integration for setup.

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
5. Use quorum for resilience: Don't require unanimous consent unless necessary
6. Set timeouts: Prevent agreements from hanging indefinitely
7. Enforce post-quantum for sensitive agreements: Use minimum_strength: "post-quantum" for long-term security

Next Steps

• DNS Verification - Verify agent identities
• Task Schema - Task-specific agreements
• Security Model - Agreement security
• Multi-Agent Agreement Example (Python)
• Multi-Agent Agreement Example (Node.js)

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

DNS verification is also a practical bridge for DID-style deployments: you can publish DID metadata for discovery while using DNS TXT + JACS signature verification as the operational trust anchor. No blockchain is required for this model.

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())?;

// AWS object storage
let storage = MultiStorage::new("aws".to_string())?;
}

For signed document CRUD/search, prefer the unified DocumentService surface:

use jacs::document::service_from_agent;

let docs = service_from_agent(agent_handle)?;
// `fs` and `rusqlite` currently resolve in JACS core.

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 (Rust API)

This page covers the Rust-specific observability API: ObservabilityConfig, LogDestination, MetricsConfig, TracingConfig, and related types. For a cross-language guide covering structured events, OTEL collector setup, and monitoring backend integration, see the Observability & Monitoring Guide.

JACS provides comprehensive observability features including logging, metrics, and distributed tracing. This chapter covers configuring and using these features in your Rust 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"] }

Convenience helpers for recording operations are always available (no feature flag needed).

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

JACS convenience helpers automatically record:

• 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 (@hai.ai/jacs) provides JavaScript/TypeScript bindings to the JACS Rust library, making it easy to integrate JACS into web applications, servers, and Node.js projects.

Requirements

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

Installation

Using npm

npm install @hai.ai/jacs

Using yarn

yarn add @hai.ai/jacs

Using pnpm

pnpm add @hai.ai/jacs

Verify Installation

Create a simple test to verify everything is working:

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

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

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

Run the test:

node test.js

Package Structure

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

Core and simple API

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

Instance-based client (recommended for new code)

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

MCP (@hai.ai/jacs/mcp)

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

HTTP / framework adapters

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

TypeScript Support

The package includes full TypeScript definitions:

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

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

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

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

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

Configuration

Basic Configuration

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

Configuration File

Create a jacs.config.json file:

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

Load the configuration:

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

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

Environment Variables

JACS reads environment variables that override configuration file settings:

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

Storage Backends

Configure storage in jacs.config.json:

File System (Default)

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

Local Indexed SQLite

{
  "jacs_default_storage": "rusqlite"
}

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

AWS Storage

{
  "jacs_default_storage": "aws"
}

AWS credentials are read from standard AWS environment variables.

Memory Storage (Testing)

{
  "jacs_default_storage": "memory"
}

Cryptographic Algorithms

ring-Ed25519 (Recommended)

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

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

RSA-PSS

{
  "jacs_agent_key_algorithm": "RSA-PSS"
}

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

pq-dilithium (Post-Quantum)

{
  "jacs_agent_key_algorithm": "pq-dilithium"
}

Pros: Quantum-resistant Cons: Experimental, large signatures

pq2025 (Post-Quantum Hybrid)

{
  "jacs_agent_key_algorithm": "pq2025"
}

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

Development Setup

Project Structure

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

Package.json Setup

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

Basic Application

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

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

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

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

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

Common Issues

Module Not Found

If you get Module not found errors:

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

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

Permission Errors

If you get permission errors accessing files:

# Check directory permissions
ls -la jacs_data/ jacs_keys/

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

Binary Compatibility

If you get binary compatibility errors:

# Rebuild native modules
npm rebuild

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

TypeScript Issues

If TypeScript can't find definitions:

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

Next Steps

Now that you have JACS installed:

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

Simplified API

The simplified API (@hai.ai/jacs/simple) provides a streamlined, module-level interface for common JACS operations. It's designed to get you signing and verifying in under 2 minutes.

v0.7.0: Async-First API

All NAPI operations now return Promises by default. Sync variants are available with a Sync suffix, following the Node.js convention (like fs.readFile vs fs.readFileSync).

// Async (default, recommended -- does not block the event loop)
const signed = await jacs.signMessage({ action: 'approve' });

// Sync (blocks event loop, use in scripts or CLI tools)
const signed = jacs.signMessageSync({ action: 'approve' });

Quick Start

Quickstart -- one call (with required name/domain) to start signing:

const jacs = require('@hai.ai/jacs/simple');

const info = await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
console.log(info.configPath, info.publicKeyPath, info.privateKeyPath);
const signed = await jacs.signMessage({ action: 'approve', amount: 100 });
const result = await jacs.verify(signed.raw);
console.log(`Valid: ${result.valid}, Signer: ${result.signerId}`);

quickstart(name, domain, ...) creates a persistent agent with keys on disk (default algorithm: pq2025). If ./jacs.config.json already exists, it loads it; otherwise it creates a new agent. Returned AgentInfo includes config/key paths (config_path/public_key_path/private_key_path in Python, configPath/publicKeyPath/privateKeyPath in Node) plus key directory metadata so you can locate key material immediately. Rust/CLI quickstart requires an explicit password source (JACS_PRIVATE_KEY_PASSWORD, or JACS_PASSWORD_FILE in CLI). Python/Node can auto-generate a password if needed; set JACS_SAVE_PASSWORD_FILE=true if you want that generated password persisted to ./jacs_keys/.jacs_password. Pass { algorithm: 'ring-Ed25519' } to override the default (pq2025).

To load an existing agent explicitly, use load() instead:

const agent = await jacs.load('./jacs.config.json');
const signed = await jacs.signMessage({ action: 'approve', amount: 100 });

When to Use the Simplified API

API Reference

Every function that calls into NAPI has both async (default) and sync variants:

Pure sync functions (no NAPI call, no suffix needed):

quickstart(options)

Create a persistent agent with keys on disk. If ./jacs.config.json already exists, loads it. Otherwise creates a new agent, saving keys and config to disk. If JACS_PRIVATE_KEY_PASSWORD is unset, Node quickstart auto-generates a secure password in-process (JACS_SAVE_PASSWORD_FILE=true persists it to ./jacs_keys/.jacs_password). Call this once before signMessage() or verify().

Parameters:

• options (object, required fields): { name: string, domain: string, description?: string, algorithm?: string, configPath?: string }. Default algorithm: "pq2025". Also: "ring-Ed25519", "RSA-PSS".

Returns: Promise<AgentInfo> (async) or AgentInfo (sync)

const info = await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
console.log(`Agent ID: ${info.agentId}`);
console.log(`Config path: ${info.configPath}`);
console.log(`Public key: ${info.publicKeyPath}`);
console.log(`Private key: ${info.privateKeyPath}`);

// Or with a specific algorithm
const info = await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
  algorithm: 'ring-Ed25519',
});

// Sync variant (blocks event loop)
const info = jacs.quickstartSync({
  name: 'my-agent',
  domain: 'my-agent.example.com',
  algorithm: 'ring-Ed25519',
});

load(configPath?)

Load a persistent agent from a configuration file. Use this instead of quickstart(options) when you want to load a specific config file explicitly.

Parameters:

• configPath (string, optional): Path to jacs.config.json (default: "./jacs.config.json")

Returns: Promise<AgentInfo> (async) or AgentInfo (sync)

const info = await jacs.load('./jacs.config.json');
console.log(`Agent ID: ${info.agentId}`);

// Sync variant
const info = jacs.loadSync('./jacs.config.json');

isLoaded()

Check if an agent is currently loaded.

Returns: boolean

if (!jacs.isLoaded()) {
  await jacs.load('./jacs.config.json');
}

getAgentInfo()

Get information about the currently loaded agent.

Returns: AgentInfo or null if no agent is loaded

const info = jacs.getAgentInfo();
if (info) {
  console.log(`Agent: ${info.agentId}`);
}

verifySelf()

Verify the loaded agent's own integrity (signature and hash).

Returns: Promise<VerificationResult> (async) or VerificationResult (sync)

Throws: Error if no agent is loaded

const result = await jacs.verifySelf();
if (result.valid) {
  console.log('Agent integrity verified');
} else {
  console.log('Errors:', result.errors);
}

signMessage(data)

Sign arbitrary data as a JACS document.

Parameters:

• data (any): Object, array, string, or any JSON-serializable value

Returns: Promise<SignedDocument> (async) or SignedDocument (sync)

Throws: Error if no agent is loaded

// Async (recommended)
const signed = await jacs.signMessage({
  action: 'transfer',
  amount: 500,
  recipient: 'agent-123'
});

// Sync
const signed = jacs.signMessageSync({
  action: 'transfer',
  amount: 500,
  recipient: 'agent-123'
});

console.log(`Document ID: ${signed.documentId}`);
console.log(`Signed by: ${signed.agentId}`);

signFile(filePath, embed?)

Sign a file with optional content embedding.

Parameters:

• filePath (string): Path to the file to sign
• embed (boolean, optional): If true, embed file content in the document (default: false)

Returns: Promise<SignedDocument> (async) or SignedDocument (sync)

// Reference only (stores hash)
const signed = await jacs.signFile('contract.pdf', false);

// Embed content (creates portable document)
const embedded = await jacs.signFile('contract.pdf', true);

verify(signedDocument)

Verify a signed document and extract its content.

Parameters:

• signedDocument (string): The JSON string of the signed document

Returns: Promise<VerificationResult> (async) or VerificationResult (sync)

const result = await jacs.verify(signedJson);

if (result.valid) {
  console.log(`Signed by: ${result.signerId}`);
  console.log(`Data: ${JSON.stringify(result.data)}`);
} else {
  console.log(`Invalid: ${result.errors.join(', ')}`);
}

verifyStandalone(signedDocument, options?)

Verify a signed document without loading an agent. Use when you only need to verify (e.g. a lightweight API). Does not use the global agent.

Parameters:

• signedDocument (string): The signed JACS document JSON
• options (object, optional): { keyResolution?, dataDirectory?, keyDirectory? }

Returns: VerificationResult (always sync -- no NAPI call)

const result = jacs.verifyStandalone(signedJson, { keyResolution: 'local', keyDirectory: './keys' });
console.log(result.valid, result.signerId);

audit(options?)

Run a read-only security audit and health checks. Returns an object with risks, health_checks, summary, and overall_status. Does not require a loaded agent; does not modify state.

Parameters: options (object, optional): { configPath?, recentN? }

Returns: Promise<object> (async) or object (sync)

See Security Model -- Security Audit for full details and options.

const result = await jacs.audit();
console.log(`Risks: ${result.risks.length}, Status: ${result.overall_status}`);

updateAgent(newAgentData)

Update the agent document with new data and re-sign it.

This function expects a complete agent document (not partial updates). Use exportAgent() to get the current document, modify it, then pass it here.

Parameters:

• newAgentData (object|string): Complete agent document as JSON string or object

Returns: Promise<string> (async) or string (sync) -- The updated and re-signed agent document

const agentDoc = JSON.parse(jacs.exportAgent());
agentDoc.jacsAgentType = 'hybrid';
const updated = await jacs.updateAgent(agentDoc);

updateDocument(documentId, newDocumentData, attachments?, embed?)

Update an existing document with new data and re-sign it.

Parameters:

• documentId (string): The document ID (jacsId) to update
• newDocumentData (object|string): Updated document as JSON string or object
• attachments (string[], optional): Array of file paths to attach
• embed (boolean, optional): If true, embed attachment contents

Returns: Promise<SignedDocument> (async) or SignedDocument (sync)

const original = await jacs.signMessage({ status: 'pending', amount: 100 });
const doc = JSON.parse(original.raw);
doc.content.status = 'approved';
const updated = await jacs.updateDocument(original.documentId, doc);

exportAgent()

Export the current agent document for sharing or inspection.

Returns: string -- The agent JSON document (pure sync, no suffix needed)

const agentDoc = jacs.exportAgent();
const agent = JSON.parse(agentDoc);
console.log(`Agent type: ${agent.jacsAgentType}`);

getDnsRecord(domain, ttl?)

Return the DNS TXT record line for the loaded agent. Pure sync, no suffix needed.

Parameters: domain (string), ttl (number, optional, default 3600)

Returns: string

getWellKnownJson()

Return the well-known JSON object for the loaded agent. Pure sync, no suffix needed.

Returns: object

getPublicKey()

Get the loaded agent's public key in PEM format. Pure sync, no suffix needed.

Returns: string -- PEM-encoded public key

const pem = jacs.getPublicKey();
console.log(pem);

Type Definitions

AgentInfo

interface AgentInfo {
  agentId: string;      // Agent's UUID
  name: string;         // Agent name from config
  publicKeyPath: string; // Path to public key file
  configPath: string;   // Path to loaded config
}

SignedDocument

interface SignedDocument {
  raw: string;          // Full JSON document with signature
  documentId: string;   // Document's UUID (jacsId)
  agentId: string;      // Signing agent's ID
  timestamp: string;    // ISO 8601 timestamp
}

VerificationResult

interface VerificationResult {
  valid: boolean;       // True if signature verified
  data?: any;           // Extracted document content
  signerId: string;     // Agent who signed
  timestamp: string;    // When it was signed
  attachments: Attachment[];  // File attachments
  errors: string[];     // Error messages if invalid
}

Attachment

interface Attachment {
  filename: string;     // Original filename
  mimeType: string;     // MIME type
  hash: string;         // SHA-256 hash
  embedded: boolean;    // True if content is embedded
  content?: Buffer;     // Embedded content (if available)
}

Complete Example

const jacs = require('@hai.ai/jacs/simple');

// Load agent
const agent = await jacs.load('./jacs.config.json');
console.log(`Loaded agent: ${agent.agentId}`);

// Verify agent integrity
const selfCheck = await jacs.verifySelf();
if (!selfCheck.valid) {
  throw new Error('Agent integrity check failed');
}

// Sign a transaction
const transaction = {
  type: 'payment',
  from: agent.agentId,
  to: 'recipient-agent-uuid',
  amount: 250.00,
  currency: 'USD',
  memo: 'Q1 Service Payment'
};

const signed = await jacs.signMessage(transaction);
console.log(`Transaction signed: ${signed.documentId}`);

// Verify the transaction (simulating recipient)
const verification = await jacs.verify(signed.raw);

if (verification.valid) {
  console.log(`Payment verified from: ${verification.signerId}`);
  console.log(`Amount: ${verification.data.amount} ${verification.data.currency}`);
} else {
  console.log(`Verification failed: ${verification.errors.join(', ')}`);
}

// Sign a file
const contractSigned = await jacs.signFile('./contract.pdf', true);
console.log(`Contract signed: ${contractSigned.documentId}`);

// Update agent metadata
const agentDoc = JSON.parse(jacs.exportAgent());
agentDoc.jacsAgentType = 'ai';
const updatedAgent = await jacs.updateAgent(agentDoc);
console.log('Agent metadata updated');

// Share public key
const publicKey = jacs.getPublicKey();
console.log('Share this public key for verification:');
console.log(publicKey);

MCP Integration

The simplified API works well with MCP tool implementations:

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const jacs = require('@hai.ai/jacs/simple');

// Load agent once at startup
await jacs.load('./jacs.config.json');

// Define a signed tool
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'approve_request') {
    const signed = await jacs.signMessage({
      action: 'approve',
      requestId: args.requestId,
      approvedBy: jacs.getAgentInfo().agentId
    });

    return {
      content: [{ type: 'text', text: signed.raw }]
    };
  }
});

Error Handling

const jacs = require('@hai.ai/jacs/simple');

try {
  await jacs.load('./missing-config.json');
} catch (e) {
  console.error('Config not found:', e.message);
}

try {
  // Will fail if no agent loaded
  await jacs.signMessage({ data: 'test' });
} catch (e) {
  console.error('No agent:', e.message);
}

try {
  await jacs.signFile('/nonexistent/file.pdf');
} catch (e) {
  console.error('File not found:', e.message);
}

// Verification doesn't throw - check result.valid
const result = await jacs.verify('invalid json');
if (!result.valid) {
  console.error('Verification errors:', result.errors);
}

See Also

• Basic Usage - JacsAgent class usage
• API Reference - Complete JacsAgent API
• MCP Integration - Model Context Protocol

Basic Usage

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

v0.7.0: Async-First API

All NAPI operations now return Promises by default. Sync variants are available with a Sync suffix, following the Node.js convention (like fs.readFile vs fs.readFileSync).

// Async (default, recommended)
await agent.load('./jacs.config.json');
const doc = await agent.createDocument(JSON.stringify(content));

// Sync (blocks event loop)
agent.loadSync('./jacs.config.json');
const doc = agent.createDocumentSync(JSON.stringify(content));

Initializing an Agent

Create and Load Agent

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

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

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

// Or use sync variant
agent.loadSync('./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 '@hai.ai/jacs';

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

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

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

With Custom Schema

Validate against a custom JSON Schema:

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

With Output File

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

Without Saving

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

With Attachments

const signedDocument = await 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 = await agent.verifyDocument(signedDocumentJson);
console.log('Document valid:', isValid);

Verify Specific Signature Field

// Verify with a custom signature field
const isValid = await 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 = await agent.updateDocument(
  documentKey,
  JSON.stringify(updatedData)
);

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

Update with New Attachments

const updatedDocument = await 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 = await agent.signString('Important message to sign');
console.log('Signature:', signature);

Verify Arbitrary Data

// Verify a signature on string data
const isValid = await 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 = await 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 = await agent.signAgreement(
  documentWithAgreementJson,
  'jacsAgreement'  // agreement field name
);

Check Agreement Status

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

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

Agent Operations

Verify Agent

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

Update Agent

// Update agent document
const updatedAgentJson = await 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 = await agent.signAgent(
  externalAgentJson,
  publicKeyBuffer,
  'ring-Ed25519'
);

Request/Response Signing

These methods remain synchronous (V8-thread-only, no Sync suffix):

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 '@hai.ai/jacs';

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

Create Configuration

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

// 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 '@hai.ai/jacs';

const agent = new JacsAgent();

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

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

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

Complete Example

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

async function main() {
  // Initialize agent
  const agent = new JacsAgent();
  await 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 = await agent.createDocument(JSON.stringify(task));
  console.log('Task created');

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

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

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

  // Check agreement status
  const status = await 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

MCP Integration (Node.js)

Node has two MCP stories:

1. Wrap an MCP transport with signing and verification
2. Register JACS operations as MCP tools on an existing server

If you want a full out-of-the-box server instead, prefer the Rust jacs-mcp binary.

Install

npm install @hai.ai/jacs @modelcontextprotocol/sdk

1. Wrap A Transport

Use this when you already have an MCP server or client and want signed JSON-RPC messages.

With a loaded client

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { JacsClient } from '@hai.ai/jacs/client';
import { createJACSTransportProxy } from '@hai.ai/jacs/mcp';

const client = await JacsClient.quickstart({
  name: 'mcp-agent',
  domain: 'mcp.local',
});

const transport = new StdioServerTransport();
const secureTransport = createJACSTransportProxy(transport, client, 'server');

With only a config path

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

const secureTransport = await createJACSTransportProxyAsync(
  transport,
  './jacs.config.json',
  'server',
);

createJACSTransportProxy() does not take a config path. Use the async factory when the agent is not already loaded.

2. Register JACS Tools On Your MCP Server

Use this when the model should explicitly call JACS operations such as signing, verification, agreement creation, or trust-store inspection.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { JacsClient } from '@hai.ai/jacs/client';
import { registerJacsTools } from '@hai.ai/jacs/mcp';

const server = new Server(
  { name: 'jacs-tools', version: '1.0.0' },
  { capabilities: { tools: {} } },
);

const client = await JacsClient.quickstart({
  name: 'mcp-agent',
  domain: 'mcp.local',
});

registerJacsTools(server, client);

The registered tool set includes:

• document signing and verification
• agreement helpers
• audit and agent-info helpers
• trust-store helpers
• setup and registry helper stubs

For lower-level integration, use getJacsMcpToolDefinitions() plus handleJacsMcpToolCall().

Failure Behavior

The transport proxy is not permissive by default.

• Signing or verification failures fail closed unless you explicitly pass allowUnsignedFallback: true
• createJACSTransportProxy() expects a real JacsClient or JacsAgent, not an unloaded shell

Common Pattern

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { JacsClient } from '@hai.ai/jacs/client';
import { createJACSTransportProxy } from '@hai.ai/jacs/mcp';

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});

const server = new McpServer({ name: 'my-server', version: '1.0.0' });
const transport = new StdioServerTransport();
const secureTransport = createJACSTransportProxy(transport, client, 'server');

await server.connect(secureTransport);

For stdio servers, keep logs on stderr, not stdout.

Example Paths In This Repo

• jacsnpm/examples/mcp.stdio.server.js
• jacsnpm/examples/mcp.stdio.client.js
• jacsnpm/examples/mcp.sse.server.js
• jacsnpm/examples/mcp.sse.client.js

When To Use LangChain Instead

Choose LangChain.js Integration instead when:

• the model and tools already live in the same Node.js process
• you only need signed tool outputs, not an MCP boundary
• you do not need other MCP clients to connect

LangChain.js Integration

Use the LangChain.js adapter when the model already runs inside your Node.js app and you want provenance at the tool boundary.

Choose The Pattern

Give The Agent JACS Tools

Use createJacsTools() when the model should explicitly ask to sign, verify, inspect trust, or create agreements.

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

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});

const jacsTools = createJacsTools({ client });
const llmWithTools = model.bindTools([...myTools, ...jacsTools]);

The tool set includes 14 tools:

• jacs_sign
• jacs_verify
• jacs_create_agreement
• jacs_sign_agreement
• jacs_check_agreement
• jacs_verify_self
• jacs_trust_agent
• jacs_trust_agent_with_key
• jacs_list_trusted
• jacs_is_trusted
• jacs_share_public_key
• jacs_share_agent
• jacs_audit
• jacs_agent_info

Auto-Sign Existing Tools

Use this when the model should keep using your existing tool set but every result needs a signature.

Wrap one tool:

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

const signed = signedTool(mySearchTool, { client });

Wrap a LangGraph ToolNode:

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

const node = jacsToolNode([tool1, tool2], { client });

For custom graph logic:

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

const wrapToolCall = jacsWrapToolCall({ client });

Install

npm install @hai.ai/jacs @langchain/core
npm install @langchain/langgraph

@langchain/langgraph is only required for jacsToolNode().

Strict Mode

Pass strict: true when you want wrapper failures to throw instead of returning error-shaped output:

const jacsTools = createJacsTools({ client, strict: true });

Examples In This Repo

• jacsnpm/examples/langchain/basic-agent.ts
• jacsnpm/examples/langchain/signing-callback.ts

When To Use MCP Instead

Choose Node.js MCP Integration instead when:

• the model is outside your process and connects over MCP
• you want a shared MCP server usable by multiple clients
• you need transport-level signing in addition to signed tool outputs

Vercel AI SDK

Sign it. Prove it. -- for every AI model output.

The JACS Vercel AI SDK adapter adds cryptographic provenance to AI-generated text and tool results using the LanguageModelV3Middleware pattern. Works with generateText, streamText, and any model provider (OpenAI, Anthropic, etc.).

5-Minute Quickstart

1. Install

npm install @hai.ai/jacs ai @ai-sdk/openai

2. Create a JACS client

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

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});

3. Sign every model output

import { withProvenance } from '@hai.ai/jacs/vercel-ai';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const model = withProvenance(openai('gpt-4'), { client });
const { text, providerMetadata } = await generateText({ model, prompt: 'Hello!' });

console.log(providerMetadata?.jacs?.text?.documentId); // JACS document ID

Quick Start

import { JacsClient } from '@hai.ai/jacs/client';
import { withProvenance } from '@hai.ai/jacs/vercel-ai';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
const model = withProvenance(openai('gpt-4'), { client });

const { text, providerMetadata } = await generateText({
  model,
  prompt: 'Summarize the quarterly report.',
});

console.log(text);
console.log(providerMetadata?.jacs?.text?.documentId); // JACS document ID
console.log(providerMetadata?.jacs?.text?.signed);      // true

Every model output is signed by your JACS agent. The provenance record is attached to providerMetadata.jacs.

Installation

npm install @hai.ai/jacs ai @ai-sdk/openai  # or any provider

The ai package is a peer dependency.

Two Ways to Use

withProvenance (convenience)

Wraps a model with the JACS middleware in one call:

import { withProvenance } from '@hai.ai/jacs/vercel-ai';

const model = withProvenance(openai('gpt-4'), { client });

jacsProvenance (composable)

Returns a LanguageModelV3Middleware you can compose with other middleware:

import { jacsProvenance } from '@hai.ai/jacs/vercel-ai';
import { wrapLanguageModel } from 'ai';

const provenance = jacsProvenance({ client });

const model = wrapLanguageModel({
  model: openai('gpt-4'),
  middleware: provenance,
});

Options

interface ProvenanceOptions {
  client: JacsClient;                  // Required: initialized JacsClient
  signText?: boolean;                  // Sign generated text (default: true)
  signToolResults?: boolean;           // Sign tool call results (default: true)
  strict?: boolean;                    // Throw on signing failure (default: false)
  metadata?: Record<string, unknown>;  // Extra metadata in provenance records
}

Streaming

Streaming works automatically. Text chunks are accumulated and signed when the stream completes:

import { streamText } from 'ai';

const result = streamText({
  model: withProvenance(openai('gpt-4'), { client }),
  prompt: 'Write a haiku.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

// Provenance is available after stream completes
const metadata = await result.providerMetadata;
console.log(metadata?.jacs?.text?.signed); // true

Tool Call Signing

When signToolResults is true (default), tool results in the prompt are signed:

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text, providerMetadata } = await generateText({
  model: withProvenance(openai('gpt-4'), { client }),
  tools: {
    getWeather: tool({
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => `Weather in ${city}: sunny, 72F`,
    }),
  },
  prompt: 'What is the weather in Paris?',
});

// Both text output and tool results are signed
console.log(providerMetadata?.jacs?.text?.signed);
console.log(providerMetadata?.jacs?.toolResults?.signed);

Provenance Record

Each signed output produces a ProvenanceRecord:

interface ProvenanceRecord {
  signed: boolean;       // Whether signing succeeded
  documentId: string;    // JACS document ID
  agentId: string;       // Signing agent's ID
  timestamp: string;     // ISO 8601 timestamp
  error?: string;        // Error message if signing failed
  metadata?: Record<string, unknown>;
}

Access records from providerMetadata.jacs:

const { providerMetadata } = await generateText({ model, prompt: '...' });

const textProvenance = providerMetadata?.jacs?.text;
const toolProvenance = providerMetadata?.jacs?.toolResults;

Strict Mode

By default, signing failures are logged but do not throw. Enable strict to throw on failure:

const model = withProvenance(openai('gpt-4'), {
  client,
  strict: true,  // Throws if signing fails
});

Next Steps

• Express Middleware - Sign HTTP API responses
• MCP Integration - Secure MCP transport
• API Reference - Complete API documentation

Express Middleware

Sign it. Prove it. -- in your Express app.

JACS provides jacsMiddleware for Express v4/v5 that verifies incoming signed request bodies and optionally auto-signs JSON responses. No body-parser gymnastics, no monkey-patching.

5-Minute Quickstart

1. Install

npm install @hai.ai/jacs express

2. Create a JACS client

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

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});

3. Add signing middleware

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

const app = express();
app.use(express.text({ type: 'application/json' }));
app.use(jacsMiddleware({ client, verify: true }));

app.post('/api/data', (req, res) => {
  console.log(req.jacsPayload); // verified payload
  res.json({ status: 'ok' });
});

app.listen(3000);

Quick Start

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

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
const app = express();

app.use(express.text({ type: 'application/json' }));
app.use(jacsMiddleware({ client, verify: true }));

app.post('/api/data', (req, res) => {
  console.log(req.jacsPayload); // verified payload
  res.json({ status: 'ok' });
});

app.listen(3000);

Options

jacsMiddleware({
  client?: JacsClient;      // Pre-initialized client (preferred)
  configPath?: string;       // Path to jacs.config.json (if no client)
  sign?: boolean;            // Auto-sign res.json() responses (default: false)
  verify?: boolean;          // Verify incoming POST/PUT/PATCH bodies (default: true)
  optional?: boolean;        // Allow unsigned requests through (default: false)
  authReplay?: boolean | {   // Replay protection for auth-style endpoints (default: false)
    enabled?: boolean;
    maxAgeSeconds?: number;    // default: 30
    clockSkewSeconds?: number; // default: 5
    cacheTtlSeconds?: number;  // default: maxAge + skew
  };
})

If neither client nor configPath is provided, the middleware initializes a client with JacsClient.quickstart({ name: 'jacs-express', domain: 'localhost' }) on first request.

What the Middleware Does

Every request gets req.jacsClient -- a JacsClient instance you can use for manual signing/verification in route handlers.

POST/PUT/PATCH with verify: true (default): The string body is verified as a JACS document. On success, req.jacsPayload contains the extracted payload. On failure, a 401 is returned (unless optional: true).

With sign: true: res.json() is intercepted to auto-sign the response body before sending.

Verify Incoming Requests

app.use(express.text({ type: 'application/json' }));
app.use(jacsMiddleware({ client }));

app.post('/api/process', (req, res) => {
  if (!req.jacsPayload) {
    return res.status(400).json({ error: 'Missing payload' });
  }

  const { action, data } = req.jacsPayload;
  res.json({ processed: true, action });
});

With optional: true, unsigned requests pass through with req.jacsPayload unset:

app.use(jacsMiddleware({ client, optional: true }));

app.post('/api/mixed', (req, res) => {
  if (req.jacsPayload) {
    // Verified JACS request
    res.json({ verified: true, data: req.jacsPayload });
  } else {
    // Unsigned request -- handle accordingly
    res.json({ verified: false });
  }
});

Auth Replay Protection (Auth Endpoints)

Enable replay protection when signed JACS bodies are used as authentication artifacts:

app.use(
  jacsMiddleware({
    client,
    verify: true,
    authReplay: { enabled: true, maxAgeSeconds: 30, clockSkewSeconds: 5 },
  })
);

When enabled, middleware enforces:

• signature timestamp freshness (maxAgeSeconds + clockSkewSeconds)
• single-use (signerId, signature) dedupe inside a TTL cache

Notes:

• Keep this mode scoped to auth-style endpoints.
• Cache is in-memory per process; use a shared cache for multi-instance deployments.

Auto-Sign Responses

Enable sign: true to intercept res.json() calls:

app.use(jacsMiddleware({ client, sign: true }));

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

Manual Signing in Routes

Use req.jacsClient for fine-grained control:

app.use(jacsMiddleware({ client }));

app.post('/api/custom', async (req, res) => {
  const result = processData(req.jacsPayload);

  // Sign manually
  const signed = await req.jacsClient.signMessage(result);
  res.type('application/json').send(signed.raw);
});

Per-Route Middleware

Apply JACS to specific routes only:

const app = express();
const jacs = jacsMiddleware({ client });

// Public routes -- no JACS
app.get('/health', (req, res) => res.json({ status: 'ok' }));

// Protected routes
app.use('/api', express.text({ type: 'application/json' }), jacs);

app.post('/api/secure', (req, res) => {
  res.json({ data: req.jacsPayload });
});

Multiple Agents

Use different JacsClient instances per route group:

const adminClient = await JacsClient.quickstart({
  name: 'admin-agent',
  domain: 'admin.example.com',
  algorithm: 'pq2025',
});
const userClient = await JacsClient.quickstart({
  name: 'user-agent',
  domain: 'user.example.com',
  algorithm: 'ring-Ed25519',
});

app.use('/admin', express.text({ type: 'application/json' }));
app.use('/admin', jacsMiddleware({ client: adminClient }));

app.use('/user', express.text({ type: 'application/json' }));
app.use('/user', jacsMiddleware({ client: userClient }));

Migration from JACSExpressMiddleware

The legacy JACSExpressMiddleware from @hai.ai/jacs/http still works but is deprecated. To migrate:

The new middleware is simpler, faster (no per-request init), and gives you req.jacsClient for manual operations.

Next Steps

• Koa Middleware - Same pattern for Koa
• HTTP Server - Core HTTP integration concepts
• Vercel AI SDK - AI model provenance signing
• API Reference - Complete API documentation

Koa Middleware

Sign it. Prove it. -- in your Koa app.

JACS provides jacsKoaMiddleware for Koa with the same design as the Express middleware -- verify incoming signed bodies, optionally auto-sign responses.

Quick Start

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { JacsClient } from '@hai.ai/jacs/client';
import { jacsKoaMiddleware } from '@hai.ai/jacs/koa';

const client = await JacsClient.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});
const app = new Koa();

app.use(bodyParser({ enableTypes: ['text'] }));
app.use(jacsKoaMiddleware({ client, verify: true }));

app.use(async (ctx) => {
  console.log(ctx.state.jacsPayload); // verified payload
  ctx.body = { status: 'ok' };
});

app.listen(3000);

Options

jacsKoaMiddleware({
  client?: JacsClient;      // Pre-initialized client (preferred)
  configPath?: string;       // Path to jacs.config.json (if no client)
  sign?: boolean;            // Auto-sign ctx.body after next() (default: false)
  verify?: boolean;          // Verify incoming POST/PUT/PATCH bodies (default: true)
  optional?: boolean;        // Allow unsigned requests through (default: false)
  authReplay?: boolean | {   // Replay protection for auth-style endpoints (default: false)
    enabled?: boolean;
    maxAgeSeconds?: number;    // default: 30
    clockSkewSeconds?: number; // default: 5
    cacheTtlSeconds?: number;  // default: maxAge + skew
  };
})

How It Works

Every request gets ctx.state.jacsClient for manual use.

POST/PUT/PATCH with verify: true: The string body is verified. On success, ctx.state.jacsPayload is set. On failure, 401 is returned (unless optional: true).

With sign: true: After downstream middleware runs, if ctx.body is a non-Buffer object, it is signed before the response is sent.

Auth Replay Protection (Auth Endpoints)

Enable replay protection when signed JACS bodies are used as authentication artifacts:

app.use(
  jacsKoaMiddleware({
    client,
    verify: true,
    authReplay: { enabled: true, maxAgeSeconds: 30, clockSkewSeconds: 5 },
  })
);

When enabled, middleware enforces:

• signature timestamp freshness (maxAgeSeconds + clockSkewSeconds)
• single-use (signerId, signature) dedupe inside a TTL cache

Notes:

• Keep this mode scoped to auth-style endpoints.
• Cache is in-memory per process; use a shared cache for multi-instance deployments.

Auto-Sign Responses

app.use(jacsKoaMiddleware({ client, sign: true }));

app.use(async (ctx) => {
  // This will be JACS-signed automatically after next()
  ctx.body = { result: 42, timestamp: new Date().toISOString() };
});

Manual Signing

app.use(jacsKoaMiddleware({ client }));

app.use(async (ctx) => {
  const result = processData(ctx.state.jacsPayload);
  const signed = await ctx.state.jacsClient.signMessage(result);
  ctx.type = 'application/json';
  ctx.body = signed.raw;
});

Comparison with Express

Next Steps

• Express Middleware - Express version
• Vercel AI SDK - AI model provenance signing
• 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 '@hai.ai/jacs';
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 '@hai.ai/jacs';

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 '@hai.ai/jacs/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 '@hai.ai/jacs';

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 '@hai.ai/jacs/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 '@hai.ai/jacs/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 '@hai.ai/jacs/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 '@hai.ai/jacs/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 '@hai.ai/jacs';

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

API Reference

Complete API documentation for the @hai.ai/jacs Node.js package.

Installation

npm install @hai.ai/jacs

v0.7.0: Async-First API

All NAPI operations now return Promises by default. Sync variants are available with a Sync suffix, following the Node.js convention (like fs.readFile vs fs.readFileSync).

// Async (default, recommended)
await agent.load('./jacs.config.json');
const doc = await agent.createDocument(JSON.stringify(content));

// Sync (blocks event loop)
agent.loadSync('./jacs.config.json');
const doc = agent.createDocumentSync(JSON.stringify(content));

Core Module

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

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() or loadSync() to initialize with a configuration.

Example:

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

agent.load(configPath) / agent.loadSync(configPath)

Load and initialize the agent from a configuration file.

Parameters:

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

Returns: Promise<string> (async) or string (sync) -- The loaded agent's JSON

Example:

const agent = new JacsAgent();

// Async (recommended)
const agentJson = await agent.load('./jacs.config.json');

// Sync
const agentJson = agent.loadSync('./jacs.config.json');

console.log('Agent loaded:', JSON.parse(agentJson).jacsId);

agent.createDocument(...) / agent.createDocumentSync(...)

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: Promise<string> (async) or string (sync) -- The signed document as a JSON string

Example:

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

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

agent.verifyDocument(...) / agent.verifyDocumentSync(...)

Verify a document's signature and hash integrity.

Parameters:

• documentString (string): The signed document JSON string

Returns: Promise<boolean> (async) or boolean (sync) -- True if the document is valid

Example:

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

agent.verifySignature(...) / agent.verifySignatureSync(...)

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: Promise<boolean> (async) or boolean (sync)

agent.updateDocument(...) / agent.updateDocumentSync(...)

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: Promise<string> (async) or string (sync)

Example:

const doc = JSON.parse(signedDoc);
const documentKey = `${doc.jacsId}:${doc.jacsVersion}`;
const updatedDoc = await agent.updateDocument(
  documentKey,
  JSON.stringify({ ...doc, title: 'Updated Title' })
);

agent.createAgreement(...) / agent.createAgreementSync(...)

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
• agreementFieldName (string, optional): Field name (default: 'jacsAgreement')

Returns: Promise<string> (async) or string (sync)

agent.signAgreement(...) / agent.signAgreementSync(...)

Sign an agreement as the current agent.

Parameters:

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

Returns: Promise<string> (async) or string (sync)

agent.checkAgreement(...) / agent.checkAgreementSync(...)

Check the status of an agreement.

Parameters:

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

Returns: Promise<string> (async) or string (sync) -- JSON string with agreement status

agent.signArtifact(...) / agent.signArtifactSync(...)

Sign an A2A artifact with JACS provenance. This is the canonical method name.

Parameters:

• artifactJson (string): JSON string of the artifact to sign
• artifactType (string): Type of artifact (e.g., "task", "message")
• parentSignaturesJson (string, optional): JSON string of parent signatures for chain of custody

Returns: Promise<string> (async) or string (sync) -- The signed, wrapped artifact as a JSON string

Example:

const signed = await agent.signArtifact(
  JSON.stringify({ action: 'classify', input: 'hello' }),
  'task'
);

agent.wrapA2aArtifact(...) / agent.wrapA2aArtifactSync(...)

Deprecated since 0.9.0. Use signArtifact() / signArtifactSync() instead. This method will be removed in 1.0.0.

Set JACS_SHOW_DEPRECATIONS=1 to see runtime warnings when deprecated methods are called.

Wraps an A2A artifact with JACS provenance signature. Identical behavior to signArtifact() / signArtifactSync().

Parameters: Same as signArtifact() / signArtifactSync().

agent.signString(...) / agent.signStringSync(...)

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

Parameters:

• data (string): The data to sign

Returns: Promise<string> (async) or string (sync) -- Base64-encoded signature

agent.verifyString(...) / agent.verifyStringSync(...)

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: Promise<boolean> (async) or boolean (sync)

agent.signRequest(params) -- V8-thread-only

Sign a request payload, wrapping it in a JACS document. This method is synchronous (no Sync suffix) because it uses V8-thread-only APIs.

Parameters:

• params (any): The request payload object

Returns: string -- JACS-signed request as a JSON string

agent.verifyResponse(documentString) -- V8-thread-only

Verify a JACS-signed response and extract the payload. Synchronous only.

Parameters:

• documentString (string): The JACS-signed response

Returns: object -- Object containing the verified payload

agent.verifyResponseWithAgentId(documentString) -- V8-thread-only

Verify a response and return both the payload and signer's agent ID. Synchronous only.

Parameters:

• documentString (string): The JACS-signed response

Returns: object -- Object with payload and agent ID

agent.verifyAgent(...) / agent.verifyAgentSync(...)

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: Promise<boolean> (async) or boolean (sync)

agent.updateAgent(...) / agent.updateAgentSync(...)

Update the agent document with new data.

Parameters:

• newAgentString (string): The modified agent document as JSON string

Returns: Promise<string> (async) or string (sync)

agent.signAgent(...) / agent.signAgentSync(...)

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: Promise<string> (async) or string (sync)

Utility Functions

hashString(data)

Hash a string using SHA-256.

Parameters:

• data (string): The string to hash

Returns: string -- Hexadecimal hash string

import { hashString } from '@hai.ai/jacs';
const hash = hashString('data to hash');

createConfig(options)

Create a JACS configuration JSON string programmatically.

Parameters:

• jacsUseSecurity (string, optional)
• jacsDataDirectory (string, optional)
• jacsKeyDirectory (string, optional)
• jacsAgentPrivateKeyFilename (string, optional)
• jacsAgentPublicKeyFilename (string, optional)
• jacsAgentKeyAlgorithm (string, optional)
• jacsPrivateKeyPassword (string, optional)
• jacsAgentIdAndVersion (string, optional)
• jacsDefaultStorage (string, optional)

Returns: string -- Configuration as JSON string

HTTP Module

import { JACSExpressMiddleware, JACSKoaMiddleware } from '@hai.ai/jacs/http';

JACSExpressMiddleware(options)

Express middleware for JACS request/response handling.

Parameters:

• options.configPath (string): Path to JACS configuration file

Returns: Express middleware function

JACSKoaMiddleware(options)

Koa middleware for JACS request/response handling.

Parameters:

• options.configPath (string): Path to JACS configuration file

Returns: Koa middleware function

MCP Module

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

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

createJACSTransportProxyAsync(transport, configPath, role)

Async factory that waits for JACS to be fully loaded.

Returns: Promise

TypeScript Support

The package includes full TypeScript definitions. Import types as needed:

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

const agent: JacsAgent = new JacsAgent();
const hash: string = hashString('data');

Deprecated Functions

The following module-level functions are deprecated. Use new JacsAgent() and instance methods instead:

• load() -> Use agent.load() / agent.loadSync()
• signAgent() -> Use agent.signAgent() / agent.signAgentSync()
• verifyString() -> Use agent.verifyString() / agent.verifyStringSync()
• signString() -> Use agent.signString() / agent.signStringSync()
• verifyAgent() -> Use agent.verifyAgent() / agent.verifyAgentSync()
• updateAgent() -> Use agent.updateAgent() / agent.updateAgentSync()
• verifyDocument() -> Use agent.verifyDocument() / agent.verifyDocumentSync()
• updateDocument() -> Use agent.updateDocument() / agent.updateDocumentSync()
• verifySignature() -> Use agent.verifySignature() / agent.verifySignatureSync()
• createAgreement() -> Use agent.createAgreement() / agent.createAgreementSync()
• signAgreement() -> Use agent.signAgreement() / agent.signAgreementSync()
• createDocument() -> Use agent.createDocument() / agent.createDocumentSync()
• checkAgreement() -> Use agent.checkAgreement() / agent.checkAgreementSync()
• signRequest() -> Use agent.signRequest() (V8-thread-only, sync)
• verifyResponse() -> Use agent.verifyResponse() (V8-thread-only, sync)
• verifyResponseWithAgentId() -> Use agent.verifyResponseWithAgentId() (V8-thread-only, sync)

Migration Example:

// Old (deprecated, v0.6.x)
import jacs from '@hai.ai/jacs';
jacs.load('./jacs.config.json');
const doc = jacs.createDocument(JSON.stringify({ data: 'test' }));

// New (v0.7.0, async)
import { JacsAgent } from '@hai.ai/jacs';
const agent = new JacsAgent();
await agent.load('./jacs.config.json');
const doc = await agent.createDocument(JSON.stringify({ data: 'test' }));

// New (v0.7.0, sync)
import { JacsAgent } from '@hai.ai/jacs';
const agent = new JacsAgent();
agent.loadSync('./jacs.config.json');
const doc = agent.createDocumentSync(JSON.stringify({ data: 'test' }));

Error Handling

All methods may throw errors. Use try/catch for error handling:

try {
  const agent = new JacsAgent();
  await agent.load('./jacs.config.json');
  const doc = await 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

For framework adapters (LangChain, FastAPI, CrewAI, Anthropic, etc.) use optional extras, e.g. pip install jacs[langchain], jacs[fastapi], or jacs[all]. Optional: jacs[langgraph], jacs[ws]. See Framework Adapters and the package pyproject.toml.

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!')

# Quick check (no config file; in-memory agent)
from jacs.client import JacsClient
client = JacsClient.ephemeral()
signed = client.sign_message({"hello": "jacs"})
result = client.verify(signed.raw_json)
print('Sign & verify OK:', result.valid)

Or with an existing config file:

import jacs
agent = jacs.JacsAgent()
agent.load('./jacs.config.json')
print('Agent loaded successfully!')

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

Local Indexed SQLite

{
  "jacs_default_storage": "rusqlite"
}

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

AWS Storage

{
  "jacs_default_storage": "aws"
}

AWS credentials are read from standard AWS environment variables.

Memory Storage (Testing)

{
  "jacs_default_storage": "memory"
}

Cryptographic Algorithms

ring-Ed25519 (Recommended)

{
  "jacs_agent_key_algorithm": "ring-Ed25519"
}

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

RSA-PSS

{
  "jacs_agent_key_algorithm": "RSA-PSS"
}

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

pq-dilithium (Post-Quantum)

{
  "jacs_agent_key_algorithm": "pq-dilithium"
}

Pros: Quantum-resistant Cons: Experimental, large signatures

pq2025 (Post-Quantum Hybrid)

{
  "jacs_agent_key_algorithm": "pq2025"
}

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

Development Setup

Project Structure

my-jacs-project/
├── 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.9.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

Simplified API

The simplified API (jacs.simple) provides a streamlined, module-level interface for common JACS operations. It's designed to get you signing and verifying in under 2 minutes.

Quick Start

Zero-config -- one call to start signing:

import jacs.simple as jacs

info = jacs.quickstart(name="my-agent", domain="my-agent.example.com")
print(info.config_path, info.public_key_path, info.private_key_path)
signed = jacs.sign_message({"action": "approve", "amount": 100})
result = jacs.verify(signed.raw)
print(f"Valid: {result.valid}, Signer: {result.signer_id}")

quickstart(name, domain, ...) creates a persistent agent with keys on disk (default algorithm: pq2025). If ./jacs.config.json already exists, it loads it; otherwise it creates a new agent. Returned AgentInfo includes config/key paths (config_path/public_key_path/private_key_path in Python, configPath/publicKeyPath/privateKeyPath in Node) plus key directory metadata so you can locate key material immediately. Rust/CLI quickstart requires an explicit password source (JACS_PRIVATE_KEY_PASSWORD, or JACS_PASSWORD_FILE in CLI). Python/Node can auto-generate a password if needed; set JACS_SAVE_PASSWORD_FILE=true if you want that generated password persisted to ./jacs_keys/.jacs_password. Pass algorithm="ring-Ed25519" to override the default (pq2025).

To load an existing agent explicitly, use load() instead:

agent = jacs.load("./jacs.config.json")
signed = jacs.sign_message({"action": "approve", "amount": 100})

When to Use the Simplified API

API Reference

quickstart(name, domain, description=None, algorithm=None, config_path=None)

Create a persistent agent with keys on disk. If ./jacs.config.json already exists, loads it. Otherwise creates a new agent, saving keys and config to disk. If JACS_PRIVATE_KEY_PASSWORD is unset, Python quickstart auto-generates a secure password in-process (JACS_SAVE_PASSWORD_FILE=true persists it to ./jacs_keys/.jacs_password). Call this once before sign_message() or verify().

Parameters:

• name (str, required): Agent name used for first-time creation.
• domain (str, required): Agent domain used for DNS/public-key verification workflows.
• description (str, optional): Human-readable description.
• algorithm (str, optional): Signing algorithm. Default: "pq2025". Also: "ring-Ed25519", "RSA-PSS".
• config_path (str, optional): Config path (default: "./jacs.config.json").

Returns: AgentInfo dataclass

info = jacs.quickstart(name="my-agent", domain="my-agent.example.com")
print(f"Agent ID: {info.agent_id}")
print(f"Config path: {info.config_path}")
print(f"Public key: {info.public_key_path}")
print(f"Private key: {info.private_key_path}")

# Or with a specific algorithm
info = jacs.quickstart(
    name="my-agent",
    domain="my-agent.example.com",
    algorithm="ring-Ed25519",
)

load(config_path=None, strict=None)

Load a persistent agent from a configuration file. Use this instead of quickstart(name=..., domain=..., ...) when you want to load a specific config file explicitly.

Parameters:

• config_path (str, optional): Path to jacs.config.json (default: "./jacs.config.json")
• strict (bool, optional): If True, verification failures raise; if None, uses JACS_STRICT_MODE env var

Returns: AgentInfo dataclass

Raises: JacsError if config not found or invalid

info = jacs.load("./jacs.config.json")
print(f"Agent ID: {info.agent_id}")
print(f"Config: {info.config_path}")

is_loaded()

Check if an agent is currently loaded.

Returns: bool

if not jacs.is_loaded():
    jacs.load("./jacs.config.json")

get_agent_info()

Get information about the currently loaded agent.

Returns: AgentInfo or None if no agent is loaded

info = jacs.get_agent_info()
if info:
    print(f"Agent: {info.agent_id}")

verify_self()

Verify the loaded agent's own integrity (signature and hash).

Returns: VerificationResult

Raises: AgentNotLoadedError if no agent is loaded

result = jacs.verify_self()
if result.valid:
    print("Agent integrity verified")
else:
    print(f"Errors: {result.errors}")

sign_message(data)

Sign arbitrary data as a JACS document.

Parameters:

• data (any): Dict, list, string, or any JSON-serializable value

Returns: SignedDocument

Raises: AgentNotLoadedError if no agent is loaded

# Sign a dict
signed = jacs.sign_message({
    "action": "transfer",
    "amount": 500,
    "recipient": "agent-123"
})

print(f"Document ID: {signed.document_id}")
print(f"Signed by: {signed.agent_id}")
print(f"Timestamp: {signed.timestamp}")
print(f"Raw JSON: {signed.raw}")

sign_file(file_path, embed=False)

Sign a file with optional content embedding.

Parameters:

• file_path (str): Path to the file to sign
• embed (bool, optional): If True, embed file content in the document (default: False)

Returns: SignedDocument

Raises: JacsError if file not found or no agent loaded

# Reference only (stores hash)
signed = jacs.sign_file("contract.pdf", embed=False)

# Embed content (creates portable document)
embedded = jacs.sign_file("contract.pdf", embed=True)

verify(signed_document)

Verify a signed document and extract its content.

Parameters:

• signed_document (str|dict|SignedDocument): The signed document as JSON string, dict, or SignedDocument

Returns: VerificationResult

Raises: AgentNotLoadedError if no agent is loaded

result = jacs.verify(signed_json)

if result.valid:
    print(f"Signed by: {result.signer_id}")
    print(f"Timestamp: {result.timestamp}")
else:
    print(f"Invalid: {', '.join(result.errors)}")

verify_standalone(document, key_resolution="local", data_directory=None, key_directory=None)

Verify a signed document without loading an agent. Use when you only need to verify (e.g. a lightweight API).

Parameters: document (str|dict), key_resolution (str), data_directory (str, optional), key_directory (str, optional)

Returns: VerificationResult

verify_by_id(document_id)

Verify a document by its storage ID (uuid:version) without passing the full JSON. Requires the document to be stored locally (e.g. in the agent's data directory).

Parameters: document_id (str): Document ID in format "uuid:version"

Returns: VerificationResult

reencrypt_key(old_password, new_password)

Re-encrypt the loaded agent's private key with a new password.

Parameters: old_password (str), new_password (str)

Raises: AgentNotLoadedError if no agent loaded; JacsError if password is wrong

audit(config_path=None, recent_n=None)

Run a read-only security audit and health checks. Returns a dict with risks, health_checks, summary, and overall_status. Does not require a loaded agent; does not modify state.

See Security Model — Security Audit for full details and options.

result = jacs.audit()
print(f"Risks: {len(result['risks'])}, Status: {result['overall_status']}")

update_agent(new_agent_data)

Update the agent document with new data and re-sign it.

This function expects a complete agent document (not partial updates). Use export_agent() to get the current document, modify it, then pass it here.

Parameters:

• new_agent_data (dict|str): Complete agent document as JSON string or dict

Returns: str - The updated and re-signed agent document

Raises: AgentNotLoadedError if no agent loaded, JacsError if validation fails

import json

# Get current agent document
agent_doc = json.loads(jacs.export_agent())

# Modify fields
agent_doc["jacsAgentType"] = "hybrid"
agent_doc["jacsContacts"] = [{"contactFirstName": "Jane", "contactLastName": "Doe"}]

# Update (creates new version, re-signs, re-hashes)
updated = jacs.update_agent(agent_doc)
new_doc = json.loads(updated)

print(f"New version: {new_doc['jacsVersion']}")
print(f"Previous: {new_doc['jacsPreviousVersion']}")

Valid jacsAgentType values: "human", "human-org", "hybrid", "ai"

update_document(document_id, new_document_data, attachments=None, embed=False)

Update an existing document with new data and re-sign it.

Note: The original document must have been saved to disk (created without no_save=True).

Parameters:

• document_id (str): The document ID (jacsId) to update
• new_document_data (dict|str): Updated document as JSON string or dict
• attachments (list, optional): List of file paths to attach
• embed (bool, optional): If True, embed attachment contents

Returns: SignedDocument with the updated document

Raises: JacsError if document not found, no agent loaded, or validation fails

import json

# Create a document (must be saved to disk)
original = jacs.sign_message({"status": "pending", "amount": 100})

# Later, update it
doc = json.loads(original.raw)
doc["content"]["status"] = "approved"

updated = jacs.update_document(original.document_id, doc)
new_doc = json.loads(updated.raw)

print(f"New version: {new_doc['jacsVersion']}")
print(f"Previous: {new_doc['jacsPreviousVersion']}")

export_agent()

Export the current agent document for sharing or inspection.

Returns: str - The agent JSON document

Raises: AgentNotLoadedError if no agent loaded

agent_doc = jacs.export_agent()
print(agent_doc)

# Parse to inspect
agent = json.loads(agent_doc)
print(f"Agent type: {agent['jacsAgentType']}")

get_dns_record(domain, ttl=3600)

Return the DNS TXT record line for the loaded agent (for DNS-based discovery). Format: _v1.agent.jacs.{domain}. TTL IN TXT "v=hai.ai; ...".

Returns: str

get_well_known_json()

Return the well-known JSON object for the loaded agent (e.g. for /.well-known/jacs-pubkey.json). Keys: publicKey, publicKeyHash, algorithm, agentId.

Returns: dict

get_public_key()

Get the loaded agent's public key in PEM format for sharing with others.

Returns: str - PEM-encoded public key

Raises: AgentNotLoadedError if no agent loaded

pem = jacs.get_public_key()
print(pem)
# -----BEGIN PUBLIC KEY-----
# ...
# -----END PUBLIC KEY-----

Type Definitions

All types are Python dataclasses for convenient access:

AgentInfo

@dataclass
class AgentInfo:
    agent_id: str       # Agent's UUID
    config_path: str    # Path to loaded config
    public_key_path: Optional[str] = None  # Path to public key file

SignedDocument

@dataclass
class SignedDocument:
    raw: str            # Full JSON document with signature
    document_id: str    # Document's UUID (jacsId)
    agent_id: str       # Signing agent's ID
    timestamp: str      # ISO 8601 timestamp

VerificationResult

@dataclass
class VerificationResult:
    valid: bool                  # True if signature verified
    signer_id: Optional[str]     # Agent who signed
    timestamp: Optional[str]     # When it was signed
    attachments: List[Attachment]  # File attachments
    errors: List[str]            # Error messages if invalid

Attachment

@dataclass
class Attachment:
    filename: str       # Original filename
    mime_type: str      # MIME type
    content_hash: str   # SHA-256 hash of file content
    content: Optional[str] = None  # Base64-encoded content (if embedded)
    size_bytes: int = 0 # Size of the original file

Exceptions

class JacsError(Exception):
    """Base exception for JACS errors."""
    pass

class AgentNotLoadedError(JacsError):
    """Raised when an operation requires a loaded agent."""
    pass

Complete Example

import json
import jacs.simple as jacs
from jacs.types import JacsError, AgentNotLoadedError

# Load agent
agent = jacs.load("./jacs.config.json")
print(f"Loaded agent: {agent.agent_id}")

# Verify agent integrity
self_check = jacs.verify_self()
if not self_check.valid:
    raise RuntimeError("Agent integrity check failed")

# Sign a transaction
transaction = {
    "type": "payment",
    "from": agent.agent_id,
    "to": "recipient-agent-uuid",
    "amount": 250.00,
    "currency": "USD",
    "memo": "Q1 Service Payment"
}

signed = jacs.sign_message(transaction)
print(f"Transaction signed: {signed.document_id}")

# Verify the transaction (simulating recipient)
verification = jacs.verify(signed.raw)

if verification.valid:
    doc = json.loads(signed.raw)
    print(f"Payment verified from: {verification.signer_id}")
    print(f"Amount: {doc['content']['amount']} {doc['content']['currency']}")
else:
    print(f"Verification failed: {', '.join(verification.errors)}")

# Sign a file
contract_signed = jacs.sign_file("./contract.pdf", embed=True)
print(f"Contract signed: {contract_signed.document_id}")

# Update agent metadata
agent_doc = json.loads(jacs.export_agent())
agent_doc["jacsAgentType"] = "ai"
if not agent_doc.get("jacsContacts") or len(agent_doc["jacsContacts"]) == 0:
    agent_doc["jacsContacts"] = [{"contactFirstName": "AI", "contactLastName": "Agent"}]
updated_agent = jacs.update_agent(agent_doc)
print("Agent metadata updated")

# Share public key
public_key = jacs.get_public_key()
print("Share this public key for verification:")
print(public_key)

MCP Integration

The simplified API works well with FastMCP tool implementations:

from fastmcp import FastMCP
import jacs.simple as jacs

mcp = FastMCP("My Server")

# Load agent once at startup
jacs.load("./jacs.config.json")

@mcp.tool()
def approve_request(request_id: str) -> dict:
    """Approve a request with cryptographic signature."""
    signed = jacs.sign_message({
        "action": "approve",
        "request_id": request_id,
        "approved_by": jacs.get_agent_info().agent_id
    })
    return {"signed_approval": signed.raw}

@mcp.tool()
def verify_approval(signed_json: str) -> dict:
    """Verify a signed approval."""
    result = jacs.verify(signed_json)
    return {
        "valid": result.valid,
        "signer": result.signer_id,
        "errors": result.errors
    }

Error Handling

import jacs.simple as jacs
from jacs.types import JacsError, AgentNotLoadedError

try:
    jacs.load("./missing-config.json")
except JacsError as e:
    print(f"Config not found: {e}")

try:
    # Will fail if no agent loaded
    jacs.sign_message({"data": "test"})
except AgentNotLoadedError as e:
    print(f"No agent: {e}")

try:
    jacs.sign_file("/nonexistent/file.pdf")
except JacsError as e:
    print(f"File not found: {e}")

# Verification doesn't throw - check result.valid
result = jacs.verify("invalid json")
if not result.valid:
    print(f"Verification errors: {result.errors}")

See Also

• Basic Usage - JacsAgent class usage
• API Reference - Complete JacsAgent API
• MCP Integration - Model Context Protocol

Basic Usage

This chapter covers fundamental JACS operations in Python. For quick signing and verification, start with the Simplified API (jacs.simple) or JacsClient; the sections below use the JacsAgent class directly for fine-grained control.

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 (Python)

Python exposes two different MCP stories:

1. Secure a local FastMCP transport with jacs.mcp
2. Expose JACS operations as MCP tools with jacs.adapters.mcp

Use the first when you already have an MCP server or client. Use the second when you want the model to call JACS signing, agreement, A2A, or trust helpers as normal MCP tools.

What Is Supported

• Local FastMCP server wrapping with JACSMCPServer
• Local FastMCP client wrapping with JACSMCPClient
• One-line server creation with create_jacs_mcp_server()
• FastMCP tool registration with register_jacs_tools(), register_a2a_tools(), and register_trust_tools()

Important Constraints

• JACSMCPClient, JACSMCPServer, and jacs_call() enforce loopback-only URLs
• Unsigned fallback is disabled by default
• strict=True is about config loading and failure behavior, not an opt-in to security

1. Secure A FastMCP Server

The shortest path is the factory:

from jacs.mcp import create_jacs_mcp_server

mcp = create_jacs_mcp_server("My Server", "./jacs.config.json")

@mcp.tool()
def hello(name: str) -> str:
    return f"Hello, {name}!"

If you already have a FastMCP instance:

from fastmcp import FastMCP
from jacs.mcp import JACSMCPServer

mcp = JACSMCPServer(FastMCP("Secure Server"), "./jacs.config.json")

2. Secure A FastMCP Client

from jacs.mcp import JACSMCPClient

client = JACSMCPClient("http://localhost:8000/sse", "./jacs.config.json")

async with client:
    result = await client.call_tool("hello", {"name": "World"})

To allow unsigned fallback explicitly:

client = JACSMCPClient(
    "http://localhost:8000/sse",
    "./jacs.config.json",
    allow_unsigned_fallback=True,
)

3. Register JACS As MCP Tools

This is the better fit when the model should be able to ask for signatures, agreements, A2A cards, or trust-store operations directly.

from fastmcp import FastMCP
from jacs.client import JacsClient
from jacs.adapters.mcp import (
    register_jacs_tools,
    register_a2a_tools,
    register_trust_tools,
)

client = JacsClient.quickstart(name="mcp-agent", domain="mcp.local")
mcp = FastMCP("JACS Tools")

register_jacs_tools(mcp, client=client)
register_a2a_tools(mcp, client=client)
register_trust_tools(mcp, client=client)

The core tool set includes document signing, verification, agreements, audit, and agent-info helpers. The A2A and trust helpers are opt-in registrations.

Useful Helper APIs

From jacs.mcp:

• jacs_tool to sign a specific tool's response
• jacs_middleware() for explicit Starlette middleware
• jacs_call() for one-off authenticated local MCP calls

Example Paths In This Repo

• jacspy/examples/mcp/server.py
• jacspy/examples/mcp/client.py
• jacspy/examples/mcp_server.py
• jacspy/tests/test_adapters_mcp.py

When To Use Adapters Instead

Choose Python Framework Adapters instead of MCP when:

• the model and tools already live in the same Python process
• you only need signed LangChain, LangGraph, CrewAI, or FastAPI boundaries
• you do not need MCP clients to connect from outside the app

Framework Adapters

Use adapters when the model already runs inside your Python app and you want provenance at the framework boundary, not a separate MCP server.

Choose The Adapter

Install only the extra you need:

pip install jacs[langchain]
pip install jacs[fastapi]
pip install jacs[crewai]
pip install jacs[anthropic]

Optional: jacs[langgraph] (LangGraph ToolNode), jacs[ws] (WebSockets). See pyproject.toml for the full list.

LangChain / LangGraph

This is the smallest JACS path if your model already lives in LangChain.

LangChain middleware

from langchain.agents import create_agent
from jacs.client import JacsClient
from jacs.adapters.langchain import jacs_signing_middleware

client = JacsClient.quickstart(name="langchain-agent", domain="langchain.local")

agent = create_agent(
    model="openai:gpt-4o",
    tools=[search_tool, calc_tool],
    middleware=[jacs_signing_middleware(client=client)],
)

LangGraph ToolNode

from jacs.adapters.langchain import with_jacs_signing

tool_node = with_jacs_signing([search_tool, calc_tool], client=client)

Wrap one tool instead of the whole graph

from jacs.adapters.langchain import signed_tool

signed_search = signed_tool(search_tool, client=client)

The executable example to start from in this repo is jacspy/examples/langchain/signing_callback.py.

FastAPI / Starlette

Use this when the trust boundary is an API route instead of an MCP transport.

from fastapi import FastAPI
from jacs.client import JacsClient
from jacs.adapters.fastapi import JacsMiddleware

client = JacsClient.quickstart(name="api-agent", domain="api.local")
app = FastAPI()
app.add_middleware(JacsMiddleware, client=client)

Useful options:

• strict=True to reject verification failures instead of passing through
• sign_responses=False or verify_requests=False to narrow the behavior
• a2a=True to also expose A2A discovery routes from the same FastAPI app

For auth-style endpoints, replay protection is available:

app.add_middleware(
    JacsMiddleware,
    client=client,
    strict=True,
    auth_replay_protection=True,
    auth_max_age_seconds=30,
    auth_clock_skew_seconds=5,
)

To sign only one route:

from jacs.adapters.fastapi import jacs_route

@app.get("/signed")
@jacs_route(client=client)
async def signed_endpoint():
    return {"ok": True}

CrewAI

CrewAI support is guardrail-first:

from crewai import Task
from jacs.adapters.crewai import jacs_guardrail

task = Task(
    description="Summarize the report",
    agent=my_agent,
    guardrail=jacs_guardrail(client=client),
)

If you build tasks with factories, signed_task() can pre-attach the guardrail.

Anthropic / Claude SDK

Use the Anthropic adapter when you want signed return values from normal Python tool functions:

from jacs.adapters.anthropic import signed_tool

@signed_tool(client=client)
def get_weather(location: str) -> str:
    return f"Weather in {location}: sunny"

When To Use MCP Instead

Choose Python MCP Integration instead of adapters when:

• the model is outside your process and talks over MCP
• you want an MCP tool suite for JACS operations
• you need the same server to be usable by external MCP clients

API Reference

Complete API documentation for the jacs Python package.

For most use cases, the Simplified API (jacs.simple) and JacsClient (instance-based, multiple agents) are recommended. This page documents the lower-level JacsAgent class and module-level functions.

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_artifact(artifact_json, artifact_type, parent_signatures_json=None)

Sign an A2A artifact with JACS provenance. This is the canonical method name.

Parameters:

• artifact_json (str): JSON string of the artifact to sign
• artifact_type (str): Type of artifact (e.g., "task", "message")
• parent_signatures_json (str, optional): JSON string of parent signatures for chain of custody

Returns: str - The signed, wrapped artifact as a JSON string

Example:

signed = agent.sign_artifact(
    json.dumps({"action": "classify", "input": "hello"}),
    "task"
)

agent.wrap_a2a_artifact(artifact_json, artifact_type, parent_signatures_json=None)

Deprecated since 0.9.0. Use sign_artifact() instead. This method will be removed in 1.0.0.

Set JACS_SHOW_DEPRECATIONS=1 to see runtime warnings when deprecated methods are called.

Wraps an A2A artifact with JACS provenance signature. Identical behavior to sign_artifact().

Parameters: Same as sign_artifact().

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, create_jacs_mcp_server, jacs_call

Canonical MCP documentation lives at Python MCP Integration. This API section lists the MCP entry points only:

• JACSMCPServer(mcp_server, config_path="./jacs.config.json", strict=False) - Wrap a FastMCP server with JACS request verification and response signing.
• JACSMCPClient(url, config_path="./jacs.config.json", strict=False, **kwargs) - Create a FastMCP client with JACS signing/verification interceptors.
• create_jacs_mcp_server(name, config_path=None) - One-line server factory.
• jacs_call(server_url, method, **params) - One-shot authenticated MCP call.

For examples, strict-mode behavior, and security guidance, see Python MCP Integration.

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

Go (jacsgo) Installation and Quick Start

jacsgo provides Go bindings for signing and verifying JACS documents in services, APIs, and agent runtimes.

Note: Go bindings are community-maintained. Python and Node.js currently have broader framework adapter coverage. For full MCP surface use the Rust jacs-mcp server; the Go MCP examples in the repo are demo code.

Install

go get github.com/HumanAssisted/JACS/jacsgo

Minimal Sign + Verify

Create an agent first (CLI: jacs create --name my-agent, or programmatically with jacs.Create() and JACS_PRIVATE_KEY_PASSWORD). Then:

package main

import (
	"fmt"
	"log"

	jacs "github.com/HumanAssisted/JACS/jacsgo"
)

func main() {
	// Load agent: nil = default ./jacs.config.json
	if err := jacs.Load(nil); err != nil {
		log.Fatal("create an agent first: jacs create --name my-agent")
	}

	signed, err := jacs.SignMessage(map[string]interface{}{
		"event":  "tool-result",
		"status": "ok",
	})
	if err != nil {
		log.Fatal(err)
	}

	result, err := jacs.Verify(signed.Raw)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Valid: %t signer=%s\n", result.Valid, result.SignerID)
}

Programmatic agent creation

Use jacs.Create(name, &jacs.CreateAgentOptions{...}). Password must be set in options or via JACS_PRIVATE_KEY_PASSWORD. See the jacsgo README for the full API table and options.

Concurrent use

For multiple agents in one process, use NewJacsAgent(), then agent.Load(path) and agent methods; call agent.Close() when done. Attestation, A2A (agent cards, trust policy), and protocol helpers are available on JacsAgent and as package-level wrappers (see godoc or the jacsgo README).

Common Go Use Cases

• Sign outbound API/MCP payloads before crossing trust boundaries
• Verify inbound signed payloads before executing sensitive actions
• Sign files (SignFile) for portable chain-of-custody workflows
• Generate DNS TXT fingerprints (GetDnsRecord) for public identity verification

MCP and HTTP Patterns

The Go repository includes runnable examples for transport-level signing:

• jacsgo/examples/mcp/main.go for MCP-style request/response signing
• jacsgo/examples/http/ for signed HTTP client/server traffic

Identity and Trust Notes

• JACS agent identity is key-based (jacsId + versioned signatures)
• Verification behavior follows the configured key-resolution order in the runtime (for example local and remote resolution modes supported by the underlying JACS core)
• DID interoperability is possible at the integration layer without requiring blockchain infrastructure

See DNS-Based Verification and DID Integration (No Blockchain Required).

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 '@hai.ai/jacs';

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
• Agent State Schema - Signed agent state documents
• Commitment Schema - Shared agreements between agents
• Todo List Schema - Private task tracking with inline items
• Conversation Schema - Message threading and ordering
• 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: